From 45185b350c7e2d0fbf8100dd313573858e09096d Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Tue, 11 Feb 2025 16:06:38 -0700 Subject: [PATCH 1/5] Add step for rewriting image names in backup and restore resources --- docs/vendor/embedded-disaster-recovery.mdx | 35 +++++++++++++++++++++- 1 file changed, 34 insertions(+), 1 deletion(-) diff --git a/docs/vendor/embedded-disaster-recovery.mdx b/docs/vendor/embedded-disaster-recovery.mdx index 6fd0d21955..3858096ce1 100644 --- a/docs/vendor/embedded-disaster-recovery.mdx +++ b/docs/vendor/embedded-disaster-recovery.mdx @@ -95,7 +95,40 @@ To configure Velero Backup and Restore custom resources for Embedded Cluster dis - '*' ``` -1. (Optional) You can use Velero functionality like [backup](https://velero.io/docs/main/backup-hooks/) and [restore](https://velero.io/docs/main/restore-hooks/) hooks to customize the backup and restore process as needed. +1. For any image names that you include in your Backup and Restore resources, rewrite the image name using the Replicated KOTS [HasLocalRegistry](/reference/template-functions-config-context#haslocalregistry), [LocalRegistryHost](/reference/template-functions-config-context#localregistryhost), and [LocalRegistryNamespace](/reference/template-functions-config-context#localregistrynamespace) template functions. This ensures that the image name is rendered correctly during deployment, allowing the image to be pulled from the user's local image registry (such as in air gap installations) or through the Replicated proxy service. If an image name is not templated, then the image is not automatically rewritten by KOTS and cannot be pulled, causing the application to fail to deploy after a restore. + + **Example:** + + ```yaml + apiVersion: velero.io/v1 + kind: Restore + metadata: + name: restore + spec: + hooks: + resources: + - name: restore-hook-1 + includedNamespaces: + - kotsadm + labelSelector: + matchLabels: + app: example + postHooks: + - init: + initContainers: + - name: restore-hook-init1 + image: + # Use HasLocalRegistry, LocalRegistryHost, and LocalRegistryNamespace + # to template the image name + registry: '{{repl HasLocalRegistry | ternary LocalRegistryHost "proxy.replicated.com" }}' + repository: '{{repl HasLocalRegistry | ternary LocalRegistryNamespace "proxy/my-app/quay.io/my-org" }}/nginx' + tag: 1.24-alpine + ``` + :::note + For more information about and additional examples of how to rewrite image names using the KOTS [HasLocalRegistry](/reference/template-functions-config-context#haslocalregistry), [LocalRegistryHost](/reference/template-functions-config-context#localregistryhost), and [LocalRegistryNamespace](/reference/template-functions-config-context#localregistrynamespace) template functions, see [Task 1: Rewrite Image Names](helm-native-v2-using#rewrite-image-names) in _Configuring the HelmChart v2 Custom Resource_. + ::: + +1. (Optional) Use Velero functionality like [backup](https://velero.io/docs/main/backup-hooks/) and [restore](https://velero.io/docs/main/restore-hooks/) hooks to customize the backup and restore process as needed. **Example**: From 36cf59b39f62d6377b84840ac81fc8b732b6ad9b Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Tue, 11 Feb 2025 16:11:52 -0700 Subject: [PATCH 2/5] copyedit --- docs/vendor/embedded-disaster-recovery.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/vendor/embedded-disaster-recovery.mdx b/docs/vendor/embedded-disaster-recovery.mdx index 3858096ce1..4a6d221011 100644 --- a/docs/vendor/embedded-disaster-recovery.mdx +++ b/docs/vendor/embedded-disaster-recovery.mdx @@ -95,7 +95,7 @@ To configure Velero Backup and Restore custom resources for Embedded Cluster dis - '*' ``` -1. For any image names that you include in your Backup and Restore resources, rewrite the image name using the Replicated KOTS [HasLocalRegistry](/reference/template-functions-config-context#haslocalregistry), [LocalRegistryHost](/reference/template-functions-config-context#localregistryhost), and [LocalRegistryNamespace](/reference/template-functions-config-context#localregistrynamespace) template functions. This ensures that the image name is rendered correctly during deployment, allowing the image to be pulled from the user's local image registry (such as in air gap installations) or through the Replicated proxy service. If an image name is not templated, then the image is not automatically rewritten by KOTS and cannot be pulled, causing the application to fail to deploy after a restore. +1. For any image names that you include in your Backup and Restore resources, rewrite the image name using the Replicated KOTS [HasLocalRegistry](/reference/template-functions-config-context#haslocalregistry), [LocalRegistryHost](/reference/template-functions-config-context#localregistryhost), and [LocalRegistryNamespace](/reference/template-functions-config-context#localregistrynamespace) template functions. This ensures that the image name is rendered correctly during deployment, allowing the image to be pulled from the user's local image registry (such as in air gap installations) or through the Replicated proxy registry. If any images referenced in Backup and Restore resources cannot be pulled, the application will fail to deploy after a restore. **Example:** From c9ad7156d612ea0097da7f4805363baa6073eaf9 Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Tue, 11 Feb 2025 16:14:11 -0700 Subject: [PATCH 3/5] copyedit --- docs/vendor/embedded-disaster-recovery.mdx | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/vendor/embedded-disaster-recovery.mdx b/docs/vendor/embedded-disaster-recovery.mdx index 4a6d221011..1bee22c7f5 100644 --- a/docs/vendor/embedded-disaster-recovery.mdx +++ b/docs/vendor/embedded-disaster-recovery.mdx @@ -124,9 +124,7 @@ To configure Velero Backup and Restore custom resources for Embedded Cluster dis repository: '{{repl HasLocalRegistry | ternary LocalRegistryNamespace "proxy/my-app/quay.io/my-org" }}/nginx' tag: 1.24-alpine ``` - :::note - For more information about and additional examples of how to rewrite image names using the KOTS [HasLocalRegistry](/reference/template-functions-config-context#haslocalregistry), [LocalRegistryHost](/reference/template-functions-config-context#localregistryhost), and [LocalRegistryNamespace](/reference/template-functions-config-context#localregistrynamespace) template functions, see [Task 1: Rewrite Image Names](helm-native-v2-using#rewrite-image-names) in _Configuring the HelmChart v2 Custom Resource_. - ::: + For more information about how to rewrite image names using the KOTS [HasLocalRegistry](/reference/template-functions-config-context#haslocalregistry), [LocalRegistryHost](/reference/template-functions-config-context#localregistryhost), and [LocalRegistryNamespace](/reference/template-functions-config-context#localregistrynamespace) template functions, including additional examples, see [Task 1: Rewrite Image Names](helm-native-v2-using#rewrite-image-names) in _Configuring the HelmChart v2 Custom Resource_. 1. (Optional) Use Velero functionality like [backup](https://velero.io/docs/main/backup-hooks/) and [restore](https://velero.io/docs/main/restore-hooks/) hooks to customize the backup and restore process as needed. From 302149de5a974ffcdbe1f9785cb41507c2dbdcc7 Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Wed, 12 Feb 2025 08:18:42 -0700 Subject: [PATCH 4/5] rm sentence about deploy failure --- docs/vendor/embedded-disaster-recovery.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/vendor/embedded-disaster-recovery.mdx b/docs/vendor/embedded-disaster-recovery.mdx index 1bee22c7f5..c78cf55ac6 100644 --- a/docs/vendor/embedded-disaster-recovery.mdx +++ b/docs/vendor/embedded-disaster-recovery.mdx @@ -95,7 +95,7 @@ To configure Velero Backup and Restore custom resources for Embedded Cluster dis - '*' ``` -1. For any image names that you include in your Backup and Restore resources, rewrite the image name using the Replicated KOTS [HasLocalRegistry](/reference/template-functions-config-context#haslocalregistry), [LocalRegistryHost](/reference/template-functions-config-context#localregistryhost), and [LocalRegistryNamespace](/reference/template-functions-config-context#localregistrynamespace) template functions. This ensures that the image name is rendered correctly during deployment, allowing the image to be pulled from the user's local image registry (such as in air gap installations) or through the Replicated proxy registry. If any images referenced in Backup and Restore resources cannot be pulled, the application will fail to deploy after a restore. +1. For any image names that you include in your Backup and Restore resources, rewrite the image name using the Replicated KOTS [HasLocalRegistry](/reference/template-functions-config-context#haslocalregistry), [LocalRegistryHost](/reference/template-functions-config-context#localregistryhost), and [LocalRegistryNamespace](/reference/template-functions-config-context#localregistrynamespace) template functions. This ensures that the image name is rendered correctly during deployment, allowing the image to be pulled from the user's local image registry (such as in air gap installations) or through the Replicated proxy registry. **Example:** From 53e00f691efd2ecf3d5e29928a6f83616ee438d9 Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Wed, 12 Feb 2025 08:32:10 -0700 Subject: [PATCH 5/5] add additionalImages step --- docs/vendor/embedded-disaster-recovery.mdx | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-) diff --git a/docs/vendor/embedded-disaster-recovery.mdx b/docs/vendor/embedded-disaster-recovery.mdx index c78cf55ac6..784add1a1e 100644 --- a/docs/vendor/embedded-disaster-recovery.mdx +++ b/docs/vendor/embedded-disaster-recovery.mdx @@ -126,9 +126,24 @@ To configure Velero Backup and Restore custom resources for Embedded Cluster dis ``` For more information about how to rewrite image names using the KOTS [HasLocalRegistry](/reference/template-functions-config-context#haslocalregistry), [LocalRegistryHost](/reference/template-functions-config-context#localregistryhost), and [LocalRegistryNamespace](/reference/template-functions-config-context#localregistrynamespace) template functions, including additional examples, see [Task 1: Rewrite Image Names](helm-native-v2-using#rewrite-image-names) in _Configuring the HelmChart v2 Custom Resource_. +1. If you support air gap installations, add any images that are referenced in your Backup and Restore resources to the `additionalImages` field of the KOTS Application custom resource. This ensures that the images are included in the air gap bundle for the release so they can be used during the backup and restore process in environments with limited or no outbound internet access. For more information, see [additionalImages](/reference/custom-resource-application#additionalimages) in _Application_. + + **Example:** + + ```yaml + apiVersion: kots.io/v1beta1 + kind: Application + metadata: + name: my-app + spec: + additionalImages: + - elasticsearch:7.6.0 + - quay.io/orgname/private-image:v1.2.3 + ``` + 1. (Optional) Use Velero functionality like [backup](https://velero.io/docs/main/backup-hooks/) and [restore](https://velero.io/docs/main/restore-hooks/) hooks to customize the backup and restore process as needed. - **Example**: + **Example:** For example, a Postgres database might be backed up using pg_dump to extract the database into a file as part of a backup hook. It can then be restored using the file in a restore hook: