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:
Windows
Open PowerShell and run:
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:
Open a new terminal window.
Run the required source command if it was displayed by the installer.
For example:
or:
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:
The first command displays the installed plugin version.
The second command lists the installed kubectl plugins and should include:
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
Windows (PowerShell)
After the installation completes, verify the installed 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
Windows
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.
Log in to the AceCloud portal.
Open the Kubernetes cluster that you want to connect to.
Click Download KubeConfig.
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:
This uses the specified KubeConfig only for that command.
Option B: Set the KubeConfig for the Current Session
Set the KUBECONFIG environment variable:
You can then run kubectl commands normally:
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
2. Merge the KubeConfigs
3. Replace the Existing Configuration
4. View Available Contexts
5. Switch to the AceCloud Cluster
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:
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:
To remove the locally stored AceCloud plugin data and cache, run:
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.
Last updated