Blueprints

A blueprint is a JSON document that describes an enterprise network. It is applied with a single command to provision the network, and is designed for infrastructure-as-code workflows.

Overview

A blueprint is a single JSON document that describes an entire enterprise network: its name, join rule, policies, identity provider, webhooks, audit export, role pre-assignments, and admin token. Applying it with one command causes the registry to provision everything in a deterministic sequence.

Blueprints can be stored in version control, reviewed in pull requests, and applied through CI/CD pipelines.

Blueprint format

{
  "name": "prod-fleet",
  "join_rule": "invite_only",
  "enterprise": true,
  "policy": {
    "max_members": 100,
    "allowed_ports": [80, 443, 1001],
    "description": "Production fleet - US East"
  },
  "identity_provider": {
    "type": "oidc",
    "url": "https://accounts.example.com/.well-known/openid-configuration",
    "client_id": "pilot-prod"
  },
  "webhooks": [
    {
      "url": "https://ops.example.com/pilot-events",
      "events": ["member.kicked", "network.policy_changed"]
    }
  ],
  "audit_export": {
    "format": "splunk_hec",
    "endpoint": "https://splunk.example.com:8088/services/collector",
    "token": "hec-token-here"
  },
  "roles": {
    "42": "admin",
    "108": "admin"
  },
  "network_admin_token": "network-specific-secret"
}

Fields reference

`name` (string, required): Network name. Lowercase alphanumeric with hyphens. Used for idempotent lookup.
`join_rule` (string, optional): One of `open`, `invite_only`, or `token`. Defaults to `open`.
`enterprise` (bool, optional): Enable enterprise features. Defaults to `false`.
`policy` (object, optional): Network policy: `max_members`, `allowed_ports`, `description`.
`identity_provider` (object, optional): IDP configuration: `type`, `url`, `client_id`.
`webhooks` (array, optional): Webhook endpoints: `url` and `events` filter.
`audit_export` (object, optional): Export config: `format`, `endpoint`, `token`.
`roles` (object, optional): Map of node ID (string) to role (`admin` or `member`). Pre-assigns RBAC roles.
`network_admin_token` (string, optional): Per-network admin token for delegated administration.

Apply sequence

When a blueprint is applied, the registry executes these steps in order:

Find or create: Look up the network by name. If it exists, use it. If not, create it with the specified join rule.
Enable enterprise: If `enterprise: true` and the network is not yet enterprise, enable it.
Set policies: Apply the `policy` object using merge-on-update semantics.
Configure IDP: Set the identity provider configuration if specified.
Configure audit export: Set the audit export endpoint and format if specified.
Configure webhooks: Register webhook endpoints if specified.
Assign roles: For each entry in `roles`, set the RBAC role. Nodes must already be members of the network.

Each step is independent. If a later step fails, earlier steps are not rolled back. The result includes which actions were taken and which failed.

Idempotency

Blueprints are idempotent. Applying the same blueprint twice produces the same result. The registry looks up the network by `name`:

If a network with that name exists, it is updated, not duplicated.
If no network with that name exists, a new one is created.

This makes blueprints safe to apply repeatedly in CI/CD pipelines. Re-applying after a partial failure completes the remaining steps without duplicating already-completed ones.

Validation

The registry validates the blueprint before applying any changes:

`name` is required and must match the network name rules (lowercase alphanumeric with hyphens).
`join_rule` must be one of `open`, `invite_only`, or `token`.
`policy.max_members` must be a non-negative integer.
`policy.allowed_ports` must have 100 or fewer entries.
`policy.description` must be 256 or fewer characters.
`identity_provider.type` must be a valid provider type (`oidc`, `saml`, `entra_id`, `ldap`, `webhook`).
`roles` values must be `admin` or `member`. The `owner` role cannot be assigned this way.

If validation fails, no changes are made and an error is returned.

Protocol command

To apply a blueprint:

{
  "command": "provision_network",
  "blueprint": {
    "name": "prod-fleet",
    "enterprise": true,
    "policy": { "max_members": 100 }
  },
  "node_id": 1,
  "admin_token": "your-admin-token"
}

The `node_id` identifies the agent that will be the network owner if a new network is created.

Result format:

{
  "network_id": 5,
  "created": true,
  "actions": [
    "network created",
    "enterprise enabled",
    "policy set",
    "audit export configured"
  ]
}

The `created` field indicates whether a new network was created (`true`) or an existing one was updated (`false`).

For programmatic use, a blueprint can be loaded from a JSON file:

<span class="comment"># Go SDK</span>
bp, err := registry.LoadBlueprint("network.json")
result, err := client.ProvisionNetwork(bp, nodeID, adminToken)

`LoadBlueprint` reads and validates the JSON file.

Status query

To inspect the provisioning state of a network:

{
  "command": "get_provision_status",
  "network_id": 5,
  "admin_token": "your-admin-token"
}

This command returns the network’s current configuration as seen by the registry. This can be used to verify that a blueprint was applied correctly or to diff the current state against a desired state.