diff options
Diffstat (limited to 'ansible_collections/google/cloud/CONTRIBUTING.md')
| -rw-r--r-- | ansible_collections/google/cloud/CONTRIBUTING.md | 84 |
1 files changed, 71 insertions, 13 deletions
diff --git a/ansible_collections/google/cloud/CONTRIBUTING.md b/ansible_collections/google/cloud/CONTRIBUTING.md index 716d767c8..74c753d58 100644 --- a/ansible_collections/google/cloud/CONTRIBUTING.md +++ b/ansible_collections/google/cloud/CONTRIBUTING.md @@ -15,13 +15,25 @@ under a directory `ansible_collections`. Clone ensuring that hierarchy: ```shell mkdir -p $TARGET_DIR/ansible_collections/google -git clone <url> $TARGET_DIR/collections/google/cloud +git clone <url> $TARGET_DIR/ansible_collections/google/cloud +``` + +Then set up your Python virtual environment: + +```shell +cd $TARGET_DIR/ansible_collections/google/cloud +python3 -m venv venv +. ./venv/bin/activate +pip3 install -r requirements.txt +pip3 install -r requirements-test.txt +pip3 install ansible ``` ## Running tests -### prequisites for all tests +### Prequisites for all tests +- Install `gcloud` following [these instructions](https://cloud.google.com/sdk/docs/install). - Install the `ansible` package. - Some container runtime is necessary (e.g. `podman` or `docker`). The instructions use podman. @@ -29,18 +41,63 @@ git clone <url> $TARGET_DIR/collections/google/cloud ### Integration testing prequisites -#### Installing personal GCP credentials +#### Authentication with personal GCP credentials + +If you are running the integration tests locally the easiest way to +authenticate to GCP is using [application default credentials](https://cloud.google.com/sdk/docs/authorizing#adc). +Once you have installed `gcloud` and performed basic initialization (via `gcloud init`) run: + +```shell +gcloud auth application-default login +``` + +#### Authentication with service account credentials + +A service account may also be used to run the integration tests. You can create one using `gcloud`: + +```shell +gcloud iam service-accounts create ansible-test-account \ + --description="For running Anisble integration tests" \ + --display-name="Ansible Test Account" +``` + +You'll also need to export a key file. Here and below `$SERVICE_ACCOUNT_NAME` +is the full email address of the service account, in the form +`EMAIL@PROJECT_ID.iam.gserviceaccount.com`, e.g., if you used the +account name `ansible-test-account` as suggested above and your project +ID is `my-test-project`, use `ansible-test-account@my-test-project.iam.gserviceaccount.com`. + +```shell +gcloud iam service-accounts keys create /path/to/cred/file.json \ + --iam-account=ansible-test-account@my-test-project.iam.gserviceaccount.com +chmod 0600 /path/to/cred/file.json +``` + +Read the [best practices for managing service account keys](https://cloud.google.com/iam/docs/best-practices-for-managing-service-account-keys) +to learn how to keep your service account key and your GCP resources safe. + +#### Configuring test credentials The integration tests for this module require the use of real GCP credentials, and must provide -ansible-test those values. They can be added by authoring the following in `tests/integration/cloud-config-gcp.ini`: +ansible-test those values. They can be added by creating the file `tests/integration/cloud-config-gcp.ini`. + +If you are using personal (i.e., application default) credentials, add: + +``` +[default] +gcp_project: $PROJECT_ID +gcp_cred_kind: application +gcp_folder_id: $TEST_FOLDER (to create test projects) +``` + +If you are using a service account for credentials, add: ``` [default] -gcp_project: @PROJECT_ID -gcp_cred_file: @CRED_FILE -gcp_cred_kind: @CRED_KIND -gcp_cred_email: @EMAIL -gcp_folder_id: @TEST_FOLDER (to create test projects) +gcp_project: $PROJECT_ID +gcp_cred_file: /path/to/cred/file.json +gcp_cred_kind: serviceaccount +gcp_folder_id: $TEST_FOLDER (to create test projects) ``` #### Setting up the project for testing @@ -51,7 +108,8 @@ and is expected to be configured beforehand. For convenience, a bootstrap script is provided. NOTE: running this script will make irreversible changes in your -GCP project (e.g. create an AppEngine project): +GCP project (e.g. create an AppEngine project). You can omit +`$SERVICE_ACCOUNT_NAME` is you are using application default credentials. ```bash bash ./scripts/bootstrap-project.sh $PROJECT_ID $SERVICE_ACCOUNT_NAME @@ -66,10 +124,10 @@ Run `ansible-test integration`. Currently some tests are disabled as [test are b ### Prequisites for role tests If you would like to use podman, you must -install the `molecule[podman]` package in PyPI: +install the `molecule-plugins[podman]` package in PyPI: ``` -pip install --upgrade molecule[podman] +pip install --upgrade molecule-plugins[podman] ``` ### Running role tests @@ -92,7 +150,7 @@ ansible-lint ## Specific Tasks -The following enumerates detailed documentation for specific tasks related tot +The following enumerates detailed documentation for specific tasks related to the codebase. ### Updating the supported ansible-core version |