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.

Following is a sample listing of the project content in the src directory for that blueprint.

Local Project Content

src/
└── main/
    └── resources/
        └── blueprints/
            └── Example Blueprint/
                ├── content.yaml
                ├── details.json
                └── versions.json

Each blueprint is placed in a separate directory and the data is split in the following files.

• The content.yaml file contains the exported blueprint code (in YAML format).
• The details.json file contains the metadata information for the blueprint.
• The versions.json file contains the version information. Note that this is just the metadata and for now the version history is not preserved.

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: {}
resources:
  Cloud_Machine_1:
    type: Cloud.Machine
    metadata:
      layoutPosition:
        - 0
        - 0
    properties:
      image: smallVM
      flavor: medium
      networks:
        - network: ${resource.Cloud_Network_1.id}
  Cloud_Network_1:
    type: Cloud.Network
    metadata:
      layoutPosition:
        - 1
        - 0
    properties:
      networkType: existing

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": "d47d5b96-97b7-4002-9549-99bb9a45ad69",
  "name": "Small VM",
  "description": "",
  "requestScopeOrg": false
}

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.

blueprint:
  - Example Blueprint
# ...

Importing

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.

• 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 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 vrang.bp.unrelease.versions property of the Maven profile configuration in the settings.xml file.

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

Warning

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

---

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