All Apps Organization Project

Overview¶

Field	Value
Name	vcfa-all-apps
Archetype Group ID	com.vmware.pscoe.vcfa-all-apps.archetypes
Archetype Artifact ID	package-vcfa-all-apps-archetype
Package extension	vcfaa
Product compatibility	VCF Automation All Apps Organization (9.x)

VCF Automation projects for All Apps organizations are called vcfa-all-apps 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 All Apps organization projects.

Content Type	Attribute key in Content Descriptor	Comment
Blueprints	`blueprint`	See Blueprints.
Custom Resources	`custom-resource`	See Custom Resources.
Event Subscriptions	`subscription`	See Event Subscriptions.
Notifications (Templates)	`scenario`	See Notifications.
Policies	`policy`	See Policies.
Property Groups	`property-group`	See Property Groups.
Resource Actions	`resource-action`	See Resource Actions.
Workflows (as Catalog Items)	`workflow`	See Workflows.

Create New VCFA Project for All Apps Organizations¶

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

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

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

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

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

mvn archetype:generate ^
  -DinteractiveMode=false ^
  -DarchetypeGroupId=com.vmware.pscoe.vcfa-all-apps.archetypes ^
  -DarchetypeArtifactId=package-vcfa-all-apps-archetype ^
  -DarchetypeVersion=4.24.1 ^
  -DgroupId=com.company.department ^
  -DartifactId=vcfa-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 VCF Automation All Apps projects, make sure to set the value to com.vmware.pscoe.vcfa-all-apps.archetypes.
The archetypeArtifactId property defines the artifact ID of the archetype (project template) that you want to use for the project. For VCF Automation All Apps projects, make sure to set the value to package-vcfa-all-apps-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.

vcfa-project
├── README.md
├── content.yaml
├── pom.xml
├── release.sh
└── src
    └── main
        └── resources
            └── blueprints
                └── Small VM
                    └── content.yaml
                    └── details.json
                    └── Small VM__FormData.json
                    └── styles.css
            └── custom-resources
                └── Custom REST Host
                    └── details.json
            └── policies
                └── approval
                    └── vm_resize_approval.json
                └── day2-actions
                    └── vm_remove_disk.json
                └── iaas-resource
                    └── large-namespace-policy.json
                └── lease
                    └── short_lease.json
            └── property-groups
                └── Custom VM Properties.json
            └── resource-actions
                └── Add CD-ROM to Deployment
                    └── Add CD-ROM to Deployment__FormData.json
                    └── details.json
                    └── styles.css
            └── scenarios
                └── Deployment Lease Expired
                    └── details.json
                    └── template.html
            └── subscriptions
                └── Add user to deployment.json
            └── workflows
                └── Add a user to a user group.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:
property-group:
custom-resource:
resource-action:
workflow:
subscription:
policy:
  approval:
  day2-actions:
  iaas-resource:
  lease:
scenario:

Note

VCFA Project for All Apps supports only the content types outlined in the 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.

Content Filtering¶

Following is a list of the rules for managing project contents based on the contents of the content descriptor for each category type. Note that these rules apply to both operation types, export (pulling contents) and import (pushing contents).

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

Content Filtering 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 and imports all blueprint/template objects
property-group:           # exports and imports property group objects listed in the filter
  - memory
custom-resource:          # exports and imports all custom resource objects
resource-action:          # exports and imports all resource action objects
workflow:                 # exports and imports workflow objects listed in the filter
  - Some Workflow
subscription:             # exports and imports all EBS subscription objects
policy:                   # exports and imports policy objects listed in the filter
  approval:               # exports and imports approval policy objects listed in the filter
    - blueprint_approval
  day2-actions: []        # does not export or import day-2 action policy objects
  iaas-resource: []       # does not export or import IaaS resource policy objects
  lease: []               # does not export or import lease policy objects
scenario: []              # does not export or import scenario/notification objects

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 case an import is needed).

Single Project And Single Organization¶

When you are working with the vcfa-all-apps 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 ID value that you defined in one of the following sources (based on the import mechanism that you use).
- The <vcfa.project.name> attribute from the settings.xml Maven profile that you are using.
- The vcfa_project_name property that you provide to the installer script.
If the JSON definition contains the organization key with a value, the value is replaced by the organization ID value that you defined in one with the following sources (based on the import mechanism that you use) and content object is imported with the scope option to make it available for any project within the organization or the whole organization.
- The <vcfa.org.name> attribute from the settings.xml Maven profile that you are using.
- The vcfa_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 .....  -->
    <vcfa.host>flt-auto01.corp.internal</vcfa.host>
    <vcfa.csp.host>cloud.corp.internal</vcfa.csp.host>
    <vcfa.proxy>http://proxy.host:80</vcfa.proxy>
    <vcfa.port>443</vcfa.port>
    <vcfa.username>administrator@tenant</vcfa.username>
    <vcfa.password>someSecurePassword</vcfa.password>
    <vcfa.project.name>{project+name}</vcfa.project.name>
    <vcfa.org.name>{tenant}</vcfa.org.name>
    <vcfa.refresh.token>{refresh+token}</vcfa.refresh.token>
    <vcfa.bp.unrelease.versions>true|false</vcfa.bp.unrelease.versions>
    <vcfa.vro.integration>{vro+integration+name}</vcfa.vro.integration>
    <vcfa.import.timeout>{import+timeout}</vcfa.import.timeout>
    <vcfa.data.collection.delay.seconds>{data+collection+delay}</vcfa.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 vcfa-all-apps: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 vcfa.username element for VCF Automation All Apps organizations, you need to 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@AllApps for a configurationadmin user from an organization with the name AllApps.
In the vcfa.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 vcfa.bp.unrelease.versions optional element, specify whether old versions of a blueprint should be unreleased. The default value is true.
In the vcfa.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 vcfa.data.collection.delay.seconds optional element, specify the delay in seconds for waiting for the data collection from VCF Operations Orchestrator to VCFA before importing data. You can also pass this configuration as an interactive parameter -Dvcfa.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 vcfa.org.name element, you always need to specify the organization name. The vcfa-all-apps project is scoped to a single organization.

Operations¶

This section describes the operations that you can perform with the VCF Automation project for an All 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.vcfaa 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 an All 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 vcfa-all-apps: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 on the local filesystem by overriding any local content.

mvn vcfa-all-apps: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

Use the value of the <vcfa.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 vcfa-all-apps: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 vcfa-all-apps:push -Ptarget-env

Include Dependencies¶

By default, the vcfa-all-apps: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 vcfa-all-apps: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 vcfa-all-apps: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 vcfa-all-apps: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 -Dvcfa.bp.release=false, where the vcfa.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.

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 vcfa-all-apps:release command as shown in the following example.

mvn clean package vcfa-all-apps:release -Ptarget-env -Dvcfa.contentType=blueprint -Dvcfa.contentNames=testBlueprint -Dvcfa.version=1 -DreleaseIfNotUpdated=false

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

The vcfa.contentType parameter defaults to the value all that releases all supported content types.
The vcfa.contentNames parameter defaults to the value [] that releases all content of the given types on the server.
The vcfa.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 vcfa.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 vcfa-all-apps: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 VCF Automation All 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 vcfa-all-apps: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 vcfa-all-apps: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 vcfa-all-apps: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 vcfa-all-apps: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>
```