Forming orchestrator API requests
Sections
Instructions on interacting with this API.
8143
, and all endpoints are relative to the /orchestrator/v1
path. So, for example, the full URL for the
jobs
endpoint on localhost would be https://localhost:8143/orchestrator/v1/jobs
.Authenticating to the orchestrator API with a token
You need to authenticate requests to the orchestrators’s API. You can do this using user authentication tokens.
For detailed information about authentication tokens, see Token-based authentication. The following example shows how to use a token in an API request.
To use the jobs
endpoint of the orchestrator API to get a list of all jobs
that exist in the orchestrator, along with their associated metadata, you'd first generate a
token with the puppet-access tool. You'd then copy that token and replace
<TOKEN>
with that string in the following request:
auth_header="X-Authentication: $(puppet-access show)"
uri="https://$(puppet config print server):8143/orchestrator/v1/jobs"
curl --insecure --header "$auth_header" "$uri"
Copied!
See Usage notes for curl examples for information about forming curl commands.
Example token usage: deploy an environment
If you want to deploy an environment with the orchestrator's API, you can form a request with the token you generated earlier. For example:
type_header='Content-Type: application/json'
auth_header="X-Authentication: $(puppet-access show)"
uri="https://$(puppet config print server):8143/orchestrator/v1/command/deploy"
data='{"environment": "production", "scope" : { "node_group" : "00000000-0000-4000-8000-000000000000" }}'
curl --insecure --header "$type_header" --header "$auth_header" --request POST "$uri" --data "$data"
Copied!
This returns a JSON structure that includes a link to the new job started by the orchestrator.
{
"job" : {
"id" : "https://orchestrator.vm:8143/orchestrator/v1/jobs/81",
"name" : "81"
}
}
Copied!
You can make an additional request to get more information about the job. For example:
auth_header="X-Authentication: $(puppet-access show)"
uri="https://$(puppet config print server):8143/orchestrator/v1/jobs/81"
curl --insecure --header "$auth_header" "$uri"
Copied!