Identity and enrollment

This page shows how to install kibo, connect to ctrl with an enrollment key, and issue or revoke enrollment keys for other Operators and nodes.

• For the full rules on identity, certificates, and configuration, see Identity, configuration, and connections.
• For cluster management after enrollment, see Nodes, Storage pools, Catalog, and Artifact reclamation.
• For everyday Workspace operations, see kibo CLI. For global parameters and exit codes, see kibo CLI reference.

OverviewCopy Anchor Link

The kibo command-line tool performs Workspace operations, Template publishing, and node management through the ctrl API. Because it works only through the ctrl API, your workstation does not need to run the same system as the deployment:

The two macOS builds come from the same release build as the Linux one and have the same features. So far only their build identity has been checked; they have not gone through runtime acceptance on macOS.

The kibo tool accesses ctrl with an Operator identity. The identity is stored in a local directory called a context. Creating a context is called enrollment: you get a one-time enrollment key and pass it to kibo context enroll, which exchanges it with ctrl for a client certificate and saves it.

Install kibo from the release set. The examples on this page call it directly.

Operator setup and node enrollmentCopy Anchor Link

These are the complete steps on the Operator workstation for a first deployment.

Prerequisites: the ctrl host administrator has issued the first Operator enrollment key with kibotos-ctrl enrollment create and handed it to you over a secure channel. See Install ctrl.

sudo install -m 0755 kibo_VERSION_linux_amd64 /usr/local/bin/kibo
umask 077
kibo context enroll --endpoint https://ctrl.kibotos.example:18092 --key-file operator-enrollment.key
rm operator-enrollment.key
kibo context show
kibo enrollment create --node node-a --data-plane-extra-host node-a.example.com --output node-enrollment.key --json

• Take kibo from the verified release set directory. On a macOS workstation, use the file for its architecture instead, and install it as /usr/local/bin/kibo the same way.
• The last step generates the node's enrollment key. Transfer it securely to the node host, where kibotos-node join uses it, then delete the key file on both sides. For the node-side steps, see Install node.
• Keep the context directory only on the Operator workstation. Template build hosts use separate accounts and do not share this directory.
• Do not copy this directory to gateways or other programs. Each of them needs its own identity, issued separately with kibo enrollment create --operator.

Connection configuration (context)Copy Anchor Link

All remote kibo commands go through the mTLS port of ctrl and authenticate with the Operator identity in the context. There is no default server address, so you must enroll first.

kibo context enroll --endpoint https://ctrl.example.com:18092  # Prompts for the key without echo
kibo context show                                             # Shows the local context without contacting ctrl
kibo version                                                 # Queries the current ctrl

Server addressCopy Anchor Link

• --endpoint must be HTTPS. The host part is a lowercase fully qualified domain name or an IP address, and it must match [identity].host in the ctrl configuration.
• enroll takes the ctrl server CA from the key, verifies ctrl, and then saves the address, identity, and CA together.

Key, proxy, and context directoryCopy Anchor Link

For all flags of enroll, see kibo context enroll.

• Without a key flag, enroll prompts for the key without echo. In a script, pass it with --key-file, --key-stdin, or --key-fd. For how each source is read, see Enrollment key rules.
• If you need a forward proxy, add --proxy to the enroll command, for example --proxy http://proxy.example:3128. The proxy setting is saved in the context. For the accepted proxies and the proxy environment variables, see Forward proxy.
• enroll writes the context to its default directory, or to the absolute path in KIBO_CONTEXT_DIR. If the directory already exists, enroll refuses to overwrite it; to enroll again, delete the old directory first. See Context directory.
• Delete the key file after enrollment succeeds.

Lifetime and renewalCopy Anchor Link

The identity is valid for 30 days. kibo renews it automatically before it expires, and kibo context renew renews it manually. An expired identity cannot be renewed: enroll again with a new enrollment key. See Lifetime.

TroubleshootingCopy Anchor Link

In both cases a retry does not succeed. Fix the context or the identity state first.

Issuing and revoking enrollment keysCopy Anchor Link

An enrolled Operator can use kibo enrollment to issue enrollment keys for other Operators or nodes, and to revoke their identities. Replace the IDs in the examples with real values:

kibo enrollment create --node node-a --ttl 1h --data-plane-extra-host 127.0.0.1 --output node-a.key
kibo enrollment create --operator teammate --ttl 1h --output teammate.key
kibo --json enrollment create --node node-b --output node-b.key
kibo enrollment revoke --node node-a --yes
kibo enrollment revoke --operator teammate --yes

createCopy Anchor Link

For all flags, see kibo enrollment create. The flags follow these rules:

• Give exactly one of --operator and --node. A node ID must be a lowercase domain name; see Identity rules.
• The key is written only to the --output file, with permissions 0600. The file must not exist; - and symbolic links are not accepted.
• --data-plane-extra-host adds a name to the node's data-plane certificate. The data-plane address the node advertises must be one of the certificate's names. For how the names are combined, see Data-plane certificate of a node.
• The command output (including --json) contains only a summary: the grant ID, subject, lifetime, and output_file. The full key is not kept by ctrl.

Idempotent replayCopy Anchor Link

• When you repeat the same create with --command-id, ctrl returns the original grant but not the key again. The kibo command exits nonzero and does not write the output file.
• The same command ID with a different subject, type, or extra host names returns already_exists.
• If writing the output file fails, check the state of the grant and the file first rather than repeating create directly.

revokeCopy Anchor Link

• Revocation is irreversible and requires --yes. It invalidates the subject's identity and unused enrollment keys at once. For what it affects, see Revocation.
• To bring it back, issue a new key, then run kibotos-node join or kibo context enroll.
• If you only want a node to stop accepting new Workspaces, use kibo node drain instead of revoking it.

The first OperatorCopy Anchor Link

When the cluster has no Operator yet, the ctrl host administrator issues the key with a local command:

sudo -u kibotos-ctrl kibotos-ctrl enrollment create \
  --config /etc/kibotos/ctrl/config.toml --operator operator-b \
  --output /var/lib/kibotos/ctrl/operator-b-enrollment.key

Use the same command to recover when the identities of all Operators are lost.