Approve a deploy

A release that reaches a spacecraft is hard to take back, so a mission usually wants a second person to agree before it goes up. SpaceOS records every deploy in the published phase and sends nothing until the target's approvers sign a decision. Each decision covers one deploy and one artifact digest.

Three things decide who may approve:

The operator authority is the key pair every approval roots in. The computer that keeps it creates it once.
An operator identity is one person's certificate and private key, issued under the authority.
The target's registration names the identities that approve deploys to it, and the quorum, the number of them who must sign.

A target that one operator runs alone needs none of this. Its registration records the one operator identity the computer holds as the sole approver, and a deploy that identity publishes is approved in the same command.

This guide sets up a target with two approvers, Alice and Bob, and a quorum of two. Alice holds the operator authority.

Create the operator authority

On Alice's computer, create the authority and issue her identity:

$ space keys ca
✓ Created the operator authority
  certificate: /tmp/space-docs/config/keys/operator-ca.crt.pem
  key: /tmp/space-docs/config/keys/operator-ca.key.pem
  sha256: ...
  issue with: space keys issue NAME
$ space keys issue alice
✓ Issued an operator identity
  subject: alice
  certificate: /tmp/space-docs/config/keys/operator.alice.crt.pem
  key: /tmp/space-docs/config/keys/operator.alice.key.pem
  sha256: ...
  decide with: space deploy approve TARGET VERSION --as alice

space keys ca creates the authority once. Run again, it shows the authority that exists and mints nothing. space keys ls lists the authority and the identities under it.

Enroll a second operator

Bob's private key never leaves his computer. He draws it there and sends Alice a certification request. The transcripts below set SPACE_CONFIG on Bob's commands so that they read a configuration of his own. On his own computer, Bob runs the same commands without it.

On Bob's computer, draw the key and write the request:

$ SPACE_CONFIG=/tmp/space-docs/bob/space.toml space keys request bob --out bob.csr
✓ Drew an operator key and the request that asks for its certificate
  subject: bob
  request: bob.csr
  request sha256: ...
  key: /tmp/space-docs/bob/keys/operator.bob.key.pem
  certify with: space keys certify FILE --out FILE
  then file with: space keys install FILE

Bob sends bob.csr to Alice and reads her the request sha256 value over a different channel, such as a call. On Alice's computer, certify the request and check that the value she prints matches the one Bob read:

$ space keys certify bob.csr --out bob.crt.pem
✓ Certified an operator identity under this authority
  subject: bob
  request sha256: ...
  certificate: bob.crt.pem
  authority: /tmp/space-docs/config/keys/operator-ca.crt.pem
  registered: /tmp/space-docs/config/keys/operator-ca.certified.bob.json
  file it with: space keys install FILE

The authority certifies each name once. A second request under the name bob is refused, because the approval gate counts approvers by name.

Alice sends bob.crt.pem back. On Bob's computer, file it beside his key:

$ SPACE_CONFIG=/tmp/space-docs/bob/space.toml space keys install bob.crt.pem
✓ Filed an operator identity certified elsewhere
  subject: bob
  certificate: /tmp/space-docs/bob/keys/operator.bob.crt.pem
  key: /tmp/space-docs/bob/keys/operator.bob.key.pem
  decide with: space deploy approve --record FILE --as bob --out FILE

Name the target's approvers

The approvers a registration names also sign the registration. Alice writes the new registration to a file and Bob signs it. Alice then records it:

$ space target connect sat-42 --profile cm5-dev --approver alice --approver bob --quorum 2 --out sat-42.reg
sat-42 registration version 1: 2 of alice, bob, written to sat-42.reg
Each approver still to sign runs `space target sign sat-42.reg --as NAME`, and `space target connect sat-42 --registration sat-42.reg` records it
$ SPACE_CONFIG=/tmp/space-docs/bob/space.toml space target sign sat-42.reg --as bob
sat-42 registration version 1: 2 of alice, bob, signed by alice, bob
$ space target connect sat-42 --profile cm5-dev --registration sat-42.reg
✓ sat-42 registered: cm5-dev, local
$ space target show sat-42 | sed -n '/^approvers/,/^quorum/p'
approvers    : alice, bob
quorum       : 2

--quorum ranges from 1 to the number of approvers, and every approver must sign when you omit it. A decision counts only under the registration version it was signed under.

Approve a published deploy

Alice deploys a release to the target. The deploy stops in the published phase and waits for two decisions:

space deploy payload:release --target sat-42
space show sat-42 v1

Bob's computer does not hold Alice's deploy store, so Alice writes the record to a file and sends it:

space show sat-42 v1 --json > sat-42-v1.json

On Bob's computer, sign a decision on that record. The command admits nothing; it writes Bob's decision to a file:

space deploy approve --record sat-42-v1.json --as bob --out bob.approval

Bob sends bob.approval back. On Alice's computer, sign her own decision and present Bob's with it:

space deploy approve sat-42 v1 --as alice --approval bob.approval

The deploy moves to approved once the quorum of approvers named in the registration has signed this deploy and its artifact digest. The identity that published the deploy never counts toward the quorum. Every condition the gate cannot establish is refused with what it saw, and nothing is recorded.

Hold, release, or reject

An operator can take an approved deploy off the uplink queue and put it back later:

space deploy hold sat-42 v1 --reason "wait for the thermal review"
space deploy release sat-42 v1

space deploy release returns a held deploy to the queue. It cannot admit a deploy that was never approved. To stop a deploy for good, reject it:

space deploy reject sat-42 v1 --reason "superseded by v2"

A rejected deploy cannot be approved again. Deployment states lists every phase a deploy passes through.