Skip to content

Commit 568de07

Browse files
retr0hclaude
andauthored
feat: delete a machine from admission, and delete machines that stop reporting (#890)
* feat: delete a machine from admission, and delete machines that stop reporting DELETE /api/admission/{machine_id} (osapi client admission delete) removes a machine's key and each record of it, and keeps none: a machine that asks again is new. It is for a machine that goes away on purpose, such as a VM that is rebuilt. Revoke stays for a machine that is not trusted. controller.pki.delete_after deletes an admitted machine that has not reported for that long, by its last report or, when it never reported, its admission. An online machine is never deleted, and when the registry or the last reports do not read, nothing is deleted. Empty is never. Closes #889 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * test: update the golden contract for the delete route Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * style: format the delete_after tag with golangci-lint Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
1 parent b301d73 commit 568de07

39 files changed

Lines changed: 1158 additions & 76 deletions

‎cmd/client_admission.go‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -43,7 +43,7 @@ func init() {
4343
renderAdmission(out)
4444
},
4545
)
46-
// admit, reject and revoke answer 204, with no body: each prints what
46+
// admit, reject, revoke and delete answer 204, with no body: each prints what
4747
// it did, with --json too.
4848
command.Acts(
4949
admission.Group,
@@ -55,6 +55,11 @@ func init() {
5555
"reject",
5656
func(_ *cobra.Command, in admission.RejectInput, _ struct{}) { admissionDone(in.MachineID, "rejected") },
5757
)
58+
command.Acts(
59+
admission.Group,
60+
"delete",
61+
func(_ *cobra.Command, in admission.MachineInput, _ struct{}) { admissionDone(in.MachineID, "deleted") },
62+
)
5863
command.Acts(
5964
admission.Group,
6065
"revoke",

‎configs/osapi.dev.yaml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,7 @@ controller:
2121
# key_dir: /etc/osapi/pki
2222
# auto_admit: false
2323
# rotation_grace_period: 24h
24+
# delete_after: ""
2425

2526
agent:
2627
nats:

‎configs/osapi.yaml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@ controller:
1717
# key_dir: /etc/osapi/pki
1818
# auto_admit: false
1919
# rotation_grace_period: 24h
20+
# delete_after: ""
2021
api:
2122
# Host the API, and the UI on its listener, binds to. Empty binds every
2223
# interface.
Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
{"parameters":[{"description":"The machine ID of the node.","in":"path","name":"machine_id","required":true,"schema":{"maxLength":255,"minLength":1,"type":"string"},"x-oapi-codegen-extra-tags":{"validate":"required,min=1,max=255"}}]}
Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
{"title":"Body"}
Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
{"responses":{"204":{"description":"The machine is deleted."},"400":{"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"A description of the error that occurred.","example":"Failed to retrieve status."},"details":{"type":"string","description":"Additional details about the error.","example":"Failed due to network timeout."},"code":{"type":"integer","description":"The error code.","example":500}},"title":"ErrorResponse"}}},"description":"The request is not valid."},"401":{"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"A description of the error that occurred.","example":"Failed to retrieve status."},"details":{"type":"string","description":"Additional details about the error.","example":"Failed due to network timeout."},"code":{"type":"integer","description":"The error code.","example":500}},"title":"ErrorResponse"}}},"description":"Unauthorized - API key required"},"403":{"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"A description of the error that occurred.","example":"Failed to retrieve status."},"details":{"type":"string","description":"Additional details about the error.","example":"Failed due to network timeout."},"code":{"type":"integer","description":"The error code.","example":500}},"title":"ErrorResponse"}}},"description":"Forbidden - Insufficient permissions"},"404":{"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"A description of the error that occurred.","example":"Failed to retrieve status."},"details":{"type":"string","description":"Additional details about the error.","example":"Failed due to network timeout."},"code":{"type":"integer","description":"The error code.","example":500}},"title":"ErrorResponse"}}},"description":"No record of the machine."},"500":{"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"A description of the error that occurred.","example":"Failed to retrieve status."},"details":{"type":"string","description":"Additional details about the error.","example":"Failed due to network timeout."},"code":{"type":"integer","description":"The error code.","example":500}},"title":"ErrorResponse"}}},"description":"An error on the controller."},"503":{"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"A description of the error that occurred.","example":"Failed to retrieve status."},"details":{"type":"string","description":"Additional details about the error.","example":"Failed due to network timeout."},"code":{"type":"integer","description":"The error code.","example":500}},"title":"ErrorResponse"}}},"description":"Admission is not configured: set controller.pki.enabled."}}}
Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
---
2+
id: delete-machine
3+
title: "Delete a machine"
4+
description: "Removes a machine's key and each record of it, and keeps none. A machine that asks again is new. Use it for a machine that goes away on purpose, such as a VM that is rebuilt; revoke a machine that is not trusted."
5+
sidebar_label: "Delete a machine"
6+
hide_title: true
7+
hide_table_of_contents: true
8+
api: eJztWN1v2zYQ/1cOfNkGKLLTNS8a+uCh6eAhGYYu3R6SoDiLZ4m1RKrk0bFn6H8fjpI/mmbFXjPkySJ937/j8Y47pSmU3nRsnFWFek+tW1MAhBbL2lj6LsCKtoBWA2FZg6fSeQ1uCYaztL0i6gJYZymH2Z4NuEYGDKsAWKGxYAJYesjhQyAwDEvnjzoG4sqJ3gfcgrPQRd+5QBmEWNaAYtCf1wOdCeBpEU3DP4GntVvRY0miyzGwj4FJ5ypTriOP4uJcq0K9pYaYrgcWlakOPbbE5IMqbnePInJT00H6/K04zjWBdZpEsBGSDrlWmbLYkirUSPzRaJUpT5+j8aRVwT5SpkJZU4uq2KkWN1dkK65V8eriIlOtsfv1eaZ424mswN7YSvWZ2pw57MxZ6TRVZM9owx7PGKsgstbYGI0sHHuFWWvsm/Osxc2bVxcXqu/vxZjQORso8byavpaff3fWBNApUDoXA15Pp0JfOstkWT6x6xpTprBOPgXh3534N3rgFp+oZAmyFxDYDNrJe+dPyEZHs0f2zOBkvY994h2QdmUZvR8wpg22XSPC3qFpSAM78MTe0JogMHIMyRFNjKYJ/0G51kY+sYGRB3DhIh+NeFKtjiSqLfGD8ytg05KLnFQLeid6jWWqyH+l+ObgZDmm2UHJxXTa95liw0nlpVC9H2FVfd8/JUpSgsLhWKRkGSE9f4H02UH6wWLk2nnzN2k4g9nv81ShD5UmAfvjC7DPDth3zi+M1mThDOY2xOXSlIYsQ0e+NSEYZ8OA7usXdJ8dur+5k96Jj/dsMufi5XJ9hpDO7CjJ2WS2wOdd05AfQX2pws8QVD3W2n2/VDq7NFX0pAsIxKcodyuTk8VFk3rkPlOByugNb9Mc8TOhJz+L0tLfKtzLLR68YVL30pEPDfztUenH2e/zjwdSdZ+plrh2MrUMzXgaV0SimmBnJgfSye44d/RKLPHrYaC5P5r1h+TakE6nxh3CWzN3ahxSZL1IRCobP9453yKrQv36101y19ilS+xjcF3AznwNzrYjnYGnjpAlWHAYx0IaBK+MjRuoXeCQwy9mTbB10QNWcvkhLBsizgSLO4sQamqa/M7e2aQNGuIAaGE2HxlatFjRqVDg2rtY1SBu6hPto9D93wiNq4zN4VIm3QOZJALCgmpcG+cLcGnONLaSc49JRXZnNS2NFenyr2kpgwfDInNpNqTB2C5ympdd5C5yDoP5ZU3lKqTZ+s7uO/UFLZ1Pc/LnSJECGJbZOlDprAYfLZQ12opSgoolo8nDLpggouSuIZ3fWZUpSYUBjPN8mk9VlqoSlqkqRd+M2IdiMqkM13GRl66dJAvPjBs+5Dg2piQ5N8VuP+1ez2/gatzNHolyHdngoi8pd76ajMxhcj0f0qdzgVu0J9KGyfw4zz/OpZNq+n99qhiPItOGJ12DxkrcU1x348m/VcMpO5aJTBUnrw73mZKcFMLdboGBPvim72X7cyS/HUrCGr2Rszi8eJiQipgqltgE+kbQv38/jhk/wLcfRp50Y9xEu5WcxCbKSmVqRdsvH076+z5TNaEmnwwcCGZlSR2fsH51n/anBfPt5dXlzaUE6ssq96iqJQVPWrbbDRQ3bkW27w+GsqzFxr7/B265r7A=
9+
sidebar_class_name: "delete api-method"
10+
info_path: gen/api/osapi
11+
custom_edit_url: null
12+
---
13+
14+
import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
15+
import ParamsDetails from "@theme/ParamsDetails";
16+
import RequestSchema from "@theme/RequestSchema";
17+
import StatusCodes from "@theme/StatusCodes";
18+
import OperationTabs from "@theme/OperationTabs";
19+
import TabItem from "@theme/TabItem";
20+
import Heading from "@theme/Heading";
21+
import Translate from "@docusaurus/Translate";
22+
23+
<Heading
24+
as={"h1"}
25+
className={"openapi__heading"}
26+
children={"Delete a machine"}
27+
>
28+
</Heading>
29+
30+
<MethodEndpoint
31+
method={"delete"}
32+
path={"/api/admission/{machine_id}"}
33+
context={"endpoint"}
34+
>
35+
36+
</MethodEndpoint>
37+
38+
39+
40+
Removes a machine's key and each record of it, and keeps none. A machine that asks again is new. Use it for a machine that goes away on purpose, such as a VM that is rebuilt; revoke a machine that is not trusted.
41+
42+
<Heading
43+
id={"request"}
44+
as={"h2"}
45+
className={"openapi-tabs__heading"}
46+
>
47+
<Translate id="theme.openapi.request.title">Request</Translate>
48+
</Heading>
49+
50+
<ParamsDetails
51+
{...require("./delete-machine.ParamsDetails.json")}
52+
>
53+
54+
</ParamsDetails>
55+
56+
<RequestSchema
57+
{...require("./delete-machine.RequestSchema.json")}
58+
>
59+
60+
</RequestSchema>
61+
62+
<StatusCodes
63+
{...require("./delete-machine.StatusCodes.json")}
64+
>
65+
66+
</StatusCodes>
67+
68+
69+

‎docs/docs/gen/api/sidebar.ts‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,12 @@ const sidebar: SidebarsConfig = {
2020
label: "List admission records",
2121
className: "api-method get",
2222
},
23+
{
24+
type: "doc",
25+
id: "gen/api/delete-machine",
26+
label: "Delete a machine",
27+
className: "api-method delete",
28+
},
2329
{
2430
type: "doc",
2531
id: "gen/api/get-admission",

‎docs/docs/sidebar/features/agent-identity.md‎

Lines changed: 17 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -116,9 +116,14 @@ osapi client admission admit --machine-id <machine-id> \
116116
# Reject a machine, with the reason
117117
osapi client admission reject --machine-id <machine-id> --reason "unknown host"
118118

119-
# Revoke an admitted machine: its key stops verifying at once
119+
# Revoke an admitted machine that is not trusted: its key stops verifying at
120+
# once, and a record shows it if it asks again
120121
osapi client admission revoke --machine-id <machine-id>
121122

123+
# Delete a machine that goes away on purpose, such as before a rebuild: its key
124+
# and each record of it go, and it is new if it asks again
125+
osapi client admission delete --machine-id <machine-id>
126+
122127
# Show the local controller key fingerprint
123128
osapi client controller key fingerprint
124129
```
@@ -305,18 +310,22 @@ controller:
305310
enabled: false
306311
# Directory for controller keypair storage.
307312
key_dir: /etc/osapi/pki
308-
# Automatically accept all enrollment requests (dev only).
313+
# Admit each machine that asks to join (development and tests).
309314
auto_admit: false
310315
# Grace period for key rotation (Go duration).
311316
rotation_grace_period: 24h
317+
# Delete an admitted machine that has not reported for this long
318+
# (Go duration, such as 720h). Empty is never.
319+
delete_after: ''
312320
```
313321

314-
| Field | Type | Default | Description |
315-
| ----------------------- | ------ | ---------------- | ------------------------------------------------------------ |
316-
| `enabled` | bool | `false` | Turn on PKI enrollment and job signing |
317-
| `key_dir` | string | `/etc/osapi/pki` | Directory for the controller key pair |
318-
| `auto_admit` | bool | `false` | Admit each machine that asks to join (development and tests) |
319-
| `rotation_grace_period` | string | `24h` | osapi accepts both keys during rotation |
322+
| Field | Type | Default | Description |
323+
| ----------------------- | ------ | ---------------- | -------------------------------------------------------------- |
324+
| `enabled` | bool | `false` | Turn on PKI enrollment and job signing |
325+
| `key_dir` | string | `/etc/osapi/pki` | Directory for the controller key pair |
326+
| `auto_admit` | bool | `false` | Admit each machine that asks to join (development and tests) |
327+
| `rotation_grace_period` | string | `24h` | osapi accepts both keys during rotation |
328+
| `delete_after` | string | empty | Delete an admitted machine that has not reported for this long |
320329

321330
## What does not change
322331

‎docs/docs/sidebar/sdk/client/agent/admission.md‎

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@ machine can be revoked later.
1717
| `Admit(ctx, machineID, fingerprint)` | Admit a pending machine |
1818
| `Reject(ctx, machineID, reason)` | Reject a pending machine |
1919
| `Revoke(ctx, machineID)` | Remove the key of an admitted machine |
20+
| `Delete(ctx, machineID)` | Remove a machine and each record of it |
2021

2122
The state is `pending`, `admitted`, `rejected` or `revoked`.
2223

@@ -40,8 +41,13 @@ err := c.Admission.Admit(ctx, "d530664edc1c431eb5ef1e9dfd6617a5", "SHA256:1f53de
4041
// Reject, with the reason
4142
err := c.Admission.Reject(ctx, "d530664edc1c431eb5ef1e9dfd6617a5", "unknown host")
4243

43-
// Revoke: nothing that the machine signs verifies after this
44+
// Revoke a machine that is not trusted: nothing that it signs verifies
45+
// after this, and a record shows it if it asks again
4446
err := c.Admission.Revoke(ctx, "d530664edc1c431eb5ef1e9dfd6617a5")
47+
48+
// Delete a machine that goes away on purpose, such as before a rebuild: it
49+
// leaves no record, and is new if it asks again
50+
err := c.Admission.Delete(ctx, "d530664edc1c431eb5ef1e9dfd6617a5")
4551
```
4652

4753
Admit compares the fingerprint with the key in the request of the machine. A
@@ -82,6 +88,6 @@ Refer to
8288

8389
## Permissions
8490

85-
List and Get need `admission:read`. Admit, Reject and Revoke need
91+
List and Get need `admission:read`. Admit, Reject, Revoke and Delete need
8692
`admission:write`, and return only an error: the API answers 204. When PKI is
8793
off, each method returns the 503 error of the API.

0 commit comments

Comments
 (0)