Agent installation with Helm

The Akuity Platform provides an official Helm chart for installing and registering the Akuity agent on a cluster. The chart handles both registering the agent with the Akuity Platform and deploying the agent components in a single step. It supports both Argo CD cluster agents and Kargo agents, selected with the agentType value.

The chart is published to the OCI registry at oci://quay.io/akuity/akuity-platform-charts/akuity-agent.

Overview

When installed, the chart runs a registration job that:

1. Creates (or upserts) the agent entry in the Akuity Platform using the Akuity CLI.
2. Fetches the generated agent manifests from the platform.
3. Applies the agent manifests to the cluster.

The agent is designed to be provisioned as part of a cluster bootstrapping process. Rather than registering clusters manually after they are created, we recommend embedding this Helm chart into the platform infrastructure that is already in place. For example Terraform - so that every new cluster is registered automatically on creation.

Choosing the agent type

The agentType value selects which agent to install:

• argocd (default) — registers the cluster with an Argo CD instance and installs the Argo CD cluster agent.
• kargo — registers a Kargo agent with a Kargo instance and installs the Kargo agent.

In both cases clusterName is the name the agent is registered under (the cluster name for Argo CD, the agent name for Kargo) and instanceName is the Argo CD or Kargo instance to attach to.

Prerequisites

• An Akuity Platform organization and an existing Argo CD or Kargo instance to register the agent with.
• An Akuity API key. Generate one from the API Keys tab on the organization profile page in the Akuity Portal UI, or see the CLI reference for the akuity apikey create command.
• Helm v3 and kubectl access to the target cluster.

Installing an Argo CD agent

helm install akuity-agent oci://quay.io/akuity/akuity-platform-charts/akuity-agent \
  --namespace akuity-agent \
  --create-namespace \
  --set clusterName=<cluster-name> \
  --set instanceName=<argocd-instance-name> \
  --set organizationName=<organization-name> \
  --set akuityApiKeyId=<api-key-id> \
  --set akuityApiKeySecret=<api-key-secret>

agentType defaults to argocd, so it does not need to be set explicitly.

Installing a Kargo agent

helm install akuity-kargo-agent oci://quay.io/akuity/akuity-platform-charts/akuity-agent \
  --namespace akuity \
  --create-namespace \
  --set agentType=kargo \
  --set clusterName=<agent-name> \
  --set instanceName=<kargo-instance-name> \
  --set organizationName=<organization-name> \
  --set akuityApiKeyId=<api-key-id> \
  --set akuityApiKeySecret=<api-key-secret>

By default the chart installs a self-hosted Kargo agent (kargo.selfHosted=true): the agent runs in your cluster and the chart applies its manifests. The Kargo agent installs a mutating admission webhook in its namespace; the registration job waits for that webhook to become ready before completing, so the install may take a little longer than the Argo CD agent.

Set kargo.selfHosted=false for an Akuity-managed agent. In that case the agent is run by Akuity, no manifests are produced for the cluster, and the chart only registers the agent (it does not apply anything to your cluster).

warning

Each Kargo agent should be installed into a single namespace. The Kargo agent's webhook selects namespaces by the agent's instance and name labels, so reusing the same clusterName (agent name) and instanceName across multiple namespaces can cause their webhooks to interfere with each other. Use a distinct clusterName per agent.

helm uninstall removes the registration job but does not remove the in-cluster Kargo agent, including its cluster-scoped MutatingWebhookConfiguration. To remove an agent, delete it from the Akuity Portal UI so the platform tears down its in-cluster resources cleanly. Leaving an agent's resources behind (for example by deleting its namespace manually) can orphan the webhook configuration and block future installs.

Configuration reference

Common values

Value	Description	Required
agentType	Agent to install: argocd (default) or kargo	No
clusterName	Name to register the agent under (cluster name for Argo CD, agent name for Kargo)	Yes
instanceName	Name of the Argo CD or Kargo instance to register with	Yes
organizationName	Name of your Akuity organization	Yes
akuityApiKeyId	Akuity API key ID	Yes
akuityApiKeySecret	Akuity API key secret	Yes
akuityServerUrl	Akuity Platform API URL (defaults to https://akuity.cloud)	No
version	Pin a specific agent version	No
agentSize	Agent resource size	No
labels	Labels to apply to the agent, e.g. ["env=prod", "team=platform"]	No
annotations	Annotations to apply to the agent	No
disableAutoUpdate	Disable automatic agent updates	No
extraArgs	Extra arguments to pass to the agent create command	No
rbac.extraRules	Extra policy rules appended to the registration job's ClusterRole, for granting permissions to additional resources the agent manifests may require	No

Argo CD options (agentType: argocd)

Value	Description	Required
argocd.project	Project to associate the cluster with	No
argocd.namespaceScoped	Install the agent in namespace-scoped mode	No
argocd.stateReplication	Enable state replication	No
argocd.redisTunneling	Enable Redis tunneling	No
argocd.disableAutoUpgrade	Disable automatic agent upgrades	No
argocd.argoprojCustomImageRegistry	Custom image registry for Argo CD (argoproj) images	No

Deprecated

The Argo CD options moved under the argocd.* key. The previous top-level keys (project, namespaceScoped, stateReplication, redisTunneling, disableAutoUpgrade, argoprojCustomImageRegistry) are deprecated but still honored for backwards compatibility, and will be removed in a future release. If a value is set both at the top level and under argocd.*, the argocd.* value takes precedence (for booleans, either being true enables the flag). Migrate existing values files to the argocd.* keys.

Kargo options (agentType: kargo)

Value	Description	Required
kargo.selfHosted	Run the agent in this cluster (true, default) or as an Akuity-managed agent (false)	No
kargo.agentNamespace	Namespace to install the Kargo agent into (defaults to the release namespace)	No
kargo.akuityArgocdName	Name of an Akuity-managed Argo CD instance to associate with this agent	No
kargo.selfManagedArgocdUrl	URL of a self-managed Argo CD instance to associate with this agent	No
kargo.argocdNamespace	Target Argo CD namespace for the agent	No
kargo.kargoCustomImageRegistry	Custom image registry for Kargo images	No
kargo.akuityCustomImageRegistry	Custom image registry for Akuity images	No
kargo.kustomizationPath	Path to a kustomization.yaml with extra Kargo agent kustomizations	No
kargo.defaultShard	Set this agent as the instance's default shard	No

Embedding in Terraform

For clusters managed by Terraform, use the helm_release resource to register each cluster as part of provisioning. This ensures the agent is always installed when a new cluster is created, without any manual steps.

variable "akuity_api_key_id" {
  type      = string
  sensitive = true
}

variable "akuity_api_key_secret" {
  type      = string
  sensitive = true
}

resource "helm_release" "akuity_agent" {
  name             = "akuity-agent"
  repository       = "oci://quay.io/akuity/akuity-platform-charts"
  chart            = "akuity-agent"
  namespace        = "akuity-agent"
  create_namespace = true

  set {
    name  = "clusterName"
    value = var.cluster_name
  }

  set {
    name  = "instanceName"
    value = var.argocd_instance_name
  }

  set {
    name  = "organizationName"
    value = var.akuity_organization_name
  }

  set {
    name        = "akuityApiKeyId"
    value       = var.akuity_api_key_id
    type        = "string"
  }

  set_sensitive {
    name  = "akuityApiKeySecret"
    value = var.akuity_api_key_secret
  }
}

note

Store akuityApiKeyId and akuityApiKeySecret in a secrets manager (such as AWS Secrets Manager or HashiCorp Vault) and pass them into Terraform as sensitive variables rather than hardcoding them in the configuration.