From 46caf62061a6cf158bc33f2e54992f5304b619a0 Mon Sep 17 00:00:00 2001 From: Austin Abro Date: Mon, 11 Aug 2025 10:28:55 -0400 Subject: [PATCH 1/7] data injections migration Signed-off-by: Austin Abro --- .../data-injections-migration.mdx | 117 ++++++++++++++++++ 1 file changed, 117 insertions(+) create mode 100644 site/src/content/docs/best-practices/data-injections-migration.mdx diff --git a/site/src/content/docs/best-practices/data-injections-migration.mdx b/site/src/content/docs/best-practices/data-injections-migration.mdx new file mode 100644 index 0000000000..62e2acc6d3 --- /dev/null +++ b/site/src/content/docs/best-practices/data-injections-migration.mdx @@ -0,0 +1,117 @@ +--- +title: "Migrate off of Data injections" +--- + +This guide explains how to migrate your Zarf deployment from the data injections feature to OCI image-based data delivery methods. Data injections is planned to be deprecated the current Zarf schema version and fully removed by Zarf v1.0.0. There are for several reasons behind this: + +- **Poor User Experience**: Many users have struggled to figure out how to adopt data injections. +- **Host dependency**: Data injections shell out to `tar`, relying on host binaries that may not be available or differ across environments +- **Better alternatives**: OCI images provide a Kubernetes native solution for data delivery, and neatly fit into the Zarf delivery paradigm. + +## Migration guide + +### Step 1: Package Your Data in a Container Image + +First, create a container image containing your data: + +```dockerfile +FROM alpine:3.18 +COPY your-data-file /your-data/your-data-file +``` + +Build and push this image: +```bash +docker build -t your-registry/your-data:tag . +docker push your-registry/your-data:tag +``` + +Some registries will not accept images over a certain size. In this case, you can load the image from the Docker Daemon. This can be slow, users are recommended to try out [this strategy for improving the speed of image loads](https://docs.zarf.dev/faq#how-can-i-improve-the-speed-of-loading-large-images-from-docker-on-zarf-package-create). Additionally, before Data Injections is removed Zarf allow users to load images directly from a tar file, ([#2181](https://github.com/zarf-dev/zarf/issues/)), this will be significantly faster than Docker daemon pulls. + +### Step 2: Update zarf.yaml + +**Before (Data Injections):** +```yaml +kind: ZarfPackageConfig +metadata: + name: my-data-app + +components: + - name: my-app + required: true + images: + - ghcr.io/my-app:1.0.0 + - alpine:3.18 + dataInjections: + - source: zim-data + target: + namespace: my-app + selector: app=my-app + container: data-loader + path: /data + compress: true +``` + +**After (Init Container Strategy):** +```yaml +kind: ZarfPackageConfig +metadata: + name: init-data-loading + +components: + - name: kiwix-serve-init + required: true + images: + - ghcr.io/my-app:1.0.0 + - your-registry/your-data:tag # Your container with your data file +``` + +**Key Changes:** +- Remove `dataInjections` section entirely. +- Replace the image used during data injections with your data image. + +### Step 3: Update Deployment Manifest + +**Before (Data Injections):** +```yaml +spec: + template: + spec: + initContainers: + - name: data-loader + image: alpine:3.18 + command: ["sh", "-c"] + args: + - 'while [ ! -f /data/###ZARF_DATA_INJECTION_MARKER### ]; do echo "waiting for zarf data sync" && sleep 1; done; echo "we are done waiting!"' + volumeMounts: + - mountPath: /data + name: data +``` + +**After (Init Container Strategy):** +```yaml +spec: + template: + spec: + initContainers: + - name: data-puller + image: your-registry/your-data:tag + command: ["sh", "-c"] + args: + - | + cp /your-data/your-data-file /data/my-app-data-location + ls -la /data + echo "Data initialization complete" + volumeMounts: + - mountPath: /data + name: data +``` + +**Key Changes:** +- Replace data injection marker waiting logic with direct data copying. +- Use your data container image. + +Your app should be ready to deploy. If there are any reasons that this method does not work for you, please comment in issue [#3926](https://github.com/zarf-dev/zarf/issues/3926) + +## Future Alternatives + +Once the feature is stable, we will recommend the new OCI volume source feature. This feature, in beta as of 1.33, will provide a simpler way to mount data from an image into a pod. Read more about OCI volume sources in the enhancement proposal [4639-oci-volume-source](https://github.com/kubernetes/enhancements/tree/master/keps/sig-node/4639-oci-volume-source). From c7869ba6baa66656a5659fef10708f10205832bf Mon Sep 17 00:00:00 2001 From: Austin Abro Date: Mon, 11 Aug 2025 10:40:33 -0400 Subject: [PATCH 2/7] oci image Signed-off-by: Austin Abro --- .../content/docs/best-practices/data-injections-migration.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/site/src/content/docs/best-practices/data-injections-migration.mdx b/site/src/content/docs/best-practices/data-injections-migration.mdx index 62e2acc6d3..3fc4b767db 100644 --- a/site/src/content/docs/best-practices/data-injections-migration.mdx +++ b/site/src/content/docs/best-practices/data-injections-migration.mdx @@ -10,7 +10,7 @@ This guide explains how to migrate your Zarf deployment from the data injections ## Migration guide -### Step 1: Package Your Data in a Container Image +### Step 1: Package Your Data in an OCI Image First, create a container image containing your data: From f4615d516067dec4eaaec4302607fb98210383a0 Mon Sep 17 00:00:00 2001 From: Austin Abro Date: Mon, 11 Aug 2025 11:27:00 -0400 Subject: [PATCH 3/7] host dependency Signed-off-by: Austin Abro --- .../content/docs/best-practices/data-injections-migration.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/site/src/content/docs/best-practices/data-injections-migration.mdx b/site/src/content/docs/best-practices/data-injections-migration.mdx index 3fc4b767db..0e1c71399c 100644 --- a/site/src/content/docs/best-practices/data-injections-migration.mdx +++ b/site/src/content/docs/best-practices/data-injections-migration.mdx @@ -5,7 +5,7 @@ title: "Migrate off of Data injections" This guide explains how to migrate your Zarf deployment from the data injections feature to OCI image-based data delivery methods. Data injections is planned to be deprecated the current Zarf schema version and fully removed by Zarf v1.0.0. There are for several reasons behind this: - **Poor User Experience**: Many users have struggled to figure out how to adopt data injections. -- **Host dependency**: Data injections shell out to `tar`, relying on host binaries that may not be available or differ across environments +- **Host dependency**: Data injections shells out to `tar`. This makes testing difficult and introduces differences across environments. - **Better alternatives**: OCI images provide a Kubernetes native solution for data delivery, and neatly fit into the Zarf delivery paradigm. ## Migration guide From b24d570dd9ba85c9f282d7f6ad45960147a28b42 Mon Sep 17 00:00:00 2001 From: Austin Abro Date: Mon, 11 Aug 2025 11:28:05 -0400 Subject: [PATCH 4/7] folder Signed-off-by: Austin Abro --- .../content/docs/best-practices/data-injections-migration.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/site/src/content/docs/best-practices/data-injections-migration.mdx b/site/src/content/docs/best-practices/data-injections-migration.mdx index 0e1c71399c..bca4e539b9 100644 --- a/site/src/content/docs/best-practices/data-injections-migration.mdx +++ b/site/src/content/docs/best-practices/data-injections-migration.mdx @@ -25,7 +25,7 @@ docker build -t your-registry/your-data:tag . docker push your-registry/your-data:tag ``` -Some registries will not accept images over a certain size. In this case, you can load the image from the Docker Daemon. This can be slow, users are recommended to try out [this strategy for improving the speed of image loads](https://docs.zarf.dev/faq#how-can-i-improve-the-speed-of-loading-large-images-from-docker-on-zarf-package-create). Additionally, before Data Injections is removed Zarf allow users to load images directly from a tar file, ([#2181](https://github.com/zarf-dev/zarf/issues/)), this will be significantly faster than Docker daemon pulls. +Some registries will not accept images over a certain size. In this case, you can load the image from the Docker Daemon. This can be slow, users are recommended to try out [this strategy for improving the speed of image loads](https://docs.zarf.dev/faq#how-can-i-improve-the-speed-of-loading-large-images-from-docker-on-zarf-package-create). Additionally, before Data Injections is removed Zarf will allow users to load images directly from a tar file, ([#2181](https://github.com/zarf-dev/zarf/issues/)), this will be significantly faster than Docker daemon pulls. ### Step 2: Update zarf.yaml @@ -42,7 +42,7 @@ components: - ghcr.io/my-app:1.0.0 - alpine:3.18 dataInjections: - - source: zim-data + - source: my-folder target: namespace: my-app selector: app=my-app From 66d49a107f4dd807104f37eef8b5616863eeac8e Mon Sep 17 00:00:00 2001 From: Austin Abro Date: Mon, 11 Aug 2025 11:30:19 -0400 Subject: [PATCH 5/7] data injections Signed-off-by: Austin Abro --- .../content/docs/best-practices/data-injections-migration.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/site/src/content/docs/best-practices/data-injections-migration.mdx b/site/src/content/docs/best-practices/data-injections-migration.mdx index bca4e539b9..b82f2c5bb0 100644 --- a/site/src/content/docs/best-practices/data-injections-migration.mdx +++ b/site/src/content/docs/best-practices/data-injections-migration.mdx @@ -114,4 +114,4 @@ Your app should be ready to deploy. If there are any reasons that this method do ## Future Alternatives -Once the feature is stable, we will recommend the new OCI volume source feature. This feature, in beta as of 1.33, will provide a simpler way to mount data from an image into a pod. Read more about OCI volume sources in the enhancement proposal [4639-oci-volume-source](https://github.com/kubernetes/enhancements/tree/master/keps/sig-node/4639-oci-volume-source). +Once the new Kubernetes feature [OCI volume sources](https://github.com/kubernetes/enhancements/tree/master/keps/sig-node/4639-oci-volume-source) is considered stable, this document will recommend that users switch to that method. OCI volumes sources, in beta as of Kubernetes 1.33, will provide a simpler way to mount data from an image into a pod. From 46cfd8dcc07459689423a7b928fa3816c0f0d7d6 Mon Sep 17 00:00:00 2001 From: Austin Abro Date: Mon, 11 Aug 2025 11:39:25 -0400 Subject: [PATCH 6/7] alternative Signed-off-by: Austin Abro --- .../content/docs/best-practices/data-injections-migration.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/site/src/content/docs/best-practices/data-injections-migration.mdx b/site/src/content/docs/best-practices/data-injections-migration.mdx index b82f2c5bb0..7273aa5ed3 100644 --- a/site/src/content/docs/best-practices/data-injections-migration.mdx +++ b/site/src/content/docs/best-practices/data-injections-migration.mdx @@ -114,4 +114,4 @@ Your app should be ready to deploy. If there are any reasons that this method do ## Future Alternatives -Once the new Kubernetes feature [OCI volume sources](https://github.com/kubernetes/enhancements/tree/master/keps/sig-node/4639-oci-volume-source) is considered stable, this document will recommend that users switch to that method. OCI volumes sources, in beta as of Kubernetes 1.33, will provide a simpler way to mount data from an image into a pod. +Once the new Kubernetes feature [OCI volume sources](https://github.com/kubernetes/enhancements/tree/master/keps/sig-node/4639-oci-volume-source) is considered stable, this document will recommend that method. OCI volumes sources, in beta as of Kubernetes 1.33, provide a simpler way to mount data from an image into a pod. From 8c2959e3c374f3d0fd74d76a084ed439c73af0bf Mon Sep 17 00:00:00 2001 From: Austin Abro Date: Mon, 11 Aug 2025 12:16:35 -0400 Subject: [PATCH 7/7] my-app Signed-off-by: Austin Abro --- .../content/docs/best-practices/data-injections-migration.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/site/src/content/docs/best-practices/data-injections-migration.mdx b/site/src/content/docs/best-practices/data-injections-migration.mdx index 7273aa5ed3..dc44ed9e73 100644 --- a/site/src/content/docs/best-practices/data-injections-migration.mdx +++ b/site/src/content/docs/best-practices/data-injections-migration.mdx @@ -58,7 +58,7 @@ metadata: name: init-data-loading components: - - name: kiwix-serve-init + - name: my-app required: true images: - ghcr.io/my-app:1.0.0