SSH keys
SSH keys are stored as SSHKey resources and referenced by name in node type or NodeClaim properties. During provisioning, the public keys are included in the user data (for example, cloud-init) so they are configured on the instance.
A tenant doesn't see the platform's own SSH keys
unless a platform admin assigns a key to it or shares one with every tenant. The capability
decides whether the tenant may register keys of its own, and those names carry the
<tenant>-- prefix. With the capability disabled, the tenant sees no SSH keys at all.
SSH keys may be used with any provider that supports user data during provisioning, including Metal3, KubeVirt, and Terraform.
Create an SSHKey​
The platform generates every SSH key's name. You choose a prefix, and the platform appends a random suffix. A key created with the prefix my-ssh-key- gets a name such as my-ssh-key-x7k2p.
To create a key in the platform UI, navigate to your Profile > SSH Keys. To create one directly, set metadata.generateName instead of metadata.name:
apiVersion: management.loft.sh/v1
kind: SSHKey
metadata:
generateName: my-ssh-key-
spec:
displayName: "My SSH Key"
description: "Development access key"
publicKey: "ssh-ed25519 AAAA... user@host"
Create it with kubectl create, and print the name the platform generated:
kubectl --context <management-context> create -f my-ssh-key.yaml -o name
The output names the new key, for example sshkey.management.loft.sh/my-ssh-key-x7k2p. Node types and instances reference the key by that generated name.
The platform refuses a request that sets metadata.name, including requests from platform admins. This means kubectl apply and GitOps tools that apply a manifest with a fixed name can't create SSH keys. Create them with generateName, then reference the generated name.
A tenant user's prefix must start with the tenant name followed by --, for example acme--deploy-. SSH keys are cluster-scoped, so all tenants draw from one set of key names, and the prefix keeps them apart. The platform UI adds the prefix for you.
If you leave spec.displayName empty, the platform fills it in from the prefix. It drops the trailing -, and for a tenant user it also drops the tenant prefix. The prefix acme--deploy- gives the display name deploy.
Fields​
| Field | Description | Editable after creation |
|---|---|---|
spec.displayName | Human-readable name shown in the UI. Defaults to the name prefix. | Yes |
spec.description | Optional description. | Yes |
spec.publicKey | The SSH public key content. | No |
spec.owner | Optional user or team that owns this resource. | No |
spec.access | Optional access control list. | No |
Metadata such as labels and annotations stays editable. Changing spec.publicKey, spec.owner, or spec.access on an existing key is refused.
Replace a key​
You can't change a key's public key in place. To rotate a key, or to give it a different owner or access list:
-
Create a new
SSHKeywith the intended public key, owner, and access list. -
If you're replacing a platform key shared with tenants, apply the same sharing label to the new key. See Share SSH keys with tenants.
-
If you shared the key in step 2, confirm the new key carries the label before switching references:
kubectl --context <management-context> get sshkey <new-key-name> --show-labels -
Update every node provider and node type that references the old key so it names the new one. An instance's properties can't change after creation, so an instance that names the old key keeps it.
-
Wait for instances that name the old key directly to finish provisioning before deleting it. Alternatively, recreate those instances with the new key. Recreating an instance releases its server and restarts provisioning.
-
Delete the old key.
SSH keys are injected at provision time. A server that's already provisioned keeps the old public key until you release and reprovision it.
Use SSH keys​
Reference SSH keys by name in node type properties or NodeClaim properties. Multiple keys can be specified as a comma-separated list.
properties:
vcluster.com/ssh-keys: my-ssh-key-x7k2p,team-key-m4q9z
All referenced keys are added to the provisioned server's authorized_keys.
An instance can only use keys its tenant can see. See Share SSH keys with tenants. A node type's key list overrides the node provider's list. With the default Replace policy, a claim's key list overrides that list. With Merge, both the operator's and the claim's keys apply. See vcluster.com/user-data-claim-policy.
The management API checks key visibility when you create a NodeClaim. Provisioning checks it again. If a key on the claim or its node type is missing or inaccessible to its tenant, the API refuses the claim:
ssh key "<name>" not found
The platform gives the same answer for a key that doesn't exist, so the error doesn't reveal whether another tenant's key exists.
The management API also checks keys inherited from the node provider. The tenant might not be able to see that provider, so the refusal doesn't name the key:
node provider "<name>" references a resource that cannot be used; ask the platform admin to share it with your tenant, or set your own value in spec.properties
A NodePool gets the same check when you create it or change its template. It covers keys in the pool's template and its node provider. Keys that a node type or network environment adds, and those of claims the platform creates itself, such as cluster control plane claims, are checked during provisioning. If the tenant can't use a key, provisioning can't complete.
Share SSH keys with tenants​
Each tenant sees its own SSH keys. Keys that a platform admin creates outside any tenant belong to the platform and stay hidden from tenants until the admin shares them. Which keys an instance can use depends on who owns its project:
| Instance owner | Keys the instance can use |
|---|---|
| A tenant | The tenant's own keys, platform keys shared with that tenant, and platform keys shared with all tenants |
| The platform | Platform keys without an exclusive-to label, including keys shared with all tenants. Keys a tenant owns aren't available. |
To assign a platform key exclusively to one tenant, label it with tenant.vcluster.com/exclusive-to. This makes the key unavailable to platform-owned instances. New requests that reference it fail, and pending provisioning can fail. Use a separate key if platform-owned instances still need the existing key.
Assign the key with:
kubectl --context <management-context> label sshkey my-ssh-key-x7k2p \
tenant.vcluster.com/exclusive-to=acme
To share a platform key with every tenant, label it with tenant.vcluster.com/all:
kubectl --context <management-context> label sshkey my-ssh-key-x7k2p \
tenant.vcluster.com/all=true
A tenant sees SSH keys only when the SSH keys capability is turned on for it. The platform refuses to share a key with a tenant that has the capability turned off. The same capability controls whether tenant users may register keys of their own. See What a platform admin grants a tenant.
To stop sharing a key, remove the label. For example, tenant.vcluster.com/exclusive-to- removes the single-tenant label. The key becomes unavailable to affected tenants' new requests. A pending instance that still needs to resolve the key fails provisioning with an error containing failed to get ssh key <name>. Removing the label doesn't remove the key from provisioning data already prepared for an instance. Servers that are already provisioned keep the key until they're reprovisioned.
Access control​
SSHKey resources are cluster-scoped. Use the spec.owner and spec.access fields to control who can use or modify them. Set both when you create the key, because neither can change afterwards.
apiVersion: management.loft.sh/v1
kind: SSHKey
metadata:
generateName: team-key-
spec:
displayName: "Team Shared Key"
publicKey: "ssh-ed25519 AAAA... team@org"
owner:
team: platform-team
access:
- teams:
- platform-team
verbs:
- get
- update
- delete