Mint a join code (bootstrap-admin).
curl --request POST \ --url https://stratum.example.com/v1/admin/cluster/join-codes \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "ttlSeconds": 1, "endpoint": "192.0.2.240" }'. A joiner is given the endpoint (the API VIP
or a control-plane member’s address; port 9444 implied) and a short
code, 10 characters and a check character, shown XXXX-XXXX-XXX. The
code is proven to the join listener by a PAKE (OPAQUE) bound to the TLS
connection, which also proves the listener to the joiner, so it carries
no CA fingerprint. It is shown once, in this response; only its OPAQUE
record is stored.
Reusable until it expires (4 hours by default, at most 7 days) or is
revoked. While any code is live, every control-plane member opens the
join listener (TLS, port 9444, a cluster-CA certificate for its
addresses and the API VIP); it closes when the last one expires or is
revoked. Audited (cluster.join_code.minted). Gates on
ha:MintJoinToken.
Authorizations
Section titled “Authorizations”Request Body
Section titled “Request Body”A join code request.
object
Lifetime. 4 hours by default, at most 7 days.
Where joiners reach the cluster, host or host:port. Default: the API
VIP. Any control-plane member’s management address may be named
instead. The port defaults to the join listener’s (9444).
Example
192.0.2.240Responses
Section titled “Responses”The code, shown once.
A freshly minted join code. code and url are shown once: only the
code’s OPAQUE record is stored. Give the joining machine endpoint and
code (stage 1’s two fields, or install.yaml join.endpoint and
join.code), or url alone (a QR code, a paste).
object
A join code: what a joining machine proves to the cluster’s join listener with a PAKE. Only its OPAQUE record is stored; the code itself is shown once, in the response that mints it. Reusable until it expires or is revoked: one code serves every node of a batch, because the approval is the gate, not the code.
object
The code’s first two characters, which pick it among the cluster’s codes. Not secret on its own (10 of the code’s 50 bits); shown so a list can tell codes apart.
PAKE exchanges started with this code and not proven. Past 10 the code
is burned: revoked by system:too-many-attempts.
The join listener the code points at, host:port.
The SHA-256 of the cluster root CA (DER) the code’s PAKE keys derive
from, as hex pairs. A CA rotation ends the code (JOIN_CODE_STALE). A
joiner learns the CA through the PAKE and pins it.
live until it expires or is revoked.
Who revoked it; system:too-many-attempts for a burned code.
How many machines registered with this code.
Where joiners reach the join listener, as they type it: the host alone
when the port is the default 9444, else host:port.
The code: 10 Crockford base32 characters and a check character (Luhn mod 32) that catches a typo on the joiner, in groups of four. Case, dashes and spaces do not matter; O reads as 0, I and L as 1.
The endpoint and the code as one string, also for a QR code.
Example
{ "joinCode": { "id": "jc-4f7k2q9m", "selector": "4F", "endpoint": "192.0.2.240:9444", "caFingerprint": "7D:9F:05:39:12:F6:D4:91:0A:1B:2C:3D:4E:5F:60:71:82:93:A4:B5:C6:D7:E8:F9:0A:1B:2C:3D:4E:5F:60:71", "state": "live" }, "endpoint": "192.0.2.240", "code": "4F7K-2Q9M-ABD", "url": "stratum-join://192.0.2.240/4F7K-2Q9M-ABD"}Bad request.
object
The findings of a rejected IAM policy document (custom and resource policies).
One finding of a rejected IAM policy document. A rejection lists every finding, so the author fixes the document in one round trip.
object
The finding, e.g. INVALID_DOCUMENT, UNKNOWN_ACTION, ACTION_NOT_APPLICABLE.
Index of the statement at fault; -1 for the document as a whole.
The offending action, where one is at fault (ACTION_NOT_APPLICABLE).
Field errors, for codes that carry them: each problem at its field
(see FieldError). Documented on the responses that set it, e.g.
approveNodeJoin’s INVALID_INPUT and JOIN_APPROVAL_REFUSED.
Absent otherwise.
One field’s problem, the stage-2 installer API’s shape.
field is the field’s path, message what is wrong with it.
object
The field’s path, e.g. links[0].interface, disks[1].confirm,
mgmt.address or role; empty for the whole request.
Structured facts about the refusal, for codes that carry them. The
shape is fixed per code and documented on the response that answers
it, e.g. IMAGE_POOL_MISMATCH (see ImagePoolMismatchDetails) and
IMAGE_IN_USE. Absent for codes that carry none.
object
Example
{ "issues": [ { "code": "ACTION_NOT_APPLICABLE", "action": "compute:CreateVpc" } ]}Authenticated but not authorized.
object
The findings of a rejected IAM policy document (custom and resource policies).
One finding of a rejected IAM policy document. A rejection lists every finding, so the author fixes the document in one round trip.
object
The finding, e.g. INVALID_DOCUMENT, UNKNOWN_ACTION, ACTION_NOT_APPLICABLE.
Index of the statement at fault; -1 for the document as a whole.
The offending action, where one is at fault (ACTION_NOT_APPLICABLE).
Field errors, for codes that carry them: each problem at its field
(see FieldError). Documented on the responses that set it, e.g.
approveNodeJoin’s INVALID_INPUT and JOIN_APPROVAL_REFUSED.
Absent otherwise.
One field’s problem, the stage-2 installer API’s shape.
field is the field’s path, message what is wrong with it.
object
The field’s path, e.g. links[0].interface, disks[1].confirm,
mgmt.address or role; empty for the whole request.
Structured facts about the refusal, for codes that carry them. The
shape is fixed per code and documented on the response that answers
it, e.g. IMAGE_POOL_MISMATCH (see ImagePoolMismatchDetails) and
IMAGE_IN_USE. Absent for codes that carry none.
object
Example
{ "issues": [ { "code": "ACTION_NOT_APPLICABLE", "action": "compute:CreateVpc" } ]}Conflicting state.
object
The findings of a rejected IAM policy document (custom and resource policies).
One finding of a rejected IAM policy document. A rejection lists every finding, so the author fixes the document in one round trip.
object
The finding, e.g. INVALID_DOCUMENT, UNKNOWN_ACTION, ACTION_NOT_APPLICABLE.
Index of the statement at fault; -1 for the document as a whole.
The offending action, where one is at fault (ACTION_NOT_APPLICABLE).
Field errors, for codes that carry them: each problem at its field
(see FieldError). Documented on the responses that set it, e.g.
approveNodeJoin’s INVALID_INPUT and JOIN_APPROVAL_REFUSED.
Absent otherwise.
One field’s problem, the stage-2 installer API’s shape.
field is the field’s path, message what is wrong with it.
object
The field’s path, e.g. links[0].interface, disks[1].confirm,
mgmt.address or role; empty for the whole request.
Structured facts about the refusal, for codes that carry them. The
shape is fixed per code and documented on the response that answers
it, e.g. IMAGE_POOL_MISMATCH (see ImagePoolMismatchDetails) and
IMAGE_IN_USE. Absent for codes that carry none.
object
Example
{ "issues": [ { "code": "ACTION_NOT_APPLICABLE", "action": "compute:CreateVpc" } ]}Upstream temporarily unavailable (driver / scheduler / dependency).
object
The findings of a rejected IAM policy document (custom and resource policies).
One finding of a rejected IAM policy document. A rejection lists every finding, so the author fixes the document in one round trip.
object
The finding, e.g. INVALID_DOCUMENT, UNKNOWN_ACTION, ACTION_NOT_APPLICABLE.
Index of the statement at fault; -1 for the document as a whole.
The offending action, where one is at fault (ACTION_NOT_APPLICABLE).
Field errors, for codes that carry them: each problem at its field
(see FieldError). Documented on the responses that set it, e.g.
approveNodeJoin’s INVALID_INPUT and JOIN_APPROVAL_REFUSED.
Absent otherwise.
One field’s problem, the stage-2 installer API’s shape.
field is the field’s path, message what is wrong with it.
object
The field’s path, e.g. links[0].interface, disks[1].confirm,
mgmt.address or role; empty for the whole request.
Structured facts about the refusal, for codes that carry them. The
shape is fixed per code and documented on the response that answers
it, e.g. IMAGE_POOL_MISMATCH (see ImagePoolMismatchDetails) and
IMAGE_IN_USE. Absent for codes that carry none.
object
Example
{ "issues": [ { "code": "ACTION_NOT_APPLICABLE", "action": "compute:CreateVpc" } ]}