Managing Kargo Resources with Argo CD and Private Image Registries

This article explains how to:

• Use your own container image repositories for Akuity Platform, Argo CD, and Kargo control plane workloads.
• Configure Argo CD to manage Kargo resources.
• Automatically create applications per Kargo project using ApplicationSets.
• Enforce team-based visibility and access using Argo CD Projects and SSO.

1. Using Custom Image Repositories

When running Akuity’s Self-Hosted Platform, you may want to use your own private registry instead of the default public image sources.

Below is a sample Helm values.yaml configuration for customizing image repositories used by Akuity Platform, Argo CD, and Kargo control planes.

# Helm value file (values.yaml)
# Reference: https://docs.akuity.io/self-hosted/helm-values-reference

## Akuity platform images (akuity-platform namespace)
image:
  repository: us-docker.pkg.dev/akuity/akp-sh/akuity-platform

## Argo CD control plane images (argocd-.* namespaces)
instanceValues:
  kustomization:
    apiVersion: kustomize.config.k8s.io/v1beta1
    kind: Kustomization
    images:
      - name: quay.io/akuity/argocd
        newName: myregistry.com/org_name/argocd
      - name: quay.io/akuity/busybox
        newName: myregistry.com/org_name/busybox
      - name: quay.io/akuity/dexidp/dex
        newName: myregistry.com/org_name/dex
      - name: quay.io/akuity/edoburu/pgbouncer
        newName: myregistry.com/org_name/pgbouncer
      - name: quay.io/akuity/ghcr.io/appscode-images/pgpool2
        newName: myregistry.com/org_name/pgpool2
      - name: quay.io/akuity/haproxy
        newName: myregistry.com/org_name/haproxy
      - name: quay.io/akuity/rancher/k3s
        newName: myregistry.com/org_name/k3s
      - name: quay.io/akuity/redis
        newName: myregistry.com/org_name/redis
      - name: us-docker.pkg.dev/akuity/akp/agent-server
        newName: myregistry.com/org_name/agent-server
      - name: us-docker.pkg.dev/akuity/docker-io/curlimages/curl
        newName: myregistry.com/org_name/curl

## Kargo control plane images (kargo-.* namespaces)
kargoInstanceValues:
  kustomization:
    apiVersion: kustomize.config.k8s.io/v1beta1
    kind: Kustomization
    images:
      - name: ghcr.io/dexidp/dex
        newName: myregistry.com/org_name/dex
      - name: quay.io/akuity/edoburu/pgbouncer
        newName: myregistry.com/org_name/pgbouncer
      - name: quay.io/akuity/ghcr.io/appscode-images/pgpool2
        newName: myregistry.com/org_name/pgpool2
      - name: quay.io/akuity/kargo
        newName: myregistry.com/org_name/kargo
      - name: quay.io/akuity/rancher/k3s
        newName: myregistry.com/org_name/k3s
      - name: quay.io/argoproj/argo-rollouts
        newName: myregistry.com/org_name/argo-rollouts
      - name: us-docker.pkg.dev/akuity/akp/agent-server
        newName: myregistry.com/org_name/agent-server
      - name: us-docker.pkg.dev/akuity/docker-io/curlimages/curl
        newName: myregistry.com/org_name/curl

You can check the current image tags for each version of the platform here:
👉 Akuity Self-Hosted Image List

2. Configuring Agents for Argo CD and Kargo

Each Argo CD and Kargo instance can use custom image registries for their Agents.
This can be configured via:

UI Path:

• Argo CD: Argo CD → Instance → Settings → Agent Default Settings

• Kargo: Kargo → Instance → Settings → Agent Default Settings

Alternatively, this can be automated via:

• The Akuity Terraform Provider, or

• The Declarative Specs method.

3. Managing Kargo Resources with Argo CD

You can leverage Argo CD to declaratively manage Kargo resources using the following structure:

Recommended Setup:

1. One Git Repository per Kargo Instance

   • Each repository manages a specific Kargo instance.

   • Within each repository, create a separate branch per Kargo Project.

2. Automated Application Creation via ApplicationSets

   • Configure an Argo CD ApplicationSet to automatically generate an Application for each new branch.

   • This ensures each Kargo project gets its own managed Application automatically.

3. Team-Based Access Control using SSO and Argo CD Projects

   • Integrate SSO for Argo CD to allow team-specific login and visibility.

   • Configure Argo CD Projects so each team can only view and manage their own Kargo resources.

   • This isolates project visibility and prevents cross-team access.

4. Example Architecture
   ├── kargo-instance-repo
│   ├── project-team-a (branch)
│   │   ├── promotion.yaml
│   │   ├── stage.yaml
│   │   └── project.yaml
│   ├── project-team-b (branch)
│   └── project-team-c (branch)
└── ApplicationSet.yaml  ← Defines rules to create an Argo CD Application for each branch
   
   

   Each branch (project-team-a, project-team-b, etc.) maps to a separate Argo CD Project, providing isolation and delegated management per team.

References:

• Akuity Self-Hosted Helm Values Reference

• Akuity Self-Hosted Image List

• Argo CD ApplicationSet Documentation