POST /v1/commands/unpin-from-all

Unpin one or more specific nodes from all node groups they’re pinned to. Unpinning has no effect on nodes that are assigned to node groups via dynamic rules.

Request format

If you submit a request to the /v1/commands/unpin-from-all endpoint, the endpoint only removes the specified nodes from groups that you have permission to view and edit. Because group permissions are applied hierarchically, you must have one of the following permissions for the parent groups of each group you want to unpin nodes from:

Create, edit, and delete child groups
Edit child group rules

When Forming node classifier API requests to this endpoint, the body must be a JSON object containing the certnames of the nodes you want to unpin. For a single node, you can supply this in a simple JSON object. For multiple nodes, supply the certnames in an array. For example, this JSON body unpins a single node:

{"nodes": "foo"}

And this body unpins three nodes:

{"nodes": ["foo", "bar", "baz"]}

Here is an example of a complete curl request for this endpoint:

type_header= 'Content-Type: application/json'
auth_header="X-Authentication: $(puppet-access show)"
uri="https://$(puppet config print server):4433/classifier-api/v1/commands/unpin-from-all"
data='{"nodes": ["host1.example", "host2.example"]}'

curl --insecure --header "$type_header"  --header "$auth_header"--request POST "$uri" --data "$data"

Nodes assigned to groups via dynamic rules can't be unpinned. If you want to remove dynamically-classified nodes from groups, you need to modify the group's rules. To explore a node's classification, use the Classification endpoints.

Response format

If you have a lot of node groups, the endpoint takes longer to respond.

If unpinning is successful, the service returns a list of nodes and the groups they were unpinned from. If a node you specified in your request was not pinned to any groups, that node is omitted from the response. Here are two response examples:

{"nodes": [{"name": "foo",
            "groups": [{"id": "8310b045-c244-4008-88d0-b49573c84d2d",
                        "name": "Webservers",
                        "environment": "production"},
                       {"id": "84b19b51-6db5-4897-9409-a4a3a94b7f09",
                        "name": "Test",
                        "environment": "test"}]},
           {"name": "bar",
            "groups": [{"id": "84b19b51-6db5-4897-9409-a4a3a94b7f09",
                        "name": "Test",
                        "environment": "test"}]}]}

{"nodes":
   [{"name":"host1.example",
     "groups":[{"id":"2d83d860-19b4-4f7b-8b70-e5ee4d8646db","name":"test","environment":"production"}]}, 
    {"name":"host2.example",
     "groups":[{"id":"2d83d860-19b4-4f7b-8b70-e5ee4d8646db","name":"test","environment":"production"}]}]}

Error responses

If there is an error, Node classifier API errors provide error information in the kind key.

If your request doesn't specify any nodes to unpin, the service returns a 400 Malformed Request response.

If the request body is invalid JSON, is missing the nodes key, or contains any keys other than nodes, the service returns a 400 Malformed Request response.