> 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/kubectl-authentication-plugin-overview.md). # Kubectl Authentication Plugin Overview ## **Overview** The **AceCloud kubectl Authentication Plugin** enables secure authentication between kubectl and your AceCloud Kubernetes clusters. The plugin automatically obtains and refreshes the credentials required to authenticate kubectl commands with the cluster. Once the plugin is installed and the cluster KubeConfig is downloaded from the AceCloud portal, authentication is handled automatically in the background. ## **Why You Need the AceCloud Authentication Plugin** Access to your AceCloud Kubernetes cluster uses a **short-lived access credential** that expires approximately every **15 minutes** by design. Without the authentication plugin, you would need to manually re-authenticate and update your KubeConfig frequently to continue using kubectl. The **AceCloud kubectl Authentication Plugin** automates this process. Once installed, it runs automatically when required and renews the access credential before it expires, as long as your KubeConfig remains valid. Your KubeConfig itself has a maximum validity period of **30 days**. Once this period expires, you must download a new KubeConfig from the AceCloud portal. This provides: * **Continuous kubectl access** without repeated manual authentication. * **Reduced security risk** by avoiding long-lived access credentials on your machine. * **Automatic application of updated permissions**, without requiring a new KubeConfig for routine permission changes. ## **How the Authentication Flow Works** The authentication process involves the following components: 1. **kubectl** initiates a request using the configured KubeConfig. 2. The **AceCloud authentication plugin** is invoked by kubectl. 3. The plugin communicates with the **AceCloud portal**. 4. The AceCloud portal authenticates the request through **AceCloud IAM**. 5. AceCloud IAM provides the required authentication credential. 6. The plugin returns the valid credential to kubectl. 7. kubectl uses the credential to authenticate with the **Kubernetes API server**. ## **How It Fits into Your Workflow** You interact with the authentication plugin primarily during two activities: 1. **Installing the plugin** on your system. 2. **Downloading the KubeConfig** for each AceCloud Kubernetes cluster you want to access. After these steps, use kubectl normally. For example: ``` kubectl get pods kubectl get nodes kubectl apply -f my-app.yaml ``` When you run a command, kubectl invokes the authentication plugin, which ensures that a valid access credential is available before the request is sent to the Kubernetes API server. No separate login or manual credential refresh is required. ## **How Authentication Works** The KubeConfig does not contain a permanent credential that directly authenticates with the Kubernetes cluster. Instead, it contains a **refresh token**. The refresh token is exchanged through the AceCloud portal for a separate **short-lived access token**. The access token is the credential used to authenticate with the Kubernetes cluster. The plugin automatically renews this credential as required. ### **Authentication Flow** **KubeConfig → Refresh Token → AceCloud Portal → Access Token → Kubernetes API Server** This process occurs automatically whenever required, without requiring the user to manually handle passwords or access tokens. ## **KubeConfig Lifecycle** The KubeConfig downloaded from the AceCloud portal remains valid for a limited period. According to the current configuration: * The KubeConfig is valid for up to **30 days**. * If unused, it expires after **7 days**. * An administrator can also revoke the user's access. When the KubeConfig expires or the user's access is revoked, the authentication plugin can no longer refresh the access token. In this situation, kubectl displays a message instructing you to download a fresh KubeConfig from the AceCloud portal. **Note:** KubeConfig expiration is expected behavior and does not indicate a problem with the authentication plugin. ## **Benefits of Automatic Credential Management** ### **Reduced Credential Exposure** The access credential used to authenticate with the Kubernetes cluster is short-lived and refreshed regularly. This reduces the period during which an individual credential remains useful if it is exposed. ### **Automatic Credential Rotation** Credentials are automatically rotated as part of the authentication process. Users do not need to manually generate or replace credentials during normal operation. ### **Automatic Permission Updates** Changes to a user's permissions in the AceCloud portal are reflected when the plugin obtains a new access credential. As a result, permission changes typically take effect within minutes without requiring the user to download a new KubeConfig. ## **What the Plugin Does and Does Not Do** | **Function** | **Description** | | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | **Password management** | The plugin does not request or store your AceCloud password. Authentication is handled through the AceCloud portal. | | **KubeConfig modification** | The plugin does not modify the downloaded KubeConfig. The KubeConfig should not require manual editing. | | **Credential management** | The plugin automatically obtains and refreshes the credentials required by kubectl. | | **Portal communication** | The plugin communicates with the AceCloud portal over a secure connection to maintain authentication. | | **Multiple cloud providers** | The plugin can operate alongside authentication plugins for other Kubernetes platforms. Each platform can use its own plugin and Kubernetes context. | ## **Security** The AceCloud kubectl Authentication Plugin is designed to minimize exposure of Kubernetes access credentials. Key security measures include: * Communication between the plugin and the AceCloud portal is encrypted using **HTTPS**. * Credentials obtained by the plugin are designed for one-time use and are replaced during subsequent authentication operations. * Credentials stored locally by the plugin use restricted file permissions so that they are accessible only to the local user account. **Security Note:** Always protect your KubeConfig file and do not share a personal KubeConfig with other users, scripts, or systems. For automation and shared access scenarios, use a dedicated Kubernetes service account. ## **Important Considerations** * Install the authentication plugin before connecting kubectl to an AceCloud Kubernetes cluster. * Download the KubeConfig from the AceCloud portal for each cluster you need to access. * Do not manually modify the downloaded KubeConfig. * Do not share a personal KubeConfig between users or automation systems. * If your credential expires or your access is revoked, download a fresh KubeConfig from the AceCloud portal. * Use a dedicated service account for CI/CD pipelines and other automation use cases. ## **Related Articles** * [**Installing and Setting Up the AceCloud kubectl Auth Plugin**](https://docs.acecloud.ai/knowledge-base/kubernetes-hosted/installing-and-setting-up-the-acecloud-kubectl-auth-plugin) – Install and configure the authentication plugin and connect kubectl to an AceCloud Kubernetes cluster. * [**Troubleshooting the AceCloud kubectl Auth Plugin**](https://docs.acecloud.ai/knowledge-base/kubernetes-hosted/troubleshooting-the-acecloud-kubectl-auth-plugin) – Troubleshoot authentication, credential, plugin, network, and KubeConfig-related issues.