Accessing the Kargo Control Plane From a Custom Step Without an API Token

Custom promotion steps that need to call back into the Kargo API (for example, to read a Promotion's stage and freight) don't need a manually generated API token. Setting the access-control-plane capability on the step provisions Kubernetes credentials directly into the step's container.

Enabling the capability

apiVersion: ee.kargo.akuity.io/v1alpha1
kind: CustomPromotionStep
metadata:
  name: control-plane-smoke-test
spec:
  image: your-registry/kubectl:1.34
  capabilities:
  - access-control-plane
  env:
  - name: PROJECT
    value: $
  - name: PROMOTION
    value: $
  - name: HOME
    value: /tmp
  command:
  - /bin/sh
  - -ec
  - |
    KARGO_DIR="${STEP_DIRECTORY:-/coordination}/kubernetes/kargo"

    if [ -f "${KARGO_DIR}/kubeconfig" ]; then
      # Remote control plane: a ready-made kubeconfig is provided.
      export KUBECONFIG="${KARGO_DIR}/kubeconfig"
    elif [ -f "${KARGO_DIR}/token" ]; then
      # In-cluster control plane: build a kubeconfig around the rotating token.
      export KUBECONFIG=/tmp/kargo.kubeconfig
      cat > "$KUBECONFIG" <<EOF
    apiVersion: v1
    kind: Config
    clusters:
    - name: kargo
      cluster:
        server: https://${KUBERNETES_SERVICE_HOST}:${KUBERNETES_SERVICE_PORT}
        certificate-authority: ${KARGO_DIR}/ca.crt
    users:
    - name: kargo
      user:
        tokenFile: ${KARGO_DIR}/token
    contexts:
    - name: kargo
      context:
        cluster: kargo
        user: kargo
    current-context: kargo
    EOF
    else
      echo "no control plane access provisioned -- is capabilities: [access-control-plane] set?" >&2
      exit 1
    fi

Depending on whether the Kargo control plane is remote or in the same cluster as the step, the coordinator provisions either a ready-made kubeconfig or a token + ca.crt pair under ${STEP_DIRECTORY}/kubernetes/kargo/.

Reference: https://docs.kargo.io/user-guide/reference-docs/promotion-steps/custom-steps#advanced-step-capabilities