Skip to content

uri

Makes one HTTP call from the host when the step is first applied, and again whenever its arguments or triggers change, such as registering the host with a load balancer after a deploy. A refresh doesn’t call it.

Use uri to make one HTTP call from the host as part of a rollout: register it with a load balancer, tell a monitoring system a deploy happened, post to a chat webhook. It’s ansible.builtin.uri for a call. To wait for an app to answer, use wait_for with url instead.

Register the host once, with a token kept out of state:

step "register" {
uri {
url = "https://lb.example.com/api/backends"
method = "POST"
headers = { "Content-Type" = "application/json" }
headers_wo = { Authorization = "Bearer use-an-ephemeral-value-here" }
body = jsonencode({ host = "web1", port = 8080 })
status_codes = [200, 201]
}
}

Tell a webhook each time the app’s version changes:

step "announce" {
uri {
url = "http://127.0.0.1:9000/hooks/deployed"
method = "POST"
body = "deployed"
triggers = { version = "1.4.2" }
}
}
Name Type Required Description
body string One of The request body, such as jsonencode({ host = “web1” }).
body_wo string One of The body, kept out of plan and state. Set this or body.
headers map of string No Request headers, such as { “Content-Type” = “application/json” }.
headers_wo map of string No Headers kept out of plan and state, such as an Authorization header. A change to them doesn’t call again on its own: put a version of the secret in triggers for that.
method string No GET (default), POST, PUT, PATCH, DELETE or HEAD.
skip_tls_verify bool No true accepts any certificate for an https:// url.
status_codes list of number No The answers that count as success. Defaults to [200]. Redirects are followed first.
triggers dynamic No Any value; the call is made again whenever it changes.
url string Yes An http:// or https:// URL. The request is the host’s: it goes through the SSH connection and leaves from the host, so 127.0.0.1 is the host, and it needs no curl there.

Conn3x sets these; reference them as conn3x_uri.<circuit>__<step>["<host>"].<name>.

Name Type Description
response string The first MiB of the answer’s body. Marked sensitive, since an API’s answer often holds a token.
status number The status the call got.

A step lowers to the conn3x_uri resource, one instance per host, and connects with its circuit’s ssh block.

When it calls. The first apply makes the call. After that, a change to any argument, or to triggers, makes it again. A refresh never calls, since a call leaves nothing on the host to read, and a plan with nothing changed shows nothing. headers_wo and body_wo can’t be compared, since they’re never stored, so put a version of the secret in triggers to call again when it changes.

From the host. The request goes through the SSH connection as a forwarded TCP connection that sshd opens on the host, as wait_for’s url does. 127.0.0.1 is the host’s loopback, a name resolves through the host’s DNS, and the host needs no curl. Redirects are followed, https:// checks the certificate unless skip_tls_verify is true, and no proxy set on this machine is used. A call can take 30 seconds.

Success. The step fails when the answer’s status isn’t in status_codes, [200] by default, and the error names the status. status and response, the first MiB of the body, are kept, and response is marked sensitive, since an API’s answer often holds a token.

Secrets. headers_wo and body_wo reach the host’s request and nowhere else: not the plan, not state. Set body or body_wo, not both.

Deleting a uri step calls nothing. To undo what a call did, such as taking the host out of the load balancer, add a step that makes that call.