Last modified May 30, 2023

'gsctl create keypair' command reference

The 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 kubectl configuration.

Examples

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 .key)

• Your client certificate (file ending .crt).

Full argument reference

• --cluster, -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 a-z, 0-9 and - can be used.
• --certificate-organizations: A comma separated list of organizations for the issued certificate’s ‘O’ fields.
• --description, -d: Can be used to specify a description. If not given, a description like Added by user email@example.com 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

Using the --certificate-organizations and --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.

Warning: Setting 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 admin, edit or view instead, or creating new custom roles with needed permission.

Related

• 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