VM Apps Organization Project

Overview¶

Field	Value
Name	vra-ng
Archetype Group ID	com.vmware.pscoe.vra-ng.archetypes
Archetype Artifact ID	package-vra-ng-archetype
Package extension	vrang
Product compatibility	VCF Automation VM Apps Organization (9.x) Aria Automation (8.x)

VCF Automation projects (for VM Apps organizations and in Aria Automation) are called vra-ng (New Generation) projects in Build Tools for VMware Aria. The project type is a representation of VCFA content in human-friendly YAML and/or JSON format. The project consist of a content descriptor and a content container.

The Content Descriptor defines what part of VCFA content is part of the project in the content.yaml file.
The Content Container holds the actual content representation in the ./src directory.

Supported Content¶

Following is a list of the supported content for VCF Automation VM Apps organization (and Aria Automation) projects.

Content Type	Attribute key in Content Descriptor	Comment
Cloud Templates (Blueprints)	`blueprint`	See Blueprint page.
Content (Catalog) Items	`catalog-item`	See Catalog Items page.
Content Sources	`content-source`	N/A
Custom Resources	`custom-resource`	See Custom Resources page.
Entitlements (Catalog)	`catalog-entitlement`	Starting with version 8.8 of Aria Automation, catalog entitlements are replaced by content sharing policies.
Policies	`policy`	See Policies page.
Property Groups	`property-group`	N/A
Resource Actions	`resource-action`	N/A
Notification Scenarios	`scenario`	N/A
(Event) Subscriptions	`subscription`	N/A

Create New VCFA Project for VM Apps Organizations¶

Build Tools for VMware Aria provides ready-to-use VCFA project templates (maven archetypes) for VM Apps organizations (and Aria Automation).

To create a new VCFA project for VM Apps from the archetype, use the following command.

Linux / MacOS (Unix)Windows (PowerShell)Windows (CMD)

mvn archetype:generate \
  -DinteractiveMode=false \
  -DarchetypeGroupId=com.vmware.pscoe.vra-ng.archetypes \
  -DarchetypeArtifactId=package-vra-ng-archetype \
  -DarchetypeVersion=4.24.1 \
  -DgroupId=com.company.department \
  -DartifactId=vrang-project

mvn archetype:generate `
  -DinteractiveMode=false `
  -DarchetypeGroupId=com.vmware.pscoe.vra-ng.archetypes `
  -DarchetypeArtifactId=package-vra-ng-archetype `
  -DarchetypeVersion=4.24.1 `
  -DgroupId=com.company.department `
  -DartifactId=vrang-project

mvn archetype:generate ^
  -DinteractiveMode=false ^
  -DarchetypeGroupId=com.vmware.pscoe.vra-ng.archetypes ^
  -DarchetypeArtifactId=package-vra-ng-archetype ^
  -DarchetypeVersion=4.24.1 ^
  -DgroupId=com.company.department ^
  -DartifactId=vrang-project

Expand for Description of Defined Properties for the Command

Following is a list of the properties that you define in the command for generating a project from the archetype with details about their expected and default values.

The interactiveMode flag specifies whether you want to run the command in interactive mode.
The archetypeGroupId property defines the group ID of the archetype (project template) that you want to use for the project. For Aria Automation/VCF Automation VM Apps projects, make sure to set the value to com.vmware.pscoe.vra-ng.archetypes.
The archetypeArtifactId property defines the artifact ID of the archetype (project template) that you want to use for the project. For Aria Automation/VCF Automation VM Apps projects, make sure to set the value to package-vra-ng-archetype.
The archetypeVersion property is optional and defines the version of the archetype (project template) that you want to use for the project. This version matches the version of Build Tools for VMware Aria.

Note

Note that if you do not specify a value for the archetypeVersion property, the command uses the default value of 2.38.1. However, since the archetype content changes, you are advised to use an up-to-date version.
The groupId property defines the distinct identifier of the group to which your project belongs. You should use this property to define the base name of the company or the group that creates the project. It acts as a namespace that ensures that project names don't clash with each other. It is recommended to choose a groupId that reflects your organization or main project.
The artifactId property defines the unique identifier for your project or module (within the company or project group). It represents the name of the artifact that is generated by the project. It is recommended to use an artifactId value that reflects the specific project (and project type in multi-module projects).

Content Structure¶

The command for creating a project produces the following project file structure.

vrang-project
├── README.md
├── content.yaml
├── pom.xml
├── release.sh
└── src
    └── main
        └── resources
            └── blueprints
                └── Example Blueprint/
                    └── blueprint.yaml
                    └── content.yaml
                    └── versions.yaml
            └── content-sources
                └── source.json
            └── property-group
                └── property_group_name.json
            └── catalog-items
                └── forms
                    └── content source name__workflow one name with custom form.json
                    └── content source name__workflow one name with custom form__FormData.json
                    └── content source name__workflow three name with custom icon and form.json
                    └── content source name__workflow three name with custom icon and form__FormData.json
                └── icons
                    └── content source name__workflow two name with custom icon.png
                    └── content source name__workflow three name with custom icon and form.png
                └── content source name__workflow one name with custom form.json
                └── content source name__workflow two name with custom icon.json
                └── content source name__workflow three name with custom icon and form.json
            └── entitlements
                └── Blueprint.yaml
                └── Workflow.yaml
                └── ABX Action.yaml
            └── subscriptions
                └── subscription.json
            └── custom-resources
                └── customResource.json
            └── resource-actions
                └── resourceAction.json
            └── policy
                └── approval
                    └── approvalPolicy1.json
                └── content-sharing
                    └── contentSharingPolicy1.json
                └── day2-actions
                    └── day2ActionsPolicy1.json
                └── deployment-limit
                    └── deploymentLimitPolicy1.json
                └── lease
                    └── leasePolicy1.json
                └── resource-quota
                    └── resourceQuotaPolicy1.json
            └── scenarios
                └── Scenario Name.json

Project Content¶

The following sections give details about the project content management.

Content Descriptor¶

The Content Descriptor is implemented by a content.yaml file with the following structure.

blueprint:
subscription:
custom-resource:
resource-action:
catalog-entitlement:
catalog-item:
content-source:
property-group:
scenario:
policy:
  approval:
  content-sharing:
  day2-actions:
  deployment-limit:
  lease:
  resource-quota:

Note

VCFA Project for VM Apps and Aria Automation supports only the content types outlined into Content Descriptor.

To capture the state of your VCFA environment, fill in the names of the content objects and use the commands described in the Pull Content section.

For more information on each component, see the corresponding sub-section page.

Content Filtering¶

The rules for project contents management depend on the operation.

Import Rules for Content Types¶

For import operations (pushing content), all local objects that are available in the ./src directory of the project are imported and the content descriptor from the content.yaml file is not taken into consideration.

Export Rules for Content Types¶

For export operations (pulling content), remote objects are exported based on the following rules for each category in the content descriptor.

Empty array ([]) - nothing from the object type is exported.
List of items - only the listed items from the object type are exported. If an object is not present on the server, an exception is thrown.
Null (no value) - everything from the object type is exported.

Export Rule Example¶

Following is a sample listing of a content descriptor for a project with examples of how the filtering rules apply for each category type.

Content Descriptor

blueprint:                # exports all blueprint/cloud template objects
subscription:             # exports all EBS subscription objects
catalog-item:             # exports catalog item objects listed in the filter
  # note that the notation is <content source name>__<catalog item name>
  - Project Blueprints__WindowsVM
  - Project Blueprints__LinuxVm
  - Main Workflows__ConfigureVM
custom-resource:          # exports all custom resource objects
resource-action:          # exports all resource action objects
property-group:           # exports property group objects listed in the filter
  - memory
catalog-entitlement: []   # does not export entitlement objects
content-source:           # exports content source objects listed in the filter
  - Project Blueprints
  - Main Workflows
  - Utility Workflows
  - Project Abx Actions
  - Project Code Stream pipelines
policy:                   # export policy objects listed in the filter per type
  approval: []            # does not export approval policy objects
  content-sharing:        # exports content sharing policy objects listed in the filter
    - cs policy 1
    - cs policy 2
  day2-actions: []        # does not export day-2 action policy objects
  deployment-limit: []    # does not export deployment limit policy objects
  lease: []               # does not export lease policy objects
  resource-quota: []      # does not export resource quota policy objects
scenario: []              # does not export scenario objects

Note

Unreleased blueprints that have a custom form are automatically released with version 1.

Note

To export custom forms and/or icons, you need to specify the associated catalog item name in the catalog-item element. The naming convention for this is <content source name>__<catalog item name>.

The integration endpoint data for each Orchestrator workflow that is associated with the content source is also updated with the one fetched from the VCFA server.

ID handling¶

You should not rely on IDs exported by Build Tools for VMware Aria. Where needed, Build Tools for VMware Aria removes such IDs or in some cases, it fetches data from the remote server, modifies it in flight, and pushes it to the server (in cases where an import is needed).

Single Project And Single Organization¶

When you are working with the vra-ng project type, each project that you generate is intended to work with a single project and a single organization only. In case you need to work with more that one project or organization, you need to generate a separate Maven project for each of them.

For every object type that contains the organization or the projectId key in the JSON definition (such as VCFA policies), the following behavior applies.

If the JSON definition contains the projectId key with a value, the value is replaced by the project defined in one of the following sources (based on import mechanism that you use).
- The <vrang.project.name> attribute from the settings.xml Maven profile that you are using.
- The vrang_project_name property that you provide to the installer script.
If the JSON definition contains the organization key with a value, the object is imported with the scope option Available for any project or Organization (the exact option name differs in the user interface based on product version) that you defined in one of the following sources (based on import mechanism that you use).
- The <vrang.org.name> attribute from the settings.xml Maven profile that you are using.
- The vrang_org_name property that you provide to the installer script.

Environment Connection Parameters¶

You need to add the following configurations to the Maven profile from the settings.xml file that you intend to use for a project.

<!-- (1)! -->
<profile>
    <!--    ..... OTHER DIRECTIVES .....  -->
    <vrang.host>flt-auto01.corp.internal</vrang.host>
    <vrang.csp.host>cloud.corp.internal</vrang.csp.host>
    <vrang.proxy>http://proxy.host:80</vrang.proxy>
    <vrang.port>443</vrang.port>
    <vrang.username>administrator</vrang.username>
    <vrang.password>someSecurePassword</vrang.password>
    <vrang.tenant>{tenant}</vrang.tenant>
    <vrang.project.name>{project+name}</vrang.project.name>
    <vrang.org.name>{org+name}</vrang.org.name>
    <vrang.refresh.token>{refresh+token}</vrang.refresh.token>
    <vrang.bp.unrelease.versions>true|false</vrang.bp.unrelease.versions>
    <vrang.vro.integration>{vro+integration+name}</vrang.vro.integration>
    <vrang.import.timeout>{import+timeout}</vrang.import.timeout>
    <vrang.data.collection.delay.seconds>{data+collection+delay}</vrang.data.collection.delay.seconds>
</profile>

The location of the settings.xml file for MacOS is ~/.m2 and C:\Users\username\\.m2 for Windows.

To specify the Maven profile that you want to use for an operation, pass its name with the -P option as shown in the following example.

mvn vra-ng:pull -Ptarget-env

Following is a list of elements from the profile configuration with further description of their values and the behavior they cause.

In the vrang.username element for VCF Automation VM Apps organizations, instead of using the <vrang.tenant> element for the organization, you can provide the user name in the format user@domain (or more precisely, user@organization). For example, use admin@System for the admin user from the Provider organization (the System domain identifies the Provider organization) or use configurationadmin@Classic for a configurationadmin user from an organization with the name Classic.
In the vrang.refresh.token element, provide a refresh token that you want to use instead of user credentials for authentication.

Note

Refresh token takes precedence over credentials.
In the vrang.bp.unrelease.versions optional element, specify whether old versions of a blueprint should be unreleased. The default value is true.
In the vrang.import.timeout optional element, specify the timeout in milliseconds for syncing Catalog Item objects before performing additional operations (such as attaching Custom Forms, Icons, etc.). The default value is 6000.
In the vrang.data.collection.delay.seconds optional element, specify the delay in seconds for waiting for the data collection from the Orchestrator instance to VCFA before importing data. You can also pass this configuration as an interactive parameter with the -D option as -Dvrang.data.collection.delay.seconds=600.

Use this configuration when the VCFA project contains references to Orchestrator workflows and dynamic types that you are importing together with the VCFA content for the project since VCF Automation needs to retrieve the details of the Orchestrator content first before it can create the VCFA objects that point to the Orchestrator content. The default value is 0 or no delay.

Note

Note that if you provide a delay value, Build Tools for VMware Aria forces data collection via REST API and if it completes successfully, the delay is skipped and the provided delay time is disregarded. In case the data collection fails, however, the delay time is used and a wait timer is triggered.
In the vrang.org.name element, you always need to specify the organization name. The vra-ng project is scoped to a single organization.

Operations¶

This section describes the operations that you can perform with the VCF Automation project for a VM Apps organization.

Build the Project¶

This section describes the operation for building the project.

Overview¶

A Maven goal for compiling the code into a deployment-ready package.

Usage¶

To build the project, use the following command.

mvn clean package

The result of the command is a file with the name com.company.department.project.type-1.0.0-SNAPSHOT.vra-ng that is generated in the target directory of the project.

Pull Content¶

This section describes the pulling of content for the project.

Overview¶

When working with a VCF Automation project for a VM Apps organization, you mainly make content changes on a live server using the VCFA user interface and then you capture those changes in the Maven project on your filesystem so that you can store the content, track changes, collaborate, etc.

Usage¶

To pull content from a remote server, use the vra-ng:pull custom Maven goal. The following command pulls the content defined in the Content Descriptor file to the current project from a specified server and expands its content in the local filesystem by overriding any local content.

mvn vra-ng:pull -Ptarget-env

Warning

The command fails if the content.yaml content descriptor file is empty or if Build Tools for VMware Aria cannot find any of the described content on the target VCFA server.

Note

If a catalog item has a custom form and/or an icon, they are exported in subdirectories of the catalog-items directory of the project.

Note

Use the value of the <vrang.vro.integration> element in the Maven profile to specify the integration endpoint that you want to use for Orchestrator resources in the project (such as workflows exposed as catalog items). If the property is missing, Build Tools for VMware Aria uses the default name embedded-VRO.

Additional Parameters¶

In the Maven command, you can pass additional parameters as flags with the -D option to override profile properties, such as mvn vra-ng:pull -Ptarget-env -Dbp.ignore.versions=true, where the value of the bp.ignore.versions parameter ignores blueprint versioning (for details, see the Version Management section in Blueprints). This option defaults to false but when dealing with blueprint development, you can set this option to true to avoid unnecessary blueprint versions.

Push Content¶

This section describes the operation for pushing project content to the target environment.

Overview¶

A Maven goal for packaging and deploying all local content from ./src directory to the remote server.

Usage¶

To push the project content to the target environment (defined in the Maven build profile that you specify in the -P${PROFILE} argument), use the following command.

mvn clean package vra-ng:push -Ptarget-env

Include Dependencies¶

By default, the vra-ng:push goal deploys all dependencies of the current project to the target environment. You can control this behavior by adding the -DincludeDependencies flag with the value false (to overwrite the default value true).

To skip deploying the project dependencies, run the following command.

mvn package vra-ng:push -Ptarget-env -DincludeDependencies=false

Ignore Certificates¶

This section describes the flags that allow you to bypass the security feature for verifying the certificate and certificate hostname of the remote server in a development/testing environment.

Warning

Do not use the flags described in this section when targeting production servers.

Instead, make sure that the certificates have the correct CN, use FQDN to access the servers, and add the certificates to the Java key store (i.e. cacerts).

Use the Maven ProfileDirectly Pass The Parameters

You can ignore certificate errors for all operations by adding the following parameters to the target profile in your Maven settings.xml file.

For the the certificate is not trusted error, use the vrealize.ssl.ignore.certificate parameter.
For the the CN does not match the actual hostname error, use the vrealize.ssl.ignore.hostname parameter.

<!-- Parameters for ignoring certificates in settings.xml file --> <!-- # (1)! -->
...
<profiles>
  ...
  <profile>
      <id>target-env</id>
      <properties>
          ...
          <vrealize.ssl.ignore.hostname>true</vrealize.ssl.ignore.hostname>
          <vrealize.ssl.ignore.certificate>true</vrealize.ssl.ignore.certificate>
      </properties>
  </profile>
</profiles>

The location of the settings.xml file for MacOS is ~/.m2 and C:\Users\username\\.m2 for Windows.

You can ignore certificate errors for specific operations by adding the following flags to your command.

To ignore the the certificate is not trusted error, add the -Dvrealize.ssl.ignore.certificate flag to your command.
```
mvn package vra-ng:push -Ptarget-env -Dvrealize.ssl.ignore.certificate
```
To ignore the the CN does not match the actual hostname error, add the flag -Dvrealize.ssl.ignore.certificate:
```
mvn package vra-ng:push -Ptarget-env -Dvrealize.ssl.ignore.hostname
```

Additional Parameters¶

In the Maven command, you can pass additional parameters as flags with the -D option, such as mvn clean package -Ptarget-env -Dvrang.bp.release=false, where the Dvrang.bp.release parameter creates a new version of an already-released blueprint (see the Version Management section in Blueprints). This option defaults to true but when dealing with blueprint development, you can set this option to false to avoid unnecessary blueprint versions.

Note

If there are custom forms in the custom-forms directory that are associated with workflows and catalog items, they are imported to the VCFA server as well along with the content sources that are associated with them (they are read from the content-sources directory).

Bundle the Project¶

This section describes the operation for bundling the project.

Overview¶

A Maven goal for producing an installation bundle that contains the solution package, all its dependencies, and scripts for deploying them to a target environment.

Usage¶

To bundle the project, use the following command.

mvn clean package -Pbundle-with-installer

For more information about using the bundle, see the documentation of the Installer CLI tool.

Release¶

To release specific content that is available on a live server, you can use the vrealize:release command as shown in the following example.

mvn clean package vrealize:release -Ptarget-env -Dvrang.contentType=blueprint -Dvrang.contentNames=testBlueprint -Dvrang.version=1 -DreleaseIfNotUpdated=false

Note that the only required parameter in this command is vrang.version. The following list explains the default behavior for other parameters from the command.

The vrang.contentType parameter defaults to the value all that releases all supported content types.
The vrang.contentNames parameter defaults to the value [] that releases all content of the given types on the server.
The vrang.releaseIfNotUpdated parameter defaults to the value false that skips content if there are no updates since latest version.

Note

Nothing will be released if any of the content on the server already has a release with the version that you specify in the vrang.version parameter.

Clean Up Content¶

This section describes the operation for cleaning up project content from a target environment.

Note

Note that the supported functionality for the cleaning up of project content from a target environment depends on the project type. For details, see the Project Type Support for Content Clean Up.

Overview¶

A dedicated goal for cleaning up project packages from a given environment (server).

Usage¶

To clean up content from the target environment (defined in the Maven build profile that you specify in the -P${PROFILE} argument), use the following command.

mvn vra-ng:clean -DincludeDependencies=true -DcleanUpOldVersions=true -DcleanUpLastVersion=false -Ddryrun=true -Ptarget-env

Following is a list of the properties that you define via the -D command line arguments in the command with short description of their values.

The includeDependencies flag specifies whether the package dependencies should be deleted together with the project package.
The cleanUpOldVersions flag specifies whether old versions of the package should be deleted. When combined with the includeDependencies flag, the operation is extended to the dependencies of the project package as well.
The cleanUpLastVersion flag specifies whether the latest version of the project package should be deleted before importing.
The dryrun flag specifies whether the operation should be run in dry run mode.

Note

Note that the Aria Automation/VCF Automation VM Apps project does not support running the clean up operation in dry run mode. For details, see the Project Type Support for Content Clean Up.

Examples¶

Following is a list of usage examples for cleaning up content from an environment.

To clean up only the current project package version from the server and keep the older package versions and dependencies, use the command with the following argument values.
```
mvn vra-ng:clean -DcleanUpLastVersion=true -DcleanUpOldVersions=false -DincludeDependencies=false -Ptarget-env
```
To clean up the current project package version and its dependencies from the server but keep the older package versions, use the command with the following argument values. Note that this is a force removal operation.
```
mvn vra-ng:clean -DcleanUpLastVersion=true -DcleanUpOldVersions=false -DincludeDependencies=true -Ptarget-env
```
To clean up the old project package versions and the old versions of package dependencies but keep the current (latest) package version, use the command with the following argument values.
```
mvn vra-ng:clean -DcleanUpLastVersion=false -DcleanUpOldVersions=true -DincludeDependencies=true -Ptarget-env
```

Project Type Support for Content Clean Up¶

The following table provides details about the support of the cleaning up of project content via the vra-ng:clean command per project type (archetype).

Archetype	Supported	Comment
vro	Yes	-
vcd	Partial	Does not support dry run mode.
abx	No	Not implemented.
vrops	No	Not implemented.
vra-ng	Partial	Does not support dry run mode.
vrli	No	Product does not provide native package support.
cs	No	Product (Code Stream Services) does not provide native package support.
vcfa-all-apps	Partial	Does not support dry run mode.

Operation Troubleshooting¶

Following is a list of tips on how to resolve issues that you might face when performing any of the supported operations.

If a Maven error does not contain enough information, re-run the command with the -X debug flag.
```
mvn -X <rest of the command>
```
Sometimes Maven might cache old artifacts. To force the fetching of new artifacts, run the command with the -U flag. Alternatively, remove < home >/.m2/repository directory.
```
mvn -U <rest of the command>
```