Forming orchestrator API requests

Instructions on interacting with this API.

By default, the orchestrator service listens on port 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.

Tip: The orchestrator API accepts well-formed HTTP(S) requests.

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"

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"

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" } }

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"