Last modified October 12, 2018
gsctl create kubeconfig
gsctl create kubeconfig command is used to configure kubectl for access to
a cluster in your Giant Swarm installation. It can operate in two different
By default, your standard kubectl configuration file will be modified. A cluster, user, and context entry are added. A client certificate together with a private key and the CA certificate of the cluster are placed in your gsctl configuration directory.
Alternatively, a self-contained kubectl configuration file can be created. This is useful when you would like to keep things separate, or if you want to hand the file to someone. Here, certificate, key, and CA certificate are stored inline in the file. To enable this behaviour, use the flag
--self-containedand set it’s value to the desired output file path.
In both cases, a new key pair will be created in your installation, just as it
is the case with the
gsctl create keypair command.
As a prerequisite, you need to be logged in to
gsctl and you have to be
a member of the organization owning the cluster. If you can find the cluster
gsctl list clusters, this is the case.
Command Line Examples
To create a new key pair with default settings and modify your kubectl
configuration, you can execute the command like here (where
an example for a cluster ID):
$ gsctl create kubeconfig --cluster w6wn8
The output of the command gives details on what exactly happens.
- A new key pair is created and downloaded to files. This consists of a client
certificate and the according private key. This key pair has an expiry. When
not set specifically using the
--ttlflag, a default is used. Note: Since client certificates in Kubernetes cannot be revoked, we recommend to set short expiry periods.
- The kubectl configuration file is altered to add a cluster, a user and a
context entry. The context is named in the form
giantswarm-<cluster_id>, but this can be overwritten using the
- The new context is selected so that you can directly start using kubectl with the cluster.
The next example shows creation of a self-contained configuration file:
$ gsctl create kubeconfig -c w6wn8 --self-contained kubeconfig.yaml
Here, the file
kubeconfig.yaml will be created and it will contain the
credentials data. If the file already exists, an interactive confirmation to
overwrite this file will be required. The confirmation can be suppressed using
To conclude the examples sections, here is a more complex example showing how to create admin access (valid for one day only) in a self-contained file:
$ gsctl create kubeconfig --cluster w6wn8 \ --description "Admin certificate for Jane" \ --ttl 1 \ --self-contained kubeconfig-w6wn8-jane.yaml \ --certificate-organizations system:masters
-c: Used to specify the cluster ID to create a key pair for.
--ttl: Allows to set the key pair expiry, in days. Defaults to 30 days.
-d: Can be used to specify a description. If not given, a description like
Added by user firstname.lastname@example.org using 'gsctl create kubeconfig'is set.
--self-contained: This option sets the path for a self-contained kubectl config file. Credentials will be included. The file will contain only one user, one cluster, and one context. When this option is used, the default kubectl config file is not altered.
--force: Always overwrite existing files without prompt when using
--context: Allows to set the context name to be used in the config file. Defaults to
giantswarm-plus the cluster ID. This name is used with the
kubectl config use-contextcommand to select the context.
--cn-prefix: The common name prefix for the issued certificates ‘CN’ field. Note that only the charactes
-can be used.
--certificate-organizations: A comma separated list of organizations for the issued certificate’s ‘O’ fields.
Key pair expiry
A key pair has a limited lifetime, which you can affect only on creation. In general, we suggest using short-lived key pairs for security reasons, since Kubernetes does not allow to revoke certificates.
Depending on the installation, there might be a minimum and maximum key pair lifetime configured, to enforce security policies. If you’d like to find out about effective limits of your installation, please ask our support team.
Manipulation of your kubectl configuration
When not using the
--self-contained flag, your kubectl configuration file is
modified just as if you would manually apply the following commands:
kubectl config set-credentials [flags] giantswarm-<cluster-id>-user
kubectl config set-cluster [flags] giantswarm-<cluster-id>
kubectl config set-context [flags] <context-name>
kubectl config use-context <context-name>
kubectl has its ways to decide which configuration file to use and modify. By
default, the location
$HOME/.kube/config is used. This can be overwritten
KUBECONFIG environment variable.
Whenever you execute the
create kubeconfig command again for the same cluster,
existing entries with this name get overwritten. Should you ever manually edit
one of these entries, be aware that these changes might be overwritten by gsctl.
Once your key pair has expired, the re-execution of
gsctl create kubeconfig
with the according flags will request and download a fresh key pair and update
the paths to certificates and the key in the user and cluster entry.
Old certificates and keys are not removed when new key pairs are fetched.
Kubernetes RBAC and the certificate’s subject common name and organization fields
--cn-prefix flags you can
influence the common name (CN) and organization (O) fields of the issued
Kubernetes will take these values and map them to the username and group memberships respectively. This will let you set up fine grained permissions for the certificates that you issue by applying RBAC authorization resources to your cluster.