VM Apps / Classic Tenant 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 / Classic Tenant (9.x) Aria Automation (8.x)

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

Content Descriptor defines what part VCFA content will be part of this project - content.yaml.
Content Container holds the actual content representation - ./src folder.

Supported Content¶

blueprint
content-sources
property-group
catalog-item
catalog-entitlement
subscription
custom-resource
resource-actions
policies
scenarios

Create New VCFA Project¶

Build Tools for VMware Aria provides ready to use VCFA project templates (maven archetypes).

To create a new VCFA project from archetype use the following command:

mvn archetype:generate \
    -DinteractiveMode=false \
    -DarchetypeGroupId=com.vmware.pscoe.vra-ng.archetypes \
    -DarchetypeArtifactId=package-vra-ng-archetype \
    -DarchetypeVersion= # (1)! \
    -DgroupId=com.company.bu # (2)! \
    -DartifactId=project.type # (3)!

This parameter is optional. Default value is 2.38.1. Note that archetype contents change so usually an up-to-date version is preferred.
The groupId in Maven is a distinctive identifier specifically used for a project. It acts as a namespace, ensuring that project names don't clash with each other. It is recommended to choose a groupId that reflects your organization or project.
The artifactId is a unique identifier for a specific project or module within a project. It represents the name of the artifact that is generated by the project. It is recommended to choose a artifactId that reflects the project type.

Note

If is not specified a default value of 2.38.1 will be used.

Content Structure¶

The result of this command will produce the following project file structure:

catalog
├── README.md
├── content.yaml
├── pom.xml
├── release.sh
└── src
    └── main
        └── blueprints
            └── blueprint.yaml
            └── content.yaml
            └── versions.yaml
        └── content-sources
            └── source.json
        └── property-group
            └── property_group_name.json
        └── catalog-items
            └── forms
                └── source name__workflow one name with custom form.json
                └── source name__workflow one name with custom form__FormData.json
                └── source name__workflow three name with custom icon and form.json
                └── source name__workflow three name with custom icon and form__FormData.json
            └── icons
                └── source name__workflow two name with custom icon.png
                └── source name__workflow three name with custom icon and form.png
            └── source name__workflow one name with custom form.json
            └── source name__workflow two name with custom icon.json
            └── 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
                └── aprovalPolicy1.json
            └── content-sharing
                └── contentSharingPolicy1.json
            └── day2-actions
                └── day2ActionsPolicy1.json
            └── deployment-limit
                └── deploymentLimitPolicy1.json
            └── lease
                └── leasePolicy1.json 
            └── resource-quota
                └── resourceQuotaPolicy1.json 
        └── scenarios
            └── Scenario Name.json

Content¶

Content Descriptor¶

Content Descriptor is implemented by 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 supports only content types outlined into Content Descriptor.

To capture the state of your VCFA environment simply fill in the names of the content objects and follow the Pull Content section.

For more information on each component please refer to corresponding sub-section.

Content Filtering¶

Contents are managed by different rules.

Import Rules for content types¶

All local objects available in ./src folder are imported. The content.yaml is not taken into consideration.

Export Rules for content types¶

Empty array [] - nothing is exported
List of items - the given items are exported. If they are not present on the server an Exception is thrown.
Null (nothing given) - everything is being exported

Note

An error is thrown if the given entities are not found on the target server.

Example¶

Content

blueprint: # will export all 
subscription: # will export all 
catalog-item:  # export according to filter
  - Project Blueprints__WindowsVM
  - Project Blueprints__LinuxVm
  - Main Workflows__ConfigureVM
custom-resource: # will export all 
resource-action: # will export all 
property-group:  # export according to filter
  - memory
catalog-entitlement: [] # will export none
content-source:  # export according to filter
  - Project Blueprints
  - Main Workflows
  - Utility Workflows
  - Project Abx Actions
  - Project Code Stream pipelines
policy:  # export according to filter
  approval: [] # will export none
  content-sharing:
    - cs policy 1
    - cs policy 2
  day2-actions: [] # will export none
  deployment-limit: [] # will export none
  lease: [] # will export none
  resource-quota: [] # will export none
scenario: [] # will export none

Note

Unreleased blueprints that have custom form will be automatically released with version 1.

Note

To import / export custom forms and/or icons you have to specify the associated catalog-item name in catalog-item tag. The naming convention for this is SOURCE_NAME__CATALOG_ITEM_NAME The integration endpoint data for each workflow that is associated with the content source will be updated as well with the one fetched from the VCFA server.

ID handling¶

Relying on ids exported by Build Tools for VMware Aria should not happen. Build Tools for VMware Aria will remove where needed such ids or in some cases data will be fetched from the remote server, modified in flight and pushed to the server ( in cases where an import is needed ).

Single Project And Single Organization¶

When working with vra-ng project type, each generated project is intended to work with only one project and one organization. In a case where more are needed, you must generate multiple projects.

For every object type that contains organization or projectId key in the JSON definition (e.g. Policies) the following behaviour applies: - if the JSON definition contains projectId key and value defined, the value is replaced by the project defined in (based on import mechanism used): - <vrang.project.name> from the selected settings.xml Maven profile. - vrang_project_name provided to the installer script. - if the JSON definition contains organization key and value defined, the object is imported with the option of Available for any project or Organization enabled for the specific organization (the exact option name differentiates in UI based on product version) defined in (based on import mechanism used): - <vrang.org.name> from the selected settings.xml Maven profile. - vrang_org_name provided to the installer script.

Environment Connection Parameters¶

The following need to be added to the profile that you intend to use:

<!-- (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 settings.xml for MacOS is ~/.m2 and C:\Users\username\.m2 for Windows
vrang.username - For VCF 9 Automation - Classic organization instead of using you need to provide username in the following format: user@domain. E.g.:
admin@System - Provider admin (the "System" domain is used to identify the user as Provider admin)
configurationadmin@Classic - Classic organization admin
vrang.refresh.token - uses the given refresh token instead of credentials.

Note

Refresh token takes precedence over credentials.

vrang.bp.unrelease.versions - Defaults to true. Controls whether old versions of a blueprint sould be unreleased.
vrang.import.timeout - Timeout in miliseconds when syncing from Content Source for Catalog Items to appear before performing additional operations (e.g. attaching Custom Forms, Icons, etc.). Default value is 6000.
vrang.data.collection.delay.seconds - Delay in seconds to wait for vRA data collection to pass before importing data. Can also be passed as an interactive parameter -Dvrang.data.collection.delay.seconds=600. useful when Dynamic types and custom resources are used in the projects and vRO content is imported, however vRA needs to then retrieve it in order to be able to create the custom Resource and use the Create/Delete Workflows. This only happens after a short delay and the vRA data collector scrapes vRO. Defaults to no delay.
if a value is provided data collection is forced via REST API and if it completes successfully the provided delay time is skipped. In case the data collection fails, the delay is triggered.
vrang.org.name - needs to be specified. The vra-ng project is scoped to a single organization.

Use the profile by passing it with -P, e.g.:

mvn vra-ng:pull -Ptarget-env

Operations¶

Build Project¶

Overview¶

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

Usage¶

mvn clean package

The output of the command will result in com.company.bu.project.type-1.0.0-SNAPSHOT.vra-ng file generated in the target folder of the project.

Bundle Project¶

Overview¶

Maven goal for producing an installation bundle containing the solution package, all its dependencies and scripts for deploying to target environment.

Usage¶

mvn clean package -Pbundle-with-installer

For more information refer to Installer documentation.

Pull Content¶

Overview¶

When working on a VCFA project, you mainly make changes on a live server using the VCFA UI (Service Broker, Cloud Assembly, etc.) and then you need to capture those changes in the maven project on your filesystem to be able to store the content, track changes, collaborate, etc.

Usage¶

To support this use case, a custom maven goal vra-ng:pull is used. The following command will pull the content outlined into Content Descriptor file to the current project from a specified server and expand its content in the local filesystem overriding any local content:

mvn vra-ng:pull -Ptarget-env

Warning

The command will fail if the content.yaml is empty or it cannot find some of the described content on the target VCFA server.

Note

If a catalog item has a custom form and/or an icon they will be exported in subdirs of the catalog-items directory

Note

The value of the <vrang.vro.integration> is used to change the integration endpoint of Workflow Content Sources and other resources that point to that type of integration. If the property is missing a default name "embedded-VRO" will be used.

Additional Parameters¶

Additional parameters that can be passed as flags to the maven command, e.g. mvn vra-ng:pull -Dbp.ignore.versions=true.

bp.ignore.versions - ignores blueprint versioning (refer to the Blueprint Versioning section). This option defaults to false. When dealing with blueprint development, you might want to set this to true in order to avoid unnecessary blueprint versions.

Push Content¶

Overview¶

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

Usage¶

mvn clean package vrealize:push -Ptarget-env

Include Dependencies¶

By default, the vrealize:push goal will deploy all dependencies of the current project to the target environment. You can control that by the -DincludeDependencies flag. The value is true by default, so you skip the dependencies by executing the following:

mvn package vrealize:push -Ptarget-env -DincludeDependencies=false

Note

Dependencies will not be deployed if the server has a newer version of the same package deployed. For example, if the current project depends on com.vmware.pscoe.example-2.4.0 and on the server there is com.vmware.pscoe.example-2.4.2, the package will not be downgraded. You can force that by adding the `-Dvra.importOldVersions flag:

mvn package vrealize:push -Ptarget-env -Dvra.importOldVersions

The command above will forcefully deploy the exact versions of the dependent packages, downgrading anything it finds on the server.

Ignore Certificates¶

This section describes how to bypass a security feature in development/testing environment. Do not use those flags when targeting production servers. Instead, make sure the certificates have the correct CN, use FQDN to access the servers and add the certificates to Java's key store (i.e. cacerts).

Use Maven ProfilesDirectly Pass The Parameters

You can ignore certificate errors the certificate is not trusted and the CN does not match the actual hostname by appending the following parameters to the target profile in your maven 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 settings.xml for MacOS is ~/.m2 and C:\Users\username\.m2 for Windows

You can ignore certificate error, i.e. the certificate is not trusted, by adding the flag -Dvrealize.ssl.ignore.certificate:

mvn package {projectGoal}:push -Ptarget-env -Dvrealize.ssl.ignore.certificate

You can ignore certificate hostname error, i.e. the CN does not match the actual hostname, by adding the flag -Dvrealize.ssl.ignore.certificate:

mvn package {projectGoal}:push -Ptarget-env -Dvrealize.ssl.ignore.hostname

Additional Parameters¶

Additional parameters that can be passed as flags to the maven command, e.g. mvn clean package -Dvrang.bp.release=true.

vrang.bp.release - create a new version for already released blueprint (refer to the Blueprint Versioning section). This option defaults to true. When dealing with blueprint development, you might want to set this to false in order to avoid unnecessary blueprint versions.

Note

If there are any custom forms or icons associated with a catalog-item they will also be imported.

Note

If there are custom forms in the custom-forms directory that are associated with workflows, they will be imported to the VCFA server as well.

Note

If there are custom forms in the custom-forms directory that are associated with workflows, the content-sources that are associated with them will be imported as well (they will be read from the content-sources directory).

Release¶

To release a specific content uploaded on a live server, you can use the vrealize:release command:

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

Only parameter vrang.version is required. Defalut behavior for other parameters: - vrang.contentType: default value "all". Releases all supported content types. - vrang.contentNames: default value "[]". Releases all content of given types on server. - vrang.releaseIfNotUpdated: default value "false". Skips content if there are no updates since latest version.

Note

Nothing will be released if any of the content already has the given version existing.

Clean Up Content¶

Overview¶

A dedicated goal is implemented to clean up project packages on a given environment.

Usage¶

mvn vrealize:clean -DincludeDependencies=true -DcleanUpOldVersions=true -DcleanUpLastVersion=false -Ddryrun=true -P${PROFILE}

includeDependencies - a flag depicting if dependencies should also be deleted
cleanUpOldVersions - a flag depicting if old versions of the package (and dependencies in case of includeDependencies) should be deleted
cleanUpLastVersion - a flag depicting if the latest version should also be deleted before importing
dryrun - Dryrun or not

Examples¶

Clean up only current package version from the server

mvn vrealize:clean -DcleanUpLastVersion=true -DcleanUpOldVersions=false -DincludeDependencies=false

Clean up current package version from the server and its dependencies. This is a force removal operation.
```
mvn vrealize:clean -DcleanUpLastVersion=true -DcleanUpOldVersions=false -DincludeDependencies=true
```

Clean up old package versions and the old version of package dependencies.

mvn vrealize:clean -DcleanUpLastVersion=false -DcleanUpOldVersions=true -DincludeDependencies=true

Project Type Support for vrealize clean¶

Archetype	Supported	Comment
vro	Yes	-
vcd	Partial	It does not support dryRunning
abx	No	Not implemented
vrops	No	Not implemented
vra-ng	Partial	Does not support dryRunning
vrli	No	vRLI does not provide native package support
cs	No	Code Stream Services does not provide native support for packages

Troubleshooting¶

If maven error does not contain enough information re-run it with -X debug flag.
```
mvn -X <rest of the command>
```
Sometimes maven might cache old artifacts. Force fetching new artifacts with -U. Alternatively remove /.m2/repository folder.
```
mvn -U <rest of the command>
```