Virga

Virga tests your Cloud resources.

What is Virga

In meteorology, Virga is an observable streak or shaft of precipitation falling from a cloud that evaporates or
sublimates before reaching the ground. Wikipedia

This piece of software is not about a weather phenomenon.

Virga is a tool for analysing your Cloud infrastructure before the rain catastrophically reaches the ground.

This project is still in pre-alpha

There are many things still missing:

• the documentation needs to be completed
• the definition files are just a draft for testing purposes

Providers supported

At the moment only AWS.

Requirements

• Python
• PyYAML
• JMESPath

Specific for AWS

• an AWS working account
• boto3

Quick start

1. Install Virga pip install virga
2. Create and edit the file tests.yaml
3. Launch the command virga-asserts -p aws -t tests.yaml

tests.yaml is a test file.

Configuration files

See This project is still in pre-alpha

There are two types of configuration files.

The definitions (see docs/definition_file.md) are specific to the provider and define
the way we want to filter the resources to check. These files are unlikely to be changed.

The tests are the actual tests we want to implement.

Test files

Let’s start with an use case: you want to test that the subnet with the id subnet-0123456789 has:

• the CIDR block equals to 10.0.0.0/24
• the tag environment has value staging
• the tag Name has value my-subnet

and then you want to know if the EC2 instances with the tag name starting with the value my-app are in the subnet
my-subnet.

subnets:
- id: subnet-0123456789
  assertions:
  - CidrBlock=='10.0.0.0/24'
  - Tags[?Key=='environment' && Value=='staging']
  - Tags[?Key=='Name' && Value=='my-subnet']
instances:
- name: my-app-*
  assertions:
  - SubnetId=="_lookup('subnets', 'name', 'my-subnet')"

The keys id and name are identifiers declared in the definitions file.

The assertions are the actual tests: each item of the list represents a condition to verify using
JMESPath.

In the assertions above there is a spurious case

SubnetId=="_lookup('subnets', 'name', 'my-subnet')"

_lookup is not a standard JMESPath construct but a Virga function (see _lookup function).

_lookup function

The _lookup function filters a single resource returning the ID.

In the example above instead of declaring the equality

SubnetId=="subnet-0123456789"

we have filtered the subnet by the tag:Name.

The argument passed to the function are:

• the resource type
• the identifier (eg. name)
• the value to search

If no result is found, the test fails.

virga-asserts options

Following the list of options of virga-asserts

usage: virga-asserts [-h] -p {aws} [-t TESTFILE [TESTFILE ...]] [-d DEFINITIONS] [-l LOGFILE] [-s] [-o OUTPUT] [--debug]
optional arguments:
  -h, --help            show this help message and exit
  -p {aws}, --provider {aws}
                        provider
  -t TESTFILE [TESTFILE ...], --testfile TESTFILE [TESTFILE ...]
                        test file
  -d DEFINITIONS, --definitions DEFINITIONS
                        custom definitions path
  -l LOGFILE, --logfile LOGFILE
                        redirect the output to a log file
  -s, --silent          do not output results
  -o OUTPUT, --output OUTPUT
                        save the resource info into the specified directory
  --debug               show debug

The command requires a valid provider and at least one test file (see Test files).

Sample generation

Virga comes with a tool for generating test files out of resources.

virga-samples requires:

• a valid provider
• the ID of the resource to exemplify

Example

The command virga-assert -p aws -s instances -r i-0123456789 will generate a valid test file for the resource
i-0123456789.

Options

usage: virga-samples [-h] -p PROVIDER -s SECTION -r RESOURCE [-d DEFINITIONS]
optional arguments:
  -h, --help            show this help message and exit
  -p PROVIDER, --provider PROVIDER
                        provider
  -s SECTION, --section SECTION
                        section
  -r RESOURCE, --resource RESOURCE
                        resource id
  -d DEFINITIONS, --definitions DEFINITIONS
                        definitions path

FAQ

See This project is still in pre-alpha

AWS credentials settings

Even if AWS requires appropriate credentials, Virga does not explicitly requires any
credentials setting.

There are several ways to set AWS credentials, if you have some doubts about it, we suggest you to spend some time
studying this topic before using AWS.

A quick way is using AWS CLI

pip install awscli --upgrade --user
aws configure

For more information refer to boto3 documentation.

Why my test is failing

See This project is still in pre-alpha

Resource mapping

• List of AWS resources

Advanced topics

• Definition file
• How to build a custom provider