Blueprints

Blueprints

Plan and apply reusable infrastructure definitions with recorded resource identities.

Blueprints define a set of project resources and produce a reviewed change plan. They suit repeatable environments that combine networks, droplets, storage, and operational labels.

Definition

A blueprint contains an API version, project scope, and resources identified by stable logical names. References can use another resource's logical name within the same blueprint. External IDs must already exist in the destination scope.

Save this definition as payments.yaml in your deployment directory:

YAML
apiVersion: infra.solarius.me/v1
kind: Blueprint
metadata:
  name: payments-web
spec:
  organizationId: org_main
  projectId: prj_payments
  resources:
    production:
      type: network
      regionId: reg_euwest
      ipv4Cidr: 10.42.0.0/24
    web:
      type: droplet
      regionId: reg_euwest
      imageId: img_ubuntu
      vcpus: 2
      memoryMiB: 4096
      rootVolume:
        sizeGiB: 30
        storagePolicyId: sp_replicated
      networkRef: production
      labels:
        service: web
        environment: production

This example requires an available image and storage policy in reg_euwest. The network logical name resolves to the network created by the blueprint. Blueprint field names use their schema's casing; HTTP request fields use the API schema.

Plan

From that directory, generate a saved plan for review:

Shell
infra blueprints plan --file payments.yaml --out payments.plan.json

Planning validates syntax, resolves current IDs and revisions, and lists creates, updates, replacements, and deletions. It does not reserve all required capacity or prove that guest initialization will succeed.

Review replacement actions carefully. Changing a region or image can require a new droplet rather than an in-place edit. The plan identifies separately retained volumes, addresses, and backups.

Apply

After reviewing the proposed changes, apply the saved plan:

Shell
infra blueprints apply --plan payments.plan.json --wait

Apply checks the recorded scope and revisions before execution. A changed resource can make the plan stale; regenerate it rather than forcing an old plan over current state. The accepted apply returns a parent operation and child operations for each resource change.

Resources execute in dependency order where the blueprint declares references. Unrelated resources can progress independently. A failure does not roll back all previous children. The result records partial changes and the logical-name-to-ID mapping needed for the next plan.

Ownership and drift

Infra records which blueprint manages each logical resource. Renaming a logical name is treated as removing one managed entry and adding another unless an explicit import or rename operation preserves the mapping.

Console changes to a managed resource appear as drift on the next plan. Choose whether to update the definition or restore its declared configuration. A blueprint does not continuously overwrite manual changes unless an explicit reconciliation schedule is enabled.

Removal

Removing a definition entry proposes deletion according to the resource's retention settings. Deletion protection, attached-volume dependencies, and backup retention still apply. Deleting the local YAML file performs no server action.

Keep blueprint definitions and reviewed plans in version control without secret values. Reference approved secret IDs and use service-account access for automated application.

Use import, rename, and detach when adopting existing resources or changing logical ownership. The Blueprint API exposes plan revisions, mapped state, and active apply locks.