Gardenctl

What is gardenctl?

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.

Installation

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/gardenctl

Option 2: Manually download and install from gardenctl releases as follows:

1. 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-amd64

To 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

2. Make the gardenctl binary executable.

chmod +x ./gardenctl-darwin-amd64

3. Move the binary in to your PATH.

sudo mv ./gardenctl-darwin-amd64 /usr/local/bin/gardenctl

How to build it

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.

Prerequisites

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.

Build gardenctl

From source

First, you need to clone the repository and build gardenctl.

git clone https://github.com/gardener/gardenctl.git
cd gardenctl
make build

After 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/gardenctl

gardenctl supports auto completion. This recommended feature is bound to gardenctl or the alias g. To configure it you can run:

if you are using bash:

echo "source <(gardenctl completion bash)" >> ~/.bashrc
source ~/.bashrc

if you are using zsh:

echo "source <(gardenctl completion zsh)" >> ~/.zshrc
source ~/.zshrc

Via Dockerfile

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.

Configure gardenctl

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
  dashboardUrl: https://url_to_dashboard
  accessRestrictions:
  - key: seed.gardener.cloud/eu-access
    notifyIf: true 
    msg: warning msg
    options:
    - key: support.gardener.cloud/eu-access-for-cluster-addons
      notifyIf: true
      msg: warning msg
    - key: support.gardener.cloud/eu-access-for-cluster-nodes
      notifyIf: true
      msg: warning msg
- 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 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.

• aliyun
• aws
• az
• gcloud
• openstack

Moreover, gardenctl offers auto completion. To use it, the command

gardenctl completion bash

print 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.

Use gardenctl

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 target
• gardenctl 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.

Examples of basic usage:

• 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 -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 | cluster-autoscaler
• Show logs from garden nodes
  gardenctl target -g garden-name
gardenctl logs gardener-apiserver | gardener-controller-manager
• SSH to shoot nodes (please unset any proxy env vars like HTTPS and HTTP before this command)
  gardenctl k get nodes
gardenctl ssh node_name

Advanced usage based on JsonQuery

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'