Puppet orchestrator API: plans endpoint

This release was removed from general availability due to upgrade issues.
Docs for the latest available release are here.
This version is out of date. For current versions, see Puppet Enterprise support lifecycle.
Sections

Use the /plans endpoint to see all known plans in your environments.

GET /plans

List all known plans in a given environment.

Parameters

The request accepts the following query parameters:
Parameter Definition
environment Return the plans in a particular environment. Defaults to production.

Response format

The response is a JSON object that lists the known plans and where to find more information about them. It uses the following keys:
Key Definition
items Contains an array of all known plans for the specified environment.
environment A map containing the name key with the environment name and a code_id key indicating the code id the plans are listed from.
Note: code_id is always null.
Each item above has the following keys:
Key Definition
id An absolute URL to retrieve plan details.
name The full name of the plan.
permitted A boolean indicating if the user making the request is permitted to use the plan.

For example:

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

Error responses

For this endpoint, the kind key of the error displays the conflict.
Key Definition
puppetlabs.orchestrator/validation-error If the environment parameter is not a legal environment name, the server returns a 400 response.
puppetlabs.orchestrator/unknown-environment If the specified environment doesn't exist, the server returns a 404 response.

GET /plans/:module/:planname

Return data about the specified plan, including metadata.

Parameters

Parameter Definition
environment Return the plan from a particular environment. Defaults to production.
Note: code_id is always null.

Response format

The response is a JSON object that includes information about the specified plan. The following keys are used:
Key Definition
id An absolute URL to retrieve plan details.
name The full name of the plan.
environment A map containing a name key with the environment name and a code_id key indicating the code id the plan is being listed from.
permitted A boolean indicating if the user is permitted to use the plan or not.
metadata A map containing a description field with the plan's description, as well as a parameters map where keys are parameter names and values that map to type, default_value, and description.
type The type of the parameter, matches a puppet type. If no type is present for the parameter, defaults to {{Any`
default_value The default value of the parameter when it is not set. Optional.
description A description of the parameter. Optional.
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
}

Error responses

Key Definition
puppetlabs.orchestrator/validation-error If the environment parameter is not a legal environment name, or the module or plan name is invalid, the server returns a 400 response.
puppetlabs.orchestrator/unknown-environment If the specified environment doesn't exist, the server returns a 404 response.
puppetlabs.orchestrator/unknown-plan If the specified plan doesn't exist within that environment, the server returns a 404 response.
Puppet sites use proprietary and third-party cookies. By using our sites, you agree to our cookie policy.