generated from coulomb/repo-seed
Implement NK-WP-0013 playbook capability contract
This commit is contained in:
@@ -0,0 +1,56 @@
|
||||
{
|
||||
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
||||
"$id": "https://netkingdom.local/schemas/playbook-capability-declaration_v0.1.schema.json",
|
||||
"title": "NetKingdom Playbook Capability Declaration v0.1",
|
||||
"type": "object",
|
||||
"additionalProperties": false,
|
||||
"required": ["apiVersion", "kind", "metadata", "spec"],
|
||||
"properties": {
|
||||
"apiVersion": {
|
||||
"type": "string",
|
||||
"const": "netkingdom.io/playbook-capability/v0.1"
|
||||
},
|
||||
"kind": {
|
||||
"type": "string",
|
||||
"const": "PlaybookCapabilityDeclaration"
|
||||
},
|
||||
"metadata": {
|
||||
"type": "object",
|
||||
"additionalProperties": false,
|
||||
"required": ["id", "name", "owner", "repo", "domain", "contract_version"],
|
||||
"properties": {
|
||||
"id": {"type": "string", "minLength": 1},
|
||||
"name": {"type": "string", "minLength": 1},
|
||||
"owner": {"type": "string", "minLength": 1},
|
||||
"repo": {"type": "string", "minLength": 1},
|
||||
"domain": {"type": "string", "minLength": 1},
|
||||
"contract_version": {"type": "string", "const": "0.1"},
|
||||
"source_links": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "object",
|
||||
"additionalProperties": false,
|
||||
"required": ["label", "path"],
|
||||
"properties": {
|
||||
"label": {"type": "string", "minLength": 1},
|
||||
"path": {"type": "string", "minLength": 1}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"spec": {
|
||||
"type": "object",
|
||||
"additionalProperties": false,
|
||||
"required": ["playbook", "capabilities", "parameters", "responsibilities", "trust", "catalog"],
|
||||
"properties": {
|
||||
"playbook": {"type": "object"},
|
||||
"capabilities": {"type": "array", "minItems": 1},
|
||||
"parameters": {"type": "array"},
|
||||
"responsibilities": {"type": "array", "minItems": 1},
|
||||
"trust": {"type": "object"},
|
||||
"catalog": {"type": "object"}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
299
canon/standards/playbook-capability-contract_v0.1.md
Normal file
299
canon/standards/playbook-capability-contract_v0.1.md
Normal file
@@ -0,0 +1,299 @@
|
||||
---
|
||||
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
|
||||
```
|
||||
Reference in New Issue
Block a user