Skip to main content

Shards and Agents

Kargo uses a sharding mechanism to distribute Stage reconciliation across multiple agents. Each agent has a name that serves as its shard identifier. Stages without a shard assignment are reconciled by the default shard agent.

When to Use Shards​

Assign Stages to specific shards when:

  • Verification requires in-cluster resources: Stages with AnalysisTemplates that require Kubernetes Jobs must run on a self-hosted agent in the target cluster.
  • Network isolation: Stages need to access private services (private Git servers, self-hosted Prometheus, internal APIs) only accessible from specific clusters.
  • Multi-cluster deployments: Multiple agents across different clusters require Stages to be reconciled by agents in the correct cluster.
  • Resource distribution: Distribute the load of Stage reconciliation across multiple agents.

Assigning Stages to Shards​

To assign a Stage to a specific agent shard, set the spec.shard field in your Stage manifest to the name of the agent:

apiVersion: kargo.akuity.io/v1alpha1
kind: Stage
metadata:
  name: production
  namespace: my-project
spec:
  shard: prod-selfhosted
  requestedFreight:
  - origin:
      kind: Warehouse
      name: my-warehouse
  verification:
    analysisTemplates:
    - name: health-check
      kind: ClusterAnalysisTemplate
important

The spec.shard field is the source of truth for shard assignment. Kargo's webhook automatically syncs the kargo.akuity.io/shard label from this field. Do not set the label directly in your YAML files, as it will be automatically managed by Kargo.

Default Shard​

If a Stage does not specify a spec.shard field, it will be reconciled by the agent configured as the default shard. The first agent you connect to a Kargo instance is automatically set as the default shard. You can change the default shard later in the Akuity Platform dashboard.

Example Configuration​

In a typical setup, most Stages run on the default shard (Akuity Platform-managed agent), while Stages with verification run on a self-hosted agent:

# Stage without verification - uses default shard
apiVersion: kargo.akuity.io/v1alpha1
kind: Stage
metadata:
  name: dev
  namespace: my-project
spec:
  # No shard specified - uses default shard
  requestedFreight:
  - origin:
      kind: Warehouse
      name: my-warehouse

---
# Stage with verification - uses self-hosted shard
apiVersion: kargo.akuity.io/v1alpha1
kind: Stage
metadata:
  name: staging
  namespace: my-project
spec:
  shard: prod-selfhosted
  requestedFreight:
  - origin:
      kind: Warehouse
      name: my-warehouse
  verification:
    analysisTemplates:
    - name: integration-tests
      kind: ClusterAnalysisTemplate

Verifying Shard Assignment​

After applying a Stage with spec.shard set, verify the shard assignment using one of the following methods:

  1. Using the Kargo CLI:

    kargo get stages --project <project-name>

    The output will show the shard column:

    NAME      SHARD                  CURRENT FREIGHT   HEALTH   PHASE
    dev                                abc123          Healthy  Steady
    staging  prod-selfhosted           def456          Healthy  Steady

  2. In the Kargo UI: Navigate to your project and view the Stage details. The shard information is displayed in the Stage metadata.

  3. Using kubectl: The kargo.akuity.io/shard label is automatically set by Kargo's webhook:

    kubectl get stage <stage-name> -n <namespace> -o json | jq -r '.metadata.labels."kargo.akuity.io/shard"'