Installer

Overview

The Installer module allows you to package a project and all its dependencies into an all-in-one bundle that you can deploy to a target environment via a script that is included in the bundle.

When you bundle a project with the -Pbundle-with-installer Maven profile, you get an additional ***-bundle.zip artifact that contains your project, all its dependencies, the bundle Installer CLI tool (script), and additional Java files that are required for the operation of the Installer CLI tool.

You can extract the ZIP bundle and run the Installer CLI tool in the bin/ directory to import all project content packages into a target environment. Additionally, at the end of the process for importing project content, you can run an Orchestrator workflow that stores or performs additional configurations related to your projects.

Process Flow

You can run the Installer CLI tool in one of two modes, interactive and unattended.

• In interactive mode, the tool shows prompts to collect the necessary properties for importing the project content (based on the bundle content).

  Tip

  If you start the Installer tool in interactive mode, read carefully all prompts and specify the correct values for your environment. The default values in the prompts are set according to PSCoE best practices.

• In unattended mode, you provide a Java properties file (with the .properties extension) that contains all necessary properties for importing the content.

  Tip

  To retrieve the list of required properties for a specific bundle, you can run the Installer tool in interactive mode first and store the collected properties to a file. Alternatively, you can prepare your own .properties file by using the sample listings of properties based on project type and operation under List of Properties section.

Based on the types of project content of the extracted bundle and the property values that you pass to it, the Installer CLI tool performs all applicable operations from the following list (in the specified order).

1. Read common properties.
2. Import the Orchestrator project content.
3. Import the Aria Automation Code Stream/Pipelines project content.
4. Import the VCF Automation ABX project content.
5. Import the VCF Automation project content for a VM Apps organization.
6. Import the VCF Automation project content for an All Apps organization.
7. Import the VMware Cloud Director project content.
8. Clean up the bundle versions of VCF Operations Orchestrator project content packages.
9. Clean up the old versions of VCF Operations Orchestrator project content packages (if applicable).
10. Clean up the VCF Automation project content for a VM Apps organization from the bundle.
11. Clean up the VCF Automation project content for an All Apps organization from the bundle.
12. Import the VCF Operations project content.
13. Import the VCF Operations for Logs project content.
14. Import the SSH (basic) project content.
15. Run an Orchestrator workflow.

The following diagram shows an overview of the process flow of the Installer CLI tool and the operations it performs.

Usage

This section provides details about using the Installer CLI tool.

Run the Installer

To run the Installer CLI tool, you first need to extract the contents of the ZIP bundle that you created with the -Pbundle-with-installer Maven profile and open a terminal inside the extracted bundle directory. Then use one of the following options to start the Installer in the respective mode.

• To start the Installer in interactive mode, run the following command, read carefully all prompts, and specify the correct values for your environment.

  At the end of the interaction, before it starts any of the content management operations, the Installer will prompt you to store all your answers to an environment.properties file on the local filesystem disk. You can then use this file with the same answers for a different run of the Installer, for a different bundle, or for a different environment. Note that the Installer encodes the values of all password properties in the file but you should still make sure that the file is well protected.

  Linux / MacOSWindows (CMD)

  ./bin/installer
  

  bin\installer.bat
  

• To start the Installer in unattended mode, add a Properties file with all applicable properties inside the extracted bundle directory (for example, in the bin/ directory with the script), and run the following command in which you specify the path to the .properties file as the only argument of the command.

  Tip

  The following command uses a file with the default name environment.properties in the bin/ directory of the extracted bundle.

  Linux / MacOSWindows (CMD)

  ./bin/installer ./bin/environment.properties
  

  bin\installer.bat bin\environment.properties
  

Following is a sample listing of an environment.properties file for a bundle that contains content for two project types, VCF Operations Orchestrator and VCF Automation for a VM Apps organization, but imports only the Orchestrator content (to a standalone Orchestrator instance) and then runs the Orchestrator workflow with the ID 1944423533582937823496790834565483423.

# Example environment.properties file
ignore_ssl_certificate_verification=true
ignore_ssl_host_verification=true
http_connection_timeout=360
http_socket_timeout=360
vrealize_ssh_timeout=300

vro_import_packages=true                                # Starts the import operation for the Orchestrator project content
vro_embedded=false
vro_enable_backup=true                                  # Specifies that this a standalone instance
vro_server=flt-orchestrator01.corp.internal
vro_port=443
vro_auth=basic
vro_tenant=vsphere.local
vro_username=administrator@vsphere.local
vro_password={PASS}Vk13YXJlMSE\=                        # Same as "VMware1\!"

vro_import_old_versions=false
skip_vro_import_old_versions=true                       # Set to the opposite value of "vro_import_old_versions"
vro_import_configuration_attribute_values=false
vro_import_configuration_secure_attribute_values=false
vro_force_import_latest_versions=false

vro_delete_old_versions=true                            # Starts the clean up operation for old versions of project packages

# Run vRO configuration workflow
vro_run_workflow=true                                   # Starts the Run Workflow operations
vro_run_workflow_id=1944423533582937823496790834565483423
# input.json contains JSON where each first class KEY represents
# the workflow input parameter name and its value is sent as value
# Supported types of workflow in/output parameters are string, number, boolean, Array/string
vro_run_workflow_input_file_path=./input.json
# output.json contains JSON where each first class KEY represents
# the workflow output parameter name and its value is a pretty printed value as JSON
vro_run_workflow_output_file_path=./output.json
vro_run_workflow_timeout=300

vra_ng_import_packages=false                            # Skips the import operations for the VCF Automation for a VM Apps organization content

List of Properties

Following is an exhaustive list of all properties that you can use with the Installer tool. The properties are grouped in sections per project type (that is available in the bundle). Within each section, the properties are grouped in subsections based on their purpose and the operation they are used for.

Note that the script uses the properties from the Common properties section for all operations.

List of all Installer properties (grouped by project type)

#################################################################################
## Common properties (required for all operations)                             ##
#################################################################################

## Common SSL verification properties                                          ##
ignore_ssl_certificate_verification
ignore_ssl_host_verification

## Common timeout properties                                                   ##
http_connection_timeout
http_socket_timeout
vrealize_ssh_timeout

#################################################################################
## Properties for Orchestrator Projects                                        ##
#################################################################################

##  Operation flags. Note that each flag creates a separate session!           ##
vro_import_packages             # imports project bundle packages
vro_delete_last_version         # cleans up project bundle packages
vro_delete_old_versions         # cleans up old versions of bundle packages

## Orchestrator type flag - specifies if host is embedded or standalone/external##
## The value determines the set of connection configuration properties to use! ##
## When embedded, use VCF Automation VM Apps connection configurations         ##
vro_embedded                                        

## Connection configuration                                                    ##
## These properties are used only for standalone/external Orchestrator         ##
## instances (i.e. when "vro_embedded=false")                                  ##
vro_server
vro_port
vro_proxy
# "vro_auth" specifies the authentication type, "basic" or "vra" (VCF Automation)
vro_auth
vro_authHost                    # used only when "vro_auth=vra"
vro_authPort                    # used only when "vro_auth=vra"
vro_refresh_token               # used only when "vro_auth=vra"
vro_username
vro_password
vro_tenant                      # tenant or organization name; can be "null"

## Import configuration - used only for import operation                       ##
## (i.e. when "vro_import_packages=true")                                      ##
vro_enable_backup
vro_import_old_versions
# set "skip_vro_import_old_versions" to opposite value of "vro_import_old_versions"
skip_vro_import_old_versions
vro_import_configuration_attribute_values
vro_import_configuration_secure_attribute_values      
vro_force_import_latest_versions

#################################################################################
## Properties for VCF Automation VM Apps and Aria Automation Projects          ##
#################################################################################

## Operation flags. Note that each flag creates a separate session!            ##
vra_ng_import_packages          # imports project bundle content
vrang_delete_content            # cleans up project bundle content

## Connection configuration                                                    ##
vrang_host
vrang_port
vrang_csp_host                  # optional; set to the value of "vrang_host"
vrang_proxy_required
vrang_proxy                     # used when "vrang_proxy_required=true"
# "vrang_auth_with_refresh_token" specifies the authentication type
vrang_auth_with_refresh_token
vrang_refresh_token             # used when "vrang_auth_with_refresh_token=true"
vrang_username                  # used when "vrang_auth_with_refresh_token=false"
vrang_password                  # used when "vrang_auth_with_refresh_token=false"

## Content management configuration - used for import and clean up operations  ##
## (i.e. when "vra_ng_import_packages=true" or "vrang_delete_content=true")    ##
vrang_project_name
vrang_org_name

## Import configuration - used only for import operation                       ##
## (i.e. when "vra_ng_import_packages=true")                                   ##
vrang_import_overwrite_mode     # optional, can set value to "SKIP"
# "vrang_vro_integration_name" specifies the integration endpoint for Workflow
# Content Sources and other resources that point to that type of integration.
# If the property is missing, the default name "embedded-VRO" is used
vrang_vro_integration_name
# "vrang_import_timeout" sets the timeout (in milliseconds) for the
# synchronization of the content source and custom forms
vrang_import_timeout
# "vrang_data.collection.delay.seconds" sets the delay (wait time in seconds)
# for the data collection of the Orchestrator integration so the import of
# Automation content that depends on Orchestrator objects can succeed.
# When the property is provided, the script forces data collection for the
# integration and only if this fails, the script uses the delay.
vrang_data.collection.delay.seconds
vrang_bp_unrelease_versions

#################################################################################
## Properties for ABX Projects (VCF Automation VM Apps and Aria Automation)    ##
#################################################################################

## Operation flag                                                              ##
abx_import_packages             # imports project bundle content
# NOTE: When importing ABX content, the script unpacks all ABX modules and      #
# imports them iteratively                                                      #

## Configuration properties                                                    ##
# Use all properties from the "Connection configuration" group and the "Content
# management configuration" groups for VCF Automation VM Apps and Aria Automation
# There are no additional configuration properties for ABX content

#################################################################################
## Properties for Code Stream/Pipelines Projects (Aria Automation)             ##
#################################################################################
## This project type is supported only for Aria Automation (v8.x)              ##

## Operation flag                                                              ##
cs_import_packages              # imports project bundle content

## Configuration properties                                                    ##
# Use all properties from the "Connection configuration" group and the "Content
# management configuration" groups for VCF Automation VM Apps and Aria Automation
# together with the following property
vrang_cloud_proxy_name

#################################################################################
## Properties for VCF Automation All Apps Projects                             ##
#################################################################################

## Operation flags. Note that each flag creates a separate session!            ##
vcfaa_import_packages           # imports project bundle content
vcfa_delete_content             # cleans up project bundle content

## Connection configuration                                                    ##
vcfa_host
vcfa_port
vcfa_csp_host                   # optional; set to the value of "vcfa_host"
vcfa_proxy_required
vcfa_proxy                      # used when "vcfa_proxy_required=true"
# "vcfa_auth_with_refresh_token" specifies the authentication type
vcfa_auth_with_refresh_token
vcfa_refresh_token              # used when "vcfa_auth_with_refresh_token=true"
vcfa_username                   # used when "vcfa_auth_with_refresh_token=false"
vcfa_password                   # used when "vcfa_auth_with_refresh_token=false"

## Content management configuration - used for import and clean up operations  ##
## (i.e. when "vcfaa_import_packages=true" or "vcfa_delete_content=true")      ##
vcfa_project_name
vcfa_org_name

## Import configuration - used only for import operation                       ##
## (i.e. when "vra_ng_import_packages=true")                                   ##
vcfa_import_overwrite_mode      # optional, can set value to "SKIP"
# "vcfa_vro_integration_name" specifies the integration endpoint for workflow
# catalog item and other resources that point to that type of integration.
# If the property is missing, the default name "embedded-VRO" is used
vcfa_vro_integration_name
# "vcfa_import_timeout" sets the timeout (in milliseconds) for the
# synchronization of the content source and custom forms
vcfa_import_timeout
# "vcfa_data.collection.delay.seconds" sets the delay (wait time in seconds)
# for the data collection of the Orchestrator integration so the import of
# Automation content that depends on Orchestrator objects can succeed.
# When the property is provided, the script forces data collection for the
# integration and only if this fails, the script uses the delay.
vcfa_data.collection.delay.seconds
vcfa_bp_unrelease_versions

#################################################################################
## Properties for VCF Operations Projects                                      ##
#################################################################################

## Operation flag                                                              ##
vrops_import_packages           # imports project bundle content

## Connection configuration                                                    ##
# HTTP-REST connection configuration                                            #
vrops_httpHost
vrops_httpPort
vrops_restUser
vrops_restPassword
vrops_restAuthProvider
vrops_restAuthSource

# SSH connection configuration                                                  #
vrops_sshPort
vrops_sshUsername
vrops_sshPassword

## Import configuration                                                        ##
vrops_dashboardUser
vrops_importDashboardsForAllUsers

#################################################################################
## Properties for VCF Operations for Logs Projects                             ##
#################################################################################

## Operation flag                                                              ##
vrli_import_packages            # imports project bundle content

## Connection configuration                                                    ##
# VCF Operations for Logs connection configuration                              #
vrli_server
vrli_port
vrli_username
vrli_password
vrli_provider

# VCF Operations integration connection configuration                           #
vrli_vrops_server
vrli_vrops_server_port
vrli_vrops_server_user
vrli_vrops_server_password
vrli_vrops_server_auth_source

## Import configuration                                                        ##
vrli_package_import_overwrite_mode

#################################################################################
## Properties for VCD Projects                                                 ##
#################################################################################

## Operation flag                                                              ##
vcd_import_packages             # imports project bundle content
# vcd_delete_old_versions       # clean up operation for VCD is not supported

## Connection configuration                                                    ##
vcd_server
vcd_port
vcd_username
vcd_password

## Import configuration                                                        ##
vcd_import_old_versions
# set "skip_vcd_import_old_versions" to opposite value of "vcd_import_old_versions"
skip_vcd_import_old_versions
vcd_import_overwrite_mode

#################################################################################
## Properties for SSH Projects                                                 ##
#################################################################################

## Operation flag                                                              ##
ssh_import_packages             # imports project bundle content

## Connection configuration                                                    ##
ssh_server
ssh_port
ssh_username
ssh_password

## Import configuration                                                        ##
ssh_directory

#################################################################################
## Properties for Running an Orchestrator Workflow                             ##
#################################################################################

## Operation flag                                                              ##
vro_run_workflow                # runs existing Orchestrator workflow
# Note that this operation is also available for project bundles that do not    #
# have Orchestrator content                                                     #

## Connection configuration                                                    ##
## Use connection configurations for Orchestrator instance, either embedded    ##
## (i.e. VCF Automation VM Apps) or standalone/external                        ##

## Workflow run configurations                                                 ##
vro_run_workflow_id
vro_run_workflow_input_file_path
vro_run_workflow_output_file_path
vro_run_workflow_err_file_path
vro_run_workflow_timeout

#################################################################################

Logging configuration

The Installer tool supports detailed logging configuration for the execution of the script based on the Logback project.

When you generate a bundle with the -Pbundle-with-installer Maven profile, the Installer generates a logback.xml file inside the etc/ directory of the bundle and you can use this file to define the logging configurations for the script, such as severity, appenders, etc. For detailed information about the available configurations, see the official Logback documentation.

Example

Following is a sample listing of the logback.xml file with the logging configuration.

etc/logback.xml (Logging Configuration)

<configuration>
    <!-- Console appender for INFO logs -->
    <appender name="INFO_CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
        <filter class="ch.qos.logback.classic.filter.LevelFilter">
            <level>INFO</level>
            <onMatch>ACCEPT</onMatch>
            <onMismatch>DENY</onMismatch>
        </filter>
        <encoder>
            <pattern>%d{yyyy-MM-dd HH:mm:ss} [%thread] %-5level %logger{36} - %msg%n</pattern>
        </encoder>
    </appender>

    <!-- Console appender for WARN logs -->
    <appender name="WARN_CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
        <filter class="ch.qos.logback.classic.filter.LevelFilter">
            <level>WARN</level>
            <onMatch>ACCEPT</onMatch>
            <onMismatch>DENY</onMismatch>
        </filter>
        <encoder>
            <pattern>%d{yyyy-MM-dd HH:mm:ss} [%thread] %-5level %logger{36} - %msg%n</pattern>
        </encoder>
    </appender>

    <!-- Console appender for DEBUG logs -->
    <appender name="DEBUG_CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
        <filter class="ch.qos.logback.classic.filter.LevelFilter">
            <level>DEBUG</level>
            <onMatch>ACCEPT</onMatch>
            <onMismatch>DENY</onMismatch>
        </filter>
        <encoder>
            <pattern>%d{yyyy-MM-dd HH:mm:ss} [%thread] %-5level %logger{36} - %msg%n</pattern>
        </encoder>
    </appender>

    <!-- Root logger with level INFO -->
    <root level="INFO">
        <appender-ref ref="INFO_CONSOLE" />
        <appender-ref ref="WARN_CONSOLE" />
        <appender-ref ref="DEBUG_CONSOLE" />
    </root>

    <!-- Uncomment the below tag if you need to enable DEBUG logging as well -->
    <!--
    <root level="DEBUG">
        <appender-ref ref="INFO_CONSOLE" />
        <appender-ref ref="WARN_CONSOLE" />
        <appender-ref ref="DEBUG_CONSOLE" />
    </root>
    -->
</configuration>

Run Workflow

You can use the Installer to run any existing Orchestrator workflow automatically at the end of the import (and clean up) process. You can provide the necessary values for the input parameters of the Workflow in a file in JSON or YAML format. Additionally, the script expects you to specify the paths to two more files, one for writing the standard output of the workflow (again in JSON or YAML format) and one for writing the error output (if applicable).

A common use case for this operation is the running of an installation workflow that prepares and stores the configurations and objects required for using the solution from your bundle projects, such as managing HTTP-REST Hosts and vCenter SDK Connections in the Orchestrator inventory, storing credentials as Secured Strings and other runtime configurations in Orchestrator configuration elements, etc.

Note that the operation for running an Orchestrator workflow is available for all project bundles, even the ones that do not contain any of the Orchestrator project types.

Supported Input Value Types for Input Parameters

You can use the following value types for the input parameters of an Orchestrator workflow. The Installer sends all other types as parameters of type string.

• number
• boolean
• string
• Array/string

Sample File with Workflow Input Parameter Values

Following is a sample listing (in both YAML and JSON format) of a file with inputs for a workflow with four input parameters.

Expand for details of the workflow input parameters and how they are processed

Following is a list of the input parameters of the workflow with details of how they are defined in the Orchestrator workflow, what are their data types in the sample input file, and how the Installer passes them to the Orchestrator workflow.

Parameter Name	Workflow Definition Data Type	Input File Data Type	Actual Input Data Type
jsonString	string	(JSON) object	string
tags	Array/string	Array/string	Array/string
blacklist	Array/string	Array/string	Array/string
environment	string	null	null

YAMLJSON

jsonString:
  scheduled-snapshot:
    evaluationTime: "18:00:00"
    retrainedSnapshotCount: 2
    manageSnapshotTimeoutMinutes: 120
  vsphere:
    authentication:
      - hostname: "vc-l-01a.corp.internal"
        port: 443
        domain: "vsphere.local"
        username: "administrator"
        password: "VMware1!VMware1!"
        apiCompatibilityVersion: 702
        createSdkConnection: true
        ignoreCertificateWarnings: true
        sessionPerUser: false
  vra:
    authentication:
      hostname: vcfa.corp.internal
      port: 443
      authHostname: vcfa.corp.internal
      authPort: 443
      username: admin
      password: VMware1!VMware1!
      domain: vm-apps
      projectName: Development
      orgName: vm-apps
      isPersistent: false
tags: ["bak.scheduled-snapshot", "vsphere.authentication", "vra.authentication"]
blacklist: []
environment: null

{
  "jsonString": {
    "scheduled-snapshot": {
      "evaluationTime": "18:00:00",
      "retrainedSnapshotCount": 2,
      "manageSnapshotTimeoutMinutes": 120
    },
    "vsphere": {
      "authentication": [
        {
          "hostname": "vc-l-01a.corp.internal",
          "port": 443,
          "domain": "vsphere.local",
          "username": "administrator",
          "password": "VMware1!VMware1!",
          "apiCompatibilityVersion": 702,
          "createSdkConnection": true,
          "ignoreCertificateWarnings": true,
          "sessionPerUser": false
        }
      ]
    },
    "vra": {
      "authentication": {
        "hostname": "vcfa.corp.internal",
        "port": 443,
        "authHostname": "vcfa.corp.internal",
        "authPort": 443,
        "username": "admin",
        "password": "VMware1!VMware1!",
        "domain": "vm-apps",
        "projectName": "Development",
        "orgName": "vm-apps",
        "isPersistent": false
      }
    }
  },
  "tags": [
    "bak.scheduled-snapshot",
    "vsphere.authentication",
    "vra.authentication"
  ],
  "blacklist": [],
  "environment": null
}

Configuration Properties for Running a Workflow

When you want to run an Orchestrator with the Installer tool, you need to provide the following properties together with the properties that specify the connection configurations for the Orchestrator host (either embedded or standalone/external).

Note

Both YAML and JSON are supported file formats for Workflow input and output files.

# Flag for starting the operation for running a workflow. If the value is set to `false`, the script skips all the other properties.
vro_run_workflow=true

# UUID of the existing workflow in the Orchestrator instance
vro_run_workflow_id=1490692845582937823496790834565483423
# Path to the JSON or YAML file that contains the inputs for the Workflow. Each root attribute of this file
# must have the name of an input parameter of the target workflow
vro_run_workflow_input_file_path=./install.json
# Path to the JSON or YAML file in which the script stores the workflow execution outputs
vro_run_workflow_output_file_path=./output.json 
# Path to the file in which the script writes any errors encountered during the workflow execution
vro_run_workflow_err_file_path=./workflow.err
# workflow execution timeout
vro_run_workflow_timeout=300