Publish & Deploy Packages w/OCI

Introduction

In this tutorial, we are going to run through how to publish a Zarf package to an OCI 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 tutorial uses Docker Hub)

Prerequisites

For following along locally, please ensure the following prerequisites are met:

• Zarf binary installed on your $PATH: (Installing Zarf)
• Access to a Registry supporting the OCI Distribution Spec, this tutorial will be using Docker Hub
• Access to a cluster that has been initialized with zarf.

Working with OCI Packages

This tutorial will require a registry to be configured (see prerequisites for more information). The below sets up some variables for us to use when logging into the registry:

With those set, you can tell Zarf to login to your registry with the following:

Note

If you do not have the Docker CLI installed, you may need to create a Docker compliant auth config file manually:

Publish Package

First, create a valid Zarf package definition (zarf.yaml), with the metadata.version key set.

Create the package locally:

CLI Reference

Then publish the package to the registry:

Note

Your package tarball may be named differently based on your machine’s architecture. For example, if you are running on an AMD64 machine, the tarball will be named zarf-package-helm-oci-chart-amd64-0.0.1.tar.zst.

CLI Reference

Note

The name and reference of this OCI artifact is derived from the package metadata, e.g.: helm-oci-chart:0.0.1-arm64

To modify, edit zarf.yaml and re-run zarf package create .

Note

The above publish command publishes a fully-built package that is ready to deploy to a cluster, but this isn’t the only kind of package you can publish to an OCI registry.

If you specify a path to a directory containing a zarf.yaml (as you would on zarf package create) you can create a skeleton package that is importable into other packages using component composability. These can be inspected like normal Zarf packages but cannot be deployed as they haven’t been fully created yet.

Inspect Package

CLI Reference

Inspecting a Zarf package stored in an OCI registry is the same as inspecting a local package and has the same flags:

Deploy Package

CLI Reference

Deploying a package stored in an OCI registry is nearly the same experience as deploying a local package:

Pull Package

CLI Reference

Packages can be saved to the local disk in order to deploy a package multiple times without needing to fetch it every time.

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.

1. 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

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
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

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.

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 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 tutorial.
2. Perform the Initialize a cluster tutorial.

After that you can try deploying the package again.

Secrets “zarf-state” not found.

Remediation

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 tutorial. Perform the Initialize a cluster tutorial, then try again.