#Access a Cluster with KubeConfig

#Introduction

This topic explains the currently supported ways to use KubeConfig to access a cluster in . Use it when you need local access from ACP CLI (ac), kubectl, helm, client-go, or similar Kubernetes clients.

A KubeConfig file is a YAML client configuration file. It is not a Kubernetes resource. A KubeConfig file typically defines the target cluster endpoint, the client credential, and the context that combines them.

ACP CLI (ac) uses standard kubeconfig and provides a kubectl-like experience. It is compatible with kubectl workflows and also adds ACP-specific context, cluster, and session operations. If you already use ac login, ACP CLI can configure kubeconfig and create contexts automatically. This topic focuses on the KubeConfig access paths themselves, including downloaded KubeConfig files and manually assembled token-based KubeConfig files.

#Scenarios

This topic applies to the following scenarios:

• A cluster administrator needs a ready-to-use KubeConfig for cluster administration, troubleshooting, or inspection.
• A developer or project user needs a KubeConfig that matches their own ACP identity and RBAC permissions.
• A pipeline or connector needs an independent credential that is separate from a personal day-to-day account.

#Choose the Access Path

Use the following table to choose the appropriate access path:

If you need stricter identity isolation or shorter lifecycle control, use a token-based KubeConfig instead of long-term reuse of the downloaded file.

#Prerequisites

Before you begin, ensure the following conditions are met:

• You can sign in to and access the target cluster.
• You have ACP CLI (ac) or kubectl installed on the local machine where you will use the KubeConfig file.
• If you want to use a token-based KubeConfig, you can create an ACP API token from Profile > API Tokens. For details, see Introduction.
• If you want to use KubeConfig for a pipeline or connector, prepare a dedicated account and grant only the required permissions before creating its token.

#Procedure

#Download and Use the Platform-Provided KubeConfig

Use this path when you need direct cluster access from the platform-provided KubeConfig file.

export KUBECONFIG="$HOME/.kube/<cluster-name>.yaml"
kubectl config get-contexts
kubectl config current-context
ac config current-context

kubectl get nodes
kubectl get pods -A
ac get nodes
ac get pods -A

Use this downloaded file directly when you need cluster administration. You can also use it as a template for a token-based KubeConfig that works with both ac and kubectl.

#Build a Token-Based KubeConfig with Your Own ACP API Token

Use this path when you want the KubeConfig permissions to match a specific ACP user or automation account.

This path does not elevate permissions. The KubeConfig file only carries the connection and authentication settings. The effective access boundary still depends on the token owner and that identity's RBAC assignments.

https://<platform-access-address>/kubernetes/<cluster-name>

apiVersion: v1
kind: Config
clusters:
  - name: <cluster-name>
    cluster:
      server: https://<platform-access-address>/kubernetes/<cluster-name>
      certificate-authority-data: <base64-encoded-ca-data>
users:
  - name: <user-name>
    user:
      token: <acp-api-token>
contexts:
  - name: <context-name>
    context:
      cluster: <cluster-name>
      user: <user-name>
      namespace: <namespace>
current-context: <context-name>

export KUBECONFIG="$HOME/.kube/<user-or-automation>.yaml"
kubectl auth can-i get pods -n <namespace>
kubectl get pods -n <namespace>
ac config current-context
ac get pods -n <namespace>

#Use a Dedicated Account for Pipeline or Connector Access

For pipeline or connector access, use a dedicated account instead of a personal user account:

1. Create a dedicated account for the pipeline or connector.
2. Grant only the required project-level or tenant-level permissions to that account.
3. Create an ACP API token for that account.
4. Build a token-based KubeConfig by using that token.
5. Store the token or KubeConfig file in the secret management system of the automation platform.
6. Rotate the credential by creating a new token, updating the secret, and revoking the old token.

This pattern provides an independent credential for automation, but it is not a native project-level KubeConfig object in ACP.

#Lifecycle and Revocation

The lifetime behavior depends on which access path you use:

If you need a shorter validity period or easier revocation, prefer the token-based path.

#Verification

After you prepare the KubeConfig file, perform the following checks:

1. Run kubectl config get-contexts and confirm that the expected context exists.
2. Run a read-only command such as kubectl get pods -A or kubectl get pods -n <namespace> and confirm that the response matches the intended access scope.
3. For a token-based KubeConfig, run kubectl auth can-i <verb> <resource> -n <namespace> and confirm that the result matches the token owner's role.
4. If you use ACP CLI, run ac config current-context or ac namespace and confirm that the active context matches the intended cluster and namespace.
5. If you use ACP CLI, run ac get pods -n <namespace> or ac get nodes and confirm that the response matches the intended access scope.

#Next Steps

• For ACP API token management, see Introduction.
• For ACP CLI basics, see Getting Started with ACP CLI.
• For ACP CLI context and session management, see Managing CLI Profiles.
• For ACP CLI and kubectl compatibility, see Usage of ac and kubectl Commands.