gardenctl is a command-line client designed to facilitate the administration of gardens, seed, and shoot clusters within the Gardener ecosystem. It provides tools for configuring access to clusters, managing cloud provider CLI integrations, and enabling secure SSH connections to cluster nodes.
Key Features:
Cluster Management: Simplify the configuration and management of multiple garden clusters, including setting up kubeconfig paths and garden identities.
Configuration Setup: Easily create or modify garden configurations using the gardenctl config command, allowing for targeted operations across clusters.
Shell Session Isolation: Maintain isolated shell sessions to prevent conflicts across different terminal windows or tabs, ensuring secure and reliable cluster interactions.
Completion Support: Enhance productivity with shell completion support for bash, zsh, fish, and PowerShell, providing suggestions for gardener resources such as shoots or projects.
SSH Access: Establish direct SSH connections to nodes within Shoot clusters, streamlining debugging and maintenance tasks.
Audience & Benefit:
Ideal for operations teams managing Kubernetes clusters at scale, gardenctl enables efficient cluster administration and automation. By simplifying configuration management and providing robust CLI tools, it helps reduce manual overhead and enhances operational efficiency.
The tool can be installed via winget, making it accessible to a wide range of users.
README
gardenctl-v2
What is gardenctl?
gardenctl is a command-line client for the Gardener. It facilitates the administration of one or many garden, seed and shoot clusters. Use this tool to configure access to clusters and configure cloud provider CLI tools. It also provides support for accessing cluster nodes via ssh.
Attention brew users: gardenctl-v2 uses the same binary name as the legacy gardenctl (gardener/gardenctl) CLI. If you have an existing installation you should remove it with brew uninstall gardenctl before attempting to install gardenctl-v2. Alternatively, you can choose to link the binary using a different name. If you try to install without removing or relinking the old installation, brew will run into an error and provide instructions how to resolve it.
# Example for macOS
# set operating system and architecture
os=darwin # choose between darwin, linux, windows
arch=arm64 # choose between amd64, arm64
# Get latest version. Alternatively set your desired version
version=$(curl -s https://raw.githubusercontent.com/gardener/gardenctl-v2/master/LATEST)
# Download gardenctl
curl -LO "https://github.com/gardener/gardenctl-v2/releases/download/${version}/gardenctl_v2_${os}_${arch}"
# Make the gardenctl binary executable
chmod +x "./gardenctl_v2_${os}_${arch}"
# Move the binary in to your PATH
sudo mv "./gardenctl_v2_${os}_${arch}" /usr/local/bin/gardenctl
gardenctl requires a configuration file. The default location is in ~/.garden/gardenctl-v2.yaml.
You can modify this file directly using the gardenctl config command. It allows adding, modifying and deleting gardens.
Example config command:
# Adapt the path to your kubeconfig file for the garden cluster (not to be mistaken with your shoot cluster)
export KUBECONFIG=~/relative/path/to/kubeconfig.yaml
# Fetch cluster-identity of garden cluster from the configmap
cluster_identity=$(kubectl -n kube-system get configmap cluster-identity -ojsonpath={.data.cluster-identity})
# Configure garden cluster
gardenctl config set-garden $cluster_identity --kubeconfig $KUBECONFIG
This command will create or update a garden with the provided identity and kubeconfig path of your garden cluster.
Example Config
gardens:
- identity: landscape-dev # Unique identity of the garden cluster. See cluster-identity ConfigMap in kube-system namespace of the garden cluster
kubeconfig: ~/relative/path/to/kubeconfig.yaml
# name: my-name # An alternative, unique garden name for targeting
# context: different-context # Overrides the current-context of the garden cluster kubeconfig
# patterns: ~ # List of regex patterns for pattern targeting
> [!NOTE]
> - To use the kubeconfigs for shoot clusters provided by gardenctl, you need to have gardenlogin installed as a kubectl auth plugin.
> - If your garden cluster kubeconfig uses OIDC authentication, ensure that you have the kubeloginkubectl auth plugin installed.
Config Path Overwrite
The gardenctl config path can be overwritten with the environment variable GCTL_HOME.
The gardenctl config name can be overwritten with the environment variable GCTL_CONFIG_NAME.
export GCTL_HOME=/alternate/garden/config/dir
export GCTL_CONFIG_NAME=myconfig # without extension!
# config is expected to be under /alternate/garden/config/dir/myconfig.yaml
Shell Session
The state of gardenctl is bound to a shell session and is not shared across windows, tabs or panes.
A shell session is defined by the environment variable GCTL_SESSION_ID. If this is not defined,
the value of the TERM_SESSION_ID environment variable is used instead. If both are not defined,
this leads to an error and gardenctl cannot be executed. The target.yaml and temporary
kubeconfig.*.yaml files are stored in the following directory ${TMPDIR}/garden/${GCTL_SESSION_ID}.
You can make sure that GCTL_SESSION_ID or TERM_SESSION_ID is always present by adding
the following code to your terminal profile ~/.profile, ~/.bashrc or comparable file.
Gardenctl supports completion that will help you working with the CLI and save you typing effort.
It will also help you find clusters by providing suggestions for gardener resources such as shoots or projects.
Completion is supported for bash, zsh, fish and powershell.
You will find more information on how to configure your shell completion for gardenctl by executing the help for
your shell completion command. Example:
gardenctl completion bash --help
Usage
Targeting
You can set a target to use it in subsequent commands. You can also overwrite the target for each command individually.
Note that this will not affect your KUBECONFIG env variable. To update the KUBECONFIG env for your current target see Configure KUBECONFIG section
Generate a script that points KUBECONFIG to the targeted cluster for the specified shell. Use together with eval to configure your shell. Example for bash:
eval "$(gardenctl kubectl-env bash)"
To load the kubectl configuration for each bash session add the command at the end of the ~/.bashrc file.
