--- title: "Connecting to a cluster with kubeconfig" slug: "kubernetes-cluster-access" source: "https://app.cloudpe.com/help/kubernetes-cluster-access" updated: "2026-08-30T19:03:44.293Z" --- # Connecting to a cluster with kubeconfig ## 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 1. Open **Kubernetes** in the dashboard sidebar to reach **Kubernetes Clusters**. ![](/kb/kubernetes-paas/k8s-cluster-provisioning-01-list.png) 2. 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. ![](/kb/kubernetes-paas/k8s-cluster-provisioning-03-detail.png) 3. Click **Kubeconfig**. CloudPE issues a new client certificate and returns the composed kubeconfig YAML for download. ![](/kb/kubernetes-paas/kubernetes-cluster-access-01-kubeconfig.png) 4. Save the file and point `kubectl` at it: ```bash 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. 5. 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. ![](/kb/kubernetes-paas/kubernetes-cluster-access-02-security-tab.png) 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 `` with the CMP cluster ID shown in the dashboard URL. List your clusters (`k8s:read`): ```bash curl -X GET https://app.cloudpe.com/api/v1/k8s/ \ -H "Authorization: Bearer " ``` Fetch one cluster, to confirm its status before downloading (`k8s:read`): ```bash curl -X GET https://app.cloudpe.com/api/v1/k8s/ \ -H "Authorization: Bearer " ``` Download the kubeconfig (`k8s:kubeconfig`): ```bash curl -X GET https://app.cloudpe.com/api/v1/k8s//kubeconfig \ -H "Authorization: Bearer " \ -o kubeconfig.yaml ``` Rotate the cluster CA (`k8s:rotate_ca`) and review past rotations (`k8s:read`): ```bash curl -X POST https://app.cloudpe.com/api/v1/k8s//rotate-ca \ -H "Authorization: Bearer " curl -X GET https://app.cloudpe.com/api/v1/k8s//ca-rotations \ -H "Authorization: Bearer " ``` ## 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. ## Related - [Creating a Kubernetes cluster](/help/k8s-cluster-provisioning) - [Deploying apps on the PaaS platform](/help/paas-app-deployments)