Blueprints

Early access. Enterprise blueprints are available in assisted deployments and may evolve during rollout. Review generated changes before applying them.

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

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. It is applied with one command to provision everything in a deterministic sequence.

Blueprints are designed for infrastructure-as-code workflows. They can be stored in version control, with changes reviewed in pull requests and applied through CI/CD pipelines.

Blueprint format

{
  "name": "prod-fleet",
  "join_rule": "invite",
  "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": {
    "audit_url": "https://ops.example.com/pilot-audit",
    "identity_url": "https://ops.example.com/pilot-identity"
  },
  "audit_export": {
    "format": "splunk_hec",
    "endpoint": "https://splunk.example.com:8088/services/collector",
    "token": "hec-token-here"
  },
  "roles": [
    {"external_id": "[email protected]", "role": "admin"},
    {"external_id": "[email protected]", "role": "member"}
  ],
  "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`, `token`, or `invite`. Defaults to `open`.
`enterprise` (bool, optional): Enable enterprise features. Defaults to `false`.
`policy` (object, optional): Network policy: `max_members`, `allowed_ports`, `description`.
`expr_policy` (object, optional): Programmable expression policy applied to the network. Same document as the `set_expr_policy` RPC.
`identity_provider` (object, optional): IDP configuration: `type`, `url`, `client_id`.
`webhooks` (object, optional): Webhook endpoints: `audit_url` and `identity_url`.
`audit_export` (object, optional): Export config: `format`, `endpoint`, `token`.
`roles` (array, optional): RBAC pre-assignments by external identity: `[{external_id, role}]` where role is `owner`, `admin`, or `member`. Applied when a matching node joins.
`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.
Apply expr policy: If `expr_policy` is present, install the programmable policy document on the network.
Configure IDP: Set the identity provider configuration if specified.
Configure webhooks: Register the `audit_url` / `identity_url` endpoints if specified.
Configure audit export: Set the audit export endpoint and format if specified.
Pre-assign roles: Store each `{external_id, role}` as a pre-assignment. The role is applied when a node with that external identity later joins. Membership is not required at apply time.

Each step is independent. If a later step fails, earlier steps are not rolled back, and the call returns an error immediately. The result's `actions` list names only the steps that succeeded. Failures are surfaced as the returned error, not itemized in the result.

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`, `token`, or `invite`.
`identity_provider.type` must be a valid provider type (`oidc`, `saml`, `entra_id`, `ldap`, `webhook`).
`roles` values must be `owner`, `admin`, or `member`.

If validation fails, no changes are made and the error is returned immediately. Policy fields like `max_members` and `allowed_ports` are not range-checked on the blueprint path. Those limits apply to the separate `set_network_policy` RPC.

Protocol command

To apply a blueprint:

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

The blueprint is the only payload field besides `admin_token`. The admin token is a global registry token. No network owner is assigned by the blueprint path, and there is no explicit `node_id` on the RPC.

Result format:

{
  "network_id": 5,
  "name": "prod-fleet",
  "created": true,
  "type": "provision_network_ok",
  "actions": [
    "created network 5 (prod-fleet)",
    "enabled enterprise features",
    "applied network policy",
    "configured splunk_hec audit export to https://splunk.example.com:8088/..."
  ]
}

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

For programmatic use, load a blueprint from a JSON file with the typed loader in the `common/registry/wire` package, then pass it to the client.

// Go SDK — the typed loader lives in common/registry/wire
import "github.com/pilot-protocol/common/registry/wire"
import "github.com/pilot-protocol/common/registry/client"

bp, err := wire.LoadBlueprint("network.json")   // *wire.NetworkBlueprint
// ProvisionNetwork takes a map[string]interface{} blueprint + admin token.
// Marshal the blueprint JSON into a map, or build the map directly.
result, err := c.ProvisionNetwork(blueprintMap, adminToken)

`wire.LoadBlueprint` reads and validates the JSON file, returning a typed struct. `client.Client.ProvisionNetwork(blueprint, adminToken)` takes the blueprint as a `map[string]interface{}` and the admin token. There is no explicit `nodeID` argument, and the blueprint path assigns no network owner.

Status query

Inspect the provisioning state of a network:

{
  "type": "get_provision_status",
  "admin_token": "your-admin-token"
}

This command takes no `network_id` and returns a registry-wide summary of all networks. Per network, it returns enterprise status, policy, `idp_type`, an `audit` format string, a `webhook_enabled` flag, and an `rbac_pre_assignments` count. This is a summary, not full configs or endpoints. It is used to verify a blueprint was applied.