gardenctl is a command-line client for administrative purposes for the Gardener. It facilitates the administration of one or many garden, seed and shoot clusters, e.g. to check for issues which occured in one of these clusters. Details about the concept behind the Gardener are described in the Gardener wiki.
gardenctl is shipped for mac and linux in a binary format.
Option 1: Install the latest release with Homebrew (macOS and Linux) as follows:
brew install gardener/tap/gardenctlOption 2: Manually download and install from gardenctl releases as follows:
- Download the latest release:
curl -LO https://github.com/gardener/gardenctl/releases/download/$(curl -s https://raw.githubusercontent.com/gardener/gardenctl/master/LATEST)/gardenctl-darwin-amd64To download a specific version, replace the $(curl -s https://raw.githubusercontent.com/gardener/gardenctl/master/LATEST) portion of the command with the specific version.
For example, to download version 0.16.0 on macOS, type:
curl -LO https://github.com/gardener/gardenctl/releases/download/v0.16.0/gardenctl-darwin-amd64- Make the gardenctl binary executable.
chmod +x ./gardenctl-darwin-amd64- Move the binary in to your PATH.
sudo mv ./gardenctl-darwin-amd64 /usr/local/bin/gardenctlIf no binary builds are available for your platform or architecture, you can build it from source, go get it or build the docker image from Dockerfile. Please keep in mind to use an up to date version of golang.
To build gardenctl from sources you need to have a running Golang environment. Moreover, since gardenctl allows to execute kubectl as well as a running kubectl installation is recommended, but not required. Please check this description for further details.
First, you need to clone the repository and build gardenctl.
git clone https://github.com/gardener/gardenctl.git
cd gardenctl
make buildAfter successfully building gardenctl the executables are in the directory ~/go/src/github.com/gardener/gardenctl/bin/. Next, move the executable for your architecture to /usr/local/bin. In this case for darwin-amd64.
sudo mv bin/darwin-amd64/gardenctl-darwin-amd64 /usr/local/bin/gardenctlgardenctl supports auto completion. This recommended feature is bound to gardenctl or the alias g. To configure it you can run:
echo "source <(gardenctl completion bash)" >> ~/.bashrc
source ~/.bashrcFirst clone the repository as described in the the build step "From source". As next step add the garden "config" file and "clusters" folder with the corresponding kubeconfig files for the garden cluster. Then build the container image via docker build -t gardener/gardenctl:v1 . in the cloned repository and run a shell in the image with docker run -it gardener/gardenctl:v1 /bin/bash.
gardenctl requires a configuration file. The default location is in ~/.garden/config, but it can be overwritten with the environment variable GARDENCONFIG.
Here an example file:
email: [email protected]
githubURL: https://github.location.company.corp
gardenClusters:
- name: dev
kubeConfig: ~/clusters/dev/kubeconfig.yaml
- name: prod
kubeConfig: ~/clusters/prod/kubeconfig.yamlThe path to the kubeconfig files of a garden cluster can be relative by using the ~ (tilde) expansion or absolute.
gardenctl caches some information, e.g. the garden project names. The location of this cache is per default $GARDENCTL_HOME/cache. If GARDENCTL_HOME is not set, ~/.garden is assumed.
gardenctl supports multiple sessions. The session ID can be set via $GARDEN_SESSION_ID and the sessions are stored under $GARDENCTL_HOME/sessions.
gardenctl makes it easy to get additional information of your IaaS provider by using the secrets stored in the corresponding projects in the Gardener. To use this functionality, the CLIs of the IaaS providers need to be available.
Please check the IaaS provider documentation for more details about their CLIs.
Moreover, gardenctl offers auto completion. To use it, the command
gardenctl completion bashprint on the standard output a completion script which can be sourced via
source <(gardenctl completion bash)Please keep in mind that the auto completion is bound to gardenctl or the alias g.
gardenctl requires the definition of a target, e.g. garden, project, seed or shoot. The following commands, e.g. gardenctl ls shoots uses the target definition as a context for getting the information.
Targets represent a hierarchical structure of resources. On top, there is/are the garden/s. E.g. in case you setup a development and a production garden, you would have two entries in your ~/.garden/config. Via gardenctl ls gardens you get a list of the available gardens.
gardenctl get target
Displays the current targetgardenctl target [garden|project|seed|shoot]
Set the target e.g. to a garden. It is as well possible to set the target directly to a element deeper in the hierarchy, e.g. to a shoot.gardenctl drop target
Drop the deepest target.
- List all seed cluster
gardenctl ls seeds - List all projects with shoot cluster
gardenctl ls projects - Target a seed cluster
gardenctl target seed-gce-dev - Target a project
gardenctl target garden-vora - Open prometheus ui for a targeted shoot-cluster
gardenctl show prometheus - Execute an aws command on a targeted aws shoot cluster
gardenctl aws ec2 describe-instancesor
gardenctl aws ec2 describe-instances --no-cachewithout locally caching credentials - Target a shoot directly and get all kube-dns pods in kube-system namespace
gardenctl target myshoot
gardenctl kubectl get pods -- -n kube-system -l k8s-app=kube-dns - List all cluster with an issue
gardenctl ls issues - Drop an element from target stack
gardenctl drop - Open a shell to a cluster node
gardenctl shell nodename - Show logs from elasticsearch
gardenctl logs etcd-main --elasticsearch - Show last 100 logs from elasticsearch from the last 2 hours
gardenctl logs etcd-main --elasticsearch --since=2h --tail=100 - Show logs from seed nodes
gardenctl target -g garden-name -s seed-name
gardenctl logs tf infra shoot-name - Show logs from shoot nodes
gardenctl target -g garden-name -t shoot-name
gardenctl logs api | scheduler | controller-manager | etcd-main -c etcd |etcd-main -c backup-restore | vpn-seed | vpn-shoot | machine-controller-manager | prometheus |grafana | alertmanager | cluster-autoscaler - Show logs from garden nodes
gardenctl target -g garden-name
gardenctl logs gardener-apiserver | gardener-controller-manager
The following examples are based on jq. The Json Query Playground offers a convenient environment to test the queries.
Below a list of examples:
- List the project name, shoot name and the state for all projects with issues
gardenctl ls issues -o json | jq '.issues[] | { project: .project, shoot: .shoot, state: .status.lastOperation.state }'- Print all issues of a single project e.g.
garden-myproject
gardenctl ls issues -o json | jq '.issues[] | if (.project=="garden-myproject") then . else empty end' - Print all issues with error state "Error"
gardenctl ls issues -o json | jq '.issues[] | if (.status.lastOperation.state=="Error") then . else empty end'- Print all issues with error state not equal "Succeded"
gardenctl ls issues -o json | jq '.issues[] | if (.status.lastOperation.state!="Succeeded") then . else empty end'- Print
createdByinformation (typically email addresses) of all shoots
gardenctl k get shoots -- -n garden-core -o json | jq -r ".items[].metadata | {email: .annotations.\"garden.sapcloud.io/createdBy\", name: .name, namespace: .namespace}"Here a few on cluster analysis:
- Which states are there and how many clusters are in this state?
gardenctl ls issues -o json | jq '.issues | group_by( .status.lastOperation.state ) | .[] | {state:.[0].status.lastOperation.state, count:length}'- Get all clusters in state
Failed
gardenctl ls issues -o json | jq '.issues[] | if (.status.lastOperation.state=="Failed") then . else empty end'