Skip to content

docs: fix incorrect Foreman examples in NodeClassifier docs #131

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
slauger merged 1 commit into from
Mar 16, 2026
Merged

docs: fix incorrect Foreman examples in NodeClassifier docs #131

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
58 changes: 10 additions & 48 deletions docs/concepts/external-node-classification.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,52 +24,6 @@ The `openvox-enc` binary is a static Go binary shipped in the openvox-server con

## Supported Classifiers

### Foreman

Foreman provides an ENC endpoint that returns YAML. It supports both simple GET requests with mTLS (using Puppet certificates) and the v2 API with Basic Auth.

**GET with mTLS (classic):**

```yaml
apiVersion: openvox.voxpupuli.org/v1alpha1
kind: NodeClassifier
metadata:
name: foreman
spec:
url: https://foreman.example.com
request:
method: GET
path: /node/{certname}
response:
format: yaml
auth:
mtls: true
cache:
enabled: true
```

**GET with Basic Auth (API v2):**

```yaml
apiVersion: openvox.voxpupuli.org/v1alpha1
kind: NodeClassifier
metadata:
name: foreman-api
spec:
url: https://foreman.example.com
request:
method: GET
path: /api/v2/hosts/{certname}/enc
response:
format: yaml
auth:
basic:
secretRef:
name: foreman-credentials
usernameKey: username
passwordKey: password
```

### Puppet Enterprise

PE's Node Classifier uses a POST-based API that accepts node facts and returns JSON classification data.
Expand Down Expand Up @@ -143,7 +97,7 @@ spec:

| Method | Description | Use Case |
|---|---|---|
| `mtls` | Mutual TLS using Puppet SSL certificates | Foreman with Puppet CA trust |
| `mtls` | Mutual TLS using Puppet SSL certificates | Services trusting the Puppet CA |
| `token` | Custom HTTP header with token value | Puppet Enterprise (X-Authentication) |
| `bearer` | Authorization: Bearer header | Generic API services |
| `basic` | HTTP Basic Authentication | Foreman API v2, legacy services |
Expand Down Expand Up @@ -179,7 +133,7 @@ metadata:
name: production
spec:
authorityRef: production-ca
nodeClassifierRef: foreman
nodeClassifierRef: pe-classifier
image:
repository: ghcr.io/slauger/openvox-server
tag: "8.12.1"
Expand All @@ -193,3 +147,11 @@ external_nodes = /usr/local/bin/openvox-enc
```

For the full CRD reference, see [NodeClassifier](../reference/nodeclassifier.md).

## Known Limitations

### Foreman

Foreman is **not directly compatible** with the `NodeClassifier` CRD. Foreman's ENC protocol requires a separate facts upload (`POST /api/hosts/facts`) before the classification call (`GET /node/{certname}`), because its classification relies on its own internal fact database. The operator's `openvox-enc` binary uses the PE Classifier v1 API format — a single request with facts in the body — which Foreman does not implement.

See [#26](https://github.com/slauger/openvox-operator/issues/26) for details and planned workarounds.
20 changes: 2 additions & 18 deletions docs/reference/nodeclassifier.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,25 +6,9 @@ NodeClassifier is a standalone resource referenced by Config via `nodeClassifier

## Example

### Foreman (GET, mTLS)
### Foreman

```yaml
apiVersion: openvox.voxpupuli.org/v1alpha1
kind: NodeClassifier
metadata:
name: foreman
spec:
url: https://foreman.example.com
request:
method: GET
path: /node/{certname}
response:
format: yaml
auth:
mtls: true
cache:
enabled: true
```
Foreman is not directly compatible with the `NodeClassifier` CRD. See [#26](https://github.com/slauger/openvox-operator/issues/26) and the [External Node Classification](../concepts/external-node-classification.md#foreman) guide for details.

### Puppet Enterprise (POST, Token Auth)

Expand Down
Loading