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 cluster with the Akuity Platform and deploying the agent components in a single step.

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

Prerequisites

• An Akuity Platform organization and an existing Argo CD instance to register the cluster 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 the chart

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>

Configuration reference

Value	Description	Required
clusterName	Name of the cluster as it will appear in the Akuity Platform	Yes
instanceName	Name of the Argo CD instance to register the cluster 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 cluster, e.g. ["env=prod", "team=platform"]	No
annotations	Annotations to apply to the cluster	No
project	Project to associate the cluster with	No
namespaceScoped	Install the agent in namespace-scoped mode	No
disableAutoUpdate	Disable automatic agent updates	No
stateReplication	Enable state replication	No
redisTunneling	Enable Redis tunneling	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.