Disable the Puppet agent

The following examples demonstrate how to use the Puppet Job API to disable the Puppet agent on target nodes using the disable action. Disabling the agent prevents Puppet from making any changes until it is re-enabled. A reason parameter is required when using this action. The response will indicate that the Puppet job is created and is scheduled to run. You can use the job ID from the response to retrieve the job status and payload details.

Request syntax

The target for a Puppet disable job can be specified using a list of node hostnames, a node group name, a node group ID, a saved filter name, or a saved filter ID. Only one target parameter can be used per request.

Target nodes using a list of hostnames.

post api/jobs/puppet '{"action":"disable","reason":"<reason>","hostnames":["<node_hostname>"]}'

Target nodes using a node group name.

post api/jobs/puppet '{"action":"disable","reason":"<reason>","node_group_name":"<node_group_name>"}'

Target nodes using a node group ID.

post api/jobs/puppet '{"action":"disable","reason":"<reason>","node_group_id":<node_group_id>}'

Target nodes using a saved filter name.

post api/jobs/puppet '{"action":"disable","reason":"<reason>","saved_filter_name":"<saved_filter_name>"}'

Target nodes using a saved filter ID.

post api/jobs/puppet '{"action":"disable","reason":"<reason>","saved_filter_id":<saved_filter_id>}'

Action-specific parameters

Parameter	Type	Description	Required
`reason`	String	The reason for disabling Puppet. This value is recorded and visible in the payload.	Yes

Examples

Example 1: Disable the Puppet agent for a list of hostnames.

This example starts a Puppet job to disable the Puppet agent on nodes with hostnames sit0001red0 and sit0001red1. A reason must be provided.

ruby api.rb <customer_code> post api/jobs/puppet '{"action":"disable","reason":"Performing scheduled maintenance","hostnames":["sit0001red0","sit0001red1"]}'

Response

{
    "id": 1598120,
    "type": "Puppet",
    "status": "pending",
    "message": null,
    "trigged_by": "test.user",
    "parameters": {
        "action": "disable",
        "reason": "Performing scheduled maintenance",
        "hostnames": [
            "sit0001red0",
            "sit0001red1"
        ]
    },
    "time_started": "2024-09-03T19:22:05Z"
}

Example 2: Disable the Puppet agent using a node group name.

This example starts a Puppet job to disable the Puppet agent for all nodes in the node group Test Node Group.

ruby api.rb <customer_code> post api/jobs/puppet '{"action":"disable","reason":"Performing scheduled maintenance","node_group_name":"Test Node Group"}'

Response

{
    "id": 1598121,
    "type": "Puppet",
    "status": "pending",
    "message": null,
    "trigged_by": "test.user",
    "parameters": {
        "action": "disable",
        "reason": "Performing scheduled maintenance",
        "node_group_name": "Test Node Group"
    },
    "time_started": "2024-09-03T19:25:31Z"
}

Retrieving the payload of a Puppet disable job.

Use the following API call to retrieve the job details, which includes the payload confirming the Puppet agent was disabled on each node. Ensure that you are using the job ID from the output of the previous API call when requesting the job details.

ruby api.rb <customer_code> get api/jobs/1598120\?include_payload=true

Response

{
    "id": 1598120,
    "type": "Puppet",
    "status": "finished",
    "message": null,
    "payload": {
        "success_nodes": {
            "sit0001red0": {
                "status": "Disabling Puppet",
                "note": "Disabled by test.user: Performing scheduled maintenance"
            },
            "sit0001red1": {
                "status": "Disabling Puppet",
                "note": "Disabled by test.user: Performing scheduled maintenance"
            }
        }
    },
    "trigged_by": "test.user",
    "success_nodes_count": 2,
    "failed_nodes_count": 0,
    "total_nodes_count": 2,
    "parameters": {
        "action": "disable",
        "reason": "Performing scheduled maintenance",
        "hostnames": [
            "sit0001red0",
            "sit0001red1"
        ]
    },
    "time_started": "2024-09-03T19:22:05Z",
    "time_finished": "2024-09-03T19:22:10Z"
}