gardenlogin
s get-client-certificate
command can be used as a kubectl
credential plugin. It fetches the cluster-admin
credentials from the API introduced with GEP-16. See more details under Authentication Flow
With GEP-16, users are able to generate kubeconfigs for Shoot
clusters with short-lived certificates, to access the cluster as cluster-admin
.
Install the latest release from Homebrew, Chocolatey or GitHub Releases.
# Homebrew (macOS and Linux)
brew install gardener/tap/gardenlogin
# Chocolatey (Windows)
choco install gardenlogin
Nix with Flakes (prerequisite: Nix, the package manager):
# Nix (macOS, Linux, and Windows)
# development version
nix profile install github:gardener/gardenlogin
# or release <version>
nix profile install github:gardener/gardenlogin/<version>
#check installation
nix profile list | grep gardenlogin
# optionally, open a new shell and verify that cmd completion works
gardenlogin --help
kubectl gardenlogin --help
If you install via GitHub releases, you need to put the gardenlogin
binary on your path under the name kubectl-gardenlogin
so that the kubectl plugin mechanism can find it when you invoke kubectl gardenlogin
. The other install methods do this for you.
# Example for macOS
# set operating system and architecture
os=darwin # choose between darwin, linux, windows
arch=amd64
# Get latest version. Alternatively set your desired version
version=$(curl -s https://raw.githubusercontent.com/gardener/gardenlogin/master/LATEST)
# Download gardenlogin
curl -LO "https://github.com/gardener/gardenlogin/releases/download/${version}/gardenlogin_${os}_${arch}"
# Make the gardenlogin binary executable
chmod +x "./gardenlogin_${os}_${arch}"
# Move the binary in to your PATH
sudo mv "./gardenlogin_${os}_${arch}" /usr/local/bin/gardenlogin
# create kubectl-gardenlogin symlink
ln -s /usr/local/bin/gardenlogin /usr/local/bin/kubectl-gardenlogin
gardenlogin
requires a configuration file. The default location is in ~/.garden/gardenlogin.yaml
.
If no configuration file is found, it falls back to the gardenctl-v2
configuration file (~/.garden/gardenctl-v2.yaml
) which shares the same configuration properties.
Hint: If you intend to use both gardenlogin
and gardenctl-v2, it is recommended to store the configuration file in ~/.garden/gardenctl-v2.yaml
. This allows both applications to share a single configuration.
gardens:
- identity: landscape-dev # Unique identity of the garden cluster. See cluster-identity ConfigMap in kube-system namespace of the garden cluster
kubeconfig: ~/path/to/garden-cluster/kubeconfig.yaml
# context: different-context # Overrides the current-context of the garden cluster kubeconfig
- The
gardenlogin
config path can be overwritten with the environment variableGL_HOME
. - The
gardenlogin
config name can be overwritten with the environment variableGL_CONFIG_NAME
.
export GL_HOME=/alternate/garden/config/dir
export GL_CONFIG_NAME=myconfig # without extension!
# config is expected to be under /alternate/garden/config/dir/myconfig.yaml
An example kubeconfig
for a shoot cluster looks like the following:
# supported with kubectl version v1.20.0 onwards
apiVersion: v1
kind: Config
clusters:
- name: shoot--myproject--mycluster
cluster:
server: https://api.mycluster.myproject.example.com
certificate-authority-data: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCi4uLgotLS0tLUVORCBDRVJUSUZJQ0FURS0tLS0t
extensions:
- name: client.authentication.k8s.io/exec
extension:
shootRef:
namespace: garden-myproject
name: mycluster
gardenClusterIdentity: landscape-dev # must match with the garden cluster identity from the config
contexts:
- name: shoot--myproject--mycluster
context:
cluster: shoot--myproject--mycluster
user: shoot--myproject--mycluster
current-context: shoot--myproject--mycluster
users:
- name: shoot--myproject--mycluster
user:
exec:
apiVersion: client.authentication.k8s.io/v1
provideClusterInfo: true
command: kubectl
args:
- gardenlogin
- get-client-certificate
An example kubeconfig
supporting kubectl
version v1.11.0
onwards can be found under example/02-kubeconfig.yaml.
The following describes the flow to authenticate against a Shoot
cluster as cluster admin:
- The user would either download the
Shoot
clusterkubeconfig
- using the
gardener/dashboard
(TODO) - by targeting the cluster with
gardenctl
- or using
gardenctl kubeconfig --raw --garden landscape-dev --project my-project --shoot my-shoot
to print the kubeconfig for the respective target cluster
- using the
kubectl
is then configured to use the downloadedkubeconfig
for the shoot cluster- A
kubectl
command is executed, e.g.kubectl get namespaces
- The
gardenlogin
credential plugin is called to print theExecCredential
tostdout
, see input and output formats for more information. - In case a valid credential is already cached locally it is returned directly. Otherwise, a new credential has to be requested
- According to the garden cluster identity under
clusters[].cluster.extensions[].extension.gardenClusterIdentity
, thegardenlogin
plugin searches a matching garden cluster in its configuration file (gardenClusters[].clusterIdentity
) to get thekubeconfig
of the garden cluster - The
gardenlogin
plugin callsshoots/adminkubeconfig
resource with anAdminKubeConfigRequest
for theShoot
cluster referenced underclusters[].cluster.extensions[].extension.shootRef
- The
gardenlogin
plugin takes the x509 client certificate from the returnedAdminKubeConfigRequest
understatus.kubeconfig
and prints it asExecCredential
tostdout