Development tips & tricks
Development Tips & Tricks¶
Two methods can be used get Ansible up and running quickly with all the requirements to leverage ansible-avd. A Python Virtual Environment or Docker container.
The best way to use the development files, is to copy them to the root directory where you have your repositories cloned. For example, see the file/folder structure below.
├── git_projects │ ├── ansible-avd │ ├── ansible-cvp │ ├── netdevops-examples | ├── <YOUR OWN TESTING REPOSITORY> │ ├── Makefile
Build local environment¶
Please refer to Setup environment page
Once installed, use
dev-start command to bring up all the required containers:
- An mkdoc for AVD documentation listening on port
- An mkdoc or CVP documentation listening on port
- An AVD runner with a pseudo terminal connected to shell for ansible execution
The docker container approach for development can be used to ensure that everybody is using the same development environment while still being flexible enough to use the repo you are making changes in. You can inspect the Dockerfile to see what packages have been installed. The container will mount the current working directory, so you can work with your local files.
The ansible version is passed in with the docker build command using
ANSIBLE_VERSION variable. If the ANSIBLE variable is not used the Dockerfile will by default set the ansible version to describe in AVD requirements.
# Start development stack $ make start docker-compose -f ansible-avd/development/docker-compose.yml up -d Recreating development_ansible_1 ... done Recreating development_webdoc_cvp_1 ... done Recreating development_webdoc_avd_1 ... done # List containers started with stack $ docker-compose -f ansible-avd/development/docker-compose.yml ps Name Command State Ports ----------------------------------------------------------------------------- ansible_avd /bin/sh -c while true; do ... Up webdoc_avd sh -c pip install -r ansib ... Up 0.0.0.0:8000->8000/tcp webdoc_cvp sh -c pip install -r ansib ... Up 0.0.0.0:8001->8000/tcp # Get a shell with ansible (if not in shell from previous command) $ make dev-run docker-compose -f ansible-avd/development/docker-compose.yml exec ansible zsh Agent pid 52 ➜ /projects # Test MKDOCS access (outside of development container) $ curl -s http://127.0.0.1:8000 | head -n 10 <!doctype html> <html lang="en" class="no-js"> <head> <meta charset="utf-8"> <meta name="viewport" content="width=device-width,initial-scale=1"> # Stop development stack $ make dev-stop docker-compose -f ansible-avd/development/docker-compose.yml kill &&\ docker-compose -f ansible-avd/development/docker-compose.yml rm -f Killing development_ansible_1 ... done Killing development_webdoc_1 ... done Going to remove development_ansible_1, development_webdoc_1 Removing development_ansible_1 ... done Removing development_webdoc_1 ... done
pre-commit can run standard hooks on every commit to automatically point out issues in code such as missing semicolons, trailing whitespace, and debug statements. By pointing these issues out before code review, this allows a code reviewer to focus on the architecture of a change while not wasting time with trivial style nitpicks.
Repository implements following hooks:
trailing-whitespace: Fix trailing whitespace. if found, commit is stopped and you must run commit process again.
trailing-whitespace, this hook fix wrong end of file and stop your commit.
check-yaml: Check all YAML files ares valid
check-added-large-files: Check if there is no large file included in repository
check-merge-conflict: Validate there is no
MERGEsyntax related to a invalid merge process.
pylint: Run python linting with settings defined in
yamllint: Validate all YAML files using configuration from
ansible-lint: Validate yaml files are valid against ansible rules.
pre-commit is part of development requirememnts. To install, run
pip command in ansible-avd folder:
$ pip install -r development/requirements-dev.txt ...
Run pre-commit manually¶
pre-commit manually before your commit, use this command:
pre-commit run [WARNING] Unstaged files detected. [INFO] Stashing unstaged files to /Users/xxx/.cache/pre-commit/patch1590742434. Trim Trailing Whitespace.............................(no files to check)Skipped Fix End of Files.....................................(no files to check)Skipped Check Yaml...........................................(no files to check)Skipped Check for added large files..........................(no files to check)Skipped Check for merge conflicts............................(no files to check)Skipped Check for Linting error on Python files..............(no files to check)Skipped Check for Linting error on YAML files................(no files to check)Skipped Check for ansible-lint errors............................................Passed [INFO] Restored changes from /Users/xxx/.cache/pre-commit/patch1590742434.
Command will automatically detect changed files using git status and run tests according their type.
This process is also implemented in project CI to ensure code quality and compliance with ansible development process.
Configure git hook¶
To automatically run tests when running a commit, configure your repository whit command:
$ pre-commit install pre-commit installed at .git/hooks/pre-commit
To remove installation, use
Check 404 links¶
To validate documentation, you should check for not found links in your local version of the documentation. This test requires to run mkdocs container as explained in installation documentation.
In a shell, run the following make command. It starts a container in AVD documentation network and leverage
muffet tool to check 404 HTTP code:
$ check-avd-404 docker run --network container:webdoc_avd raviqqe/muffet \ http://127.0.0.1:8000 \ -e ".*fonts.gstatic.com.*" \ -e ".*edit.*" \ -f --limit-redirections=3 \ --timeout=60 http://127.0.0.1:8000/docs/installation/development/ 404 http://127.0.0.1:8000/docs/installation/development/setup-environment2.md make: *** [check-avd-404] Error 1
This process is also implemented in project CI to protect documentation against dead links.