Sync OCI artifacts from Artifact Registry
This page shows you how to sync an OCI artifact from Artifact Registry.
You can configure Config Sync to sync from OCI images by using Artifact Registry. To use this feature, you must enable the RootSync and RepoSync APIs.
Since Artifact Registry is a fully-managed service with support for both
container images and non-container artifacts, we recommend that you use
it for your container image storage and management on Google Cloud. There are
multiple tools available to push artifacts to Artifact Registry. For example,
you can
push a Docker image,
push a Helm chart, or use
the
go-containerregistry library
to work with container registries. Choose the tool that works best for you.
This page shows you a simple way to create and publish your image to a
repository in Artifact Registry with crane
and oras
.
Create an Artifact Registry repository
In this section, you'll create an Artifact Registry repository. To learn more about creating Artifact Registry repositories, see Create repositories.
Create environment variables:
export PROJECT_ID=PROJECT_ID export AR_REPO_NAME=AR_REPO_NAME export GSA_NAME=GSA_NAME export AR_REGION=AR_REGION
Replace the following:
PROJECT_ID
: your project IDAR_REPO_NAME
: the name that you want to give your Artifact Registry repository.GSA_NAME
: the name of the custom Google service account that you want to use to connect to Artifact Registry.AR_REGION
: the region where you want to locate the Artifact Registry repository. You can use regions such asus-central1
or multi-regions such asus
.
Enable the Artifact Registry API:
gcloud services enable artifactregistry.googleapis.com \ --project=${PROJECT_ID}
Create an Artifact Registry repository:
gcloud artifacts repositories create ${AR_REPO_NAME} \ --repository-format=docker \ --location=${AR_REGION} \ --description="Config Sync OCI repo" \ --project=${PROJECT_ID}
Grant the Artifact Registry Reader (
roles/artifactregistry.reader
) IAM role to the Google service account:gcloud artifacts repositories add-iam-policy-binding ${AR_REPO_NAME} \ --location ${AR_REGION} \ --member "serviceAccount:${GSA_NAME}@${PROJECT_ID}.iam.gserviceaccount.com" \ --role roles/artifactregistry.reader
Push an image to the Artifact Registry repository
In this section, you'll create an OCI image and push it to Artifact Registry.
Create a
Namespace
manifest file:cat <<EOF> test-namespace.yaml apiVersion: v1 kind: Namespace metadata: name: test EOF
Log in to Artifact Registry:
gcloud auth configure-docker ${AR_REGION}-docker.pkg.dev
Package and push the image to Artifact Registry:
crane
The commands in this section use
crane
to interact with remote images and registries.Package the file:
tar -cf test-namespace.tar test-namespace.yaml
Install the
crane
tool.Push the image to Artifact Registry:
crane append -f test-namespace.tar -t ${AR_REGION}-docker.pkg.dev/${PROJECT_ID}/${AR_REPO_NAME}/test-namespace:v1
oras
The commands in this section use
oras
to interact with remote images and registries.Package the file:
tar -czf test-namespace.tar.gz test-namespace.yaml
Install the
oras
tool.Push the image to Artifact Registry:
oras push ${AR_REGION}-docker.pkg.dev/${PROJECT_ID}/${AR_REPO_NAME}/test-namespace:v1 test-namespace.tar.gz
Configure Config Sync to sync from your image
In this section, you'll create a RootSync
object and configure Config Sync
to sync from the OCI image.
Create a
RootSync
object with a unique name:cat <<EOF>> ROOT_SYNC_NAME.yaml apiVersion: configsync.gke.io/v1beta1 kind: RootSync metadata: name: ROOT_SYNC_NAME namespace: config-management-system spec: sourceFormat: unstructured sourceType: oci oci: image: ${AR_REGION}-docker.pkg.dev/${PROJECT_ID}/${AR_REPO_NAME}/test-namespace:v1 dir: . auth: gcpserviceaccount gcpServiceAccountEmail: ${GSA_NAME}@${PROJECT_ID}.iam.gserviceaccount.com EOF
Replace
ROOT_SYNC_NAME
with the name of yourRootSync
object. The name should be unique in the cluster and have no more than 26 characters. For the full list of options when configuringRootSync
objects, seeRootSync
andRepoSync
fields.Grant the Workload Identity User (
roles/iam.workloadIdentityUser
) IAM role to the Google service account:gcloud iam service-accounts add-iam-policy-binding \ --role roles/iam.workloadIdentityUser \ --member "serviceAccount:$PROJECT_ID.svc.id.goog[config-management-system/root-reconciler-${ROOT_SYNC_NAME}]" \ ${GSA_NAME}@${PROJECT_ID}.iam.gserviceaccount.com
Create IAM policy binding between the Google service account and Kubernetes service account:
gcloud iam service-accounts add-iam-policy-binding \ --role roles/iam.workloadIdentityUser \ --member "serviceAccount:${PROJECT_ID}.svc.id.goog[config-management-system/KSA_NAME]" \ ${GSA_NAME}@${PROJECT_ID}.iam.gserviceaccount.com
KSA_NAME
: the Kubernetes service account for the reconciler. For root repositories, if theRootSync
name isroot-sync
,KSA_NAME
isroot-reconciler
. Otherwise, it isroot-reconciler-ROOT_SYNC_NAME
.
Apply the
RootSync
object:kubectl apply -f ROOT_SYNC_NAME.yaml
Verify that Config Sync is syncing from the image:
nomos status --contexts=$(kubectl config current-context)
You should see output similar to the following example:
Connecting to clusters... *publish-config-registry -------------------- <root>:root-sync-test ${AR_REGION}-docker.pkg.dev/${PROJECT_ID}/${AR_REPO_NAME}/test-namespace:v1 SYNCED 05e6a6b77de7a62286387cfea833d45290105fe84383224938d7b3ab151a55a1 Managed resources: NAMESPACE NAME STATUS SOURCEHASH namespace/test Current 05e6a6b
You have now successfully synced an image to your cluster.
What's next
- Learn more about installing Config Sync.