Advanced Patching API

To enable Advanced Patching, you must acquire a Puppet Enterprise Advanced license. Contact your Puppet Enterprise administrator or Contact our sales team to acquire a license and enable this feature.

Before you begin

See Advanced Patching.

Create a blackout window

POST /v1/command/create-blackout-window

Important: To create a blackout window, you must be authenticated by means of one of the following methods:

X-Authentication Header
RBAC Allowlisted Certificate

Request format

{
  "name": "string",
  "description": "string",
  "window_start": "2019-08-24T14:15:22Z",
  "window_end": "2019-08-24T14:15:22Z"
}

Parameters


Name	In	Type	Required	Description
body	body	any	true	none

Response format


Status	Meaning	Description	Schema
201	Created	Created.	entity-id
401	Unauthorized	Authentication failed.	not-authenticated-error
403	Forbidden	Requester does not have create permissions.	forbidden-request-error
415	Unsupported Media Type	Content type of payload is unsupported.	content-type-error
500	Internal Server Error	Unexpected server error.	error

Delete a blackout window

POST /v1/command/delete-blackout-window

Important: To delete a blackout window, you must be authenticated by means of one of the following methods:

X-Authentication Header
RBAC Allowlisted Certificate

Request format

{{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}

Parameters


Name	In	Type	Required	Description
body	body	object	true	none
» id	body	string(uuid)	true	none

Response format

{
  "kind": "puppetlabs.rbac/user-revoked",
  "msg": "string"
}

Responses


Status	Meaning	Description	Schema
204	No Content	Deletion of the blackout window was successful.	None
401	Unauthorized	Authentication failed.	not-authenticated-error
403	Forbidden	Requester does not have create permissions.	forbidden-request-error

Get a list of blackout windows

GET /v1/blackout-windows

Important: To get a list of blackout windows, you must be authenticated by means of one of the following methods:

X-Authentication Header
RBAC Allowlisted Certificate

Parameters


Name	In	Type	Required	Description
order_by	query	string	false	none
order	query	sort_order	false	none
limit	query	limit	false	none
offset	query	offset	false	none

Enumerated values


Parameter	Value
order_by	name
order_by	description
order_by	id
order_by	next_instance
order	asc
order	desc

Response format

{
  "items": [
    {
      "name": "string",
      "description": "string",
      "window_start": "2019-08-24T14:15:22Z",
      "window_end": "2019-08-24T14:15:22Z",
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "next_instance": "2019-08-24"
    }
  ],
  "pagination": {
    "limit": 1000,
    "offset": 0,
    "order_by": "string",
    "order": "asc",
    "total": 0
  }
}

Responses


Status	Meaning	Description	Schema
200	OK	Request was successful, returns an array of blackout windows.	Inline
401	Unauthorized	Authentication failed	not-authenticated-error
403	Forbidden	Requester does not have view permissions.	forbidden-request-error

Response schema

Status code: 200


Name	Type	Required	Restrictions	Description
» items	[oneOf]	false	none	none

oneOf


Name	Type	Required	Restrictions	Description
»» anonymous	any	false	none	none

allOf


Name	Type	Required	Restrictions	Description
»»» anonymous	one-time-window	false	none	none
»»»» name	string	true	none	A user defined unique name for the window
»»»» description	string	false	none	A user defined description for the window
»»»» window_start	string(date-time)	true	none	The start of the valid period for the window. If not specified, defaults to `now`
»»»» window_end	string(date-time)	true	none	The end of the valid period of the window. If not specified, implies the end of time.

and


Name	Type	Required	Restrictions	Description
»»» anonymous	object	false	none	none
»»»» id	identifier(uuid)	false	none	none
»»»» next_instance	string(date)	false	none	The start date for this one-time-window. Not present if the time is in the past

xor


Name	Type	Required	Restrictions	Description
»» anonymous	any	false	none	none

allOf


Name	Type	Required	Restrictions	Description
anonymous	repeated-time-window	false	none	none
»»»» name	string	true	none	A user defined unique name for the window
»»»» description	string	false	none	A user defined description for the window
»»»» series_start	string(date)	false	none	The start of the valid period for the series. If not specified, defaults to `today` in UTC
»»»» series_end	string(date)	false	none	The end of the valid period of the series. If not specified, implies the end of time.
»»»» series	object	true	none	Define valid periods of time within the overall window. Times within the overall window that are outside a sub window are not valid.
»»»»» cron	string	true	none	cron tab specification per https://www.quartz-scheduler.org/documentation/quartz-2.3.0/tutorials/crontrigger.html#format
»»»»» duration	object	true	none	none
»»»»»» amount	integer	true	none	none
»»»»»» unit	string	true	none	Unit of time: s - seconds, m - minutes, h - hours, d - days

and


Name	Type	Required	Restrictions	Description
»»» anonymous	object	false	none	none
»»»» id	identifier(uuid)	false	none	none
»»»» next_instance	string(date)	false	none	The start date for the next instance of this window. Not present if the time is in the past.

continued


Name	Type	Required	Restrictions	Description
» pagination	pagination	false	none	none
»» limit	limit	true	none	The maximum number of records returned. Zero indicates no limit.
»» offset	offset	true	none	The number of records skipped before collecting the results.
»» order_by	string	true	none	none
»» order	sort_order	true	none	The sorting direction to apply, 'asc' for ascending, 'desc' for descending.
»» total	integer	true	none	The total number of records available, ignoring limit and offset

Enumerated values


Property	Value
unit	s
unit	h
unit	m
unit	d
order	asc
order	desc

Get a single blackout window

GET /v1/blackout-windows/{id}

Important: To get a single blackout window, you must be authenticated by means of one of the following methods:

X-Authentication Header
RBAC Allowlisted Certificate

Parameters


Name	In	Type	Required	Description
id	path	identifier	false	none

Response format

{
  "name": "string",
  "description": "string",
  "window_start": "2019-08-24T14:15:22Z",
  "window_end": "2019-08-24T14:15:22Z",
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "next_instance": "2019-08-24"
}

Responses


Status	Meaning	Description	Schema
200	OK	Request was successful, returns an array of blackout windows.	Inline
401	Unauthorized	Authentication failed.	not-authenticated-error
403	Forbidden	Requester does not have view permissions.	forbidden-request-error
404	Not Found	Blackout window not found.	error

Response schema


Property	Value
unit	s
unit	h
unit	m
unit	d

Create a maintenance window

POST /v1/command/create-maintenance-window

Important: To create a maintenance window, you must be authenticated by means of one of the following methods:

X-Authentication Header
RBAC Allowlisted Certificate

Request format

{
  "name": "string",
  "description": "string",
  "window_start": "2019-08-24T14:15:22Z",
  "window_end": "2019-08-24T14:15:22Z"
}

Parameters


Name	In	Type	Required	Description
body	body	any	true	none

Response-format

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}

Responses


Status	Meaning	Description	Schema
201	Created	Created.	entity-id
401	Unauthorized	Authentication failed.	not-authenticated-error
403	Forbidden	Requester does not have create permissions.	forbidden-request-error
415	Unsupported Media Type	Content type of payload is unsupported.	content-type-error
500	Internal Server Error	Unexpected server error.	error

Delete a maintenance window

POST /v1/command/delete-maintenance-window

Important: To delete a maintenance window, you must be authenticated by means of one of the following methods:

X-Authentication Header
RBAC Allowlisted Certificate

Request format

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}

Parameters


Name	In	Type	Required	Description
body	body	object	true	none
» id	body	string(uuid)	true	none

Response format

{
  "kind": "puppetlabs.rbac/user-revoked",
  "msg": "string"
}

Responses


Status	Meaning	Description	Schema
204	No Content	Deletion of the maintenance window was successful.	None
401	Unauthorized	Authentication failed.	not-authenticated-error
403	Forbidden	Requester does not have create permissions.	forbidden-request-error

Get a list of maintenance windows

GET /v1/maintenance-windows

Important: To get a list of maintenance windows, you must be authenticated by means of one of the following methods:

X-Authentication Header
RBAC Allowlisted Certificate

Parameters


Name	In	Type	Required	Description
order_by	query	string	false	none
order	query	sort_order	false	none
limit	query	limit	false	none
offset	query	offset	false	none

Enumerated values


Parameter	Value
order_by	name
order_by	description
order_by	id
order_by	next_instance
order	asc
order	desc

Response format

{
  "items": [
    {
      "name": "string",
      "description": "string",
      "window_start": "2019-08-24T14:15:22Z",
      "window_end": "2019-08-24T14:15:22Z",
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "next_instance": "2019-08-24"
    }
  ],
  "pagination": {
    "limit": 1000,
    "offset": 0,
    "order_by": "string",
    "order": "asc",
    "total": 0
  }
}

Responses


Status	Meaning	Description	Schema
200	OK	Request was successful, returns an array of maintenance windows.	Inline
401	Unauthorized	Authentication failed.	not-authenticated-error
403	Forbidden	Requester does not have view permissions.	forbidden-request-error

Response schema

Status code: 200


Name	Type	Required	Restrictions	Description
» items	[oneOf]	false	none	none

oneOf


Name	Type	Required	Restrictions	Description
»» anonymous	any	false	none	none

allOf


Name	Type	Required	Restrictions	Description
»»» anonymous	one-time-window	false	none	none
»»»» name	string	true	none	A user defined unique name for the window
»»»» description	string	false	none	A user defined description for the window
»»»» window_start	string(date-time)	true	none	The start of the valid period for the window. If not specified, defaults to `now`
»»»» window_end	string(date-time)	true	none	The end of the valid period of the window. If not specified, implies the end of time.

and


Name	Type	Required	Restrictions	Description
»»» anonymous	object	false	none	none
»»»» id	identifier(uuid)	false	none	none
»»»» next_instance	string(date)	false	none	The start date for this one-time-window. Not present if the time is in the past

xor


Name	Type	Required	Restrictions	Description
»» anonymous	any	false	none	none

allOf


Name	Type	Required	Restrictions	Description
anonymous	repeated-time-window	false	none	none
»»»» name	string	true	none	A user defined unique name for the window
»»»» description	string	false	none	A user defined description for the window
»»»» series_start	string(date)	false	none	The start of the valid period for the series. If not specified, defaults to `today` in UTC
»»»» series_end	string(date)	false	none	The end of the valid period of the series. If not specified, implies the end of time.
»»»» series	object	true	none	Define valid periods of time within the overall window. Times within the overall window that are outside a sub window are not valid.
»»»»» cron	string	true	none	cron tab specification per https://www.quartz-scheduler.org/documentation/quartz-2.3.0/tutorials/crontrigger.html#format
»»»»» duration	object	true	none	none
»»»»»» amount	integer	true	none	none
»»»»»» unit	string	true	none	Unit of time: s - seconds, m - minutes, h - hours, d - days

and


Name	Type	Required	Restrictions	Description
»»» anonymous	object	false	none	none
»»»» id	identifier(uuid)	false	none	none
»»»» next_instance	string(date)	false	none	The start date for the next instance of this window. Not present if the time is in the past.

continued


Name	Type	Required	Restrictions	Description
» pagination	pagination	false	none	none
»» limit	limit	true	none	The maximum number of records returned. Zero indicates no limit.
»» offset	offset	true	none	The number of records skipped before collecting the results.
»» order_by	string	true	none	none.
»» order	sort_order	true	none	The sorting direction to apply, 'asc' for ascending, 'desc' for descending.
»» total	integer	true	none	The total number of records available, ignoring limit and offset.

Enumerated values


Property	Value
unit	s
unit	h
unit	m
unit	d
order	asc
order	desc

Get a single maintenance window

GET /v1/maintenance-windows/{id}

Important: To get a single maintenance window, you must be authenticated by means of one of the following methods:

X-Authentication Header
RBAC Allowlisted Certificate

Parameters


Name	In	Type	Required	Description
id	path	identifier	false	none

Response format

{
  "name": "string",
  "description": "string",
  "window_start": "2019-08-24T14:15:22Z",
  "window_end": "2019-08-24T14:15:22Z",
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "next_instance": "2019-08-24"
}

Responses


Status	Meaning	Description	Schema
200	OK	Request was successful, returns an individual maintenance window.	Inline
401	Unauthorized	Authentication failed.	not-authenticated-error
403	Forbidden	Requester does not have view permissions.	forbidden-request-error
404	Not Found	Maintenance window not found.	error

Response schema


Property	Value
unit	s
unit	h
unit	m
unit	d

Create a patch group

POST /v1/command/create-patch-group

Important: To create a patch group, you must be authenticated by means of one of the following methods:

X-Authentication Header
RBAC Allowlisted Certificate

Request format

{{
  "patch_group": {
    "name": "string",
    "description": "string",
    "node_list": [
      "string"
    ],
    "maintenance_windows": [
      "497f6eca-6276-4993-bfeb-53cbbbba6f08"
    ],
    "blackout_windows": [
      "497f6eca-6276-4993-bfeb-53cbbbba6f08"
    ]
  },
  "options": {
    "force_move": false
  }
}

Parameters


Name	In	Type	Required	Description
body	body	create-patch-group-payload	true	none

Response format

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "operation": "fc63ceec-84f0-4df1-a7e8-77c5f8c0b283"
}

Responses


Status	Meaning	Description	Schema
201	Created	Created.	entity-id
401	Unauthorized	Authentication failed.	not-authenticated-error
403	Forbidden	Requester does not have create permissions.	forbidden-request-error
409	Conflict	Node already exists in a different patch group and force is false.	collision-error
415	Unsupported Media Type	Content type of payload is unsupported.	content-type-error
500	Internal Server Error	Unexpected server error.	error

Delete a patch group

Delete a patch group and any patch jobs targeting it, along with their scheduled tasks.POST /v1/command/delete-patch-group

Request format

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}

Parameters


Name	In	Type	Required	Description
body	body	object	true	none
» id	body	string(uuid)	true	none

Response format

{
  "kind": "puppetlabs.rbac/user-revoked",
  "msg": "string"
}

Responses


Status	Meaning	Description	Schema
204	No Content	Deletion of the patch group and associated jobs was successful.	None
401	Unauthorized	Authentication failed.	not-authenticated-error
403	Forbidden	Requester does not have edit permissions on patch groups.	forbidden-request-error

Get a single patch group

GET /v1/patch-groups/{id}

Important: To get a single patch group, you must be authenticated by means of one of the following methods:

X-Authentication Header
RBAC Allowlisted Certificate

Parameters


Name	In	Type	Required	Description
id	path	identifier	false	none

Response format

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "string",
  "description": "string",
  "node_list": [
    "string"
  ],
  "maintenance_windows": [
    "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  ],
  "blackout_windows": [
    "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  ],
  "state": "pending",
  "package_updates": [
    "string"
  ],
  "security_package_updates": [
    "string"
  ],
  "last_package_update_time": "2019-08-24T14:15:22Z",
  "nodes_with_package_updates": [
    "string"
  ]
}

Responses


Status	Meaning	Description	Schema
200	OK	Request was successful, returns an individual patch group.	Inline
401	Unauthorized	Authentication failed.	not-authenticated-error
403	Forbidden	Requester does not have view permissions.	forbidden-request-error
404	Not Found	Patch group not found.	error

Get a list of patch groups

GET /v1/patch-groups

Important: To get a list of patch groups, you must be authenticated by means of one of the following methods:

X-Authentication Header
RBAC Allowlisted Certificate

Parameters


Name	In	Type	Required	Description
order_by	query	string	false	none
order	query	sort_order	false	none
limit	query	limit	false	none
offset	query	offset	false	none
with_updates_only	query	boolean	false	none

Enumerated values


Parameter	Value
order_by	name
order_by	description
order_by	id
order	asc
order	desc

Response format

{
  "items": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "name": "string",
      "description": "string",
      "node_list": [
        "string"
      ],
      "maintenance_windows": [
        "497f6eca-6276-4993-bfeb-53cbbbba6f08"
      ],
      "blackout_windows": [
        "497f6eca-6276-4993-bfeb-53cbbbba6f08"
      ],
      "state": "pending",
      "package_updates": [
        "string"
      ],
      "security_package_updates": [
        "string"
      ],
      "last_package_update_time": "2019-08-24T14:15:22Z",
      "nodes_with_package_updates": [
        "string"
      ]
    }
  ],
  "pagination": {
    "limit": 1000,
    "offset": 0,
    "order_by": "string",
    "order": "asc",
    "total": 0
  }
}

Responses


Status	Meaning	Description	Schema
200	OK	Request was successful, returns an array of patch groups.	Inline
401	Unauthorized	Authentication failed,	not-authenticated-error
403	Forbidden	Requester does not have view permissions.	forbidden-request-error

Response schema

Status code: 200


Name	Tupe	Required	Restrictions	Description
items	[patch-group-response]	false	none	none.
»» id	identifier(uuid)	true	none	none.
»» name	string	true	none	A unique name for the patch group.
»» description	string	false	none	A user defined description for the group.
»» node_list	[node]	true	none	none.
»» maintenance_windows	[identifier]	false	none	none.
»» blackout_windows	[identifier]	false	none	none.
»» state	string	true	none	none.
»» package_updates	[string]	true	none	The set of pending package updates for the nodes in the patch group.
»» security_package_updates	[string]	true	none	The set of pending security package updates for the nodes in the patch group. These are also listed in the package_updates.
»» last_package_update_time	string(date-time)	false	none	none.
»» nodes_with_package_updates	[string]	true	none	nodes in the patch group that have pending package updates.
» pagination	pagination	false	none	none.
»» limit	limit	true	none	The maximum number of records returned. Zero indicates no limit.
»» offset	offset	true	none	The number of records skipped before collecting the results.
»» order_by	string	true	none	none.
»» order	sort_order	true	none	The sorting direction to apply, 'asc' for ascending, 'desc' for descending.
»» total	integer	true	none	The total number of records available, ignoring limit and offset.

Enumerated values


Property	Value
state	pending
state	failed
state	ready
order	asc
order	desc

Validate a proposed patch group

Validate a proposed patch group name to ensure that it is well formed and does not collide with any other names. POST /v1/command/validate-patch-group-name

Important: To get a list of blackout windows, you must be authenticated by means of one of the following methods:

X-Authentication Header
RBAC Allowlisted Certificate

Request format

{
  "name": "string"
}

Parameters


Name	In	Type	Required	Description
body	body	patch-group-validate-name-payload	true	none

Response-format

{
  "valid": true,
  "reasons": [
    "string"
  ]
}

Responses


Status	Meaning	Description	Schema
200	OK	Request was successful, returns state of the operation.	entity-id
401	Unauthorized	Authentication failed.	not-authenticated-error

Response schema

Status code: 200


Name	Type	Required	Restrictions	Description
» valid	boolean	true	none	none
» reasons	[string]	false	none	none

Create a patch job

POST /v1/command/create-patch-job

Important: To create a patch job, you must be authenticated by means of one of the following methods:

X-Authentication Header
RBAC Allowlisted Certificate

Request format

{
  "description": "string",
  "parameters": {
    "yum_params": "string",
    "dpkg_params": "string",
    "zypper_params": "string",
    "reboot": "always",
    "timeout": 3600,
    "security_only": false,
    "clean_cache": true
  },
  "scope": {
    "patch_group_id": "29980d5c-46c9-4ec0-82cc-ea2bba6a4260"
  },
  "schedule": {
    "frequency": "now",
    "timestamp": "2019-08-24T14:15:22Z"
  },
  "ignore_maintenance_windows": false,
  "ignore_blackout_windows": false
}

Parameters


Name	In	Type	Required	Description
body	body	patch-job	true	none

Response format

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}

Responses


Status	Meaning	Description	Schema
201	Created	Created.	Inline
401	Unauthorized	Authentication failed.	not-authenticated-error
403	Forbidden	Requester does not have create permissions.	forbidden-request-error
409	Conflict	Node already exists in a different patch group and force is false.	collision-error
415	Unsupported Media Type	Content type of payload is unsupported.	content-type-error
500	Internal Server Error	Unexpected server error.	error

Response schema


Name	In	Type	Required	Description
» id	string(uuid)	true	none	none

Get a list of patch jobs

GET /v1/patch-jobs

Important: To get a list of patch jobs, you must be authenticated by means of one of the following methods:

X-Authentication Header
RBAC Allowlisted Certificate

Parameters


Name	In	Type	Required	Description
limit	query	limit	false	none
offset	query	offset	false	none

Response format

{
  "items": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "description": "string",
      "parameters": {
        "yum_params": "string",
        "dpkg_params": "string",
        "zypper_params": "string",
        "reboot": "always",
        "timeout": 3600,
        "security_only": false,
        "clean_cache": true
      },
      "scope": {
        "patch_group_id": "29980d5c-46c9-4ec0-82cc-ea2bba6a4260"
      },
      "schedule": {
        "frequency": "now",
        "timestamp": "2019-08-24T14:15:22Z"
      },
      "ignore_maintenance_windows": false,
      "ignore_blackout_windows": false,
      "next_run_time": "2019-08-24T14:15:22Z",
      "created_by": "ee824cad-d7a6-4f48-87dc-e8461a9201c4"
    }
  ],
  "pagination": {
    "limit": 1000,
    "offset": 0
  }
}

Responses


Status	Meaning	Description	Schema
200	OK	Request was successful, returns an array of patch jobs.	Inline
401	Unauthorized	Authentication failed.	not-authenticated-error
403	Forbidden	Requester does not have view permissions.	forbidden-request-error

Response schema

Status code: 200


Name	Type	Required	Restrictions	Description
» items	[allOf]	false	none	none

allOf


Name	Type	Required	Restrictions	Description
»» anonymous	any	false	none	none
»»» id	identifier(uuid)	false	none	none

and


Name	Type	Required	Restrictions	Description
»» anonymous	patch-job	false	none	none
»»» description	string	false	none	none
»»» parameters	patch-job-parameters	false	none	none
»»»» yum_params	string	false	none	Any additional parameters to include in the yum upgrade command (such as including/excluding repos)
»»»» dpkg_params	string	false	none	Any additional parameters to include in the dpkg command
»»»» zypper_params	string	false	none	Any additional parameters to include in the zypper update command
»»»» reboot	string	false	none	Should the server reboot after patching has been applied? (Defaults to 'never')
»»»» timeout	integer	false	none	How many seconds should we wait until timing out the patch run?
»»»» security_only	boolean	false	none	Limit patches to those tagged as security related?
»»»» clean_cache	boolean	false	none	Should the yum/dpkg caches be cleaned at the start of the task? (Defaults to false)
»»» scope	object	false	none	none
»»»» patch_group_id	string(uuid)	false	none	none
»»» schedule	object	true	none	none
»»»» frequency	string	true	none	How often the job should run. If `now`, the rest of the schedule is ignored, and will be run at the first opportunity.

oneOf


Name	Type	Required	Restrictions	Description
»» anonymous	one-time-execution	false	none	none
»»»»» timestamp	string(date-time)	false	none	none

xor


Name	Type	Required	Restrictions	Description
»»»» anonymous	repeated-time-interval	false	none	none
»»»»» name	string	true	none	A user defined unique name for the interval
»»»»» description	string	false	none	A user defined description for the interval
»»»»» series_start	string(date)	false	none	The start of the valid period for the series. If not specified, defaults to `today` in UTC
»»»»» series_end	string(date)	false	none	The end of the valid period of the series. If not specified, implies the end of time.
»»»»» series	object	true	none	Define valid periods of time within the overall window. Times within the overall window that are outside a subwindow are not valid.
»»»»»» cron	string	true	none	cron tab specification per https://www.quartz-scheduler.org/documentation/quartz-2.3.0/tutorials/crontrigger.html#format

and


Name	Type	Required	Restrictions	Description
»» anonymous	object	false	none	none
»»» next_run_time	string(date-time)	false	none	When the job will next run, if applicable
»»» created_by	string(uuid)	false	none	User id that created the job

continued


Name	Type	Required	Restrictions	Description
pagination	object	false	none	none
»» limit	limit	false	none	The maximum number of records returned. Zero indicates no limit.
»» offset	offset	false	none	The number of records skipped before collecting the results.

Enumerated values


Property	Value
reboot	always
reboot	never
reboot	patched
reboot	smart
frequency	now
frequency	once
frequency	recurring

Get a single patch job

GET /v1/patch-jobs/{id}

Important: To get a single patch job, you must be authenticated by means of one of the following methods:

X-Authentication Header
RBAC Allowlisted Certificate

Parameters


Name	In	Type	Required	Description
id	path	identifier	true	none

Response format

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "description": "string",
  "parameters": {
    "yum_params": "string",
    "dpkg_params": "string",
    "zypper_params": "string",
    "reboot": "always",
    "timeout": 3600,
    "security_only": false,
    "clean_cache": true
  },
  "scope": {
    "patch_group_id": "29980d5c-46c9-4ec0-82cc-ea2bba6a4260"
  },
  "schedule": {
    "frequency": "now",
    "timestamp": "2019-08-24T14:15:22Z"
  },
  "ignore_maintenance_windows": false,
  "ignore_blackout_windows": false,
  "next_run_time": "2019-08-24T14:15:22Z",
  "created_by": "ee824cad-d7a6-4f48-87dc-e8461a9201c4"
}

Responses


Status	Meaning	Description	Schema
200	OK	Request was successful, returns an individual patch job.	patch-job-response
401	Unauthorized	Authentication failed.	not-authenticated-error
403	Forbidden	Requester does not have view permissions.	forbidden-request-error
404	Not Found	Patch job not found.	error

Get a list of operations

GET /v1/operations

Important: To get a list of blackout windows, you must be authenticated by means of one of the following methods:

X-Authentication Header
RBAC Allowlisted Certificate

Parameters


Name	In	Type	Required	Description
order_by	query	string	false	none
order	query	sort_order	false	none
limit	query	limit	false	none
offset	query	offset	false	none
type	query	string	false	none

Enumerated values


Parameter	Value
order_by	type
order_by	id
order_by	creator
order_by	created_on
order_by	state
order	asc
order	desc

Response format

{
  "items": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "creator": "1dccd4a6-75d2-43aa-a088-76d941f1b60a",
      "created_on": "2019-08-24T14:15:22Z",
      "state": "queued",
      "type": "string",
      "history": [
        {
          "description": "string",
          "state": "created",
          "stage": "string",
          "result": {},
          "timestamp": "2019-08-24T14:15:22Z"
        }
      ]
    }
  ],
  "pagination": {
    "limit": 1000,
    "offset": 0,
    "order_by": "string",
    "order": "asc",
    "total": 0,
    "type": "string"
  }
}

Responses


Status	Meaning	Description	Schema
200	OK	Request was successful, returns an array of operations	Inline
401	Unauthorized	Authentication failed	not-authenticated-error
403	Forbidden	Requester does not have view permissions.	forbidden-request-error

Response schema

Status code: 200


Name	Type	Required	Restrictions	Description
» items	[operation]	false	none	none.
»» id	identifier(uuid)	true	none	none.
»» creator	identifier(uuid)	false	none	none.
»» created_on	string(date-time)	false	none	Time the operation was created.
»» state	operation-state	true	none	none.
»» type	operation-type	false	none	none.
»» history	[event]	false	none	none.
»»» description	string	false	none	A human readable string describing what is happening in this step.
»»» state	string	false	none	none
»»» stage	string	false	none	The stage of the operation that succeeds this step.
»»» result	object	false	none	none.
»»» timestamp	string(date-time)	true	none	The time the event was inserted.
» pagination	any	false	none	none.

allOf


Name	Type	Required	Restrictions	Description
»» anonymous	pagination	false	none	none.
»»» limit	limit	true	none	The maximum number of records returned. Zero indicates no limit.
»»» offset	offset	true	none	The number of records skipped before collecting the results.
»»» order_by	string	true	none	none.
»»» order	sort_order	true	none	The sorting direction to apply, 'asc' for ascending, 'desc' for descending.
»»» total	integer	true	none	The total number of records available, ignoring limit and offset.

and


Name	Type	Required	Restrictions	Description
»» anonymous	object	false	none	none
»»» type	string	false	none	Limit results to only operations of this type.

Enumerated values


Property	Value
state	queued
state	running
state	finished
state	failed
state	created
state	success
state	failed
order	asc
order	desc

Get a single operation

GET /v1/operations/{id}

Important: To get a single blackout window, you must be authenticated by means of one of the following methods:

X-Authentication Header
RBAC Allowlisted Certificate

Parameters


Name	In	Type	Required	Description
last_step_index	query	operation-step-index	false	The last seen history entry for this operation. This value is used for long-polling waiting for a change in state unless the operation is finished or failed.
id	path	identifier	true	The operation in question to retrieve.

Response format

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "creator": "1dccd4a6-75d2-43aa-a088-76d941f1b60a",
  "created_on": "2019-08-24T14:15:22Z",
  "state": "queued",
  "type": "string",
  "history": [
    {
      "description": "string",
      "state": "created",
      "stage": "string",
      "result": {},
      "timestamp": "2019-08-24T14:15:22Z"
    }
  ]
}

Responses


Status	Meaning	Description	Schema
200	OK	Request was successful, returns state of the operation.	operation
401	Unauthorized	Authentication failed.	not-authenticated-error
404	Not Found	Operation not found.	error

Schemas

offset

The number of records skipped before collecting the results.

Properties


Name	Type	Required	Restrictions	Description
anonymous	integer	false	none	The number of records skipped before collecting the results.

limit

The maximum number of records returned. Zero indicates no limit.

Properties


Name	Type	Required	Restrictions	Description
anonymous	integer	false	none	The maximum number of records returned. Zero indicates no limit.

sort_order

The sorting direction to apply, 'asc' for ascending, 'desc' for descending.

"asc"

Properties


Name	Type	Required	Restrictions	Description
anonymous	string	false	none	The sorting direction to apply, 'asc' for ascending, 'desc' for descending.

Enumerated values


Property	Value
anonymous	asc
anonymous	desc

one-time-window

{
  "name": "string",
  "description": "string",
  "window_start": "2019-08-24T14:15:22Z",
  "window_end": "2019-08-24T14:15:22Z"
}

Properties


Name	Type	Required	Restrictions	Description
name	string	true	none	A user defined unique name for the window
description	string	false	none	A user defined description for the window
window_start	string(date-time)	true	none	The start of the valid period for the window. If not specified, defaults to `now`
window_end	string(date-time)	true	none	The end of the valida period of the window. If not specified, implies the end of time.

one-time-window response

{
  "name": "string",
  "description": "string",
  "window_start": "2019-08-24T14:15:22Z",
  "window_end": "2019-08-24T14:15:22Z",
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "next_instance": "2019-08-24"
}

Properties

allOf


Name	Type	Required	Restrictions	Description
anonymous	one-time-window	false	none	none

and


Name	Type	Required	Restrictions	Description
anonymous	object	false	none	none
» id	identifier	false	none	none
» next_instance	string(date)	false	none	The start date for this one-time-window. Not present if the time is in the past.

repeated-time-interval

{
  "name": "string",
  "description": "string",
  "series_start": "2019-08-24",
  "series_end": "2019-08-24",
  "series": {
    "cron": "string"
  }
}

Properties


Name	Type	Required	Restrictions	Description
name	string	true	none	A user defined unique name for the interval
description	string	false	none	A user defined description for the interval
series_start	string(date)	false	none	The start of the valid period for the series. If not specified, defaults to `today` in UTC
series_end	string(date)	false	none	The end of the valid period of the series. If not specified, implies the end of time.
series	object	true	none	Define valid periods of time within the overall window. Times within the overall window that are outside a subwindow are not valid.
» cron	string	true	none	cron tab specification per https://www.quartz-scheduler.org/documentation/quartz-2.3.0/tutorials/crontrigger.html#format

repeated-time-window

{
  "name": "string",
  "description": "string",
  "series_start": "2019-08-24",
  "series_end": "2019-08-24",
  "series": {
    "cron": "string",
    "duration": {
      "amount": 1,
      "unit": "s"
    }
  }
}

Properties


Name	Type	Required	Restrictions	Description
name	string	true	none	A user defined unique name for the window
description	string	false	none	A user defined description for the window
series_start	string(date)	false	none	The start of the valid period for the series. If not specified, defaults to `today` in UTC
series_end	string(date)	false	none	The end of the valid period of the series. If not specified, implies the end of time.
series	object	true	none	Define valid periods of time within the overall window. Times within the overall window that are outside a subwindow are not valid.
» cron	string	true	none	cron tab specification per https://www.quartz-scheduler.org/documentation/quartz-2.3.0/tutorials/crontrigger.html#format
» duration	object	true	none	none
»» amount	integer	true	none	none
»» unit	string	true	none	Unit of time: s - seconds, m - minutes, h - hours, d - days

Enumerated values


Property	Value
unit	s
unit	h
unit	m
unit	d

repeated-time-window-response

{
  "name": "string",
  "description": "string",
  "series_start": "2019-08-24",
  "series_end": "2019-08-24",
  "series": {
    "cron": "string",
    "duration": {
      "amount": 1,
      "unit": "s"
    }
  },
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "next_instance": "2019-08-24"
}

Properties

allOf


Name	Type	Required	Restrictions	Description
anonymous	repeated-time-window	false	none	none

and


Name	Type	Required	Restrictions	Description
anonymous	object	false	none	none
» id	identifier	false	none	none
» next_instance	string(date)	false	none	The start date for the next instance of this window. Not present if the time is in the past.

identifier

"497f6eca-6276-4993-bfeb-53cbbbba6f08"

Properties


Name	Type	Required	Restrictions	Description
anonymous	string(uuid)	false	none	none

entity-id

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}

Properties


Name	Type	Required	Restrictions	Description
id	identifier	false	none	none

error

{
  "kind": "string",
  "msg": "string",
  "details": {}
}

Properties


Name	Type	Required	Restrictions	Description
kind	string	true	none	an indication of the type of error from a service perspective
msg	string	true	none	More detail about the error.
details	object	false	none	Detailed information about the error, payload can vary

collision-error

{
  "kind": "node-in-use",
  "msg": "A node specified in the request is already in use in a patch group",
  "details": {
    "nodes": [
      {
        "node": "string",
        "patch_group": "6b8b4f36-ff74-424f-993a-8d6fb0151c60"
      }
    ]
  }
}

Properties


Name	Type	Required	Restrictions	Description
kind	string	true	none	an indication of the type of error from a service perspective.
msg	string	true	none	More detail about the error.
details	object	true	none	Detailed information about collisions.
» nodes	[object]	true	none	none.
»» node	node	true	none	none.
»» patch_group	identifier	true	none	none.

Enumerated values


Property	Value
kind	node-in-use
msg	A node specified in the request is already in use in a patch group
msg	Nodes specified in the request are already used in a patch group

content-type-error

{
  "kind": "unsupported type",
  "msg": "string"
}

Properties


Name	Type	Required	Restrictions	Description
kind	string	true	none	none
msg	string	true	none	none

Enumerated values


Property	Value
kind	unsupported type

not-authenticated-error

{
  "kind": "puppetlabs.rbac/user-revoked",
  "msg": "string"
}

Properties


Name	Type	Required	Restrictions	Description
kind	string	true	none	none
msg	string	true	none	none

Enumerated values


Property	Value
kind	puppetlabs.rbac/user-revoked
kind	puppetlabs.rbac/token-expired
kind	puppetlabs.rbac/token-revoked
kind	puppetlabs.rbac/invalid-token
kind	puppetlabs.rbac/user-unauthenticated

forbidden-request-error

{
  "kind": "forbidden-request",
  "msg": "string"
}

Properties


Name	Type	Required	Restrictions	Description
kind	string	true	none	none
msg	string	true	none	none

Enumerated values


Property	Value
kind	forbidden-request

node

"string"

Properties


Name	Type	Required	Restrictions	Description
anonymous	string	false	none	none

base-patch-group

{
  "name": "string",
  "description": "string",
  "node_list": [
    "string"
  ],
  "maintenance_windows": [
    "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  ],
  "blackout_windows": [
    "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  ]
}

Properties


Name	Type	Required	Restrictions	Description
name	string	true	none	A unique name for the patch group
description	string	false	none	A user defined description for the group
node_list	[node]	true	none	none
maintenance_windows	[identifier]	false	none	none
blackout_windows	[identifier]	false	none	none

patch-group-response

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "string",
  "description": "string",
  "node_list": [
    "string"
  ],
  "maintenance_windows": [
    "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  ],
  "blackout_windows": [
    "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  ],
  "state": "pending",
  "package_updates": [
    "string"
  ],
  "security_package_updates": [
    "string"
  ],
  "last_package_update_time": "2019-08-24T14:15:22Z",
  "nodes_with_package_updates": [
    "string"
  ]
}

Properties


Name	Type	Required	Restrictions	Description
id	identifier	true	none	the unique identifier for this patch group
name	string	true	none	A unique name for the patch group
description	string	false	none	A user defined description for the group
node_list	[node]	true	none	none
maintenance_windows	[identifier]	false	none	none
blackout_windows	[identifier]	false	none	none
state	string	true	none	none
package_updates	[string]	true	none	The set of pending package updates for the nodes in the patch group
security_package_updates	[string]	true	none	The set of pending security package updates for the nodes in the patch group. These are also listed in the package_updates.
last_package_update_time	string(date-time)	false	none	none
nodes_with_package_updates	[string]	true	none	nodes in the patch group that have pending package updates.

Enumerated values


Property	Value
state	pending
state	failed
state	ready

patch-group-with-operation-response

{
  {
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "operation": "fc63ceec-84f0-4df1-a7e8-77c5f8c0b283"
}

Properties


Name	Type	Required	Restrictions	Description
id	identifier	true	none	the unique identifier for this patch group
operation	identifier	true	none	the unique identifier for the operation associated with the creation of this patch group

event

{
  "description": "string",
  "state": "created",
  "stage": "string",
  "result": {},
  "timestamp": "2019-08-24T14:15:22Z"
}

Properties


Name	Type	Required	Restrictions	Description
description	string	false	none	A human readable string describing what is happening in this step.
state	string	false	none	none
stage	string	false	none	The stage of the operation that succeeds this step.
result	object	false	none	none
timestamp	string(date-time)	true	none	The time the event was inserted

Enumerated values


Property	Value
state	created
state	success
state	failed

operation-step-index

An index of history in the operation, can be used with long-polling to wait for the resource to change.

Properties


Name	Type	Required	Restrictions	Description
anonymous	integer	false	none	An index of history in the operation, can be used with long-polling to wait for the resource to change.

operation

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "creator": "1dccd4a6-75d2-43aa-a088-76d941f1b60a",
  "created_on": "2019-08-24T14:15:22Z",
  "state": "queued",
  "type": "string",
  "history": [
    {
      "description": "string",
      "state": "created",
      "stage": "string",
      "result": {},
      "timestamp": "2019-08-24T14:15:22Z"
    }
  ]
}

Properties


Name	Type	Required	Restrictions	Description
id	identifier	true	none	Unique identifier for this operation
creator	identifier	false	none	User id for the user responsible for starting the operation
created_on	string(date-time)	false	none	Time the operation was created
state	operation-state	true	none	State of the operation
type	operation-type	false	none	none
history	[event]	false	none	none

operation-state

"queued"

Properties


Name	Type	Required	Restrictions	Description
anonymous	string	false	none	none

Enumerated values


Property	Value
anonymous	queued
anonymous	running
anonymous	finished
anonymous	failed

operation-type

"string"

Properties


Name	Type	Required	Restrictions	Description
anonymous	string	false	none	none

create-patch-group-payload

{
  "patch_group": {
    "name": "string",
    "description": "string",
    "node_list": [
      "string"
    ],
    "maintenance_windows": [
      "497f6eca-6276-4993-bfeb-53cbbbba6f08"
    ],
    "blackout_windows": [
      "497f6eca-6276-4993-bfeb-53cbbbba6f08"
    ]
  },
  "options": {
    "force_move": false
  }
}

Properties


Name	Type	Required	Restrictions	Description
patch_group	base-patch-group	true	none	none
options	object	false	none	none
» force_move	boolean	false	none	In the case that a node exists in another patch group, a true value of this flag indicates that it is be forcibly moved from one to the other.

patch-group-validate-name-payload

{
  "name": "string"
}

Properties


Name	Type	Required	Restrictions	Description
name	string	true	none	none

pagination

{
  "limit": 1000,
  "offset": 0,
  "order_by": "string",
  "order": "asc",
  "total": 0
}

Properties


Name	Type	Required	Restrictions	Description
limit	limit	true	none	The maximum number of records returned. Zero indicates no limit.
offset	offset	true	none	The number of records skipped before collecting the results.
order_by	string	true	none	none
order	sort_order	true	none	The sorting direction to apply, 'asc' for ascending, 'desc' for descending.
total	integer	true	none	The total number of records available, ignoring limit and offset

patch-job-parameters

{
  "yum_params": "string",
  "dpkg_params": "string",
  "zypper_params": "string",
  "reboot": "always",
  "timeout": 3600,
  "security_only": false,
  "clean_cache": true
}

Properties


Name	Type	Required	Restrictions	Description
yum_params	string	false	none	Any additional parameters to include in the yum upgrade command (such as including/excluding repos)
dpkg_params	string	false	none	Any additional parameters to include in the dpkg command
zypper_params	string	false	none	Any additional parameters to include in the zypper update command
reboot	string	false	none	Should the server reboot after patching has been applied? (Defaults to 'never')
timeout	integer	false	none	How many seconds we wait until timing out the patch run?
security_only	boolean	false	none	Limit patches to those tagged as security related?
clean_cache	boolean	false	none	Should the yum/dpkg caches be cleaned at the start of the task? (Defaults to false)

Enumerated values


Property	Value
reboot	always
reboot	never
reboot	patched
reboot	smart

one-time-execution

{
  "timestamp": "2019-08-24T14:15:22Z"
}

Properties


Name	Type	Required	Restrictions	Description
timestamp	string(date-time)	false	none	none

patch-job

{{
  "description": "string",
  "parameters": {
    "yum_params": "string",
    "dpkg_params": "string",
    "zypper_params": "string",
    "reboot": "always",
    "timeout": 3600,
    "security_only": false,
    "clean_cache": true
  },
  "scope": {
    "patch_group_id": "29980d5c-46c9-4ec0-82cc-ea2bba6a4260"
  },
  "schedule": {
    "frequency": "now",
    "timestamp": "2019-08-24T14:15:22Z"
  },
  "ignore_maintenance_windows": false,
  "ignore_blackout_windows": false
}

Properties


Name	Type	Required	Restrictions	Description
description	string	false	none	none
parameters	patch-job-parameters	false	none	none
scope	object	false	none	none
» patch_group_id	string(uuid)	false	none	none
schedule	object	true	none	none
» frequency	string	true	none	How often the job runs. If `now`, the rest of the schedule is ignored, and runs at the first opportunity.

oneOf


Name	Type	Required	Restrictions	Description
» anonymous	one-time-execution	false	none	none

xor


Name	Type	Required	Restrictions	Description
» anonymous	repeated-time-interval	false	none	none

continued


Name	Type	Required	Restrictions	Description
ignore_maintenance_windows	boolean	false	none	Allow this job run outside the defined maintenance windows
ignore_blackout_windows	boolean	false	none	Allow this job run inside the defined blackout windows

Enumerated values


Property	Value
frequency	now
frequency	once
frequency	recurring

patch-job-response

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "description": "string",
  "parameters": {
    "yum_params": "string",
    "dpkg_params": "string",
    "zypper_params": "string",
    "reboot": "always",
    "timeout": 3600,
    "security_only": false,
    "clean_cache": true
  },
  "scope": {
    "patch_group_id": "29980d5c-46c9-4ec0-82cc-ea2bba6a4260"
  },
  "schedule": {
    "frequency": "now",
    "timestamp": "2019-08-24T14:15:22Z"
  },
  "ignore_maintenance_windows": false,
  "ignore_blackout_windows": false,
  "next_run_time": "2019-08-24T14:15:22Z",
  "created_by": "ee824cad-d7a6-4f48-87dc-e8461a9201c4"
}

Properties

allOf


Name	Type	Required	Restrictions	Description
anonymous	entity-id	false	none	none

and


Name	Type	Required	Restrictions	Description
anonymous	patch-job	false	none	none

and


Name	Type	Required	Restrictions	Description
anonymous	object	false	none	none
» next_run_time	string(date-time)	false	none	When the job runs next, if applicable
» created_by	string(uuid)	false	none	User id that created the job

Was this page helpful?

We’re sorry to hear that!
Please tell us why so we can help. Enter your feedback and email. This form is sent to the Puppet docs team. We ask for your email as we might contact you regarding your feedback. If you need help with the product itself, visit Puppet Support or ask in Puppet Community on Slack. Feedback:

Email Address:

To learn about how Puppet uses your personal information, visit our privacy policy.

If you leave us your email, we may contact you regarding your feedback. For more information on how Puppet uses your personal information, see our privacy policy.

See an issue? Please file a JIRA ticket in our [DOCUMENTATION] project.