Blueprint Syntax and Best Practices

Last updated: March 4, 2026

Why a Dedicated Syntax Article

The Nutanix Blueprint 101 article covers concepts and a working example. But when I actually started writing blueprints as code with calm-dsl, I spent a lot of time digging through the DSL source code to understand exactly what syntax was valid where.

This article is a structured syntax reference with explanations of the choices I make, written the way I wish the documentation had been laid out.

Blueprint JSON/YAML Structure

When you export a blueprint from Prism Central (Blueprint Designer → Download), you get a JSON file. This is the raw data model that everything else — the UI and calm-dsl — generates from.

Understanding the top-level structure helps when reading API responses or debugging DSL-generated blueprints.

Top-Level Keys

{
  "kind": "blueprint",
  "metadata": {
    "name": "my-app-blueprint",
    "uuid": "...",
    "categories": {},
    "project_reference": { "kind": "project", "uuid": "..." }
  },
  "spec": {
    "name": "my-app-blueprint",
    "description": "...",
    "resources": {
      "credential_definition_list": [ ... ],
      "substrate_definition_list": [ ... ],
      "service_definition_list": [ ... ],
      "package_definition_list": [ ... ],
      "app_profile_list": [ ... ],
      "default_credential_local_reference": { ... }
    }
  },
  "status": { "state": "ACTIVE", ... },
  "api_version": "3.0"
}

The spec.resources object is the blueprint body. Everything else is metadata wrapping.

`app_profile_list` Items

Each profile contains:

name — profile identifier
uuid
variable_list — profile-level variable overrides
deployment_list — links services to substrates with replica counts
action_list — profile-level actions

`service_definition_list` Items

{
  "name": "AppService",
  "uuid": "...",
  "singleton": false,
  "depends_on_list": [
    { "kind": "app_service", "uuid": "...db-service-uuid..." }
  ],
  "variable_list": [...],
  "action_list": [...],   
  "container_spec": {}    
}

depends_on_list is how service dependency ordering is declared — it is the JSON equivalent of the arrow you draw in the Blueprint Designer canvas.

`substrate_definition_list` Items (AHV)

{
  "name": "AppSubstrate",
  "uuid": "...",
  "type": "AHV_VM",
  "os_type": "Linux",
  "readiness_probe": {
    "connection_type": "SSH",
    "port": "22",
    "retries": "5",
    "delay_secs": "10",
    "address": "@@{address}@@",
    "credential_local_reference": { "kind": "app_credential", "uuid": "..." }
  },
  "create_spec": {
    "name": "@@{calm_application_name}@@-@@{calm_array_index}@@",
    "resources": {
      "num_vcpus_per_socket": 2,
      "num_sockets": 1,
      "memory_size_mib": 4096,
      "power_state": "ON",
      "nic_list": [
        {
          "nic_type": "NORMAL_NIC",
          "network_function_nic_type": "INGRESS",
          "subnet_reference": { "kind": "subnet", "uuid": "...subnet-uuid..." }
        }
      ],
      "disk_list": [
        {
          "device_properties": {
            "device_type": "DISK",
            "disk_address": { "adapter_type": "SCSI", "device_index": 0 }
          },
          "data_source_reference": {
            "kind": "image",
            "uuid": "...image-uuid..."
          }
        }
      ],
      "guest_customization": {
        "cloud_init": {
          "user_data": "I2Nsb3VkLWNvbmZpZy4uLg=="
        }
      }
    }
  }
}

The user_data in guest_customization.cloud_init is base64-encoded cloud-init YAML. This is important when debugging: decode it to see the actual script.

The calm-dsl Python DSL Syntax Reference

calm-dsl is the official Python library that generates the JSON blueprint spec. Install it:

pip install calm-dsl
calm init dsl  # configure PC connection

Blueprint Skeleton

Every calm-dsl blueprint file follows this structure:

from calm.dsl.builtins import *

# 1. Credentials
MyCred = basic_cred(...)

# 2. VM image package reference
MyImage = vm_disk_package(...)

# 3. Service class(es)
class MyService(Service):
    ...

# 4. Substrate class(es)
class MySubstrate(Substrate):
    ...

# 5. Package class(es) — links service to image
class MyPackage(Package):
    ...

# 6. Deployment class(es) — links package+substrate with replica count
class MyDeployment(Deployment):
    ...

# 7. Profile class(es)
class DefaultProfile(Profile):
    deployments = [MyDeployment]

# 8. Blueprint class
class MyBlueprint(Blueprint):
    credentials = [MyCred]
    services = [MyService]
    packages = [MyPackage]
    substrates = [MySubstrate]
    profiles = [DefaultProfile]

The ordering matters for readability but not execution — Python class references resolve at parse time.

Credentials

from calm.dsl.builtins import basic_cred, Credential, read_local_file

# SSH key credential (preferred for Linux)
SSHCred = basic_cred(
    username="ubuntu",
    password=None,
    cred_type=Credential.SSH,
    private_key=read_local_file(".local/keys/id_rsa"),  # reads file at build time
    default=True,
    name="SSH-Ubuntu",
)

# Username + password credential (Windows or legacy)
WinCred = basic_cred(
    username="Administrator",
    password="@@{WIN_ADMIN_PASSWORD}@@",  # macro references a secret variable
    cred_type=Credential.PASSWORD,
    name="Win-Admin",
)

Key rule: Only one credential can be default=True per blueprint. This default is used for service readiness probes unless overridden per substrate.

Variables

Blueprint variables are defined as class attributes on Service, Profile, or Blueprint classes.

from calm.dsl.builtins import CalmVariable

class DefaultProfile(Profile):

    # Simple string — shown in launch form, editable
    app_version = CalmVariable.Simple(
        "v1.0.0",
        label="Application Version",
        description="Git tag to deploy",
        is_mandatory=True,
        runtime=True,   # editable at launch time
    )

    # Secret — masked in UI and logs
    db_password = CalmVariable.Simple.Secret(
        "",
        label="Database Password",
        is_mandatory=True,
        runtime=True,
    )

    # Integer with bounds
    replica_count = CalmVariable.Simple.int(
        "1",
        label="Web Tier Replicas",
        is_mandatory=False,
        runtime=True,
    )

    # Dropdown (multi-choice)
    environment = CalmVariable.Simple(
        "dev",
        label="Environment",
        runtime=True,
        options=["dev", "staging", "prod"],
    )

    # Dynamic variable — runs a script at launch time to populate choices
    available_versions = CalmVariable.WithOptions.FromTask.HTTP(
        CalmTask.HTTP.get(
            "https://gitlab.example.com/api/v4/projects/42/releases",
            headers={"PRIVATE-TOKEN": "@@{GITLAB_TOKEN}@@"},
            response_paths={"available_versions": "$.*.tag_name"},
        ),
        label="Available Release Tags",
        runtime=True,
    )

    deployments = [AppDeployment]

Variable Scoping Rules

Scope

Defined On

Accessible In

Blueprint-level

Blueprint class

All profiles, all services

Profile-level

Profile class

Services within that profile

Service-level

Service class

Tasks within that service only

Action-level

Inline in CalmTask

That task only

Services

A Service class defines behavior — tasks that run at lifecycle events. It does not define the VM spec (that is the Substrate).

class AppService(Service):
    """Application service tier."""

    # Service-level variable (only accessible within this service)
    install_dir = CalmVariable.Simple("/opt/app", runtime=False)

    @action
    def __install__():
        """Runs during the 'create' lifecycle action, after VM is ready."""
        CalmTask.Exec.ssh(
            name="Install dependencies",
            script="""
set -euo pipefail
export DEBIAN_FRONTEND=noninteractive
apt-get update -q
apt-get install -y python3-pip python3-venv git
""",
            target=ref(AppService),
            cred=ref(SSHCred),
        )
        CalmTask.Exec.ssh(
            name="Clone and install app",
            script="""
set -euo pipefail
git clone @@{app_repo_url}@@ @@{install_dir}@@
cd @@{install_dir}@@
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
""",
            target=ref(AppService),
        )

    @action
    def __start__():
        """Runs on 'start' lifecycle action."""
        CalmTask.Exec.ssh(
            name="Start app service",
            script="systemctl start app.service",
            target=ref(AppService),
        )

    @action
    def __stop__():
        """Runs on 'stop' lifecycle action."""
        CalmTask.Exec.ssh(
            name="Stop app service",
            script="systemctl stop app.service || true",
            target=ref(AppService),
        )

    @action
    def deploy_update(version=""):
        """Custom Day 2 action — update to a specific version."""
        CalmTask.Exec.ssh(
            name="Pull new version",
            script="""
set -euo pipefail
cd @@{install_dir}@@
git fetch --tags
git checkout @@{version}@@
.venv/bin/pip install -r requirements.txt
systemctl restart app.service
echo "Deployed @@{version}@@"
""",
            target=ref(AppService),
        )

Built-in Action Names

These names are reserved and trigger automatically at lifecycle events:

Action Name

Trigger

__create__

After VM provisioning (via substrate)

__install__

Synonym for __create__ in package context

__delete__

Before VM deprovisioning

__start__

When application is started

__stop__

When application is stopped

__restart__

When restart is invoked

Custom action names (anything else) appear as manually-triggered Day 2 actions.

Substrates and AHV Spec YAML

Rather than embedding the full VM spec in Python code, I keep it in a YAML file per substrate and reference it with read_ahv_spec().

class AppSubstrate(Substrate):
    """AHV VM substrate for the application tier."""

    provider_type = "AHV_VM"
    provider_spec = read_ahv_spec("specs/app-vm.yaml")

    readiness_probe = {
        "connection_type": "SSH",
        "port": "22",
        "retries": "5",
        "delay_secs": "15",
        "address": "@@{address}@@",
        "credential": ref(SSHCred),
    }

The specs/app-vm.yaml file:

# specs/app-vm.yaml
name: @@{calm_application_name}@@-app-@@{calm_array_index}@@
categories: {}
resources:
  num_vcpus_per_socket: 2
  num_sockets: 1
  memory_size_mib: 4096
  power_state: ON
  nic_list:
    - nic_type: NORMAL_NIC
      subnet_reference:
        kind: subnet
        name: vlan-100-servers   # use name for portability; UUID is cluster-specific
  disk_list:
    - device_properties:
        device_type: DISK
        disk_address:
          adapter_type: SCSI
          device_index: 0
      data_source_reference:
        kind: image
        name: ubuntu-22.04-server-cloudimg   # name-based reference for portability
  guest_customization:
    cloud_init:
      user_data: |
        #cloud-config
        hostname: @@{calm_application_name}@@-app-@@{calm_array_index}@@
        users:
          - name: ubuntu
            sudo: ALL=(ALL) NOPASSWD:ALL
            ssh_authorized_keys:
              - @@{SSH_PUBLIC_KEY}@@
        packages:
          - curl
          - git
        runcmd:
          - timedatectl set-timezone Asia/Bangkok

Important: The user_data in the YAML spec can contain macros (@@{...}@@). This is evaluated at launch time, not at blueprint definition time.

Packages and Actions

A Package connects a Service to its install/uninstall actions and to the VM image reference. In most single-image scenarios, the Package class is minimal:

class AppPackage(Package):
    """Package for AppService — links to service actions."""

    services = [ref(AppService)]

    @action
    def __install__():
        CalmTask.Exec.ssh(
            name="Bootstrap",
            script="echo 'VM @@{name}@@ provisioned at @@{address}@@'",
            target=ref(AppService),
        )

    @action
    def __uninstall__():
        CalmTask.Exec.ssh(
            name="Cleanup",
            script="rm -rf /opt/app || true",
            target=ref(AppService),
        )

Profiles and Deployments

A Deployment links a Package (application) to a Substrate (VM definition) and sets replica count:

class AppDeployment(Deployment):
    packages = [ref(AppPackage)]
    substrate = ref(AppSubstrate)
    min_replicas = "1"
    max_replicas = "3"  # enables scale-out action

A Profile groups deployments and defines profile-level variables:

class DevProfile(Profile):
    """Small footprint for dev/test pipelines."""

    app_version = CalmVariable.Simple("latest", runtime=True, label="Version")

    deployments = [AppDeployment]


class ProdProfile(Profile):
    """Production sizing."""

    app_version = CalmVariable.Simple("", runtime=True, is_mandatory=True, label="Version Tag")

    deployments = [AppDeploymentProd]  # references a substrate with larger VM spec

Multiple profiles in the same blueprint share Services but can reference different Substrates, enabling different VM sizing per environment without duplicating logic.

Task Types Reference

Task Type

DSL Syntax

Use Case

SSH exec

CalmTask.Exec.ssh(script=..., target=...)

Run shell script on a Linux VM

PowerShell exec

CalmTask.Exec.powershell(script=..., target=...)

Run script on Windows VM

HTTP call

CalmTask.HTTP.post(url=..., headers=..., body=...)

Call an API endpoint

Set variable

CalmTask.SetVariable.ssh(script=..., variables=[...])

Capture script output into a variable

Delay

CalmTask.Delay(delay_seconds=30)

Wait between tasks

Execute runbook

CalmTask.RunbookTask(runbook=ref(...))

Trigger a separate Runbook

While loop

CalmTask.WhileLoopTask(...)

Retry logic with condition

Set Variable Task — Capturing Script Output

This pattern is how I pass dynamic values between tasks and between services at runtime:

@action
def __install__():
    # Capture the assigned IP into a variable for use by other services
    CalmTask.SetVariable.ssh(
        name="Capture DB address",
        script="echo @@{address}@@",
        variables=["db_host"],          # variable name to set
        target=ref(DBService),
    )
    # Now @@{DBService.db_host}@@ is available in other services

HTTP Task — Calling External APIs

CalmTask.HTTP.post(
    name="Notify deployment webhook",
    url="https://hooks.example.com/deploy",
    credential=ref(WebhookCred),
    headers={"Content-Type": "application/json"},
    body=json.dumps({
        "app": "@@{calm_application_name}@@",
        "version": "@@{app_version}@@",
        "env": "@@{environment}@@",
    }),
    expected_response_params=[{"name": "status", "value": "ok", "type": "json"}],
)

Macro Substitution Syntax

Nutanix blueprints use @@{variable_name}@@ for macro substitution. This is replaced at runtime before a task script or cloud-init config is executed.

Built-in Macros

Macro

Value

@@{calm_application_name}@@

The application name chosen at launch

@@{calm_array_index}@@

0-based index of the current VM replica (for replicated services)

@@{calm_unique_hash}@@

A short unique hash — useful in hostnames to avoid collisions

@@{calm_jwt}@@

A short-lived JWT for calling back to the NCM Self-Service API from within a task

@@{address}@@

The primary IP address allocated to the VM

@@{name}@@

The VM name (as set in substrate spec)

Cross-Service Macro Access

To access a variable that belongs to a different service, prefix with the service name:

# In app-service task, referencing db-service's address
DB_HOST="@@{DBService.address}@@"

This only works with service-level variables and the built-in address and name macros, not with profile-level variables (those are global and need no prefix).

Macro in cloud-init

Macros work in the user_data field of the substrate spec:

#cloud-config
hostname: @@{calm_application_name}@@-@@{calm_array_index}@@
write_files:
  - path: /etc/app/config.env
    content: |
      APP_VERSION=@@{app_version}@@
      DB_HOST=@@{DBService.address}@@
      ENVIRONMENT=@@{environment}@@

This means the entire application config can be injected at VM boot — no need for a separate configure task just to write a config file.

Blueprint Best Practices

These are practices I settled on after iterating through several blueprint versions in my home-lab.

1. Use Name References, Not UUID References, in Substrate Specs

Subnet and image UUIDs are cluster-specific. A blueprint that hard-codes UUIDs breaks when imported into a different cluster.

# Instead of this (UUID — cluster-specific, fragile):
subnet_reference:
  kind: subnet
  uuid: "00000000-0000-0000-0000-000000000001"

# Do this (name — portable across clusters):
subnet_reference:
  kind: subnet
  name: vlan-100-servers

The same applies to data_source_reference for images. Use name unless you have a specific reason to pin to a UUID.

2. Always Set a Readiness Probe with Retries

Without a readiness probe, the blueprint engine fires install tasks before SSH is available on the VM. This produces misleading "connection refused" errors that look like task failures.

readiness_probe = {
    "connection_type": "SSH",
    "port": "22",
    "retries": "5",       # retry 5 times before declaring failure
    "delay_secs": "15",   # wait 15 seconds between retries
    "address": "@@{address}@@",
    "credential": ref(SSHCred),
}

For Windows VMs, use "connection_type": "WinRM" and port 5985 or 5986.

3. Separate VM Spec from Blueprint Logic

Keep AHV VM specs in specs/*.yaml files and reference them with read_ahv_spec().

Benefits:

The Python DSL file focuses on behavior (tasks, variables, actions)
VM sizing is easy to diff in version control
You can have specs/app-vm-dev.yaml and specs/app-vm-prod.yaml with different CPU/memory, referenced from different Profiles

blueprints/
  my-app-blueprint.py    # DSL — all tasks, variables, actions
  specs/
    app-vm-dev.yaml      # AHV VM spec — small sizing
    app-vm-prod.yaml     # AHV VM spec — production sizing
    db-vm.yaml           # AHV VM spec — database VM
  vars/
    credentials.yml      # Ansible vault encrypted (for calm-dsl init)

4. Use Secret Variables for All Sensitive Values

Any value that should not appear in plain text in the Prism Central UI or audit logs must be declared as a Secret type variable:

# Wrong — password appears in logs
db_password = CalmVariable.Simple("changeme", runtime=True)

# Correct — masked in UI and logs
db_password = CalmVariable.Simple.Secret("", runtime=True, is_mandatory=True)

Never pass a secret value through a non-secret variable even "temporarily."

5. Write Idempotent Task Scripts

Each task script should be safe to run more than once. This matters because:

Blueprint retries will re-run failed tasks
You may trigger the same Day 2 action multiple times

# Not idempotent — fails on second run if dir exists
mkdir /opt/app && git clone ... /opt/app

# Idempotent — safe to re-run
if [[ ! -d /opt/app ]]; then
  git clone @@{app_repo_url}@@ /opt/app
else
  cd /opt/app && git pull
fi

For package installations, apt-get install -y is already idempotent. For services, use systemctl enable --now rather than start on its own.

6. Include a `delete` Action that Cleans Up

The __delete__ action on a Service runs before the VM is powered off and deleted. Use it to:

Deregister the VM from a load balancer
Remove DNS records
Revoke any service tokens

@action
def __delete__():
    CalmTask.Exec.ssh(
        name="Deregister from LB",
        script="""
set -e
curl -sf -X DELETE \
  "http://@@{lb_host}@@/api/backends/@@{address}@@" || true
echo "Deregistered @@{address}@@"
""",
        target=ref(AppService),
    )

Skipping this means stale entries accumulate in supporting systems.

7. Pin the calm-dsl Version in Your Project

calm-dsl releases can introduce breaking syntax changes. Pin the version in requirements.txt:

calm-dsl==3.9.0

And document in your README.md which Prism Central version and calm-dsl version the blueprint was tested against. A blueprint generated with calm-dsl 3.9 may not import cleanly into a PC running a much older version.

8. Version Blueprints with Git Tags

Each time you make a structural change to the blueprint (not just a script tweak), bump the version and tag it in Git:

git tag -a blueprint-v1.2.0 -m "Add db-backup Day 2 action"
git push origin blueprint-v1.2.0

In Prism Central, use the same version string when publishing to the Marketplace so it is clear which Git state corresponds to the published version.

9. Test Blueprint Actions in Isolation Before Publishing

Before publishing to the Marketplace, test each action:

Launch the blueprint manually from the Blueprint Designer ("Launch" button, not Marketplace)
With the application running, trigger each Day 2 action individually from the Application view (Actions tab)
Check the task execution log for errors — not just "success" status

The Marketplace launch does not show task-level logs easily, so debugging published blueprints is harder than debugging from the designer.

10. Avoid Hardcoding IP Addresses in Tasks

Hardcoding IP addresses in task scripts is the fastest way to create a blueprint that only works in your cluster. Use macros or dynamic variables:

# Fragile — hardcoded
MONITORING_SERVER="192.168.1.200"

# Portable — from a blueprint variable
MONITORING_SERVER="@@{monitoring_server_ip}@@"

Define monitoring_server_ip as a profile-level variable with a sensible default. Different environments can override it at launch without changing the blueprint.

Version Control Workflow with calm-dsl

My workflow for managing blueprints in Git:

my-blueprints/
  .calm/                        # calm-dsl config (gitignored — contains credentials path)
  blueprints/
    my-app/
      blueprint.py              # DSL blueprint definition
      specs/
        app-vm.yaml
        db-vm.yaml
      tests/
        test_launch.sh          # smoke test: launch, ping, delete
  requirements.txt              # pinned calm-dsl version
  Makefile

Makefile targets:

.PHONY: validate push launch delete

validate:
	python blueprint.py  # Python parse check

push:
	calm create bp \
	  --file blueprints/my-app/blueprint.py \
	  --name "my-app-blueprint" \
	  --force  # update if exists

launch:
	calm launch bp "my-app-blueprint" \
	  --app_name "my-app-test-$(shell date +%s)" \
	  --profile DefaultProfile

delete:
	calm delete app "$(APP_NAME)"

Blueprint Linting and Validation

calm-dsl does not have a dedicated lint command, but I use two checks before pushing:

1. Python Parse Check

python blueprints/my-app/blueprint.py

If the DSL class hierarchy has errors (missing references, wrong types), this raises a Python exception immediately without needing a PC connection.

2. Dry-Run JSON Dump

calm compile bp --file blueprints/my-app/blueprint.py --out json | python -m json.tool > /dev/null

calm compile generates the JSON that would be sent to Prism Central. Pipe it through json.tool to catch any malformed output. Redirect to /dev/null since the goal is just the exit code.

3. GitLab CI Validation Job

In the project's .gitlab-ci.yml, I run both checks automatically:

validate-blueprint:
  stage: lint
  image: python:3.12-slim
  before_script:
    - pip install calm-dsl==3.9.0 --quiet
    - calm init dsl --pc_ip "$PC_HOST" --pc_port 9440 --pc_username "$PC_USERNAME" --pc_password "$PC_PASSWORD"
  script:
    - python blueprints/my-app/blueprint.py
    - calm compile bp --file blueprints/my-app/blueprint.py --out json | python -m json.tool > /dev/null
    - echo "Blueprint validates cleanly"
  rules:
    - changes:
        - blueprints/my-app/**

This catches syntax errors on every merge request before anything reaches Prism Central.

Next Steps

Now that the blueprint syntax and best practices are clear, see how blueprints integrate into automated pipelines: GitLab CI/CD Integration with Nutanix Blueprint.

Go back to the Nutanix 101 series index.

PreviousNutanix Blueprint – Self-Service Application Blueprints NextWriting a Blueprint for Windows VM Automation

Last updated 11 hours ago

hashtagTable of Contents

hashtagWhy a Dedicated Syntax Article

hashtagBlueprint JSON/YAML Structure

hashtagTop-Level Keys

hashtagapp_profile_list Items

hashtagservice_definition_list Items

hashtagsubstrate_definition_list Items (AHV)

hashtagThe calm-dsl Python DSL Syntax Reference

hashtagBlueprint Skeleton

hashtagCredentials

hashtagVariables

hashtagVariable Scoping Rules

hashtagServices

hashtagBuilt-in Action Names

hashtagSubstrates and AHV Spec YAML

hashtagPackages and Actions

hashtagProfiles and Deployments

hashtagTask Types Reference

hashtagSet Variable Task — Capturing Script Output

hashtagHTTP Task — Calling External APIs

hashtagMacro Substitution Syntax

hashtagBuilt-in Macros

hashtagCross-Service Macro Access

hashtagMacro in cloud-init

hashtagBlueprint Best Practices

hashtag1. Use Name References, Not UUID References, in Substrate Specs

hashtag2. Always Set a Readiness Probe with Retries

hashtag3. Separate VM Spec from Blueprint Logic

hashtag4. Use Secret Variables for All Sensitive Values

hashtag5. Write Idempotent Task Scripts

hashtag6. Include a __delete__ Action that Cleans Up

hashtag7. Pin the calm-dsl Version in Your Project

hashtag8. Version Blueprints with Git Tags

hashtag9. Test Blueprint Actions in Isolation Before Publishing

hashtag10. Avoid Hardcoding IP Addresses in Tasks

hashtagVersion Control Workflow with calm-dsl

hashtagBlueprint Linting and Validation

hashtag1. Python Parse Check

hashtag2. Dry-Run JSON Dump

hashtag3. GitLab CI Validation Job

hashtagNext Steps

Table of Contents