Puppet orchestrator API: command endpoint

Request format

The request body must be a JSON object using these keys:

For example, to deploy the node1.example.com environment in no-op mode, the following request is valid:

{
  "environment" : "",
  "noop" : true,
  "scope" : {
    "nodes" : ["node1.example.com"]
  }
}

Scope

Scope is a JSON object containing exactly one of these keys:

To deploy an application instance in the production environment:

{
  "environment" : "production",
  "scope" : {
    "application" : "Wordpress_app[demo]"
  }
}

To deploy a list of nodes:

{
  "environment" : "production",
  "scope" : {
    "nodes" : ["node1.example.com", "node2.example.com"]
  }
}

To deploy a list of nodes with the certname value matching a regex:

{
  "environment" : "production",
  "scope" : {
    "query" : ["from", "nodes", ["~", "certname", ".*"]]
  }
}

To deploy to the nodes defined by the "All Nodes" node group:

{
  "environment" : "production",
  "scope" : {
    "node_group" : "00000000-0000-4000-8000-000000000000"
  }
}

Response format

If all node runs succeed, and the environment is successfully deployed, the server returns a 202 response.

The response is a JSON object containing a link to retrieve information about the status of the job and uses any one of these keys:

For example:

{
  "job" : {
    "id" : "https://orchestrator.example.com:8143/orchestrator/v1/jobs/1234"
    "name" : "1234"
  }
}

Error responses

For this endpoint, the kind key of the error displays the conflict.

The job transitions to status stopped when all pending agent runs have finished.

This command is idempotent: it can be issued against the same job any number of times.

Request format

The JSON body of the request must contain the ID of the job to stop. The job ID is the same value as the name property returned with the deploy command.

• job: the name of the job to stop.

For example:

{
  "job": "1234"
}

Response format

If the job is stopped successfully, the server returns a 202 response. The response uses these keys:

For example:

{
  "job" : {
    "id" : "https://orchestrator.example.com:8143/orchestrator/v1/jobs/1234",
    "name" : "1234",
    "nodes" : {
      "new" : 5,
      "running" : 8,
      "failed"  : 3,
      "errored" : 1,
      "skipped" : 2,
      "finished": 5
    }
  }
}

Error responses

For this endpoint, the kind key of the error displays the conflict.

Request format

The request body must be a JSON object and uses the following keys:

For example, to run the package task on node1.example.com, the following request is valid:

{
  "environment" : "test-env-1",
  "task" : "package",
  "params" : {
    "action" : "install",
    "name" : "httpd"
  },
  "scope" : {
    "nodes" : ["node1.example.com"]
  }
}

Scope

Scope is a JSON object containing exactly one of the following keys:

To deploy an application instance in the production environment, the following request is valid:

{
  "environment" : "production",
  "scope" : {
    "application" : "Wordpress_app[demo]"
  }
}

{
  "environment" : "production",
  "scope" : {
    "nodes" : ["node1.example.com", "node2.example.com"]
  }
}

{
  "environment" : "production",
  "scope" : {
    "query" : ["from", "nodes", ["~", "certname", ".*"]]
  }
}

{
  "environment" : "production",
  "scope" : {
    "node_group" : "00000000-0000-4000-8000-000000000000"
  }
}

Response format

If the task is starts successfully, the response will have a 202 status.

Error responses

For this endpoint, the kind key of the error displays the conflict.

Request format

The request body must be a JSON object and uses the following keys:

For example, to run the package task on node1.example.com, the following request is valid:

{
  "environment" : "test-env-1",
  "task" : "package",
  "params" : {
    "action" : "install",
    "package" : "httpd"
  },
  "scope" : {
    "nodes" : ["node1.example.com"]
  },
  "scheduled_time" : "2027-05-05T19:50:08Z"
}

Response format

If the task schedules successfully the server returns 202.

The response is a JSON object containing a link to retrieve information about the status of the job. The keys of this object are

• id: an absolute URL that links to the newly created job.
• name: the name of the newly created job.

{
  "scheduled_job" : {
    "id" : "https://orchestrator.example.com:8143/orchestrator/v1/scheduled_jobs/2",
    "name" : "1234"
  }
}

Error responses

For this endpoint, the kind key of the error displays the conflict.