Skip to main content

Admission

Admission decides which machines can join. When PKI is on, a new agent asks to join, and its request waits until an operator admits or rejects it. An admitted machine can be revoked later.

Methods​

MethodDescription
List(ctx, state)List the records; "" lists each state
Get(ctx, machineID)Get the record of one machine
Admit(ctx, machineID, fingerprint)Admit a pending machine
Reject(ctx, machineID, reason)Reject a pending machine
Revoke(ctx, machineID)Remove the key of an admitted machine
Delete(ctx, machineID)Remove a machine and each record of it

The state is pending, admitted, rejected or revoked.

Usage​

import "github.com/osapi-io/osapi/pkg/sdk/client"

c := client.New("http://localhost:8080", token)

// List the machines that wait for a decision
resp, err := c.Admission.List(ctx, "pending")
for _, a := range resp.Data.Items {
fmt.Printf("%s %s %s\n", a.MachineID, a.Hostname, a.Fingerprint)
}

// Admit, with the fingerprint that `osapi agent admission get` prints on the
// machine
err := c.Admission.Admit(ctx, "d530664edc1c431eb5ef1e9dfd6617a5", "SHA256:1f53dea6...")

// Reject, with the reason
err := c.Admission.Reject(ctx, "d530664edc1c431eb5ef1e9dfd6617a5", "unknown host")

// Revoke a machine that is not trusted: nothing that it signs verifies
// after this, and a record shows it if it asks again
err := c.Admission.Revoke(ctx, "d530664edc1c431eb5ef1e9dfd6617a5")

// Delete a machine that goes away on purpose, such as before a rebuild: it
// leaves no record, and is new if it asks again
err := c.Admission.Delete(ctx, "d530664edc1c431eb5ef1e9dfd6617a5")

Admit compares the fingerprint with the key in the request of the machine. A different fingerprint returns a ConflictError, and the machine stays pending. Read the fingerprint on the machine, not from List: the purpose of the check is to show that the request came from that machine.

Example​

Refer to examples/sdk/client/admission.go.

Types​

Admission​

FieldTypeDescription
MachineIDstringThe machine ID, the key of the record
HostnamestringThe hostname that the machine reported
FingerprintstringThe SHA256 fingerprint of the key of the machine
Statestringpending, admitted, rejected or revoked
OnlineboolThe agent reports now
LastSeen*time.TimeThe last report of the agent
RequestedAt*time.TimeWhen the machine asked to join
AdmittedAt*time.TimeWhen the machine was admitted
DecidedAt*time.TimeWhen the machine was rejected or revoked
ReasonstringWhy the machine was rejected
PreviousstringThe earlier state of a machine that asks again
PreviousFingerprintstringThe fingerprint of that earlier state

AdmissionList​

FieldTypeDescription
Items[]AdmissionThe records
TotalItemsintThe number of records

Permissions​

List and Get need admission:read. Admit, Reject, Revoke and Delete need admission:write, and return only an error: the API answers 204. When PKI is off, each method returns the 503 error of the API.