--- title: "Connect to a Kubernetes cluster" description: "Download a TIR Kubernetes cluster's kubeconfig and use it with kubectl, through the --kubeconfig flag or the KUBECONFIG variable, on any operating system." content_type: "how-to" product: "tir-kubernetes" platform: "TIR" url: "/tir/tir-kubernetes/how-to/connect-to-a-cluster/" topic: ["create-and-connect"] --- # Connect to a Kubernetes cluster Connect to a TIR Kubernetes cluster by downloading its kubeconfig from TIR and giving it to `kubectl`. The kubeconfig points at the cluster's API server, which has a public IP address and listens on port 6443. That means `kubectl` works straight from your own machine, over the internet. ## Before you begin - A cluster in the **Worker Joined** or **Ready** state. The kubeconfig becomes available at **Worker Joined**. - `kubectl` on your own machine. See the [Kubernetes install guide](https://kubernetes.io/docs/tasks/tools/). - A role with the read permission on Kubernetes in the project, which is all you need to download the kubeconfig. See [Roles and permissions](/tir/tir-iam/concepts/roles-and-permissions/). ## Download the kubeconfig 1. In TIR, open your project. In the side menu, under **PRODUCTS**, select **Kubernetes**. 2. Select **Download kubeconfig** in one of two places: - In **Manage Kubernetes Cluster**, open the cluster's **Actions** menu. - Select the cluster's name to open its details page, and use the button at the top. Your browser saves the file as the cluster's name followed by `-kubeconfig.yaml`, with any character other than a letter, a digit, a dot, an underscore, or a hyphen turned into a hyphen. The kubeconfig gives full administrative access to the cluster, so anyone who has the file controls the cluster. Keep it as you would a private key, out of repositories, tickets, and chat. The only way to retire a kubeconfig is to delete its cluster, so a leaked file means deleting the cluster and creating a new one. On Linux and macOS, move the file somewhere predictable and make it readable only by you: ```bash mkdir -p ~/.kube mv ~/Downloads/-kubeconfig.yaml ~/.kube/.yaml chmod 600 ~/.kube/.yaml ``` Replace `` with your cluster's name. The commands that follow use the file at `~/.kube/.yaml`. ## Point kubectl at the cluster `kubectl` reads `~/.kube/config` unless you tell it otherwise. The downloaded kubeconfig works like any other kubeconfig, with the `--kubeconfig` flag or the `KUBECONFIG` variable. To run one command against the cluster, pass the file with the flag: ```bash kubectl --kubeconfig ~/.kube/.yaml get nodes ``` To leave out the flag, set `KUBECONFIG` for the terminal you are in. It lasts until you close the terminal, which makes it the safest choice while you are trying things out. On macOS and Linux: ```bash export KUBECONFIG=~/.kube/.yaml kubectl get nodes ``` In Windows PowerShell: ```powershell $env:KUBECONFIG = "$HOME\.kube\.yaml" kubectl get nodes ``` In the Windows Command Prompt: ```cmd set KUBECONFIG=%USERPROFILE%\.kube\.yaml kubectl get nodes ``` ## Set KUBECONFIG for every terminal To keep the setting in every new terminal on macOS or Linux, add the line to your shell profile. Use `~/.zshrc` for zsh, the macOS default, or `~/.bashrc` for bash. ```bash export KUBECONFIG=$HOME/.kube/.yaml ``` Then reload the profile and check which cluster `kubectl` uses: ```bash source ~/.zshrc # or: source ~/.bashrc kubectl config current-context ``` On Windows, set it for your user account, so every new terminal picks it up: ```powershell [Environment]::SetEnvironmentVariable( "KUBECONFIG", "$HOME\.kube\.yaml", "User" ) ``` Open a new terminal and run `kubectl config current-context` to check it. ## Use several clusters at once `KUBECONFIG` takes a list of files and `kubectl` merges them as it reads them, leaving the files on disk as they are. Separate the files with a colon on macOS and Linux, and with a semicolon on Windows. Here, `` and `` stand for the names of two clusters: ```bash export KUBECONFIG=$HOME/.kube/.yaml:$HOME/.kube/.yaml ``` ```powershell $env:KUBECONFIG = "$HOME\.kube\.yaml;$HOME\.kube\.yaml" ``` List the clusters, and switch to the one you want to work on: ```bash kubectl config get-contexts kubectl config use-context ``` When two files have a context with the same name, the first file in the list wins. To keep both, rename one of the contexts before you merge: ```bash kubectl config rename-context ``` To write the merged result into one file, back up `~/.kube/config` first, because this command replaces it: ```bash KUBECONFIG=$HOME/.kube/config:$HOME/.kube/.yaml \ kubectl config view --flatten > ~/.kube/merged-config mv ~/.kube/merged-config ~/.kube/config chmod 600 ~/.kube/config ``` ## Check the connection Check which file and cluster `kubectl` is using, and that the cluster answers: ```bash echo $KUBECONFIG kubectl config current-context kubectl cluster-info kubectl get nodes -o wide ``` The list includes the control plane nodes as well as the workers, and each node shows `Ready` once it has joined. Your own pods run on the workers only. To check that cluster networking is healthy, list the system pods: ```bash kubectl get pods -n kube-system ``` Cilium, the cluster's network plugin, has a pod on every node. Each one shows `Running` when networking is healthy. ## Deploy a first app To check the cluster end to end, start a web server and reach it from your machine: ```bash kubectl create deployment hello --image=nginx kubectl expose deployment hello --port=80 --type=ClusterIP kubectl get pods -w ``` Once the pod is `Running`, forward a local port to it, then open `http://localhost:8080` in your browser: ```bash kubectl port-forward deployment/hello 8080:80 ``` The nginx welcome page opens. Press Ctrl+C to stop forwarding, and remove the app: ```bash kubectl delete deployment hello kubectl delete service hello ``` You can now run `kubectl` and Helm against the cluster from any terminal. To publish an app on a public address instead of forwarding a port, attach a reserved IP and [expose services with a load balancer](/tir/tir-kubernetes/how-to/expose-services-with-a-load-balancer/). If `kubectl` times out, reaches the wrong cluster, or reports a certificate error, see [Troubleshooting TIR Kubernetes](/tir/tir-kubernetes/troubleshooting/tir-kubernetes/#kubectl-cannot-connect-to-the-cluster).