From 5458389bdee3a03078fcfee88daf2b5f6500ebdf Mon Sep 17 00:00:00 2001 From: trfore Date: Wed, 24 Apr 2024 14:37:18 -0500 Subject: [PATCH 1/5] ci: set default env var values but allow passing in GH, tox or molecule workflow --- extensions/molecule/default/molecule.yml | 2 ++ extensions/molecule/multiple_certs/molecule.yml | 2 ++ extensions/molecule/step_ssh/molecule.yml | 4 ++-- 3 files changed, 6 insertions(+), 2 deletions(-) diff --git a/extensions/molecule/default/molecule.yml b/extensions/molecule/default/molecule.yml index b0effc4..a2fdbf0 100644 --- a/extensions/molecule/default/molecule.yml +++ b/extensions/molecule/default/molecule.yml @@ -22,6 +22,8 @@ provisioner: playbooks: converge: ${MOLECULE_PLAYBOOK:-converge.yml} env: + STEP_CA_VERSION: ${STEP_CA_VERSION:-latest} + STEP_CLI_VERSION: ${STEP_CLI_VERSION:-latest} TARGET_CA: ${MOLECULE_NAME:-ca-server} config_options: defaults: diff --git a/extensions/molecule/multiple_certs/molecule.yml b/extensions/molecule/multiple_certs/molecule.yml index 75aacab..52907b3 100644 --- a/extensions/molecule/multiple_certs/molecule.yml +++ b/extensions/molecule/multiple_certs/molecule.yml @@ -45,6 +45,8 @@ provisioner: playbooks: converge: ${MOLECULE_PLAYBOOK:-converge.yml} env: + STEP_CA_VERSION: ${STEP_CA_VERSION:-latest} + STEP_CLI_VERSION: ${STEP_CLI_VERSION:-latest} TARGET_CA: ca-server-${MOLECULE_NAME:-01} TARGET_CLIENTS: ca-client-${MOLECULE_NAME:-01} config_options: diff --git a/extensions/molecule/step_ssh/molecule.yml b/extensions/molecule/step_ssh/molecule.yml index 283515e..28434bf 100644 --- a/extensions/molecule/step_ssh/molecule.yml +++ b/extensions/molecule/step_ssh/molecule.yml @@ -43,8 +43,8 @@ provisioner: playbooks: converge: ${MOLECULE_PLAYBOOK:-converge.yml} env: - STEP_CA_VERSION: ${MOLECULE_STEP_CA_VERSION:-"latest"} - STEP_CLI_VERSION: ${MOLECULE_STEP_CLI_VERSION:-"latest"} + STEP_CA_VERSION: ${STEP_CA_VERSION:-latest} + STEP_CLI_VERSION: ${STEP_CLI_VERSION:-latest} TARGET_CA: ca-server-${MOLECULE_NAME:-01} TARGET_CLIENTS: ca-client-${MOLECULE_NAME:-01} config_options: From e9ad3bd19a136feaa61d19a0cdfb796f88a6e321 Mon Sep 17 00:00:00 2001 From: trfore Date: Wed, 24 Apr 2024 14:38:15 -0500 Subject: [PATCH 2/5] test: add local tox config file --- tox.ini | 74 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 74 insertions(+) create mode 100644 tox.ini diff --git a/tox.ini b/tox.ini new file mode 100644 index 0000000..58c67fa --- /dev/null +++ b/tox.ini @@ -0,0 +1,74 @@ +[tox] +minversion = 4.0.0 +envlist = + lint + docs + py-ansible{2.15, 2.16}-{default,ssh} + py-ansible{2.16}-{default,ssh}-{centos, debian} + py-ansible{2.16}-{mult} + +[testenv] +description = + default-!centos-!debian: Run molecule scenario on Ubuntu (default) + ssh-!centos-!debian: Run molecule scenario on Ubuntu (step_ssh) + centos-!ssh: Run molecule scenario on CentOS (default) + centos-!default: Run molecule scenario on CentOS (step_ssh) + debian-!ssh: Run molecule scenario on Debian (default) + debian-!default: Run molecule scenario on Debian (default) + mult: Run molecule scenario to request multiple server certs (Ubuntu) +deps = + ansible2.15: ansible-core == 2.15.* + ansible2.16: ansible-core == 2.16.* + docker + jmespath + molecule + molecule-plugins[docker] + pytest + pytest-testinfra +commands = + default: molecule {posargs:test -s default} + ssh: molecule {posargs:test -s step_ssh} + mult: molecule {posargs:test -s multiple_certs} +setenv = + ANSIBLE_COLLECTIONS_PATH={work_dir}/{env_name}/.ansible/collections/ansible_collections + MOLECULE_EPHEMERAL_DIRECTORY={work_dir}/{env_name}/.cache/molecule + MOLECULE_GLOB=./extensions/molecule/*/molecule.yml + MOLECULE_NAME={env_name} + centos: MOLECULE_IMAGE=trfore/docker-centos9-systemd + debian: MOLECULE_IMAGE=trfore/docker-debian12-systemd + PY_COLORS=1 + TOX_ENVNAME={env_name} +passenv = + DOCKER_HOST + MOLECULE_IMAGE + STEP_CA_VERSION + STEP_CLI_VERSION + +[testenv:docs] +description = Build the docsite for local preview +deps = + ansible-core + antsibull-docs +allowlist_externals = bash, chmod +commands_pre = + ansible-galaxy collection install . --force + chmod 0700 {env:DOCS_PATH} +commands = + antsibull-docs sphinx-init --squash-hierarchy --use-current --dest-dir {env:DOCS_PATH} trfore.smallstep + pip install -r {env:DOCS_PATH}/requirements.txt + bash {env:DOCS_PATH}/build.sh +setenv = + ANSIBLE_COLLECTIONS_PATH={work_dir}/{env_name}/.ansible/collections/ansible_collections + DOCS_PATH={env_dir}/tmp + PY_COLORS=1 + TOX_ENVNAME={env_name} + +[testenv:lint] +description = Run all linting tasks +skip_install = true +deps = + pre-commit +commands = + pre-commit run {posargs:--all --show-diff-on-failure} +setenv = + TOX_ENVNAME={env_name} From eb9caade1a61a11b257c420485f0d25e1bd9d39c Mon Sep 17 00:00:00 2001 From: trfore Date: Wed, 24 Apr 2024 14:38:31 -0500 Subject: [PATCH 3/5] docs: add contribution guide with tox instructions --- CONTRIBUTING.md | 105 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 105 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..647b379 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,105 @@ +# Contributing + +## Contribute + +- [Fork the repository](/~https://github.com/trfore/ansible-smallstep/fork) on github and clone it. +- Create a new branch and add your code. +- Write test that cover the changes and expected outcome. +- Test your changes locally using `tox`. +- Push the changes to your fork and submit a pull-request on github. + +```sh +git clone /~https://github.com/USERNAME/ansible-smallstep && cd ansible-smallstep +git checkout -b MY_BRANCH +# add code and test +tox run-parallel +git push -u origin MY_BRANCH +gh pr create --title 'feature: add ...' +``` + +### Setup a Dev Environment + +```sh +cd ansible-smallstep +python3 -m venv .venv && source .venv/bin/activate +python3 -m pip install -r requirements/dev-requirements.txt +pre-commit install +``` + +### Tox: Test Suite + +- A local installation of [Docker](https://docs.docker.com/engine/installation/) is required to run the `molecule` test scenarios. +- All `tox` environments are created within the project directory under `.tox`. +- The collection is tested using the last three versions of `ansible-core` on a Ubuntu image. Additionally, the collection is tested using the latest `ansible-core` on CentOS and Debian. + - NOTE: Some molecule scenarios, `multiple_certs` and `step_ssh`, will generate a docker bridge network for each `tox` environment using the next available subnet, e.g. `172.18.0.0/16`. The default docker network is `172.17.0.0/16`. +- Extensive code modifications that change how a playbook is written need to be accompanied by test, e.g. molecule scenario, that covers the changes. This will help avoid end-user frustration with faulty code examples in the documentation. + - Follow best practices for creating playbooks and handling variables within `playbooks/`, but avoid encrypting files. This will keep encrypted files out of the collection build and avoid issues with [`ansible-lint` #2889](/~https://github.com/ansible/ansible-lint/issues/2889). + +```sh +cd ansible-smallstep +# list environments and test +tox list +# lint all files +tox -e lint run +# run a specific test environment +tox -e py-ansible2.16-default run +# run a group of tests, e.g. the default molecule scenario +tox -f default run +# run all test in parallel +tox run-parallel +``` + +- You can also pass environment variables to tox for: `MOLECULE_IMAGE`, `STEP_CA_VERSION`, and `STEP_CLI_VERSION`. When running multiple test, we highly recommend using `STEP_*_VERSION` variables to avoid hitting GitHub's API rate limiter. + +```sh +MOLECULE_IMAGE='trfore/docker-debian12-systemd' tox -e py-ansible2.16-default run +STEP_CA_VERSION='0.26.0' STEP_CLI_VERSION='0.26.0' tox -e py-ansible2.16-default run +# highly recommended +STEP_CA_VERSION='0.26.0' STEP_CLI_VERSION='0.26.0' tox run-parallel +``` + +- For iterative development and testing, the tox molecule environments are written to accept `molecule` arguments. This allows for codebase changes to be tested as you write across multiple distros and versions of `ansible-core`. + +```sh +# molecule converge +tox -e py-ansible2.16-default run -- converge -s default +# molecule test w/o destroying the container +tox -e py-ansible2.16-default run -- test -s default --destroy=never + +# exec into the container via tox +tox -e py-ansible2.16-default run -- login -s default +# exec into the container +docker exec -it py-ansible2.16-default bash + +# parallel testing +tox -f default run-parallel -- test -s default --destroy=never +# remove all containers +tox -f default run-parallel -- destroy -s default +``` + +### Tox: Docsite Preview + +- If you are making changes to the docsite, `docs/`, or adding variables, e.g. `argument_specs.yml`, you can build the docsite locally and preview the changes. + +```sh +cd ansible-smallstep +# build site using tox +tox -e docs +# preview the docsite +python3 -c 'import webbrowser; webbrowser.open_new(".tox/docs/tmp/build/html/index.html")' +``` + +### Documentation + +- New features or extensive code changes need to be accompanied by documentation in a `argument_specs.yml` and README. This information can be redundant, yet it is often helpful to start with the argument_specs then copy it to a README. +- Adding a scenario guide, `docs/docsite/rst/guide_*.rst`, to the documentation is also nice for features with many arguments or different configurations. + +### Pull Request + +- All pull request are run through a more extensive test suite that will validate the collection on multiple OSs and releases, yet local `pre-commit` and `tox` test should provide a good proxy for the github tests. + +## Additional References + +- [Ansible community guide](https://docs.ansible.com/ansible/devel/community/index.html) +- [Github Docs: Forking a repository](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo#forking-a-repository) +- [Ansible Docs: `ansible-core` support matrix](https://docs.ansible.com/ansible/latest/reference_appendices/release_and_maintenance.html#ansible-core-support-matrix) From e081181febaa612d59ebc01601680d6eb9e27418 Mon Sep 17 00:00:00 2001 From: trfore Date: Wed, 24 Apr 2024 14:39:09 -0500 Subject: [PATCH 4/5] chore: update collection version --- galaxy.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/galaxy.yml b/galaxy.yml index f2f06e5..cb24028 100644 --- a/galaxy.yml +++ b/galaxy.yml @@ -1,6 +1,6 @@ namespace: trfore name: smallstep -version: 1.1.0 +version: 1.1.1 readme: README.md authors: - Taylor Fore (/~https://github.com/trfore/) From 728dc5d001ab6617de86f9d14c306f30725139b4 Mon Sep 17 00:00:00 2001 From: trfore Date: Wed, 24 Apr 2024 14:44:31 -0500 Subject: [PATCH 5/5] docs: add PR template --- .github/pull_request_template.md | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) create mode 100644 .github/pull_request_template.md diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..cdf1908 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,32 @@ +## Description + +Please include a summary of the change and which issue is fixed. Please also include relevant motivation and context. List any dependencies that are required for this change. + +## Type of change + +- [ ] Bug fix (non-breaking change which fixes an issue) +- [ ] New feature (non-breaking change which adds functionality) +- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected) +- [ ] This change requires a documentation update + +## How Has This Been Tested? + +Please describe the tests that you ran to verify your changes. Provide instructions so we can reproduce. Please also list any relevant details for your test configuration + +### Test Configuration + +```sh +# Please provide example playbook or CLI command +$ molecule test -s MY_SCENARIO +$ tox -f MY_SCENARIO run +``` + +## Checklist: + +- [ ] I have performed a self-review of my own code +- [ ] I have commented my code, particularly in hard-to-understand areas +- [ ] I have made corresponding changes to the documentation +- [ ] My changes generate no new warnings +- [ ] I have added tests that prove my fix is effective or that my feature works +- [ ] New and existing unit tests pass locally with my changes +- [ ] Any dependent changes have been merged and published in downstream modules