Skip to content

docs: explain how to use noxfile_config and add secrets #5054

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
busunkim96 merged 6 commits into from
Dec 9, 2020
Merged

docs: explain how to use noxfile_config and add secrets #5054

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
6b2f9b4
docs: explain env vars and secrets in authoring guide
busunkim96 Dec 9, 2020
a3e4915
docs: explain noxfile config
busunkim96 Dec 9, 2020
d8136a7
docs: fix formatting
busunkim96 Dec 9, 2020
2c1e1a3
docs: make GH team a link
busunkim96 Dec 9, 2020
ddfae8b
fix: more formatting
busunkim96 Dec 9, 2020
67689d6
Merge branch 'master' into explain-env-vars
leahecole Dec 9, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
72 changes: 68 additions & 4 deletions AUTHORING_GUIDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -521,11 +521,10 @@ Once you have your project created and configured, you'll need to set
environment variables to identify the project and resources to be used
by tests. See
[testing/test-env.tmpl.sh](https://github.com/GoogleCloudPlatform/python-docs-samples/blob/master/testing/test-env.tmpl.sh)
for a list of all environment variables used by all tests. Not every
for a list of all environment variables that must be set manually. Not every
test needs all of these variables. All required environment variables
should be listed in the README and `testing/test-env.tmpl.sh`. If you
find one is missing, please add instructions for setting it as part of
your PR.
are listed in `testing/test-env.tmpl.sh`. If you need to add a new secret,
follow instructions in [Secrets](#secrets).

We suggest that you copy this file as follows:

Expand Down Expand Up @@ -555,6 +554,18 @@ This repository supports two ways to run tests locally.

Please read the [MAC Setup Guide](https://github.com/GoogleCloudPlatform/python-docs-samples/blob/master/MAC_SETUP.md).

#### `noxfile_config.py`

The [`noxfile_config.py`](noxfile_config.py) allows for customization
of some options:

* Ignore specific Python versions.
* Enforce type hints.
* Specify a different Google Cloud Project.
* Add additional environment variables. Also see [Environment Variables](#environment-variables).

Options are documented inside the [noxfile_config.py](noxfile_config.py).

### Running tests with nox

Automated testing for samples is managed by
Expand Down Expand Up @@ -633,6 +644,59 @@ On MacOS systems, you also need to install `coreutils` to use
$ brew install coreutils
```

### Environment Variables and Secrets

This section explains how to set environment variables that are needed
by tests.


#### Environment Variables

If a `noxfile_config.py` does not exist, copy [`noxfile_config.py`](noxfile_config.py)
into the directory.

Add the new environment variables to the `envs` dictionary.

```py
TEST_CONFIG_OVERRIDE = {
# You can opt out from the test for specific Python versions.
"ignored_versions": ["2.7"],
# Old samples are opted out of enforcing Python type hints
# All new samples should feature them
"enforce_type_hints": True,
# An envvar key for determining the project id to use. Change it
# to 'BUILD_SPECIFIC_GCLOUD_PROJECT' if you want to opt in using a
# build specific Cloud project. You can also use your own string
# to use your own Cloud project.
"gcloud_project_env": "GOOGLE_CLOUD_PROJECT",
# 'gcloud_project_env': 'BUILD_SPECIFIC_GCLOUD_PROJECT',
# A dictionary you want to inject into your test. Don't put any
# secrets here. These values will override predefined values.
"envs": {"DJANGO_SETTINGS_MODULE": "mysite.settings"},
}
```


#### Secrets

For setting up a local test environment, see [Test Environment Setup](#test-environment-setup).

Secrets (e.g., project names, API keys, passwords) are kept in
Cloud Secret Manager. See [python-docs-samples-test-env](https://console.cloud.google.com/security/secret-manager/secret/python-docs-samples-test-env/versions?project=cloud-devrel-kokoro-resources).
If you are unable to access the link, reach out to your assigned pull
request reviewer or someone in [@GoogleCloudPlatform/python-samples-owners](https://github.com/orgs/GoogleCloudPlatform/teams/python-samples-owners)
for assistance.

1. Add the new environment variable to [`testing/test-env.tmpl.sh`](testing/test-env.tmpl.sh)
in your pull request.
2. Run [`scripts/decrypt-secrets.sh`](scripts/decrypt-secrets.sh)
to fetch the secrets. A new file `testing/test-env.sh` will appear.
3. Add the new environment variable to `testing/test-env.sh`.
4. Run [`scripts/encrypt-secrets.sh`](scripts/encrypt-secrets.sh)
to upload the secrets to secret manager.



### Google Cloud Storage Resources

Certain samples require integration with Google Cloud Storage (GCS), most
Expand Down
10 changes: 4 additions & 6 deletions noxfile_config.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,19 +22,17 @@

TEST_CONFIG_OVERRIDE = {
# You can opt out from the test for specific Python versions.
'ignored_versions': ["2.7"],
"ignored_versions": ["2.7"],
# Old samples are opted out of enforcing Python type hints
# All new samples should feature them
'enforce_type_hints': False,

"enforce_type_hints": True,
# An envvar key for determining the project id to use. Change it
# to 'BUILD_SPECIFIC_GCLOUD_PROJECT' if you want to opt in using a
# build specific Cloud project. You can also use your own string
# to use your own Cloud project.
'gcloud_project_env': 'GOOGLE_CLOUD_PROJECT',
"gcloud_project_env": "GOOGLE_CLOUD_PROJECT",
# 'gcloud_project_env': 'BUILD_SPECIFIC_GCLOUD_PROJECT',

# A dictionary you want to inject into your test. Don't put any
# secrets here. These values will override predefined values.
'envs': {},
"envs": {},
}