User-Provided Metadata
Occasionally you might want to add additional information to your Runs which isn’t handled on a first-class basis by Spacelift. You can attach this kind of information using the run metadata parameter, which is available through spacectl as well as the GraphQL API.

Usage

Let’s start with a small example. You’ll need a private worker for this.
On the machine where the worker resides, create a simple policy in a file:
1
package spacelift
2
sample { true }
Copied!
And then start the worker with an additional environment variable:
1
SPACELIFT_LAUNCHER_RUN_INITIALIZATION_POLICY=/path/to/your/policy.rego
Copied!
This policy will make our launcher sample each initialization policy evaluation and print it as a log on stderr.
We’ll also need a Stack to which this worker is attached.
We can now trigger a run and provide an arbitrary metadata string:
1
~> spacectl stack deploy --id testing-spacelift --run-metadata "deploy-metadata"
2
You have successfully created a deployment
3
The live run can be visited at http://cube2222.app.spacelift.tf/stack/testing-spacelift/run/01FEKAGP4AYV0DWP4QDFTANRES
Copied!
And in the private worker logs we should suitably see (formatted for readability):
1
{
2
"caller": "setup.go:201",
3
"level": "info",
4
"msg": "Sample 0/INITIALIZATION/7YGHCNF7W6VMBQ49XQ42MH4JD1/allow",
5
"sample": {
6
"body": "package spacelift\nsample { true }\n",
7
"input": {
8
"docker_image": "",
9
"run": {
10
"based_on_local_workspace": false,
11
"changes": [],
12
"commit": {
13
"author": "cube2222",
14
"branch": "master",
15
"created_at": 1628243895000000000,
16
"message": "Update main.tf"
17
},
18
"created_at": 1630588655754344000,
19
"id": "01FEKAGP4AYV0DWP4QDFTANRES",
20
"state": "PREPARING",
21
"triggered_by": "api::01FEGXFB7TWQ2NNF95W7HPRE2E",
22
"updated_at": 1630588656197898500,
23
"user_provided_metadata": [ // <------------------
24
"deploy-metadata". // <-- the metadata --
25
] // <------------------
26
},
27
"static_run_environment": {
28
"account_name": "cube2222",
29
"auto_deploy": false,
30
"before_apply": null,
31
"before_init": null,
32
"command": "",
33
"commit_branch": "master",
34
"commit_sha": "7d629c6c3f3b6da07e28a87727f0586e577d98c1",
35
"endpoint_logs": "tcp://169.254.0.3:1983",
36
"endpoint_registry": "registry.spacelift.io",
37
"environment_variables": {},
38
"project_root": "",
39
"refresh_state": true,
40
"repository_path": "cube2222/testing-spacelift",
41
"run_type": "TRACKED",
42
"run_ulid": "01FEKAGP4AYV0DWP4QDFTANRES",
43
"skip_init": false,
44
"stack_labels": null,
45
"stack_slug": "testing-spacelift",
46
"terraform_version": "0.14.10",
47
"vendor_specific_config": {
48
"vendor": "terraform",
49
"typed_config": {
50
"use_terragrunt": false,
51
"use_infracost": false
52
}
53
}
54
},
55
"worker_version": "development"
56
},
57
"outcome": "allow",
58
"results": {
59
"deny": [],
60
"sample": true
61
},
62
"error": ""
63
},
64
"ts": "2021-09-02T13:17:37.785219048Z"
65
}
Copied!
Great!
We can now go ahead and confirm this run:
1
~> spacectl stack confirm --id testing-spacelift --run-metadata "confirm-metadata" --run 01FEKAGP4AYV0DWP4QDFTANRES
2
You have successfully confirmed a deployment
3
The live run can be visited at http://cube2222.app.spacelift.tf/stack/testing-spacelift/run/01FEKAGP4AYV0DWP4QDFTANRES
Copied!
In the policy sample log for the relevant metadata key we’ll see an additional entry, which was added when confirming:
1
"user_provided_metadata": [
2
"deploy-metadata",
3
"confirm-metadata"
4
]
Copied!
And that's basically it! It's a very flexible building block which lets you build various automation and compliance helper tooling.

Run signatures

A standard use case for this feature would be to sign your runs when you’re creating them.
You'll have to bring the infrastructure for managing keys and signatures yourself - usually you'll already have something like that internally. But in short you can create a cryptographic signature of the parameters for a run you’re about to create - based on the commit SHA, run type, stack, date, etc. - and then you can pass that signature to Spacelift when creating the run.
Later, in the initialization policy you can use the exec function to run your custom binary for verifying that signature. This way - for your most sensitive stacks - you can verify whether runs you are receiving from the Spacelift backend are legit, intentionally created by an employee of your company.
Last modified 1mo ago
Copy link