generated from coulomb/repo-seed
300 lines
9.4 KiB
Markdown
300 lines
9.4 KiB
Markdown
---
|
|
id: netkingdom-playbook-capability-contract
|
|
type: standard
|
|
title: "NetKingdom Playbook Capability Contract v0.1"
|
|
domain: netkingdom
|
|
status: accepted
|
|
version: "0.1"
|
|
created: "2026-05-22"
|
|
updated: "2026-05-22"
|
|
scope: meta-orchestration
|
|
adr:
|
|
- docs/adr/ADR-0012-playbook-capability-contract-ownership.md
|
|
schema:
|
|
- canon/schemas/playbook-capability-declaration_v0.1.schema.json
|
|
validator:
|
|
- tools/playbook-capability-contract/playbook_contract_validator.py
|
|
---
|
|
|
|
# NetKingdom Playbook Capability Contract v0.1
|
|
|
|
## Purpose
|
|
|
|
The Playbook Capability Contract is the declared interface between
|
|
NetKingdom meta-orchestration and Railiance execution playbooks.
|
|
|
|
It lets a playbook state:
|
|
|
|
- which capability it provisions;
|
|
- which parameters it exposes, including defaults, constraints, and
|
|
security sensitivity;
|
|
- which resources and responsibilities it claims;
|
|
- which trust states it requires or satisfies;
|
|
- how it is published into a catalog.
|
|
|
|
NetKingdom consumes declarations to select playbooks, choose safe
|
|
parameter overrides, sequence trust states, and build a responsibility
|
|
map. Railiance owns the playbooks and execution mechanics.
|
|
|
|
## Ownership
|
|
|
|
NetKingdom owns this contract. Railiance publishes conformant
|
|
declarations. Execution stays in Railiance. See ADR-0012.
|
|
|
|
## File Convention
|
|
|
|
Declaration files SHOULD live in the publishing repo at:
|
|
|
|
```text
|
|
capabilities/playbooks/<declaration-id>.yaml
|
|
```
|
|
|
|
Each file describes one playbook or one stable playbook entry point. A
|
|
playbook with materially different modes may publish multiple
|
|
declarations if those modes provide different capabilities or expose
|
|
different security-sensitive parameters.
|
|
|
|
## Top-Level Shape
|
|
|
|
```yaml
|
|
apiVersion: netkingdom.io/playbook-capability/v0.1
|
|
kind: PlaybookCapabilityDeclaration
|
|
metadata:
|
|
id: railiance-infra.bootstrap-host
|
|
name: Railiance S1 host bootstrap
|
|
owner: railiance-infra
|
|
repo: railiance-infra
|
|
domain: railiance
|
|
contract_version: "0.1"
|
|
spec:
|
|
playbook: {}
|
|
capabilities: []
|
|
parameters: []
|
|
responsibilities: []
|
|
trust: {}
|
|
catalog: {}
|
|
```
|
|
|
|
## Capability Vocabulary
|
|
|
|
`spec.capabilities[].id` MUST be one of the controlled vocabulary values
|
|
below. Capability ids are stable comparison keys.
|
|
|
|
| Capability id | Tier | Meaning |
|
|
| --- | --- | --- |
|
|
| `s1.os-baseline` | S1 | Host provisioning, OS convergence, hardening, and substrate access baseline |
|
|
| `s1.secret-bootstrap` | S1 | Bootstrap secret material, SOPS/age handling, emergency material placement |
|
|
| `s2.cluster-runtime` | S2 | Kubernetes runtime, ingress, networking, admission, and cluster access |
|
|
| `s3.platform-services` | S3 | Databases, caches, object storage, brokers, and shared platform services |
|
|
| `c0.bootstrap-identity` | C0 | Local/bootstrap identity before runtime IAM exists |
|
|
| `c1.lightweight-sso` | C1 | key-cape lightweight SSO profile implementation |
|
|
| `c2a.light-2fa` | C2a | Lightweight built-in second factor such as TOTP/WebAuthn |
|
|
| `c2b.token-authority` | C2b | privacyIDEA or equivalent token authority |
|
|
| `c3.runtime-secrets` | C3 | OpenBao or equivalent runtime secret authority |
|
|
| `c4.fine-grained-authorization` | C4 | flex-auth and delegated PDP readiness |
|
|
| `c5.enterprise-federation` | C5 | expanded-mode Keycloak, enterprise federation, or SAML brokering |
|
|
| `c6.self-optimizing-audit` | C6 | audit feedback loops, drift surfacing, and continuous adaptation |
|
|
|
|
The `S*` entries align to Railiance stack layers. The `C*` entries align
|
|
to the NetKingdom capability progression. A declaration may list more
|
|
than one capability only when the same playbook entry point truly
|
|
provides each one.
|
|
|
|
## Resource Kinds
|
|
|
|
Every capability and responsibility claim references one or more
|
|
resource kinds:
|
|
|
|
| Resource kind | Meaning |
|
|
| --- | --- |
|
|
| `identities` | humans, service accounts, agents, groups, tenants, and assurance evidence |
|
|
| `roles_scopes_policies` | roles, scopes, policy packages, protected-system registrations, decision records |
|
|
| `secrets_credentials` | bootstrap material, runtime secrets, dynamic credentials, leases, credential rotations |
|
|
| `infrastructure_resources` | hosts, runtime, networking, platform services, storage, and deployment substrate |
|
|
|
|
## Parameter Declarations
|
|
|
|
Each parameter entry has this shape:
|
|
|
|
```yaml
|
|
- name: swapfile_size_mb
|
|
type: integer
|
|
required: false
|
|
default: 4096
|
|
constraints:
|
|
minimum: 0
|
|
maximum: 65536
|
|
sensitivity: operational
|
|
tuning_authority: netkingdom_tunable
|
|
description: Swap size applied by the bootstrap playbook.
|
|
```
|
|
|
|
Allowed `type` values:
|
|
|
|
- `string`
|
|
- `integer`
|
|
- `number`
|
|
- `boolean`
|
|
- `array`
|
|
- `object`
|
|
|
|
Allowed `sensitivity` values:
|
|
|
|
- `public` - safe to display and tune freely.
|
|
- `operational` - affects behavior or sizing, not secret material.
|
|
- `security_sensitive` - affects security posture and requires platform
|
|
review.
|
|
- `secret_reference` - points to secret material but must not contain the
|
|
secret value itself.
|
|
|
|
Allowed `tuning_authority` values:
|
|
|
|
- `playbook_default` - NetKingdom should rely on the playbook default.
|
|
- `netkingdom_tunable` - NetKingdom may override for a scenario.
|
|
- `platform_only` - only platform-control-plane authority may override.
|
|
- `tenant_tunable` - tenant-scoped scenario owners may override within
|
|
constraints.
|
|
- `forbidden` - declaration exposes the value for audit only; callers may
|
|
not override it.
|
|
|
|
Security-sensitive and secret-reference parameters MUST NOT be
|
|
`tenant_tunable`. Secret-reference defaults must be references or paths,
|
|
not plaintext secret values.
|
|
|
|
Supported constraints:
|
|
|
|
| Constraint | Applies to | Meaning |
|
|
| --- | --- | --- |
|
|
| `enum` | all scalar types | value must be one of the listed values |
|
|
| `minimum` / `maximum` | integer, number | numeric bounds |
|
|
| `min_items` / `max_items` | array | array length bounds |
|
|
| `pattern` | string | regular expression the value must match |
|
|
|
|
## Responsibility Claims
|
|
|
|
Responsibility entries feed the responsibility map. They do not transfer
|
|
execution ownership to NetKingdom.
|
|
|
|
```yaml
|
|
- resource_kind: infrastructure_resources
|
|
owner: railiance-infra
|
|
resources:
|
|
- server:target_hosts
|
|
- os-baseline
|
|
repo_owns: Provisioning, convergence, and verification mechanics.
|
|
netkingdom_orchestrates: Whether this substrate capability is selected, and which security posture is required.
|
|
```
|
|
|
|
`owner` names the repo or provider that holds execution ownership.
|
|
`repo_owns` explains the implementation responsibility.
|
|
`netkingdom_orchestrates` explains the meta-orchestration responsibility.
|
|
|
|
## Trust States And Readiness
|
|
|
|
Declarations use the trust-state vocabulary from the platform
|
|
architecture:
|
|
|
|
- `bare_host_trust`
|
|
- `cluster_trust`
|
|
- `bootstrap_secret_trust`
|
|
- `bootstrap_identity_trust`
|
|
- `runtime_secret_trust`
|
|
- `runtime_identity_trust`
|
|
- `runtime_authorization_trust`
|
|
- `tenant_onboarding_trust`
|
|
|
|
Each declaration lists states it requires and states it satisfies:
|
|
|
|
```yaml
|
|
trust:
|
|
requires:
|
|
- state: bare_host_trust
|
|
readiness_checks: []
|
|
satisfies:
|
|
- state: bootstrap_secret_trust
|
|
readiness_checks:
|
|
- id: sops-age-material-present
|
|
description: SOPS/age material is present for bootstrap secrets.
|
|
evidence: ansible role sops_agent converged successfully
|
|
```
|
|
|
|
Readiness checks are evidence obligations. The declaration names the
|
|
check; the Railiance playbook or verification tooling performs it.
|
|
|
|
## Catalog And Consumption Model
|
|
|
|
A catalog is an index of declarations. For v0.1, the catalog mechanism is
|
|
file-based:
|
|
|
|
1. Railiance repos publish declarations under
|
|
`capabilities/playbooks/*.yaml`.
|
|
2. NetKingdom or a future catalog job discovers those files from known
|
|
orchestrated repos.
|
|
3. The validator checks each declaration against this contract.
|
|
4. A scenario states required capability ids and parameter overrides.
|
|
5. NetKingdom selects declarations that provide the required
|
|
capabilities.
|
|
6. NetKingdom applies only allowed parameter overrides, rejecting
|
|
out-of-range, tenant-forbidden, or security-unsafe overrides.
|
|
7. NetKingdom composes the responsibility and trust-state claims into a
|
|
scenario responsibility map and readiness sequence.
|
|
|
|
The declaration is not an execution plan. It is the interface that lets a
|
|
separate playbook runner execute safely.
|
|
|
|
## Scenario Shape
|
|
|
|
The validator supports a small scenario file for conformance demos:
|
|
|
|
```yaml
|
|
id: scenario:s1-host-bootstrap-reference
|
|
authority: platform
|
|
requires:
|
|
capabilities:
|
|
- s1.os-baseline
|
|
parameter_overrides:
|
|
railiance-infra.bootstrap-host:
|
|
target_hosts:
|
|
- railiance01
|
|
swapfile_size_mb: 8192
|
|
```
|
|
|
|
Allowed scenario authorities are `platform`, `netkingdom`, and `tenant`.
|
|
Tenant authority cannot override `platform_only`,
|
|
`security_sensitive`, or `secret_reference` parameters.
|
|
|
|
## Conformance
|
|
|
|
A declaration conforms when it passes:
|
|
|
|
```text
|
|
tools/playbook-capability-contract/playbook_contract_validator.py
|
|
```
|
|
|
|
The validator checks:
|
|
|
|
- top-level API version and kind;
|
|
- required metadata;
|
|
- controlled capability ids and tiers;
|
|
- resource-kind vocabulary;
|
|
- parameter type/default/constraint/sensitivity/tuning rules;
|
|
- responsibility claims;
|
|
- trust-state and readiness-check shape;
|
|
- catalog publication metadata;
|
|
- optional scenario selection and parameter override compatibility.
|
|
|
|
## Reference Adoption
|
|
|
|
The reference declaration for v0.1 is in:
|
|
|
|
```text
|
|
../railiance-infra/capabilities/playbooks/railiance-infra.bootstrap-host.yaml
|
|
```
|
|
|
|
It describes the existing Railiance S1 Ansible bootstrap playbook and can
|
|
be selected by the sample scenario in:
|
|
|
|
```text
|
|
examples/playbook-capability-contract/scenario-s1-host-bootstrap.yaml
|
|
```
|