Skip to content

VCF Operations

Overview

Field Value
Name vrops
Archetype Group ID com.vmware.pscoe.vrops.archetypes
Archetype Artifact ID package-vrops-archetype
Package extension vrops
Product compatibility VCF Operations (9.x)
Aria Operations (8.x)

VCF Ops projects are called vrops projects in Build Tools for VMware Aria. The project type is a representation of VCF Ops content into human friendly format saved into different file types - JSON, XML, properties, ZIP. The project consist of content descriptor and content container.

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

Supported Content

  • view
  • dashboard
  • alert-definition
  • symptom-definition
  • policy
  • default-policy
  • recommendation
  • super-metric
  • metric-config
  • report
  • custom-group

Create New VCF Ops Project

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

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

mvn archetype:generate \
  -DinteractiveMode=false \
  -DarchetypeGroupId=com.vmware.pscoe.vrops.archetypes \
  -DarchetypeArtifactId=package-vrops-archetype \
  -DarchetypeVersion=4.25.0 \
  -DgroupId=com.company.department \
  -DartifactId=vrops-project

mvn archetype:generate `
  -DinteractiveMode=false `
  -DarchetypeGroupId=com.vmware.pscoe.vrops.archetypes `
  -DarchetypeArtifactId=package-vrops-archetype `
  -DarchetypeVersion=4.25.0 `
  -DgroupId=com.company.department `
  -DartifactId=vrops-project

mvn archetype:generate ^
  -DinteractiveMode=false ^
  -DarchetypeGroupId=com.vmware.pscoe.vrops.archetypes ^
  -DarchetypeArtifactId=package-vrops-archetype ^
  -DarchetypeVersion=4.25.0 ^
  -DgroupId=com.company.department ^
  -DartifactId=vrops-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 Operations projects, make sure to set the value to com.vmware.pscoe.vrops.archetypes.
  • The archetypeArtifactId property defines the artifact ID of the archetype (project template) that you want to use for the project. For VCF Operations projects, make sure to set the value to package-vrops-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 result of this command will produce the following project file structure:

operations
├── README.md
├── content.yaml
├── pom.xml
├── release.sh
└── src
    └── main
        └── resources
            └── alert_definitions
                └── Cluster is disbalanced.json
            └── custom_groups
                └── vCenter Folder Tag.json
            └── dashboards
                └── metadata
                    └── dashboardGroupActivationMetadata.vrops.json
                    └── dashboardSharingMetadata.vrops.json
                    └── dashboardUserActivationMetadata.vrops.json
                └── resources
                    └── resources.properties
                └── Assess Cost.json
            └── metricconfigs
                └── vSAN Savings
            └── policies
                └── policiesMetadata.vrops.json
                └── Policy for Virtual Machines - Risk Profile 1.zip
            └── recommendations
                └── Bring the VMware Cloud Foundation Operations Node back online.json
            └── reports
                └── Cluster Cost Report
                    └── resources
                        └── resources.properties
                    └── content.xml
            └── supermetrics
                └── Group CPU Average.json
            └── symptom_definitions
                └── Cloud Proxy is down.json
            └── views
                └── resources
                    └── content.properties
                └── Cluster Basic Inventory.xml

Content

Content Descriptor

Content Descriptor is implemented by content.yaml file with the following structure:

view:
dashboard:
alert-definition:
symptom-definition:
policy:
default-policy:
recommendation:
super-metric:
metric-config:
report:
custom-group:

Note

VCF Ops Project supports only content types outlined into Content Descriptor.

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

Note

All object types are list of string values except for default-policy which is a single policy name string.

Note

Due to limitation of the VCF Ops CLI the import / export of report definitions is not currently supported.

Note

The import of the symptoms definitions defined for all the adapter types is not currently supported.

Content Filtering

Contents are managed by different rules.

Import Rules for content types
  • Only objects explicitly defined in the content.yaml are imported.
  • default-policy does not actually import a policy - it only sets an existing policy with the given name as default.
Export Rules for content types
  • Only objects explicitly defined in the content.yaml are exported.
  • default-policy is not exported. If you want to export the policy set as default it needs to be added to the policy list.

Example

Content 
view:
  - Cluster Basic Inventory
dashboard:
  - Assess Cost
alert-definition:
  - Cluster is disbalanced
symptom-definition:
  - Automation service is down
  - Cloud Proxy is down
recommendation:
  - Bring the VMware Cloud Foundation Operations Node back online
super-metric:
  - Group CPU Average
report:
  - Cluster Cost Report
metric-config:
  - vSAN Savings
custom-group:
  - VCF World
policy:
  - Policy for Virtual Machines - Risk Profile 1
default-policy: Default Policy

Environment Connection Parameters

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

<!-- (1)! -->
<profile>
    <!--    ..... OTHER DIRECTIVES .....  -->
    <vrops.host>flt-ops01a.corp.internal</vrops.host>
    <vrops.port>443</vrops.port>
    <vrops.sshPort>22</vrops.sshPort>
    <vrops.username>admin</vrops.username>
    <vrops.password>someSecurePassword</vrops.password>
    <vrops.restUser>admin</vrops.restUser>
    <vrops.restPassword>someSecurePassword</vrops.restPassword>
    <vrops.dashboardUser>admin</vrops.dashboardUser>
    <vrops.importDashboardsForAllUsers>true|false</vrops.importDashboardsForAllUsers>
    <vrops.restAuthSource>local</vrops.restAuthSource>
    <vrops.restAuthProvider>BASIC|AUTH_N</vrops.restAuthProvider>
</profile>
  1. The location of the settings.xml file for MacOS is ~/.m2 and C:\Users\username\\.m2 for Windows.

Note

Some VCF Ops content is managed via in-guest CLI commands instead of REST API which requires credentials for REST API (vrops.restUser and vrops.password) and SSH communication (vrops.username and vrops.password) with sufficient privileges.

  • vrops.dashboardUser - User account to which to assign the ownership of a dashboard when importing it.

  • vrops.importDashboardsForAllUsers - If parameter is missing or set to true, the dashboards are imported to all users. If parameter is set to false, the dashboards are imported only for the user specified in vrops.dashboardUser.

  • vrops.restAuthSource - Authentication source used for acquiring a token for REST API communication.

  • vrops.restAuthProvider - Defines the type of authentication used for REST API communication.

    • Supported values: BASIC, AUTH_N (token based authentication - supported since version 2.8.0).
    • Default value: AUTH_N.

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

mvn vrops:pull -Ptarget-env

Operations

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 output of the command will result in com.company.department.project.type-1.0.0-SNAPSHOT.vrops file generated in the target folder of the project.

Bundle the Project

This section describes the operation for bundling the project into an installation bundle (ZIP file).

Overview

A Maven profile 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

The command produces a ZIP file (installation bundle) with a name that follows the pattern <project.groupId>.<project.artifactId>-<project.version>-bundle.zip, where the values for the placeholders are retrieved from the respective properties of the project pom.xml file.

Following is a sample listing of the structure of the installation bundle ZIP file for the VCF Operations project in which the project version is 0.1.0-SNAPSHOT.

Sample structure of an installation bundle
com.company.department.vrops-project-0.1.0-SNAPSHOT-bundle.zip
└── bin
    └── installer
    └── installer.bat
└── etc
    └── logback.xml
└── repo/
└── vrops 
    └── com.company.department.vrops-project-0.1.0-SNAPSHOT.vrops

Following is a list of the directories in the installation bundle with a short description of their contents.

  • The bin directory contains the installer script (CLI tool) for importing the solution components from the bundle in two formats, Bash (for Linux/Mac OS) and .bat (for Windows). For more information about using the CLI tool, see the documentation of the Installer.
  • The etc directory contains configuration files of the Java binaries for the installer script, such as the logging configurations in the logback.xml file. For more information about the logging configuration file, see Logging Configuration.
  • The repo directory contains the Java binaries for the installer script.

  • The vrops directory contains the project file(s) with the components that you can import to the remote server.

    Note

    Based on your configurations and dependencies, you can have multiple Maven modules in a single installation bundle. So in addition to the vrops directory for the VCF Operations project, you can have additional modules for projects of other types.

Bundle Additional Files

By default, the -Pbundle-with-installer Maven profile packages only the files and directories that are strictly necessary for importing the project components to the target system (as shown in the Sample structure of an installation bundle listing). However, it also allows you to package additional files or directories from your repository as part of the bundle ZIP and copy them to the root of the installation bundle.

You can use such additional files and directories to bundle supplementary version-controlled content (such as integration tests, files with sample inputs for Orchestrator workflows, properties files for the installer script, Ansible playbooks, etc.) in a single deliverable file.

You specify the additional content that you want to add to the bundle in the <properties> element of the pom.xml file of the project. You can use up to nine <installer.included.item*> elements (in which * stands for a number between 1 and 9) to specify the paths to the files and directories that you want to include.

For example, the following sample configuration of a pom.xml file includes a file with the name environment.properties as item1 and the contents of the integration-tests/ directory as item2.

Sample pom.xml file
<!-- Parameters for including additional files in installation bundles in the pom.xml file --> 
<project>
    ...
    <properties>
        <installer.included.item1>environment.properties</installer.included.item1>
        <installer.included.item2>integration-tests/**</installer.included.item2>
    </properties>
    ...
</project>

Pull Content

Overview

When working on a VCF Ops project, you mainly make changes on a live server using the VCF Ops UI 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, the a custom maven goal vrops: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 vrops:pull -Ptarget-env

Note

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

Wildcard Support

The content descriptor supports wildcard for most of the asset types. This means that you can specify a wildcard (*) symbol in the asset names defined in the content.yaml file exporting all assets matching the wildcard expression. E.g.

report:
  - "*reports"

Note

Due to limitation of VCF Ops REST API wildcard is currently NOT supported for the dashboard and metric-config asset types.

Note

If you specify a wildcard in the asset name defined in the content.yamlfile, it needs to be enclosed with quotes ("). You can also enclose the asset name with quotes (") in the content.yaml file, even if you specify it with its full name.

Push Content

Overview

Maven goal for deploying the solution to target environment.

Usage

mvn clean package vrops:push -Ptarget-env
Include Dependencies

By default, the vrealize: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 vrealize: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).

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>
  1. 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 vrealize: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 vrealize:push -Ptarget-env -Dvrealize.ssl.ignore.hostname

Clean Up Content

The cleaning up of project content from a target environment is not supported for the VCF Operations project. For details, see the Project Type Support for Content Clean Up.

Project Type Support for Content Clean Up

The following table provides details about the support of the cleaning up of project content via the vrealize: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>