repository·main·Indexed 18 days ago
https://github.com/rancher/cliA unified command-line tool for interacting with Rancher Server (version 2.x.x). It enables users to manage Rancher resources, including Kubernetes clusters, project contexts, and member roles, via a terminal interface. Key capabilities include cluster creation, importing existing clusters, node registration, and Kubeconfig retrieval.
You can run the CLI using a Docker container. To provide authentication, you must mount your local cli2.json configuration file into the container at /home/cli/.rancher/cli2.json using a volume mount.
To build the rancher/cli Docker image, run make. To build using a custom repository name, use REPO=custom make to produce a custom/cli image.
docker run --rm -it -v <PATH_TO_CONFIG>:/home/cli/.rancher/cli2.json rancher/cli2 [ARGS]The CLI requires your Rancher Server URL and authentication credentials (API keys). Authentication information is stored in a JSON file named cli2.json, which is automatically created in ~/.rancher/cli2.json the first time you run the rancher login command.
When providing the server URL, ensure you include the specific port exposed during your Rancher Server installation.
rancher login https://<RANCHER_SERVER_URL> -t my-secret-token$PATH. Alternatively, you can build the binary from source using make.The Rancher CLI is a unified tool for interacting with your Rancher Server. You can view a complete list of available commands by running the --help flag.
rancher --helpYou can build the Rancher CLI binaries using make. The resulting binaries will be located in the /bin directory.
make build.CROSS=1 make build to ensure compatibility.# For Linux
make build
# For Mac
CROSS=1 make buildWhen working with tokens issued via the extension API, the CLI uses the ext/ prefix to distinguish them from standard v3 Management tokens.
ext/ (e.g., ext/my-token-name) tells the CLI to bypass the v3 API and look up the token directly via the ext.cattle.io/v1 API. The prefix is automatically stripped by the CLI before performing the actual API call.The CLI maintains a mapping of Kubeconfigs associated with specific users and clusters within its configuration file.
When retrieving a Kubeconfig, the CLI uses a key format of {user}-{cluster} to look up the specific configuration for that user context. This allows the CLI to switch between different Kubernetes contexts seamlessly based on the user and the current cluster being targeted.
The Rancher CLI uses OAuth2 to exchange identity provider credentials for a Rancher-specific token. The process follows these steps:
auth_code or device_code).auth_code flow: A local server is started, a browser is opened to the provider's auth URL, and the CLI waits for a callback.device_code flow: The CLI displays a VerificationURI and a UserCode.id_token.id_token to the Rancher server via a POST request to the login endpoint. The request body includes:type: The authentication provider name.responseType: Usually kubeconfig (or kubeconfig_<clusterID> if a specific cluster is targeted).id_token: The token received from the OAuth provider.The Rancher CLI manages two distinct types of authentication tokens: v3 Management API tokens and ext.cattle.io/v1 Tokens.
To ensure compatibility, the CLI uses a fallback mechanism for lookups and validation:
ext/, the CLI identifies it as an ext.cattle.io/v1 token and skips the v3 Management API lookup entirely to avoid unnecessary 404 errors.ext/ prefix, the CLI first attempts to find the token via the v3 Management API. If the token is not found (a 404 error), it falls back to the ext.cattle.io/v1 API.ext/, the CLI attempts to retrieve the token from the ext.cattle.io/v1 API. The ext/ prefix is stripped before the request is made to the extension API.This dual-layer approach allows the CLI to seamlessly support both legacy and extended token formats used by different Rancher server configurations.
The Rancher CLI supports two primary OAuth authentication flows. You can control which flow is used via the CATTLE_OAUTH_AUTH_FLOW environment variable or by passing the appropriate flag in your command.
auth_code: The Authorization Code flow. This flow automatically attempts to open your default web browser to complete the authentication. It starts a local callback server to receive the authorization code.device_code (Default): The Device Code flow. This is used when a browser cannot be automatically opened or when working in headless environments. The CLI will provide a verification URI and a user code for you to enter manually in a browser on another device.If no flow is specified, the CLI defaults to device_code.
export CATTLE_OAUTH_AUTH_FLOW=auth_code
# or use the CLI flag if available in the parent commandThe Rancher CLI supports different output formats for commands via the --format flag and suppresses headers via the --quiet flag.
Supported formats:
json: Outputs the object as a JSON string.yaml: Outputs the object as a YAML string.default: (When no format is specified) Outputs data in a tabular format using a template.custom: Any other string is treated as a Go template for the object values.Behavioral rules:
--quiet is used, headers are suppressed and the output defaults to showing only the {{.ID}} of the object.--format is provided (other than json or yaml), headers are suppressed and the output uses that format/template.The Rancher CLI uses a configuration file to manage settings. You can specify the path to this file using the --config flag or the RANCHER_CONFIG_DIR environment variable. If neither is provided, the CLI defaults to the directory returned by cmd.ConfigDir().
Flags:
--config (alias: -c): Path to rancher config.Environment Variables:
RANCHER_CONFIG_DIR: Path to rancher config.# Using the flag
rancher --config /path/to/config.yaml cluster list
# Using the environment variable
export RANCHER_CONFIG_DIR=/path/to/config.yaml
rancher cluster list