Getting Started

Installation

SUSE package

SLES 15

Ensure you have properly registered SLES then perform the following commands as root for SLES 15:

$ SUSEConnect -p sle-module-public-cloud/15.#/x86_64
$ zypper ar https://download.opensuse.org/repositories/Cloud:Tools:CI/SLE_15_SP#/Cloud:Tools:CI.repo
$ zypper refresh
$ zypper in python3-img-proof

Replace # with the service pack you are using. Currently support exists for SP2+.

openSUSE Leap 15

Perform the following commands as root for Leap 15:

$ zypper ar https://download.opensuse.org/repositories/Cloud:Tools:CI/openSUSE_Leap_15.#/Cloud:Tools:CI.repo
$ zypper refresh
$ zypper in python3-img-proof

Currently Leap 15.3+ is supported.

openSUSE Tumbleweed

Perform the following commands as root for Tumbleweed:

$ zypper ar https://download.opensuse.org/repositories/Cloud:Tools:CI/openSUSE_Tumbleweed/Cloud:Tools:CI.repo
$ zypper refresh
$ zypper in python3-img-proof

Note

An openSUSE and SLES test suite is shipped alongside the SUSE package as python3-img-proof-tests.

SUSE test suite

To install the SLES test suite alongside the package use the following command:

$ zypper in python3-img-proof-tests

PyPI

$ pip install img-proof

Development

Install the latest development version from GitHub:

$ pip install git+https://github.com/SUSE-Enceladus/img-proof.git

Branch

Install a specific branch from GitHub:

$ pip install git+https://github.com/SUSE-Enceladus/img-proof.git@{branch/release}

See PyPI docs for more information on vcs support.

Configuration

img-proof Config

The img-proof configuration file is ini format ~/.config/img_proof/config. This can be used for any configuration value including cloud framework specific values.

To override the default configuration location the CLI option -C or --config is available.

The config file can have multiple sections. The default section is [img_proof] and each cloud framework can have its own section such as [{cloud_framework}]. A config file with an [ec2] section may look like the following:

[img_proof]
test_dirs = /custom/tests/path/
results_dir = /custom/results/dir/

[ec2]
region = us-west-1
ssh_private_key_file = ~/.ssh/id_rsa

There are multiple ways to provide configuration values when using img-proof. All options are available via command line and the configuration file. Also, for certain clouds img-proof will read cloud specific config files.

All command line options which have a format such as --ssh-user can be placed in config with underscores. E.g. --ssh-user would be ssh_user in the config file.

The precedence for values is as follows:

command line -> cloud config -> img-proof config -> defaults

The command line arguments if provided will be used over all other values.

Azure Config

The Azure provider class has no additional config file. Options should be placed into the img-proof config file.

EC2 Config

For testing EC2 instances img-proof will look for the ec2utils configuration file located at ~/.ec2utils.conf.

See ec2utils for an example configuration file.

To override the EC2 config location the CLI option, --cloud-config is available. In order for img-proof to use the ec2imgutils config file the --account-name is required.

GCE Config

The GCE cloud class has no additional config file. Options should be placed into the img-proof config file.

OCI Config

For testing OCI instances img-proof will look for the Oracle configuration file located at ~/.oci/config.

See OCI docs for more info on the Oracle configuration file.

To override the OCI config location the CLI option, --cloud-config is available.

The OCI config file is optional as img-proof will also look for configuration arguments in the img-proof config file and these can be overridden by CLI values.

SSH Config

The SSH cloud class has no additional config file. Options should be placed into the img-proof config file.

Aliyun Config

The Aliyun cloud class has no additional config file. Options should be placed into the img-proof config file.

Credentials

Azure

Azure uses service principals for authentication. A service principal (service account) json file is required to use the Azure cloud via file based authentication. It is critical the json file is generated with the endpoint URLs for SDK authentication.

To create the file you will need the Azure CLI.

The following command will generate the necessary json file:

$ az ad sp create-for-rbac --sdk-auth --role Contributor --scopes /subscriptions/{subscription_id} --name "{name}" > mycredentials.json

Once a json credential file is generated for a service principal it can be used to test images/instances in Azure. The --service-account-file option should point to the path to this file.

See Azure docs for more info on creating a service principal json file.

EC2

The EC2 credentials are a --secret-access-key and --access-key-id. These can be from a root account but it’s suggested to use IAM accounts to control role based access.

Once you have generated secret key values these can be configured with the --secret-access-key and --access-key-id options.

See EC2 docs for more information on setting up IAM accounts.

GCE

GCE uses service accounts for file based authentication. The service account is required to have the following roles:

Additionally the file must be JSON format and contain a private key.

The following steps will create a service account with gcloud and gsutil:

$ gcloud --project={project-id} iam service-accounts create {service-account-id}
$ gcloud --project={project-id} iam service-accounts keys create {service_account-id}-key.json --iam-account {service-account-id}@{project-id}.iam.gserviceaccount.com
$ gcloud projects add-iam-policy-binding {project-id} --member serviceAccount:{service-account-id}@{project-id}.iam.gserviceaccount.com --role roles/compute.instanceAdmin.v1
$ gcloud projects add-iam-policy-binding {project-id} --member serviceAccount:{service-account-id}@{project-id}.iam.gserviceaccount.com --role roles/iam.serviceAccountUser

The json file generated by the second command “{service_account-id}-key.json” is used for GCE authentication.

$ img-proof test gce ... --service-account-file {service_account-id}-key.json

Or you can follow the Libcloud docs or Google docs.

Once a json credential file is generated for a service account it can be used to test images/instances in GCE. The --service-account-file option should point to the path to this file.

For more information on updating an existing service account:

SSH

Requires no cloud credentials to test instances. SSH user, SSH private key can be placed in SSH section of config. The instance to be tested must be running.

OCI

To use OCI a new compartment, a new user, a new group and an api signing key are required. The user will require access to the compartment via a policy.

The first step is to create an API signing key which will be used by the user for running commands via the OCI SDK. The following doc provides info on creating a key and getting the public key and fingerprint.

Once you have the API signing key you will now create a user, group, compartment and a policy for the new user. The following doc provides all the steps necessary to set these artifacts up. The group will require the following policy for the new compartment:

Allow group {group_name} to manage all-resources in compartment {compartment_name}

With this setup you can now add the API key to your user. The steps to upload your public key are in the following doc: doc

All of this info can be added as arguments to the OCI config, img-proof config or as command line arguments when testing images in OCI. The required options are:

  • --availability-domain

  • --compartment-id

  • --oci-user-id

  • --signing-key-fingerprint

  • --signing-key-file

  • --tenancy

Aliyun

The Aliyun credentials are a --access-secret and --access-key. These can be from a root account but it’s suggested to use RAM accounts to control role based access.

See Aliyun docs for more information on setting up RAM accounts.