Skip to Content

Deploying Ark

Deploy Ark locally using the CLI, Helm, or to remote clusters with registry-based deployment.

Required resources

Running Ark requires at least 2 vCPU and 4 GiB of RAM. Further resource consumption depends on individual workflows and load.

Install with the CLI

For the standard CLI install, follow the Quickstart, which is kept current and tested. This page covers: Helm and remote-cluster deployment, storage backends, private registries, CI/CD RBAC, and multi-tenant operation.

Storage backend

ark install reads the storage backend from .arkrc.yaml. The default is etcd, which stores resources as CRDs. The PostgreSQL path uses an aggregated API server backed by Postgres and is suited for larger fleets, oversize resources, or shared-DB strategies.

To use PostgreSQL, add a storage block to .arkrc.yaml:

storage:
  backend: postgresql
  postgresql:
    host: db.example.com
    user: ark
    passwordSecretName: ark-db-password

Then run ark install as usual. The --backend CLI flag overrides the config value (e.g., --backend etcd for a temporary switch). See PostgreSQL Storage Backend for the full setup, database requirements, and operational notes.

Local Development

To run in local development mode with live-reload, install Devspace , clone and run:

# Clone the repo, move to the project.
git clone https://github.com/mckinsey/agents-at-scale-ark.git
cd agents-at-scale-ark
 
# Run with live-reload for local development.
devspace dev

More details are in the Local Development developer guide.

Deploying via Helm

Ark can be deployed using the Helm charts that are attached to all releases  and deployed to the charts packages . By default the chart uses the latest images available on the release. This process, including the deployment of prerequisites can also be run via the ark install command.

Install prerequisites on your remote cluster:

# Install cert-manager
helm repo add jetstack https://charts.jetstack.io --force-update  
helm repo update
helm upgrade --install cert-manager jetstack/cert-manager \
  --namespace cert-manager \
  --create-namespace \
  --set crds.enabled=true
 
# Install Gateway API CRDs
kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.3.0/standard-install.yaml

Deploy the Ark controller:

helm upgrade --install \
  ark-controller oci://ghcr.io/mckinsey/agents-at-scale-ark/charts/ark-controller \
  --namespace ark-system \
  --create-namespace \
  --set rbac.enable=true

In many cases, you will want to install the ark-api and ark-dashboard services as well. When running on a local cluster you may also want to install the localhost-gateway:

helm upgrade --install ark-api oci://ghcr.io/mckinsey/agents-at-scale-ark/charts/ark-api
helm upgrade --install ark-dashboard oci://ghcr.io/mckinsey/agents-at-scale-ark/charts/ark-dashboard
helm upgrade --install localhost-gateway oci://ghcr.io/mckinsey/agents-at-scale-ark/charts/localhost-gateway

The fark (Fast Agentic Runtime Kit) CLI can be built from source:

cd tools/fark
go build -o fark ./cmd/fark
cp fark /usr/local/bin
fark

Or installed via the GitHub Releases 

Deploying from a Private Registry

The chart can be configured to install containers hosted in any registry:

helm upgrade --install \
  ark-controller oci://ghcr.io/mckinsey/agents-at-scale-ark/charts/ark-controller \
  --version 0.1.31 \
  --namespace ark-system \
  --create-namespace \
  --set controllerManager.container.image.repository=your-registry.com/ark-controller \
  --set controllerManager.container.image.tag=0.1.31 \
  --set containerRegistry.enabled=true \
  --set containerRegistry.server=your-registry.com \
  --set containerRegistry.username=your_username \
  --set containerRegistry.password=your_token \
  --set rbac.enable=true
 
helm upgrade --install \
  ark-completions oci://ghcr.io/mckinsey/agents-at-scale-ark/charts/ark-completions \
  --version 0.1.31 \
  --namespace ark-system \
  --set image.repository=your-registry.com/ark-completions \
  --set image.tag=0.1.31

If you need to transfer containers between registries, use the transfer script:

# Transfer from source registry to your target registry
export SOURCE_DOCKER_REGISTRY=source-registry.com  
export TARGET_DOCKER_REGISTRY=your-registry.com
export TARGET_DOCKER_USERNAME=your_username
export TARGET_DOCKER_TOKEN=your_token
export VERSION=0.1.31
./scripts/deploy/transfer-ark-containers.sh

Checking Ark Version and Status

Once deployed, you can check the running version:

# Via Helm
helm list -n ark-system
 
# Via deployment labels  
kubectl get deployment ark-controller -n ark-system \
  -o jsonpath='{.metadata.labels.app\.kubernetes\.io/version}'

The Ark CLI can be used to show the status of all running Ark services and their versions, with the ark status command.

# Check overall system status
ark status

Cluster Preparation for CI/CD Deployments

Before using GitHub Actions to deploy Ark to a cluster, platform administrators need to set up the required RBAC permissions.

Ark includes a standard deployer role in ark/config/rbac/ark-deployer-role.yaml that defines the minimum permissions required for deployments. This role allows creating namespaces, deploying services, installing CRDs, and configuring webhooks.

Setup Process

Apply the standard Ark deployer role and then bind to the repository - this will ensure that your GitHub Actions will be able to deploy Ark. In many cases you will have to specify the specific runner via runs_on but this will depend on your organization’s OIDC configuration:

# Create the ark deployer role, which has the necessary permissions to
# deploy Ark.
kubectl apply -f ark/config/rbac/ark-deployer-role.yaml
 
# Add the GitHub repository to the role. This allows GitHub workflows to
# deploy Ark to any cluster they have OIDC access to.
./scripts/deploy/bind-deployer-role.sh "mckinsey/agents-at-scale-ark"

This creates a ClusterRoleBinding that connects your GitHub repository identity (via OIDC) to the deployment permissions.

The Ark Controller

By default, the ark-controller is deployed into the ark-system namespace. When the controller executes a query, it can optionally impersonate the service account specified in the query.serviceAccount field. Impersonation is enabled by default and can be configured via the ark-controller chart values:

# values.yaml for ark-controller
rbac:
  enable: true
  impersonation:
    # Allow impersonation when requested by queries.
    enabled: true

When enabled (default), the controller can impersonate any service account specified in queries. When disabled, queries can only run with the controller’s own identity. If no serviceAccount is specified for a query, no impersonation will occur and the ark-controller will execute the query using its own service account.

Setting Up Tenant Namespaces

The ark-tenant Helm chart provisions namespaces for Ark workloads:

helm install ark-tenant oci://ghcr.io/mckinsey/agents-at-scale-ark/charts/ark-tenant \
  -n tenant-1 \
  --create-namespace \
  --set serviceAccount.name=ark-tenant

This creates:

  • The namespace (if it doesn’t exist)
  • The service account
  • An ark-tenant-role with Ark and Kubernetes permissions
  • A RoleBinding linking the service account to the role
  • Builtin tools (terminate, noop) for agent workflows

Resource quotas and network policies are also available, documented in the chart. Queries then run under this service account via their query.serviceAccount field (subject to the impersonation setting above); omit it to use the controller’s own identity.

The Tenant and Namespace Management guide is the canonical reference for multi-tenancy — CLI-based setup, cross-tenant access via RBAC, broker storage isolation, and the development workflow.

Last updated on
Quickstart