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. The easiest way to install it, is to download the file or curl it.
curl -LO https://github.com/gardener/gardenctl/releases/download/0.1.0/gardenctl-darwin-amd64
After downloading 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/gardenctl
If 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 with dep
as dependency management system. 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 create a target folder structure before cloning and building gardenctl
.
mkdir -p ~/go/src/github.com/gardener
cd ~/go/src/github.com/gardener
git clone https://github.com/gardener/gardenctl.git
cd gardenctl
go build gardenctl.go
In case dependencies are missing, run dep ensure
and build gardenctl
again via go build gardenctl.go
.
After the successful build you get the executable gardenctl
in the the directory ~/go/src/github.com/gardener/gardenctl
. Next, make it available by moving the executable to e.g. /usr/local/bin
.
sudo mv gardenctl /usr/local/bin
gardenctl
supports auto completion. This recommended feature is bound to gardenctl
or the alias g
. To configure it you can run:
echo "gardenctl completion && source gardenctl_completion.sh && rm gardenctl_completion.sh" >> ~/.bashrc
source ~/.bashrc
First install gardenctl
via the go get
command.
go get github.com/gardener/gardenctl
It will locate the binary under $GOPATH/bin/gardenctl
. To generate the auto completion and add it to your ~/.bashrc
file, run the following command:
echo "$GOPATH/bin/gardenctl completion && source gardenctl_completion.sh && rm gardenctl_completion.sh" >> ~/.bashrc
First 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:
githubURL: https://github.location.company.corp
gardenClusters:
- name: dev
kubeConfig: ~/clusters/dev/kubeconfig.yaml
- name: prod
kubeConfig: ~/clusters/prod/kubeconfig.yaml
The 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
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
creates the file gardenctl_completion.sh
which can then be sourced later on via
source gardenctl_completion.sh
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
usees 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-instances
or
gardenctl aws ec2 describe-instances --no-cache
without 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 | grep 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
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
createdBy
information (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'