Basics of Orchestration API V1 in Puppet

Forming orchestrator API requests

The orchestrator API requires authentication and accepts properly formatted HTTPS requests.

The URI path for Orchestrator API queries must fit the following pattern:

https://<DNS>:8143/orchestrator/v1/<ENDPOINT>

The components of the variable route come from:

• DNS: The DNS name of your PE console host. You can use a puppet command, localhost, or manually type the DNS name (as explained in Using example commands).
   
• ENDPOINT: A section or sections that specify the endpoint, such as a command or a jobs section. Certain endpoints demand extra portions, such as POST /command/deploy.

Orchestrator API authentication

Requests to the orchestrator API must be authenticated using user authentication tokens. Visit Token-based authentication for information on how to create, configure, revoke, and delete authentication tokens in PE.

You can use the  puppet-access show to include a token in an orchestrator API call, for example:

Code:

auth_header="X-Authentication: $(puppet-access show)"
uri="https://$(puppet config print server):8143/orchestrator/v1/jobs"
curl --insecure --header "$auth_header" GET "$uri"

Root endpoints

You can use the orchestrator endpoint to obtain metadata from the orchestrator API

GET /orchestrator

It provides a list of connections to resources for application management as well as metadata about the orchestrator API.

Request format

The following is the request format for forming orchestrator API requests:

GET https://orchestrator.example.com:8143/orchestrator

The GET /orchestrator endpoint supports no parameters, but you still need to give authentication as with other orchestrator API endpoints.

Response format

The response is a JSON object with the following keys:

• info: It contains the title, description, licence details, and version compatibility warnings for the API.
   
• status: A URI route that you can use to check the status of the orchestrator API. Use the Status API to look up the status of the orchestrator services.
   
• collections: A number of endpoints, including the environments and jobs endpoints, can be accessed via collections of URI paths. You can learn which environments are available or whether a named environment is present from the environment endpoint response.
   
• commands: The Command endpoints' commands URI paths.
   

Let's look into the details of command endpoints. 

Command endpoints

You can use the command endpoints to start and stop running jobs, plans, and Puppet on demand. Additionally, you can make task-targets, granting permission escalation to users who would otherwise be unable to execute specific activities or tasks on specific nodes or node groups.

POST /command/deploy

You can execute Puppet on demand – and make the orchestrator available to all of the environment's nodes.

Request format

The content type of requests made to this endpoint using the Forming orchestrator API is application/json. The following table contains the keys that must be used in the body of the JSON object. There is always a need for the environment key. The values of other keys may determine whether additional keys are needed.

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"

Response format

The server returns 202 and a JSON object with the following keys if all node runs are successful and the environment is successfully deployed:

• id: A permanent web address that points to the recently created job.
   
• name: The newly created job is identified by a string field number. You can use this with other endpoints like POST /command/stop and GET /jobs/job-id> to receive information about a job's status.
   

Example:

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

POST /command/stop

It is used to stop the orchestrator job that is running right now.

Request format

The content type of requests made to this endpoint using the Forming orchestrator API is application/json. The body must contain a JSON object with a job key specifying the job ID of the task to be stopped, such as:

{
  "job": "1909"
}

Response format

If the job is successfully terminated, the server responds with 202 and returns a JSON object with the following keys:

• id: A permanent web address that points to the terminated job. This is based on the request's job key.
   
• Name: A number that uniquely identifies the stopped job.
   
• nodes: A hash of all possible node states, together with the number of nodes that are currently in each state.
   

Example:

{
  "job" : {
    "id" : "https://orchestrator.example.com:8143/orchestrator/v1/jobs/1909",
    "name" : "1909",
    "nodes" : {
      "new" : 2,
      "running" : 1,
      "failed" : 4,
      "errored" : 0,
      "skipped" : 4,
      "finished": 7
    }
  }
}

POST /command/task

On a group of nodes, run a task. Nodes in the defined scope that you do not have authority to run tasks on are excluded from the task's execution.

Request format

The content type of requests made to this endpoint using the Forming orchestrator API is application/json. The following table contains the keys that must be used in the body of the JSON object. The majority of keys must be used; however, certain keys may be empty or optional.

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

Response format

The server responds with 202 and a JSON object with the following keys if the task launches successfully:

• id: A permanent URL pointing to the recently established job. To get details about the job's status, use it in conjunction with the GET /jobs/job-id> endpoint.
   
• name: The newly established job's stringified identification number.
   

Example:

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

POST /command/task_target

It is used to create a task-target, which is a collection of tasks, nodes, and node groups you may use to grant users with a specified level of privilege escalation when they otherwise wouldn't be able to perform a given task or perform a task on a given node or node group. The user can execute the task(s) in the task-target on the set of nodes specified in the task-target when you give them permission to utilise it.

Request format

The content type of requests made to this endpoint using the Forming orchestrator API is application/json. A JSON object utilising these keys must make up the body.

Example:

{
  "display_name": "display_name",
  "tasks": ["task_1", "task_2"],
  "nodes": ["node1" "node2"],
  "node_groups": ["00000000-0000-4000-8000-000000000000"]
}

Response format

Upon successfully creating the task-target, the server issues a 200 response and returns a JSON object with the following keys:

• id: A permanent web address that points to the task-target. You can use it to acquire details about the task-target using the GET /scopes/task targets/task-target-id> endpoint.
   
• name: The special identification for the task-target.
   

Example:

{
  "task_target": {
    "id": "https://orchestrator.example.com:8143/orchestrator/v1/scopes/task_targets/1909",
    "name": "1909"
  }
}

POST /command/plan_run

You can run a plan using the plan executor.

Request format

The content type of requests made to this endpoint using the Forming orchestrator API is application/json. A JSON object utilising these keys must make up the body.

Example:

{
  "plan_name" : "ninjas",
  "description" : "Start the coding on node1 and node2",
  "params" : {
    "nodes" : ["node1.example.com", "node2.example.com"],
    "command" : "whoami",
    "canary" : 1
  }
}

Response format

If the plan starts off successfully, the server returns 202 and a JSON object with the name of the newly formed plan job.

Example:

{
  "name" : "1909"
}

Inventory endpoints

The inventory endpoints are used to determine whether the orchestrator can connect to a node. These endpoints are based on nodes that are linked to the PCP broker, a component of the Puppet orchestrator architecture.

GET /inventory

It is used to get a list of every node linked to the Puppet Communications Protocol (PCP) broker.

Request format

This endpoint receives simple calls from the Forming orchestrator API, like:

GET https://orchestrator.example.com:1909/orchestrator/v1/inventory

There are no parameters supported by the GET /inventory endpoint. However, you still need to give authentication like with other orchestrator API endpoints.

Response format

A JSON object with an array of nodes is the sign of an appropriate response. The following keys are used in response to give details about each node's PCP broker connection.

Example:

{
  "items" : [
    {
      "name" : "n1.example.com",
      "connected" : true,
      "broker" : "pcp://broker1.example.com/server",
      "timestamp": "2022-010-16T23:45:47.447Z"
    },
    
    {
      "name" : "n3.example.com",
      "connected" : false
    }
  ]
}

GET /inventory/<node>

It is used to obtain details regarding a certain node's association with the Puppet Communications Protocol (PCP) broker.

Request format

The URI path for Forming orchestrator API calls to this endpoint must contain a particular node name.

Example:

GET "https://orchestrator.example.com:8143/orchestrator/v1/inventory/<NODE_NAME>"

Response Format

A JSON object using these keys to provide details about the specified node's PCP broker connection is a sign of a successful response.

Example:

{
  "name" : "n1.example.com",
  "connected" : true,
  "broker" : "pcp://broker.example.com/server",
  "timestamp" : "2022-10-17T00:08:24.144Z"
}

POST /inventory

It returns details regarding connections made by various nodes to the Puppet Communications Protocol (PCP) broker.

Request format

The content type of requests made to this endpoint using the Forming orchestrator API is application/json. The body must contain a JSON object with an array of node names.

Example:

{
  "nodes" : [
    "node1.example.com",
  ]
}

Response format

A JSON object using these keys to convey details about each node's PCP broker connection constitutes a successful response:

Example:

{
  "items" : [
    {
      "name" : "node1.example.com",
      "connected" : false
    }
      ]
}

Frequently Asked Questions

What is the use of root endpoints?

You can use the orchestrator endpoint to obtain metadata from the orchestrator API.

What is the use of inventory endpoints?

The inventory endpoints are used to determine whether the orchestrator can connect to a node.

What is the use of a command endpoint?

The command endpoints are used to start and stop running jobs, plans, and Puppet on demand.

Conclusion

In this article, we have extensively discussed the details of the Basics of Orchestration API V1 in Puppet, along with the details of Orchestrator API authentication, Root endpoints, Command endpoints, and Inventory endpoints.

We hope that this blog has helped you enhance your knowledge regarding the Basics of Orchestration API V1 in Puppet, and if you would like to learn more, you can refer to our guided paths on the Coding Ninjas Studio platform to learn more about DSA, DBMS, Competitive Programming, Python, Java, JavaScript, etc. To practice and improve yourself in the interview, you can also check out Top 100 SQL problems, Interview experience, Coding interview questions, and the Utimate guide path for interviews. Do upvote our blog to help other ninjas grow. Happy Coding!!