Plans endpoints

When Forming orchestrator API requests to this endpoint, you can use the default URI path to query plans in the production environment, such as:

https://orchestrator.example.com:8143/orchestrator/v1/plans

For any other environments, you must use the environment parameter to specify the environment whose plans you want to query. For example, this request queries plans in the development environment:

https://orchestrator.example.com:8143/orchestrator/v1/plans?environment=development

The environment object contains these keys:

• name: The environment specified in the request.
• code_id: Either null or a unique string. Puppet Server uses the code_id to retrieve the version of file resources in an environment at the time when a catalog was compiled. You can learn more about code_id in the Puppet Static catalogs documentation.

The items array contains one JSON object for each plan in the environment. Each plan object uses these keys:

Key	Definition
id	A URI path you can use with the GET /plans/<module>/<plan-name> endpoint to learn more about the plan.
name	The plan's name. You can use this with, for example, the POST /command/plan_run endpoint.
permitted	A Boolean indicating if you are permitted to run the plan.

For example, this response describes three plans in the production environment:

{
  "environment": {
    "name": "production",
    "code_id": null
  },
  "items": [
    {
      "id": "https://orchestrator.example.com:8143/orchestrator/v1/plans/profile/firewall",
      "name": "profile::firewall",
      "permitted": true
    },
    {
      "id": "https://orchestrator.example.com:8143/orchestrator/v1/plans/profile/rolling_update",
      "name": "profile::rolling_update",
      "permitted": true
    },
    {
      "id": "https://orchestrator.example.com:8143/orchestrator/v1/plans/canary/random",
      "name": "canary::random",
      "permitted": false
    }
  ]
}

If there is an error, Orchestrator API error responses provide error information in the kind key:

Response code	Key	Description
400	puppetlabs.orchestrator/validation-error	The environment parameter does not supply a legal environment name. For example, the name is not a string or contains illegal characters.
404	puppetlabs.orchestrator/unknown-environment	No environment exists that matches the specified environment.

When Forming orchestrator API requests to this endpoint, the URI path must include a specific module and plan name, such as:

GET "https://orchestrator.example.com:8143/orchestrator/v1/plans/profile/firewall"

Use the GET /plans endpoint to get module and plan names.

If a plan is available in multiple environments, you can append the environment parameter to retrieve details about the plan in a specific environment. If you do not specify this parameter, the endpoint uses the default value, which is production. For example, this request retrieves details about the firewall plan in the development environment:

GET "https://orchestrator.example.com:8143/orchestrator/v1/plans/profile/firewall?environment=development"

The response is a JSON object that uses these keys to provide information about the specified plan:

Key	Definition
id	The URI path identifying the module and plan, as supplied in the request.
name	The plan's name. You can use this with, for example, the POST /command/plan_run endpoint.
environment	A JSON object containing the name of the environment specified in the request and the code_id. The code_id is either null or a unique string that Puppet Server uses to retrieve the version of file resources in an environment at the time when a catalog was compiled. You can learn more about code_id in the Puppet Static catalogs documentation.
metadata	A JSON object that can be empty or contain a description of the plan and a parameters JSON object. The parameters object, if present, can use these keys: type: The required parameter type, as a valid Puppet type. If the parameter has no defined type, the value is Any. default_value: The parameter's default value. Omitted if the parameter has no default value. description: The parameter's description. Omitted if the parameter has no description. Tip: The parameters are determined by the plan's Parameters key.
permitted	A Boolean indicating if you are permitted to run the plan.

For example:

{
  "id": "https://orchestrator.example.com:8143/orchestrator/v1/plans/package/install",
  "name": "canary::random",
  "environment": {
    "name": "production",
    "code_id": null
  },
  "metadata": {},
  "permitted": true
}

If there is an error, Orchestrator API error responses provide error information in the kind key:

Response code	Key	Description
400	puppetlabs.orchestrator/validation-error	There is a problem with the format of the module name, plan name, or environment parameter in the request. For example, one of the values contains illegal characters.
404	puppetlabs.orchestrator/unknown-environment	No environment exists that matches the specified environment.
404	puppetlabs.orchestrator/unknown-plan	The endpoint can't find a match for the specified plan. There are several possible reasons for this, including: The endpoint can't find a valid relationship between the specified module and plan. The plan name is well-formed but doesn't match any existing plans. There is no such plan in the specified environment. For example, a plan that only exists in the development environment returns 404 if the request specified a different environment or used the default environment value.