Connecting to a cluster with kubeconfig

Last updated 30 Aug 2026

Overview

Every Kubernetes cluster on CloudPE exposes an admin kubeconfig that lets kubectl, Helm and CI tooling talk to the cluster's API server. CloudPE composes the file for you: it fetches the cluster CA, generates a key pair and CSR locally, has the cluster's certificate authority sign a client certificate, and returns a ready-to-use kubeconfig YAML with the cluster, user and context blocks already filled in.

A fresh client certificate is issued on every download — there is no way to re-fetch a previously issued one, so treat each downloaded file as a distinct admin credential.

This article covers downloading the kubeconfig from the dashboard, fetching it over the API, and what changes after a CA rotation.

Before you start

The cluster must exist and be finished with its current operation. Kubeconfig download is available once the cluster reaches CREATE_COMPLETE or UPDATE_COMPLETE — a cluster still provisioning has no API address yet.
You need the k8s:read permission to see clusters under Kubernetes, and k8s:kubeconfig to download the file. Rotating the CA additionally needs k8s:rotate_ca.
The cluster's project must be fully provisioned, and Kubernetes must be enabled in the cluster's region.
Install kubectl locally before you start, and decide where the file will live (~/.kube/config, or a separate path used with --kubeconfig).
Network reachability is your responsibility: the kubeconfig points at the cluster's API address. If the cluster was created without floating IPs for API access, you must reach that address from inside the network (for example over VPN).

Steps

Open Kubernetes in the dashboard sidebar to reach Kubernetes Clusters.
Select the cluster you want to connect to. The detail page opens on the Overview tab, which shows the cluster status, API endpoint, network and node addresses. If the status strip still shows an operation in progress, use Refresh and wait for it to complete.
Click Kubeconfig. CloudPE issues a new client certificate and returns the composed kubeconfig YAML for download.
Save the file and point kubectl at it:
```
export KUBECONFIG=~/Downloads/kubeconfig.yaml
kubectl get nodes
```
To make it permanent, merge or copy it to ~/.kube/config. The node list should match the nodes shown on the Nodes tab.
To review or roll the cluster's certificate authority, open the Security tab. Rotate CA issues a new cluster CA; the tab also lists previous rotations so you can confirm when the last one ran.

After a rotation, any kubeconfig downloaded before it stops working — download a fresh one and redistribute it to your users and CI systems.

API

All calls use a Bearer token. Replace <cluster-id> with the CMP cluster ID shown in the dashboard URL.

List your clusters (k8s:read):

curl -X GET https://app.cloudpe.com/api/v1/k8s/ \
  -H "Authorization: Bearer <API_KEY>"

Fetch one cluster, to confirm its status before downloading (k8s:read):

curl -X GET https://app.cloudpe.com/api/v1/k8s/<cluster-id> \
  -H "Authorization: Bearer <API_KEY>"

Download the kubeconfig (k8s:kubeconfig):

curl -X GET https://app.cloudpe.com/api/v1/k8s/<cluster-id>/kubeconfig \
  -H "Authorization: Bearer <API_KEY>" \
  -o kubeconfig.yaml

Rotate the cluster CA (k8s:rotate_ca) and review past rotations (k8s:read):

curl -X POST https://app.cloudpe.com/api/v1/k8s/<cluster-id>/rotate-ca \
  -H "Authorization: Bearer <API_KEY>"

curl -X GET https://app.cloudpe.com/api/v1/k8s/<cluster-id>/ca-rotations \
  -H "Authorization: Bearer <API_KEY>"

Limits & billing

Downloading a kubeconfig and rotating the CA are control-plane actions and are not billed separately.
Cluster charges are usage-based and metered hourly for the control plane and worker nodes, with Docker volumes and the API floating IP billed as their own line items. The per-hour figure shown on a cluster's usage row is compute-only; the full breakdown, including storage and floating IP, is on the cluster's Billing tab.
Access is org-scoped: a kubeconfig can only be requested for clusters in an organization where you hold k8s:kubeconfig.

Troubleshooting

Error	What it means	What to do
`Kubeconfig not available for cluster in {…} state`	The cluster has not completed its current lifecycle operation.	Wait until the cluster reaches `CREATE_COMPLETE` or `UPDATE_COMPLETE`, then use Refresh and retry.
`Cluster is not yet provisioned`	The cluster record exists but the underlying cluster has not been created yet.	Wait for provisioning to finish; check the status strip on the cluster detail page.
`Kubeconfig unavailable — the underlying cluster could not be located. Contact support.`	The cluster could not be resolved on the orchestration side.	Open a support ticket with the cluster name and region.
`Cloud provider authentication error`	The platform's credentials for the region failed while fetching or signing certificates.	Retry the download. If it persists, contact support.
`Unable to connect to Kubernetes service in this region. Please try again later or contact support. ({…})`	The regional Kubernetes service is unreachable.	Retry after a few minutes, then contact support with the cluster ID.
`Kubernetes is not enabled for this region`	The region does not offer managed Kubernetes.	Use a region where Kubernetes is available.
`Cluster must be CREATE_COMPLETE to rotate CA (current status: {…})`	A CA rotation was requested while another operation was running.	Wait for the cluster to return to `CREATE_COMPLETE` and try Rotate CA again.
`Failed to enqueue CA rotation. Please retry.`	The rotation request could not be queued.	Retry the rotation from the Security tab.

FAQ

Can I download the same kubeconfig twice? No. Each download generates a new key pair and a newly signed client certificate. Older downloaded files keep working until the CA is rotated, so distribute copies deliberately rather than re-downloading for every user.

Does rotating the CA invalidate existing kubeconfigs? Yes. After Rotate CA, download a fresh kubeconfig and update anywhere the old one is stored, including CI/CD secrets.

The file downloads but kubectl times out. Why? The kubeconfig points at the cluster's API address. If that address is not routable from your machine — for example a cluster created without floating IPs for API access — connect from inside the cluster's network or over VPN.

Can I give the kubeconfig to a teammate instead of granting them access? It is an admin credential for the cluster, so prefer granting k8s:kubeconfig in the organization and letting each person download their own, which keeps the audit trail per user.

Where do I see which nodes should appear in kubectl get nodes? The Nodes tab on the cluster detail page lists the cluster's nodes and their addresses.

Did this guide answer your question?If you need customized assistance with your deployment, reach out to our team.

Contact Support