Skip to content

Initializing TKeeper

Tip

You can also init TKeeper from the control plane by visiting /ui.
Information described in this section is about initializing a keeper from the command line or programmatically.

You need tkeeper.system.init permission to run initialization.

Initialization is a one-time operation that binds a keeper node to a cluster configuration and prepares its local storage and sealing state.

Prerequisites

  • All keepers in the same cluster must use the same cluster threshold and cluster total settings (quorum parameters). A mismatch will prevent the cluster from operating correctly.
  • The caller must have the tkeeper.system.init permission to run initialization.

Initialize (System API)

Initialization is performed via:

  • POST /v1/keeper/system/init 
    {
  "peerId": 1,
  "threshold": 2,
  "total": 3
}

Fields descriptions:

  • peerId (int) - Intended keeper instance ID. MUST be unique and >=1 among all keepers in the cluster.
  • threshold (int) - Cluster threshold. MUST match the threshold used by all keepers in the cluster.
  • total (int) - Total keeper count in the cluster. MUST match the total used by all keepers in the cluster.

The request provides the initialization payload. The concrete payload shape depends on the sealing method.

Shamir sealing and returned shares

When the sealing provider is Shamir, initialization produces a set of unseal shares. Shamir initialization data is represented as:

  • threshold (int)
  • total (int)
  • shares64 (list of base64 strings)

Important distinction:

  • Cluster threshold/total: quorum parameters for distributed operations across keeper peers (t-of-n keepers).
  • Shamir threshold/total returned on init: parameters for unsealing shares of the unseal key only. They do not describe the keeper cluster quorum.

Warning

Treat shares64 as high-value recovery material. Loosing threshold count of shares will make keeper unsealing impossible.

Note

For non-Shamir sealing providers (AWS or Google), initialization does not return any shares (204 status code).

After initialization: sealing state and readiness

After initialization the keeper is ready to be unsealed and used.

Readiness endpoint

  • GET /v1/keeper/system/ready returns 204 only when the keeper is UNSEALED, otherwise 503.

Status endpoint

  • GET /v1/keeper/system/status returns the current state and unseal progress.
  • If the caller lacks tkeeper.system.unseal, the server returns sealedBy = null even when sealed.
  1. Start all keepers with the intended cluster configuration.
  2. Call init on each keeper once.
  3. If using Shamir sealing, store shares64 in an operator-controlled, offline location or distribute shares accross core team members.
  4. Unseal each keeper until it reports UNSEALED (readiness returns 204).
  5. Proceed with normal operations (key lifecycle, signing, encryption/decryption).

Tip

We recommend using Shamir sealing for production clusters.
Although it is possible to use cloud KMS, Shamir shares save you from vendor lock-in.