diff --git a/docs-website/static/docs/walkthroughs/publish_and_deploy_create.html b/docs-website/static/docs/walkthroughs/publish_and_deploy_create.html new file mode 100644 index 0000000000..9b1f035c16 --- /dev/null +++ b/docs-website/static/docs/walkthroughs/publish_and_deploy_create.html @@ -0,0 +1,102 @@ + + + + + + +
+$ zarf package create .
+Saving log file to
+/var/folders/bk/rz1xx2sd5zn134c0_j1s2n5r0000gp/T/zarf-2023-03-30-11-01-47-3104819928.log
+
+Using build directory .
+
+kind: ZarfPackageConfig
+metadata:
+  name: helm-oci-chart
+  description: Deploy podinfo using a Helm OCI chart
+  version: 0.0.1
+components:
+- name: helm-oci-chart
+  required: true
+  charts:
+  - name: podinfo
+    url: oci://ghcr.io/stefanprodan/charts/podinfo
+    version: 6.3.3
+    namespace: helm-oci-demo
+  images:
+  - ghcr.io/stefanprodan/podinfo:6.3.3
+
+? Create this Zarf package? (y/N) Yes
+
+Specify a maximum file size for this package in Megabytes. Above this size, the package will be
+split into multiple files. 0 will disable this feature.
+? Please provide a value for "Maximum Package Size" (0) 0
+
+

+                                                                                
+  📦 HELM-OCI-CHART COMPONENT                                                   
+                                                                                
+                                                                                
+

+  •  Processing helm chart podinfo:6.3.3 from repo oci://ghcr.io/stefanprodan/charts/podinfo
+  •  Processing helm chart podinfo:6.3.3 from repo oci://ghcr.io/stefanprodan/charts/podinfo
+  
+

+                                                                                
+  📦 COMPONENT IMAGES                                                           
+                                                                                
+                                                                                
+

+
+  •  Loading metadata for 1 images.
+  •  Loading metadata for 1 images.
+  •  Pulling Zarf package data (0.00 Byte of 26.10 MBs)
+  ✔  Pulling 1 images (26.10 MBs)
+  •  Creating SBOMs for 1 images and 0 components with files.
+  •  Creating SBOMs for 1 images and 0 components with files.
+
+ + diff --git a/docs-website/static/docs/walkthroughs/publish_and_deploy_deploy.html b/docs-website/static/docs/walkthroughs/publish_and_deploy_deploy.html new file mode 100644 index 0000000000..153246c422 --- /dev/null +++ b/docs-website/static/docs/walkthroughs/publish_and_deploy_deploy.html @@ -0,0 +1,128 @@ + + + + + + +
+$ zarf package deploy oci://$REPOSITORY_URL/helm-oci-chart:0.0.1-arm64
+
+Saving log file to
+/var/folders/bk/rz1xx2sd5zn134c0_j1s2n5r0000gp/T/zarf-2023-03-30-12-09-38-2083571763.log
+  •  Pulling Zarf package from $REPOSITORY_URL/helm-oci-chart:0.0.1-arm64
+  •  Pulling Zarf package data (0.00 Byte of 26.90 MBs)
+  ✔  d8399f7b56ca [application/vnd.unknown.config.v1+json]
+  ✔  fd143c92d486 zarf.yaml
+  ✔  515aceaacb8d images/index.json
+  ✔  b66dbb27a733 images/oci-layout
+  ✔  42c097bd02de components/helm-oci-chart.tar
+  ✔  46564f0eff85 images/blobs/sha256/46564f0...06008f762391a7bb7d58f339ee
+  ✔  4f4fb700ef54 images/blobs/sha256/4f4fb70...b5577484a6d75e68dc38e8acc1
+  ✔  932a2288fd3a sboms.tar
+  ✔  74eae207aa23 images/blobs/sha256/74eae20...fcb007d3da7b842313f80d2c33
+  ✔  a9eaa45ef418 images/blobs/sha256/a9eaa45...6789c52a87ba5a9e6483f2b74f
+  ✔  ab67ffd6e92e images/blobs/sha256/ab67ffd...f8c9d93c0e719f6350e99d3aea
+  ✔  6ff8f4799d50 images/blobs/sha256/6ff8f47...4bc00ec8b988d28cef78ea9a5b
+  ✔  e2b45cdcd8bf images/blobs/sha256/e2b45cd...000f1bc1695014e38821dc675c
+  ✔  b95c82728c36 images/blobs/sha256/b95c827...042a9c5d84426c1674044916d4
+  ✔  8c5b695f4724 images/blobs/sha256/8c5b695...014f94c8d4ea62772c477c1e03
+  ✔  cf79ae90993d [application/vnd.oci.image.manifest.v1+json]
+  ✔  Pulling Zarf package data (26.90 MBs)
+  ✔  Pulled $REPOSITORY_URL/helm-oci-chart:0.0.1-arm64
+  •  Loading Zarf Package /var/folders/bk/rz1xx2sd5zn134c0_j1s2n5r0000gp/T/zarf-3635611772
+  •  Loading Zarf Package /var/folders/bk/rz1xx2sd5zn134c0_j1s2n5r0000gp/T/zarf-3635611772
+
+kind: ZarfPackageConfig
+metadata:
+  name: helm-oci-chart
+  description: Deploy podinfo using a Helm OCI chart
+  version: 0.0.1
+  architecture: arm64
+build:
+  terminal: JvBUnicornMBP5
+  user: jason
+  architecture: arm64
+  timestamp: Thu, 30 Mar 2023 11:04:19 -0400
+  version: v0.25.0
+  migrations:
+  - scripts-to-actions
+components:
+- name: helm-oci-chart
+  required: true
+  charts:
+  - name: podinfo
+    url: oci://ghcr.io/stefanprodan/charts/podinfo
+    version: 6.3.3
+    namespace: helm-oci-demo
+  images:
+  - ghcr.io/stefanprodan/podinfo:6.3.3
+This package has 1 artifacts with software bill-of-materials (SBOM) included. You can view them now
+in the zarf-sbom folder in this directory or to go directly to one, open this in your browser:
+/Users/jason/src/github.com/jasonvanbrackel/zarf/docs-website/static/docs/walkthroughs/zarf-sbom/sbom-viewer-ghcr.io_stefanprodan_podinfo_6.3.3.html
+
+* This directory will be removed after package deployment.
+
+?Deploy this Zarf package? (y/N) Yes
+
+

+                                                                                
+  📦 HELM-OCI-CHART COMPONENT                                                   
+                                                                                
+                                                                                
+

+
+  •  Loading the Zarf State from the Kubernetes cluster
+  •  Loading the Zarf State from the Kubernetes cluster
+  •  Opening tunnel 55523 -> 5000 for svc/zarf-docker-registry in namespace zarf
+  •  Creating port forwarding tunnel at http://127.0.0.1:55523/v2/_catalog
+  •  Storing images in the zarf registry
+  •  Storing images in the zarf registry
+  •  Processing helm chart podinfo:6.3.3 from oci://ghcr.io/stefanprodan/charts/podinfo
+  •  Processing helm chart podinfo:6.3.3 from oci://ghcr.io/stefanprodan/charts/podinfo
+  ✔  Zarf deployment complete
+
+
+ + diff --git a/docs-website/static/docs/walkthroughs/publish_and_deploy_docker_config.html b/docs-website/static/docs/walkthroughs/publish_and_deploy_docker_config.html new file mode 100644 index 0000000000..f4d9134874 --- /dev/null +++ b/docs-website/static/docs/walkthroughs/publish_and_deploy_docker_config.html @@ -0,0 +1,64 @@ + + + + + + +
+	$ mkdir -p ~/.docker
+	$ AUTH=$(echo -n "$REGISTRY_USERNAME:$REGISTRY_SECRET" | base64)
+	# Note: If using Docker Hub, the registry URL is `https://index.docker.io/v1/` for the auth config
+	$ cat < ~/.docker/config.json
+	{
+	  "auths": {
+		  "$REGISTRY": {
+		    "auth": "$AUTH"
+		  }
+	  }
+	}
+	EOF
+
+ + diff --git a/docs-website/static/docs/walkthroughs/publish_and_deploy_inspect.html b/docs-website/static/docs/walkthroughs/publish_and_deploy_inspect.html new file mode 100644 index 0000000000..7e80c7a128 --- /dev/null +++ b/docs-website/static/docs/walkthroughs/publish_and_deploy_inspect.html @@ -0,0 +1,83 @@ + + + + + + +
+$ zarf package inspect oci://$REPOSITORY_URL/helm-oci-chart:0.0.1-arm64
+
+Saving log file to
+/var/folders/bk/rz1xx2sd5zn134c0_j1s2n5r0000gp/T/zarf-2023-03-30-13-13-29-2403571657.log
+  •  Loading Zarf Package oci://$REPOSITORY_URL/helm-oci-chart:0.0.1-arm64
+  •  Loaded Zarf Package oci://$REPOSITORY_URL/helm-oci-chart:0.0.1-arm64
+
+
+kind: ZarfPackageConfig
+metadata:
+  name: helm-oci-chart
+  description: Deploy podinfo using a Helm OCI chart
+  version: 0.0.1
+  architecture: arm64
+build:
+  terminal: JvBUnicornMBP5
+  user: jason
+  architecture: arm64
+  timestamp: Thu, 30 Mar 2023 11:04:19 -0400
+  version: v0.25.0
+  migrations:
+  - scripts-to-actions
+components:
+- name: helm-oci-chart
+  required: true
+  charts:
+  - name: podinfo
+    url: oci://ghcr.io/stefanprodan/charts/podinfo
+    version: 6.3.3
+    namespace: helm-oci-demo
+  images:
+  - ghcr.io/stefanprodan/podinfo:6.3.3
+ + diff --git a/docs-website/static/docs/walkthroughs/publish_and_deploy_list.html b/docs-website/static/docs/walkthroughs/publish_and_deploy_list.html new file mode 100644 index 0000000000..1daf39e8a7 --- /dev/null +++ b/docs-website/static/docs/walkthroughs/publish_and_deploy_list.html @@ -0,0 +1,61 @@ + + + + + + +
+$ zarf package list
+
+Saving log file to
+/var/folders/bk/rz1xx2sd5zn134c0_j1s2n5r0000gp/T/zarf-2023-03-30-12-10-01-2517631162.log
+Package       | Components
+init           | [zarf-injector zarf-seed-registry zarf-registry zarf-agent]
+dos-games      | [baseline]
+helm-oci-chart | [helm-oci-chart]
+
+
+ + diff --git a/docs-website/static/docs/walkthroughs/publish_and_deploy_login.html b/docs-website/static/docs/walkthroughs/publish_and_deploy_login.html new file mode 100644 index 0000000000..f0c088578c --- /dev/null +++ b/docs-website/static/docs/walkthroughs/publish_and_deploy_login.html @@ -0,0 +1,55 @@ + + + + + + +
+$ echo $REGISTRY_SECRET | zarf tools registry login $REGISTRY --username $REGISTRY_USERNAME --password-stdin
+
+2023/03/07 23:03:16 logged in via /home/zarf/.docker/config.json
+
+ + diff --git a/docs-website/static/docs/walkthroughs/publish_and_deploy_manifest.html b/docs-website/static/docs/walkthroughs/publish_and_deploy_manifest.html new file mode 100644 index 0000000000..aad375aa7a --- /dev/null +++ b/docs-website/static/docs/walkthroughs/publish_and_deploy_manifest.html @@ -0,0 +1,76 @@ + + + + + + +
+# Make a new directory to work in
+$ mkdir -p zarf-publish-walkthrough && cd zarf-publish-walkthrough
+
+# For this walkthrough we will use the  example package
+# located here: https://github.com/defenseunicorns/zarf/blob/main/examples/helm-oci-chart/zarf.yaml
+$ cat <<EOF > zarf.yaml
+kind: ZarfPackageConfig
+metadata:
+  name: helm-oci-chart
+  description: Deploy podinfo using a Helm OCI chart
+  # Note: In order to publish, the package must have a version
+  version: 0.0.1
+
+components:
+  - name: helm-oci-chart
+    required: true
+    charts:
+      - name: podinfo
+        version: 6.3.3
+        namespace: helm-oci-demo
+        url: oci://ghcr.io/stefanprodan/charts/podinfo
+    images:
+      - ghcr.io/stefanprodan/podinfo:6.3.3
+EOF
+
+ + diff --git a/docs-website/static/docs/walkthroughs/publish_and_deploy_publish.html b/docs-website/static/docs/walkthroughs/publish_and_deploy_publish.html new file mode 100644 index 0000000000..b2dc87096f --- /dev/null +++ b/docs-website/static/docs/walkthroughs/publish_and_deploy_publish.html @@ -0,0 +1,107 @@ + + + + + + +
+$ zarf package publish zarf-package-helm-oci-chart-arm64-0.0.1.tar.zst oci://$REPOSITORY_URL
+
+Saving log file to
+/var/folders/bk/rz1xx2sd5zn134c0_j1s2n5r0000gp/T/zarf-2023-03-30-11-24-50-121854673.log
+  •  Loading Zarf Package zarf-package-helm-oci-chart-arm64-0.0.1.tar.zst
+  •  Loading Zarf Package zarf-package-helm-oci-chart-arm64-0.0.1.tar.zst
+
+

+                                                                                
+  📦 PACKAGE PUBLISH helm-oci-chart:0.0.1-arm64                                 
+                                                                                
+                                                                                
+

+
+  •  Publishing package to $REPOSITORY_URL/helm-oci-chart:0.0.1-arm64
+  •  
+  •  Prepared 14 layers
+  •  Publishing jvb/helm-oci-chart:0.0.1-arm64
+  ✔  b66dbb27a733 images/oci-layout
+  ✔  515aceaacb8d images/index.json
+  ✔  fd143c92d486 zarf.yaml
+  ✔  932a2288fd3a sboms.tar
+  ✔  46564f0eff85 images/blobs/sha256/46564f0...06008f762391a7bb7d58f339ee
+  ✔  4f4fb700ef54 images/blobs/sha256/4f4fb70...b5577484a6d75e68dc38e8acc1
+  ✔  6ff8f4799d50 images/blobs/sha256/6ff8f47...4bc00ec8b988d28cef78ea9a5b
+  ✔  8c5b695f4724 images/blobs/sha256/8c5b695...014f94c8d4ea62772c477c1e03
+  ✔  74eae207aa23 images/blobs/sha256/74eae20...fcb007d3da7b842313f80d2c33
+  ✔  a9eaa45ef418 images/blobs/sha256/a9eaa45...6789c52a87ba5a9e6483f2b74f
+  ✔  ab67ffd6e92e images/blobs/sha256/ab67ffd...f8c9d93c0e719f6350e99d3aea
+  ✔  b95c82728c36 images/blobs/sha256/b95c827...042a9c5d84426c1674044916d4
+  ✔  e2b45cdcd8bf images/blobs/sha256/e2b45cd...000f1bc1695014e38821dc675c
+  ✔  42c097bd02de components/helm-oci-chart.tar
+  •  Publishing jvb/helm-oci-chart:0.0.1-arm64
+  ✔  d8399f7b56ca [application/vnd.unknown.config.v1+json]
+  ✔  515aceaacb8d images/index.json
+  ✔  b66dbb27a733 images/oci-layout
+  ✔  932a2288fd3a sboms.tar
+  ✔  fd143c92d486 zarf.yaml
+  ✔  46564f0eff85 images/blobs/sha256/46564f0...06008f762391a7bb7d58f339ee
+  ✔  4f4fb700ef54 images/blobs/sha256/4f4fb70...b5577484a6d75e68dc38e8acc1
+  ✔  42c097bd02de components/helm-oci-chart.tar
+  ✔  6ff8f4799d50 images/blobs/sha256/6ff8f47...4bc00ec8b988d28cef78ea9a5b
+  ✔  74eae207aa23 images/blobs/sha256/74eae20...fcb007d3da7b842313f80d2c33
+  ✔  a9eaa45ef418 images/blobs/sha256/a9eaa45...6789c52a87ba5a9e6483f2b74f
+  ✔  8c5b695f4724 images/blobs/sha256/8c5b695...014f94c8d4ea62772c477c1e03
+  ✔  b95c82728c36 images/blobs/sha256/b95c827...042a9c5d84426c1674044916d4
+  ✔  ab67ffd6e92e images/blobs/sha256/ab67ffd...f8c9d93c0e719f6350e99d3aea
+  ✔  e2b45cdcd8bf images/blobs/sha256/e2b45cd...000f1bc1695014e38821dc675c
+  ✔  cf79ae90993d [application/vnd.oci.image.manifest.v1+json]
+  ✔  Published $REPOSITORY_URL/helm-oci-chart:0.0.1-arm64 [application/vnd.oci.image.manifest.v1+json]
+
+  •  To inspect/deploy/pull:
+  •  zarf package inspect oci://$REPOSITORY_URL/helm-oci-chart:0.0.1-arm64 --insecure
+  •  zarf package deploy oci://$REPOSITORY_URL/helm-oci-chart:0.0.1-arm64 --insecure
+  •  zarf package pull oci://$REPOSITORY_URL/helm-oci-chart:0.0.1-arm64 --insecure
+
+ + diff --git a/docs-website/static/docs/walkthroughs/publish_and_deploy_pull.html b/docs-website/static/docs/walkthroughs/publish_and_deploy_pull.html new file mode 100644 index 0000000000..561176211a --- /dev/null +++ b/docs-website/static/docs/walkthroughs/publish_and_deploy_pull.html @@ -0,0 +1,80 @@ + + + + + + +
+$ zarf package pull oci://$REPOSITORY_URL/helm-oci-chart:0.0.1-arm64
+
+Saving log file to
+/var/folders/bk/rz1xx2sd5zn134c0_j1s2n5r0000gp/T/zarf-2023-03-30-11-56-13-4058959193.log
+  •  Pulling Zarf package from $REPOSITORY_URL/helm-oci-chart:0.0.1-arm64
+  •  Pulling Zarf package data (0.00 Byte of 26.90 MBs)
+  ✔  515aceaacb8d images/index.json
+  ✔  fd143c92d486 zarf.yaml
+  ✔  d8399f7b56ca [application/vnd.unknown.config.v1+json]
+  ✔  b66dbb27a733 images/oci-layout
+  ✔  42c097bd02de components/helm-oci-chart.tar
+  ✔  46564f0eff85 images/blobs/sha256/46564f0...06008f762391a7bb7d58f339ee
+  ✔  4f4fb700ef54 images/blobs/sha256/4f4fb70...b5577484a6d75e68dc38e8acc1
+  ✔  932a2288fd3a sboms.tar
+  ✔  74eae207aa23 images/blobs/sha256/74eae20...fcb007d3da7b842313f80d2c33
+  ✔  a9eaa45ef418 images/blobs/sha256/a9eaa45...6789c52a87ba5a9e6483f2b74f
+  ✔  ab67ffd6e92e images/blobs/sha256/ab67ffd...f8c9d93c0e719f6350e99d3aea
+  ✔  6ff8f4799d50 images/blobs/sha256/6ff8f47...4bc00ec8b988d28cef78ea9a5b
+  ✔  e2b45cdcd8bf images/blobs/sha256/e2b45cd...000f1bc1695014e38821dc675c
+  ✔  b95c82728c36 images/blobs/sha256/b95c827...042a9c5d84426c1674044916d4
+  ✔  8c5b695f4724 images/blobs/sha256/8c5b695...014f94c8d4ea62772c477c1e03
+  ✔  cf79ae90993d [application/vnd.oci.image.manifest.v1+json]
+  ✔  Pulling Zarf package data (26.90 MBs)
+  ✔  Pulled $REPOSITORY_URL/helm-oci-chart:0.0.1-arm64
+
+# Use vim if you want to inspect the tarball's contents without decompressing it
+$ vim zarf-package-helm-oci-chart-arm64-0.0.1.tar.zst
+# You quit vim with the keyboard command `:q`
+
+ + diff --git a/docs-website/static/docs/walkthroughs/publish_and_deploy_remove.html b/docs-website/static/docs/walkthroughs/publish_and_deploy_remove.html new file mode 100644 index 0000000000..a245963916 --- /dev/null +++ b/docs-website/static/docs/walkthroughs/publish_and_deploy_remove.html @@ -0,0 +1,57 @@ + + + + + + +
+$ zarf package remove helm-oci-chart --confirm
+
+Saving log file to
+/var/folders/bk/rz1xx2sd5zn134c0_j1s2n5r0000gp/T/zarf-2023-03-30-12-10-10-2699609497.log
+  •  Removing zarf package helm-oci-chart
+
+ + diff --git a/docs-website/static/docs/walkthroughs/publish_and_deploy_setup.html b/docs-website/static/docs/walkthroughs/publish_and_deploy_setup.html new file mode 100644 index 0000000000..9104063438 --- /dev/null +++ b/docs-website/static/docs/walkthroughs/publish_and_deploy_setup.html @@ -0,0 +1,59 @@ + + + + + + +
+# Setup some variables for the registry we will be using
+$ REGISTRY=docker.io
+$ set +o history
+$ REGISTRY_USERNAME=<username> # <-- replace with your username
+$ REPOSITORY_URL=$REGISTRY/$REGISTRY_USERNAME
+$ REGISTRY_SECRET=<secret> # <-- replace with your password or auth token
+$ set -o history
+
+ + diff --git a/docs-website/static/docs/walkthroughs/troubleshoot_insecure_registry.html b/docs-website/static/docs/walkthroughs/troubleshoot_insecure_registry.html new file mode 100644 index 0000000000..5a87cd8d59 --- /dev/null +++ b/docs-website/static/docs/walkthroughs/troubleshoot_insecure_registry.html @@ -0,0 +1,74 @@ + + + + + + +
+$ zarf package publish zarf-package-helm-oci-chart-arm64-0.0.1.tar.zst
+
+Saving log file to
+/var/folders/bk/rz1xx2sd5zn134c0_j1s2n5r0000gp/T/zarf-2023-03-30-12-43-07-140496909.log
+  •  Loading Zarf Package zarf-package-helm-oci-chart-arm64-0.0.1.tar.zst
+  •  Loading Zarf Package zarf-package-helm-oci-chart-arm64-0.0.1.tar.zst
+
+

+                                                                                
+  📦 PACKAGE PUBLISH helm-oci-chart:0.0.1-arm64                                 
+                                                                                
+                                                                                
+

+
+  •  Publishing package to $REPOSITORY_URL/helm-oci-chart:0.0.1-arm64
+  •  
+  •  Prepared 14 layers
+  •  Publishing jvb/helm-oci-chart:0.0.1-arm64
+     ERROR:  Failed to publish package: unable to publish package $REPOSITORY_URL/helm-oci-chart:0.0.1-arm64:
+             Head
+             "https://localhost:5000/v2/jvb/helm-oci-chart/manifests/sha256:239ff96a91a4e356ed6e8eadb4dad633cbffea69fc35d436e08ebdc7f2d9a2fd":
+             http: server gave HTTP response to HTTPS client
+
+ + diff --git a/docs-website/static/docs/walkthroughs/troubleshoot_version_required_no_version.html b/docs-website/static/docs/walkthroughs/troubleshoot_version_required_no_version.html new file mode 100644 index 0000000000..d2b396a540 --- /dev/null +++ b/docs-website/static/docs/walkthroughs/troubleshoot_version_required_no_version.html @@ -0,0 +1,70 @@ + + + + + + +
+$ cat zarf.yaml
+kind: ZarfPackageConfig
+metadata:
+  name: helm-oci-chart
+  description: Deploy podinfo using a Helm OCI chart
+  # Note: In order to publish, the package must have a version
+  VERSION NEEDS TO BE HERE
+
+components:
+  - name: helm-oci-chart
+    required: true
+    charts:
+      - name: podinfo
+        version: 6.3.3
+        namespace: helm-oci-demo
+        url: oci://ghcr.io/stefanprodan/charts/podinfo
+    images:
+      - ghcr.io/stefanprodan/podinfo:6.3.3
+
+ + diff --git a/docs-website/static/docs/walkthroughs/troubleshoot_version_required_publish.html b/docs-website/static/docs/walkthroughs/troubleshoot_version_required_publish.html new file mode 100644 index 0000000000..39c5c83c61 --- /dev/null +++ b/docs-website/static/docs/walkthroughs/troubleshoot_version_required_publish.html @@ -0,0 +1,59 @@ + + + + + + +
+$ zarf package publish zarf-package-helm-oci-chart-arm64.tar.zst  oci://$REPOSITORY_URL
+
+Saving log file to
+/var/folders/bk/rz1xx2sd5zn134c0_j1s2n5r0000gp/T/zarf-2023-03-30-12-17-19-1023269385.log
+  •  Loading Zarf Package zarf-package-helm-oci-chart-arm64.tar.zst
+  •  Loading Zarf Package zarf-package-helm-oci-chart-arm64.tar.zst
+     ERROR:  Failed to publish package: version is required for publishing
+
+ + diff --git a/docs/.images/walkthroughs/publish_and_deploy_thumbnail.png b/docs/.images/walkthroughs/publish_and_deploy_thumbnail.png new file mode 100644 index 0000000000..6de909c8ba Binary files /dev/null and b/docs/.images/walkthroughs/publish_and_deploy_thumbnail.png differ diff --git a/docs/13-walkthroughs/7-publish-and-deploy.md b/docs/13-walkthroughs/7-publish-and-deploy.md index 539d181a07..8166271bcb 100644 --- a/docs/13-walkthroughs/7-publish-and-deploy.md +++ b/docs/13-walkthroughs/7-publish-and-deploy.md @@ -4,98 +4,51 @@ In this walkthrough, we are going to run through how to publish a Zarf package to an [OCI](https://github.com/opencontainers/image-spec) compliant registry, allowing end users to pull and deploy packages without needing to build locally, or transfer the package to their environment. +## System Requirements + +- Internet access to download resources or upload packages +- Access to a registry (this walkthrough uses Docker Hub) + ## Prerequisites For following along locally, please ensure the following prerequisites are met: 1. Zarf binary installed on your `$PATH`: ([Install Instructions](../3-getting-started.md#installing-zarf)) 2. Access to a [Registry supporting the OCI Distribution Spec](https://oras.land/implementors/#registries-supporting-oci-artifacts), this walkthrough will be using Docker Hub +3. Access to a cluster that has been [initialized with zarf](./1-initializing-a-k8s-cluster.md). ## Setup +[![Using OCI to Store & Deploy Zarf Packages Video on YouTube](../.images/walkthroughs/publish_and_deploy_thumbnail.png)](https://www.youtube.com/watch?v=QKxgJnC_37Y "Using OCI to Store & Deploy Zarf Packages") + This walkthrough will require a registry to be configured (see [prerequisites](#prerequisites) for more information). The below sets up some variables for us to use when logging into the registry: -```bash -# Setup some variables for the registry we will be using -$ REGISTRY=docker.io -$ set +o history -$ REGISTRY_USERNAME= # <-- replace with your username -$ REPOSITORY_URL=$REGISTRY/$REGISTRY_USERNAME -$ REGISTRY_SECRET= # <-- replace with your password or auth token -$ set -o history -``` + With those set, you can tell Zarf to login to your registry with the following: -```bash -$ echo $REGISTRY_SECRET | zarf tools registry login $REGISTRY --username $REGISTRY_USERNAME --password-stdin - -2023/03/07 23:03:16 logged in via /home/zarf/.docker/config.json -``` + :::note If you do not have the Docker CLI installed, you may need to create a Docker compliant auth config file manually: -```bash -$ mkdir -p ~/.docker -$ AUTH=$(echo -n "$REGISTRY_USERNAME:$REGISTRY_SECRET" | base64) -# Note: If using Docker Hub, the registry URL is `https://index.docker.io/v1/` for the auth config -$ cat < ~/.docker/config.json -{ - "auths": { - "$REGISTRY": { - "auth": "$AUTH" - } - } -} -EOF -``` + ::: -## Publish Package +### Publish Package First, create a valid Zarf package definition (`zarf.yaml`), with the `metadata.version` key set. -```yaml -# Make a new directory to work in -$ mkdir -p zarf-publish-walkthrough && cd zarf-publish-walkthrough - -# For this walkthrough we will use the `helm-oci-chart` example package -# located here: https://github.com/defenseunicorns/zarf/blob/main/examples/helm-oci-chart/zarf.yaml -$ cat < zarf.yaml -kind: ZarfPackageConfig -metadata: - name: helm-oci-chart - description: Deploy podinfo using a Helm OCI chart - # Note: In order to publish, the package must have a version - version: 0.0.1 - -components: - - name: helm-oci-chart - required: true - charts: - - name: podinfo - version: 6.3.3 - namespace: helm-oci-demo - url: oci://ghcr.io/stefanprodan/charts/podinfo - images: - - "ghcr.io/stefanprodan/podinfo:6.3.3" -EOF -``` + + Create the package locally: [CLI Reference](../4-user-guide/1-the-zarf-cli/100-cli-commands/zarf_package_create.md) -```bash -# Create the package (interactively) -$ zarf package create . -# Make these choices at the prompts: -# Create this Zarf package? Yes -# Please provide a value for "Maximum Package Size" 0 -``` + Then publish the package to the registry: @@ -107,35 +60,7 @@ Your package tarball may be named differently based on your machine's architectu [CLI Reference](../4-user-guide/1-the-zarf-cli/100-cli-commands/zarf_package_publish.md) -```bash -$ zarf package publish zarf-package-helm-oci-chart-arm64-0.0.1.tar.zst oci://$REPOSITORY_URL - -... - - • Publishing package to $REPOSITORY_URL/helm-oci-chart:0.0.1-arm64 - ✔ Prepared 14 layers - ✔ 515aceaacb8d images/index.json - ✔ 4615b4f0c1ed zarf.yaml - ✔ 1300d6545c84 sboms.tar - ✔ b66dbb27a733 images/oci-layout - ✔ 46564f0eff85 images/blobs/sha256/46564f0...06008f762391a7bb7d58f339ee - ✔ 4f4fb700ef54 images/blobs/sha256/4f4fb70...b5577484a6d75e68dc38e8acc1 - ✔ 6ff8f4799d50 images/blobs/sha256/6ff8f47...4bc00ec8b988d28cef78ea9a5b - ✔ 74eae207aa23 images/blobs/sha256/74eae20...fcb007d3da7b842313f80d2c33 - ✔ a9eaa45ef418 images/blobs/sha256/a9eaa45...6789c52a87ba5a9e6483f2b74f - ✔ 8c5b695f4724 images/blobs/sha256/8c5b695...014f94c8d4ea62772c477c1e03 - ✔ ab67ffd6e92e images/blobs/sha256/ab67ffd...f8c9d93c0e719f6350e99d3aea - ✔ b95c82728c36 images/blobs/sha256/b95c827...042a9c5d84426c1674044916d4 - ✔ e2b45cdcd8bf images/blobs/sha256/e2b45cd...000f1bc1695014e38821dc675c - ✔ 79be488a834e components/helm-oci-chart.tar - ✔ aed84ba183e7 [application/vnd.oci.artifact.manifest.v1+json] - ✔ Published $REPOSITORY_URL/helm-oci-chart:0.0.1-arm64 [application/vnd.oci.artifact.manifest.v1+json] - - • To inspect/deploy/pull: - • zarf package inspect oci://$REPOSITORY_URL/helm-oci-chart:0.0.1-arm64 - • zarf package deploy oci://$REPOSITORY_URL/helm-oci-chart:0.0.1-arm64 - • zarf package pull oci://$REPOSITORY_URL/helm-oci-chart:0.0.1-arm64 -``` + :::note @@ -145,75 +70,98 @@ To modify, edit `zarf.yaml` and re-run `zarf package create .` ::: -## Inspect Package +### Inspect Package [CLI Reference](../4-user-guide/1-the-zarf-cli/100-cli-commands/zarf_package_inspect.md) Inspecting a Zarf package stored in an OCI registry is the same as inspecting a local package and has the same flags: -```yaml -$ zarf package inspect oci://$REPOSITORY_URL/helm-oci-chart:0.0.1-arm64 ---- -kind: ZarfPackageConfig -metadata: - name: helm-oci-chart - description: Deploy podinfo using a Helm OCI chart - version: 0.0.1 - architecture: arm64 -build: - terminal: minimind.local - user: whoami - architecture: arm64 - timestamp: Tue, 07 Mar 2023 14:27:25 -0600 - version: v0.25.0-rc1-41-g07d61ba7 - migrations: - - scripts-to-actions -components: - - name: helm-oci-chart - required: true - charts: - - name: podinfo - url: oci://ghcr.io/stefanprodan/charts/podinfo - version: 6.3.3 - namespace: helm-oci-demo - images: - - ghcr.io/stefanprodan/podinfo:6.3.3 -``` - -## Deploy Package + -[CLI Reference](../4-user-guide/1-the-zarf-cli/100-cli-commands/zarf_package_deploy.md) -Deploying a package stored in an OCI registry is nearly the same experience as deploying a local package: +### Deploy Package -```bash -# Due to the length of the console output from this command, -# it has been omitted from this walkthrough -$ zarf package deploy oci://$REPOSITORY_URL/helm-oci-chart:0.0.1-arm64 -# Make these choices at the prompts: -# Deploy this Zarf package? Yes +[CLI Reference](../4-user-guide/1-the-zarf-cli/100-cli-commands/zarf_package_deploy.md) -$ zarf packages list +Deploying a package stored in an OCI registry is nearly the same experience as deploying a local package: - Package | Components - helm-oci-chart | [helm-oci-chart] - init | [zarf-injector zarf-seed-registry zarf-registry zarf-agent git-server] -``` + -## Pull Package +### Pull Package [CLI Reference](../4-user-guide/1-the-zarf-cli/100-cli-commands/zarf_package_pull.md) Packages can be saved to the local disk in order to deploy a package multiple times without needing to fetch it every time. -```bash -# go home so we don't clobber our currently local built package -$ cd ~ -$ mkdir -p zarf-packages && cd zarf-packages + + + +## Removal + +1. Use the `zarf package list` command to get a list of the installed packages. This will give you the name of the games package to remove it. + + + +2. Use the `zarf package remove` command to remove the `helm-oci-chart` package. Don't forget the `--confirm` flag. Otherwise you'll receive an error. + + + +## Troubleshooting + +### Failed to publish package: version is required for publishing + +#### Example + + + +#### Remediation + +You attempted to publish a package with no version metadata. + + + +1. Open the zarf.yaml file. +2. Add a version attribute to the [package metadata](https://docs.zarf.dev/docs/user-guide/zarf-schema#metadata) +3. Recreate the package with the `zarf package create` command. +4. Publish the package. The filename will now have the version as part of it. + +### Failed to publish, http: server gave HTTP response to HTTPS client + +#### Example + + + +#### Remediation + +You attempted to publish a package to an insecure registry, using http instead of https. + +1. Use the `--insecure` flag. Note that this is not suitable for production workloads. + +### Unable to connect to the Kubernetes cluster. + +#### Example + + + +#### Remediation + +If you receive this error, either you don't have a Kubernetes cluster, your cluster is down, or your cluster is unreachable. + +1. Check your kubectl configuration, then try again. For more information about kubectl configuration see [Configure Access to Multiple Clusters](https://kubernetes.io/docs/tasks/access-application-cluster/configure-access-multiple-clusters/) from the Kubernetes documentation. + +If you need to setup a cluster, you can perform the following. + +1. Deploy a Kubernetes cluster with the [Creating a K8s Cluster with Zarf](./4-creating-a-k8s-cluster-with-zarf.md) walkthrough. +2. Perform the [Initialize a cluster](./1-initializing-a-k8s-cluster.md) walkthrough. + +After that you can try deploying the package again. + +### Secrets "zarf-state" not found. + +#### Example + + -$ zarf package pull oci://$REPOSITORY_URL/helm-oci-chart:0.0.1-arm64 +#### Remediation -# use vim if you want to inspect the tarball's contents without decompressing it -$ vim zarf-package-helm-oci-chart-arm64-0.0.1.tar.zst -# don't forget to escape w/ `:q` -``` +If you receive this error when zarf is attempting to deploy any component, this means you have not initialized the kubernetes cluster. This is one of the prerequisites for this walkthrough. Perform the [Initialize a cluster](./1-initializing-a-k8s-cluster.md) walkthrough, then try again.