Connect to a cluster with kubectl

kubectl connects to your cluster with the cluster’s kubeconfig, a file you download from the cluster’s Cluster Details tab. Once kubectl uses it, every kubectl command runs against your cluster. The same tab has the token that signs you in to the Kubernetes Dashboard.

Before you begin

• Your cluster reads Running. See Create a cluster.
• kubectl is installed on your computer. See Install Tools on the Kubernetes site.
• A security group attached to the cluster allows inbound TCP port 6443 from where you connect, and your network lets you reach that port. The kubeconfig points kubectl at the master node’s public IP on TCP port 6443. See Manage a cluster’s security groups.

Download the kubeconfig

1. In MyAccount, under Compute, click Kubernetes, and click your cluster’s name.
2. On the Cluster Details tab, in the Kubeconfig row, click the download button. The file is saved as <cluster-name>-kubeconfig.yaml, where <cluster-name> is your cluster’s name.
3. Move the file to a folder of its own, such as ~/.kube/, and use that path. On Windows, use $HOME\.kube\.

The kubeconfig signs in as the cluster’s administrator, so anyone who has the file has full control of the cluster. Keep it as safe as a password, and do not commit it to a code repository. If the kubeconfig leaks, contact support to replace the credentials.

Point kubectl at the kubeconfig

For a single command, pass the file with --kubeconfig:

kubectl --kubeconfig="$HOME/.kube/<cluster-name>-kubeconfig.yaml" get nodes

To use the file for every command, set the KUBECONFIG environment variable to its full path.

Linux and macOS

For the current terminal session, run:

export KUBECONFIG="$HOME/.kube/<cluster-name>-kubeconfig.yaml"

To keep it for every new session, add the line to your shell’s startup file, and reload it. For Zsh, the default shell on macOS, run:

echo 'export KUBECONFIG="$HOME/.kube/<cluster-name>-kubeconfig.yaml"' >> ~/.zshrc
source ~/.zshrc

For Bash, the default shell on most Linux systems, run:

echo 'export KUBECONFIG="$HOME/.kube/<cluster-name>-kubeconfig.yaml"' >> ~/.bashrc
source ~/.bashrc

Windows

For the current PowerShell session, run:

$env:KUBECONFIG = "$HOME\.kube\<cluster-name>-kubeconfig.yaml"

To keep it for every new session, run:

[System.Environment]::SetEnvironmentVariable("KUBECONFIG", "$HOME\.kube\<cluster-name>-kubeconfig.yaml", [System.EnvironmentVariableTarget]::User)

Open a new PowerShell window for the change to take effect.

Check the connection

Run:

kubectl get nodes

kubectl lists the cluster’s nodes, one row each, like this:

NAME          STATUS   ROLES     AGE   VERSION
<node-name>   Ready    <roles>   5m    v<version>

A node that reads Ready can run pods.

• If the command times out, see kubectl times out on port 6443.
• If it reports x509: certificate has expired or is not yet valid, see kubectl says x509: certificate has expired or is not yet valid.

(Optional) Open the Kubernetes Dashboard

The cluster comes with the Kubernetes Dashboard installed, a web view of what runs in it.

1. Start a local proxy to the cluster, and leave it running while you use the dashboard. With KUBECONFIG set, run:

   kubectl proxy

   Without it, add --kubeconfig="$HOME/.kube/<cluster-name>-kubeconfig.yaml" to the command.

2. In a browser, open:

   http://localhost:8001/api/v1/namespaces/kubernetes-dashboard/services/https:kubernetes-dashboard:/proxy/

3. On the cluster’s Cluster Details tab, next to Kubeconfig Token, click View Token, and copy the token. View Token is available while the cluster reads Running.

4. On the dashboard’s sign-in page, paste the token and sign in.

The Kubernetes Dashboard opens on your cluster. To stop the proxy, press Ctrl+C in its terminal.

With kubectl connected, you can run commands against your cluster. The cluster’s certificate renews one year after the cluster is created. After each renewal, download the kubeconfig again so kubectl has the new certificate; see Renew the cluster certificate. Next, deploy and expose an application; see Expose a service with a load balancer.