> For the complete documentation index, see [llms.txt](https://docs.acecloud.ai/knowledge-base/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.acecloud.ai/knowledge-base/kubernetes-hosted/installing-and-setting-up-the-acecloud-kubectl-auth-plugin.md).

# Installing and Setting Up the AceCloud kubectl Auth Plugin

### **Overview**

The **AceCloud kubectl Auth Plugin** enables kubectl to authenticate and connect to your AceCloud Kubernetes clusters.

This article explains how to:

* Install the AceCloud kubectl Auth Plugin.
* Verify the plugin installation.
* Download and configure the cluster KubeConfig.
* Connect kubectl to an AceCloud cluster.
* Use multiple Kubernetes contexts.
* Manage the plugin and its locally cached credentials.

### **Prerequisites**

Before installing and configuring the plugin, ensure that you have:

* **kubectl version 1.20 or later** installed.
* An **AceCloud portal account** with access to at least one Kubernetes cluster.
* A network connection that can reach the **AceCloud portal**.

### **Step 1: Install the AceCloud kubectl Auth Plugin**

#### **Linux or macOS**

Open a terminal and run:

```
curl -fsSL https://raw.githubusercontent.com/AceCloudAI/kubectl-acecloud-auth/main/install.sh | bash
```

#### **Windows**

Open **PowerShell** and run:

```
irm https://raw.githubusercontent.com/AceCloudAI/kubectl-acecloud-auth/main/install.ps1 | iex
```

The installer automatically detects your operating system, downloads the appropriate plugin version, verifies the download, and installs the plugin on your system.

#### **Update the System Path**

After installation, you may see an **ACTION REQUIRED** message.

This message indicates that the plugin was installed in a location that was not previously included in your system PATH. The installer adds the required path automatically.

To apply the change:

1. Open a **new terminal window**.
2. Run the required source command if it was displayed by the installer.

For example:

```
source ~/.bashrc
```

or:

```
source ~/.zshrc
```

The exact command depends on your shell.

If the **ACTION REQUIRED** message is not displayed, no additional configuration is required.

### **Verify the Installation**

Run the following commands:

```
kubectl acecloud_auth Version
```

```
kubectl plugin list
```

The first command displays the installed plugin version.

The second command lists the installed kubectl plugins and should include:

```
kubectl-acecloud_auth
```

If either command returns a **command not found** error, open a new terminal window and run the commands again.

### **Upgrade the AceCloud kubectl Auth Plugin**

Upgrading the AceCloud kubectl Auth Plugin uses the same installation process as the initial setup. Run the installation command for your operating system again to replace the existing plugin with the latest available version.

#### **Linux/macOS**

```
curl -fsSL https://raw.githubusercontent.com/AceCloudAI/kubectl-acecloud-auth/main/install.sh | bash
```

#### **Windows (PowerShell)**

```
irm https://raw.githubusercontent.com/AceCloudAI/kubectl-acecloud-auth/main/install.ps1 | iex
```

After the installation completes, verify the installed version:

```
kubectl acecloud_auth version
```

**Note:** You do not need to uninstall the existing plugin or clear the plugin cache before upgrading. You also do not need to download a new KubeConfig. **Do not download a new KubeConfig as part of the upgrade**, as doing so invalidates the KubeConfig currently in use.

### **Install a Specific Plugin Version**

By default, the installer installs the latest available release. If you need to install a specific version, set the VERSION environment variable before running the installer.

#### **Linux or macOS**

```
VERSION=v1.2.3
curl -fsSL https://raw.githubusercontent.com/AceCloudAI/kubectl-acecloud-auth/main/install.sh | bash
```

#### **Windows**

```
$env:VERSION = "v1.2.3"
irm https://raw.githubusercontent.com/AceCloudAI/kubectl-acecloud-auth/main/install.ps1 | iex
```

Replace v1.2.3 with the required plugin version.

## **Step 2: Download the KubeConfig**

The KubeConfig contains the configuration and authentication information required to connect kubectl to your AceCloud Kubernetes cluster.

1. Log in to the **AceCloud portal**.
2. Open the Kubernetes cluster that you want to connect to.
3. Click **Download KubeConfig**.
4. Save the downloaded KubeConfig file securely.

The downloaded KubeConfig is ready to use and should **not be manually edited**.

**Security Note:** Treat your KubeConfig as a sensitive credential. Keep it private, do not share it with other users, and do not commit it to a code repository.

#### **Do Not Share Personal KubeConfig Files**

Do not use the same personal KubeConfig across multiple:

* Users
* Machines
* Scripts
* Automation or CI/CD pipelines

The authentication credential is automatically renewed. When a credential is renewed, the previous credential becomes invalid. If multiple clients use the same KubeConfig, credential refreshes can conflict and cause authentication failures.

Each user should use their own KubeConfig.

For automation, CI/CD, or shared service use cases, use a dedicated **Kubernetes service account** instead.

## **Step 3: Configure kubectl to Use the Cluster**

You can configure kubectl to use the downloaded KubeConfig in several ways.

### **Option A: Use the KubeConfig for a Single Command**

Specify the KubeConfig using the --kubeconfig option:

```
kubectl --kubeconfig /path/to/your-kubeconfig.yaml get pods
```

This uses the specified KubeConfig only for that command.

### **Option B: Set the KubeConfig for the Current Session**

Set the KUBECONFIG environment variable:

```
export KUBECONFIG=/path/to/your-kubeconfig.yaml
```

You can then run kubectl commands normally:

```
kubectl get pods
```

To make this configuration persistent, add the export command to your shell profile.

### **Option C: Merge with an Existing KubeConfig**

If you manage multiple Kubernetes clusters, you can merge the AceCloud KubeConfig with your existing KubeConfig and switch between clusters using Kubernetes contexts.

#### **1. Back Up Your Existing KubeConfig**

```
cp ~/.kube/config ~/.kube/config.bak
```

#### **2. Merge the KubeConfigs**

```
KUBECONFIG=~/.kube/config:/path/to/your-kubeconfig.yaml \
kubectl config view --flatten > /tmp/merged-config
```

#### **3. Replace the Existing Configuration**

```
mv /tmp/merged-config ~/.kube/config
```

#### **4. View Available Contexts**

```
kubectl config get-contexts
```

#### **5. Switch to the AceCloud Cluster**

```
kubectl config use-context
```

After switching to the required context, you can use kubectl commands normally.

## **Verify the Connection**

After configuring the KubeConfig, run a Kubernetes command to verify that you can access the cluster:

```
kubectl get pods
```

If the command returns the expected cluster resources, your kubectl configuration is working correctly.

The AceCloud authentication plugin automatically maintains your authentication credential in the background.

## **Useful Commands**

| **Command**                        | **Description**                                                                                                               |
| ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| kubectl acecloud\_auth version     | Displays the installed AceCloud kubectl Auth Plugin version.                                                                  |
| kubectl acecloud\_auth help        | Displays plugin usage information.                                                                                            |
| kubectl-acecloud\_auth clear-cache | Clears locally cached credentials. Use this when authentication appears to be stuck or the cached credential may be outdated. |

## **Remove the AceCloud kubectl Auth Plugin**

To remove the installed plugin, run:

```
rm "$(command -v kubectl-acecloud_auth)"
```

To remove the locally stored AceCloud plugin data and cache, run:

```
rm -rf ~/.kube/acecloud
```

**Note:** Removing the plugin does not remove the Kubernetes cluster or resources associated with your AceCloud account.

### **Related Article**

For authentication-related errors and their resolutions, see [**Troubleshooting the AceCloud kubectl Auth Plugin**](https://docs.acecloud.ai/knowledge-base/kubernetes-hosted/troubleshooting-the-acecloud-kubectl-auth-plugin).