Forming orchestrator API requests

This version is out of date. For current versions, see Puppet Enterprise support lifecycle.

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"
Puppet sites use proprietary and third-party cookies. By using our sites, you agree to our cookie policy.