Scripting deploy.sh with --json
Add --json to any deploy.sh command to drive it from a script, a CI job or an agent. Stdout then holds one JSON object per line and nothing else. Everything meant for a person, such as Terraform's and Docker's output, goes to stderr.
./scripts/deploy.sh deploy --config <file> --json > events.ndjson
Every event names its step and its status. Read stdout line by line, parse each line, and act on the steps you need. Skip steps you don't know, because new ones are added over time.
{"step": "start", "status": "ok", "command": "deploy", "cloud": "gcp", "tee": "sev-snp-svsm", "project": "my-project", "tag": "v1.4.0"}
{"step": "terraform_plan", "status": "ok", "summary": "Plan: 14 to add, 0 to change, 0 to destroy."}
{"step": "warning", "status": "warn", "message": "..."}
{"step": "complete", "status": "ok", "cloud": "gcp", "endpoint": "https://203.0.113.7", "...": "..."}
The schema
schemas/deploy-events.schema.yaml lists every step, the statuses it can have and its fields. It is a JSON Schema, so you can validate each line against it. A test in CI fails when deploy.sh emits a step, status or field the schema doesn't list.
A field's value is a string unless the schema gives it another type. Numbers such as restarts are strings too. A field can be missing when deploy.sh had no value for it.
A few fields carry JSON from elsewhere, such as the instance list in status. If that JSON doesn't parse, the field is null, and the text is in an unparsed object under the field's name.
How a run ends
A run that succeeds exits 0. deploy, up and up-polaris end with a complete event, and the other commands with an event of their own, such as status or promote.
A run that fails exits non-zero, and most failures end with an error event. The event's class says what kind of failure it was, and so does the exit code. status is the exception, described below.
| Exit code | class | What failed |
|---|---|---|
| 1 | failed | Anything not in the rows below |
| 2 | usage | A flag or config value is wrong or missing |
| 3 | prerequisite | Something --preflight checks, such as a tool, a cloud login, a base image or a KMS key |
| 4 | cloud | terraform init, plan or apply |
| 5 | health | The Policy Manager or the proxy never came up |
| 6 | pm_unreachable | A command that needs the Policy Manager couldn't reach it |
{"step": "error", "status": "failed", "message": "Unknown option: --bogus", "class": "usage", "exit_code": 2}
A cloud or health failure may pass on a second try. A usage or prerequisite failure won't until the input or the machine has changed.
A run stopped by a signal exits 128 plus the signal's number, such as 130 for Ctrl-C, and writes no error event.
Warnings
Under --json, every warning is a warning event with a message. Some warnings also have a step of their own, such as azure_pm_replaced_alone, so a script can match on them. Their status is warn.
The deploy result
deploy, up and up-polaris end with a complete event. On a cloud it carries what you need to use the deployment:
| Field | What it is |
|---|---|
endpoint | The workload's attested HTTPS endpoint |
management_token | The Policy Manager's management token |
readonly_token | A read-only token for the Policy Manager |
workload_token | The token for swapping the workload with set-workload |
deployment_id | The deployment's id |
cloud, tee_type, region, zone, project_id | Where it runs |
cvm_external_ip, pm_internal_ip, cvm_instance_id, pm_instance_id | The two VMs |
pm_identity | The PM's identity record, an object, when deploy could check it. On aws-sev, gcp-sev-direct and svsm it carries pm_identity_pubkey, base64 of the SPKI DER of the PM's identity key, when the deployment has one. On Azure it can also carry cvm, what Desktop checks the first CVM's proxy against before it sends an ID token on the tunnel's CONNECT: platform, vm_unique_id, pcrs_sha256 (boot PCRs 0 to 9) and id_key_digests or mr_tds. Other platforms write no cvm, and Desktop then sends no ID token |
On-prem, complete names the artifact set instead, in artifact_dir.
The three token fields are credentials. The schema marks them x-polaris-secret. Keep them out of logs, and store them the way you store other secrets.
destroy on a cloud ends with {"step": "complete", "status": "ok", "action": "destroy", "cloud": "..."}. On-prem it ends with a destroy event.
Status
status --json prints a status event. instances is the cloud's list of VMs. pm_status holds the Policy Manager's verdict for each workload VM, pm_convergence its autolearn progress, and pm_license its license.
pm_reachable says whether the Policy Manager answered. When it is false, pm_unreachable_reason says why, for example that there is no SSH route to it. Both are null in hardware mode, which has no Policy Manager, and in a dry run.
status exits 0 when it could list the VMs, even if the Policy Manager wasn't read. It exits 1 in two cases, with no error event:
- It couldn't list the VMs. The
statusevent's status iserror. - On GCP, the Policy Manager's launch measurement no longer matches the one the workload VM pins. The status is
failed, andpm_measurementsays what was found.