Blueprints

Overview¶

A blueprint is a declarative template that is used to define and automate the deployment of infrastructure, applications, and services with the option to expose the functionality to entitled users via the VCF Automation Catalog.

Project Structure¶

Build Tools for VMware Aria stores blueprint objects in several files in a directory with the blueprint name under the src/main/resources/blueprints directory in the project content on the local filesystem.

Following is a sample listing of the local filesystem for a blueprint with the name Example Blueprint.

Local Project Content

src/
└── main/
    └── resources/
        └── blueprints/
            └── Example Blueprint/
                ├─ content.yaml
                ├─ details.json
                ├─ Example Blueprint__FormData.json
                └─ styles.css

Following is a list of the files for each blueprint object with a short description of their content and purpose.

The content.yaml file contains the exported blueprint code (in YAML format).
The details.json file contains the metadata information for the blueprint.
The <blueprint name>__FormData.json¹ file is optional and contains the custom form definition for the blueprint, if available.
The style.css file is optional and contains the CSS for the custom form of the blueprint, if available.

Sample Project File Content¶

This section contains sample listings of the content of the files for each blueprint object as they are stored in the src/main/resources/blueprints/<blueprint name>/² directory in the project content on the local filesystem.

Following is a sample listing of the content of the content.yaml file for the Small VM blueprint (as defined in the project archetype).

src/main/resources/blueprints/Small VM/content.yaml

formatVersion: 1
inputs:
  vmName:
    type: string
    title: VM name
  vmSize:
    type: string
    title: VM size
    oneOf:
      - title: Small
        const: best-effort-small
      - title: Meduim
        const: best-effort-medium
      - title: Large
        const: best-effort-large
  emailList:
    type: array
    title: Notification email(s)
    items:
      type: string
resources:
  CCI_Supervisor_Namespace_1:
    type: CCI.Supervisor.Namespace
    metadata:
      layoutPosition:
        - 0
        - 0
    properties:
      name: vcf-ns-demo
      existing: true
  Virtual_Machine_1:
    type: CCI.Supervisor.Resource
    metadata:
      layoutPosition:
        - 0
        - 0
    properties:
      context: ${resource.CCI_Supervisor_Namespace_1.id}
      manifest:
        apiVersion: vmoperator.vmware.com/v1alpha3
        kind: VirtualMachine
        metadata:
          name: ${input.vmName}-${env.shortDeploymentId}
        spec:
          className: ${input.vmSize}
          imageName: vmi-0a0044d7c690bcbea
          powerState: PoweredOn
          storageClass: vsan-default-storage-policy
      wait:
        conditions:
          - type: VirtualMachineCreated
            status: 'True'

Following is a sample listing of the content of the details.json file for the Small VM blueprint (as defined in the project archetype).

src/main/resources/blueprints/Small VM/details.json

{
  "id": "ebfa16aa-05c4-428b-871e-b01d2ab99733",
  "name": "Small VM",
  "description": "",
  "requestScopeOrg": true
}

Following is a sample listing of the content of the Small VM__FormData.json file (custom form) for the Small VM blueprint (as defined in the project archetype).

src/main/resources/blueprints/Small VM/Small VM__FormData.json

{
  "layout": {
    "pages": [
      {
        "id": "page_general",
        "title": "General",
        "sections": [
          {
            "id": "section_cf56a1ce",
            "fields": [
              {
                "id": "vmName",
                "display": "textField",
                "state": {
                  "visible": true,
                  "read-only": false
                },
                "signpostPosition": "right-middle"
              }
            ]
          },
          {
            "id": "section_140994b3",
            "fields": [
              {
                "id": "vmSize",
                "display": "dropDown",
                "state": {
                  "visible": true,
                  "read-only": false
                },
                "signpostPosition": "right-middle"
              }
            ]
          },
          {
            "id": "section_09613334",
            "fields": [
              {
                "id": "emailList",
                "display": "array",
                "state": {
                  "visible": true,
                  "read-only": false
                },
                "signpostPosition": "right-middle"
              }
            ]
          }
        ],
        "state": {}
      }
    ]
  },
  "schema": {
    "vmName": {
      "label": "VM name",
      "type": {
        "dataType": "string",
        "isMultiple": false
      },
      "placeholder": "",
      "constraints": {
        "required": true
      }
    },
    "vmSize": {
      "label": "VM size",
      "type": {
        "dataType": "string",
        "isMultiple": false
      },
      "valueList": [
        {
          "value": "best-effort-small",
          "label": "Small"
        },
        {
          "value": "best-effort-medium",
          "label": "Meduim"
        },
        {
          "value": "best-effort-large",
          "label": "Large"
        }
      ],
      "placeholder": "",
      "constraints": {
        "required": true
      }
    },
    "emailList": {
      "label": "Notification email(s)",
      "type": {
        "dataType": "string",
        "isMultiple": true
      },
      "constraints": {}
    }
  },
  "options": {
    "externalValidations": [
      {
        "label": "ValidateEmails",
        "source": {
          "id": "com.vmware.library.mail/validateEmailAddressList",
          "type": "scriptAction",
          "parameters": [
            {
              "$type": {
                "dataType": "string",
                "isMultiple": true
              },
              "list": "emailList"
            }
          ]
        },
        "target": [
          "emailList"
        ]
      }
    ]
  }
}

Export¶

To export a blueprint from the VCF Automation server (pull the content), you need to add the blueprint name as a list item of the blueprint element in the content.yaml content descriptor file for the project.

Tip

Alternatively, if you want to export all blueprint objects from the project on the VCF Automation server, you can configure the blueprint element with no value (i.e. its value is null). For details, see the Content Filtering section.

Following is a sample listing of the content.yaml file for a project that exports only the Example Blueprint blueprint from the project on the VCF Automation server.

content.yaml

blueprint:
  - Example Blueprint
# ...

Import¶

When you import a blueprint to a project on a VCF Automation server (push operation), Build Tools for VMware Aria matches the blueprint object by its name (the name of the directory under src/main/resources/blueprints in the project content on your local filesystem) and performs one of the following operations.

Warning

Note that for push operations for VCF Automation projects for All Apps organizations, Build Tools for VMware Aria uses the content filtering rules that you define in the content.yaml content descriptor file. For details, see the Content Filtering section.

If a blueprint with the same name does not exist on the server, Build Tools for VMware Aria creates a new blueprint with the details from the local project files.
If a blueprint with the same name already exists on the server, Build Tools for VMware Aria checks if there are any differences between the local copy and the server copy and performs one of the following operations.
- If there are no differences between the local copy and the server copy, BTVA skips the operation and does not update the blueprint on the server.
- If there are differences between the local copy and the server copy, BTVA updates the content on the server and releases a new version of the blueprint. For details about the versioning that BTVA uses, see Version Management.

Version Management¶

When you push a blueprint to a VCFA server that contains a previously-released version of a blueprint with the same name, Build Tools for VMware Aria creates and releases a new version of the blueprint to maintain the intended state. Note, however, that if the content of the blueprint has not been modified since the latest released version, BTVA does not create a new version to avoid unnecessary versioning.

If there is a custom form associated with the blueprint that you are importing and there is no previously-released version, Build Tools for VMware Aria creates and releases an initial blueprint version (1) in order to import the custom form.

When creating a new version of the blueprint, BTVA auto-generates the new version based on the latest existing version of the blueprint and tries to continue the numbering. If it fails to detect a version that is based on semantic versioning (MAJOR.MINOR.PATCH), BTVA releases a date-formatted version.

The following table lists the supported version formats that BTVA detects with their respective incrementing rules.

Latest version	New version	Incrementing rules
1	2	Major version detected - increment the major version.
1.0	1.1	Major and minor version detected - increment the minor version.
1.0.0	1.0.1	Major, minor, and patch version detected - increment the patch version.
1.0.0-alpha	2026-07-27-14-36-42	Arbitrary version detected - generate a new version based on date-time.

Handling of Previously-Released Blueprint Versions¶

By default, BTVA unreleases all released versions of the blueprint that are not the latest one.

To control this behavior, you can use the vcfa.bp.unrelease.versions property of the Maven profile configuration in the settings.xml file.

<vcfa.bp.unrelease.versions>false</vcfa.bp.unrelease.versions>

Warning

Version history gets lost. This is known behavior and currently there is no workaround for it.

The <blueprint name> placeholder stands for the name of the blueprint that matches the name of the parent directory. ↩
The <blueprint name> placeholder stands for the name of the blueprint that determines the name of the directory. ↩