Here you will learn the needed steps on how to configure your environment
Build Tools for VMware Aria are built on top of the Maven build automation ecosystem. vRealize Automation and vRealize Orchestrator content are described as Maven Project Object Models which enable huge amount of options like automated build going through phases like validate, compile, test, package, verify, install and deploy; dependency management, versioning, etc.
- Build Tools for VMware Aria Platform
- Build Tools for VMware Aria Platform ready to use
- Workstation can access Build Tools for VMware Aria Platform services
- Java 17
- Maven 3.5+ (official installation guide)
There are several things that need to be in place before you can use the Build Tools for VMware Aria to work with vRO content.
Java keystore used for signing packages build time.
# Create new Keystore
keytool -keystore package.jks -genkey -alias _dunesrsa_alias_ -storepass 'VMware1!' -keyalg RSA
# Delete default alias
keytool -delete -alias _dunesrsa_alias_ -keystore package.jks -storepass 'VMware1!'
# Generate new Key
keytool -genkey -keyalg RSA -keysize 2048 -alias _dunesrsa_alias_ -keystore package.jks -storepass 'VMware1!' -validity 3650 -dname 'CN=Project,OU=Department,O=Company,L=City,ST=State,C=XX,[email protected]'
## Optional ##
# Generate Certificate Signing Request
keytool -certreq -alias _dunesrsa_alias_ -keypass 'VMware1!' -keystore package.jre -storepass 'VMware1!' -file packageCertRequest.csr
# Import the signed certificate
keytool -importcert -alias _dunesrsa_alias_ -keypass 'VMware1!' -file packageCertRequest.crt -keystore package.jks -storepass 'VMware1!'
# Export/Backup Certificate
keytool -exportcert -alias _dunesrsa_alias_ -keystore package.jks -storepass 'VMware1!' -file packageCertExportNote: Mind the single quotes in the examples above on Windows - those might be part of the passowrd depending on which interpreter (shell) you are using. Correct the string literal and escaping appropriately for your case.
Note: JKS is a propriatary format specific to the particular JVM provider. When running above commands, ensure the keytool used is the one under the JVM that Maven would use (check with mvn -v).
Firstly, you will need to configure Maven.
There are a number of properties that must be set through profiles in the settings.xml file, as they are environment specific:
- keystorePassword - Required. This is the password for the keystore used for signing vRO packages.
- keystoreLocation - Required. This is the location of the keystore. You can either hardcode a location on the machine executing the build.
- snapshotRepositoryUrl - Required. This is the url of the snapshot maven repository.
- releaseRepositoryUrl - Required. This is the url of the release maven repository. Could be the same as snapshotRepositoryUrl.
The recommended approach is to keep a settings XML file under SCM to be used by developers and a modified version with credentials for the Artifactory deployed on the CI server directly (i.e. not accessible by everyone).
Furthermore, in the example, bundling (i.e. should the bundle.zip be produced upon build) is moved to a separate profile and developers/CI can choose whether to create the bundle or not by including the "-Pbundle" command line argument to the maven invocation.
<?xml version="1.0" encoding="UTF-8"?>
<settings xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.1.0 http://maven.apache.org/xsd/settings-1.1.0.xsd"
xmlns="http://maven.apache.org/SETTINGS/1.1.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<servers>
<server>
<username>{vro_username}</username>
<password>{native+maven+encrypted+pass}</password>
<id>corp-dev-vro</id>
</server>
<server>
<username>{vra_username}</username>
<password>{native+maven+encrypted+pass}</password>
<id>corp-dev-vra</id>
</server>
</servers>
<profiles>
<profile>
<id>packaging</id>
<properties>
<!-- Version < 2.14
<keystorePassword>{keystore_password}</keystorePassword>
<keystoreLocation>{keystore_location}</keystoreLocation>
-->
<!-- Version >= 2.14 -->
<keystoreGroupId>com.vmware.pscoe.build</keystoreGroupId>
<keystoreArtifactId>archetype.keystore</keystoreArtifactId>
<keystoreVersion>2.0.0</keystoreVersion>
<vroPrivateKeyPem>target/${keystoreArtifactId}-${keystoreVersion}/private_key.pem</vroPrivateKeyPem>
<vroCertificatePem>target/${keystoreArtifactId}-${keystoreVersion}/cert.pem</vroCertificatePem>
<vroKeyPass>VMware1!</vroKeyPass>
</properties>
</profile>
<profile>
<id>bundle</id>
<properties>
<assembly.skipAssembly>false</assembly.skipAssembly>
</properties>
</profile>
<profile>
<id>artifactory</id>
<repositories>
<repository>
<snapshots><enabled>false</enabled></snapshots>
<id>central</id>
<name>central</name>
<url>http://{artifactory-hostname}/artifactory/{release_repository}</url>
</repository>
<repository>
<snapshots><enabled>true</enabled></snapshots>
<id>central-snapshots</id>
<name>central-snapshots</name>
<url>http://{artifactory-hostname}/artifactory/{snapshot_repository}</url>
</repository>
</repositories>
<pluginRepositories>
<pluginRepository>
<snapshots><enabled>false</enabled></snapshots>
<id>central</id>
<name>central</name>
<url>http://{artifactory-hostname}/artifactory/{release_repository}</url>
</pluginRepository>
<pluginRepository>
<snapshots><enabled>true</enabled></snapshots>
<id>central-snapshots</id>
<name>central-snapshots</name>
<url>http://{artifactory-hostname}/artifactory/{snapshot_repository}</url>
</pluginRepository>
</pluginRepositories>
<properties>
<releaseRepositoryUrl>http://{artifactory-hostname}/artifactory/{release_repository}</releaseRepositoryUrl>
<snapshotRepositoryUrl>http://{artifactory-hostname}/artifactory/{snapshot_repository}</snapshotRepositoryUrl>
</properties>
</profile>
<profile>
<!--Environment identifier. Multiple environments are allowed by configuring multiple profiles -->
<id>corp-dev</id>
<properties>
<!--vRO Connection-->
<vro.host>{vro_host}</vro.host>
<vro.port>{vro_port}</vro.port>
<vro.username>{vro_username}</vro.username> <!--NOT RECOMMENDED USE vro.serverId and encrypted credentials-->
<vro.password>{vro_password}</vro.password> <!--NOT RECOMMENDED USE vro.serverId and encrypted credentials-->
<vro.serverId>corp-dev-vro</vro.serverId>
<vro.auth>{basic|vra}</vro.auth> <!-- If "basic" is selected here, ensure com.vmware.o11n.sso.basic-authentication.enabled=true System Property is set in vRO -->
<vro.authHost>{auth_host}</vro.authHost> <!-- Required for external vRO instances when vra auth is used -->
<vro.authPort>{auth_port}</vro.authPort> <!-- Required for external vRO instances when vra auth is used -->
<vro.refresh.token>{refresh_token}</vro.refresh.token> <!-- login with tokenwhen vra auth is used -->
<vro.proxy>http://proxy.host:80</vro.proxy>
<vro.tenant>{vro_tenant}</vro.tenant>
<!--vRA Connection-->
<vra.host>{vra_host}</vra.host>
<vra.port>{vra_port}</vra.port>
<vra.tenant>{vra_tenant}</vra.tenant>
<vra.serverId>corp-dev-vra</vra.serverId>
<vra.username>{vra_username}</vra.username> <!--NOT RECOMMENDED USE vra.serverId and encrypted credentials-->
<vra.password>{vra_password}</vra.password> <!--NOT RECOMMENDED USE vra.serverId and encrypted credentials-->
</properties>
</profile>
</profiles>
<activeProfiles>
<activeProfile>artifactory</activeProfile>
<activeProfile>packaging</activeProfile>
</activeProfiles>
</settings>Note: {vro_username} is usually taking the form of
username@domain. For vRO8 embedded in vRA8 with BASIC for {vro_auth} it will be required that onlyusernamepart is specified for successful authentication.
vRO packages are signed. In order to be able to use the toolchain, you have to have a keystore and configure it in the settings.xml file both for the developers and the CI.
You must have the keystore file accessible on the machine and set the keystoreLocation and keystorePassword properties through the settings.xml.
There is a built-in bundling capabilities that are described in a Maven profile. You can decide to not only package a vRO/vRA project, but also to create a *-bundle.zip with all its dependencies. This will create an archive with the following structure:
vro/ # all vRO packages. If the current project is vRO, its package will be here as well.
vra/ # all vRA packages. IF the current project is vRA, its package will be here as well.
repo/ # JARs that comprise the bundle installer - a CLI tool that is capable of importing the whole bundle to a target environment.
bin/ # shells for invoking the bundle installer CLI.
installer # Bash executable version of the installer for Linux/Unix/macOS
intasller.bat # Batch exectable version of the installer for WindowsThe bundle is produced as a separate artifact during mvn package. To produce it, you need to add the -Pbundle-with-installer profile:
mvn clean deploy -Pbundle-with-installerTo learn more about the bundle installer, check Build Tools for VMware Aria - Bundle Installer for more information.
All API calls from the toolchain (i.e. the client) verify the SSL certificate returned by vRO/vRA (i.e. the server). If you are using self-signed or third-party signed certificates, you may need to add those certificates or their CA certificates to the default JAVA keystore, i.e. JAVA_HOME/lib/security/cacerts. This is the recommended approach.
The other option, applicable ONLY for development environments, is to ignore certificate checks by passing a flag.
Controlling timeouts is done through the following System Properties:
- the Connection Timeout ("vrealize.connection.timeout") – the time to establish the connection with the remote host (Defaults to 360 seconds (6 minutes))
- the Socket Timeout ("vrealize.socket.timeout") – the time waiting for data – after establishing the connection maximum time of inactivity between two data packets (Defaults to 360 seconds(6 minutes))
- the vra 8.x content import timeout ("vrang.import.timeout") – (in miliseconds) the time out waiting for import of custom forms / content sources to complete (Defaults to 6 seconds)
-
the vra 8.x data collection delay ("vrang.data.collection.delay.seconds") – (in seconds) the amount of time to way before running the import job. The vRA data collection usually takes around 10 minutes ( 600 seconds ) to complete. Defaults to no delay.
You can set these as JVM Options as specified here
-
Timeouts can be set up to be used by the installer too using the following settings (in the environment properties file):
- http_connection_timeout - for the connection timeout (in seconds), default is 360 seconds (6 minutes)
- http_socket_timeout - for the socket timeout (in seconds), default is 360 seconds (6 minutes)
- vrang_import_timeout - for the vra 8.x content import timeout (custom forms, content sources).
Checksums are supported for the following project types - vRO JS, TS, XML and vRA 7/8. By defaults the target folder will also contain .sha1 checksums for the different file types, e.g. js.sha1, ts.sha1, xml.sha1, content.sha1 and packages.sha1. These are specified per project type in the base pom.xml using following definition:
<properties>
...
<checksum.definitions>js,packages</checksum.definitions>
...
</properties>To add more checksum definitions for your project, just redefine this property in your pom.xml. For example, add the "docs" checksum to the build:
<properties>
...
<checksum.definitions>js,packages,docs</checksum.definitions>
...
</properties>With the "docs" prefix you can now specify if the phase is enabled, readmes location directory, files glob filter and as well list of excludes RegExp patterns of files to ommit. For example like this:
<properties>
...
<checksum.definitions>js,packages,docs</checksum.definitions>
<checksum.docsEnabled>true</checksum.docsEnabled> <!-- Required and allows for children to disable this step also -->
<checksum.docsDir>docs/markdown</checksum.docsDir>
<checksum.docsGlob>*.md</checksum.docsGlob>
<checksum.docsExcludes>\.docx$,\.pdf$</checksum.docsExcludes>
...
</properties>