Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 26 additions & 13 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -191,19 +191,32 @@ Add the operation to the table in the domain landing page
Add the operation to an existing workflow example in
`examples/operations/` that covers the same domain. Domain groupings:

| Domain | Example file |
| ------- | -------------------- |
| Node | `node-info.go` |
| Node | `hostname-update.go` |
| Network | `dns-update.go` |
| Network | `ping.go` |
| Command | `command.go` |
| File | `file-deploy.go` |
| File | `file-changed.go` |
| Agent | `agent-drain.go` |
| Docker | `docker.go` |
| Cron | `cron.go` |
| Health | (used as gate) |
| Domain | Example file |
| ----------- | -------------------- |
| Node | `node-info.go` |
| Node | `hostname-update.go` |
| Network | `dns-update.go` |
| Network | `ping.go` |
| Interface | `interface.go` |
| Route | `route.go` |
| Command | `command.go` |
| File | `file-deploy.go` |
| File | `file-changed.go` |
| Agent | `agent-drain.go` |
| Docker | `docker.go` |
| Cron | `cron.go` |
| Sysctl | `sysctl.go` |
| NTP | `ntp.go` |
| Timezone | `timezone.go` |
| Service | `service.go` |
| Package | `package.go` |
| User | `user.go` |
| Group | `group.go` |
| Certificate | `certificate.go` |
| Process | `process.go` |
| Power | `power.go` |
| Log | `log.go` |
| Health | (used as gate) |

If no domain match exists, create a new `{domain}.go` file. Every
operation must appear in at least one runnable example.
Expand Down
37 changes: 25 additions & 12 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -41,18 +41,31 @@ the request:

## ⚙️ Operations

37 typed constructors across 8 domains:

| Domain | Docs | Example |
| ------ | ---- | ------- |
| Node | [8 operations](docs/operations/node/) | [node-info.go](examples/operations/node-info.go) |
| Network | [3 operations](docs/operations/network/) | [dns-update.go](examples/operations/dns-update.go) |
| Command | [2 operations](docs/operations/command/) | [command.go](examples/operations/command.go) |
| Docker | [9 operations](docs/operations/docker/) | [docker.go](examples/operations/docker.go) |
| Cron | [5 operations](docs/operations/cron/) | [cron.go](examples/operations/cron.go) |
| File | [5 operations](docs/operations/file/) | [file-deploy.go](examples/operations/file-deploy.go) |
| Agent | [4 operations](docs/operations/agent/) | [agent-drain.go](examples/operations/agent-drain.go) |
| Health | [1 operation](docs/operations/health/) | [basic.go](examples/features/basic.go) |
101 typed constructors across 21 domains:

| Domain | Docs | Example |
| ----------- | -------------------------------------------- | ---------------------------------------------------- |
| Node | [8 operations](docs/operations/node/) | [node-info.go](examples/operations/node-info.go) |
| Network | [4 operations](docs/operations/network/) | [dns-update.go](examples/operations/dns-update.go) |
| Interface | [5 operations](docs/operations/interface/) | [interface.go](examples/operations/interface.go) |
| Route | [5 operations](docs/operations/route/) | [route.go](examples/operations/route.go) |
| Command | [2 operations](docs/operations/command/) | [command.go](examples/operations/command.go) |
| Docker | [9 operations](docs/operations/docker/) | [docker.go](examples/operations/docker.go) |
| Cron | [5 operations](docs/operations/cron/) | [cron.go](examples/operations/cron.go) |
| Sysctl | [5 operations](docs/operations/sysctl/) | [sysctl.go](examples/operations/sysctl.go) |
| NTP | [4 operations](docs/operations/ntp/) | [ntp.go](examples/operations/ntp.go) |
| Timezone | [2 operations](docs/operations/timezone/) | [timezone.go](examples/operations/timezone.go) |
| Service | [10 operations](docs/operations/service/) | [service.go](examples/operations/service.go) |
| Package | [6 operations](docs/operations/package/) | [package.go](examples/operations/package.go) |
| User | [9 operations](docs/operations/user/) | [user.go](examples/operations/user.go) |
| Group | [5 operations](docs/operations/group/) | [group.go](examples/operations/group.go) |
| Certificate | [4 operations](docs/operations/certificate/) | [certificate.go](examples/operations/certificate.go) |
| Process | [3 operations](docs/operations/process/) | [process.go](examples/operations/process.go) |
| Power | [2 operations](docs/operations/power/) | [power.go](examples/operations/power.go) |
| Log | [3 operations](docs/operations/log/) | [log.go](examples/operations/log.go) |
| File | [5 operations](docs/operations/file/) | [file-deploy.go](examples/operations/file-deploy.go) |
| Agent | [4 operations](docs/operations/agent/) | [agent-drain.go](examples/operations/agent-drain.go) |
| Health | [1 operation](docs/operations/health/) | [basic.go](examples/features/basic.go) |

## ✨ Features

Expand Down
39 changes: 26 additions & 13 deletions docs/operations/README.md
Original file line number Diff line number Diff line change
@@ -1,21 +1,34 @@
# Operations

The orchestrator provides 37 typed constructors organized by domain. Each method
returns a `*Step` that can be chained with ordering, conditions, and error
handling.
The orchestrator provides 101 typed constructors organized by domain. Each
method returns a `*Step` that can be chained with ordering, conditions, and
error handling.

## Domains

| Domain | Operations | Description |
| ------------------- | ---------- | ------------------------------------------------- |
| [Node](node/) | 8 | Hostname, disk, memory, load, uptime, OS, status |
| [Network](network/) | 3 | DNS configuration, ping |
| [Command](command/) | 2 | Direct exec, shell commands |
| [Docker](docker/) | 9 | Container lifecycle, exec, images |
| [Cron](cron/) | 5 | Cron drop-in file management |
| [File](file/) | 5 | Upload, deploy, status, undeploy, drift detection |
| [Agent](agent/) | 4 | Discovery, inspection, drain/undrain |
| [Health](health/) | 1 | Liveness check |
| Domain | Operations | Description |
| --------------------------- | ---------- | ------------------------------------------------- |
| [Node](node/) | 8 | Hostname, disk, memory, load, uptime, OS, status |
| [Network](network/) | 4 | DNS configuration, ping |
| [Interface](interface/) | 5 | Network interface configuration via Netplan |
| [Route](route/) | 5 | Network route configuration via Netplan |
| [Command](command/) | 2 | Direct exec, shell commands |
| [Docker](docker/) | 9 | Container lifecycle, exec, images |
| [Cron](cron/) | 5 | Cron drop-in file management |
| [Sysctl](sysctl/) | 5 | Kernel parameter management |
| [NTP](ntp/) | 4 | NTP server configuration |
| [Timezone](timezone/) | 2 | System timezone management |
| [Service](service/) | 10 | Systemd service lifecycle and unit files |
| [Package](package/) | 6 | System package management |
| [User](user/) | 9 | User accounts, SSH keys, passwords |
| [Group](group/) | 5 | Local group management |
| [Certificate](certificate/) | 4 | CA certificate trust store management |
| [Process](process/) | 3 | Process listing, inspection, signals |
| [Power](power/) | 2 | Reboot and shutdown |
| [Log](log/) | 3 | Systemd journal queries |
| [File](file/) | 5 | Upload, deploy, status, undeploy, drift detection |
| [Agent](agent/) | 4 | Discovery, inspection, drain/undrain |
| [Health](health/) | 1 | Liveness check |

## Idempotency

Expand Down
26 changes: 26 additions & 0 deletions docs/operations/certificate/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
# Certificate Management

Manage CA certificates in the system trust store on target nodes -- list,
create, update, and delete certificates backed by the file provider.

## Operations

| Method | Description | Idempotent |
| ---------------------------------------------------- | ----------------------- | -------------- |
| [`CertificateList(target)`](list.md) | List CA certificates | Read-only |
| [`CertificateCreate(target, opts)`](create.md) | Create a CA certificate | Non-idempotent |
| [`CertificateUpdate(target, name, opts)`](update.md) | Update a CA certificate | Idempotent |
| [`CertificateDelete(target, name)`](delete.md) | Delete a CA certificate | Idempotent |

## Permissions

| Operation | Permission |
| ---------------- | ------------------- |
| Read operations | `certificate:read` |
| Write operations | `certificate:write` |

## Example

See
[`examples/operations/certificate.go`](../../examples/operations/certificate.go)
for a complete workflow example covering all operations.
55 changes: 55 additions & 0 deletions docs/operations/certificate/create.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,55 @@
# CertificateCreate

Creates a CA certificate in the system trust store. The PEM file must be
uploaded to the NATS Object Store first (see [FileUpload](../file/upload.md)).

## Usage

```go
step := o.CertificateCreate("web-01", osapi.CertificateCreateOpts{
Name: "internal-ca",
Object: "internal-ca.pem",
})
```

## Parameters

| Parameter | Type | Description |
| --------- | ----------------------- | --------------------------------------------------------- |
| `target` | `string` | Target host: `_any`, `_all`, hostname, or label selector. |
| `opts` | `CertificateCreateOpts` | Create options (see below). |

### CertificateCreateOpts

| Field | Type | Required | Description |
| -------- | -------- | -------- | ---------------------------------------- |
| `Name` | `string` | Yes | Certificate name. |
| `Object` | `string` | Yes | Object Store reference for the PEM file. |

## Result Type

```go
var result osapi.CertificateCAMutationResult
err := results.Decode("create-certificate-1", &result)
```

| Field | Type | Description |
| --------- | -------- | --------------------------------------------------- |
| `Name` | `string` | Certificate name. |
| `Changed` | `bool` | Whether the certificate was created. |
| `Error` | `string` | Error message if creation failed; empty on success. |

## Idempotency

**Non-idempotent.** Creating a certificate that already exists returns an error.
Use [CertificateUpdate](update.md) to replace existing certificates.

## Permissions

Requires `certificate:write` permission.

## Example

See
[`examples/operations/certificate.go`](https://github.com/osapi-io/osapi-orchestrator/blob/main/examples/operations/certificate.go)
for a complete working example.
43 changes: 43 additions & 0 deletions docs/operations/certificate/delete.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
# CertificateDelete

Deletes a CA certificate from the system trust store.

## Usage

```go
step := o.CertificateDelete("web-01", "internal-ca")
```

## Parameters

| Parameter | Type | Description |
| ---------- | -------- | --------------------------------------------------------- |
| `target` | `string` | Target host: `_any`, `_all`, hostname, or label selector. |
| `certName` | `string` | Name of the certificate to delete. |

## Result Type

```go
var result osapi.CertificateCAMutationResult
err := results.Decode("delete-certificate-1", &result)
```

| Field | Type | Description |
| --------- | -------- | ------------------------------------------------------ |
| `Name` | `string` | Certificate name. |
| `Changed` | `bool` | Whether the certificate was removed or already absent. |
| `Error` | `string` | Error message if deletion failed; empty on success. |

## Idempotency

**Idempotent.** If the certificate does not exist, returns `Changed: false`.

## Permissions

Requires `certificate:write` permission.

## Example

See
[`examples/operations/certificate.go`](https://github.com/osapi-io/osapi-orchestrator/blob/main/examples/operations/certificate.go)
for a complete working example.
50 changes: 50 additions & 0 deletions docs/operations/certificate/list.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,50 @@
# CertificateList

Lists CA certificates in the system trust store on the target node.

## Usage

```go
step := o.CertificateList("web-01")
```

## Parameters

| Parameter | Type | Description |
| --------- | -------- | --------------------------------------------------------- |
| `target` | `string` | Target host: `_any`, `_all`, hostname, or label selector. |

## Result Type

```go
var result osapi.CertificateCAResult
err := results.Decode("list-certificate-1", &result)
```

| Field | Type | Description |
| -------------- | ----------------- | ------------------------------------------------ |
| `Hostname` | `string` | The node's hostname. |
| `Certificates` | `[]CertificateCA` | List of CA certificate entries. |
| `Error` | `string` | Error message if query failed; empty on success. |

### CertificateCA

| Field | Type | Description |
| -------- | -------- | ------------------------------------------ |
| `Name` | `string` | Certificate name. |
| `Source` | `string` | Path to the certificate on the filesystem. |
| `Object` | `string` | Object Store reference. |

## Idempotency

**Read-only.** Never modifies state. Always returns `Changed: false`.

## Permissions

Requires `certificate:read` permission.

## Example

See
[`examples/operations/certificate.go`](https://github.com/osapi-io/osapi-orchestrator/blob/main/examples/operations/certificate.go)
for a complete working example.
53 changes: 53 additions & 0 deletions docs/operations/certificate/update.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,53 @@
# CertificateUpdate

Updates a CA certificate in the system trust store.

## Usage

```go
step := o.CertificateUpdate("web-01", "internal-ca", osapi.CertificateUpdateOpts{
Object: "internal-ca-v2.pem",
})
```

## Parameters

| Parameter | Type | Description |
| ---------- | ----------------------- | --------------------------------------------------------- |
| `target` | `string` | Target host: `_any`, `_all`, hostname, or label selector. |
| `certName` | `string` | Name of the certificate to update. |
| `opts` | `CertificateUpdateOpts` | Update options (see below). |

### CertificateUpdateOpts

| Field | Type | Required | Description |
| -------- | -------- | -------- | -------------------------------------------- |
| `Object` | `string` | Yes | New Object Store reference for the PEM file. |

## Result Type

```go
var result osapi.CertificateCAMutationResult
err := results.Decode("update-certificate-1", &result)
```

| Field | Type | Description |
| --------- | -------- | ------------------------------------------------- |
| `Name` | `string` | Certificate name. |
| `Changed` | `bool` | Whether the certificate was actually modified. |
| `Error` | `string` | Error message if update failed; empty on success. |

## Idempotency

**Idempotent.** Compares the current PEM content against the new content.
Returns `Changed: true` only if the certificate was actually modified.

## Permissions

Requires `certificate:write` permission.

## Example

See
[`examples/operations/certificate.go`](https://github.com/osapi-io/osapi-orchestrator/blob/main/examples/operations/certificate.go)
for a complete working example.
26 changes: 26 additions & 0 deletions docs/operations/group/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
# Group Management

Manage local groups on target nodes -- list, get, create, update, and delete
groups.

## Operations

| Method | Description | Idempotent |
| ---------------------------------------------- | -------------------- | -------------- |
| [`GroupList(target)`](list.md) | List groups | Read-only |
| [`GroupGet(target, name)`](get.md) | Get a specific group | Read-only |
| [`GroupCreate(target, opts)`](create.md) | Create a group | Non-idempotent |
| [`GroupUpdate(target, name, opts)`](update.md) | Update a group | Idempotent |
| [`GroupDelete(target, name)`](delete.md) | Delete a group | Idempotent |

## Permissions

| Operation | Permission |
| ---------------- | ------------ |
| Read operations | `user:read` |
| Write operations | `user:write` |

## Example

See [`examples/operations/user.go`](../../examples/operations/user.go) for a
complete workflow example covering group operations.
Loading
Loading