This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.


1 - Accessing the Gardener API

Accessing the Gardener API Through the Dashboard


The cluster operations that are performed manually in the dashboard or via kubectl can be automated using the Gardener API and a Service Account authorized to perform them.

Create a Service Account



  1. Select your project and choose MEMBERS from the menu on the left.

  2. Locate the section Service Accounts and choose +.

    Add service account

  3. Enter the service account details.

    Enter service account details

    The following Roles are available:

RoleGranted Permissions
OwnerCombines the Admin, UAM and Service Account Manager roles. There can only be one owner per project. You can change the owner on the project administration page.
AdminAllows to manage resources inside the project (e.g. secrets, shoots, configmaps and similar) and to manage permissions for service accounts. Note that the Admin role has read-only access to service accounts.
ViewerProvides read access to project details and shoots. Has access to shoots but is not able to create new ones. Cannot read cloud provider secrets.
UAMAllows to add/modify/remove human users, service accounts or groups to/from the project member list. In case an external UAM system is connected via a service account, only this account should get the UAM role.
Service Account ManagerAllows to manage service accounts inside the project namespace and request tokens for them. The permissions of the created service accounts are instead managed by the Admin role. For security reasons this role should not be assigned to service accounts. In particular it should be ensured that the service account is not able to refresh service account tokens forever.
  1. Choose CREATE.

Use the Service Account

To use the service account, download or copy its kubeconfig. With it you can connect to the API endpoint of your Gardener project.

Download service account kubeconfig

Note: The downloaded kubeconfig contains the service account credentials. Treat with care.

Delete the Service Account

Choose Delete Service Account to delete it.

Delete service account

2 - Connect Kubectl

Connect kubectl

In Kubernetes, the configuration for access to your cluster is a format known as kubeconfig that is normally stored as a file. It contains details such as cluster API server addresses and user access credentials. Treat it as sensitive data. Tools like kubectl use kubeconfig to connect and authenticate to a cluster and perform operations on it. Learn more about kubeconfig and kubectl on


  • You are logged on to the Gardener Dashboard.
  • You have created a cluster and its status is operational.

On this page:

Downloading kubeconfig for a cluster

  1. Select your project from the dropdown on the left, then choose CLUSTERS and locate your cluster in the list. Choose the key icon to bring up a dialog with the access options.

    In the Kubeconfig section the options are to download, copy or view the kubeconfig for the cluster. The same options are available also in the Access section in the cluster details screen. To find it, choose a cluster from the list.

  2. Choose the download icon to download kubeconfig as file on your local system.

Connecting to the cluster

In the following command, change <path-to-kubeconfig> with the actual path to the file where you stored the kubeconfig downloaded in the previous steps.

$ kubectl --kubeconfig=<path-to-kubeconfig> get namespaces

The command connects to the cluster and list its namespaces.

Exporting KUBECONFIG environment variable

Since many kubectl commands will be used, it’s a good idea to take advantage of every opportunity to shorten the expressions. The kubectl tool has a fallback strategy for looking up a kubeconfig to work with. For example, it looks for the KUBECONFIG environment variable with value that is the path to the kubeconfig file meant to be used. Export the variable:

$ export KUBECONFIG=<path-to-file>

In the previous snippet make sure to change the <path-to-file> with the path to the kubeconfig for the cluster that you want to connect to on your system.

What’s next?

3 - Custom Fields

Custom Shoot Fields

The Dashboard supports custom shoot fields, that can be defined per project by specifying metadata.annotations[""]. The fields can be configured to be displayed on the cluster list and cluster details page. Custom fields do not show up on the ALL_PROJECTS page.

nameString✔️Name of the custom field
pathString✔️Path in shoot resource, of which the value must be of primitive type (no object / array). Use lodash get path syntax, e.g. metadata.labels[""] or spec.networking.type
iconStringMDI icon for field on the cluster details page. See for available icons. Must be in the format: mdi-<icon-name>.
tooltipStringTooltip for the custom field that appears when hovering with the mouse over the value
defaultValueString/NumberDefault value, in case there is no value for the given path
showColumnBooltrueField shall appear as column in the cluster list
columnSelectedByDefaultBooltrueIndicates if field shall be selected by default on the cluster list (not hidden by default)
weightNumber0Defines the order of the column. The standard columns start with weight 100 and continue in 100 increments (200, 300, ..)
sortableBooltrueIndicates if column is sortable on the cluster list.
searchableBooltrueField shall appear in a dedicated card (Custom Fields) on the cluster details page
showDetailsBooltrueIndicates if field shall appear in a dedicated card (Custom Fields) on the cluster details page

As there is currently no way to configure the custom shoot fields for a project in the gardener dashboard, you have to use kubectl to update the project resource. See /docs/dashboard/usage/project-operations/#download-kubeconfig-for-a-user on how to get a kubeconfig for the garden cluster in order to edit the project.

The following is an example project yaml:

kind: Project
  annotations: |
        "shootStatus": {
          "name": "Shoot Status",
          "path": "metadata.labels[\"\"]",
          "icon": "mdi-heart-pulse",
          "tooltip": "Indicates the health status of the cluster",
          "defaultValue": "unknown",
          "showColumn": true,
          "columnSelectedByDefault": true,
          "weight": 950,
          "searchable": true,
          "sortable": true,
          "showDetails": true
        "networking": {
          "name": "Networking Type",
          "path": "spec.networking.type",
          "icon": "mdi-table-network",
          "showColumn": false

4 - Project Operations

Project Operations

This section demonstrates how to use the standard Kubernetes tool for cluster operation kubectl for common cluster operations with emphasis on Gardener resources. For more information on kubectl, see kubectl on


  • You’re logged on to the Gardener Dashboard.
  • You’ve created a cluster and its status is operational.

It’s recommended that you get acquainted with the resources in the Gardener API.

Downloading kubeconfig for remote project operations

The kubeconfig for project operations is different from the one for cluster operations. It has a larger scope and allows a different set of operations that are applicable for a project administrator role, such as lifecycle control on clusters and managing project members.

Depending on your goal, you create a service account suitable for automation and download its kubeconfig, or you can get a user-specific kubeconfig. The difference is the identity on behalf of which the operations are performed.

Download kubeconfig for a user

Kubernetes doesn’t offer an own resource type for human users that access the API server. Instead, you either have to manage unique user strings, or use an OpenID-Connect (OIDC) compatible Identity Provider (IDP) to do the job.

Once the latter is set up, each Gardener user can use the kubelogin plugin for kubectl to authenticate against the API server:

  1. Set up kubelogin if you don’t have it yet. More information: kubelogin setup.

  2. Open the menu at the top right of the screen, then choose MY ACCOUNT.

    Show account details

  3. On the Access card, choose the arrow to see all options for the personalized command-line interface access.

    Show details of OICD login

    The personal bearer token that is also offered here only provides access for a limited amount of time for one time operations, for example, in curl commands. The kubeconfig provided for the personalized access is used by kubelogin to grant access to the Gardener API for the user permanently by using a refresh token.

  4. Check that the right Project is chosen and keep the settings otherwise. Download the kubeconfig file and add its path to the KUBECONFIG environment variable.

You can now execute kubectl commands on the garden cluster using the identity of your user.

Download kubeconfig for a Service Account

  1. Go to a service account and choose Download.

    Download service account kubeconfig

  2. Add the downloaded kubeconfig to your configuration.

You can now execute kubectl commands on the garden cluster using the technical service account.

List Gardener API resources

  1. Using a kubeconfig for project operations, you can list the Gardner API resources using the following command:

    kubectl api-resources | grep garden

    The response looks like this:

    backupbuckets                     bbc               false        BackupBucket
    backupentries                     bec               true         BackupEntry
    cloudprofiles                     cprofile,cpfl            false        CloudProfile
    controllerinstallations           ctrlinst            false        ControllerInstallation
    controllerregistrations           ctrlreg            false        ControllerRegistration
    plants                            pl                true         Plant
    projects                                            false        Project
    quotas                            squota            true         Quota
    secretbindings                    sb                true         SecretBinding
    seeds                                               false        Seed
    shoots                                              true         Shoot
    shootstates                                         true         ShootState
    terminals                                      true         Terminal
    clusteropenidconnectpresets       coidcps        false        ClusterOpenIDConnectPreset
    openidconnectpresets              oidcps        true         OpenIDConnectPreset
  2. Enter the following command to view the Gardener API versions:

    kubectl api-versions | grep garden

    The response looks like this:

Check your permissions

  1. The operations on project resources are limited by the role of the identity that tries to perform them. To get an overview over your permissions, use the following command:

    kubectl auth can-i --list | grep garden

    The response looks like this:                      []                       []                 [create delete deletecollection get list patch update watch]                      []                       []                 [create delete deletecollection get list patch update watch]              []                       []                 [create delete deletecollection get list patch update watch]                      []                       []                 [create delete deletecollection get list patch update watch]              []                       []                 [create delete deletecollection get list patch update watch]    []                       []                 [create delete deletecollection get list patch update watch]               []                       []                 [get list watch]                    []                       [flowering]             [get patch update delete]
    namespaces                                      []                       [garden-flowering]      [get]
  2. Try to execute an operation that you aren’t allowed, for example:

    kubectl get projects

    You receive an error message like this:

    Error from server (Forbidden): is forbidden: User "system:serviceaccount:garden-flowering:robot" cannot list resource "projects" in API group "" at the cluster scope

Working with projects

  1. You can get the details for a project, where you (or the service account) is a member.

    kubectl get project flowering

    The response looks like this:

    NAME        NAMESPACE          STATUS   OWNER                    CREATOR                         AGE
    flowering   garden-flowering   Ready    [PROJECT-ADMIN]@domain   [PROJECT-ADMIN]@domain system   45m

    For more information, see Project in the API reference.

  2. To query the names of the members of a project, use the following command:

    kubectl get project docu -o jsonpath='{.spec.members[*].name }'

    The response looks like this:

    [PROJECT-ADMIN]@domain system:serviceaccount:garden-flowering:robot

    For more information, see members in the API reference.

Working with clusters

The Gardener domain object for a managed cluster is called Shoot.

List project clusters

To query the clusters in a project:

kubectl get shoots

The output looks like this:

geranium   aws            1.18.3    aws-eu1   geranium.flowering.shoot.<truncated>   Awake         Succeeded   100        True        True      True    True     74m

Create a new cluster

To create a new cluster using the command line, you need a YAML definition of the Shoot resource.

  1. To get started, copy the following YAML definition to a new file, for example, daffodil.yaml (or copy file shoot.yaml to daffodil.yaml) and adapt it to your needs.

    kind: Shoot
      name: daffodil
      namespace: garden-flowering
      secretBindingName: trial-secretbinding-gcp
      cloudProfileName: gcp
      region: europe-west1
      purpose: evaluation
        type: gcp
          kind: InfrastructureConfig
          zone: europe-west1-c
          kind: ControlPlaneConfig
        - name: cpu-worker
          maximum: 2
          minimum: 1
          maxSurge: 1
          maxUnavailable: 0
            type: n1-standard-2
              name: coreos
              version: 2303.3.0
            type: pd-standard
            size: 50Gi
            - europe-west1-c
        type: calico
          begin: 220000+0100
          end: 230000+0100
          kubernetesVersion: true
          machineImageVersion: true
        enabled: true
          - start: '00 17 * * 1,2,3,4,5'
            location: Europe/Kiev
        allowPrivilegedContainers: true
          enableBasicAuthentication: false
          nodeCIDRMaskSize: 24
          mode: IPTables
        version: 1.18.3
          enabled: false
          enabled: false
  2. In your new YAML definition file, replace the value of field metadata.namespace with your namespace following the convention garden-[YOUR-PROJECTNAME].

  3. Create a cluster using this manifest (with flag --wait=false the command returns immediately, otherwise it doesn’t return until the process is finished):

    kubectl apply -f daffodil.yaml --wait=false

    The response looks like this: created
  4. It takes 5–10 minutes until the cluster is created. To watch the progress, get all shoots and use the -w flag.

    kubectl get shoots -w

For a more extended example, see Gardener example shoot manifest.

Delete cluster

To delete a shoot cluster, you must first annotate the shoot resource to confirm the operation with "true":

  1. Add the annotation to your manifest (daffodil.yaml in the previous example):

      kind: Shoot
        name: daffodil
        namespace: garden-flowering
  2. Apply your changes of daffodil.yaml.

    kubectl apply -f daffodil.yaml

    The response looks like this: configured
  3. Trigger the deletion.

    kubectl delete shoot daffodil --wait=false

    The response looks like this: "daffodil" deleted
  4. It takes 5–10 minutes to delete the cluster. To watch the progress, get all shoots and use the -w flag.

    kubectl get shoots -w

Get kubeconfig for a cluster

To get the kubeconfig for a cluster:

kubectl get secrets daffodil.kubeconfig -o jsonpath='{.data.kubeconfig}' | base64 -d

The response looks like this:

apiVersion: v1
kind: Config
current-context: shoot--flowering--daffodil
- name: shoot--flowering--daffodil
    certificate-authority-data: LS0tLS1CRUdJTiBDR <truncated>
    server: https://api.daffodil.flowering.shoot.<truncated>
- name: shoot--flowering--daffodil
    cluster: shoot--flowering--daffodil
    user: shoot--flowering--daffodil-token
- name: shoot--flowering--daffodil-token
    token: HbjYIMuR9hmyb9 <truncated>

The name of the Secret containing the kubeconfig is in the form <cluster-name>.kubeconfig, that is, in this example: daffodil.kubeconfig

Accessing the Gardener API Through the Dashboard

Authenticating with an Identity Provider.

5 - Terminal Shortcuts

Terminal Shortcuts

As user and/or gardener administrator you can configure terminal shortcuts, which are preconfigured terminals for frequently used views.

You can launch the terminal shortcuts directly on the shoot details screen.

You can view the definition of a terminal terminal shortcut by clicking on they eye icon

What also has improved is, that when creating a new terminal you can directly alter the configuration.

With expanded configuration

On the Create Terminal Session dialog you can choose one or multiple terminal shortcuts.

Project specific terminal shortcuts created (by a member of the project) have a project icon badge and are listed as Unverified.

A warning message is displayed before a project specific terminal shortcut is ran informing the user about the risks.

How to create a project specific terminal shortcut

Disclaimer: “Project specific terminal shortcuts” is experimental feature and may change in future releases (we plan to introduce a dedicated custom resource).

You need to create a secret with the name terminal.shortcuts within your project namespace, containing your terminal shortcut configurations. Under data.shortcuts you add a list of terminal shortcuts (base64 encoded). Example terminal.shortcuts secret:

kind: Secret
type: Opaque
  name: terminal.shortcuts
  namespace: garden-myproject
apiVersion: v1
  shortcuts: LS0tCi0gdGl0bGU6IE5ldHdvcmtEZWxheVRlc3RzCiAgZGVzY3JpcHRpb246IFNob3cgbmV0d29ya21hY2hpbmVyeS5pbydzIE5ldHdvcmtEZWxheVRlc3RzCiAgdGFyZ2V0OiBzaG9vdAogIGNvbnRhaW5lcjoKICAgIGltYWdlOiBxdWF5LmlvL2RlcmFpbGVkL2s5czpsYXRlc3QKICAgIGFyZ3M6CiAgICAtIC0taGVhZGxlc3MKICAgIC0gLS1jb21tYW5kPW5ldHdvcmtkZWxheXRlc3QKICBzaG9vdFNlbGVjdG9yOgogICAgbWF0Y2hMYWJlbHM6CiAgICAgIGZvbzogYmFyCi0gdGl0bGU6IFNjYW4gQ2x1c3RlcgogIGRlc2NyaXB0aW9uOiBTY2FucyBsaXZlIEt1YmVybmV0ZXMgY2x1c3RlciBhbmQgcmVwb3J0cyBwb3RlbnRpYWwgaXNzdWVzIHdpdGggZGVwbG95ZWQgcmVzb3VyY2VzIGFuZCBjb25maWd1cmF0aW9ucwogIHRhcmdldDogc2hvb3QKICBjb250YWluZXI6CiAgICBpbWFnZTogcXVheS5pby9kZXJhaWxlZC9rOXM6bGF0ZXN0CiAgICBhcmdzOgogICAgLSAtLWhlYWRsZXNzCiAgICAtIC0tY29tbWFuZD1wb3BleWU=

How to configure the dashboard with terminal shortcuts Example values.yaml:

    terminalEnabled: true
    projectTerminalShortcutsEnabled: true # members can create a `terminal.shortcuts` secret containing the project specific terminal shortcuts
    - title: "Control Plane Pods"
      description: Using K9s to view the pods of the control plane for this cluster
      target: cp
        - "--headless"
        - "--command=pods"
    - title: "Cluster Overview"
      description: This gives a quick overview about the status of your cluster using K9s pulse feature
      target: shoot
        - "--headless"
        - "--command=pulses"
    - title: "Nodes"
      description: View the nodes for this cluster
      target: shoot
        - bin/sh
        - -c
        - sleep 1 && while true; do k9s --headless --command=nodes; done
#      shootSelector:
#        matchLabels:
#          foo: bar
terminal: # is generally required for the terminal feature
    - image: /.*/ops-toolbelt:.*/
      description: Run `ghelp` to get information about installed tools and packages
    seedRef: my-soil
        name: dashboard-terminal-admin
        namespace: garden
    disabled: false
    shootDisabled: false
    seedDisabled: false
    gardenTerminalHostDisabled: true
      annotations: managed nginx HTTPS

6 - Using Terminal

Using the Dashboard Terminal

The dashboard features an integrated web-based terminal to your clusters. It allows you to use kubectl without the need to supply kubeconfig. There are several ways to access it and they’re described on this page.


  • You are logged on to the Gardener Dashboard.
  • You have created a cluster and its status is operational.
  • The landscape administrator has enabled the terminal feature
  • The cluster you want to connect to is reachable from the dashboard

On this page:

Open from cluster list

  1. Choose your project from the menu on the left and choose CLUSTERS.

  2. Locate a cluster for which you want to open a Terminal and choose the key icon.

  3. In the dialog, choose the icon on the right of the Terminal label.

Open from cluster details page

  1. Choose your project from the menu on the left and choose CLUSTERS.

  2. Locate a cluster for which you want to open a Terminal and choose to display its details.

  3. In the Access section, choose the icon on the right of the Terminal label.


Opening up the terminal in either of the ways discussed here results in the following screen:

It provides a bash environment and range of useful tools and an installed and configured kubectl (with alias k) to use right away with your cluster.

Try to list the namespaces in the cluster.

$ k get ns

You get a result like this:

7 - Working With Projects

Working with Projects


Projects are used to group clusters, onboard IaaS resources utilized by them, and organize access control. To work with clusters, first you need to create a project that they will belong to.

Creating Your First Project


  • You have access to the Gardener Dashboard and have permissions to create projects


  1. Logon to the Gardener Dashboard and choose CREATE YOUR FIRST PROJECT.

  2. Provide a project Name, and optionally a Description and a Purpose, and choose CREATE.

⚠️ You will not be able to change the project name later. The rest of the details will be editable.


After completing the steps above, you will arrive at a similar screen:

Creating More Projects

If you need to create more projects, expand the Projects list dropdown on the left. When expanded, it reveals a CREATE PROJECT button that brings up the same dialog as above.

Deleting Your Project

When you need to delete your project, go to ADMINISTRATON, choose the trash bin icon and, confirm the operation.