---
title: Accessing the Kargo Control Plane From a Custom Step Without an API Token
description: Accessing the Kargo Control Plane From a Custom Step
---

[Skip to content](https://support.akuity.io/kb/accessing-the-kargo-control-plane-from-a-custom-step#main-content)

English

Show submenu for translations

[![Akuity-Logo-Color-1](https://support.akuity.io/hubfs/Akuity-Logo-Color-1.svg)](https://akuity.io/)

Open main navigation

Close main navigation

- English
  
  Show submenu for translations

 Hello. How can we help you?

- There are no suggestions because the search field is empty.

1. [Help Center](https://support.akuity.io/kb?hsLang=en)
2. [Kargo](https://support.akuity.io/kb/kargo?hsLang=en)
3. [Configuration](https://support.akuity.io/kb/kargo?hsLang=en#configuration)

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

## Use the access-control-plane capability to reach the Kargo API from inside a CustomPromotionStep via an auto-provisioned kubeconfig or token, instead of managing a separate API token per Kargo instance

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](https://docs.kargo.io/user-guide/reference-docs/promotion-steps/custom-steps#advanced-step-capabilities)

 

- [Argo CD](https://support.akuity.io/kb/argo-cd?hsLang=en#main-content)

    - [App of Apps](https://support.akuity.io/kb/argo-cd?hsLang=en#app-of-apps)
    - [Configuration](https://support.akuity.io/kb/argo-cd?hsLang=en#configuration)
    - [ApplicationSet](https://support.akuity.io/kb/argo-cd?hsLang=en#applicationset)
- [Akuity Platform](https://support.akuity.io/kb/akuity-platform?hsLang=en#main-content)

    - [Audit Logs](https://support.akuity.io/kb/akuity-platform?hsLang=en#audit-logs)
    - [IP Allow Lists](https://support.akuity.io/kb/akuity-platform?hsLang=en#ip-allow-lists)
    - [Terraform](https://support.akuity.io/kb/akuity-platform?hsLang=en#terraform)
    - [Configuration](https://support.akuity.io/kb/akuity-platform?hsLang=en#configuration)
    - [Agents](https://support.akuity.io/kb/akuity-platform?hsLang=en#agents)
    - [Troubleshooting](https://support.akuity.io/kb/akuity-platform?hsLang=en#troubleshooting)
- [Kargo](https://support.akuity.io/kb/kargo?hsLang=en#main-content)

    - [Configuration](https://support.akuity.io/kb/kargo?hsLang=en#configuration)
    - [Warehouses](https://support.akuity.io/kb/kargo?hsLang=en#warehouses)
    - [Metrics](https://support.akuity.io/kb/kargo?hsLang=en#metrics)
- [Self-hosted Akuity Platform](https://support.akuity.io/kb/self-hosted-akuity-platform?hsLang=en#main-content)

    - [Configuration](https://support.akuity.io/kb/self-hosted-akuity-platform?hsLang=en#configuration)

[![Akuity-Logo-Color-1](https://support.akuity.io/hubfs/Akuity-Logo-Color-1.svg "Akuity-Logo-Color-1")](https://akuity.io/)

Akuity.io Help Center

Copyright © 2025, Akuity Inc.