Last modified May 30, 2023
'gsctl create keypair' command reference
gsctl and the REST API are being phased out. We recommend to familiarize yourself with our Management API and the kubectl gs plugin as a future-proof replacement. We provide a migration page to help you with the transition.
gsctl create keypair command creates a key pair and stores the related files in your certificate folder.
If you intend to use the created key pair with the
kubectl program, we recommend you take a look at the
create kubeconfig command. It creates a new key pair and adds the according user, server, and context entries to your
Given you have a cluster with the ID
w6wn8, this command would create a new key pair for that cluster:
gsctl create keypair --cluster w6wn8
You can also use the cluster’s name for identifying the cluster:
gsctl create keypair --cluster "Cluster name"
The output will look similar to the one below:
New key pair created with ID 114e2de89... and expiry of 1 day CA certificate stored in: /Users/myself/.config/gsctl/certs/pmb9q-ca.crt Client certificate stored in: /Users/myself/.config/gsctl/certs/pmb9q-114e2de892-client.crt Client private key stored in: /Users/myself/.config/gsctl/certs/pmb9q-114e2de892-client.key
This informs you that a new key pair has been created. It will expire after a default time of 1 day.
Three files will be placed in the
certs folder, which is a subfolder of your gsctl configuration folder:
The CA certificate file (name schema:
<cluster_id>-ca.crt), which technically is not really a part of your personal key pair, but required to access the Kubernetes API for the cluster.
Your private key (file ending
Your client certificate (file ending
Full argument reference
-c: Used to specify the cluster name or ID to create a key pair for.
--cn-prefix: The common name prefix for the issued certificates ‘CN’ field. Note that only the characters
-can be used.
--certificate-organizations: A comma separated list of organizations for the issued certificate’s ‘O’ fields.
-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.
--ttl: Allows to set the key pair expiry, in days. Defaults to 1 day.
Key pair expiry
Each 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.
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.
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 certificate.
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.
system:masters as an organization means the user who uses the issued keypair has
cluster-admin rights in the selected cluster. It is a good practice to use finer grained roles, only giving the least privileges possible to the users (PoLP). Please consider using existing roles like
view instead, or creating new custom roles with needed permission.
- Creating workload cluster key pairs via the Management API
gsctl create kubeconfig: Create a key pair and prepare your kubectl configuration to access the cluster.
- Rest API: Create key pair
Need help, got feedback?
We listen to your Slack support channel. You can also reach us at email@example.com. And of course, we welcome your pull requests!