← Back to the blog

Artifactory

VCF Automation – Build Tools for VMware Aria – Up and Running

/ SimplyGeek

A laptop displaying code on a desk.
Photo: Daniil Komov / Pexels · Licence

This post updates my IaC for vRealize series with Build Tools version 4.7.0, the latest release when I wrote it. The guidance is intended for version 2.30.x or later. Earlier versions may not work as described.

vRealize Build Tools was renamed Build Tools for VMware Aria. The former VMware Fling is now an officially managed open-source project on GitHub. Its integrations extend beyond Orchestrator to manage content for these VCF solutions:

  • VCF Automation
  • VCF Operations Orchestrator
  • VCF Operations
  • VCF Operations (Logs)
  • VMware Cloud Director

Build Tools for VMware Aria is available in public Maven repositories. Except for the keystore, you no longer need to upload artefacts manually or use a vRO 7.3 appliance. With direct internet access, you can create a project and start using the tools. For enterprise environments, I recommend a supporting platform to provide greater control.

I will not be covering the following in this post:

  • Any form of Git integration
  • Continuous Integration
  • Multiple environments or multi-tenants
  • Visual Studio Code integration
  • Project structure / multiple or nested projects (apart from just the default ones created using the examples)

These topics need dedicated posts and are not prerequisites for this setup.

Deploy and configure Artifactory Repository Manager (optional)

I strongly recommend an artefact repository manager to store supporting artefacts and integrate them with deployment targets and pipelines. Options include Artifactory, Nexus and GitLab. Many enterprises already have repositories, projects and permissions in place. The basic setup below is for guidance and demonstration.

This guide does not cover every product or deployment option. I deployed JFrog Artifactory in a container managed by Podman on Rocky Linux 9, following this guide. You can follow the same guide or adapt the deployment to your environment.

Configure JFrog Artifactory

Before continuing, complete the initial Artifactory setup, change the default password and sign in to the UI. The following steps configure Artifactory for Build Tools for VMware Aria.

Create a local repository for Aria

First, create a repository for the keystore file. Earlier Build Tools versions used a Java Keystore. Its replacement is a Maven package containing a certificate and key file, which is easier to manage and distribute.

  1. Select Administration > Repositories > Local.
  2. Select Add Repository > Local Repository. In the version shown, the button is at the top right.
  3. Select Maven as the package type.
  4. Enter a Repository Key. I used aria-local.
  5. Select Create Local Repository.

The new local repository will be visible in the list.

Add the local repository to the libs-release virtual repository:

  1. Select the Virtual tab.
  2. Select libs-release.
  3. On the Basic Configuration page, scroll down to Repositories.
  4. Move your local repository to the right-hand list (Selected), either by dragging it or using the arrow button.

Select Force Authentication, just above Repositories. This requires users to authenticate and disables anonymous access.

Click Save.

Repeat the steps above to enable ‘Force Authentication‘ on the libs-snapshot virtual repository.

Create a user for repository access

Create a local Artifactory account for repository access. If you configure LDAP/Active Directory integration, you can use a directory account instead.

  1. Select Administration > User Management > Users.
  2. Select New User. In the version shown, the button is at the top right.
  3. Enter a username and password. I used aria-ci.

You can select Disable UI Access, but leave it unchecked if you need UI access for testing.

Select Save.

  1. Select Permissions > New Permission.
  2. Enter a permission name. I used aria-ci.
  3. Under Resources, select Add Repositories.
  4. Select the three checkboxes: Any Local Repository, Any Remote Repository and Any Distribution Repository.

Click OK.

Under Users, select the + icon next to Selected Users. Move the user account into this permission by dragging it or using the arrow button.

Click OK and finally click Create.

Create a certificate for Orchestrator package signing

VCF Operations Orchestrator requires a certificate to sign packages for import and export. Earlier Build Tools versions stored certificates in a Java Keystore, which was difficult to manage and share. The replacement Maven artefact contains the certificate and private key. An artefact repository manager can distribute it across the team.

Use OpenSSL to generate the certificates. I use the 3.0.x (LTS) Light release for Windows, available from the OpenSSL download page.

I keep the certificate configuration in Git. Create keystore.cfg with the following content:

[ req ]
default_bits = 2048
default_keyfile = private_key.pem
distinguished_name = req_distinguished_name
encrypt_key = no
prompt = no
string_mask = nombstr
req_extensions = v3_req

[ v3_req ]
basicConstraints = CA:FALSE
keyUsage = digitalSignature, keyEncipherment, dataEncipherment, nonRepudiation
extendedKeyUsage = serverAuth, clientAuth
subjectAltName = @alternate_names

[ req_distinguished_name ]
countryName = ##Country##
stateOrProvinceName = ##State##
localityName = ##Locality##
0.organizationName = ##OrgName
organizationalUnitName = ##OrgUnitName##
commonName = ##domain.local##

[ alternate_names ]
DNS.1 = ##domain.local##

Replace each ##xyz## placeholder with your own value.

From the command shell, run the following OpenSSL commands to create the certificate to your requirements (signed or unsigned).

Signed certificate

# Create Private Key with password.
openssl genrsa -passout pass:VMware1! -out key.pem 2048

# Create Certificate Signing Request.
openssl req -new -outform PEM -out cert.csr -inform PEM -key key.pem -config keystore.cfg

# Sign Certificate with CA (I am using Active Directory CA with a Certificate Template called 'VMwarevSphere'.
certreq -attrib "CertificateTemplate:VMwarevSphere" -submit cert.csr
<Save as cert.crt>

# Convert Certificate and Private Key to PKCS #12 format.
openssl pkcs12 -export -name "_dunesrsaalias_" -out cert.pfx -inkey key.pem -in cert.crt
openssl pkcs12 -in cert.pfx -nocerts -out private_key.pem
openssl pkcs12 -in cert.pfx -nokeys -clcerts -out cert.pem

Self-signed certificate

# Create Private Key with password.
openssl genrsa -passout pass:VMware1! -out private_key.key 2048

# Create Self-Signed Certificate.
openssl req -new --x509 -sha256 -days 3650 -key private_key.key -out cert.crt -config keystore.cfg

# Convert Certificate and Private Key to PKCS #12 format.
openssl pkcs12 -export -name "_dunesrsaalias_" -out cert.pfx -inkey private_key.key -in cert.crt
openssl pkcs12 -in cert.pfx -nocerts -out private_key.pem
openssl pkcs12 -in cert.pfx -nokeys -clcerts -out cert.pem

Create the keystore artefact (optional)

This section is only required if you plan to use an artefact repository manager.

Create a folder called ‘archetype.keystore-1.0.0‘. Move the following files into this folder:

  • private_key.pem
  • cert.pem

Create archetype.keystore-1.0.0.zip from the folder. The ZIP file must contain the archetype.keystore-1.0.0 folder itself, not just its contents.

Upload the keystore artefact to Artifactory

  1. Sign in to the Artifactory UI.
  2. Select Application > Artifactory > Artifacts.
  3. In the left-hand list, select aria-local or the local repository you created earlier.
  1. Select Deploy. In the version shown, the button is at the top right.
  2. Select Single Deploy.
  3. Add archetype.keystore-1.0.0.zip.
  4. Set Target Path to com/vmware/pscoe/build/archetype.keystore/1.0.0/archetype.keystore-1.0.0.zip.
  5. Select Deploy.

If the upload is successful, the repository will include a path to the file and its contents.

Configure the developer workstation (Windows)

The developer workstation needs prerequisite software and Maven configuration. This section covers Windows.

Install Postman (optional)

Postman provides a graphical interface for API calls, environments, variables and collections on Windows. It is optional. The example below uses it to obtain the VCF Automation API refresh token needed by the Build Tools. Download Postman to follow that example.

Obtain a VCF Automation refresh token

A refresh token is needed to obtain an access token (bearer token) for VCF Automation API calls. Supply only the refresh token to the Build Tools; they request bearer tokens internally. To obtain the refresh token, send a POST request to https://{{vra_host}}/csp/gateway/am/api/login?access_token. Replace {{vra_host}} with your VCF Automation hostname.

The POST request must include a JSON body as follows:

{
    "username": "{{username}}",
    "password": "{{password}}",
    "domain": "{{domain}}"
}

Replace {{username}}, {{password}} and {{domain}} with your values. For a local account, use System Domain. Otherwise, use the integrated directory's domain name, such as your Active Directory domain.

This Postman example uses an environment with those variables set:

Select Send to receive the refresh token:

Make a note of the refresh token, as this will be needed later.

Note that the refresh token is only valid for 90 days.

Install Java Development Kit (JDK)

Maven requires a Java JDK. The Build Tools officially support JDK 21 (LTS). I use the Adoptium build. Download the JDK, not the JRE. I recommend the Installer, which can set Path and JAVA_HOME.

Run the installer and change the option to set the JAVA_HOME variable.

Install NodeJS

The Build Tools use NodeJS to download dependencies through NPM and support version 22.x. Download it from the NodeJS website. I recommend the x64 MSI package, which also sets the environment PATH.

Open a command prompt and type node --version to verify that NodeJS is working. You should see output similar to the below:

node --version
v22.14.0

npm --version
10.9.2

Install Apache Maven

Apache Maven is used for managing and building projects based on the Project Object Model (POM). Download the Maven binary package from https://maven.apache.org/download.cgi. Build Tools supports version 3.9.x.

The binary package does not include an installer, so extract it to a directory that does not include any spaces. (I have mine located in ‘%USERPROFILE%\AppData\Local\apache-maven-3.9.9’).

Add the Maven bin directory to PATH. Open Edit environment variables for your account from the Start menu and add the path manually. I previously suggested setx, but found it unreliable.

Open a command prompt and type mvn --version to verify that Maven is working. You should see output similar to the below:

mvn --version
Apache Maven 3.9.9 (bc0240f3c744dd6b6ec2920b3cd08dcc295161ae)
Maven home: C:\Users\gavin\AppData\Local\apache-maven-3.9.6
Java version: 21.0.6, vendor: Eclipse Adoptium, runtime: C:\Program Files\Eclipse Adoptium\jdk-21.0.6.7-hotspot
Default locale: en_GB, platform encoding: Cp1252
OS name: "windows 10", version: "10.0", arch: "amd64", family: "windows"

If the command fails, check the Maven and JDK installation paths and their environment variables.

Create a master password

Maven can store encrypted server passwords in settings.xml. First, set a master password with mvn --encrypt-master-password. The command prompts for a password and returns its encrypted form:

mvn --encrypt-master-password

Store the encrypted string in settings-security.xml, in %USERPROFILE%\.m2\. If the file does not exist, create it with this content:

<settingsSecurity>
<master>{sMFA/2y5+qAHjPPmlxkFj1tcWbU6CGKwm3t1dA1eGSo=}</master>
</settingsSecurity>

Configure project settings (settings.xml)

The following settings.xml examples support setups with and without an artefact repository manager. You can use the second example to try the Build Tools without deploying a dedicated platform.

The settings.xml file should be created in the ‘%USERPROFILE%\.m2\‘ folder.

Settings.xml (using Artifactory Repository)

Use the following Settings.xml example to use Build Tools with Artifactory Repository Manager. All artefacts are retrieved from this repository. If you followed my setup, then requests to Maven Central will be proxied through Artifactory, and the keystore file will be downloaded from the aria-local repository.

Replace each {{ }} placeholder with your own value.

<?xml version="1.0" encoding="UTF-8"?>
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd">
    <servers>
        <server>
            <id>aria-release</id>
            <username>aria-ci</username>
            <password>{{encrypted_password}}</password>
        </server>
        <server>
            <id>aria-snapshots</id>
            <username>aria-ci</username>
            <password>{{encrypted_password}}</password>
        </server>
    </servers>

    <profiles>
        <profile>
            <id>artifactory</id>
            <repositories>
                <repository>
                    <snapshots><enabled>false</enabled></snapshots>
                    <id>aria-release</id>
                    <name>aria-release</name>
                    <url>http://{{artifactory_fqdn}}:8082/artifactory/libs-release</url>
                </repository>
                <repository>
                    <snapshots><enabled>true</enabled></snapshots>
                    <id>aria-snapshots</id>
                    <name>aria-snapshots</name>
                    <url>http://{{artifactory_fqdn}}:8082/artifactory/libs-snapshot</url>
                </repository>
            </repositories>
            <pluginRepositories>
                <pluginRepository>
                    <snapshots><enabled>false</enabled></snapshots>
                    <id>aria-release</id>
                    <name>aria-release</name>
                    <url>http://{{artifactory_fqdn}}:8082/artifactory/libs-release</url>
                </pluginRepository>
                <pluginRepository>
                    <snapshots><enabled>true</enabled></snapshots>
                    <id>aria-snapshots</id>
                    <name>aria-snapshots</name>
                    <url>http://{{artifactory_fqdn}}:8082/artifactory/libs-snapshot</url>
                </pluginRepository>
            </pluginRepositories>
            <properties>
                <releaseRepositoryUrl>http://{{artifactory_fqdn}}:8082/artifactory/libs-release</releaseRepositoryUrl>
                <snapshotRepositoryUrl>http://{{artifactory_fqdn}}:8082/artifactory/libs-snapshot</snapshotRepositoryUrl>
            </properties>
        </profile>
        <profile>
            <id>packaging</id>
            <properties>
                <keystoreGroupId>com.vmware.pscoe.build</keystoreGroupId>
                <keystoreArtifactId>archetype.keystore</keystoreArtifactId>
                <keystoreVersion>1.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>aria</id>
            <properties>
                <!-- VCF Automation Connection -->
                <vrang.host>{{vra_fqdn}}</vrang.host>
                <vrang.port>443</vrang.port>
                <vrang.org.name>{{vra_org_name}}</vrang.org.name>
                <vrang.project.name>{{vra_project_name}}</vrang.project.name>
                <vrang.refresh.token>{{vra_refresh_token}}</vrang.refresh.token>
                <vrang.vro.integration>{{vro_integration_name}}</vrang.vro.integration>
                <vrang.bp.release>true</vrang.bp.release>
                <!-- VCF Automation Orchestrator Connection -->
                <vro.host>{{vro_fqdn}}</vro.host>
                <vro.port>443</vro.port>
                <vro.auth>vra</vro.auth>
                <vro.authHost>{{vra_fqdn}}</vro.authHost> <!-- Required for external vro instances when vra auth is used -->
                <vro.authPort>443</vro.authPort> <!-- Required for external vro instances when vra auth is used -->
                <vro.refresh.token>{{vra_refresh_token}}</vro.refresh.token>
                <!--<vrealize.ssl.ignore.hostname>true</vrealize.ssl.ignore.hostname> -->
                <!--<vrealize.ssl.ignore.certificate>true</vrealize.ssl.ignore.certificate> -->
            </properties>
        </profile>
    </profiles>

    <mirrors>
        <mirror>
            <id>maven-default-http-blocker</id>
            <mirrorOf>external:dummy:*</mirrorOf>
            <name>Pseudo repository to mirror external repositories initially using HTTP.</name>
            <url>http://0.0.0.0/</url>
            <blocked>true</blocked>
        </mirror>
        <mirror>
            <id>aria-release</id>
            <name>Artifactory proxy for Maven Central</name>
            <url>http://{{artifactory_fqdn}}:8082/artifactory/libs-release</url>
            <mirrorOf>central</mirrorOf>
        </mirror>
    </mirrors>
    
    <activeProfiles>
        <activeProfile>artifactory</activeProfile>
        <activeProfile>packaging</activeProfile>
    </activeProfiles>
</settings>

The ‘{{encrypted_password}}‘ is the encrypted password generated using the ‘mvn –encrypt-password‘ command. This is the encrypted password for the user account that was created in the ‘Create a User for Repository Access‘ section.

Settings.xml (local / no artefact repository)

Use the following Settings.xml example to use Build Tools where no artefact repository is available. In this scenario, you are getting artefacts directly from Maven Central and sourcing the keystore certificate and private key files locally.

Replace each {{ }} placeholder with your own value.

<?xml version="1.0" encoding="UTF-8"?>
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd">
    <profiles>
        <profile>
            <id>packaging</id>
            <properties>
                <vroPrivateKeyPem>C:/path/to/keystore/private_key.pem</vroPrivateKeyPem>
                <vroCertificatePem>C:/path/to/keystore/cert.pem</vroCertificatePem>
                <vroKeyPass>VMware1!</vroKeyPass>
            </properties>
        </profile>
        <profile>
            <id>aria</id>
            <properties>
                <!-- VCF Automation Connection -->
                <vrang.host>{{vra_fqdn}}</vrang.host>
                <vrang.port>443</vrang.port>
                <vrang.org.name>{{vra_org_name}}</vrang.org.name>
                <vrang.project.name>{{vra_project_name}}</vrang.project.name>
                <vrang.refresh.token>{{vra_refresh_token}}</vrang.refresh.token>
                <vrang.vro.integration>{{vro_integration_name}}</vrang.vro.integration>
                <vrang.bp.release>true</vrang.bp.release>
                <!-- VCF Automation Orchestrator Connection -->
                <vro.host>{{vro_fqdn}}</vro.host>
                <vro.port>443</vro.port>
                <vro.auth>vra</vro.auth>
                <vro.authHost>{{vra_fqdn}}</vro.authHost> <!-- Required for external vro instances when vra auth is used -->
                <vro.authPort>443</vro.authPort> <!-- Required for external vro instances when vra auth is used -->
                <vro.refresh.token>{{vra_refresh_token}}</vro.refresh.token>
                <!--<vrealize.ssl.ignore.hostname>true</vrealize.ssl.ignore.hostname> -->
                <!--<vrealize.ssl.ignore.certificate>true</vrealize.ssl.ignore.certificate> -->
            </properties>
        </profile>
    </profiles>
   
    <activeProfiles>
        <activeProfile>packaging</activeProfile>
    </activeProfiles>
</settings>

Create your first project (actions-based)

This example creates a JavaScript Actions-based project and shows how to push and pull its code. For other project types, see the official documentation.

  1. Create a root folder for your projects.
  2. Open a command prompt in that folder.
  3. Run the following command.
mvn archetype:generate -DinteractiveMode=false -DarchetypeGroupId=com.vmware.pscoe.o11n.archetypes -DarchetypeArtifactId=package-actions-archetype -DarchetypeVersion=4.7.0 -DgroupId=com.simplygeek -DartifactId=js-actions

You can replace com.simplygeek with your own value.

A new folder is created called ‘js-actions‘ and will include a sample.js function/action.

Push actions

Push this new project to the Orchestrator server with the following command:

mvn clean package vrealize:push -DincludeDependencies=true -DskipTests -Paria -f "js-actions"

If this is successful, you will see that the package now exists under the Packages section in Orchestrator:

Pull actions

Pull this project from the Orchestrator server with the following command:

Tip: Add server-side actions to the package you pushed to include them in the next pull.

mvn clean package vro:pull -DincludeDependencies=true -DskipTests -Paria -f "js-actions"

You now have a working Build Tools setup. Future posts cover the project types and ways to manage them in Git.

I have tested the steps and solutions in this guide as thoroughly as I can. If you encounter issues, share them and I will help where I can.

Join the discussion

Sign in with GitHub to leave a comment. View discussions on GitHub.

← Explore more articlesFollow via RSS ↗