---
title: "Using kubectl to Manage Kubernetes Clusters | Hostman Docs"
description: "Learn how to install kubectl on Linux, macOS, and Windows, configure kubeconfig access, manage Kubernetes clusters, and use essential commands for pods, services, and troubleshooting."
---

> For the complete documentation index for AI agents, see [llms.txt](https://hostman.com/llms.txt).

`kubectl` is a command-line utility for working with [Kubernetes cluster](https://hostman.com/products/kubernetes/) entities. It allows you to manage cluster resources, deploy applications, view logs, and perform other administrative tasks.

> [!NOTE]
> Please note that the minor version of `kubectl` (the second digit in the version) may differ from the cluster version by +/- 1. Using newer or older versions may lead to compatibility issues. The instructions specify certain versions as examples, but you can replace them with the versions you need.

## Installing kubectl on Linux

There are two methods for installing `kubectl` on Linux.

### Installing with curl

1.  Download the `kubectl` binary:
    

```shell
curl -LO "https://storage.googleapis.com/kubernetes-release/release/v1.30.2/bin/linux/amd64/kubectl"
```

2.  Check the integrity of the file: 
    

```shell
echo "$(curl -sL https://dl.k8s.io/release/v1.30.2/bin/linux/amd64/kubectl.sha256) kubectl" | sha256sum --check
```

3.  Install `kubectl`: 
    

```shell
sudo install -o root -g root -m 0755 kubectl /usr/local/bin/kubectl
```

### Installing with apt

1.  Update the package list:
    

```shell
sudo apt update
```

2.  Install the required packages: 
    

```shell
sudo apt install -y apt-transport-https ca-certificates curl gnupg
```

3.  Add the key for the Kubernetes repository and set the correct permissions for the key: 
    

```shell
curl -fsSL https://pkgs.k8s.io/core:/stable:/v1.30/deb/Release.key | sudo gpg --dearmor -o /etc/apt/keyrings/kubernetes-apt-keyring.gpg && sudo chmod 644 /etc/apt/keyrings/kubernetes-apt-keyring.gpg
```

4.  Add the Kubernetes repository to the APT sources list and set the correct permissions on the sources list file: 
    

```shell
echo 'deb [signed-by=/etc/apt/keyrings/kubernetes-apt-keyring.gpg] https://pkgs.k8s.io/core:/stable:/v1.30/deb/ /' | sudo tee /etc/apt/sources.list.d/kubernetes.list && sudo chmod 644 /etc/apt/sources.list.d/kubernetes.list
```

5.  Update the package list again: 
    

```shell
sudo apt update
```

6.  Install `kubectl`: 
    

```shell
sudo apt install -y kubectl
```

## Installing on macOS

For macOS, you can install `kubectl` manually or with Homebrew.

### Installing with Homebrew

Install `kubectl`: 

```shell
brew install kubectl@1.30
```

Or install the entire Kubernetes CLI toolchain:

```shell
brew install kubernetes-cli@1.30
```

> [!NOTE]
> The versions available for installation via Homebrew can be found on the [utility's official page](https://formulae.brew.sh/formula/kubernetes-cli).

### Manual Installation

**For Intel**

1.  Download `kubectl` for Intel: 
    

```shell
curl -LO "https://dl.k8s.io/release/v1.30.2/bin/darwin/amd64/kubectl"
```

2.  Check the integrity of the file: 
    

```shell
echo "$(curl -sL https://dl.k8s.io/release/v1.30.2/bin/darwin/amd64/kubectl.sha256) kubectl" | sha256sum --check
```

**For Apple Silicon**

1.  Download `kubectl` for Apple Silicon: 
    

```shell
curl -LO "https://dl.k8s.io/release/v1.30.2/bin/darwin/arm64/kubectl"
```

2.  Check the integrity of the file: 
    

```shell
echo "$(curl -sL https://dl.k8s.io/release/v1.30.2/bin/darwin/arm64/kubectl.sha256) kubectl" | sha256sum --check
```

3.  Make the file executable, set the permissions to `644`, move it to the `/usr/local/bin` directory and set the owner to `root`: 
    

```shell
chmod +x ./kubectl && chmod 644 ./kubectl && sudo mv ./kubectl /usr/local/bin/kubectl && sudo chown root: /usr/local/bin/kubectl
```

## Installing on Windows

You can install `kubectl` on Windows manually or with Chocolatey.

### Installation with Chocolatey

Install `kubectl` by running: 

```shell
choco install kubernetes-cli --version=1.30.2
```

### Manual Installation

1.  Open PowerShell and run:
    

```shell
mkdir kubectl
cd .\kubectl\
curl.exe -LO "https://dl.k8s.io/release/v1.30.2/bin/windows/amd64/kubectl.exe"
```

2.  Add the `kubectl` directory path to your `PATH` by running the following script in PowerShell:
    

```shell
$destination="$env:USERPROFILE\kubectl"
$currentPath = [System.Environment]::GetEnvironmentVariable("Path", [System.EnvironmentVariableTarget]::User)

if ($currentPath -notlike "*$destination*") {
[System.Environment]::SetEnvironmentVariable("Path", "$currentPath;$destination", [System.EnvironmentVariableTarget]::User)
}
```

Or add the path manually:

-   -   Right-click on **This PC**.
    -   Select **Properties**.
    -   Go to **About**.
    -   Click on **Advanced system settings**.
    -   Navigate to the **Advanced** tab.
    -   Click on **Environment Variables**.
    -   In the **System variables** section, find the **Path** variable and add the path to the `kubectl` directory.

3.  Restart PowerShell for the changes to take effect.
    

> [!NOTE]
> Docker Desktop for Windows adds its version of `kubectl` to the `PATH`. If you have Docker Desktop installed, you may need to place the `PATH` entry for `kubectl` before the one added by the Docker Desktop installer, or remove the version of `kubectl` installed by Docker Desktop.

`kubectl` is now installed on your machine. You can verify the installation by running the command:

```shell
kubectl version
```

## Configuring Access to the Kubernetes Cluster

To connect to the cluster, you will need the `kubeconfig` configuration file.

### Obtaining the kubeconfig Configuration File

The `config.yaml` file is used by `kubectl` to determine which cluster to connect to and what credentials to use. It contains information about clusters, users, and contexts, allowing for easy switching between different [Kubernetes](https://hostman.com/products/kubernetes/) configurations.

Since the `config.yaml` file contains important credentials, it should be stored in a location that is not accessible to unauthorized persons to prevent unauthorized access to the cluster. If an outsider gains access to this file, they can manage the cluster and its resources.

You can download the configuration file from the cluster's **Dashboard**.

![6c07bc59 Ed27 4ca2 935a 7f27c707b464](https://content.hostman.com/assets/f7811ed4-afbb-4b63-8156-98e339aa687b.png?width=1554&height=1006)

### Place kubeconfig in Your Home Directory

Once you have the `config.yaml` file, you need to place it in the correct directory so `kubectl` can use it.

#### macOS and Linux

1.  Create a `.kube` directory in your home directory if it doesn't exist yet:
    

```shell
mkdir -p ~/.kube
```

2.  Copy the `config.yaml` file to this directory and rename it to `config`:
    

```shell
cp ~/Downloads/config.yaml ~/.kube/config
```

After completing these steps, `kubectl` will automatically use the configuration from the `~/.kube/config` file.

#### Windows

1.  Open PowerShell.
    
2.  Create a `.kube` directory in your home directory if it doesn't already exist:
    

```shell
mkdir $env:USERPROFILE\.kube
```

3.  Copy the `config.yaml` file to this directory and rename it to `config`:
    

```shell
copy <path_to_config.yaml> $env:USERPROFILE\.kube\config
```

4.  Run PowerShell as administrator and execute:
    

```shell
[Environment]::SetEnvironmentVariable("KUBECONFIG", $HOME + "\.kube\config", [EnvironmentVariableTarget]::Machine)
```

After completing these steps, `kubectl` will automatically use the configuration from the `$env:USERPROFILE\.kube\config` file.

### Using the KUBECONFIG Environment Variable

If you need to use multiple configuration files or place `config.yaml` in a different location, you can use the `KUBECONFIG` environment variable.

#### macOS and Linux

1.  Open the terminal.
    
2.  Set the `KUBECONFIG` environment variable:
    

```shell
export KUBECONFIG=<path-to-your-kubeconfig>
```

To make these settings persist across system reboots, run the following code changing `~/.bashrc` to `~/.zshrc` (for MacOS) or `~/.profile` if necessary:

```shell
echo "export KUBECONFIG=<path-to-your-kubeconfig>" >> ~/.bashrc
```

#### Windows

1.  Open PowerShell.
    
2.  Set the `KUBECONFIG` environment variable:
    

```shell
$env:KUBECONFIG = "<path-to-your-kubeconfig>"
```

### Using multiple configuration files

You can specify multiple kubeconfig files by separating their paths with colons (on macOS and Linux) or semicolons (on Windows):

#### Windows

```shell
$env:KUBECONFIG="<path-to-your-first-kubeconfig>;<path-to-your-second-kubeconfig>"
```

#### macOS and Linux

```shell
export KUBECONFIG=<path-to-your-first-kubeconfig>:<path-to-your-second-kubeconfig>
```

## Setting Up a Connection to the Kubernetes Cluster

Once you have access set up, you need to make sure that `kubectl` can connect to the cluster. To do this, run the following command:

```shell
kubectl cluster-info
```

This command will output information about your cluster, including the addresses of the API and other components. If the command is successful, then `kubectl` is connected to the cluster.

### Checking a Context

Contexts allow you to switch between different clusters and credentials. Each context is a combination of clusters, users, and namespaces.

To see a list of available contexts and which one is currently active, use the command:

```shell
kubectl config get-contexts
```

This command will output a table of available contexts and indicate which one is currently active.

![Image3 (1)](https://content.hostman.com/assets/3bd54c38-8778-4139-904e-eea8f75fabae.png?width=810&height=117)

If you have multiple clusters configured and want to switch to a different context, use the following command:

```shell
kubectl config use-context <context-name>
```

Replace `<context-name>` with the context name that you got from the previous command. After running this command, `kubectl` will use the new context for all subsequent commands.

## Configuring Command Completion

Command completion helps you type commands faster and reduce errors by automatically suggesting possible options as you type. This is especially useful for long, complex `kubectl` commands.

### Installing bash-completion

1.  Install the `bash-completion` package.

**Ubuntu/Debian:**

```shell
sudo apt install bash-completion
```

**CentOS/RHEL:**

```shell
sudo yum install bash-completion
```

**macOS (Homebrew):**

```shell
brew install bash-completion
```

2.  Enable autocompletion for the current session.

**bash (Linux):**

```shell
source <(kubectl completion bash)
```

**zsh (macOS and Linux):**

```shell
source <(kubectl completion zsh)
```

3.  To always keep autocompletion enabled, run the command:

**bash (Linux):**

```shell
echo "source <(kubectl completion bash)" >> ~/.bashrc
```

**zsh (macOS and Linux):**

```shell
echo "source <(kubectl completion zsh)" >> ~/.zshrc
```

## Basic kubectl Commands

### Getting Cluster Information

To get general information about your cluster, including component addresses, use the command:

```shell
kubectl cluster-info
```

### Viewing Pods

To list all pods in the current namespace, use the command:

```shell
kubectl get pods
```

If you want to see pods in a specific namespace, add the `-n` option:

```shell
kubectl get pods -n <namespace>
```

### Viewing Services

To see all services in the current namespace, run the command:

```shell
kubectl get services
```

You can also specify a namespace:

```shell
kubectl get services -n <namespace>
```

### Viewing Configuration

To see the current configuration and active context:

```shell
kubectl config view
```

### Resources Description

To get detailed information about any resource, such as a pod or service:

```shell
kubectl describe <resource-type> <resource-name>
```

For example, to get information about a pod:

```shell
kubectl describe pod <pod-name>
```

### Deleting Resources

To delete a resource, such as a pod or service:

```shell
kubectl delete <resource-type> <resource-name>
```

For example, to delete a pod: 

```shell
kubectl delete pod <pod-name>
```