Tasks endpoints

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

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

For any other environments, you must use the environment parameter to specify the environment whose tasks you want to query. For example, this request queries tasks 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 specifying where the environment's tasks are listed. 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 task in the environment. Each task object uses these keys:

Key	Definition
id	A URI path you can use with the GET /tasks/<module>/<task-name> endpoint to learn more about the task.
name	A stringified number identifying the task. You can use this with, for example, the POST /command/task endpoint.

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

{
  "environment": {
    "name": "production",
    "code_id": "urn:puppet:code-id:1:a86da166c30f871823f9b2ea224796e834840676;production"
  },
  "items": [
    {
      "id": "https://orchestrator.example.com:8143/orchestrator/v1/tasks/package/install",
      "name": "package::install"
    },
    {
      "id": "https://orchestrator.example.com:8143/orchestrator/v1/tasks/package/upgrade",
      "name": "package::upgrade"
    },
    {
      "id": "https://orchestrator.example.com:8143/orchestrator/v1/tasks/exec/init",
      "name": "exec"
    }
  ]
}

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 task name, such as:

GET "https://orchestrator.example.com:8143/orchestrator/v1/tasks/package/install"

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

To request a module's default task, use init as the task name, such as:

GET "https://orchestrator.example.com:8143/orchestrator/v1/tasks/package/init"

If a task is available in multiple environments, you can append the environment parameter to retrieve details about the task 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 install task in the development environment:

GET "https://orchestrator.example.com:8143/orchestrator/v1/tasks/package/install?environment=development"

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

Key	Definition
id	The URI path identifying the module and task, as supplied in the request.
name	A stringified number identifying the task. You can use this with, for example, the POST /command/task endpoint.
environment	A JSON object containing the name of the environment specified in the request and the code_id. code_id is either null or a unique string specifying where the environment's tasks are listed. 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.
metadata	A JSON object containing the Task metadata.
files	An array of JSON objects describing files used by the task. Each file object can use these keys: filename: The base name of the file. uri: An object containing the path and params you can use to locate the file and the version of the file used (such as the version from the production environment). The client determines which host to download the file from. sha256: The SHA-256 hash of the file content, in lowercase hexadecimal form. size_bytes: The size of the file content in bytes.

For example:

{
  "id": "https://orchestrator.example.com:8143/orchestrator/v1/tasks/package/install",
  "name": "package::install",
  "environment": {
    "name": "production",
    "code_id": "urn:puppet:code-id:1:a86da166c30f871823f9b2ea224796e834840676;production"
  },
  "metadata": {
    "description": "Install a package",
    "supports_noop": true,
    "input_method": "stdin",
    "parameters": {
      "name": {
        "description": "The package to install",
        "type": "String[1]"
      },
      "provider": {
        "description": "The provider to use to install the package",
        "type": "Optional[String[1]]"
      },
      "version": {
        "description": "The version of the package to install, defaults to latest",
        "type": "Optional[String[1]]"
      }
    }
  },
  "files": [
    {
      "filename": "install",
      "uri": {
        "path": "/package/tasks/install",
        "params": {
          "environment": "production"
        }
      },
      "sha256": "a9089b5b9720dca38a49db6f164cf8a053a7ea528711325da1c23de94672980f",
      "size_bytes": 693
    }
  ]
}

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, task 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-task	The endpoint can't find a match for the specified task. There are several possible reasons for this, including: The endpoint can't find a valid relationship between the specified module and task. The task name is well-formed but doesn't match any existing tasks. There is no such task in the specified environment. For example, a task that only exists in the development environment returns 404 if the request specified a different environment or used the default environment value.