Usage

img-proof provides two entry points, a command line interface and a controller class that can be used directly from Python code.

CLI

The command line interface is written using the Click package. The API documentation can be found at API.

Verbosity

As seen in the example the CLI output verbosity can be controlled via options:

--debug

Display debug level logging to console. Including full stack trace if there is an exception.

--verbose

(Default) Display logging info to console.

--quiet

Silence logging information on test run.

Instance Options

The instance-option arguments provide a way to enable instance options that will be activated when launching instances. This is a multi-option value. To provide multiple options in a single command split each option into a separate argument. An example for tests in Google:

img-proof test gcp ... \
  --instance-option SEV_SNP_CAPABLE \
  --instance-option GVNIC

The Google instance options are the guest os feature flags. See https://cloud.google.com/compute/docs/images/create-custom#guest-os-features for more details. As seen above an example for Google looks like:

img-proof test gcp ... \
  --instance-option SEV_SNP_CAPABLE

The Amazon options are the different options available when running the run instances command. These can be found at https://docs.aws.amazon.com/cli/latest/reference/ec2/run-instances.html.

To provide an instance option for testing in Amazon the type of option and the key/val are provided in the following format: “OptType=key.val”. Example usage to enable SEV SNP looks like:

img-proof test ec2 ... \
  --instance-option CpuOptions=AmdSevSnp.enabled

Where the key is derived from the CLI reference page provided above. In this case the AWS CLI option is –cpu-options which becomes “CpuOptions”. “AmdSevSnp” is the key and the value is “enabled”.

Cleanup

By default the instance will be terminated if all tests pass. If a test fails the instance will remain running for debugging purposes. This behavior can be configured with the --cleanup and --no-cleanup flags.

--cleanup

Instance will always be terminated.

--no-cleanup

Instance will always remain running.

ANSI Style

By default the command line output will be colored. To disable color output use the --no-color option.

Early Exit

The early exit option will stop the test run on the first failure. --early-exit is passed to Pytest as -x.

See Pytest docs for more info.

Requirements and external test injection

Using the --inject option; packages, archives and files can be injected on the test instance. This also provides the ability to install packages in an existing repository and run commands on the test instance.

The following sections may be provided in a YAML style config file. Each section can be a single item or a list of items. All files are copied and extracted to the default SSH location for the test instance. This is generally the user’s home directory.

inject_packages

an rpm path or list of rpm paths which will be copied and installed on the test instance.

inject_archives

an archive or list of archives which will be copied and extracted on the test instance.

inject_files

a file path or list of file paths which will be copied to the test instance.

execute

a command or list of commands to run on the test instance.

install

a package name or list of package names to install from an existing repo on the test instance.

The order of processing for the sections is as follows:

  1. inject_packages

  2. inject_archives

  3. inject_files

  4. execute

  5. install

Example

testing_injection.yaml.

inject_packages: /home/user/test.noarch.rpm
inject_archives: /home/user/test.tar.xz
inject_files: /home/user/test.py
install:
  - python3
  - python3-Django
execute: python test.py

> img-proof test ... --inject testing_injection.yaml

Code

img-proof can also be imported and invoked directly in Python 3 code through the controller class. It is installed as a Python site package and can be imported as follows:

from img_proof.ipa_controller import test_image

status, results = test_image(
    cloud_framework,
    access_key_id,
    ...
    storage_container,
    tests
)

See img_proof.ipa_controller module for specific methods that can be invoked.