This chapter guides you through the installation of the VMClarity backend and the CLI, and shows you the most common tasks that you can perform with VMClarity.
This is the multi-page printable view of this section. Click here to print.
Getting started
- 1: Deploy on AWS
- 2: Deploy on Azure
- 3: Deploy on Docker
- 4: Deploy on GCP
- 5: Deploy on Kubernetes
- 6: First tasks on the UI
1 - Deploy on AWS
An AWS CloudFormation template is provided for quick deployment of the VMClarity environment.
Note: To avoid extra costs (cross-region snapshots), you may want to deploy the VMClarity AWS CloudFormation template in the same region where the majority of the VMs are that you want to scan with VMClarity.
The following figure shows the basic AWS resources that the VMClarity CloudFormation template creates:
-
a VPC with a public and private subnet, and
-
an AWS Internet Gateway (IGW) and NAT Gateway (NGW) into the VPC.
The public subnet (VmClarityServerSubnet
) hosts the VMClarity Server (VmClarityServer
) EC2 instance. The VMClarity server houses the scanning configuration, the UI, and other control components. The EC2 instance is assigned an external IPv4 address (EIP) for SSH and web UI access.
The private subnet (VmClarityScannerSubnet
) hosts the VM snapshot instances (EC2) that are scanned for security vulnerabilities.
Prerequisites
- Have an AWS account.
- Create an EC2 key pair.
Deployment steps
To deploy the VMClarity AWS CloudFormation Stack, you can:
- click this quick-create link to navigate directly to the AWS CloudFormation console and jump to the wizard instructions, or
- complete the following steps.
-
Download the latest VMClarity release.
wget https://github.com/openclarity/vmclarity/releases/download/v1.1.1/aws-cloudformation-v1.1.1.tar.gz
Alternatively, copy the AWS CloudFormation template file from the project repository to deploy the latest development code and skip the next step.
-
Create a new directory and extract the files.
mkdir aws-cloudformation-v1.1.1 tar -xvzf aws-cloudformation-v1.1.1.tar.gz -C aws-cloudformation-v1.1.1
-
Log in to the AWS CloudFormation console and go to the AWS CloudFormation Stacks section, then select Create Stack > With New Resources (standard).
-
Check Template is ready and Upload a template file, then click Upload a template file/Choose file and upload the previously downloaded CFN template file.
-
In the VMClarity CloudFormation Stack wizard, set the following:
- Enter a name for the stack.
- Select the InstanceType (defaults to
t2.large
for the VMClarity Server, and the scanner VMs). - Specify the SSH key for the EC2 instance in the KeyName field. You will need this key to connect to VMClarity.
- Adjust SSHLocation according to your policies.
- Do not change AdvancedConfiguration, unless you are building from a custom registry.
- Click NEXT.
- (Optional) Add tags as needed for your environment. You can use the defaults unless you need to adjust for your own policies.
- Click NEXT, then scroll to the bottom of the screen, and check I acknowledge….
- Click SUBMIT.
-
Once the stack is deployed successfully, copy the VMClarity SSH address from the Outputs tab.
-
Open an SSH tunnel to VMClarity the server
ssh -N -L 8080:localhost:80 -i "<Path to the SSH key specified during install>" ubuntu@<VmClarity SSH Address copied during install>
-
Open the VMClarity UI in your browser at http://localhost:8080/. The dashboard opens.
-
(Optional) If needed, you can access the API athttp://localhost:8080/api. For details on the API, see API Reference.
Next steps
Complete the First tasks on the UI.
2 - Deploy on Azure
Prerequisites
-
Have an Azure subscription.
-
Create an SSH public key for Linux. Please follow these instructions for Linux and Mac users or these for Windows users. Once you have an RSA private key, convert it to an SSH2 public key with:
ssh-keygen -e -f ~/.ssh/id_rsa.pub > ~/.ssh/id_rsa2.pub
Deployment steps
-
Click here to deploy VMClarity’s custom template.
-
Fill out the required Project details and Instance details in the Basics tab.
You can set the following parameters:
Parameter Required Description Subscription True Azure subscription where resources will be billed. Region False Azure region where resources will be deployed. VMClarity Deploy Postfix True Postfix for Azure resource group name (e.g. vmclarity-<postfix>
).VMClarity Server SSH Username True SSH Username for the VMClarity Server Virtual Machine. VMClarity Server SSH Public Key True SSH Public Key for the VMClarity Server Virtual Machine. Paste the contents of ~/.ssh/id_rsa2.pub
here.VMClarity Server VM Size True The size of the VMClarity Server Virtual Machine. VMClarity Scanner VMs Size True The size of the VMClarity Scanner Virtual Machines. Security Type False Security Type of the VMClarity Server Virtual Machine, e.g. TrustedLaunch
(default) orStandard
. -
(Optional) In the Advanced tab, modify the Container Image for each service if a specific VMClarity version is required. Then, select the delete policy and the database.
Parameter Required Description Service Container Image True Docker Container Image to use for each service. Asset Scan Delete Policy True Delete Policy for resources created when performing an asset scan, e.g. Always
,OnSuccess
orNever
.Database To Use True Database type to use, e.g. SQLite
,PostgreSQL
orExternal PostgreSQL
. -
Click Review + create to create the deployment.
-
Once the deployment is completed successfully, copy the VMClarity SSH address from the Outputs tab.
-
Open an SSH tunnel to VMClarity the server
ssh -N -L 8080:localhost:80 -i "<Path to the SSH key specified during install>" ubuntu@<VmClarity SSH Address copied during install>
-
Open the VMClarity UI in your browser at http://localhost:8080/. The dashboard opens.
-
(Optional) If needed, you can access the API athttp://localhost:8080/api. For details on the API, see API Reference.
Next steps
Complete the First tasks on the UI.
3 - Deploy on Docker
Prerequisites
- Install Docker.
Deployment steps
To run VMClarity in Docker on a local machine, complete the following steps.
-
Download the latest VMClarity release.
wget https://github.com/openclarity/vmclarity/releases/download/v1.1.1/docker-compose-v1.1.1.tar.gz
-
Create a new directory, extract the files and navigate to the directory.
mkdir docker-compose-v1.1.1 tar -xvzf docker-compose-v1.1.1.tar.gz -C docker-compose-v1.1.1 cd docker-compose-v1.1.1
-
Start every control plane element with the docker compose file.
docker compose --project-name vmclarity --file docker-compose.yml up -d --wait --remove-orphans
The output should be similar to:
[+] Running 14/14 ⠿ Network vmclarity Created 0.2s ⠿ Volume "vmclarity_grype-server-db" Created 0.0s ⠿ Volume "vmclarity_apiserver-db-data" Created 0.0s ⠿ Container vmclarity-orchestrator-1 Healthy 69.7s ⠿ Container vmclarity-yara-rule-server-1 Healthy 17.6s ⠿ Container vmclarity-exploit-db-server-1 Healthy 17.7s ⠿ Container vmclarity-swagger-ui-1 Healthy 7.8s ⠿ Container vmclarity-trivy-server-1 Healthy 26.7s ⠿ Container vmclarity-uibackend-1 Healthy 17.6s ⠿ Container vmclarity-ui-1 Healthy 7.7s ⠿ Container vmclarity-freshclam-mirror-1 Healthy 7.8s ⠿ Container vmclarity-grype-server-1 Healthy 37.3s ⠿ Container vmclarity-gateway-1 Healthy 7.7s ⠿ Container vmclarity-apiserver-1 Healthy 17.7s
Please note that the
image_override.env
file enables you to use the images you build yourself. You can override parameters in thedocker-compose.yml
by passing a custom env file to thedocker compose up
command via the--env-file
flag. The/installation/docker/image_override.env
file contains an example overriding all the container images. -
Check the running containers in the Docker desktop.
-
Access the VMClarity UI. Navigate to http://localhost:8080/ in your browser.
Next steps
Complete the First tasks on the UI.
Clean up steps
-
After you’ve finished your tasks, stop the running containers.
docker compose --project-name vmclarity --file docker-compose.yml down --remove-orphans
4 - Deploy on GCP
Prerequisites
- You can install VMClarity using the CLI, so you have to have gcloud on your computer available beforehand. For details on installing and configuring gcloud, see the official installation guide.
- If you have already installed VMClarity before and want to reinstall it, you have to manually restore deleted roles that were created during the previous installation.
Deployment steps
To install VMClarity on Google Cloud Platform (GCP), complete the following steps.
-
Download the newest GCP deployment release from GitHub and extract it to any location.
wget https://github.com/openclarity/vmclarity/releases/download/v1.1.1/gcp-deployment-v1.1.1.tar.gz
-
Create a new directory, extract the files and navigate to the directory.
mkdir gcp-deployment-v1.1.1 tar -xvzf gcp-deployment-v1.1.1.tar.gz -C gcp-deployment-v1.1.1 cd gcp-deployment-v1.1.1
-
Copy the example configuration file and rename it.
cp vmclarity-config.example.yaml vmclarity-config.yaml
-
The following table contains all the fields that can be set in the
vmclarity-config.yaml
file. You have to set at least the required ones.Field Required Default Description zone
yes The Zone to locate the VMClarity server. machineType
yes The machine type for the VMClarity server. region
yes The region to locate VMClarity. scannerMachineType
e2-standard-2
Machine type to use for the Scanner instances. scannerSourceImage
projects/ubuntu-os-cloud/global/images/ubuntu-2204-jammy-v20230630
Source image to use for the Scanner instances. databaseToUse
SQLite
The database that VMClarity should use. apiserverContainerImage
ghcr.io/openclarity/vmclarity-apiserver:1.1.1
The container image to use for the apiserver. orchestratorContainerImage
ghcr.io/openclarity/vmclarity-orchestrator:1.1.1
The container image to use for the orchestrator. uiContainerImage
ghcr.io/openclarity/vmclarity-ui:1.1.1
The container image to use for the ui. uibackendContainerImage
ghcr.io/openclarity/vmclarity-ui-backend:1.1.1
The container image to use for the uibackend. scannerContainerImage
ghcr.io/openclarity/vmclarity-cli:1.1.1
The container image to use for the scanner. exploitDBServerContainerImage
ghcr.io/openclarity/exploit-db-server:v0.2.4
The container image to use for the exploit db server. trivyServerContainerImage
docker.io/aquasec/trivy:0.41.0
The container image to use for the trivy server. grypeServerContainerImage
ghcr.io/openclarity/grype-server:v0.7.0
The container image to use for the grype server. freshclamMirrorContainerImage
ghcr.io/openclarity/freshclam-mirror:v0.2.0
The container image to use for the fresh clam mirror server. postgresqlContainerImage
docker.io/bitnami/postgresql:12.14.0-debian-11-r28
The container image to use for the postgresql server. assetScanDeletePolicy
Always
When asset scans should be cleaned up after scanning. postgresDBPassword
Postgres DB password. Only required if DatabaseToUse is Postgresql. externalDBName
DB to use in the external DB. Only required if DatabaseToUse is External. externalDBUsername
Username for the external DB. Only required if the DatabaseToUse is External. externalDBPassword
Password for the external DB. Only required if the DatabaseToUse is External. externalDBHost
Hostname or IP for the external DB. Only required if the DatabaseToUse is External. externalDBPort
Port for the external DB. Only required if the DatabaseToUse is External. -
Deploy VMClarity using gcloud deployment-manager.
gcloud deployment-manager deployments create <vmclarity deployment name> --config vmclarity-config.yaml
-
Open an SSH tunnel to the VMClarity server with gcloud. For further information on how to create an SSH connection with gcloud to one of your instances check the official page.
gcloud compute ssh --project=<project id> --zone=<zone name> <name of your VM> -- -NL 8080:localhost:80
-
Open the VMClarity UI in your browser at http://localhost:8080/. The dashboard opens.
-
(Optional) If needed, you can access the API athttp://localhost:8080/api. For details on the API, see API Reference.
Next steps
Complete the First tasks on the UI.
Uninstall VMClarity
-
You can uninstall VMClarity using the gcloud manager.
gcloud deployment-manager deployments delete <vmclarity deployment name>
Restore deleted roles
-
On the IAM & Admin page on GCP, open the Roles tab, then search for VMClarity in the filter input.
-
Now manually undelete the Discoverer Snapshotter and Scanner roles to set their statuses from Deleted to Enabled.
5 - Deploy on Kubernetes
Prerequisites
- Install a tool to run local Kubernetes clusters. Here, Kind is used as the default option for creating a local cluster.
- Helm to install VMClarity.
Deployment steps
To deploy VMClarity to your Kubernetes cluster, complete the following steps.
-
Create a Kubernetes cluster.
kind create cluster --name vmclarity-k8s
-
Ensure the Kubernetes cluster is up and running. If you’re using kind, you can check the status of your clusters with the following command:
kind get clusters
-
Use Helm to install VMClarity. Run the following command:
helm install vmclarity oci://ghcr.io/openclarity/charts/vmclarity --version 1.1.1 \ --namespace vmclarity --create-namespace \ --set orchestrator.provider=kubernetes \ --set orchestrator.serviceAccount.automountServiceAccountToken=true
-
Verify that all the VMClarity pods have been successfully deployed by executing the following command:
kubectl get pods -n vmclarity
-
Wait until all pods are in the
Running
state or have completed their initialization. -
Once the pods are ready, start port forwarding to access the VMClarity gateway service. Use the following command to forward traffic from your local machine to the cluster:
kubectl port-forward -n vmclarity service/vmclarity-gateway 8080:80
-
Access the VMClarity UI by navigating to http://localhost:8080/ in your web browser.
Next steps
Complete the First tasks on the UI.
Clean up steps
-
Uninstall VMClarity with Helm. Run the following command:
helm uninstall vmclarity --namespace vmclarity
-
Delete the Kubernetes cluster.
kind delete clusters vmclarity-k8s
6 - First tasks on the UI
Configure your first scan
-
Open the VMClarity UI in your browser at http://localhost:8080/. The dashboard opens.
-
(Optional) If needed, you can access the API athttp://localhost:8080/api. For details on the API, see API Reference.
-
Click on the Scans icon. In the Scans window, you can create a new scan configuration.
-
Click New scan configuration.
-
Follow the steps of the New scan config wizard to name the scan, and identify the AWS scope (region, VPC, security groups, etc). The following example shows the AWS us-east-2 region, a specific VPC, and the
vmclarity-demo-vm
EC2 -
Enable the scan types you want to perform.
-
Select the time and/or frequency of the scans. To run the scan immediately, select Now.
-
Click Save. The new scan appears on the Scan Configurations tab.
-
Once a scan is finished, you can browse around the various VMClarity UI features and investigate the security scan reports.