Schemas

offset

The number of records skipped before collecting the results.

0

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.

1000

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.

0

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",
  "job_type": "patching"
}

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
» job_type string false none

The type of patch job

Enumerated Values

Property Value
job_type patching
job_type remediate

Update-patch-job-payload

 {
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "string",
  "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
id string(uuid) true none The UUID of the patch job to update
name string true none A user-defined name for the patch job
description string false none none
parameters patch-job-parameters false none none
scope object true 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

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