From 562f3f3ef4bd110c9e903898c3c9e9b82b850146 Mon Sep 17 00:00:00 2001 From: bakebot Date: Wed, 13 Sep 2023 10:26:54 +0000 Subject: [PATCH 1/9] Cookie initialy baked by NetworkToCode Cookie Drift Manager Tool Template: ``` { "template": "https://github.com/nautobot/cookiecutter-nautobot-app.git", "dir": "nautobot-app", "ref": "develop", "path": null } ``` Cookie: ``` { "remote": "https://github.com/nautobot/nautobot-plugin-golden-config.git", "path": "/opt/ntc/drift-manager/outputs/nautobot-plugin-golden-config", "repository_path": "/opt/ntc/drift-manager/outputs/nautobot-plugin-golden-config", "dir": "", "branch_prefix": "drift-manager", "context": { "codeowner_github_usernames": "@itdependsnetworks @jeffkala @nkallergis", "full_name": "Network to Code, LLC", "email": "opensource@networktocode.com", "github_org": "nautobot", "plugin_name": "nautobot_golden_config", "verbose_name": "Golden Config", "plugin_slug": "nautobot-golden-config", "project_slug": "nautobot-plugin-golden-config", "repo_url": "https://github.com/nautobot/nautobot-plugin-golden-config", "base_url": "golden-config", "min_nautobot_version": "1.4.0", "max_nautobot_version": "1.9999", "nautobot_version": "latest", "camel_name": "NautobotGoldenConfig", "project_short_description": "A plugin for configuration on nautobot", "version": "1.0.0", "model_class_name": "None", "open_source_license": "Apache-2.0", "docs_base_url": "https://docs.nautobot.com", "docs_app_url": "https://docs.nautobot.com/projects/golden-config/en/latest", "_template": "https://github.com/nautobot/cookiecutter-nautobot-app.git", "_output_dir": "/opt/ntc/drift-manager/outputs", "_repo_dir": "/opt/ntc/drift-manager/outputs/.cookiecutters/cookiecutter-nautobot-app/nautobot-app" }, "base_branch": "next-2.0", "remote_name": "origin", "pull_request_strategy": "PullRequestStrategy.CREATE", "post_actions": [] } ``` CLI Arguments: ``` { "cookie_dir": "", "input": false, "json_filename": "./setup-cookie-golden-config.json", "output_dir": "./outputs", "push": true, "template": "https://github.com/nautobot/cookiecutter-nautobot-app.git", "template_dir": "nautobot-app", "template_ref": "develop", "pull_request": null, "post_action": [], "disable_post_actions": false } ``` --- .bandit.yml | 7 +- .cookiecutter.json | 33 ++ .dockerignore | 27 ++ .flake8 | 12 +- .github/CODEOWNERS | 2 +- .github/ISSUE_TEMPLATE/bug_report.md | 16 +- .github/ISSUE_TEMPLATE/feature_request.md | 4 +- .../pull_request_template.md | 10 + .github/workflows/ci.yml | 49 ++- .github/workflows/rebake.yaml | 34 ++ .github/workflows/upstream_testing.yml | 6 +- .gitignore | 26 +- .readthedocs.yaml | 4 +- .yamllint.yml | 5 +- LICENSE | 2 +- README.md | 73 ++-- development/Dockerfile | 37 +- development/development.env | 13 - development/docker-compose.base.yml | 4 +- development/docker-compose.dev.yml | 21 +- development/docker-compose.mysql.yml | 8 +- development/docker-compose.postgres.yml | 4 +- development/nautobot_config.py | 171 +++----- docs/admin/compatibility_matrix.md | 18 +- docs/admin/install.md | 81 ++++ docs/admin/release_notes/version_1.0.md | 74 ++-- docs/admin/uninstall.md | 18 + docs/admin/upgrade.md | 10 + docs/assets/extra.css | 76 +++- docs/assets/overrides/partials/copyright.html | 2 + docs/dev/arch_decision.md | 7 + docs/dev/code_reference/api.md | 1 - docs/dev/code_reference/index.md | 3 + docs/dev/code_reference/package.md | 1 + docs/dev/contributing.md | 24 + docs/dev/dev_environment.md | 38 +- docs/dev/extending.md | 6 + docs/images/icon-nautobot-golden-config.png | Bin 0 -> 74601 bytes docs/requirements.txt | 6 +- docs/user/app_getting_started.md | 228 +--------- docs/user/app_overview.md | 38 +- docs/user/app_use_cases.md | 207 +-------- docs/user/external_interactions.md | 17 + docs/user/faq.md | 1 + invoke.example.yml | 2 +- invoke.mysql.yml | 2 +- mkdocs.yml | 62 +-- nautobot_golden_config/__init__.py | 55 +-- nautobot_golden_config/tests/test_api.py | 409 +----------------- nautobot_golden_config/tests/test_basic.py | 17 +- pyproject.toml | 71 ++- tasks.py | 347 ++++++++++++--- 52 files changed, 1009 insertions(+), 1380 deletions(-) create mode 100644 .cookiecutter.json create mode 100644 .dockerignore create mode 100644 .github/PULL_REQUEST_TEMPLATE/pull_request_template.md create mode 100644 .github/workflows/rebake.yaml create mode 100644 docs/admin/install.md create mode 100644 docs/admin/uninstall.md create mode 100644 docs/admin/upgrade.md create mode 100644 docs/dev/arch_decision.md create mode 100644 docs/dev/code_reference/package.md create mode 100644 docs/dev/contributing.md create mode 100644 docs/dev/extending.md create mode 100644 docs/images/icon-nautobot-golden-config.png create mode 100644 docs/user/external_interactions.md create mode 100644 docs/user/faq.md diff --git a/.bandit.yml b/.bandit.yml index 16ab010a..56f7a83b 100644 --- a/.bandit.yml +++ b/.bandit.yml @@ -1,7 +1,6 @@ --- +skips: [] # No need to check for security issues in the test scripts! exclude_dirs: - - "./nautobot_golden_config/tests/" - -skips: - - "B404" + - "./tests/" + - "./.venv/" diff --git a/.cookiecutter.json b/.cookiecutter.json new file mode 100644 index 00000000..ea65bfeb --- /dev/null +++ b/.cookiecutter.json @@ -0,0 +1,33 @@ +{ + "cookiecutter": { + "codeowner_github_usernames": "@itdependsnetworks @jeffkala @nkallergis", + "full_name": "Network to Code, LLC", + "email": "opensource@networktocode.com", + "github_org": "nautobot", + "plugin_name": "nautobot_golden_config", + "verbose_name": "Golden Config", + "plugin_slug": "nautobot-golden-config", + "project_slug": "nautobot-plugin-golden-config", + "repo_url": "https://github.com/nautobot/nautobot-plugin-golden-config", + "base_url": "golden-config", + "min_nautobot_version": "1.4.0", + "max_nautobot_version": "1.9999", + "nautobot_version": "latest", + "camel_name": "NautobotGoldenConfig", + "project_short_description": "A plugin for configuration on nautobot", + "version": "1.0.0", + "model_class_name": "None", + "open_source_license": "Apache-2.0", + "docs_base_url": "https://docs.nautobot.com", + "docs_app_url": "https://docs.nautobot.com/projects/golden-config/en/latest", + "_drift_manager": { + "template": "https://github.com/nautobot/cookiecutter-nautobot-app.git", + "template_dir": "nautobot-app", + "template_ref": "develop", + "cookie_dir": "", + "branch_prefix": "drift-manager", + "pull_request_strategy": "create", + "post_actions": [] + } + } +} diff --git a/.dockerignore b/.dockerignore new file mode 100644 index 00000000..2270f496 --- /dev/null +++ b/.dockerignore @@ -0,0 +1,27 @@ +# Docker related +development/Dockerfile +development/docker-compose*.yml +development/*.env +*.env +environments/ + +# Python +**/*.pyc +**/*.pyo +**/__pycache__/ +**/.pytest_cache/ +**/.venv/ + + +# Other +docs/_build +FAQ.md +.git/ +.gitignore +.github +tasks.py +LICENSE +**/*.log +**/.vscode/ +invoke*.yml +tasks.py diff --git a/.flake8 b/.flake8 index aaa63b60..c9f5e84d 100644 --- a/.flake8 +++ b/.flake8 @@ -1,4 +1,10 @@ [flake8] -# E501: Line length is enforced by Black, so flake8 doesn't need to check it -# W503: Black disagrees with this rule, as does PEP 8; Black wins -ignore = E501, W503, F811, F401, F405, E203 +ignore = + E501, # Line length is enforced by Black, so flake8 doesn't need to check it + W503 # Black disagrees with this rule, as does PEP 8; Black wins +exclude = + migrations, + __pycache__, + manage.py, + settings.py, + .venv diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 30cca39a..d1982711 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -1,2 +1,2 @@ -# Default owners for all files in this repository +# Default owner(s) of all files in this repository * @itdependsnetworks @jeffkala @nkallergis diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index 8f26fcbf..cbb194ae 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -5,9 +5,16 @@ about: Report a reproducible bug in the current release of nautobot-golden-confi ### Environment * Python version: -* Nautobot version: +* Nautobot version: * nautobot-golden-config version: + +### Expected Behavior + + + +### Observed Behavior + -### Expected Behavior - - - -### Observed Behavior diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md index 924a52ad..a8d54617 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.md +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -1,11 +1,11 @@ --- name: ✨ Feature Request about: Propose a new feature or enhancement + --- ### Environment -* Python version: -* Nautobot version: +* Nautobot version: * nautobot-golden-config version:

- +
- +
- An App for Nautobot. + An App for Nautobot.

## Overview -The Golden Config plugin is a Nautobot plugin that provides a NetDevOps approach to golden configuration and configuration compliance. - -### Key Use Cases - -This plugin enable five (5) key use cases. +> Developer Note: Add a long (2-3 paragraphs) description of what the App does, what problems it solves, what functionality it adds to Nautobot, what external systems it works with etc. -1. **Configuration Backups** - Is a Nornir process to connect to devices, optionally parse out lines/secrets, backup the configuration, and save to a Git repository. -2. **Intended Configuration** - Is a Nornir process to generate configuration based on a Git repo of Jinja files to combine with a GraphQL generated data and a Git repo to store the intended configuration. -3. **Source of Truth Aggregation** - Is a GraphQL query per device that creates a data structure used in the generation of configuration. -4. **Configuration Compliance** - Is a process to run comparison of the actual (via backups) and intended (via Jinja file creation) CLI configurations upon saving the actual and intended configuration. This is started by either a Nornir process for cli-like configurations or calling the API for json-like configurations -5. **Configuration Postprocessing** - (beta) This process renders a valid configuration artifact from an intended configuration, that can be pushed to devices. The current implementation renders this configuration; however, **it doesn't push it** to the target device. +### Screenshots -> Notice: The operators of their own Nautobot instance are welcome to use any combination of these features. Though the appearance may seem like they are tightly coupled, this isn't actually the case. For example, one can obtain backup configurations from their current RANCID/Oxidized process and simply provide a Git Repo of the location of the backup configurations, and the compliance process would work the same way. Also, another user may only want to generate configurations, but not want to use other features, which is perfectly fine to do so. +> Developer Note: Add any representative screenshots of the App in action. These images should also be added to the `docs/user/app_use_cases.md` section. -## Screenshots +> Developer Note: Place the files in the `docs/images/` folder and link them using only full URLs from GitHub, for example: `![Overview](https://raw.githubusercontent.com/nautobot/nautobot-plugin-golden-config/develop/docs/images/plugin-overview.png)`. This absolute static linking is required to ensure the README renders properly in GitHub, the docs site, and any other external sites like PyPI. -There are many features and capabilities the plugin provides into the Nautobot ecosystem. The following screenshots are intended to provide a quick visual overview of some of these features. +More screenshots can be found in the [Using the App](https://docs.nautobot.com/projects/golden-config/en/latest/user/app_use_cases/) page in the documentation. Here's a quick overview of some of the plugin's added functionality: -The golden configuration is driven by jobs that run a series of tasks and the result is captured in this overview. - -![Overview](https://raw.githubusercontent.com/nautobot/nautobot-plugin-golden-config/develop/docs/images/ss_golden-overview.png) - -The compliance report provides a high-level overview on the compliance of your network. -![Compliance Report](https://raw.githubusercontent.com/nautobot/nautobot-plugin-golden-config/develop/docs/images/ss_compliance-report.png) - -The compliance overview will provide a per device and feature overview on the compliance of your network devices. -![Compliance Overview](https://raw.githubusercontent.com/nautobot/nautobot-plugin-golden-config/develop/docs/images/ss_compliance-overview.png) - -Drilling into a specific device and feature, you can get an immediate detailed understanding of your device. -![Compliance Device](https://raw.githubusercontent.com/nautobot/nautobot-plugin-golden-config/develop/docs/images/ss_compliance-device.png) - -![Compliance Rule](https://raw.githubusercontent.com/nautobot/nautobot-plugin-golden-config/develop/docs/images/ss_compliance-rule.png) +![](https://raw.githubusercontent.com/nautobot/nautobot-plugin-golden-config/develop/docs/images/placeholder.png) ## Try it out! +> Developer Note: Only keep this section if appropriate. Update link to correct sandbox. + This App is installed in the Nautobot Community Sandbox found over at [demo.nautobot.com](https://demo.nautobot.com/)! > For a full list of all the available always-on sandbox environments, head over to the main page on [networktocode.com](https://www.networktocode.com/nautobot/sandbox-environments/). ## Documentation -Full web-based HTML documentation for this app can be found over on the [Nautobot Docs](https://docs.nautobot.com/projects/golden-config/en/latest/) website: +Full documentation for this App can be found over on the [Nautobot Docs](https://docs.nautobot.com) website: -- [User Guide](https://docs.nautobot.com/projects/golden-config/en/latest/user/app_overview/) - Overview, Using the App, Getting Started, Navigating compliance (cli, json, custom), backup, app usage, intended state creation. -- [Administrator Guide](https://docs.nautobot.com/projects/golden-config/en/latest/admin/admin_install/) - How to Install, Configure, Upgrade, or Uninstall the App. -- [Developer Guide](https://docs.nautobot.com/projects/golden-config/en/latest/dev/dev_contributing/) - Extending the App, Code Reference, Contribution Guide. -- [Release Notes / Changelog](https://docs.nautobot.com/projects/golden-config/en/latest/admin/release_notes/) -- [Frequently Asked Questions](https://docs.nautobot.com/projects/golden-config/en/latest/user/app_faq/) +- [User Guide](https://docs.nautobot.com/projects/golden-config/en/latest/user/app_overview/) - Overview, Using the App, Getting Started. +- [Administrator Guide](https://docs.nautobot.com/projects/golden-config/en/latest/admin/install/) - How to Install, Configure, Upgrade, or Uninstall the App. +- [Developer Guide](https://docs.nautobot.com/projects/golden-config/en/latest/dev/contributing/) - Extending the App, Code Reference, Contribution Guide. +- [Release Notes / Changelog](https://docs.nautobot.com/projects/golden-config/en/latest/admin/release_notes/). +- [Frequently Asked Questions](https://docs.nautobot.com/projects/golden-config/en/latest/user/faq/). -### Contributing to the Docs +### Contributing to the Documentation -You can find all the Markdown source for the App documentation under the [docs](https://github.com/nautobot/nautobot-plugin-golden-config/tree/develop/docs) folder in this repository. For simple edits, a Markdown capable editor is sufficient - clone the repository and edit away. +You can find all the Markdown source for the App documentation under the [`docs`](https://github.com/nautobot/nautobot-plugin-golden-config/tree/develop/docs) folder in this repository. For simple edits, a Markdown capable editor is sufficient: clone the repository and edit away. -If you need to view the fully generated documentation site, you can build it with [mkdocs](https://www.mkdocs.org/). A container hosting the docs will be started using the invoke commands (details in the [Development Environment Guide](https://docs.nautobot.com/projects/golden-config/en/latest/dev/dev_environment/#docker-development-environment)) on [http://localhost:8001](http://localhost:8001). As your changes are saved, the live docs will be automatically reloaded. +If you need to view the fully-generated documentation site, you can build it with [MkDocs](https://www.mkdocs.org/). A container hosting the documentation can be started using the `invoke` commands (details in the [Development Environment Guide](https://docs.nautobot.com/projects/golden-config/en/latest/dev/dev_environment/#docker-development-environment)) on [http://localhost:8001](http://localhost:8001). Using this container, as your changes to the documentation are saved, they will be automatically rebuilt and any pages currently being viewed will be reloaded in your browser. Any PRs with fixes or improvements are very welcome! ## Questions -For any questions or comments, please check the [FAQ](https://docs.nautobot.com/projects/golden-config/en/latest/user/app_faq/) first. Feel free to also swing by the [Network to Code Slack](https://networktocode.slack.com/) (channel `#nautobot`), sign up [here](http://slack.networktocode.com/) if you don't have an account. +For any questions or comments, please check the [FAQ](https://docs.nautobot.com/projects/golden-config/en/latest/user/faq/) first. Feel free to also swing by the [Network to Code Slack](https://networktocode.slack.com/) (channel `#nautobot`), sign up [here](http://slack.networktocode.com/) if you don't have an account. diff --git a/development/Dockerfile b/development/Dockerfile index 7b596e27..34ba9b20 100644 --- a/development/Dockerfile +++ b/development/Dockerfile @@ -1,16 +1,16 @@ # ------------------------------------------------------------------------------------- -# Nautobot Plugin Development Dockerfile Template -# Version: 0.0.1 +# Nautobot App Developement Dockerfile Template +# Version: 1.1.0 # -# Plugins that need to add additional steps or packages can do in the section below. +# Apps that need to add additional steps or packages can do in the section below. # ------------------------------------------------------------------------------------- # !!! USE CAUTION WHEN MODIFYING LINES BELOW -# Accepts a desired Nautobot version as build argument, default to 2.0.0 -ARG NAUTOBOT_VER="2.0.0-rc.2" +# Accepts a desired Nautobot version as build argument, default to 1.4.0 +ARG NAUTOBOT_VER="1.4.0" -# Accepts a desired Python version as build argument, default to 3.11 -ARG PYTHON_VER="3.11" +# Accepts a desired Python version as build argument, default to 3.8 +ARG PYTHON_VER="3.8" # Retrieve published development image of Nautobot base which should include most CI dependencies FROM ghcr.io/nautobot/nautobot-dev:${NAUTOBOT_VER}-py${PYTHON_VER} @@ -26,26 +26,25 @@ ENV NAUTOBOT_ROOT ${NAUTOBOT_ROOT} # and CI and local development may have a newer version of Poetry # Since this is only used for development and we don't ship this container, pinning Poetry back is not expressly necessary # We also don't need virtual environments in container -RUN curl -sSL https://install.python-poetry.org -o /tmp/install-poetry.py && \ - python /tmp/install-poetry.py && \ - rm -f /tmp/install-poetry.py && \ - poetry config virtualenvs.create false +RUN curl -sSL https://install.python-poetry.org | python3 - && \ + poetry config virtualenvs.create false # !!! USE CAUTION WHEN MODIFYING LINES ABOVE # ------------------------------------------------------------------------------------- -# Plugin-specific system build/test dependencies. -# +# App-specifc system build/test dependencies. +# # Example: LDAP requires `libldap2-dev` to be apt-installed before the Python package. # ------------------------------------------------------------------------------------- # --> Start safe to modify section -# Uncomment the line below if you are apt-installing any package. -# RUN apt update -# RUN apt install libldap2-dev +# Uncomment the lines below if you are apt-installing any package. +# RUN apt-get -y update && apt-get -y install \ +# libldap2-dev \ +# && rm -rf /var/lib/apt/lists/* # --> Stop safe to modify section # ------------------------------------------------------------------------------------- -# Install Nautobot Plugin +# Install Nautobot App # ------------------------------------------------------------------------------------- # !!! USE CAUTION WHEN MODIFYING LINES BELOW @@ -54,7 +53,7 @@ WORKDIR /source COPY . /source # Get container's installed Nautobot version as a forced constraint -# NAUTOBOT_VER may be a branch name and not a published release therefore we need to get the installed version +# NAUTOBOT_VER may be a branch name and not a published release therefor we need to get the installed version # so pip can use it to recognize local constraints. RUN pip show nautobot | grep "^Version: " | sed -e 's/Version: /nautobot==/' > constraints.txt @@ -68,7 +67,7 @@ RUN poetry export -f requirements.txt --with dev --without-hashes --output poetr RUN sort poetry_freeze_base.txt poetry_freeze_all.txt | uniq -u > poetry_freeze_dev.txt # Install all local project as editable, constrained on Nautobot version, to get any additional -# direct dependencies of the plugin +# direct dependencies of the app RUN pip install -c constraints.txt -e . # Install any dev dependencies frozen from Poetry diff --git a/development/development.env b/development/development.env index 080a7c71..54f0b870 100644 --- a/development/development.env +++ b/development/development.env @@ -7,8 +7,6 @@ NAUTOBOT_BANNER_TOP="Local" NAUTOBOT_CHANGELOG_RETENTION=0 NAUTOBOT_DEBUG=True -NAUTOBOT_DJANGO_EXTENSIONS_ENABLED=True -NAUTOBOT_DJANGO_TOOLBAR_ENABLED=True NAUTOBOT_LOG_LEVEL=DEBUG NAUTOBOT_METRICS_ENABLED=True NAUTOBOT_NAPALM_TIMEOUT=5 @@ -38,14 +36,3 @@ POSTGRES_DB=${NAUTOBOT_DB_NAME} MYSQL_USER=${NAUTOBOT_DB_USER} MYSQL_DATABASE=${NAUTOBOT_DB_NAME} MYSQL_ROOT_HOST=% - -# Golden Configuration specific -PER_FEATURE_WIDTH=13 -PER_FEATURE_HEIGHT=4 -PER_FEATURE_BAR_WIDTH=0.15 -ENABLE_COMPLIANCE=True -ENABLE_INTENDED=True -ENABLE_BACKUP=True -ENABLE_SOTAGG=True -ENABLE_POSTPROCESSING=True -ALLOWED_OS=all diff --git a/development/docker-compose.base.yml b/development/docker-compose.base.yml index 26356204..6a0a4c72 100644 --- a/development/docker-compose.base.yml +++ b/development/docker-compose.base.yml @@ -22,13 +22,13 @@ services: db: condition: "service_healthy" <<: - - *nautobot-build - *nautobot-base + - *nautobot-build worker: entrypoint: - "sh" - "-c" # this is to evaluate the $NAUTOBOT_LOG_LEVEL from the env - - "nautobot-server celery worker -l $$NAUTOBOT_LOG_LEVEL" ## $$ because of docker-compose + - "nautobot-server celery worker -l $$NAUTOBOT_LOG_LEVEL --events" ## $$ because of docker-compose depends_on: - "nautobot" healthcheck: diff --git a/development/docker-compose.dev.yml b/development/docker-compose.dev.yml index b95ecb81..3374422a 100644 --- a/development/docker-compose.dev.yml +++ b/development/docker-compose.dev.yml @@ -12,13 +12,8 @@ services: volumes: - "./nautobot_config.py:/opt/nautobot/nautobot_config.py" - "../:/source" - # Helper method to mount on top of the python implementations, assuming you are using py3.11 and - # have all of your projects in the same directory. Uncomment out as required. - # - "../../netutils/netutils:/opt/nautobot/lib/python3.11/site-packages/netutils" - # - "../../nornir-nautobot/nornir_nautobot:/opt/nautobot/lib/python3.11/site-packages/nornir_nautobot" - # - "../../nautobot-plugin-nornir/nautobot_plugin_nornir:/opt/nautobot/lib/python3.11/site-packages/nautobot_plugin_nornir" - # - "../../nautobot/nautobot:/opt/nautobot/lib/python3.11/site-packages/nautobot" - + healthcheck: + test: ["CMD", "true"] # Due to layering, disable: true won't work. Instead, change the test docs: entrypoint: "mkdocs serve -v -a 0.0.0.0:8080" ports: @@ -30,15 +25,15 @@ services: disable: true tty: true worker: + entrypoint: + - "sh" + - "-c" # this is to evaluate the $NAUTOBOT_LOG_LEVEL from the env + - "watchmedo auto-restart --directory './' --pattern '*.py' --recursive -- nautobot-server celery worker -l $$NAUTOBOT_LOG_LEVEL --events" ## $$ because of docker-compose volumes: - "./nautobot_config.py:/opt/nautobot/nautobot_config.py" - "../:/source" - # Helper method to mount on top of the python implementations, assuming you are using py3.11 and - # have all of your projects in the same directory. Uncomment out as required. - # - "../../netutils/netutils:/opt/nautobot/lib/python3.11/site-packages/netutils" - # - "../../nornir-nautobot/nornir_nautobot:/opt/nautobot/lib/python3.11/site-packages/nornir_nautobot" - # - "../../nautobot-plugin-nornir/nautobot_plugin_nornir:/opt/nautobot/lib/python3.11/site-packages/nautobot_plugin_nornir" - # - "../../nautobot/nautobot:/opt/nautobot/lib/python3.11/site-packages/nautobot" + healthcheck: + test: ["CMD", "true"] # Due to layering, disable: true won't work. Instead, change the test # To expose postgres or redis to the host uncomment the following # postgres: # ports: diff --git a/development/docker-compose.mysql.yml b/development/docker-compose.mysql.yml index c7fa6a1f..062ada94 100644 --- a/development/docker-compose.mysql.yml +++ b/development/docker-compose.mysql.yml @@ -20,6 +20,7 @@ services: image: "mysql:8" command: - "--default-authentication-plugin=mysql_native_password" + - "--max_connections=1000" env_file: - "development.env" - "creds.env" @@ -27,7 +28,12 @@ services: volumes: - "mysql_data:/var/lib/mysql" healthcheck: - test: ["CMD", "mysqladmin", "ping", "-h", "localhost"] + test: + - "CMD" + - "mysqladmin" + - "ping" + - "-h" + - "localhost" timeout: "20s" retries: 10 volumes: diff --git a/development/docker-compose.postgres.yml b/development/docker-compose.postgres.yml index 55afdb70..12d1de31 100644 --- a/development/docker-compose.postgres.yml +++ b/development/docker-compose.postgres.yml @@ -7,11 +7,13 @@ services: - "NAUTOBOT_DB_ENGINE=django.db.backends.postgresql" db: image: "postgres:13-alpine" + command: + - "-c" + - "max_connections=200" env_file: - "development.env" - "creds.env" volumes: - # - "./nautobot.sql:/tmp/nautobot.sql" - "postgres_data:/var/lib/postgresql/data" healthcheck: test: "pg_isready --username=$$POSTGRES_USER --dbname=$$POSTGRES_DB" diff --git a/development/nautobot_config.py b/development/nautobot_config.py index 546c4417..f397ef56 100644 --- a/development/nautobot_config.py +++ b/development/nautobot_config.py @@ -1,13 +1,24 @@ """Nautobot development configuration file.""" -# pylint: disable=invalid-envvar-default import os import sys -from django.utils.module_loading import import_string - -from nautobot.core.settings import * # noqa: F403 +from nautobot.core.settings import * # noqa: F403 # pylint: disable=wildcard-import,unused-wildcard-import from nautobot.core.settings_funcs import is_truthy, parse_redis_connection +# +# Debug +# + +DEBUG = is_truthy(os.getenv("NAUTOBOT_DEBUG", False)) +_TESTING = len(sys.argv) > 1 and sys.argv[1] == "test" + +if DEBUG and not _TESTING: + DEBUG_TOOLBAR_CONFIG = {"SHOW_TOOLBAR_CALLBACK": lambda _request: True} + + if "debug_toolbar" not in INSTALLED_APPS: # noqa: F405 + INSTALLED_APPS.append("debug_toolbar") # noqa: F405 + if "debug_toolbar.middleware.DebugToolbarMiddleware" not in MIDDLEWARE: # noqa: F405 + MIDDLEWARE.insert(0, "debug_toolbar.middleware.DebugToolbarMiddleware") # noqa: F405 # # Misc. settings @@ -16,6 +27,9 @@ ALLOWED_HOSTS = os.getenv("NAUTOBOT_ALLOWED_HOSTS", "").split(" ") SECRET_KEY = os.getenv("NAUTOBOT_SECRET_KEY", "") +# +# Database +# nautobot_db_engine = os.getenv("NAUTOBOT_DB_ENGINE", "django.db.backends.postgresql") default_db_settings = { @@ -45,18 +59,28 @@ DATABASES["default"]["OPTIONS"] = {"charset": "utf8mb4"} # -# Debug +# Redis # -DEBUG = True +# The django-redis cache is used to establish concurrent locks using Redis. +CACHES = { + "default": { + "BACKEND": "django_redis.cache.RedisCache", + "LOCATION": parse_redis_connection(redis_database=0), + "TIMEOUT": 300, + "OPTIONS": { + "CLIENT_CLASS": "django_redis.client.DefaultClient", + }, + } +} -# Django Debug Toolbar -DEBUG_TOOLBAR_CONFIG = {"SHOW_TOOLBAR_CALLBACK": lambda _request: DEBUG and not TESTING} +# Redis Cacheops +CACHEOPS_REDIS = parse_redis_connection(redis_database=1) -if DEBUG and "debug_toolbar" not in INSTALLED_APPS: # noqa: F405 - INSTALLED_APPS.append("debug_toolbar") # noqa: F405 -if DEBUG and "debug_toolbar.middleware.DebugToolbarMiddleware" not in MIDDLEWARE: # noqa: F405 - MIDDLEWARE.insert(0, "debug_toolbar.middleware.DebugToolbarMiddleware") # noqa: F405 +# +# Celery settings are not defined here because they can be overloaded with +# environment variables. By default they use `CACHES["default"]["LOCATION"]`. +# # # Logging @@ -64,10 +88,8 @@ LOG_LEVEL = "DEBUG" if DEBUG else "INFO" -TESTING = len(sys.argv) > 1 and sys.argv[1] == "test" - # Verbose logging during normal development operation, but quiet logging during unit test execution -if not TESTING: +if not _TESTING: LOGGING = { "version": 1, "disable_existing_loggers": False, @@ -101,114 +123,19 @@ }, }, } -else: - LOGGING = {} - -# -# Redis -# - -# The django-redis cache is used to establish concurrent locks using Redis. The -# django-rq settings will use the same instance/database by default. -# -# This "default" server is now used by RQ_QUEUES. -# >> See: nautobot.core.settings.RQ_QUEUES -CACHES = { - "default": { - "BACKEND": "django_redis.cache.RedisCache", - "LOCATION": parse_redis_connection(redis_database=0), - "TIMEOUT": 300, - "OPTIONS": { - "CLIENT_CLASS": "django_redis.client.DefaultClient", - }, - } -} - -# RQ_QUEUES is not set here because it just uses the default that gets imported -# up top via `from nautobot.core.settings import *`. - -# Redis Cacheops -CACHEOPS_REDIS = parse_redis_connection(redis_database=1) # -# Celery settings are not defined here because they can be overloaded with -# environment variables. By default they use `CACHES["default"]["LOCATION"]`. +# Apps # - -# Enable installed plugins. Add the name of each plugin to the list. -PLUGINS = ["nautobot_plugin_nornir", "nautobot_golden_config"] - -# Plugins configuration settings. These settings are used by various plugins that the user may have installed. -# Each key in the dictionary is the name of an installed plugin and its value is a dictionary of settings. -PLUGINS_CONFIG = { - "nautobot_plugin_nornir": { - "nornir_settings": { - "credentials": "nautobot_plugin_nornir.plugins.credentials.env_vars.CredentialsEnvVars", - "runner": { - "plugin": "threaded", - "options": { - "num_workers": 20, - }, - }, - }, - # dispatcher_mapping may be necessary if you get an error `Cannot import "". Is the library installed?` - # when you run a backup job, and is the name of the platform applied to the device. - # to the Nornir driver names ("arista_eos", "cisco_ios", etc.). - # "dispatcher_mapping": { - # "eos": "nornir_nautobot.plugins.tasks.dispatcher.arista_eos.NautobotNornirDriver", - # "arbitrary_platform_name": "nornir_nautobot.plugins.tasks.dispatcher.arista_eos.NautobotNornirDriver", - # "ios": "nornir_nautobot.plugins.tasks.dispatcher.cisco_ios.NautobotNornirDriver", - # "iosxe": "nornir_nautobot.plugins.tasks.dispatcher.cisco_ios.NautobotNornirDriver", - # "junos": "nornir_nautobot.plugins.tasks.dispatcher.juniper_junos.NautobotNornirDriver", - # "nxos": "nornir_nautobot.plugins.tasks.dispatcher.cisco_nxos.NautobotNornirDriver", - # }, - }, - "nautobot_golden_config": { - "per_feature_bar_width": float(os.environ.get("PER_FEATURE_BAR_WIDTH", 0.15)), - "per_feature_width": int(os.environ.get("PER_FEATURE_WIDTH", 13)), - "per_feature_height": int(os.environ.get("PER_FEATURE_HEIGHT", 4)), - "enable_backup": is_truthy(os.environ.get("ENABLE_BACKUP", True)), - "enable_compliance": is_truthy(os.environ.get("ENABLE_COMPLIANCE", True)), - "enable_intended": is_truthy(os.environ.get("ENABLE_INTENDED", True)), - "enable_sotagg": is_truthy(os.environ.get("ENABLE_SOTAGG", True)), - "sot_agg_transposer": os.environ.get("SOT_AGG_TRANSPOSER"), - "enable_postprocessing": is_truthy(os.environ.get("ENABLE_POSTPROCESSING", True)), - "postprocessing_callables": os.environ.get("POSTPROCESSING_CALLABLES", []), - "postprocessing_subscribed": os.environ.get("POSTPROCESSING_SUBSCRIBED", []), - "jinja_env": { - "undefined": import_string("jinja2.StrictUndefined"), - "trim_blocks": is_truthy(os.getenv("NAUTOBOT_JINJA_ENV_TRIM_BLOCKS", True)), - "lstrip_blocks": is_truthy(os.getenv("NAUTOBOT_JINJA_ENV_LSTRIP_BLOCKS", False)), - }, - # The platform_network_driver_map maps an arbitrary platform network_driver to its corresponding parser. - # Use this if the platform network_driver names in your Nautobot instance don't correspond exactly - # to the Nornir driver names ("arista_eos", "cisco_ios", etc.). - # Each key should == the network_driver of the Nautobot platform object. - # "platform_network_driver_map": { - # "eos": "arista_eos", - # "ios": "cisco_ios", - # "iosxe": "cisco_ios", - # "junos": "juniper_junos", - # "nxos": "cisco_nxos", - # }, - # "get_custom_compliance": "my.custom_compliance.func", - }, -} - -# Modify django_jinja Environment for test cases -django_jinja_config = None -for template in TEMPLATES: - if template["BACKEND"].startswith("django_jinja"): - django_jinja_config = template - -if django_jinja_config is not None: - jinja_options = django_jinja_config.get("OPTIONS") - if not jinja_options: - jinja_options = {} - django_jinja_config["OPTIONS"] = jinja_options - # Default behavior ignores UndefinedErrors - jinja_options["undefined"] = "jinja2.StrictUndefined" - -# Import filter function to have it register filter with django_jinja -from nautobot_golden_config.tests import jinja_filters # noqa: E402 +# Enable installed Apps. Add the name of each App to the list. +PLUGINS = ["nautobot_golden_config"] + +# Apps configuration settings. These settings are used by various Apps that the user may have installed. +# Each key in the dictionary is the name of an installed App and its value is a dictionary of settings. +# PLUGINS_CONFIG = { +# 'nautobot_golden_config': { +# 'foo': 'bar', +# 'buzz': 'bazz' +# } +# } diff --git a/docs/admin/compatibility_matrix.md b/docs/admin/compatibility_matrix.md index 5b6e64ae..acd191eb 100644 --- a/docs/admin/compatibility_matrix.md +++ b/docs/admin/compatibility_matrix.md @@ -1,18 +1,8 @@ # Compatibility Matrix -Changes to the support of upstream Nautobot releases will be announced 1 minor or major version ahead. - -The **deprecation policy** will be announced within the [release notes](../release_notes), and updated in the table below. There will be a `stable-.` branch that will be minimally maintained. Any security enhancements or major bugs in that branch will be supported for a limited time. - -While that last supported version will not be strictly enforced via the `max_version` setting, any issues with an updated Nautobot supported version in a minor release will require raising a bug and fixing it in Nautobot core, with no fixes expected in this plugin. This allows the Golden Config plugin the ability to quickly take advantage of the latest features in Nautobot. +!!! warning "Developer Note - Remove Me!" + Explain how the release models of the plugin and of Nautobot work together, how releases are supported, how features and older releases are deprecated etc. | Golden Config Version | Nautobot First Support Version | Nautobot Last Support Version | -| --------------------- | ------------------------------ | ----------------------------- | -| 0.9.X | 1.0.0 | 1.2.99 [Official] | -| 0.10.X | 1.0.0 | 1.2.99 [Official] | -| 1.0.X | 1.2.0 | 1.3.99 [Official] | -| 1.1.X | 1.2.0 | 1.3.99 [Official] | -| 1.2.X | 1.4.0 | 1.5.2 [Official] | -| 1.3.X | 1.4.0 | 1.5.2 [Official] | -| 1.4.X | 1.5.3 | 1.5.99 [Official] | -| 1.5.X | 1.6.1 | 1.6.99 [Official] | +| ------------- | -------------------- | ------------- | +| 1.0.X | 1.4.0 | 1.99.99 | diff --git a/docs/admin/install.md b/docs/admin/install.md new file mode 100644 index 00000000..2e06f44f --- /dev/null +++ b/docs/admin/install.md @@ -0,0 +1,81 @@ +# Installing the App in Nautobot + +Here you will find detailed instructions on how to **install** and **configure** the App within your Nautobot environment. + +!!! warning "Developer Note - Remove Me!" + Detailed instructions on installing the App. You will need to update this section based on any additional dependencies or prerequisites. + +## Prerequisites + +- The plugin is compatible with Nautobot 1.4.0 and higher. +- Databases supported: PostgreSQL, MySQL + +!!! note + Please check the [dedicated page](compatibility_matrix.md) for a full compatibility matrix and the deprecation policy. + +### Access Requirements + +!!! warning "Developer Note - Remove Me!" + What external systems (if any) it needs access to in order to work. + +## Install Guide + +!!! note + Plugins can be installed manually or using Python's `pip`. See the [nautobot documentation](https://nautobot.readthedocs.io/en/latest/plugins/#install-the-package) for more details. The pip package name for this plugin is [`nautobot-golden-config`](https://pypi.org/project/nautobot-golden-config/). + +The plugin is available as a Python package via PyPI and can be installed with `pip`: + +```shell +pip install nautobot-golden-config +``` + +To ensure Golden Config is automatically re-installed during future upgrades, create a file named `local_requirements.txt` (if not already existing) in the Nautobot root directory (alongside `requirements.txt`) and list the `nautobot-golden-config` package: + +```shell +echo nautobot-golden-config >> local_requirements.txt +``` + +Once installed, the plugin needs to be enabled in your Nautobot configuration. The following block of code below shows the additional configuration required to be added to your `nautobot_config.py` file: + +- Append `"nautobot_golden_config"` to the `PLUGINS` list. +- Append the `"nautobot_golden_config"` dictionary to the `PLUGINS_CONFIG` dictionary and override any defaults. + +```python +# In your nautobot_config.py +PLUGINS = ["nautobot_golden_config"] + +# PLUGINS_CONFIG = { +# "nautobot_golden_config": { +# ADD YOUR SETTINGS HERE +# } +# } +``` + +Once the Nautobot configuration is updated, run the Post Upgrade command (`nautobot-server post_upgrade`) to run migrations and clear any cache: + +```shell +nautobot-server post_upgrade +``` + +Then restart (if necessary) the Nautobot services which may include: + +- Nautobot +- Nautobot Workers +- Nautobot Scheduler + +```shell +sudo systemctl restart nautobot nautobot-worker nautobot-scheduler +``` + +## App Configuration + +!!! warning "Developer Note - Remove Me!" + Any configuration required to get the App set up. Edit the table below as per the examples provided. + +The plugin behavior can be controlled with the following list of settings: + +| Key | Example | Default | Description | +| ------- | ------ | -------- | ------------------------------------- | +| `enable_backup` | `True` | `True` | A boolean to represent whether or not to run backup configurations within the plugin. | +| `platform_slug_map` | `{"cisco_wlc": "cisco_aireos"}` | `None` | A dictionary in which the key is the platform slug and the value is what netutils uses in any "network_os" parameter. | +| `per_feature_bar_width` | `0.15` | `0.15` | The width of the table bar within the overview report | diff --git a/docs/admin/release_notes/version_1.0.md b/docs/admin/release_notes/version_1.0.md index 136334d5..4a9c9a8b 100644 --- a/docs/admin/release_notes/version_1.0.md +++ b/docs/admin/release_notes/version_1.0.md @@ -1,64 +1,48 @@ # v1.0 Release Notes -- Added support for Jinja2Filters to be be used in configuration generation -- Added support for multiple repos -- Add Git datasource to load GC properties -- Added support for nautobot secrets group on git repos -- Changed the release policy -- Updated navigation to a dedicated top level menu +!!! warning "Developer Note - Remove Me!" + Guiding Principles: -## v1.0.3 - 2022-06 + - Changelogs are for humans, not machines. + - There should be an entry for every single version. + - The same types of changes should be grouped. + - Versions and sections should be linkable. + - The latest version comes first. + - The release date of each version is displayed. + - Mention whether you follow Semantic Versioning. -### Fixed + Types of changes: -- [#257](https://github.com/nautobot/nautobot-plugin-golden-config/issues/257) Resolved template_content displaying SoT AGG link on Device detail page if Device not in scope of GoldenConfigSetting - - Change to pull version from package instead of static variable + - `Added` for new features. + - `Changed` for changes in existing functionality. + - `Deprecated` for soon-to-be removed features. + - `Removed` for now removed features. + - `Fixed` for any bug fixes. + - `Security` in case of vulnerabilities. -## v1.0.2 - 2022-05 -### Fixed +This document describes all new features and changes in the release `1.0`. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## Release Overview + +- Major features or milestones +- Achieved in this `x.y` release +- Changes to compatibility with Nautobot and/or other plugins, libraries etc. + +## [v1.0.1] - 2021-09-08 -- [#246](https://github.com/nautobot/nautobot-plugin-golden-config/issues/246) Dependabot update to Docker redis-7.x -- [#233](https://github.com/nautobot/nautobot-plugin-golden-config/issues/233) Dependabot update to paramiko-2.10.1 -- [#251](https://github.com/nautobot/nautobot-plugin-golden-config/issues/251) Add description to CSV config replace export +### Added -## v1.0.1 - 2022-05 +### Changed ### Fixed -- [#238](https://github.com/nautobot/nautobot-plugin-golden-config/issues/238) Fixed repo/docs/homepage links for PyPI -- [#243](https://github.com/nautobot/nautobot-plugin-golden-config/issues/243) Removing unneed javascript source as it is part of [#243](https://github.com/nautobot/nautobot-plugin-golden-config/pull/243) +- [#123](https://github.com/nautobot/nautobot-plugin-golden-config/issues/123) Fixed Tag filtering not working in job launch form -## v1.0.0 - 2022-04 +## [v1.0.0] - 2021-08-03 ### Added -- [#180](https://github.com/nautobot/nautobot-plugin-golden-config/issues/180) Added Renovate for proactive package management -- [#158](https://github.com/nautobot/nautobot-plugin-golden-config/issues/158) Allow for Jinja2 Filters to be used by GoldenConfig templates -- [#167](https://github.com/nautobot/nautobot-plugin-golden-config/issues/167) Added support for multiple repos -- [#205](https://github.com/nautobot/nautobot-plugin-golden-config/issues/205) Added support for multiple repos via multiple golden config settings -- [#206](https://github.com/nautobot/nautobot-plugin-golden-config/issues/206) Add Git datasource to load GC properties -- [#218](https://github.com/nautobot/nautobot-plugin-golden-config/issues/218) Added ability to storre SoTAgg field leveraging Nautobot saved GraphQl query -- [#225](https://github.com/nautobot/nautobot-plugin-golden-config/issues/225) Added support for nautobot secrets group on git repos -- [#234](https://github.com/nautobot/nautobot-plugin-golden-config/issues/234) Minor update to FAQ - ### Changed -- [#171](https://github.com/nautobot/nautobot-plugin-golden-config/issues/171) Changed the release policy -- [#158](https://github.com/nautobot/nautobot-plugin-golden-config/issues/158) Changed variable job_result to nautobot_job -- [#186](https://github.com/nautobot/nautobot-plugin-golden-config/issues/186) Update mariadb Docker tag to v10.7 -- [#187](https://github.com/nautobot/nautobot-plugin-golden-config/issues/187) Update postgres Docker tag to v14 -- [#188](https://github.com/nautobot/nautobot-plugin-golden-config/issues/188) Update Markdown dependency -- [#190](https://github.com/nautobot/nautobot-plugin-golden-config/issues/190) Update to Nautobot 1.2.0 -- [#190](https://github.com/nautobot/nautobot-plugin-golden-config/issues/190) Remove Nautobot 1.0 specific code -- [#211](https://github.com/nautobot/nautobot-plugin-golden-config/issues/211) Update dependency mariadb to v10.8 -- [#229](https://github.com/nautobot/nautobot-plugin-golden-config/issues/229) Updated navigation to a dedicated top level menu - ### Fixed - -- [#176](https://github.com/nautobot/nautobot-plugin-golden-config/issues/176) Fixed Pylint issue -- [#182](https://github.com/nautobot/nautobot-plugin-golden-config/issues/182) Add reference to Nornir plugin for installation -- [#183](https://github.com/nautobot/nautobot-plugin-golden-config/issues/183) Fixed documentation for sot_agg_transposer default -- [#184](https://github.com/nautobot/nautobot-plugin-golden-config/issues/184) Fix markdown links in quick-start -- [#194](https://github.com/nautobot/nautobot-plugin-golden-config/issues/194) Detailed Error Handling in get_job_filter helper -- [#229](https://github.com/nautobot/nautobot-plugin-golden-config/issues/229) Fixed [#165](https://github.com/nautobot/nautobot-plugin-golden-config/pull/165), Configuration Compliance List View "Device" filter doesn't work diff --git a/docs/admin/uninstall.md b/docs/admin/uninstall.md new file mode 100644 index 00000000..a30679d5 --- /dev/null +++ b/docs/admin/uninstall.md @@ -0,0 +1,18 @@ +# Uninstall the App from Nautobot + +Here you will find any steps necessary to cleanly remove the App from your Nautobot environment. + +## Database Cleanup + +Prior to removing the plugin from the `nautobot_config.py`, run the following command to roll back any migration specific to this plugin. + +```shell +nautobot-server migrate nautobot_plugin_golden_config zero +``` + +!!! warning "Developer Note - Remove Me!" + Any other cleanup operations to ensure the database is clean after the app is removed. Is there anything else that needs cleaning up, such as CFs, relationships, etc. if they're no longer desired? + +## Remove App configuration + +Remove the configuration you added in `nautobot_config.py` from `PLUGINS` & `PLUGINS_CONFIG`. diff --git a/docs/admin/upgrade.md b/docs/admin/upgrade.md new file mode 100644 index 00000000..3b87d56f --- /dev/null +++ b/docs/admin/upgrade.md @@ -0,0 +1,10 @@ +# Upgrading the App + +Here you will find any steps necessary to upgrade the App in your Nautobot environment. + +## Upgrade Guide + +!!! warning "Developer Note - Remove Me!" + Add more detailed steps on how the app is upgraded in an existing Nautobot setup and any version specifics (such as upgrading between major versions with breaking changes). + +When a new release comes out it may be necessary to run a migration of the database to account for any changes in the data models used by this plugin. Execute the command `nautobot-server post-upgrade` within the runtime environment of your Nautobot installation after updating the `nautobot-golden-config` package via `pip`. diff --git a/docs/assets/extra.css b/docs/assets/extra.css index 131cef77..dfe2e4b1 100644 --- a/docs/assets/extra.css +++ b/docs/assets/extra.css @@ -18,6 +18,15 @@ font-size: 0.7rem; } +/* +* The default max-width is 61rem which does not provide nearly enough space to present code examples or larger tables +*/ +.md-grid { + margin-left: auto; + margin-right: auto; + max-width: 95%; +} + .md-tabs__link { font-size: 0.8rem; } @@ -39,7 +48,7 @@ } img.logo { - height: 100px; + height: 200px; } img.copyright-logo { @@ -85,3 +94,68 @@ a.autorefs-external::after { a.autorefs-external:hover::after { background-color: var(--md-accent-fg-color); } + + +/* Customization for mkdocs-version-annotations */ +:root { + /* Icon for "version-added" admonition: Material Design Icons "plus-box-outline" */ + --md-admonition-icon--version-added: url('data:image/svg+xml;charset=utf-8,'); + /* Icon for "version-changed" admonition: Material Design Icons "delta" */ + --md-admonition-icon--version-changed: url('data:image/svg+xml;charset=utf-8,'); + /* Icon for "version-removed" admonition: Material Design Icons "minus-circle-outline" */ + --md-admonition-icon--version-removed: url('data:image/svg+xml;charset=utf-8,'); +} + +/* "version-added" admonition in green */ +.md-typeset .admonition.version-added, +.md-typeset details.version-added { + border-color: rgb(0, 200, 83); +} + +.md-typeset .version-added>.admonition-title, +.md-typeset .version-added>summary { + background-color: rgba(0, 200, 83, .1); +} + +.md-typeset .version-added>.admonition-title::before, +.md-typeset .version-added>summary::before { + background-color: rgb(0, 200, 83); + -webkit-mask-image: var(--md-admonition-icon--version-added); + mask-image: var(--md-admonition-icon--version-added); +} + +/* "version-changed" admonition in orange */ +.md-typeset .admonition.version-changed, +.md-typeset details.version-changed { + border-color: rgb(255, 145, 0); +} + +.md-typeset .version-changed>.admonition-title, +.md-typeset .version-changed>summary { + background-color: rgba(255, 145, 0, .1); +} + +.md-typeset .version-changed>.admonition-title::before, +.md-typeset .version-changed>summary::before { + background-color: rgb(255, 145, 0); + -webkit-mask-image: var(--md-admonition-icon--version-changed); + mask-image: var(--md-admonition-icon--version-changed); +} + +/* "version-removed" admonition in red */ +.md-typeset .admonition.version-removed, +.md-typeset details.version-removed { + border-color: rgb(255, 82, 82); +} + +.md-typeset .version-removed>.admonition-title, +.md-typeset .version-removed>summary { + background-color: rgba(255, 82, 82, .1); +} + +.md-typeset .version-removed>.admonition-title::before, +.md-typeset .version-removed>summary::before { + background-color: rgb(255, 82, 82); + -webkit-mask-image: var(--md-admonition-icon--version-removed); + mask-image: var(--md-admonition-icon--version-removed); +} diff --git a/docs/assets/overrides/partials/copyright.html b/docs/assets/overrides/partials/copyright.html index e0b77e5f..b92cf5e3 100644 --- a/docs/assets/overrides/partials/copyright.html +++ b/docs/assets/overrides/partials/copyright.html @@ -1,3 +1,4 @@ +
{% if config.copyright %}
@@ -18,3 +19,4 @@
+ diff --git a/docs/dev/arch_decision.md b/docs/dev/arch_decision.md new file mode 100644 index 00000000..e7bcbbe4 --- /dev/null +++ b/docs/dev/arch_decision.md @@ -0,0 +1,7 @@ +# Architecture Decision Records + +The intention is to document deviations from a standard Model View Controller (MVC) design. + +!!! warning "Developer Note - Remove Me!" + Optional page, remove if not applicable. + For examples see [Golden Config](https://github.com/nautobot/nautobot-plugin-golden-config/tree/develop/docs/dev/dev_adr.md) and [nautobot-plugin-reservation](https://github.com/networktocode/nautobot-plugin-reservation/blob/develop/docs/dev/dev_adr.md). diff --git a/docs/dev/code_reference/api.md b/docs/dev/code_reference/api.md index ae2a8545..2ce5c164 100644 --- a/docs/dev/code_reference/api.md +++ b/docs/dev/code_reference/api.md @@ -3,4 +3,3 @@ ::: nautobot_golden_config.api options: show_submodules: True - #docstring_section_style: spacy diff --git a/docs/dev/code_reference/index.md b/docs/dev/code_reference/index.md index 473f2c40..ebe9ff7d 100644 --- a/docs/dev/code_reference/index.md +++ b/docs/dev/code_reference/index.md @@ -1,3 +1,6 @@ # Code Reference Auto-generated code reference documentation from docstrings. + +!!! warning "Developer Note - Remove Me!" + Uses [mkdocstrings](https://mkdocstrings.github.io/) syntax to auto-generate code documentation from docstrings. Two example pages are provided ([api](api.md) and [package](package.md)), add new stubs for each module or package that you think has relevant documentation. diff --git a/docs/dev/code_reference/package.md b/docs/dev/code_reference/package.md new file mode 100644 index 00000000..8a3cfda5 --- /dev/null +++ b/docs/dev/code_reference/package.md @@ -0,0 +1 @@ +::: nautobot_golden_config diff --git a/docs/dev/contributing.md b/docs/dev/contributing.md new file mode 100644 index 00000000..2337f740 --- /dev/null +++ b/docs/dev/contributing.md @@ -0,0 +1,24 @@ +# Contributing to the App + +!!! warning "Developer Note - Remove Me!" + Information on how to contribute fixes, functionality, or documentation changes back to the project. + +The project is packaged with a light [development environment](dev_environment.md) based on `docker-compose` to help with the local development of the project and to run tests. + +The project is following Network to Code software development guidelines and is leveraging the following: + +- Python linting and formatting: `black`, `pylint`, `bandit`, `flake8`, and `pydocstyle`. +- YAML linting is done with `yamllint`. +- Django unit test to ensure the plugin is working properly. + +Documentation is built using [mkdocs](https://www.mkdocs.org/). The [Docker based development environment](dev_environment.md#docker-development-environment) automatically starts a container hosting a live version of the documentation website on [http://localhost:8001](http://localhost:8001) that auto-refreshes when you make any changes to your local files. + +## Branching Policy + +!!! warning "Developer Note - Remove Me!" + What branching policy is used for this project and where contributions should be made. + +## Release Policy + +!!! warning "Developer Note - Remove Me!" + How new versions are released. diff --git a/docs/dev/dev_environment.md b/docs/dev/dev_environment.md index 1d55d564..a81a5c3c 100644 --- a/docs/dev/dev_environment.md +++ b/docs/dev/dev_environment.md @@ -1,11 +1,11 @@ # Building Your Development Environment -## Quickstart +## Quickstart Guide The development environment can be used in two ways: -1. `Recommended` All services are spun up using Docker and a local volume mount attached so you can develop locally, but Nautobot is spun up within the Docker container. -2. With a local poetry environment if you wish to develop outside of Docker with the caveat of using external services provided by Docker for PostgresQL and Redis. +1. **(Recommended)** All services, including Nautobot, are spun up using Docker containers and a volume mount so you can develop locally. +2. With a local Poetry environment if you wish to develop outside of Docker, with the caveat of using external services provided by Docker for the database (PostgreSQL by default, MySQL optionally) and Redis services. This is a quick reference guide if you're already familiar with the development environment provided, which you can read more about later in this document. @@ -14,8 +14,8 @@ This is a quick reference guide if you're already familiar with the development The [Invoke](http://www.pyinvoke.org/) library is used to provide some helper commands based on the environment. There are a few configuration parameters which can be passed to Invoke to override the default configuration: - `nautobot_ver`: the version of Nautobot to use as a base for any built docker containers (default: latest) -- `project_name`: the default docker compose project name (default: `nautobot_golden_config`) -- `python_ver`: the version of Python to use as a base for any built docker containers (default: 3.11) +- `project_name`: the default docker compose project name (default: `nautobot-golden-config`) +- `python_ver`: the version of Python to use as a base for any built docker containers (default: 3.8) - `local`: a boolean flag indicating if invoke tasks should be run on the host or inside the docker containers (default: False, commands will be run in docker containers) - `compose_dir`: the full path to a directory containing the project compose files - `compose_files`: a list of compose files applied in order (see [Multiple Compose files](https://docs.docker.com/compose/extends/#multiple-compose-files) for more information) @@ -66,7 +66,7 @@ Run the following commands: ```shell poetry shell poetry install --extras nautobot -export $(cat development/development.env | xargs) +export $(cat development/dev.env | xargs) export $(cat development/creds.env | xargs) invoke start && sleep 5 nautobot-server migrate @@ -101,12 +101,9 @@ The project features a CLI helper based on [Invoke](https://www.pyinvoke.org/) t Each command can be executed with `invoke `. All commands support the arguments `--nautobot-ver` and `--python-ver` if you want to manually define the version of Python and Nautobot to use. Each command also has its own help `invoke --help` -!!! note - To run the mysql (mariadb) development environment, set the environment variable as such `export NAUTOBOT_USE_MYSQL=1`. - #### Local Development Environment -```shell +``` build Build all docker images. debug Start Nautobot and its dependencies in debug mode. destroy Destroy all containers and volumes. @@ -117,7 +114,7 @@ Each command can be executed with `invoke `. All commands support the a #### Utility -```shell +``` cli Launch a bash shell inside the running Nautobot container. create-user Create a new user in django (default: admin), will prompt for password. makemigrations Run Make Migration in Django. @@ -126,7 +123,7 @@ Each command can be executed with `invoke `. All commands support the a #### Testing -```shell +``` bandit Run bandit to validate basic static code security analysis. black Run black to check that Python files adhere to its style standards. flake8 Run flake8 to check that Python files adhere to its style standards. @@ -161,8 +158,6 @@ The `poetry shell` command is used to create and enable a virtual environment ma For more details about Poetry and its commands please check out its [online documentation](https://python-poetry.org/docs/). - - ## Full Docker Development Environment This project is set up with a number of **Invoke** tasks consumed as simple CLI commands to get developing fast. You'll use a few `invoke` commands to get your environment up and running. @@ -187,7 +182,7 @@ The first thing you need to do is build the necessary Docker image for Nautobot #14 exporting layers #14 exporting layers 1.2s done #14 writing image sha256:2d524bc1665327faa0d34001b0a9d2ccf450612bf8feeb969312e96a2d3e3503 done -#14 naming to docker.io/nautobot-golden-config/nautobot:latest-py3.11 done +#14 naming to docker.io/nautobot-golden-config/nautobot:latest-py3.7 done ``` ### Invoke - Starting the Development Environment @@ -218,9 +213,9 @@ This will start all of the Docker containers used for hosting Nautobot. You shou ```bash ➜ docker ps ****CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES -ee90fbfabd77 nautobot-golden-config/nautobot:latest-py3.11 "nautobot-server rqw…" 16 seconds ago Up 13 seconds nautobot_golden_config_worker_1 -b8adb781d013 nautobot-golden-config/nautobot:latest-py3.11 "/docker-entrypoint.…" 20 seconds ago Up 15 seconds 0.0.0.0:8080->8080/tcp, :::8080->8080/tcp nautobot_golden_config_nautobot_1 -d64ebd60675d nautobot-golden-config/nautobot:latest-py3.11 "mkdocs serve -v -a …" 25 seconds ago Up 18 seconds 0.0.0.0:8001->8080/tcp, :::8001->8080/tcp nautobot_golden_config_docs_1 +ee90fbfabd77 nautobot-golden-config/nautobot:latest-py3.7 "nautobot-server rqw…" 16 seconds ago Up 13 seconds nautobot_golden_config_worker_1 +b8adb781d013 nautobot-golden-config/nautobot:latest-py3.7 "/docker-entrypoint.…" 20 seconds ago Up 15 seconds 0.0.0.0:8080->8080/tcp, :::8080->8080/tcp nautobot_golden_config_nautobot_1 +d64ebd60675d nautobot-golden-config/nautobot:latest-py3.7 "mkdocs serve -v -a …" 25 seconds ago Up 18 seconds 0.0.0.0:8001->8080/tcp, :::8001->8080/tcp nautobot_golden_config_docs_1 e72d63129b36 postgres:13-alpine "docker-entrypoint.s…" 25 seconds ago Up 19 seconds 0.0.0.0:5432->5432/tcp, :::5432->5432/tcp nautobot_golden_config_postgres_1 96c6ff66997c redis:6-alpine "docker-entrypoint.s…" 25 seconds ago Up 21 seconds 0.0.0.0:6379->6379/tcp, :::6379->6379/tcp nautobot_golden_config_redis_1 ``` @@ -321,9 +316,6 @@ When trying to debug an issue, one helpful thing you can look at are the logs wi !!! note The `-f` tag will keep the logs open, and output them in realtime as they are generated. -!!! info - Want to limit the log output even further? Use the `--tail <#>` command line argument in conjunction with `-f`. - So for example, our plugin is named `nautobot-golden-config`, the command would most likely be `docker logs nautobot_golden_config_nautobot_1 -f`. You can find the name of all running containers via `docker ps`. If you want to view the logs specific to the worker container, simply use the name of that container instead. @@ -399,7 +391,7 @@ namespace.configure( { "nautobot_golden_config": { ... - "python_ver": "3.11", + "python_ver": "3.7", ... } } @@ -418,7 +410,7 @@ namespace.configure( { "nautobot_golden_config": { ... - "nautobot_ver": "1.0.2", + "nautobot_ver": "1.4.0", ... } } diff --git a/docs/dev/extending.md b/docs/dev/extending.md new file mode 100644 index 00000000..49b89f46 --- /dev/null +++ b/docs/dev/extending.md @@ -0,0 +1,6 @@ +# Extending the App + +!!! warning "Developer Note - Remove Me!" + Information on how to extend the App functionality. + +Extending the application is welcome, however it is best to open an issue first, to ensure that a PR would be accepted and makes sense in terms of features and design. diff --git a/docs/images/icon-nautobot-golden-config.png b/docs/images/icon-nautobot-golden-config.png new file mode 100644 index 0000000000000000000000000000000000000000..7e00cf6ae0ee76324adab30d68d64206678a85e1 GIT binary patch literal 74601 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
@5hb{hC=~cCz;d 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 literal 0 HcmV?d00001 diff --git a/docs/requirements.txt b/docs/requirements.txt index e8e7f513..5f961e5c 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,5 +1,5 @@ mkdocs==1.5.2 -mkdocs-material==9.2.4 -mkdocs-version-annotations==1.0.0 +mkdocs-material==9.1.15 mkdocstrings==0.22.0 -mkdocstrings-python==1.5.2 \ No newline at end of file +mkdocstrings-python==1.5.2 +mkdocs-version-annotations==1.0.0 diff --git a/docs/user/app_getting_started.md b/docs/user/app_getting_started.md index c3d7ee19..24ea0099 100644 --- a/docs/user/app_getting_started.md +++ b/docs/user/app_getting_started.md @@ -1,225 +1,19 @@ -# Quick Start Guides +# Getting Started with the App -- [Quick Start Guides](#quick-start-guides) -- [Backup Configuration](#backup-configuration) -- [Intended Configuration](#intended-configuration) -- [Compliance](#compliance) -- [Load Properties from Git](#load-properties-from-git) +This document provides a step-by-step tutorial on how to get the App going and how to use it. -# Backup Configuration +## Install the App -Follow the steps below to get up and running for the configuration backup element of the plugin. +To install the App, please follow the instructions detailed in the [Installation Guide](../admin/install.md). -1. Enable the feature in the `PLUGIN_SETTINGS`. The configuration should have `"enable_backup": True` set in the `PLUGINS_CONFIG` dictionary for `nautobot_golden_config`. +## First steps with the App -2. Add any git repositories that will be used to house the backup configurations. +!!! warning "Developer Note - Remove Me!" + What (with screenshots preferably) does it look like to perform the simplest workflow within the App once installed? - 1. In the UI `Extensibility -> Git Repositories`. Click Add. - 2. Populate the Git Repository data for the backup. [Git Settings](./app_use_cases.md#git-settings) - 3. Make sure to select the **Provides** called `backup configs`. - 4. Click Create. +## What are the next steps? -3. Next, make sure to create new or update existing Plugins **Settings** with the backup details. - 1. Navigate to `Golden Config -> Settings` under the Golden Configuration Section. - 2. Create new or select one of the existing `Settings` objects - 3. Fill out the Backup Repository. (The dropdown will show the repository that was just created.) - 4. Fill out Backup Path Template. Typically `{{obj.location.name}}/{{obj.name}}.cfg`, see [Setting Details](./app_use_cases.md#application-settings) - 5. Select whether or not to do a connectivity check per device. - 6. Click Save. +!!! warning "Developer Note - Remove Me!" + After taking the first steps, what else could the users look at doing. -4. Create Configuration Removals and Replacements. - - 1. [Config Removals](./app_feature_backup.md#config-removals) - 2. [Config Replacements](./app_feature_backup.md#config-replacements) - -5. Execute the Backup. - - 1. Navigate to `Golden Config -> Home` under the Golden Configuration Section. - 2. Click on the `Execute` button and select `Backup`. - 3. Select what to run the backup on. - 4. Run the Job by clicking "Run Job" button. - -> For in-depth details see [Navigating Backup](./app_feature_backup.md) - -# Intended Configuration - -Follow the steps below to get up and running for the intended configuration element of the plugin. - -!!! note - Intended Configuration requires the `enable_intended` and `enabled_sotAgg` plugin features to be used. - -!!! note - If Secret Group is used for the Repositories the secrets type HTTP(S) is required for this plugin. - -1. Enable the feature in the `PLUGIN_SETTINGS`. The configuration should have `"enable_intended": True` set in the `PLUGINS_CONFIG` dictionary for `nautobot_golden_config`. - - -2. Add any git repositories that will be used to house the intended configurations. - - 1. In the UI `Extensibility -> Git Repositories`. Click Add. - 2. Populate the Git Repository data for the intended. [Git Settings](./app_feature_backup.md#git-settings) - 3. Make sure to select the **Provides** called `intended configs`. - 4. Click Create. - -3. Add the git repository that will be used to house the Jinja2 templates. - - 1. In the UI `Extensibility -> Git Repositories`. Click Add. - 2. Populate the Git Repository data for the jinja2 templates. [Git Settings](./app_feature_backup.md#git-settings) - 3. Make sure to select the **Provides** called `jinja templates`. - 4. Click Create. - -4. Next, make sure to create new or update existing Plugins **Settings** with the intended and jinja2 template details. - - 1. Navigate to `Golden Config -> Settings` under the Golden Configuration Section. - 2. Create new or select one of the existing `Settings` objects - 3. Fill out the Intended Repository. (The dropdown will show the repository that was just created.) - 4. Fill out Intended Path Template. Typically `{{obj.location.name}}/{{obj.name}}.cfg`, see [Setting Details](./app_feature_backup.md#application-settings) - 5. Fill out Jinja Repository. (The dropdown will show the repository that was just created.) - 6. Fill out Jinja Path Template. Typically `{{obj.platform.network_driver}}.j2`. - -5. Determine what data(variables) the Jinja2 templates need from Nautobot. - - 1. See [Source of Truth Agg Details](./app_feature_sotagg.md) - 2. In the UI `Extensibility -> GraphQL Queries`. Click Add. - 3. Populate the GraphQL data. - 4. Make sure to follow the format specified in the **GraphQL** section in [Source of Truth Agg Details](./app_feature_sotagg.md) - 5. Click Create. - 6. Navigate to `Golden Config -> Settings` under the Golden Configuration Section. - 7. Select a SoTAgg Saved Query. (The dropdown will show the GraphQL query that was just created.) - -6. Execute the Intended. - - 1. Navigate to `Golden Config -> Home`. - 2. Click on the `Execute` button and select `Intended`. - 3. Select what to run the intended generation on. - 4. Run the Job. - -> For in-depth details see [Navigating Intended](./app_feature_intended.md) - -# Compliance - -Compliance requires Backups and Intended Configurations in order to be executed. - -1. Enable the feature in the `PLUGIN_SETTINGS`. The configuration should have `"enable_compliance": True` set in the `PLUGINS_CONFIG` dictionary for `nautobot_golden_config`. -2. Follow the steps in [Backup Configuration](#backup-configuration). -3. Follow the steps in [Intended Configuration](#intended-configuration). -4. Create a Compliance Feature. - - 1. Navigate to `Golden Config -> Compliance Feature`. - 2. Click Add and give the feature a name. Typically this is based on the configuration snippet or section. E.g. "aaa". - -5. Create a Compliance Rule. - - 1. Navigate to `Golden Config -> Compliance Rules`. - 2. Click Add and populate the fields, make sure the rule is linked to the feature created previously. See [Configuration Compliance Settings](./app_feature_compliance.md#configuration-compliance-settings) for details. - -6. Execute Compliance Check. - - 1. Navigate to `Golden Config -> Configuration Compliance`. - 2. Click on the `Execute` button and select `Compliance`. - 3. Select what to run the compliance on. - 4. Run the Job. - -> For in-depth details see [Navigating Compliance](./app_feature_compliance.md) - -# Load Properties from Git - -Golden Config properties include: Compliance Features, Compliance Rules, Config Removals, and Config Replacements. They can be created via the UI, API, or alternatively you can load these properties from a Git repository, defined in YAML files following the this directory structure (you can skip any of them if not apply): - -```shell -├── golden_config -│ ├── compliance_features -│ ├── compliance_rules -│ ├── config_removes -│ ├── config_replaces -``` - -The files within these folders can follow any naming pattern or nested folder structure, all of them will be recursively taken into account. So it's up to you to decide how to you prefer to organize these files (within the previously stated directory structure): - -```shell -├── golden_config -│ ├── compliance_features -│ │ └── all.yml -│ ├── compliance_rules -│ │ ├── my_rule_for_cisco_ios -│ │ │ ├── some_rules.yml -│ │ │ └── some_other_rules.yml -│ │ └── juniper_junos.yml -│ ├── config_removes -│ │ ├── cisco_ios.yml -│ │ └── juniper_junos.yml -│ ├── config_replaces -│ │ ├── cisco_ios.yml -│ │ └── juniper_junos.yml -``` - -The `YAML` files will contain all the attributes necessary to identify an object (for instance, a `ComplianceRule` is identified by the `feature_slug` and the `platform_name` together) and the other attributes (the ones that are not used to identify the object). For example: - -`compliance_features` example: - -```yaml ---- -- name: "aaa" - slug: "aaa" - description: "aaa feature" -``` - -`compliance_rules` example: - -```yaml ---- -- feature_slug: "aaa" - platform_name: "Cisco IOS" - config_ordered: true - match_config: | - aaa - line - username - role - tacacs - config_type: "cli" -``` - -`config_removes` example: - -```yaml ---- -- platform_name: "Cisco IOS" - name: "Build config" - regex: '^Building\s+configuration.*\n' -``` - -`config_replaces` example: - -```yaml ---- -- name: "username" - platform_name: "Cisco IOS" - description: "username" - regex: '(username\s+\S+\spassword\s+5\s+)\S+(\s+role\s+\S+)' - replace: '\1\2' -``` - -CustomField data can be added using the `_custom_field_data` attribute, that takes a dictionary mapping custom_field names to their values: - -```yaml ---- -- name: "aaa" - slug: "aaa" - description: "aaa feature" - _custom_field_data: - custom_field_a: "abc" - custom_field_b: 123 -``` - -!!! note - For Foreign Key references to `ComplianceFeature` and `Platform` we use the keywords `feature_slug` and `platform_name` respectively. - -1. Add the Git repository that will be used to sync Git properties. - - 1. In the UI `Extensibility -> Git Repositories`. Click Add. - 2. Populate the Git Repository data for the GC properties. [Git Settings](./app_use_cases.md#git-settings) - 3. Make sure to select the **Provides** called `Golden Config properties`. - 4. Click Create (This step runs an automatic sync). - -2. Run `sync` and all the properties will be created/updated in a declarative way and following the right order to respect the dependencies between objects. The import task will raise a `warning` if the dependencies are not available yet (for instance, a referenced `Platform` is not created), so the `sync` process will continue, and you could then fix these warnings by reviewing the mismatch (maybe creating the required object) and run the `sync` process again. +You can check out the [Use Cases](app_use_cases.md) section for more examples. diff --git a/docs/user/app_overview.md b/docs/user/app_overview.md index 74f02514..06ff5d32 100644 --- a/docs/user/app_overview.md +++ b/docs/user/app_overview.md @@ -1,38 +1,30 @@ # App Overview -The golden configuration plugin is a Nautobot plugin that aims to solve common configuration management challenges. +This document provides an overview of the App including critical information and import considerations when applying it to your Nautobot environment. !!! note Throughout this documentation, the terms "app" and "plugin" will be used interchangeably. -## Description/Overview +## Description -When engineers are starting their network automation journey, everybody asks where and how they should start. Their immediate thought is coming up with methods of automating changes within their environments. However, doing so can be scary for those who are risk averse about automation making changes. The question then comes about how automation can be used to help solve some of the big problems facing network teams today. One of those problems that we’ve repeatedly heard from our customers and fellow network engineers is around configuration drift. This issue typically occurs for multiple reasons: -- Lack of standardization for device configurations -- Multiple individuals independently making changes -- Mergers and acquisitions +## Audience (User Personas) - Who should use this App? -Thankfully, this issue can be addressed without making any changes on your devices. You might ask, “How do I do that?” That is where the Golden Configuration plugin for Nautobot comes in. The Golden Configuration plugin is comprised of four components: +!!! warning "Developer Note - Remove Me!" + Who is this meant for/ who is the common user of this app? -- Configuration Backup -- Source of Truth Aggregation -- Configuration Intended -- Configuration Compliance +## Authors and Maintainers -!!! info - The four components are not hard requirements, the application is flexible and can be updated to leverage any of these components if they already exist in another system or automated process. +!!! warning "Developer Note - Remove Me!" + Add the team and/or the main individuals maintaining this project. Include historical maintainers as well. -Utilizing these components, you can define the Golden Configuration standard for each of your devices and compare their adherence to that standard, otherwise known as their configuration compliance. +## Nautobot Features Used -## Audience (User Personas) - Who should use this App? +!!! warning "Developer Note - Remove Me!" + What is shown today in the Installed Plugins page in Nautobot. What parts of Nautobot does it interact with, what does it add etc. ? -- Network Engineers interested in Network Automation, Infrastructure as Code, etc. -- Network shops that have difficult time ensuring their configurations are to standard -- Network shops looking for a backup configuration solution -- Network shops looking for generating configurations - -## Authors and Maintainers +### Extras -- Ken Celenza (@itdependsnetworks) -- Jeff Kala (@jeffkala) +!!! warning "Developer Note - Remove Me!" + Custom Fields - things like which CFs are created by this app? + Jobs - are jobs, if so, which ones, installed by this app? diff --git a/docs/user/app_use_cases.md b/docs/user/app_use_cases.md index ca9789f3..dc06944f 100644 --- a/docs/user/app_use_cases.md +++ b/docs/user/app_use_cases.md @@ -1,209 +1,12 @@ # Using the App -## General Usage - -### Home - -The Home view is a portal to understand what the status of the devices are. - -![Home Overview](../images/ss_golden-overview.png) - -Some of the information described in this view, may not be immediately obvious. - -* The Backup/Intended/Compliance status will always show the last time the job was successfully ran for that device, but there are several conditions it may be in. - * Green with a date indicates that the run was successful, which was the last time the job ran. - * Red with a date indicates the last time the job ran successfully, with the last time the job was attempted shown when you mouse over the date. - * A red double-dashed icon indicated the job has never been successful -* The icons are provided in the following order, that largely matches the status. - * Backups - * Intended - * Unix Diff - * SoT aggregation data - * Run job - -The first four bring up a "modal" or "dialogue box" which has a detailed view for a dedicated page. The run job brings the user to a job to run all three -components against all of the devices. - -### Jobs - -There are a series of Jobs that are registered via the Plugin. They can be viewed from the standard Jobs view. - -![Job Overview](../images/job-overview.png) - -Each Job attempts to provide sane error handling, and respects the `debug` flag to provide more information. - -![Job Result](../images/job-result.png) - -### Application Settings - -The golden configuration plugin settings can be found by navigating to `Golden Config -> Settings` button. Select one of the Settings, under the `Golden Configuration` section. -Since Golden Configuration Plugin version 1.0, the plugin allows for multiple settings to be configured by the User. -Each of the settings, has the individual repositories and configuration details, as well as a Dynamic Group. -You could use a combination of settings to customize your Configuration Compliance behavior. -Settings have a name and a weight. The weight parameter indicates the priority of given Settings - the higher the weight, the device matching the Dynamic Group defined will be assigned to the scope. -At the same moment, each device will be matched up to maximum of only one `Settings.` In case of the same weight, the sorting is performed by the name. - -![Navigate to Settings](../images/navigate-compliance-rules.png) - -To create new settings click on the `+Add` button. -To update existing settings click on one of the `Settings` name. - - -|Setting|Explanation| -|:--|:--| -|Backup Repositories |The Git Repository where your backup configurations will be found. | -|Backup Path|A Jinja template which defines the path and name of backup files within the backup repository. The variable `obj` is available as the device instance object of a given device, as is the case for all Jinja templates. e.g. `{{obj.location.name}}/{{obj.name}}.cfg`| -|Intended Repositories |The Git Repository where your intended configuration state files will be found. | -|Intended Path|A Jinja template which defines the path and name of intended configuration state files within the intended state repository. e.g. `{{obj.location.name}}/{{obj.name}}.intended_cfg`| -|Jinja Repository |The Git Repository where your jinja templates will be found. | -|Jinja Path|A Jinja template which defines the path (within the repository) and name of the Jinja template file. e.g. `{{obj.platform.name}}/{{obj.role.name}}/main.j2`| -|Dynamic Group|The scope of devices on which Golden Config's jobs can operate. | -|GraphQL Query|A query that is evaluated and used to render the config. The query must start with `query ($device_id: ID!)`.| - -!!! note - Each of these will be further detailed in their respective sections. - -#### Dynamic Group - -!!! note - Starting in Golden Config v1.2 and onwards the original implementation of scope has been deprecated in favor of Dynamic Groups from Nautobot. During the migrations any Golden Config Setting scope attribute will be migrated to Dynamic Groups. All settings require a Dynamic Group, if the original scope is not set to allow ALL Devices a Dynamic Group will be created without a filter applied which will is the equivalent of all Devices. - -The [Dynamic Group](https://docs.nautobot.com/projects/core/en/stable/models/extras/dynamicgroup/) provides a filter that will limit the list of devices in scope of a Golden Config Setting. In the Golden Config Home view the Dynamic Group is used to limit the Devices that are displayed, if a Device does not match the filter of a Dynamic Group it is considered out of scope for GoldenConfig and will not show on the Golden Config Settings view. All jobs in Golden Config also use the Dynamic Group to know which Devices are in scope. A job can optionally further refine the scope, but the outer bound would be based on what is defined in the Dynamic Group. The options are best described by leveraging the Devices list view, search features (the filtering shown on the side of the Devices.) Building a query there, will provide the exact keys expected. - -##### Scope Of Devices - -Within the Detail view of a Golden Config Setting the section to denote the scope of devices links back to the Dynamic Group that is assigned and renders the filter attribute of the Dynamic Group as JSON. All updates to the scope of Devices must be done via the Dynamic Group not directly on the Golden Config Setting. - -![Dynamic Group](../images/setting-dynamic-group.png) - -The below configurations of scope can either be removed or specified for pre 1.2 only, the same logic applies in 1.2 and onwards but via DynamicGroups. - -Filtering to specific platforms, based on their name. - -```json -{ - "platform": [ - "Cisco IOS", - "Cisco NXOS", - "Arista EOS", - "Juniper Junos" - ] -} -``` - -Adding a "has_primary_ip" check. - -```json -{ - "platform": [ - "Cisco IOS", - "Cisco NXOS", - "Arista EOS", - "Juniper Junos" - ], - "has_primary_ip": "True" -} -``` - -When viewing the settings, the scope of devices is actually a link to the query built in the Devices view. Click that link to understand which devices are permitted by the filter. - -### Git Settings - -The plugin makes heavy use of the Nautobot git data sources feature. There are up to three repositories used in the application. This set of instructions will walk an operator through setting up the backup repository. The steps are the same, except for the "Provides" field name chosen. - -In order to setup this repository, go to Nautobot and navigate to the Data Sources Git integration. `Extensibility -> Git Repositories`. - -![Backup Git Navigation](../images/git-step1.png) +This document describes common use-cases and scenarios for this App. -From the Git Repositories page we can add the **Backup** repository. - -Click on `Add`. - -You will now be presented with a page to fill in the repository details. - -Parameters: - -|Field|Explanation| -|:--|:--| -|Name|User friendly name for the backup repo.| -|Slug|Auto-generated based on the `name` provided.| -|Remote URL|The URL pointing to the Git repo that stores the backup configuration files. Current git url usage is limited to `http` or `https`.| -|Branch|The branch in the Git repo to use. Defaults to `main`.| -|Token|The token is a personal access token for the `username` provided. For more information on generating a personal access token. [Github Personal Access Token](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token) -|Username|The Git username that corresponds with the personal access token above.| -|Provides|Valid providers for Git Repo.| - - -!!! note - If Secret Group is used for the Repositories the secrets type HTTP(S) is required for this plugin. - -![Example Git Backups](../images/backup-git-step2.png) - -Select `backup configs` and click on `Create`. - -Once you click `Create` and the repository syncs, the main page will now show the repo along with its status. -![Git Backup Repo Status](../images/backup-git-step3.png) - -For their respective features, the "Provides" field could be backup intended configs and jinja templates. - -### Plugins Buttons - -The plugins buttons provides you with the ability to navigate to Run the script, overview report, and detailed report. - -### Run Script - -This can be accessed via the Plugins drop-down via `Run Script` button of the `Home` view, the user will be provided a form of the Job (as described -above), which will allow the user to limit the scope of the request. - -### Device Template Content - -The plugin makes use of template content `right_page` in order to use display in-line the status of that device in the traditional Nautobot view. From here you can click the link to see the detail compliance view. - -### Location Template Content - -The plugin makes use of template content `right_page` in order to use display in-line the status of that entire location in the traditional Nautobot view. This sums the total for all locations for parent locations. - -### API - -To run the job programmatically, reference the [nautobot documentation](https://docs.nautobot.com/projects/core/en/stable/additional-features/jobs/#via-the-api) for the proper API call. Pay special attention to the `class_path` definition. - -### Feature Enablement - -Enabling features such as backup or compliance, will render those parts of the UI visible. It is worth noting that disabling features does not provide any -garbage collection and it is up to the operator to remove such data. - -### Network Operating System Support - -The version of OS's supported is documented in the [FAQ](./app_faq.md) and is controlled the platform network_driver. The platform network_driver must be exactly as expected or leverage -a configuration option--which is described the the FAQ--for the plugin to work. - -### Use-cases and common workflows - -This plugin enable four (4) key use cases. - -1. **Configuration Backups** - Is a Nornir process to connect to devices, optionally parse out lines/secrets, backup the configuration, and save to a Git repository. -2. **Intended Configuration** - Is a Nornir process to generate configuration based on a Git repo of Jinja files to combine with a GraphQL generated data and a Git repo to store the intended configuration. -3. **Source of Truth Aggregation** - Is a GraphQL query per device that creates a data structure used in the generation of configuration. -4. **Configuration Compliance** - Is a process to run comparison of the actual (via backups) and intended (via Jinja file creation) CLI configurations upon saving the actual and intended configuration. This is started by either a Nornir process for cli-like configurations or calling the API for json-like configurations +## General Usage -!!! warning "Notice" - The operators of their own Nautobot instance are welcome to use any combination of these features. Though the appearance may seem like they are tightly coupled, this isn't actually the case. For example, one can obtain backup configurations from their current RANCID/Oxidized process and simply provide a Git Repo of the location of the backup configurations, and the compliance process would work the same way. Also, another user may only want to generate configurations, but not want to use other features, which is perfectly fine to do so. +## Use-cases and common workflows ## Screenshots -There are many features and capabilities the plugin provides into the Nautobot ecosystem. The following screenshots are intended to provide a quick visual overview of some of these features. - -The golden configuration is driven by jobs that run a series of tasks and the result is captured in this overview. - -![Overview](../images/ss_golden-overview.png) - -The compliance report provides a high-level overview on the compliance of your network. -![Compliance Report](../images/ss_compliance-report.png) - -The compliance overview will provide a per device and feature overview on the compliance of your network devices. -![Compliance Overview](../images/ss_compliance-overview.png) - -Drilling into a specific device and feature, you can get an immediate detailed understanding of your device. -![Compliance Device](../images/ss_compliance-device.png) - -![Compliance Rule](../images/ss_compliance-rule.png) +!!! warning "Developer Note - Remove Me!" + Ideally captures every view exposed by the App. Should include a relevant dataset. diff --git a/docs/user/external_interactions.md b/docs/user/external_interactions.md new file mode 100644 index 00000000..eaba5b56 --- /dev/null +++ b/docs/user/external_interactions.md @@ -0,0 +1,17 @@ +# External Interactions + +This document describes external dependencies and prerequisites for this App to operate, including system requirements, API endpoints, interconnection or integrations to other applications or services, and similar topics. + +!!! warning "Developer Note - Remove Me!" + Optional page, remove if not applicable. + +## External System Integrations + +### From the App to Other Systems + +### From Other Systems to the App + +## Nautobot REST API endpoints + +!!! warning "Developer Note - Remove Me!" + API documentation in this doc - including python request examples, curl examples, postman collections referred etc. diff --git a/docs/user/faq.md b/docs/user/faq.md new file mode 100644 index 00000000..318b08dc --- /dev/null +++ b/docs/user/faq.md @@ -0,0 +1 @@ +# Frequently Asked Questions diff --git a/invoke.example.yml b/invoke.example.yml index 60d1ca37..16db4580 100644 --- a/invoke.example.yml +++ b/invoke.example.yml @@ -3,7 +3,7 @@ nautobot_golden_config: project_name: "nautobot-golden-config" nautobot_ver: "latest" local: false - python_ver: "3.11" + python_ver: "3.8" compose_dir: "development" compose_files: - "docker-compose.base.yml" diff --git a/invoke.mysql.yml b/invoke.mysql.yml index 10f73b14..5ee06af6 100644 --- a/invoke.mysql.yml +++ b/invoke.mysql.yml @@ -3,7 +3,7 @@ nautobot_golden_config: project_name: "nautobot-golden-config" nautobot_ver: "latest" local: false - python_ver: "3.11" + python_ver: "3.8" compose_dir: "development" compose_files: - "docker-compose.base.yml" diff --git a/mkdocs.yml b/mkdocs.yml index 95edbb3a..4becad9c 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,11 +1,11 @@ --- dev_addr: "127.0.0.1:8001" -edit_uri: "edit/main/docs" -site_dir: "golden-config/static/golden-config/docs" -site_name: "Golden Configuration Documentation" +edit_uri: "edit/main/nautobot-plugin-golden-config/docs" +site_dir: "nautobot_golden_config/static/nautobot_golden_config/docs" +site_name: "Golden Config Documentation" site_url: "https://docs.nautobot.com/projects/golden-config/en/latest/" repo_url: "https://github.com/nautobot/nautobot-plugin-golden-config" -copyright: "Copyright © 2023 The Authors" +copyright: "Copyright © The Authors" theme: name: "material" navigation_depth: 4 @@ -14,14 +14,17 @@ theme: - "django" - "yaml" features: + - "content.action.edit" + - "content.action.view" - "content.code.copy" - - "navigation.tracking" + - "navigation.footer" + - "navigation.indexes" - "navigation.tabs" - "navigation.tabs.sticky" - - "search.suggest" + - "navigation.tracking" - "search.highlight" - "search.share" - - "navigation.indexes" + - "search.suggest" favicon: "assets/favicon.ico" logo: "assets/nautobot_logo.svg" palette: @@ -79,8 +82,10 @@ markdown_extensions: - "pymdownx.inlinehilite" - "pymdownx.snippets" - "pymdownx.superfences" + - "footnotes" plugins: - "search" + - "mkdocs-version-annotations" - "mkdocstrings": default_handler: "python" handlers: @@ -95,46 +100,25 @@ nav: - Overview: "index.md" - User Guide: - App Overview: "user/app_overview.md" - - Using the App: "user/app_use_cases.md" - - Navigate Backup: "user/app_feature_backup.md" - - Navigate Compliance: "user/app_feature_compliance.md" - - Navigate Compliance CLI: "user/app_feature_compliancecli.md" - - Navigate Compliance JSON: "user/app_feature_compliancejson.md" - - Navigate Compliance Custom: "user/app_feature_compliancecustom.md" - - Navigate Intended: "user/app_feature_intended.md" - - Navigate SoT Agg: "user/app_feature_sotagg.md" - - Navigate Configuration Post-Processing: "user/app_feature_config_postprocessing.md" - - Navigate Config Plans: "user/app_feature_config_plans.md" - - Navigate Remediation: "user/app_feature_remediation.md" - Getting Started: "user/app_getting_started.md" - - Frequently Asked Questions: "user/app_faq.md" - - External Interactions: "user/app_external_interactions.md" - - Troubleshooting: - - General: "user/troubleshooting/troubleshoot_general.md" - - Credentials: "user/troubleshooting/troubleshoot_credentials.md" - - Dispatchers: "user/troubleshooting/troubleshoot_dispatchers.md" + - Using the App: "user/app_use_cases.md" + - Frequently Asked Questions: "user/faq.md" + - External Interactions: "user/external_interactions.md" - Administrator Guide: - - Install and Configure: "admin/admin_install.md" - - Upgrade: "admin/admin_upgrade.md" - - Uninstall: "admin/admin_uninstall.md" + - Install and Configure: "admin/install.md" + - Upgrade: "admin/upgrade.md" + - Uninstall: "admin/uninstall.md" - Compatibility Matrix: "admin/compatibility_matrix.md" - Release Notes: - "admin/release_notes/index.md" - - v1.5: "admin/release_notes/version_1.5.md" - - v1.4: "admin/release_notes/version_1.4.md" - - v1.3: "admin/release_notes/version_1.3.md" - - v1.2: "admin/release_notes/version_1.2.md" - - v1.1: "admin/release_notes/version_1.1.md" - v1.0: "admin/release_notes/version_1.0.md" - - v0.10: "admin/release_notes/version_0.10.md" - - v0.9: "admin/release_notes/version_0.9.md" - Developer Guide: - - Extending the App: "dev/dev_extending.md" - - Contributing to the App: "dev/dev_contributing.md" + - Extending the App: "dev/extending.md" + - Contributing to the App: "dev/contributing.md" - Development Environment: "dev/dev_environment.md" - - Architecture Decision Record: "dev/dev_adr.md" + - Architecture Decision Records: "dev/arch_decision.md" - Code Reference: - "dev/code_reference/index.md" - - Models: "dev/code_reference/models.md" + - Package: "dev/code_reference/package.md" - API: "dev/code_reference/api.md" - - Nautobot Docs Home ↗︎: "https://docs.nautobot.com/" + - Nautobot Docs Home ↗︎: "https://docs.nautobot.com" diff --git a/nautobot_golden_config/__init__.py b/nautobot_golden_config/__init__.py index a652bce3..e2aee2f2 100644 --- a/nautobot_golden_config/__init__.py +++ b/nautobot_golden_config/__init__.py @@ -2,60 +2,25 @@ # Metadata is inherited from Nautobot. If not including Nautobot in the environment, this should be added from importlib import metadata - __version__ = metadata.version(__name__) -from jinja2 import StrictUndefined -from django.db.models.signals import post_migrate -from nautobot.core.signals import nautobot_database_ready -from nautobot.extras.plugins import PluginConfig +from nautobot.extras.plugins import NautobotAppConfig -class GoldenConfig(PluginConfig): +class NautobotGoldenConfigConfig(NautobotAppConfig): """Plugin configuration for the nautobot_golden_config plugin.""" name = "nautobot_golden_config" - verbose_name = "Golden Configuration" + verbose_name = "Golden Config" version = __version__ author = "Network to Code, LLC" - author_email = "opensource@networktocode.com" - description = "Nautobot Apps that embraces NetDevOps and automates configuration backups, performs configuration compliance, and generates intended configurations. Includes native Git integration and gives users the flexibility to mix and match the supported features." + description = "A plugin for configuration on nautobot." base_url = "golden-config" - default_settings = { - "enable_backup": True, - "enable_compliance": True, - "enable_intended": True, - "enable_sotagg": True, - "enable_postprocessing": False, - "postprocessing_callables": [], - "postprocessing_subscribed": [], - "per_feature_bar_width": 0.3, - "per_feature_width": 13, - "per_feature_height": 4, - "get_custom_compliance": None, - "jinja_env": { - "undefined": StrictUndefined, - "trim_blocks": True, - "lstrip_blocks": False, - }, - } - - def ready(self): - """Register custom signals.""" - from nautobot_golden_config.models import ConfigCompliance # pylint: disable=import-outside-toplevel - - # pylint: disable=import-outside-toplevel - from .signals import ( - config_compliance_platform_cleanup, - post_migrate_create_statuses, - post_migrate_create_job_button, - ) - - nautobot_database_ready.connect(post_migrate_create_statuses, sender=self) - nautobot_database_ready.connect(post_migrate_create_job_button, sender=self) - - super().ready() - post_migrate.connect(config_compliance_platform_cleanup, sender=ConfigCompliance) + required_settings = [] + min_version = "1.4.0" + max_version = "1.9999" + default_settings = {} + caching_config = {} -config = GoldenConfig # pylint:disable=invalid-name +config = NautobotGoldenConfigConfig # pylint:disable=invalid-name diff --git a/nautobot_golden_config/tests/test_api.py b/nautobot_golden_config/tests/test_api.py index 0b4e3824..afa12a15 100644 --- a/nautobot_golden_config/tests/test_api.py +++ b/nautobot_golden_config/tests/test_api.py @@ -1,413 +1,28 @@ """Unit tests for nautobot_golden_config.""" -from copy import deepcopy - from django.contrib.auth import get_user_model -from django.contrib.contenttypes.models import ContentType +from django.test import TestCase from django.urls import reverse -from nautobot.dcim.models import Device, Platform -from nautobot.extras.models import DynamicGroup, GitRepository, GraphQLQuery, Status -from nautobot.core.testing import APITestCase, APIViewTestCases from rest_framework import status +from rest_framework.test import APIClient -# from nautobot.extras.models import GitRepository, GraphQLQuery, DynamicGroup -from nautobot_golden_config.choices import RemediationTypeChoice -from nautobot_golden_config.models import ConfigPlan, GoldenConfigSetting, RemediationSetting - -from .conftest import ( - create_config_compliance, - create_device, - create_device_data, - create_feature_rule_json, - create_git_repos, - create_job_result, - create_saved_queries, -) +from nautobot.users.models import Token User = get_user_model() -class GoldenConfigAPITest(APITestCase): # pylint: disable=too-many-ancestors - """Test the ConfigCompliance API.""" +class PlaceholderAPITest(TestCase): + """Test the NautobotGoldenConfig API.""" def setUp(self): """Create a superuser and token for API calls.""" - super().setUp() - self.device = create_device() - self.compliance_rule_json = create_feature_rule_json(self.device) - self.base_view = reverse("plugins-api:nautobot_golden_config-api:configcompliance-list") - - def test_root(self): - """Validate the root for Nautobot Chatops API.""" - url = reverse("plugins-api:nautobot_golden_config-api:api-root") - response = self.client.get(f"{url}?format=api", **self.header) - self.assertEqual(response.status_code, 200) + self.user = User.objects.create(username="testuser", is_superuser=True) + self.token = Token.objects.create(user=self.user) + self.client = APIClient() + self.client.credentials(HTTP_AUTHORIZATION=f"Token {self.token.key}") - def test_device_list(self): + def test_placeholder(self): """Verify that devices can be listed.""" url = reverse("dcim-api:device-list") - self.add_permissions("dcim.view_device") - response = self.client.get(url, **self.header) - self.assertEqual(response.status_code, status.HTTP_200_OK) - self.assertEqual(response.data["count"], 1) - - def test_config_compliance_list_view(self): - """Verify that config compliance objects can be listed.""" - actual = '{"foo": {"bar-1": "baz"}}' - intended = '{"foo": {"bar-2": "baz"}}' - create_config_compliance( - self.device, actual=actual, intended=intended, compliance_rule=self.compliance_rule_json - ) - self.add_permissions("nautobot_golden_config.view_configcompliance") - response = self.client.get(self.base_view, **self.header) - self.assertEqual(response.status_code, status.HTTP_200_OK) - self.assertEqual(response.data["count"], 1) - - def test_config_compliance_post_new_json_compliant(self): - """Verify that config compliance detail view.""" - self.add_permissions("nautobot_golden_config.add_configcompliance") - response = self.client.post( - self.base_view, - data={ - "device": self.device.id, - "intended": '{"foo": {"bar-1": "baz"}}', - "actual": '{"foo": {"bar-1": "baz"}}', - "rule": self.compliance_rule_json.id, - }, - format="json", - **self.header, - ) - self.assertEqual(response.status_code, status.HTTP_201_CREATED) - self.assertTrue(response.data["compliance"]) - - def test_config_compliance_post_new_json_not_compliant(self): - """Verify that config compliance detail view.""" - self.add_permissions("nautobot_golden_config.add_configcompliance") - response = self.client.post( - self.base_view, - data={ - "device": self.device.id, - "intended": '{"foo": {"bar-1": "baz"}}', - "actual": '{"foo": {"bar-2": "baz"}}', - "rule": self.compliance_rule_json.id, - }, - format="json", - **self.header, - ) - self.assertEqual(response.status_code, status.HTTP_201_CREATED) - self.assertFalse(response.data["compliance"]) - - -class GoldenConfigSettingsAPITest(APITestCase): # pylint: disable=too-many-ancestors - """Verify that the combination of values in a GoldenConfigSettings object POST are valid.""" - - def setUp(self): - """Create a superuser and token for API calls.""" - super().setUp() - create_git_repos() - create_saved_queries() - self.add_permissions("nautobot_golden_config.add_goldenconfigsetting") - self.add_permissions("nautobot_golden_config.change_goldenconfigsetting") - self.add_permissions("extras.view_dynamicgroup") - self.base_view = reverse("plugins-api:nautobot_golden_config-api:goldenconfigsetting-list") - self.content_type = ContentType.objects.get(app_label="dcim", model="device") - self.dynamic_group = DynamicGroup.objects.create( - name="test1 site site-4", - content_type=self.content_type, - filter={"has_primary_ip": "True"}, - ) - - self.data = { - "name": "test-setting-1", - "slug": "test_setting_1", - "description": "This is a description field of test-setting-1.", - "weight": 5000, - "tags": [], - "computed_fields": {}, - "custom_fields": {}, - "_custom_field_data": {}, - "backup_path_template": "{{obj.location.parent.name}}/{{obj.location.name}}/{{obj.name}}.cfg", - "intended_path_template": "{{obj.location.parent.name}}/{{obj.location.name}}/{{obj.name}}.cfg", - "jinja_path_template": "templates/{{obj.platform.name}}/{{obj.platform.name}}_main.j2", - "backup_test_connectivity": False, - "dynamic_group": str(self.dynamic_group.id), - "sot_agg_query": str(GraphQLQuery.objects.get(name="GC-SoTAgg-Query-1").id), - "jinja_repository": str(GitRepository.objects.get(name="test-jinja-repo-1").id), - "backup_repository": str(GitRepository.objects.get(name="test-backup-repo-1").id), - "intended_repository": str(GitRepository.objects.get(name="test-intended-repo-1").id), - } - # Since we enforced a singleton pattern on this model in 0.9 release migrations, nuke any auto-created objects. - GoldenConfigSetting.objects.all().delete() - - def test_golden_config_settings_create_good(self): - """Test a POST with good values.""" - response = self.client.post( - self.base_view, - data=self.data, - format="json", - **self.header, - ) - self.assertEqual(response.status_code, status.HTTP_201_CREATED) - self.assertTrue(response.data["created"]) - self.assertTrue(response.data["id"]) - self.assertEqual( - response.data["backup_path_template"], "{{obj.location.parent.name}}/{{obj.location.name}}/{{obj.name}}.cfg" - ) - self.assertEqual( - response.data["intended_path_template"], - "{{obj.location.parent.name}}/{{obj.location.name}}/{{obj.name}}.cfg", - ) - self.assertEqual( - response.data["jinja_path_template"], "templates/{{obj.platform.name}}/{{obj.platform.name}}_main.j2" - ) - self.assertFalse(response.data["backup_test_connectivity"]) - self.assertEqual(response.data["sot_agg_query"]["id"], GraphQLQuery.objects.get(name="GC-SoTAgg-Query-1").id) - self.assertEqual( - response.data["jinja_repository"]["id"], GitRepository.objects.get(name="test-jinja-repo-1").id - ) - self.assertEqual( - response.data["backup_repository"]["id"], GitRepository.objects.get(name="test-backup-repo-1").id - ) - self.assertEqual( - response.data["intended_repository"]["id"], GitRepository.objects.get(name="test-intended-repo-1").id - ) - # Clean up - GoldenConfigSetting.objects.all().delete() - self.assertEqual(GoldenConfigSetting.objects.all().count(), 0) - - def test_golden_config_settings_update_good(self): - """Verify a PUT to the valid settings object, with valid but changed values.""" - response_post = self.client.post( - self.base_view, - data=self.data, - format="json", - **self.header, - ) - new_data = deepcopy(self.data) - new_data["backup_repository"] = str(GitRepository.objects.get(name="test-backup-repo-1").id) - response = self.client.put( - f"{self.base_view}{response_post.data['id']}/", - data=new_data, - format="json", - **self.header, - ) - self.assertEqual(response.status_code, status.HTTP_200_OK) - self.assertEqual( - response.data["backup_path_template"], "{{obj.location.parent.name}}/{{obj.location.name}}/{{obj.name}}.cfg" - ) - self.assertEqual( - response.data["intended_path_template"], - "{{obj.location.parent.name}}/{{obj.location.name}}/{{obj.name}}.cfg", - ) - self.assertEqual( - response.data["jinja_path_template"], "templates/{{obj.platform.name}}/{{obj.platform.name}}_main.j2" - ) - self.assertFalse(response.data["backup_test_connectivity"]) - self.assertEqual(response.data["sot_agg_query"]["id"], GraphQLQuery.objects.get(name="GC-SoTAgg-Query-1").id) - self.assertEqual( - response.data["jinja_repository"]["id"], GitRepository.objects.get(name="test-jinja-repo-1").id - ) - self.assertEqual( - response.data["backup_repository"]["id"], GitRepository.objects.get(name="test-backup-repo-1").id - ) - self.assertEqual( - response.data["intended_repository"]["id"], GitRepository.objects.get(name="test-intended-repo-1").id - ) - # Clean up - GoldenConfigSetting.objects.all().delete() - self.assertEqual(GoldenConfigSetting.objects.all().count(), 0) - - def test_settings_api_clean_up(self): - """Transactional custom model, unable to use `get_or_create`. - - Delete all objects created of GitRepository type. - """ - GitRepository.objects.all().delete() - self.assertEqual(GitRepository.objects.all().count(), 0) - - # Put back a general GoldenConfigSetting object. - global_settings = GoldenConfigSetting.objects.create(dynamic_group=self.dynamic_group) - global_settings.save() - - -# pylint: disable=too-many-ancestors - - -class GoldenConfigSerializerCSVTest(APITestCase): - """Test CSV Export returns 200/OK.""" - - url = reverse("plugins-api:nautobot_golden_config-api:goldenconfig-list") - - def setUp(self): - super().setUp() - self._add_permissions() - - def _add_permissions(self): - model = self.url.split("/")[-2] - permission_name = model.replace("-", "") - self.add_permissions(f"nautobot_golden_config.view_{permission_name}") - - def test_csv_export(self): - response = self.client.get(f"{self.url}?format=csv", **self.header) + response = self.client.get(url) self.assertEqual(response.status_code, status.HTTP_200_OK) - - -class GoldenConfigSettingSerializerCSVTest(GoldenConfigSerializerCSVTest): - """Test CSV Export returns 200/OK.""" - - url = reverse("plugins-api:nautobot_golden_config-api:goldenconfigsetting-list") - - def _add_permissions(self): - self.add_permissions("nautobot_golden_config.view_goldenconfigsetting") - - -class ComplianceFeatureSerializerCSVTest(GoldenConfigSerializerCSVTest): - """Test CSV Export returns 200/OK.""" - - url = reverse("plugins-api:nautobot_golden_config-api:compliancefeature-list") - - -class ComplianceRuleCSVTest(GoldenConfigSerializerCSVTest): - """Test CSV Export returns 200/OK.""" - - url = reverse("plugins-api:nautobot_golden_config-api:compliancerule-list") - - -class ConfigComplianceCSVTest(GoldenConfigSerializerCSVTest): - """Test CSV Export returns 200/OK.""" - - url = reverse("plugins-api:nautobot_golden_config-api:configcompliance-list") - - -class ConfigRemoveCSVTest(GoldenConfigSerializerCSVTest): - """Test CSV Export returns 200/OK.""" - - url = reverse("plugins-api:nautobot_golden_config-api:configremove-list") - - -class ConfigReplaceCSVTest(GoldenConfigSerializerCSVTest): - """Test CSV Export returns 200/OK.""" - - url = reverse("plugins-api:nautobot_golden_config-api:configreplace-list") - - -class RemediationSettingTest(APIViewTestCases.APIViewTestCase): - """Test API for Remediation Settings.""" - - model = RemediationSetting - choices_fields = ["remediation_type"] - - @classmethod - def setUpTestData(cls): - create_device_data() - platform1 = Platform.objects.get(name="Platform 1") - platform2 = Platform.objects.get(name="Platform 2") - platform3 = Platform.objects.get(name="Platform 3") - type_cli = RemediationTypeChoice.TYPE_HIERCONFIG - type_custom = RemediationTypeChoice.TYPE_CUSTOM - - # RemediationSetting type Hier with default values. - RemediationSetting.objects.create( - platform=platform1, - remediation_type=type_cli, - ) - # RemediationSetting type Hier with custom options. - RemediationSetting.objects.create( - platform=platform2, remediation_type=type_cli, remediation_options={"some_option": "some_value"} - ) - # RemediationSetting type Custom with custom options. - RemediationSetting.objects.create( - platform=platform3, - remediation_type=type_custom, - ) - - platforms = ( - Platform.objects.create(name="Platform 4", slug="platform-4"), - Platform.objects.create(name="Platform 5", slug="platform-5"), - Platform.objects.create(name="Platform 6", slug="platform-6"), - ) - - cls.create_data = [ - {"platform": platforms[0].pk, "remediation_type": type_cli}, - { - "platform": platforms[1].pk, - "remediation_type": type_cli, - "remediation_options": {"some_option": "some_value"}, - }, - {"platform": platforms[2].pk, "remediation_type": type_custom}, - ] - - cls.update_data = { - "remediation_type": type_custom, - } - - cls.bulk_update_data = { - "remediation_type": type_cli, - } - - def test_list_objects_brief(self): - """Skipping test due to brief_fields not implemented.""" - - -# pylint: disable=too-many-ancestors,too-many-locals -class ConfigPlanTest(APIViewTestCases.APIViewTestCase): - """Test API for ConfigPlan.""" - - model = ConfigPlan - brief_fields = ["device", "display", "id", "plan_type", "url"] - # The Status serializer field requires slug, but the model field returns the UUID. - validation_excluded_fields = ["status"] - - @classmethod - def setUpTestData(cls): - create_device_data() - device1 = Device.objects.get(name="Device 1") - device2 = Device.objects.get(name="Device 2") - device3 = Device.objects.get(name="Device 3") - - rule1 = create_feature_rule_json(device1, feature="Test Feature 1") - rule2 = create_feature_rule_json(device2, feature="Test Feature 2") - rule3 = create_feature_rule_json(device3, feature="Test Feature 3") - - job_result1 = create_job_result() - job_result2 = create_job_result() - job_result3 = create_job_result() - - features = [rule1.feature, rule2.feature, rule3.feature] - plan_types = ["intended", "missing", "remediation"] - job_result_ids = [job_result1.id, job_result2.id, job_result3.id] - not_approved_status = Status.objects.get(slug="not-approved") - approved_status = Status.objects.get(slug="approved") - - for cont in range(1, 4): - plan = ConfigPlan.objects.create( - device=Device.objects.get(name=f"Device {cont}"), - plan_type=plan_types[cont - 1], - config_set=f"Test Config Set {cont}", - change_control_id=f"Test Change Control ID {cont}", - change_control_url=f"https://{cont}.example.com/", - status=not_approved_status, - job_result_id=job_result_ids[cont - 1], - ) - plan.feature.add(features[cont - 1]) - plan.validated_save() - - cls.update_data = { - "change_control_id": "Test Change Control ID 4", - "change_control_url": "https://4.example.com/", - "status": approved_status.slug, - } - - cls.bulk_update_data = { - "change_control_id": "Test Change Control ID 5", - "change_control_url": "https://5.example.com/", - "status": approved_status.slug, - } - - def test_create_object(self): - """Skipping test due to POST method not allowed.""" - - def test_create_object_without_permission(self): - """Skipping test due to POST method not allowed.""" - - def test_bulk_create_objects(self): - """Skipping test due to POST method not allowed.""" + self.assertEqual(response.data["count"], 0) diff --git a/nautobot_golden_config/tests/test_basic.py b/nautobot_golden_config/tests/test_basic.py index e25dc149..26a8c5aa 100644 --- a/nautobot_golden_config/tests/test_basic.py +++ b/nautobot_golden_config/tests/test_basic.py @@ -1,15 +1,26 @@ """Basic tests that do not require Django.""" -import os import unittest - +import os import toml +from nautobot_golden_config import __version__ as project_version + + +class TestVersion(unittest.TestCase): + """Test Version is the same.""" + + def test_version(self): + """Verify that pyproject.toml version is same as version specified in the package.""" + parent_path = os.path.dirname(os.path.dirname(os.path.dirname(os.path.realpath(__file__)))) + poetry_version = toml.load(os.path.join(parent_path, "pyproject.toml"))["tool"]["poetry"]["version"] + self.assertEqual(project_version, poetry_version) + class TestDocsPackaging(unittest.TestCase): """Test Version in doc requirements is the same pyproject.""" def test_version(self): - """Verify that pyproject.toml dev dependencies have the same versions as in the docs requirements.txt.""" + """Verify that pyproject.toml dev dependecies have the same versions as in the docs requirements.txt.""" parent_path = os.path.dirname(os.path.dirname(os.path.dirname(os.path.realpath(__file__)))) poetry_path = os.path.join(parent_path, "pyproject.toml") poetry_details = toml.load(poetry_path)["tool"]["poetry"]["group"]["dev"]["dependencies"] diff --git a/pyproject.toml b/pyproject.toml index f9155520..01e84124 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,20 +1,13 @@ [tool.poetry] name = "nautobot-golden-config" -version = "1.5.0" +version = "1.0.0" description = "A plugin for configuration on nautobot" -authors = ["Network to Code, LLC", ""] - +authors = ["Network to Code, LLC "] license = "Apache-2.0" - readme = "README.md" -homepage = "https://docs.nautobot.com/projects/golden-config/en/latest/" +homepage = "https://github.com/nautobot/nautobot-plugin-golden-config" repository = "https://github.com/nautobot/nautobot-plugin-golden-config" -documentation = "https://docs.nautobot.com/projects/golden-config/en/latest/" keywords = ["nautobot", "nautobot-plugin"] -include = [ - "LICENSE", - "README.md", -] classifiers = [ "Intended Audience :: Developers", "Development Status :: 5 - Production/Stable", @@ -24,54 +17,48 @@ classifiers = [ "Programming Language :: Python :: 3.10", "Programming Language :: Python :: 3.11", ] +include = [ + "LICENSE", + "README.md", +] packages = [ { include = "nautobot_golden_config" }, ] - -[tool.poetry.urls] -"Changelog" = "https://docs.nautobot.com/projects/golden-config/en/latest/admin/release_notes/" -"Bug Tracker" = "https://github.com/nautobot/nautobot-plugin-golden-config/issues" - [tool.poetry.dependencies] -python = "^3.8,<3.12" -deepdiff = ">=5.5.0,!=6.0,!=6.1,<7" -django-pivot = "^1.8.1" -matplotlib = "^3.3.2" -nautobot = ">=2.0.0-rc.2" # TODO: 2.0: Point to 2.x version -nautobot-plugin-nornir = { git = "https://github.com/nautobot/nautobot-plugin-nornir.git", branch = "next-2.0" } # TODO: 2.0: Point to 2.x version -nornir-nautobot = { git = "https://github.com/nautobot/nornir-nautobot.git", branch = "next-2.0" } # TODO: 2.0: Point to 2.x version - -toml = "^0.10.2" -netutils = "^1.5.0" -hier-config = "^2.2.2" -# nautobot-capacity-metrics = "2.0.0" TODO: 2.0: Turn on +python = ">=3.8,<3.12" +# Used for local development +nautobot = { version = "^1.4.0", optional = true } [tool.poetry.group.dev.dependencies] bandit = "*" -# Black 23.x.x configuration changes and migration files are taken into account black = "*" +coverage = "*" django-debug-toolbar = "*" -# we need to pin flake8 because of package dependencies that cause it to downgrade and -# therefore cause issues with linting since older versions do not take .flake8 as config -flake8 = "^3.9.2" +flake8 = "*" invoke = "*" +ipython = "*" pydocstyle = "*" pylint = "*" pylint-django = "*" -pylint-nautobot = { git = "https://github.com/nautobot/pylint-nautobot.git", branch = "develop" } # TODO: 2.0: Point to pypi +pylint-nautobot = "*" +pytest = "*" +python-dotenv = "^1.0.0" yamllint = "*" +toml = "*" Markdown = "*" # Rendering docs to HTML mkdocs = "1.5.2" # Material for MkDocs theme -mkdocs-material = "9.2.4" +mkdocs-material = "9.1.15" # Render custom markdown for version added/changed/remove notes mkdocs-version-annotations = "1.0.0" # Automatic documentation from sources, for MkDocs mkdocstrings = "0.22.0" mkdocstrings-python = "1.5.2" +[tool.poetry.extras] +nautobot = ["nautobot"] [tool.black] line-length = 120 @@ -98,8 +85,8 @@ exclude = ''' [tool.pylint.master] # Include the pylint_django plugin to avoid spurious warnings about Django patterns -load-plugins="pylint_django,pylint_nautobot" -ignore=["jinja_filters.py", ".venv"] +load-plugins="pylint_django, pylint_nautobot" +ignore=".venv" [tool.pylint.basic] # No docstrings required for private methods (Pylint default), or for test_ functions, or for inner Meta classes. @@ -109,9 +96,7 @@ no-docstring-rgx="^(_|test_|Meta$)" # Line length is enforced by Black, so pylint doesn't need to check it. # Pylint and Black disagree about how to format multi-line arrays; Black wins. disable = """, - line-too-long, - too-few-public-methods, - duplicate-code, + line-too-long """ [tool.pylint.miscellaneous] @@ -121,6 +106,11 @@ notes = """, XXX, """ +[tool.pylint-nautobot] +supported_nautobot_versions = [ + "1.4.0" +] + [tool.pydocstyle] convention = "google" inherit = false @@ -131,7 +121,7 @@ match-dir = "(?!tests|migrations|development)[^\\.].*" # My docstring is on the line after the opening quotes instead of on the same line as them. # """ # We've discussed and concluded that we consider this to be a valid style choice. -add_ignore = "D212,D417" +add_ignore = "D212" [build-system] requires = ["poetry_core>=1.0.0"] @@ -142,6 +132,3 @@ testpaths = [ "tests" ] addopts = "-vv --doctest-modules" - -[tool.pylint-nautobot] -supported_nautobot_versions = ["2"] \ No newline at end of file diff --git a/tasks.py b/tasks.py index f2e22f03..99b59ba0 100644 --- a/tasks.py +++ b/tasks.py @@ -1,6 +1,6 @@ """Tasks for use with Invoke. -(c) 2020-2023 Network To Code +Copyright (c) 2023, Network to Code, LLC Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at @@ -12,11 +12,16 @@ limitations under the License. """ -import os from distutils.util import strtobool +from invoke import Collection, task as invoke_task +import os + +from dotenv import load_dotenv -from invoke import Collection -from invoke import task as invoke_task + +def _load_dotenv(): + load_dotenv("./development/development.env") + load_dotenv("./development/creds.env") def is_truthy(arg): @@ -40,9 +45,9 @@ def is_truthy(arg): namespace.configure( { "nautobot_golden_config": { - "nautobot_ver": "2.0.0-rc.2", - "project_name": "nautobot_golden_config", - "python_ver": "3.11", + "nautobot_ver": "latest", + "project_name": "nautobot-golden-config", + "python_ver": "3.8", "local": False, "compose_dir": os.path.join(os.path.dirname(__file__), "development"), "compose_files": [ @@ -77,22 +82,23 @@ def task_wrapper(function=None): def docker_compose(context, command, **kwargs): - """Helper function for running a specific docker-compose command with all appropriate parameters and environment. + """Helper function for running a specific docker compose command with all appropriate parameters and environment. Args: context (obj): Used to run specific commands - command (str): Command string to append to the "docker-compose ..." command, such as "build", "up", etc. + command (str): Command string to append to the "docker compose ..." command, such as "build", "up", etc. **kwargs: Passed through to the context.run() call. """ build_env = { - # Note: 'docker-compose logs' will stop following after 60 seconds by default, + # Note: 'docker compose logs' will stop following after 60 seconds by default, # so we are overriding that by setting this environment variable. "COMPOSE_HTTP_TIMEOUT": context.nautobot_golden_config.compose_http_timeout, "NAUTOBOT_VER": context.nautobot_golden_config.nautobot_ver, "PYTHON_VER": context.nautobot_golden_config.python_ver, + **kwargs.pop("env", {}), } compose_command_tokens = [ - "docker-compose", + "docker compose", f"--project-name {context.nautobot_golden_config.project_name}", f'--project-directory "{context.nautobot_golden_config.compose_dir}"', ] @@ -108,7 +114,7 @@ def docker_compose(context, command, **kwargs): if service is not None: compose_command_tokens.append(service) - print(f'Running docker-compose command "{command}"') + print(f'Running docker compose command "{command}"') compose_command = " ".join(compose_command_tokens) return context.run(compose_command, env=build_env, **kwargs) @@ -125,9 +131,11 @@ def run_command(context, command, **kwargs): if "nautobot" in results.stdout: compose_command = f"exec nautobot {command}" else: - compose_command = f"run --entrypoint '{command}' nautobot" + compose_command = f"run --rm --entrypoint '{command}' nautobot" + + pty = kwargs.pop("pty", True) - docker_compose(context, compose_command, pty=True) + docker_compose(context, compose_command, pty=pty, **kwargs) # ------------------------------------------------------------------------------ @@ -159,42 +167,66 @@ def generate_packages(context): run_command(context, command) +@task +def lock(context): + """Generate poetry.lock inside the Nautobot container.""" + run_command(context, "poetry lock --no-update") + + # ------------------------------------------------------------------------------ # START / STOP / DEBUG # ------------------------------------------------------------------------------ -@task -def debug(context): - """Start Nautobot and its dependencies in debug mode.""" - print("Starting Nautobot in debug mode...") - docker_compose(context, "up") +@task(help={"service": "If specified, only affect this service."}) +def debug(context, service=""): + """Start specified or all services and its dependencies in debug mode.""" + print(f"Starting {service} in debug mode...") + docker_compose(context, "up", service=service) @task(help={"service": "If specified, only affect this service."}) -def start(context, service=None): - """Start Nautobot and its dependencies in detached mode.""" +def start(context, service=""): + """Start specified or all services and its dependencies in detached mode.""" print("Starting Nautobot in detached mode...") docker_compose(context, "up --detach", service=service) -@task -def restart(context): - """Gracefully restart all containers.""" +@task(help={"service": "If specified, only affect this service."}) +def restart(context, service=""): + """Gracefully restart specified or all services.""" print("Restarting Nautobot...") - docker_compose(context, "restart") + docker_compose(context, "restart", service=service) -@task -def stop(context): - """Stop Nautobot and its dependencies.""" +@task(help={"service": "If specified, only affect this service."}) +def stop(context, service=""): + """Stop specified or all services, if service is not specified, remove all containers.""" print("Stopping Nautobot...") - docker_compose(context, "down") + docker_compose(context, "stop" if service else "down --remove-orphans", service=service) @task def destroy(context): """Destroy all containers and volumes.""" print("Destroying Nautobot...") - docker_compose(context, "down --volumes") + docker_compose(context, "down --remove-orphans --volumes") + + +@task +def export(context): + """Export docker compose configuration to `compose.yaml` file. + + Useful to: + + - Debug docker compose configuration. + - Allow using `docker compose` command directly without invoke. + """ + docker_compose(context, "convert > compose.yaml") + + +@task(name="ps", help={"all": "Show all, including stopped containers"}) +def ps_task(context, all=False): + """List containers.""" + docker_compose(context, f"ps {'--all' if all else ''}") @task @@ -207,13 +239,13 @@ def vscode(context): @task( help={ - "service": "Docker-compose service name to view (default: nautobot)", - "follow": "Follow logs", - "tail": "Tail N number of lines or 'all'", + "service": "If specified, only display logs for this service (default: all)", + "follow": "Flag to follow logs (default: False)", + "tail": "Tail N number of lines (default: all)", } ) -def logs(context, service="nautobot", follow=False, tail=None): - """View the logs of a docker-compose service.""" +def logs(context, service="", follow=False, tail=0): + """View the logs of a docker compose service.""" command = "logs " if follow: @@ -221,18 +253,21 @@ def logs(context, service="nautobot", follow=False, tail=None): if tail: command += f"--tail={tail} " - command += service - docker_compose(context, command) + docker_compose(context, command, service=service) # ------------------------------------------------------------------------------ # ACTIONS # ------------------------------------------------------------------------------ -@task -def nbshell(context): +@task(help={"file": "Python file to execute"}) +def nbshell(context, file=""): """Launch an interactive nbshell session.""" - command = "nautobot-server nbshell" - run_command(context, command) + command = [ + "nautobot-server", + "nbshell", + f"< '{file}'" if file else "", + ] + run_command(context, " ".join(command), pty=not bool(file)) @task @@ -244,7 +279,7 @@ def shell_plus(context): @task def cli(context): - """Launch a bash shell inside the running Nautobot container.""" + """Launch a bash shell inside the Nautobot container.""" run_command(context, "bash") @@ -302,6 +337,181 @@ def post_upgrade(context): run_command(context, command) +@task( + help={ + "service": "Docker compose service name to run command in (default: nautobot).", + "command": "Command to run (default: bash).", + "file": "File to run command with (default: empty)", + }, +) +def exec(context, service="nautobot", command="bash", file=""): + """Launch a command inside the running container (defaults to bash shell inside nautobot container).""" + command = [ + "exec", + "--", + service, + command, + f"< '{file}'" if file else "", + ] + docker_compose(context, " ".join(command), pty=not bool(file)) + + +@task( + help={ + "query": "SQL command to execute and quit (default: empty)", + "input": "SQL file to execute and quit (default: empty)", + "output": "Ouput file, overwrite if exists (default: empty)", + } +) +def dbshell(context, query="", input="", output=""): + """Start database CLI inside the running `db` container. + + Doesn't use `nautobot-server dbshell`, using started `db` service container only. + """ + if input and query: + raise ValueError("Cannot specify both, `input` and `query` arguments") + if output and not (input or query): + raise ValueError("`output` argument requires `input` or `query` argument") + + _load_dotenv() + + service = "db" + env_vars = {} + command = ["exec"] + + if "docker-compose.mysql.yml" in context.nautobot_golden_config.compose_files: + env_vars["MYSQL_PWD"] = os.getenv("MYSQL_PASSWORD") + command += [ + "--env=MYSQL_PWD", + "--", + service, + "mysql", + f"--user='{os.getenv('MYSQL_USER')}'", + f"--database='{os.getenv('MYSQL_DATABASE')}'", + ] + if query: + command += [f"--execute='{query}'"] + elif "docker-compose.postgres.yml" in context.nautobot_golden_config.compose_files: + command += [ + "--", + service, + "psql", + f"--username='{os.getenv('POSTGRES_USER')}'", + f"--dbname='{os.getenv('POSTGRES_DB')}'", + ] + if query: + command += [f"--command='{query}'"] + else: + raise ValueError("Unsupported database backend.") + + if input: + command += [f"< '{input}'"] + if output: + command += [f"> '{output}'"] + + docker_compose(context, " ".join(command), env=env_vars, pty=not (input or output or query)) + + +@task( + help={ + "input": "SQL dump file to replace the existing database with. This can be generated using `invoke backup-db` (default: `dump.sql`).", + } +) +def import_db(context, input="dump.sql"): + """Stop Nautobot containers and replace the current database with the dump into the running `db` container.""" + docker_compose(context, "stop -- nautobot worker") + + _load_dotenv() + + service = "db" + env_vars = {} + command = ["exec"] + + if "docker-compose.mysql.yml" in context.nautobot_golden_config.compose_files: + env_vars["MYSQL_PWD"] = os.getenv("MYSQL_PASSWORD") + command += [ + "--env=MYSQL_PWD", + "--", + service, + "mysql", + f"--user='{os.getenv('MYSQL_USER')}'", + f"--database='{os.getenv('MYSQL_DATABASE')}'", + ] + elif "docker-compose.postgres.yml" in context.nautobot_golden_config.compose_files: + command += [ + "--", + service, + "psql", + f"--username='{os.getenv('POSTGRES_USER')}'", + "postgres", + ] + else: + raise ValueError("Unsupported database backend.") + + command += [f"< '{input}'"] + + docker_compose(context, " ".join(command), env=env_vars, pty=False) + + print("Database import complete, you can start Nautobot now: `invoke start`") + + +@task( + help={ + "output": "Ouput file, overwrite if exists (default: `dump.sql`)", + "readable": "Flag to dump database data in more readable format (default: `True`)", + } +) +def backup_db(context, output="dump.sql", readable=True): + """Dump database into `output` file from running `db` container.""" + _load_dotenv() + + service = "db" + env_vars = {} + command = ["exec"] + + if "docker-compose.mysql.yml" in context.nautobot_golden_config.compose_files: + env_vars["MYSQL_PWD"] = os.getenv("MYSQL_ROOT_PASSWORD") + command += [ + "--env=MYSQL_PWD", + "--", + service, + "mysqldump", + "--user=root", + "--add-drop-database", + "--skip-extended-insert" if readable else "", + "--databases", + os.getenv("MYSQL_DATABASE", ""), + ] + elif "docker-compose.postgres.yml" in context.nautobot_golden_config.compose_files: + command += [ + "--", + service, + "pg_dump", + "--clean", + "--create", + "--if-exists", + f"--username='{os.getenv('POSTGRES_USER')}'", + f"--dbname='{os.getenv('POSTGRES_DB')}'", + ] + + if readable: + command += ["--inserts"] + else: + raise ValueError("Unsupported database backend.") + + if output: + command += [f"> '{output}'"] + + docker_compose(context, " ".join(command), env=env_vars, pty=False) + + print(50 * "=") + print("The database backup has been successfully completed and saved to the file:") + print(output) + print("If you want to import this database backup, please execute the following command:") + print(f"invoke import-db --input '{output}'") + print(50 * "=") + + # ------------------------------------------------------------------------------ # DOCS # ------------------------------------------------------------------------------ @@ -317,6 +527,25 @@ def docs(context): start(context, service="docs") +@task +def build_and_check_docs(context): + """Build documentation to be available within Nautobot.""" + command = "mkdocs build --no-directory-urls --strict" + run_command(context, command) + + +@task(name="help") +def help_task(context): + """Print the help of available tasks.""" + import tasks # pylint: disable=all + + root = Collection.from_module(tasks) + for task_name in sorted(root.task_names): + print(50 * "-") + print(f"invoke {task_name} --help") + context.run(f"invoke {task_name} --help") + + # ------------------------------------------------------------------------------ # TESTS # ------------------------------------------------------------------------------ @@ -375,7 +604,7 @@ def bandit(context): @task def yamllint(context): - """Run yamllint to validate formatting adheres to NTC defined YAML standards. + """Run yamllint to validate formating adheres to NTC defined YAML standards. Args: context (obj): Used to run specific commands @@ -387,7 +616,7 @@ def yamllint(context): @task def check_migrations(context): """Check for missing migrations.""" - command = "nautobot-server --config=nautobot/core/tests/nautobot_config.py makemigrations --dry-run --check" + command = "nautobot-server makemigrations --dry-run --check" run_command(context, command) @@ -398,9 +627,19 @@ def check_migrations(context): "label": "specify a directory or module to test instead of running all Nautobot tests", "failfast": "fail as soon as a single test fails don't run the entire test suite", "buffer": "Discard output from passing tests", + "pattern": "Run specific test methods, classes, or modules instead of all tests", + "verbose": "Enable verbose test output.", } ) -def unittest(context, keepdb=False, label="nautobot_golden_config", failfast=False, buffer=True): +def unittest( + context, + keepdb=False, + label="nautobot_golden_config", + failfast=False, + buffer=True, + pattern="", + verbose=False, +): """Run Nautobot unit tests.""" command = f"coverage run --module nautobot.core.cli test {label}" @@ -410,6 +649,11 @@ def unittest(context, keepdb=False, label="nautobot_golden_config", failfast=Fal command += " --failfast" if buffer: command += " --buffer" + if pattern: + command += f" -k='{pattern}'" + if verbose: + command += " --verbosity 2" + run_command(context, command) @@ -423,10 +667,12 @@ def unittest_coverage(context): @task( help={ - "failfast": "fail as soon as a single test fails don't run the entire test suite", + "failfast": "fail as soon as a single test fails don't run the entire test suite. (default: False)", + "keepdb": "Save and re-use test database between test runs for faster re-testing. (default: False)", + "lint-only": "Only run linters; unit tests will be excluded. (default: False)", } ) -def tests(context, failfast=False): +def tests(context, failfast=False, keepdb=False, lint_only=False): """Run all tests for this plugin.""" # If we are not running locally, start the docker containers so we don't have to for each test if not is_truthy(context.nautobot_golden_config.local): @@ -445,7 +691,10 @@ def tests(context, failfast=False): yamllint(context) print("Running pylint...") pylint(context) - print("Running unit tests...") - unittest(context, failfast=failfast) + print("Running mkdocs...") + build_and_check_docs(context) + if not lint_only: + print("Running unit tests...") + unittest(context, failfast=failfast, keepdb=keepdb) print("All tests have passed!") unittest_coverage(context) From 008169b3031d631cf93604c8b15706d64ac43f61 Mon Sep 17 00:00:00 2001 From: Jan Snasel Date: Wed, 13 Sep 2023 11:39:26 +0000 Subject: [PATCH 2/9] chore: Manual fixes --- .bandit.yml | 5 +- .flake8 | 7 +- .github/workflows/ci.yml | 25 +- .github/workflows/upstream_testing.yml | 4 +- .gitignore | 2 + README.md | 73 ++-- development/Dockerfile | 8 +- development/development.env | 11 + development/docker-compose.dev.yml | 13 + development/nautobot_config.py | 89 ++++- docs/admin/compatibility_matrix.md | 18 +- docs/admin/release_notes/version_1.0.md | 74 ++-- docs/requirements.txt | 2 +- nautobot_golden_config/__init__.py | 53 ++- nautobot_golden_config/tests/test_api.py | 409 ++++++++++++++++++++++- poetry.lock | 339 +++++++++++++++++-- pyproject.toml | 50 ++- tasks.py | 6 +- 18 files changed, 1028 insertions(+), 160 deletions(-) diff --git a/.bandit.yml b/.bandit.yml index 56f7a83b..78140801 100644 --- a/.bandit.yml +++ b/.bandit.yml @@ -1,6 +1,7 @@ --- -skips: [] # No need to check for security issues in the test scripts! exclude_dirs: - - "./tests/" + - "./nautobot_golden_config/tests/" - "./.venv/" +skips: + - "B404" diff --git a/.flake8 b/.flake8 index c9f5e84d..c925648d 100644 --- a/.flake8 +++ b/.flake8 @@ -1,7 +1,12 @@ [flake8] ignore = E501, # Line length is enforced by Black, so flake8 doesn't need to check it - W503 # Black disagrees with this rule, as does PEP 8; Black wins + W503, # Black disagrees with this rule, as does PEP 8; Black wins + # TODO: Review the following rules, not in the template + F811, + F401, + F405, + E203, exclude = migrations, __pycache__, diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 65d3c1be..d3f05cb2 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -13,7 +13,9 @@ on: # yamllint disable-line rule:truthy rule:comments pull_request: ~ env: - PLUGIN_NAME: "nautobot-plugin-golden-config" + # TODO Fix to be repository name + # PLUGIN_NAME: "nautobot-plugin-golden-config" + PLUGIN_NAME: "nautobot-golden-config" jobs: black: @@ -82,8 +84,8 @@ jobs: strategy: fail-fast: true matrix: - python-version: ["3.8"] - nautobot-version: ["1.4.0"] + python-version: ["3.11"] + nautobot-version: ["2.0.0-rc.2"] env: INVOKE_NAUTOBOT_GOLDEN_CONFIG_PYTHON_VER: "${{ matrix.python-version }}" INVOKE_NAUTOBOT_GOLDEN_CONFIG_NAUTOBOT_VER: "${{ matrix.nautobot-version }}" @@ -121,17 +123,20 @@ jobs: matrix: python-version: ["3.8", "3.9", "3.10", "3.11"] db-backend: ["postgresql"] - nautobot-version: ["stable"] + nautobot-version: ["2.0.0-rc.2"] # ["latest"] + # The include is a method to limit the amount of jobs ran. This essentially + # means that in addition to standard postgres and stable, also the lowest + # supported version and with mysql include: - python-version: "3.11" db-backend: "postgresql" - nautobot-version: "1.4.0" - - python-version: "3.8" - db-backend: "mysql" - nautobot-version: "1.4.0" + nautobot-version: "2.0.0-rc.2" - python-version: "3.11" db-backend: "mysql" - nautobot-version: "stable" + nautobot-version: "2.0.0-rc.2" + - python-version: "3.8" + db-backend: "mysql" + nautobot-version: "latest" runs-on: "ubuntu-20.04" env: INVOKE_NAUTOBOT_GOLDEN_CONFIG_PYTHON_VER: "${{ matrix.python-version }}" @@ -189,7 +194,7 @@ jobs: - name: "Upload binaries to release" uses: "svenstaro/upload-release-action@v2" with: - repo_token: "${{ secrets.NTC_GITHUB_TOKEN }}" # use GH_NAUTOBOT_BOT_TOKEN for Nautobot Org repos. + repo_token: "${{ secrets.GH_NAUTOBOT_BOT_TOKEN }}" file: "dist/*" tag: "${{ github.ref }}" overwrite: true diff --git a/.github/workflows/upstream_testing.yml b/.github/workflows/upstream_testing.yml index 0deb8033..31c7c9d4 100644 --- a/.github/workflows/upstream_testing.yml +++ b/.github/workflows/upstream_testing.yml @@ -10,4 +10,6 @@ jobs: uses: "nautobot/nautobot/.github/workflows/plugin_upstream_testing_base.yml@develop" with: # Below could potentially be collapsed into a single argument if a concrete relationship between both is enforced invoke_context_name: "NAUTOBOT_GOLDEN_CONFIG" - plugin_name: "nautobot-plugin-golden-config" + # TODO Fix to be repository name + # plugin_name: "nautobot-plugin-golden-config" + plugin_name: "nautobot-golden-config" diff --git a/.gitignore b/.gitignore index 3643abe3..856602c2 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,5 @@ +nautobot_golden_config/transposer.py + # Ansible Retry Files *.retry diff --git a/README.md b/README.md index ae6626db..04143ede 100644 --- a/README.md +++ b/README.md @@ -1,43 +1,52 @@ -# Golden Config - - +# Nautobot Golden Config

- +
- +
- An App for Nautobot. + An App for Nautobot.

## Overview -> Developer Note: Add a long (2-3 paragraphs) description of what the App does, what problems it solves, what functionality it adds to Nautobot, what external systems it works with etc. +The Golden Config plugin is a Nautobot plugin that provides a NetDevOps approach to golden configuration and configuration compliance. -### Screenshots +### Key Use Cases -> Developer Note: Add any representative screenshots of the App in action. These images should also be added to the `docs/user/app_use_cases.md` section. +This plugin enable five (5) key use cases. -> Developer Note: Place the files in the `docs/images/` folder and link them using only full URLs from GitHub, for example: `![Overview](https://raw.githubusercontent.com/nautobot/nautobot-plugin-golden-config/develop/docs/images/plugin-overview.png)`. This absolute static linking is required to ensure the README renders properly in GitHub, the docs site, and any other external sites like PyPI. +1. **Configuration Backups** - Is a Nornir process to connect to devices, optionally parse out lines/secrets, backup the configuration, and save to a Git repository. +2. **Intended Configuration** - Is a Nornir process to generate configuration based on a Git repo of Jinja files to combine with a GraphQL generated data and a Git repo to store the intended configuration. +3. **Source of Truth Aggregation** - Is a GraphQL query per device that creates a data structure used in the generation of configuration. +4. **Configuration Compliance** - Is a process to run comparison of the actual (via backups) and intended (via Jinja file creation) CLI configurations upon saving the actual and intended configuration. This is started by either a Nornir process for cli-like configurations or calling the API for json-like configurations +5. **Configuration Postprocessing** - (beta) This process renders a valid configuration artifact from an intended configuration, that can be pushed to devices. The current implementation renders this configuration; however, **it doesn't push it** to the target device. -More screenshots can be found in the [Using the App](https://docs.nautobot.com/projects/golden-config/en/latest/user/app_use_cases/) page in the documentation. Here's a quick overview of some of the plugin's added functionality: +> Notice: The operators of their own Nautobot instance are welcome to use any combination of these features. Though the appearance may seem like they are tightly coupled, this isn't actually the case. For example, one can obtain backup configurations from their current RANCID/Oxidized process and simply provide a Git Repo of the location of the backup configurations, and the compliance process would work the same way. Also, another user may only want to generate configurations, but not want to use other features, which is perfectly fine to do so. -![](https://raw.githubusercontent.com/nautobot/nautobot-plugin-golden-config/develop/docs/images/placeholder.png) +## Screenshots -## Try it out! +There are many features and capabilities the plugin provides into the Nautobot ecosystem. The following screenshots are intended to provide a quick visual overview of some of these features. + +The golden configuration is driven by jobs that run a series of tasks and the result is captured in this overview. -> Developer Note: Only keep this section if appropriate. Update link to correct sandbox. +![Overview](https://raw.githubusercontent.com/nautobot/nautobot-plugin-golden-config/develop/docs/images/ss_golden-overview.png) + +The compliance report provides a high-level overview on the compliance of your network. +![Compliance Report](https://raw.githubusercontent.com/nautobot/nautobot-plugin-golden-config/develop/docs/images/ss_compliance-report.png) + +The compliance overview will provide a per device and feature overview on the compliance of your network devices. +![Compliance Overview](https://raw.githubusercontent.com/nautobot/nautobot-plugin-golden-config/develop/docs/images/ss_compliance-overview.png) + +Drilling into a specific device and feature, you can get an immediate detailed understanding of your device. +![Compliance Device](https://raw.githubusercontent.com/nautobot/nautobot-plugin-golden-config/develop/docs/images/ss_compliance-device.png) + +![Compliance Rule](https://raw.githubusercontent.com/nautobot/nautobot-plugin-golden-config/develop/docs/images/ss_compliance-rule.png) + +## Try it out! This App is installed in the Nautobot Community Sandbox found over at [demo.nautobot.com](https://demo.nautobot.com/)! @@ -45,22 +54,22 @@ This App is installed in the Nautobot Community Sandbox found over at [demo.naut ## Documentation -Full documentation for this App can be found over on the [Nautobot Docs](https://docs.nautobot.com) website: +Full web-based HTML documentation for this app can be found over on the [Nautobot Docs](https://docs.nautobot.com/projects/golden-config/en/latest/) website: -- [User Guide](https://docs.nautobot.com/projects/golden-config/en/latest/user/app_overview/) - Overview, Using the App, Getting Started. -- [Administrator Guide](https://docs.nautobot.com/projects/golden-config/en/latest/admin/install/) - How to Install, Configure, Upgrade, or Uninstall the App. -- [Developer Guide](https://docs.nautobot.com/projects/golden-config/en/latest/dev/contributing/) - Extending the App, Code Reference, Contribution Guide. -- [Release Notes / Changelog](https://docs.nautobot.com/projects/golden-config/en/latest/admin/release_notes/). -- [Frequently Asked Questions](https://docs.nautobot.com/projects/golden-config/en/latest/user/faq/). +- [User Guide](https://docs.nautobot.com/projects/golden-config/en/latest/user/app_overview/) - Overview, Using the App, Getting Started, Navigating compliance (cli, json, custom), backup, app usage, intended state creation. +- [Administrator Guide](https://docs.nautobot.com/projects/golden-config/en/latest/admin/admin_install/) - How to Install, Configure, Upgrade, or Uninstall the App. +- [Developer Guide](https://docs.nautobot.com/projects/golden-config/en/latest/dev/dev_contributing/) - Extending the App, Code Reference, Contribution Guide. +- [Release Notes / Changelog](https://docs.nautobot.com/projects/golden-config/en/latest/admin/release_notes/) +- [Frequently Asked Questions](https://docs.nautobot.com/projects/golden-config/en/latest/user/app_faq/) -### Contributing to the Documentation +### Contributing to the Docs -You can find all the Markdown source for the App documentation under the [`docs`](https://github.com/nautobot/nautobot-plugin-golden-config/tree/develop/docs) folder in this repository. For simple edits, a Markdown capable editor is sufficient: clone the repository and edit away. +You can find all the Markdown source for the App documentation under the [docs](https://github.com/nautobot/nautobot-plugin-golden-config/tree/develop/docs) folder in this repository. For simple edits, a Markdown capable editor is sufficient - clone the repository and edit away. -If you need to view the fully-generated documentation site, you can build it with [MkDocs](https://www.mkdocs.org/). A container hosting the documentation can be started using the `invoke` commands (details in the [Development Environment Guide](https://docs.nautobot.com/projects/golden-config/en/latest/dev/dev_environment/#docker-development-environment)) on [http://localhost:8001](http://localhost:8001). Using this container, as your changes to the documentation are saved, they will be automatically rebuilt and any pages currently being viewed will be reloaded in your browser. +If you need to view the fully generated documentation site, you can build it with [mkdocs](https://www.mkdocs.org/). A container hosting the docs will be started using the invoke commands (details in the [Development Environment Guide](https://docs.nautobot.com/projects/golden-config/en/latest/dev/dev_environment/#docker-development-environment)) on [http://localhost:8001](http://localhost:8001). As your changes are saved, the live docs will be automatically reloaded. Any PRs with fixes or improvements are very welcome! ## Questions -For any questions or comments, please check the [FAQ](https://docs.nautobot.com/projects/golden-config/en/latest/user/faq/) first. Feel free to also swing by the [Network to Code Slack](https://networktocode.slack.com/) (channel `#nautobot`), sign up [here](http://slack.networktocode.com/) if you don't have an account. +For any questions or comments, please check the [FAQ](https://docs.nautobot.com/projects/golden-config/en/latest/user/app_faq/) first. Feel free to also swing by the [Network to Code Slack](https://networktocode.slack.com/) (channel `#nautobot`), sign up [here](http://slack.networktocode.com/) if you don't have an account. diff --git a/development/Dockerfile b/development/Dockerfile index 34ba9b20..0b746de2 100644 --- a/development/Dockerfile +++ b/development/Dockerfile @@ -6,11 +6,11 @@ # ------------------------------------------------------------------------------------- # !!! USE CAUTION WHEN MODIFYING LINES BELOW -# Accepts a desired Nautobot version as build argument, default to 1.4.0 -ARG NAUTOBOT_VER="1.4.0" +# Accepts a desired Nautobot version as build argument, default to 2.0.0 +ARG NAUTOBOT_VER="2.0.0-rc.2" -# Accepts a desired Python version as build argument, default to 3.8 -ARG PYTHON_VER="3.8" +# Accepts a desired Python version as build argument, default to 3.11 +ARG PYTHON_VER="3.11" # Retrieve published development image of Nautobot base which should include most CI dependencies FROM ghcr.io/nautobot/nautobot-dev:${NAUTOBOT_VER}-py${PYTHON_VER} diff --git a/development/development.env b/development/development.env index 54f0b870..6b7d03e2 100644 --- a/development/development.env +++ b/development/development.env @@ -36,3 +36,14 @@ POSTGRES_DB=${NAUTOBOT_DB_NAME} MYSQL_USER=${NAUTOBOT_DB_USER} MYSQL_DATABASE=${NAUTOBOT_DB_NAME} MYSQL_ROOT_HOST=% + +# Golden Configuration specific +PER_FEATURE_WIDTH=13 +PER_FEATURE_HEIGHT=4 +PER_FEATURE_BAR_WIDTH=0.15 +ENABLE_COMPLIANCE=True +ENABLE_INTENDED=True +ENABLE_BACKUP=True +ENABLE_SOTAGG=True +ENABLE_POSTPROCESSING=True +ALLOWED_OS=all diff --git a/development/docker-compose.dev.yml b/development/docker-compose.dev.yml index 3374422a..8e8c15db 100644 --- a/development/docker-compose.dev.yml +++ b/development/docker-compose.dev.yml @@ -12,6 +12,13 @@ services: volumes: - "./nautobot_config.py:/opt/nautobot/nautobot_config.py" - "../:/source" + # Helper method to mount on top of the python implementations, assuming you are using py3.11 and + # have all of your projects in the same directory. Uncomment out as required. + # - "../../netutils/netutils:/opt/nautobot/lib/python3.11/site-packages/netutils" + # - "../../nornir-nautobot/nornir_nautobot:/opt/nautobot/lib/python3.11/site-packages/nornir_nautobot" + # - "../../nautobot-plugin-nornir/nautobot_plugin_nornir:/opt/nautobot/lib/python3.11/site-packages/nautobot_plugin_nornir" + # - "../../nautobot/nautobot:/opt/nautobot/lib/python3.11/site-packages/nautobot" + healthcheck: test: ["CMD", "true"] # Due to layering, disable: true won't work. Instead, change the test docs: @@ -32,6 +39,12 @@ services: volumes: - "./nautobot_config.py:/opt/nautobot/nautobot_config.py" - "../:/source" + # Helper method to mount on top of the python implementations, assuming you are using py3.11 and + # have all of your projects in the same directory. Uncomment out as required. + # - "../../netutils/netutils:/opt/nautobot/lib/python3.11/site-packages/netutils" + # - "../../nornir-nautobot/nornir_nautobot:/opt/nautobot/lib/python3.11/site-packages/nornir_nautobot" + # - "../../nautobot-plugin-nornir/nautobot_plugin_nornir:/opt/nautobot/lib/python3.11/site-packages/nautobot_plugin_nornir" + # - "../../nautobot/nautobot:/opt/nautobot/lib/python3.11/site-packages/nautobot" healthcheck: test: ["CMD", "true"] # Due to layering, disable: true won't work. Instead, change the test # To expose postgres or redis to the host uncomment the following diff --git a/development/nautobot_config.py b/development/nautobot_config.py index f397ef56..5599a096 100644 --- a/development/nautobot_config.py +++ b/development/nautobot_config.py @@ -2,6 +2,7 @@ import os import sys +from django.utils.module_loading import import_string from nautobot.core.settings import * # noqa: F403 # pylint: disable=wildcard-import,unused-wildcard-import from nautobot.core.settings_funcs import is_truthy, parse_redis_connection @@ -128,14 +129,80 @@ # Apps # -# Enable installed Apps. Add the name of each App to the list. -PLUGINS = ["nautobot_golden_config"] - -# Apps configuration settings. These settings are used by various Apps that the user may have installed. -# Each key in the dictionary is the name of an installed App and its value is a dictionary of settings. -# PLUGINS_CONFIG = { -# 'nautobot_golden_config': { -# 'foo': 'bar', -# 'buzz': 'bazz' -# } -# } +# Enable installed plugins. Add the name of each plugin to the list. +PLUGINS = ["nautobot_plugin_nornir", "nautobot_golden_config"] + +# Plugins configuration settings. These settings are used by various plugins that the user may have installed. +# Each key in the dictionary is the name of an installed plugin and its value is a dictionary of settings. +PLUGINS_CONFIG = { + "nautobot_plugin_nornir": { + "nornir_settings": { + "credentials": "nautobot_plugin_nornir.plugins.credentials.env_vars.CredentialsEnvVars", + "runner": { + "plugin": "threaded", + "options": { + "num_workers": 20, + }, + }, + }, + # dispatcher_mapping may be necessary if you get an error `Cannot import "". Is the library installed?` + # when you run a backup job, and is the name of the platform applied to the device. + # to the Nornir driver names ("arista_eos", "cisco_ios", etc.). + # "dispatcher_mapping": { + # "eos": "nornir_nautobot.plugins.tasks.dispatcher.arista_eos.NautobotNornirDriver", + # "arbitrary_platform_name": "nornir_nautobot.plugins.tasks.dispatcher.arista_eos.NautobotNornirDriver", + # "ios": "nornir_nautobot.plugins.tasks.dispatcher.cisco_ios.NautobotNornirDriver", + # "iosxe": "nornir_nautobot.plugins.tasks.dispatcher.cisco_ios.NautobotNornirDriver", + # "junos": "nornir_nautobot.plugins.tasks.dispatcher.juniper_junos.NautobotNornirDriver", + # "nxos": "nornir_nautobot.plugins.tasks.dispatcher.cisco_nxos.NautobotNornirDriver", + # }, + }, + "nautobot_golden_config": { + "per_feature_bar_width": float(os.environ.get("PER_FEATURE_BAR_WIDTH", 0.15)), + "per_feature_width": int(os.environ.get("PER_FEATURE_WIDTH", 13)), + "per_feature_height": int(os.environ.get("PER_FEATURE_HEIGHT", 4)), + "enable_backup": is_truthy(os.environ.get("ENABLE_BACKUP", True)), + "enable_compliance": is_truthy(os.environ.get("ENABLE_COMPLIANCE", True)), + "enable_intended": is_truthy(os.environ.get("ENABLE_INTENDED", True)), + "enable_sotagg": is_truthy(os.environ.get("ENABLE_SOTAGG", True)), + "sot_agg_transposer": os.environ.get("SOT_AGG_TRANSPOSER"), + "enable_postprocessing": is_truthy(os.environ.get("ENABLE_POSTPROCESSING", True)), + "postprocessing_callables": os.environ.get("POSTPROCESSING_CALLABLES", []), + "postprocessing_subscribed": os.environ.get("POSTPROCESSING_SUBSCRIBED", []), + "jinja_env": { + "undefined": import_string("jinja2.StrictUndefined"), + "trim_blocks": is_truthy(os.getenv("NAUTOBOT_JINJA_ENV_TRIM_BLOCKS", True)), + "lstrip_blocks": is_truthy(os.getenv("NAUTOBOT_JINJA_ENV_LSTRIP_BLOCKS", False)), + }, + # The platform_network_driver_map maps an arbitrary platform network_driver to its corresponding parser. + # Use this if the platform network_driver names in your Nautobot instance don't correspond exactly + # to the Nornir driver names ("arista_eos", "cisco_ios", etc.). + # Each key should == the network_driver of the Nautobot platform object. + # "platform_network_driver_map": { + # "eos": "arista_eos", + # "ios": "cisco_ios", + # "iosxe": "cisco_ios", + # "junos": "juniper_junos", + # "nxos": "cisco_nxos", + # }, + # "get_custom_compliance": "my.custom_compliance.func", + }, +} + +# TODO:Verify this is still needed +# Modify django_jinja Environment for test cases +django_jinja_config = None +for template in TEMPLATES: + if template["BACKEND"].startswith("django_jinja"): + django_jinja_config = template + +if django_jinja_config is not None: + jinja_options = django_jinja_config.get("OPTIONS") + if not jinja_options: + jinja_options = {} + django_jinja_config["OPTIONS"] = jinja_options + # Default behavior ignores UndefinedErrors + jinja_options["undefined"] = "jinja2.StrictUndefined" + +# Import filter function to have it register filter with django_jinja +from nautobot_golden_config.tests import jinja_filters # noqa: E402 diff --git a/docs/admin/compatibility_matrix.md b/docs/admin/compatibility_matrix.md index acd191eb..5b6e64ae 100644 --- a/docs/admin/compatibility_matrix.md +++ b/docs/admin/compatibility_matrix.md @@ -1,8 +1,18 @@ # Compatibility Matrix -!!! warning "Developer Note - Remove Me!" - Explain how the release models of the plugin and of Nautobot work together, how releases are supported, how features and older releases are deprecated etc. +Changes to the support of upstream Nautobot releases will be announced 1 minor or major version ahead. + +The **deprecation policy** will be announced within the [release notes](../release_notes), and updated in the table below. There will be a `stable-.` branch that will be minimally maintained. Any security enhancements or major bugs in that branch will be supported for a limited time. + +While that last supported version will not be strictly enforced via the `max_version` setting, any issues with an updated Nautobot supported version in a minor release will require raising a bug and fixing it in Nautobot core, with no fixes expected in this plugin. This allows the Golden Config plugin the ability to quickly take advantage of the latest features in Nautobot. | Golden Config Version | Nautobot First Support Version | Nautobot Last Support Version | -| ------------- | -------------------- | ------------- | -| 1.0.X | 1.4.0 | 1.99.99 | +| --------------------- | ------------------------------ | ----------------------------- | +| 0.9.X | 1.0.0 | 1.2.99 [Official] | +| 0.10.X | 1.0.0 | 1.2.99 [Official] | +| 1.0.X | 1.2.0 | 1.3.99 [Official] | +| 1.1.X | 1.2.0 | 1.3.99 [Official] | +| 1.2.X | 1.4.0 | 1.5.2 [Official] | +| 1.3.X | 1.4.0 | 1.5.2 [Official] | +| 1.4.X | 1.5.3 | 1.5.99 [Official] | +| 1.5.X | 1.6.1 | 1.6.99 [Official] | diff --git a/docs/admin/release_notes/version_1.0.md b/docs/admin/release_notes/version_1.0.md index 4a9c9a8b..136334d5 100644 --- a/docs/admin/release_notes/version_1.0.md +++ b/docs/admin/release_notes/version_1.0.md @@ -1,48 +1,64 @@ # v1.0 Release Notes -!!! warning "Developer Note - Remove Me!" - Guiding Principles: +- Added support for Jinja2Filters to be be used in configuration generation +- Added support for multiple repos +- Add Git datasource to load GC properties +- Added support for nautobot secrets group on git repos +- Changed the release policy +- Updated navigation to a dedicated top level menu - - Changelogs are for humans, not machines. - - There should be an entry for every single version. - - The same types of changes should be grouped. - - Versions and sections should be linkable. - - The latest version comes first. - - The release date of each version is displayed. - - Mention whether you follow Semantic Versioning. +## v1.0.3 - 2022-06 - Types of changes: - - - `Added` for new features. - - `Changed` for changes in existing functionality. - - `Deprecated` for soon-to-be removed features. - - `Removed` for now removed features. - - `Fixed` for any bug fixes. - - `Security` in case of vulnerabilities. - - -This document describes all new features and changes in the release `1.0`. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +### Fixed -## Release Overview +- [#257](https://github.com/nautobot/nautobot-plugin-golden-config/issues/257) Resolved template_content displaying SoT AGG link on Device detail page if Device not in scope of GoldenConfigSetting + - Change to pull version from package instead of static variable -- Major features or milestones -- Achieved in this `x.y` release -- Changes to compatibility with Nautobot and/or other plugins, libraries etc. +## v1.0.2 - 2022-05 -## [v1.0.1] - 2021-09-08 +### Fixed -### Added +- [#246](https://github.com/nautobot/nautobot-plugin-golden-config/issues/246) Dependabot update to Docker redis-7.x +- [#233](https://github.com/nautobot/nautobot-plugin-golden-config/issues/233) Dependabot update to paramiko-2.10.1 +- [#251](https://github.com/nautobot/nautobot-plugin-golden-config/issues/251) Add description to CSV config replace export -### Changed +## v1.0.1 - 2022-05 ### Fixed -- [#123](https://github.com/nautobot/nautobot-plugin-golden-config/issues/123) Fixed Tag filtering not working in job launch form +- [#238](https://github.com/nautobot/nautobot-plugin-golden-config/issues/238) Fixed repo/docs/homepage links for PyPI +- [#243](https://github.com/nautobot/nautobot-plugin-golden-config/issues/243) Removing unneed javascript source as it is part of [#243](https://github.com/nautobot/nautobot-plugin-golden-config/pull/243) -## [v1.0.0] - 2021-08-03 +## v1.0.0 - 2022-04 ### Added +- [#180](https://github.com/nautobot/nautobot-plugin-golden-config/issues/180) Added Renovate for proactive package management +- [#158](https://github.com/nautobot/nautobot-plugin-golden-config/issues/158) Allow for Jinja2 Filters to be used by GoldenConfig templates +- [#167](https://github.com/nautobot/nautobot-plugin-golden-config/issues/167) Added support for multiple repos +- [#205](https://github.com/nautobot/nautobot-plugin-golden-config/issues/205) Added support for multiple repos via multiple golden config settings +- [#206](https://github.com/nautobot/nautobot-plugin-golden-config/issues/206) Add Git datasource to load GC properties +- [#218](https://github.com/nautobot/nautobot-plugin-golden-config/issues/218) Added ability to storre SoTAgg field leveraging Nautobot saved GraphQl query +- [#225](https://github.com/nautobot/nautobot-plugin-golden-config/issues/225) Added support for nautobot secrets group on git repos +- [#234](https://github.com/nautobot/nautobot-plugin-golden-config/issues/234) Minor update to FAQ + ### Changed +- [#171](https://github.com/nautobot/nautobot-plugin-golden-config/issues/171) Changed the release policy +- [#158](https://github.com/nautobot/nautobot-plugin-golden-config/issues/158) Changed variable job_result to nautobot_job +- [#186](https://github.com/nautobot/nautobot-plugin-golden-config/issues/186) Update mariadb Docker tag to v10.7 +- [#187](https://github.com/nautobot/nautobot-plugin-golden-config/issues/187) Update postgres Docker tag to v14 +- [#188](https://github.com/nautobot/nautobot-plugin-golden-config/issues/188) Update Markdown dependency +- [#190](https://github.com/nautobot/nautobot-plugin-golden-config/issues/190) Update to Nautobot 1.2.0 +- [#190](https://github.com/nautobot/nautobot-plugin-golden-config/issues/190) Remove Nautobot 1.0 specific code +- [#211](https://github.com/nautobot/nautobot-plugin-golden-config/issues/211) Update dependency mariadb to v10.8 +- [#229](https://github.com/nautobot/nautobot-plugin-golden-config/issues/229) Updated navigation to a dedicated top level menu + ### Fixed + +- [#176](https://github.com/nautobot/nautobot-plugin-golden-config/issues/176) Fixed Pylint issue +- [#182](https://github.com/nautobot/nautobot-plugin-golden-config/issues/182) Add reference to Nornir plugin for installation +- [#183](https://github.com/nautobot/nautobot-plugin-golden-config/issues/183) Fixed documentation for sot_agg_transposer default +- [#184](https://github.com/nautobot/nautobot-plugin-golden-config/issues/184) Fix markdown links in quick-start +- [#194](https://github.com/nautobot/nautobot-plugin-golden-config/issues/194) Detailed Error Handling in get_job_filter helper +- [#229](https://github.com/nautobot/nautobot-plugin-golden-config/issues/229) Fixed [#165](https://github.com/nautobot/nautobot-plugin-golden-config/pull/165), Configuration Compliance List View "Device" filter doesn't work diff --git a/docs/requirements.txt b/docs/requirements.txt index 5f961e5c..8f550c99 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,5 +1,5 @@ mkdocs==1.5.2 -mkdocs-material==9.1.15 +mkdocs-material==9.2.4 mkdocstrings==0.22.0 mkdocstrings-python==1.5.2 mkdocs-version-annotations==1.0.0 diff --git a/nautobot_golden_config/__init__.py b/nautobot_golden_config/__init__.py index e2aee2f2..d16e5bdd 100644 --- a/nautobot_golden_config/__init__.py +++ b/nautobot_golden_config/__init__.py @@ -2,25 +2,60 @@ # Metadata is inherited from Nautobot. If not including Nautobot in the environment, this should be added from importlib import metadata + __version__ = metadata.version(__name__) +from jinja2 import StrictUndefined +from django.db.models.signals import post_migrate +from nautobot.core.signals import nautobot_database_ready from nautobot.extras.plugins import NautobotAppConfig -class NautobotGoldenConfigConfig(NautobotAppConfig): +class GoldenConfig(NautobotAppConfig): """Plugin configuration for the nautobot_golden_config plugin.""" name = "nautobot_golden_config" - verbose_name = "Golden Config" + verbose_name = "Golden Configuration" version = __version__ author = "Network to Code, LLC" - description = "A plugin for configuration on nautobot." + author_email = "opensource@networktocode.com" + description = "Nautobot Apps that embraces NetDevOps and automates configuration backups, performs configuration compliance, and generates intended configurations. Includes native Git integration and gives users the flexibility to mix and match the supported features." base_url = "golden-config" - required_settings = [] - min_version = "1.4.0" - max_version = "1.9999" - default_settings = {} - caching_config = {} + default_settings = { + "enable_backup": True, + "enable_compliance": True, + "enable_intended": True, + "enable_sotagg": True, + "enable_postprocessing": False, + "postprocessing_callables": [], + "postprocessing_subscribed": [], + "per_feature_bar_width": 0.3, + "per_feature_width": 13, + "per_feature_height": 4, + "get_custom_compliance": None, + "jinja_env": { + "undefined": StrictUndefined, + "trim_blocks": True, + "lstrip_blocks": False, + }, + } + + def ready(self): + """Register custom signals.""" + from nautobot_golden_config.models import ConfigCompliance # pylint: disable=import-outside-toplevel + + # pylint: disable=import-outside-toplevel + from .signals import ( + config_compliance_platform_cleanup, + post_migrate_create_statuses, + post_migrate_create_job_button, + ) + + nautobot_database_ready.connect(post_migrate_create_statuses, sender=self) + nautobot_database_ready.connect(post_migrate_create_job_button, sender=self) + + super().ready() + post_migrate.connect(config_compliance_platform_cleanup, sender=ConfigCompliance) -config = NautobotGoldenConfigConfig # pylint:disable=invalid-name +config = GoldenConfig # pylint:disable=invalid-name diff --git a/nautobot_golden_config/tests/test_api.py b/nautobot_golden_config/tests/test_api.py index afa12a15..0b4e3824 100644 --- a/nautobot_golden_config/tests/test_api.py +++ b/nautobot_golden_config/tests/test_api.py @@ -1,28 +1,413 @@ """Unit tests for nautobot_golden_config.""" +from copy import deepcopy + from django.contrib.auth import get_user_model -from django.test import TestCase +from django.contrib.contenttypes.models import ContentType from django.urls import reverse +from nautobot.dcim.models import Device, Platform +from nautobot.extras.models import DynamicGroup, GitRepository, GraphQLQuery, Status +from nautobot.core.testing import APITestCase, APIViewTestCases from rest_framework import status -from rest_framework.test import APIClient -from nautobot.users.models import Token +# from nautobot.extras.models import GitRepository, GraphQLQuery, DynamicGroup +from nautobot_golden_config.choices import RemediationTypeChoice +from nautobot_golden_config.models import ConfigPlan, GoldenConfigSetting, RemediationSetting + +from .conftest import ( + create_config_compliance, + create_device, + create_device_data, + create_feature_rule_json, + create_git_repos, + create_job_result, + create_saved_queries, +) User = get_user_model() -class PlaceholderAPITest(TestCase): - """Test the NautobotGoldenConfig API.""" +class GoldenConfigAPITest(APITestCase): # pylint: disable=too-many-ancestors + """Test the ConfigCompliance API.""" def setUp(self): """Create a superuser and token for API calls.""" - self.user = User.objects.create(username="testuser", is_superuser=True) - self.token = Token.objects.create(user=self.user) - self.client = APIClient() - self.client.credentials(HTTP_AUTHORIZATION=f"Token {self.token.key}") + super().setUp() + self.device = create_device() + self.compliance_rule_json = create_feature_rule_json(self.device) + self.base_view = reverse("plugins-api:nautobot_golden_config-api:configcompliance-list") + + def test_root(self): + """Validate the root for Nautobot Chatops API.""" + url = reverse("plugins-api:nautobot_golden_config-api:api-root") + response = self.client.get(f"{url}?format=api", **self.header) + self.assertEqual(response.status_code, 200) - def test_placeholder(self): + def test_device_list(self): """Verify that devices can be listed.""" url = reverse("dcim-api:device-list") - response = self.client.get(url) + self.add_permissions("dcim.view_device") + response = self.client.get(url, **self.header) + self.assertEqual(response.status_code, status.HTTP_200_OK) + self.assertEqual(response.data["count"], 1) + + def test_config_compliance_list_view(self): + """Verify that config compliance objects can be listed.""" + actual = '{"foo": {"bar-1": "baz"}}' + intended = '{"foo": {"bar-2": "baz"}}' + create_config_compliance( + self.device, actual=actual, intended=intended, compliance_rule=self.compliance_rule_json + ) + self.add_permissions("nautobot_golden_config.view_configcompliance") + response = self.client.get(self.base_view, **self.header) + self.assertEqual(response.status_code, status.HTTP_200_OK) + self.assertEqual(response.data["count"], 1) + + def test_config_compliance_post_new_json_compliant(self): + """Verify that config compliance detail view.""" + self.add_permissions("nautobot_golden_config.add_configcompliance") + response = self.client.post( + self.base_view, + data={ + "device": self.device.id, + "intended": '{"foo": {"bar-1": "baz"}}', + "actual": '{"foo": {"bar-1": "baz"}}', + "rule": self.compliance_rule_json.id, + }, + format="json", + **self.header, + ) + self.assertEqual(response.status_code, status.HTTP_201_CREATED) + self.assertTrue(response.data["compliance"]) + + def test_config_compliance_post_new_json_not_compliant(self): + """Verify that config compliance detail view.""" + self.add_permissions("nautobot_golden_config.add_configcompliance") + response = self.client.post( + self.base_view, + data={ + "device": self.device.id, + "intended": '{"foo": {"bar-1": "baz"}}', + "actual": '{"foo": {"bar-2": "baz"}}', + "rule": self.compliance_rule_json.id, + }, + format="json", + **self.header, + ) + self.assertEqual(response.status_code, status.HTTP_201_CREATED) + self.assertFalse(response.data["compliance"]) + + +class GoldenConfigSettingsAPITest(APITestCase): # pylint: disable=too-many-ancestors + """Verify that the combination of values in a GoldenConfigSettings object POST are valid.""" + + def setUp(self): + """Create a superuser and token for API calls.""" + super().setUp() + create_git_repos() + create_saved_queries() + self.add_permissions("nautobot_golden_config.add_goldenconfigsetting") + self.add_permissions("nautobot_golden_config.change_goldenconfigsetting") + self.add_permissions("extras.view_dynamicgroup") + self.base_view = reverse("plugins-api:nautobot_golden_config-api:goldenconfigsetting-list") + self.content_type = ContentType.objects.get(app_label="dcim", model="device") + self.dynamic_group = DynamicGroup.objects.create( + name="test1 site site-4", + content_type=self.content_type, + filter={"has_primary_ip": "True"}, + ) + + self.data = { + "name": "test-setting-1", + "slug": "test_setting_1", + "description": "This is a description field of test-setting-1.", + "weight": 5000, + "tags": [], + "computed_fields": {}, + "custom_fields": {}, + "_custom_field_data": {}, + "backup_path_template": "{{obj.location.parent.name}}/{{obj.location.name}}/{{obj.name}}.cfg", + "intended_path_template": "{{obj.location.parent.name}}/{{obj.location.name}}/{{obj.name}}.cfg", + "jinja_path_template": "templates/{{obj.platform.name}}/{{obj.platform.name}}_main.j2", + "backup_test_connectivity": False, + "dynamic_group": str(self.dynamic_group.id), + "sot_agg_query": str(GraphQLQuery.objects.get(name="GC-SoTAgg-Query-1").id), + "jinja_repository": str(GitRepository.objects.get(name="test-jinja-repo-1").id), + "backup_repository": str(GitRepository.objects.get(name="test-backup-repo-1").id), + "intended_repository": str(GitRepository.objects.get(name="test-intended-repo-1").id), + } + # Since we enforced a singleton pattern on this model in 0.9 release migrations, nuke any auto-created objects. + GoldenConfigSetting.objects.all().delete() + + def test_golden_config_settings_create_good(self): + """Test a POST with good values.""" + response = self.client.post( + self.base_view, + data=self.data, + format="json", + **self.header, + ) + self.assertEqual(response.status_code, status.HTTP_201_CREATED) + self.assertTrue(response.data["created"]) + self.assertTrue(response.data["id"]) + self.assertEqual( + response.data["backup_path_template"], "{{obj.location.parent.name}}/{{obj.location.name}}/{{obj.name}}.cfg" + ) + self.assertEqual( + response.data["intended_path_template"], + "{{obj.location.parent.name}}/{{obj.location.name}}/{{obj.name}}.cfg", + ) + self.assertEqual( + response.data["jinja_path_template"], "templates/{{obj.platform.name}}/{{obj.platform.name}}_main.j2" + ) + self.assertFalse(response.data["backup_test_connectivity"]) + self.assertEqual(response.data["sot_agg_query"]["id"], GraphQLQuery.objects.get(name="GC-SoTAgg-Query-1").id) + self.assertEqual( + response.data["jinja_repository"]["id"], GitRepository.objects.get(name="test-jinja-repo-1").id + ) + self.assertEqual( + response.data["backup_repository"]["id"], GitRepository.objects.get(name="test-backup-repo-1").id + ) + self.assertEqual( + response.data["intended_repository"]["id"], GitRepository.objects.get(name="test-intended-repo-1").id + ) + # Clean up + GoldenConfigSetting.objects.all().delete() + self.assertEqual(GoldenConfigSetting.objects.all().count(), 0) + + def test_golden_config_settings_update_good(self): + """Verify a PUT to the valid settings object, with valid but changed values.""" + response_post = self.client.post( + self.base_view, + data=self.data, + format="json", + **self.header, + ) + new_data = deepcopy(self.data) + new_data["backup_repository"] = str(GitRepository.objects.get(name="test-backup-repo-1").id) + response = self.client.put( + f"{self.base_view}{response_post.data['id']}/", + data=new_data, + format="json", + **self.header, + ) + self.assertEqual(response.status_code, status.HTTP_200_OK) + self.assertEqual( + response.data["backup_path_template"], "{{obj.location.parent.name}}/{{obj.location.name}}/{{obj.name}}.cfg" + ) + self.assertEqual( + response.data["intended_path_template"], + "{{obj.location.parent.name}}/{{obj.location.name}}/{{obj.name}}.cfg", + ) + self.assertEqual( + response.data["jinja_path_template"], "templates/{{obj.platform.name}}/{{obj.platform.name}}_main.j2" + ) + self.assertFalse(response.data["backup_test_connectivity"]) + self.assertEqual(response.data["sot_agg_query"]["id"], GraphQLQuery.objects.get(name="GC-SoTAgg-Query-1").id) + self.assertEqual( + response.data["jinja_repository"]["id"], GitRepository.objects.get(name="test-jinja-repo-1").id + ) + self.assertEqual( + response.data["backup_repository"]["id"], GitRepository.objects.get(name="test-backup-repo-1").id + ) + self.assertEqual( + response.data["intended_repository"]["id"], GitRepository.objects.get(name="test-intended-repo-1").id + ) + # Clean up + GoldenConfigSetting.objects.all().delete() + self.assertEqual(GoldenConfigSetting.objects.all().count(), 0) + + def test_settings_api_clean_up(self): + """Transactional custom model, unable to use `get_or_create`. + + Delete all objects created of GitRepository type. + """ + GitRepository.objects.all().delete() + self.assertEqual(GitRepository.objects.all().count(), 0) + + # Put back a general GoldenConfigSetting object. + global_settings = GoldenConfigSetting.objects.create(dynamic_group=self.dynamic_group) + global_settings.save() + + +# pylint: disable=too-many-ancestors + + +class GoldenConfigSerializerCSVTest(APITestCase): + """Test CSV Export returns 200/OK.""" + + url = reverse("plugins-api:nautobot_golden_config-api:goldenconfig-list") + + def setUp(self): + super().setUp() + self._add_permissions() + + def _add_permissions(self): + model = self.url.split("/")[-2] + permission_name = model.replace("-", "") + self.add_permissions(f"nautobot_golden_config.view_{permission_name}") + + def test_csv_export(self): + response = self.client.get(f"{self.url}?format=csv", **self.header) self.assertEqual(response.status_code, status.HTTP_200_OK) - self.assertEqual(response.data["count"], 0) + + +class GoldenConfigSettingSerializerCSVTest(GoldenConfigSerializerCSVTest): + """Test CSV Export returns 200/OK.""" + + url = reverse("plugins-api:nautobot_golden_config-api:goldenconfigsetting-list") + + def _add_permissions(self): + self.add_permissions("nautobot_golden_config.view_goldenconfigsetting") + + +class ComplianceFeatureSerializerCSVTest(GoldenConfigSerializerCSVTest): + """Test CSV Export returns 200/OK.""" + + url = reverse("plugins-api:nautobot_golden_config-api:compliancefeature-list") + + +class ComplianceRuleCSVTest(GoldenConfigSerializerCSVTest): + """Test CSV Export returns 200/OK.""" + + url = reverse("plugins-api:nautobot_golden_config-api:compliancerule-list") + + +class ConfigComplianceCSVTest(GoldenConfigSerializerCSVTest): + """Test CSV Export returns 200/OK.""" + + url = reverse("plugins-api:nautobot_golden_config-api:configcompliance-list") + + +class ConfigRemoveCSVTest(GoldenConfigSerializerCSVTest): + """Test CSV Export returns 200/OK.""" + + url = reverse("plugins-api:nautobot_golden_config-api:configremove-list") + + +class ConfigReplaceCSVTest(GoldenConfigSerializerCSVTest): + """Test CSV Export returns 200/OK.""" + + url = reverse("plugins-api:nautobot_golden_config-api:configreplace-list") + + +class RemediationSettingTest(APIViewTestCases.APIViewTestCase): + """Test API for Remediation Settings.""" + + model = RemediationSetting + choices_fields = ["remediation_type"] + + @classmethod + def setUpTestData(cls): + create_device_data() + platform1 = Platform.objects.get(name="Platform 1") + platform2 = Platform.objects.get(name="Platform 2") + platform3 = Platform.objects.get(name="Platform 3") + type_cli = RemediationTypeChoice.TYPE_HIERCONFIG + type_custom = RemediationTypeChoice.TYPE_CUSTOM + + # RemediationSetting type Hier with default values. + RemediationSetting.objects.create( + platform=platform1, + remediation_type=type_cli, + ) + # RemediationSetting type Hier with custom options. + RemediationSetting.objects.create( + platform=platform2, remediation_type=type_cli, remediation_options={"some_option": "some_value"} + ) + # RemediationSetting type Custom with custom options. + RemediationSetting.objects.create( + platform=platform3, + remediation_type=type_custom, + ) + + platforms = ( + Platform.objects.create(name="Platform 4", slug="platform-4"), + Platform.objects.create(name="Platform 5", slug="platform-5"), + Platform.objects.create(name="Platform 6", slug="platform-6"), + ) + + cls.create_data = [ + {"platform": platforms[0].pk, "remediation_type": type_cli}, + { + "platform": platforms[1].pk, + "remediation_type": type_cli, + "remediation_options": {"some_option": "some_value"}, + }, + {"platform": platforms[2].pk, "remediation_type": type_custom}, + ] + + cls.update_data = { + "remediation_type": type_custom, + } + + cls.bulk_update_data = { + "remediation_type": type_cli, + } + + def test_list_objects_brief(self): + """Skipping test due to brief_fields not implemented.""" + + +# pylint: disable=too-many-ancestors,too-many-locals +class ConfigPlanTest(APIViewTestCases.APIViewTestCase): + """Test API for ConfigPlan.""" + + model = ConfigPlan + brief_fields = ["device", "display", "id", "plan_type", "url"] + # The Status serializer field requires slug, but the model field returns the UUID. + validation_excluded_fields = ["status"] + + @classmethod + def setUpTestData(cls): + create_device_data() + device1 = Device.objects.get(name="Device 1") + device2 = Device.objects.get(name="Device 2") + device3 = Device.objects.get(name="Device 3") + + rule1 = create_feature_rule_json(device1, feature="Test Feature 1") + rule2 = create_feature_rule_json(device2, feature="Test Feature 2") + rule3 = create_feature_rule_json(device3, feature="Test Feature 3") + + job_result1 = create_job_result() + job_result2 = create_job_result() + job_result3 = create_job_result() + + features = [rule1.feature, rule2.feature, rule3.feature] + plan_types = ["intended", "missing", "remediation"] + job_result_ids = [job_result1.id, job_result2.id, job_result3.id] + not_approved_status = Status.objects.get(slug="not-approved") + approved_status = Status.objects.get(slug="approved") + + for cont in range(1, 4): + plan = ConfigPlan.objects.create( + device=Device.objects.get(name=f"Device {cont}"), + plan_type=plan_types[cont - 1], + config_set=f"Test Config Set {cont}", + change_control_id=f"Test Change Control ID {cont}", + change_control_url=f"https://{cont}.example.com/", + status=not_approved_status, + job_result_id=job_result_ids[cont - 1], + ) + plan.feature.add(features[cont - 1]) + plan.validated_save() + + cls.update_data = { + "change_control_id": "Test Change Control ID 4", + "change_control_url": "https://4.example.com/", + "status": approved_status.slug, + } + + cls.bulk_update_data = { + "change_control_id": "Test Change Control ID 5", + "change_control_url": "https://5.example.com/", + "status": approved_status.slug, + } + + def test_create_object(self): + """Skipping test due to POST method not allowed.""" + + def test_create_object_without_permission(self): + """Skipping test due to POST method not allowed.""" + + def test_bulk_create_objects(self): + """Skipping test due to POST method not allowed.""" diff --git a/poetry.lock b/poetry.lock index e6daf3a6..2d82efe5 100644 --- a/poetry.lock +++ b/poetry.lock @@ -1,4 +1,4 @@ -# This file is automatically @generated by Poetry 1.5.1 and should not be changed by hand. +# This file is automatically @generated by Poetry 1.6.1 and should not be changed by hand. [[package]] name = "amqp" @@ -46,6 +46,17 @@ doc = ["Sphinx (>=7)", "packaging", "sphinx-autodoc-typehints (>=1.2.0)"] test = ["anyio[trio]", "coverage[toml] (>=7)", "hypothesis (>=4.0)", "psutil (>=5.9)", "pytest (>=7.0)", "pytest-mock (>=3.6.1)", "trustme", "uvloop (>=0.17)"] trio = ["trio (>=0.22)"] +[[package]] +name = "appnope" +version = "0.1.3" +description = "Disable App Nap on macOS >= 10.9" +optional = false +python-versions = "*" +files = [ + {file = "appnope-0.1.3-py2.py3-none-any.whl", hash = "sha256:265a455292d0bd8a72453494fa24df5a11eb18373a60c7c0430889f22548605e"}, + {file = "appnope-0.1.3.tar.gz", hash = "sha256:02bd91c4de869fbb1e1c50aafc4098827a7a54ab2f39d9dcba6c9547ed920e24"}, +] + [[package]] name = "asgiref" version = "3.7.2" @@ -82,6 +93,23 @@ wrapt = [ {version = ">=1.14,<2", markers = "python_version >= \"3.11\""}, ] +[[package]] +name = "asttokens" +version = "2.4.0" +description = "Annotate AST trees with source code positions" +optional = false +python-versions = "*" +files = [ + {file = "asttokens-2.4.0-py2.py3-none-any.whl", hash = "sha256:cf8fc9e61a86461aa9fb161a14a0841a03c405fa829ac6b202670b3495d2ce69"}, + {file = "asttokens-2.4.0.tar.gz", hash = "sha256:2e0171b991b2c959acc6c49318049236844a5da1d65ba2672c4880c1c894834e"}, +] + +[package.dependencies] +six = ">=1.12.0" + +[package.extras] +test = ["astroid", "pytest"] + [[package]] name = "async-timeout" version = "4.0.3" @@ -125,6 +153,17 @@ files = [ [package.dependencies] pytz = {version = ">=2015.7", markers = "python_version < \"3.9\""} +[[package]] +name = "backcall" +version = "0.2.0" +description = "Specifications for callback functions passed in to an API" +optional = false +python-versions = "*" +files = [ + {file = "backcall-0.2.0-py2.py3-none-any.whl", hash = "sha256:fbbce6a29f263178a1f7915c1940bde0ec2b2a967566fe1c65c1dfb7422bd255"}, + {file = "backcall-0.2.0.tar.gz", hash = "sha256:5cbdbf27be5e7cfadb448baf0aa95508f91f2bbc6c6437cd9cd06e2a4c215e1e"}, +] + [[package]] name = "backports-zoneinfo" version = "0.2.1" @@ -627,6 +666,70 @@ mypy = ["contourpy[bokeh,docs]", "docutils-stubs", "mypy (==1.2.0)", "types-Pill test = ["Pillow", "contourpy[test-no-images]", "matplotlib"] test-no-images = ["pytest", "pytest-cov", "wurlitzer"] +[[package]] +name = "coverage" +version = "7.3.1" +description = "Code coverage measurement for Python" +optional = false +python-versions = ">=3.8" +files = [ + {file = "coverage-7.3.1-cp310-cp310-macosx_10_9_x86_64.whl", hash = "sha256:cd0f7429ecfd1ff597389907045ff209c8fdb5b013d38cfa7c60728cb484b6e3"}, + {file = "coverage-7.3.1-cp310-cp310-macosx_11_0_arm64.whl", hash = "sha256:966f10df9b2b2115da87f50f6a248e313c72a668248be1b9060ce935c871f276"}, + {file = "coverage-7.3.1-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:0575c37e207bb9b98b6cf72fdaaa18ac909fb3d153083400c2d48e2e6d28bd8e"}, + {file = "coverage-7.3.1-cp310-cp310-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:245c5a99254e83875c7fed8b8b2536f040997a9b76ac4c1da5bff398c06e860f"}, + {file = "coverage-7.3.1-cp310-cp310-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:4c96dd7798d83b960afc6c1feb9e5af537fc4908852ef025600374ff1a017392"}, + {file = "coverage-7.3.1-cp310-cp310-musllinux_1_1_aarch64.whl", hash = "sha256:de30c1aa80f30af0f6b2058a91505ea6e36d6535d437520067f525f7df123887"}, + {file = "coverage-7.3.1-cp310-cp310-musllinux_1_1_i686.whl", hash = "sha256:50dd1e2dd13dbbd856ffef69196781edff26c800a74f070d3b3e3389cab2600d"}, + {file = "coverage-7.3.1-cp310-cp310-musllinux_1_1_x86_64.whl", hash = "sha256:b9c0c19f70d30219113b18fe07e372b244fb2a773d4afde29d5a2f7930765136"}, + {file = "coverage-7.3.1-cp310-cp310-win32.whl", hash = "sha256:770f143980cc16eb601ccfd571846e89a5fe4c03b4193f2e485268f224ab602f"}, + {file = "coverage-7.3.1-cp310-cp310-win_amd64.whl", hash = "sha256:cdd088c00c39a27cfa5329349cc763a48761fdc785879220d54eb785c8a38520"}, + {file = "coverage-7.3.1-cp311-cp311-macosx_10_9_x86_64.whl", hash = "sha256:74bb470399dc1989b535cb41f5ca7ab2af561e40def22d7e188e0a445e7639e3"}, + {file = "coverage-7.3.1-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:025ded371f1ca280c035d91b43252adbb04d2aea4c7105252d3cbc227f03b375"}, + {file = "coverage-7.3.1-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:a6191b3a6ad3e09b6cfd75b45c6aeeffe7e3b0ad46b268345d159b8df8d835f9"}, + {file = "coverage-7.3.1-cp311-cp311-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:7eb0b188f30e41ddd659a529e385470aa6782f3b412f860ce22b2491c89b8593"}, + {file = "coverage-7.3.1-cp311-cp311-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:75c8f0df9dfd8ff745bccff75867d63ef336e57cc22b2908ee725cc552689ec8"}, + {file = "coverage-7.3.1-cp311-cp311-musllinux_1_1_aarch64.whl", hash = "sha256:7eb3cd48d54b9bd0e73026dedce44773214064be93611deab0b6a43158c3d5a0"}, + {file = "coverage-7.3.1-cp311-cp311-musllinux_1_1_i686.whl", hash = "sha256:ac3c5b7e75acac31e490b7851595212ed951889918d398b7afa12736c85e13ce"}, + {file = "coverage-7.3.1-cp311-cp311-musllinux_1_1_x86_64.whl", hash = "sha256:5b4ee7080878077af0afa7238df1b967f00dc10763f6e1b66f5cced4abebb0a3"}, + {file = "coverage-7.3.1-cp311-cp311-win32.whl", hash = "sha256:229c0dd2ccf956bf5aeede7e3131ca48b65beacde2029f0361b54bf93d36f45a"}, + {file = "coverage-7.3.1-cp311-cp311-win_amd64.whl", hash = "sha256:c6f55d38818ca9596dc9019eae19a47410d5322408140d9a0076001a3dcb938c"}, + {file = "coverage-7.3.1-cp312-cp312-macosx_10_9_x86_64.whl", hash = "sha256:5289490dd1c3bb86de4730a92261ae66ea8d44b79ed3cc26464f4c2cde581fbc"}, + {file = "coverage-7.3.1-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:ca833941ec701fda15414be400c3259479bfde7ae6d806b69e63b3dc423b1832"}, + {file = "coverage-7.3.1-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:cd694e19c031733e446c8024dedd12a00cda87e1c10bd7b8539a87963685e969"}, + {file = "coverage-7.3.1-cp312-cp312-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:aab8e9464c00da5cb9c536150b7fbcd8850d376d1151741dd0d16dfe1ba4fd26"}, + {file = "coverage-7.3.1-cp312-cp312-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:87d38444efffd5b056fcc026c1e8d862191881143c3aa80bb11fcf9dca9ae204"}, + {file = "coverage-7.3.1-cp312-cp312-musllinux_1_1_aarch64.whl", hash = "sha256:8a07b692129b8a14ad7a37941a3029c291254feb7a4237f245cfae2de78de037"}, + {file = "coverage-7.3.1-cp312-cp312-musllinux_1_1_i686.whl", hash = "sha256:2829c65c8faaf55b868ed7af3c7477b76b1c6ebeee99a28f59a2cb5907a45760"}, + {file = "coverage-7.3.1-cp312-cp312-musllinux_1_1_x86_64.whl", hash = "sha256:1f111a7d85658ea52ffad7084088277135ec5f368457275fc57f11cebb15607f"}, + {file = "coverage-7.3.1-cp312-cp312-win32.whl", hash = "sha256:c397c70cd20f6df7d2a52283857af622d5f23300c4ca8e5bd8c7a543825baa5a"}, + {file = "coverage-7.3.1-cp312-cp312-win_amd64.whl", hash = "sha256:5ae4c6da8b3d123500f9525b50bf0168023313963e0e2e814badf9000dd6ef92"}, + {file = "coverage-7.3.1-cp38-cp38-macosx_10_9_x86_64.whl", hash = "sha256:ca70466ca3a17460e8fc9cea7123c8cbef5ada4be3140a1ef8f7b63f2f37108f"}, + {file = "coverage-7.3.1-cp38-cp38-macosx_11_0_arm64.whl", hash = "sha256:f2781fd3cabc28278dc982a352f50c81c09a1a500cc2086dc4249853ea96b981"}, + {file = "coverage-7.3.1-cp38-cp38-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:6407424621f40205bbe6325686417e5e552f6b2dba3535dd1f90afc88a61d465"}, + {file = "coverage-7.3.1-cp38-cp38-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:04312b036580ec505f2b77cbbdfb15137d5efdfade09156961f5277149f5e344"}, + {file = "coverage-7.3.1-cp38-cp38-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:ac9ad38204887349853d7c313f53a7b1c210ce138c73859e925bc4e5d8fc18e7"}, + {file = "coverage-7.3.1-cp38-cp38-musllinux_1_1_aarch64.whl", hash = "sha256:53669b79f3d599da95a0afbef039ac0fadbb236532feb042c534fbb81b1a4e40"}, + {file = "coverage-7.3.1-cp38-cp38-musllinux_1_1_i686.whl", hash = "sha256:614f1f98b84eb256e4f35e726bfe5ca82349f8dfa576faabf8a49ca09e630086"}, + {file = "coverage-7.3.1-cp38-cp38-musllinux_1_1_x86_64.whl", hash = "sha256:f1a317fdf5c122ad642db8a97964733ab7c3cf6009e1a8ae8821089993f175ff"}, + {file = "coverage-7.3.1-cp38-cp38-win32.whl", hash = "sha256:defbbb51121189722420a208957e26e49809feafca6afeef325df66c39c4fdb3"}, + {file = "coverage-7.3.1-cp38-cp38-win_amd64.whl", hash = "sha256:f4f456590eefb6e1b3c9ea6328c1e9fa0f1006e7481179d749b3376fc793478e"}, + {file = "coverage-7.3.1-cp39-cp39-macosx_10_9_x86_64.whl", hash = "sha256:f12d8b11a54f32688b165fd1a788c408f927b0960984b899be7e4c190ae758f1"}, + {file = "coverage-7.3.1-cp39-cp39-macosx_11_0_arm64.whl", hash = "sha256:f09195dda68d94a53123883de75bb97b0e35f5f6f9f3aa5bf6e496da718f0cb6"}, + {file = "coverage-7.3.1-cp39-cp39-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:c6601a60318f9c3945be6ea0f2a80571f4299b6801716f8a6e4846892737ebe4"}, + {file = "coverage-7.3.1-cp39-cp39-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:07d156269718670d00a3b06db2288b48527fc5f36859425ff7cec07c6b367745"}, + {file = "coverage-7.3.1-cp39-cp39-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:636a8ac0b044cfeccae76a36f3b18264edcc810a76a49884b96dd744613ec0b7"}, + {file = "coverage-7.3.1-cp39-cp39-musllinux_1_1_aarch64.whl", hash = "sha256:5d991e13ad2ed3aced177f524e4d670f304c8233edad3210e02c465351f785a0"}, + {file = "coverage-7.3.1-cp39-cp39-musllinux_1_1_i686.whl", hash = "sha256:586649ada7cf139445da386ab6f8ef00e6172f11a939fc3b2b7e7c9082052fa0"}, + {file = "coverage-7.3.1-cp39-cp39-musllinux_1_1_x86_64.whl", hash = "sha256:4aba512a15a3e1e4fdbfed2f5392ec221434a614cc68100ca99dcad7af29f3f8"}, + {file = "coverage-7.3.1-cp39-cp39-win32.whl", hash = "sha256:6bc6f3f4692d806831c136c5acad5ccedd0262aa44c087c46b7101c77e139140"}, + {file = "coverage-7.3.1-cp39-cp39-win_amd64.whl", hash = "sha256:553d7094cb27db58ea91332e8b5681bac107e7242c23f7629ab1316ee73c4981"}, + {file = "coverage-7.3.1-pp38.pp39.pp310-none-any.whl", hash = "sha256:220eb51f5fb38dfdb7e5d54284ca4d0cd70ddac047d750111a68ab1798945194"}, + {file = "coverage-7.3.1.tar.gz", hash = "sha256:6cb7fe1581deb67b782c153136541e20901aa312ceedaf1467dcb35255787952"}, +] + +[package.extras] +toml = ["tomli"] + [[package]] name = "cron-descriptor" version = "1.4.0" @@ -707,6 +810,17 @@ files = [ {file = "cycler-0.11.0.tar.gz", hash = "sha256:9c87405839a19696e837b3b818fed3f5f69f16f1eec1a1ad77e043dcea9c772f"}, ] +[[package]] +name = "decorator" +version = "5.1.1" +description = "Decorators for Humans" +optional = false +python-versions = ">=3.5" +files = [ + {file = "decorator-5.1.1-py3-none-any.whl", hash = "sha256:b8c3f85900b9dc423225913c5aace94729fe1fa9763b38939a95226f02d37186"}, + {file = "decorator-5.1.1.tar.gz", hash = "sha256:637996211036b6385ef91435e4fae22989472f9d571faba8927ba8253acbc330"}, +] + [[package]] name = "deepdiff" version = "6.4.1" @@ -1162,6 +1276,20 @@ files = [ [package.extras] test = ["pytest (>=6)"] +[[package]] +name = "executing" +version = "1.2.0" +description = "Get the currently executing AST node of a frame, and other information" +optional = false +python-versions = "*" +files = [ + {file = "executing-1.2.0-py2.py3-none-any.whl", hash = "sha256:0314a69e37426e3608aada02473b4161d4caf5a4b244d1d0c48072b8fee7bacc"}, + {file = "executing-1.2.0.tar.gz", hash = "sha256:19da64c18d2d851112f09c287f8d3dbbdf725ab0e569077efb6cdcbd3497c107"}, +] + +[package.extras] +tests = ["asttokens", "littleutils", "pytest", "rich"] + [[package]] name = "flake8" version = "3.9.2" @@ -1535,6 +1663,45 @@ files = [ {file = "invoke-2.2.0.tar.gz", hash = "sha256:ee6cbb101af1a859c7fe84f2a264c059020b0cb7fe3535f9424300ab568f6bd5"}, ] +[[package]] +name = "ipython" +version = "8.12.2" +description = "IPython: Productive Interactive Computing" +optional = false +python-versions = ">=3.8" +files = [ + {file = "ipython-8.12.2-py3-none-any.whl", hash = "sha256:ea8801f15dfe4ffb76dea1b09b847430ffd70d827b41735c64a0638a04103bfc"}, + {file = "ipython-8.12.2.tar.gz", hash = "sha256:c7b80eb7f5a855a88efc971fda506ff7a91c280b42cdae26643e0f601ea281ea"}, +] + +[package.dependencies] +appnope = {version = "*", markers = "sys_platform == \"darwin\""} +backcall = "*" +colorama = {version = "*", markers = "sys_platform == \"win32\""} +decorator = "*" +jedi = ">=0.16" +matplotlib-inline = "*" +pexpect = {version = ">4.3", markers = "sys_platform != \"win32\""} +pickleshare = "*" +prompt-toolkit = ">=3.0.30,<3.0.37 || >3.0.37,<3.1.0" +pygments = ">=2.4.0" +stack-data = "*" +traitlets = ">=5" +typing-extensions = {version = "*", markers = "python_version < \"3.10\""} + +[package.extras] +all = ["black", "curio", "docrepr", "ipykernel", "ipyparallel", "ipywidgets", "matplotlib", "matplotlib (!=3.2.0)", "nbconvert", "nbformat", "notebook", "numpy (>=1.21)", "pandas", "pytest (<7)", "pytest (<7.1)", "pytest-asyncio", "qtconsole", "setuptools (>=18.5)", "sphinx (>=1.3)", "sphinx-rtd-theme", "stack-data", "testpath", "trio", "typing-extensions"] +black = ["black"] +doc = ["docrepr", "ipykernel", "matplotlib", "pytest (<7)", "pytest (<7.1)", "pytest-asyncio", "setuptools (>=18.5)", "sphinx (>=1.3)", "sphinx-rtd-theme", "stack-data", "testpath", "typing-extensions"] +kernel = ["ipykernel"] +nbconvert = ["nbconvert"] +nbformat = ["nbformat"] +notebook = ["ipywidgets", "notebook"] +parallel = ["ipyparallel"] +qtconsole = ["qtconsole"] +test = ["pytest (<7.1)", "pytest-asyncio", "testpath"] +test-extra = ["curio", "matplotlib (!=3.2.0)", "nbformat", "numpy (>=1.21)", "pandas", "pytest (<7.1)", "pytest-asyncio", "testpath", "trio"] + [[package]] name = "isort" version = "5.12.0" @@ -1552,6 +1719,25 @@ pipfile-deprecated-finder = ["pip-shims (>=0.5.2)", "pipreqs", "requirementslib" plugins = ["setuptools"] requirements-deprecated-finder = ["pip-api", "pipreqs"] +[[package]] +name = "jedi" +version = "0.19.0" +description = "An autocompletion tool for Python that can be used for text editors." +optional = false +python-versions = ">=3.6" +files = [ + {file = "jedi-0.19.0-py2.py3-none-any.whl", hash = "sha256:cb8ce23fbccff0025e9386b5cf85e892f94c9b822378f8da49970471335ac64e"}, + {file = "jedi-0.19.0.tar.gz", hash = "sha256:bcf9894f1753969cbac8022a8c2eaee06bfa3724e4192470aaffe7eb6272b0c4"}, +] + +[package.dependencies] +parso = ">=0.8.3,<0.9.0" + +[package.extras] +docs = ["Jinja2 (==2.11.3)", "MarkupSafe (==1.1.1)", "Pygments (==2.8.1)", "alabaster (==0.7.12)", "babel (==2.9.1)", "chardet (==4.0.0)", "commonmark (==0.8.1)", "docutils (==0.17.1)", "future (==0.18.2)", "idna (==2.10)", "imagesize (==1.2.0)", "mock (==1.0.1)", "packaging (==20.9)", "pyparsing (==2.4.7)", "pytz (==2021.1)", "readthedocs-sphinx-ext (==2.1.4)", "recommonmark (==0.5.0)", "requests (==2.25.1)", "six (==1.15.0)", "snowballstemmer (==2.1.0)", "sphinx (==1.8.5)", "sphinx-rtd-theme (==0.4.3)", "sphinxcontrib-serializinghtml (==1.1.4)", "sphinxcontrib-websupport (==1.2.4)", "urllib3 (==1.26.4)"] +qa = ["flake8 (==5.0.4)", "mypy (==0.971)", "types-setuptools (==67.2.0.1)"] +testing = ["Django (<3.1)", "attrs", "colorama", "docopt", "pytest (<7.0.0)"] + [[package]] name = "jinja2" version = "3.1.2" @@ -2015,16 +2201,6 @@ files = [ {file = "MarkupSafe-2.1.3-cp311-cp311-musllinux_1_1_x86_64.whl", hash = "sha256:5bbe06f8eeafd38e5d0a4894ffec89378b6c6a625ff57e3028921f8ff59318ac"}, {file = "MarkupSafe-2.1.3-cp311-cp311-win32.whl", hash = "sha256:dd15ff04ffd7e05ffcb7fe79f1b98041b8ea30ae9234aed2a9168b5797c3effb"}, {file = "MarkupSafe-2.1.3-cp311-cp311-win_amd64.whl", hash = "sha256:134da1eca9ec0ae528110ccc9e48041e0828d79f24121a1a146161103c76e686"}, - {file = "MarkupSafe-2.1.3-cp312-cp312-macosx_10_9_universal2.whl", hash = "sha256:f698de3fd0c4e6972b92290a45bd9b1536bffe8c6759c62471efaa8acb4c37bc"}, - {file = "MarkupSafe-2.1.3-cp312-cp312-macosx_10_9_x86_64.whl", hash = "sha256:aa57bd9cf8ae831a362185ee444e15a93ecb2e344c8e52e4d721ea3ab6ef1823"}, - {file = "MarkupSafe-2.1.3-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:ffcc3f7c66b5f5b7931a5aa68fc9cecc51e685ef90282f4a82f0f5e9b704ad11"}, - {file = "MarkupSafe-2.1.3-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:47d4f1c5f80fc62fdd7777d0d40a2e9dda0a05883ab11374334f6c4de38adffd"}, - {file = "MarkupSafe-2.1.3-cp312-cp312-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:1f67c7038d560d92149c060157d623c542173016c4babc0c1913cca0564b9939"}, - {file = "MarkupSafe-2.1.3-cp312-cp312-musllinux_1_1_aarch64.whl", hash = "sha256:9aad3c1755095ce347e26488214ef77e0485a3c34a50c5a5e2471dff60b9dd9c"}, - {file = "MarkupSafe-2.1.3-cp312-cp312-musllinux_1_1_i686.whl", hash = "sha256:14ff806850827afd6b07a5f32bd917fb7f45b046ba40c57abdb636674a8b559c"}, - {file = "MarkupSafe-2.1.3-cp312-cp312-musllinux_1_1_x86_64.whl", hash = "sha256:8f9293864fe09b8149f0cc42ce56e3f0e54de883a9de90cd427f191c346eb2e1"}, - {file = "MarkupSafe-2.1.3-cp312-cp312-win32.whl", hash = "sha256:715d3562f79d540f251b99ebd6d8baa547118974341db04f5ad06d5ea3eb8007"}, - {file = "MarkupSafe-2.1.3-cp312-cp312-win_amd64.whl", hash = "sha256:1b8dd8c3fd14349433c79fa8abeb573a55fc0fdd769133baac1f5e07abf54aeb"}, {file = "MarkupSafe-2.1.3-cp37-cp37m-macosx_10_9_x86_64.whl", hash = "sha256:8e254ae696c88d98da6555f5ace2279cf7cd5b3f52be2b5cf97feafe883b58d2"}, {file = "MarkupSafe-2.1.3-cp37-cp37m-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:cb0932dc158471523c9637e807d9bfb93e06a95cbf010f1a38b98623b929ef2b"}, {file = "MarkupSafe-2.1.3-cp37-cp37m-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:9402b03f1a1b4dc4c19845e5c749e3ab82d5078d16a2a4c2cd2df62d57bb0707"}, @@ -2119,6 +2295,20 @@ pillow = ">=6.2.0" pyparsing = ">=2.3.1,<3.1" python-dateutil = ">=2.7" +[[package]] +name = "matplotlib-inline" +version = "0.1.6" +description = "Inline Matplotlib backend for Jupyter" +optional = false +python-versions = ">=3.5" +files = [ + {file = "matplotlib-inline-0.1.6.tar.gz", hash = "sha256:f887e5f10ba98e8d2b150ddcf4702c1e5f8b3a20005eb0f74bfdbd360ee6f304"}, + {file = "matplotlib_inline-0.1.6-py3-none-any.whl", hash = "sha256:f1f41aab5328aa5aaea9b16d083b128102f8712542f819fe7e6a420ff581b311"}, +] + +[package.dependencies] +traitlets = "*" + [[package]] name = "mccabe" version = "0.6.1" @@ -2706,6 +2896,21 @@ all = ["gssapi (>=1.4.1)", "invoke (>=2.0)", "pyasn1 (>=0.1.7)", "pywin32 (>=2.1 gssapi = ["gssapi (>=1.4.1)", "pyasn1 (>=0.1.7)", "pywin32 (>=2.1.8)"] invoke = ["invoke (>=2.0)"] +[[package]] +name = "parso" +version = "0.8.3" +description = "A Python Parser" +optional = false +python-versions = ">=3.6" +files = [ + {file = "parso-0.8.3-py2.py3-none-any.whl", hash = "sha256:c001d4636cd3aecdaf33cbb40aebb59b094be2a74c556778ef5576c175e19e75"}, + {file = "parso-0.8.3.tar.gz", hash = "sha256:8c07be290bb59f03588915921e29e8a50002acaf2cdc5fa0e0114f91709fafa0"}, +] + +[package.extras] +qa = ["flake8 (==3.8.3)", "mypy (==0.782)"] +testing = ["docopt", "pytest (<6.0.0)"] + [[package]] name = "pathspec" version = "0.11.2" @@ -2728,6 +2933,31 @@ files = [ {file = "pbr-5.11.1.tar.gz", hash = "sha256:aefc51675b0b533d56bb5fd1c8c6c0522fe31896679882e1c4c63d5e4a0fccb3"}, ] +[[package]] +name = "pexpect" +version = "4.8.0" +description = "Pexpect allows easy control of interactive console applications." +optional = false +python-versions = "*" +files = [ + {file = "pexpect-4.8.0-py2.py3-none-any.whl", hash = "sha256:0b48a55dcb3c05f3329815901ea4fc1537514d6ba867a152b581d69ae3710937"}, + {file = "pexpect-4.8.0.tar.gz", hash = "sha256:fc65a43959d153d0114afe13997d439c22823a27cefceb5ff35c2178c6784c0c"}, +] + +[package.dependencies] +ptyprocess = ">=0.5" + +[[package]] +name = "pickleshare" +version = "0.7.5" +description = "Tiny 'shelve'-like database with concurrency support" +optional = false +python-versions = "*" +files = [ + {file = "pickleshare-0.7.5-py2.py3-none-any.whl", hash = "sha256:9649af414d74d4df115d5d718f82acb59c9d418196b7b4290ed47a12ce62df56"}, + {file = "pickleshare-0.7.5.tar.gz", hash = "sha256:87683d47965c1da65cdacaf31c8441d12b8044cdec9aca500cd78fc2c683afca"}, +] + [[package]] name = "pillow" version = "10.0.0" @@ -2936,6 +3166,31 @@ files = [ {file = "psycopg2_binary-2.9.7-cp39-cp39-win_amd64.whl", hash = "sha256:eb3b8d55924a6058a26db69fb1d3e7e32695ff8b491835ba9f479537e14dcf9f"}, ] +[[package]] +name = "ptyprocess" +version = "0.7.0" +description = "Run a subprocess in a pseudo terminal" +optional = false +python-versions = "*" +files = [ + {file = "ptyprocess-0.7.0-py2.py3-none-any.whl", hash = "sha256:4b41f3967fce3af57cc7e94b888626c18bf37a083e3651ca8feeb66d492fef35"}, + {file = "ptyprocess-0.7.0.tar.gz", hash = "sha256:5c5d0a3b48ceee0b48485e0c26037c0acd7d29765ca3fbb5cb3831d347423220"}, +] + +[[package]] +name = "pure-eval" +version = "0.2.2" +description = "Safely evaluate AST nodes without side effects" +optional = false +python-versions = "*" +files = [ + {file = "pure_eval-0.2.2-py3-none-any.whl", hash = "sha256:01eaab343580944bc56080ebe0a674b39ec44a945e6d09ba7db3cb8cec289350"}, + {file = "pure_eval-0.2.2.tar.gz", hash = "sha256:2b45320af6dfaa1750f543d714b6d1c520a1688dec6fd24d339063ce0aaa9ac3"}, +] + +[package.extras] +tests = ["pytest"] + [[package]] name = "pycodestyle" version = "2.7.0" @@ -3254,6 +3509,20 @@ files = [ [package.dependencies] six = ">=1.5" +[[package]] +name = "python-dotenv" +version = "1.0.0" +description = "Read key-value pairs from a .env file and set them as environment variables" +optional = false +python-versions = ">=3.8" +files = [ + {file = "python-dotenv-1.0.0.tar.gz", hash = "sha256:a8df96034aae6d2d50a4ebe8216326c61c3eb64836776504fcca410e5937a3ba"}, + {file = "python_dotenv-1.0.0-py3-none-any.whl", hash = "sha256:f5971a9226b701070a4bf2c38c89e5a3f0d64de8debda981d1db98583009122a"}, +] + +[package.extras] +cli = ["click (>=5.0)"] + [[package]] name = "python3-openid" version = "3.2.0" @@ -3347,7 +3616,6 @@ files = [ {file = "PyYAML-6.0.1-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:69b023b2b4daa7548bcfbd4aa3da05b3a74b772db9e23b982788168117739938"}, {file = "PyYAML-6.0.1-cp310-cp310-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:81e0b275a9ecc9c0c0c07b4b90ba548307583c125f54d5b6946cfee6360c733d"}, {file = "PyYAML-6.0.1-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:ba336e390cd8e4d1739f42dfe9bb83a3cc2e80f567d8805e11b46f4a943f5515"}, - {file = "PyYAML-6.0.1-cp310-cp310-musllinux_1_1_x86_64.whl", hash = "sha256:326c013efe8048858a6d312ddd31d56e468118ad4cdeda36c719bf5bb6192290"}, {file = "PyYAML-6.0.1-cp310-cp310-win32.whl", hash = "sha256:bd4af7373a854424dabd882decdc5579653d7868b8fb26dc7d0e99f823aa5924"}, {file = "PyYAML-6.0.1-cp310-cp310-win_amd64.whl", hash = "sha256:fd1592b3fdf65fff2ad0004b5e363300ef59ced41c2e6b3a99d4089fa8c5435d"}, {file = "PyYAML-6.0.1-cp311-cp311-macosx_10_9_x86_64.whl", hash = "sha256:6965a7bc3cf88e5a1c3bd2e0b5c22f8d677dc88a455344035f03399034eb3007"}, @@ -3355,15 +3623,8 @@ files = [ {file = "PyYAML-6.0.1-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:42f8152b8dbc4fe7d96729ec2b99c7097d656dc1213a3229ca5383f973a5ed6d"}, {file = "PyYAML-6.0.1-cp311-cp311-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:062582fca9fabdd2c8b54a3ef1c978d786e0f6b3a1510e0ac93ef59e0ddae2bc"}, {file = "PyYAML-6.0.1-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:d2b04aac4d386b172d5b9692e2d2da8de7bfb6c387fa4f801fbf6fb2e6ba4673"}, - {file = "PyYAML-6.0.1-cp311-cp311-musllinux_1_1_x86_64.whl", hash = "sha256:e7d73685e87afe9f3b36c799222440d6cf362062f78be1013661b00c5c6f678b"}, {file = "PyYAML-6.0.1-cp311-cp311-win32.whl", hash = "sha256:1635fd110e8d85d55237ab316b5b011de701ea0f29d07611174a1b42f1444741"}, {file = "PyYAML-6.0.1-cp311-cp311-win_amd64.whl", hash = "sha256:bf07ee2fef7014951eeb99f56f39c9bb4af143d8aa3c21b1677805985307da34"}, - {file = "PyYAML-6.0.1-cp312-cp312-macosx_10_9_x86_64.whl", hash = "sha256:855fb52b0dc35af121542a76b9a84f8d1cd886ea97c84703eaa6d88e37a2ad28"}, - {file = "PyYAML-6.0.1-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:40df9b996c2b73138957fe23a16a4f0ba614f4c0efce1e9406a184b6d07fa3a9"}, - {file = "PyYAML-6.0.1-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:6c22bec3fbe2524cde73d7ada88f6566758a8f7227bfbf93a408a9d86bcc12a0"}, - {file = "PyYAML-6.0.1-cp312-cp312-musllinux_1_1_x86_64.whl", hash = "sha256:8d4e9c88387b0f5c7d5f281e55304de64cf7f9c0021a3525bd3b1c542da3b0e4"}, - {file = "PyYAML-6.0.1-cp312-cp312-win32.whl", hash = "sha256:d483d2cdf104e7c9fa60c544d92981f12ad66a457afae824d146093b8c294c54"}, - {file = "PyYAML-6.0.1-cp312-cp312-win_amd64.whl", hash = "sha256:0d3304d8c0adc42be59c5f8a4d9e3d7379e6955ad754aa9d6ab7a398b59dd1df"}, {file = "PyYAML-6.0.1-cp36-cp36m-macosx_10_9_x86_64.whl", hash = "sha256:50550eb667afee136e9a77d6dc71ae76a44df8b3e51e41b77f6de2932bfe0f47"}, {file = "PyYAML-6.0.1-cp36-cp36m-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:1fe35611261b29bd1de0070f0b2f47cb6ff71fa6595c077e42bd0c419fa27b98"}, {file = "PyYAML-6.0.1-cp36-cp36m-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:704219a11b772aea0d8ecd7058d0082713c3562b4e271b849ad7dc4a5c90c13c"}, @@ -3380,7 +3641,6 @@ files = [ {file = "PyYAML-6.0.1-cp38-cp38-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:a0cd17c15d3bb3fa06978b4e8958dcdc6e0174ccea823003a106c7d4d7899ac5"}, {file = "PyYAML-6.0.1-cp38-cp38-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:28c119d996beec18c05208a8bd78cbe4007878c6dd15091efb73a30e90539696"}, {file = "PyYAML-6.0.1-cp38-cp38-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:7e07cbde391ba96ab58e532ff4803f79c4129397514e1413a7dc761ccd755735"}, - {file = "PyYAML-6.0.1-cp38-cp38-musllinux_1_1_x86_64.whl", hash = "sha256:49a183be227561de579b4a36efbb21b3eab9651dd81b1858589f796549873dd6"}, {file = "PyYAML-6.0.1-cp38-cp38-win32.whl", hash = "sha256:184c5108a2aca3c5b3d3bf9395d50893a7ab82a38004c8f61c258d4428e80206"}, {file = "PyYAML-6.0.1-cp38-cp38-win_amd64.whl", hash = "sha256:1e2722cc9fbb45d9b87631ac70924c11d3a401b2d7f410cc0e3bbf249f2dca62"}, {file = "PyYAML-6.0.1-cp39-cp39-macosx_10_9_x86_64.whl", hash = "sha256:9eb6caa9a297fc2c2fb8862bc5370d0303ddba53ba97e71f08023b6cd73d16a8"}, @@ -3388,7 +3648,6 @@ files = [ {file = "PyYAML-6.0.1-cp39-cp39-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:5773183b6446b2c99bb77e77595dd486303b4faab2b086e7b17bc6bef28865f6"}, {file = "PyYAML-6.0.1-cp39-cp39-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:b786eecbdf8499b9ca1d697215862083bd6d2a99965554781d0d8d1ad31e13a0"}, {file = "PyYAML-6.0.1-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:bc1bf2925a1ecd43da378f4db9e4f799775d6367bdb94671027b73b393a7c42c"}, - {file = "PyYAML-6.0.1-cp39-cp39-musllinux_1_1_x86_64.whl", hash = "sha256:04ac92ad1925b2cff1db0cfebffb6ffc43457495c9b3c39d3fcae417d7125dc5"}, {file = "PyYAML-6.0.1-cp39-cp39-win32.whl", hash = "sha256:faca3bdcf85b2fc05d06ff3fbc1f83e1391b3e724afa3feba7d13eeab355484c"}, {file = "PyYAML-6.0.1-cp39-cp39-win_amd64.whl", hash = "sha256:510c9deebc5c0225e8c96813043e62b680ba2f9c50a08d3724c7f28a747d1486"}, {file = "PyYAML-6.0.1.tar.gz", hash = "sha256:bfdf460b1736c775f2ba9f6a92bca30bc2095067b8a9d77876d1fad6cc3b4a43"}, @@ -3949,6 +4208,25 @@ dev = ["build", "flake8"] doc = ["sphinx"] test = ["pytest", "pytest-cov"] +[[package]] +name = "stack-data" +version = "0.6.2" +description = "Extract data from python stack frames and tracebacks for informative displays" +optional = false +python-versions = "*" +files = [ + {file = "stack_data-0.6.2-py3-none-any.whl", hash = "sha256:cbb2a53eb64e5785878201a97ed7c7b94883f48b87bfb0bbe8b623c74679e4a8"}, + {file = "stack_data-0.6.2.tar.gz", hash = "sha256:32d2dd0376772d01b6cb9fc996f3c8b57a357089dec328ed4b6553d037eaf815"}, +] + +[package.dependencies] +asttokens = ">=2.1.0" +executing = ">=1.2.0" +pure-eval = "*" + +[package.extras] +tests = ["cython", "littleutils", "pygments", "pytest", "typeguard"] + [[package]] name = "stevedore" version = "5.1.0" @@ -4047,6 +4325,21 @@ files = [ {file = "tomlkit-0.12.1.tar.gz", hash = "sha256:38e1ff8edb991273ec9f6181244a6a391ac30e9f5098e7535640ea6be97a7c86"}, ] +[[package]] +name = "traitlets" +version = "5.9.0" +description = "Traitlets Python configuration system" +optional = false +python-versions = ">=3.7" +files = [ + {file = "traitlets-5.9.0-py3-none-any.whl", hash = "sha256:9e6ec080259b9a5940c797d58b613b5e31441c2257b87c2e795c5228ae80d2d8"}, + {file = "traitlets-5.9.0.tar.gz", hash = "sha256:f6cde21a9c68cf756af02035f72d5a723bf607e862e7be33ece505abf4a3bad9"}, +] + +[package.extras] +docs = ["myst-parser", "pydata-sphinx-theme", "sphinx"] +test = ["argcomplete (>=2.0)", "pre-commit", "pytest", "pytest-mock"] + [[package]] name = "transitions" version = "0.9.0" @@ -4339,5 +4632,5 @@ testing = ["big-O", "jaraco.functools", "jaraco.itertools", "more-itertools", "p [metadata] lock-version = "2.0" -python-versions = "^3.8,<3.12" -content-hash = "78f0fbd14f3ec37f0d450c6506629a900ec58816ec3b219a938f54c80db1059f" +python-versions = ">=3.8,<3.12" +content-hash = "35fdae64058d358266b3189b622c5cbe281947edc72e045aee5d6c392d808997" diff --git a/pyproject.toml b/pyproject.toml index 01e84124..3ca67bd0 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,12 +1,13 @@ [tool.poetry] name = "nautobot-golden-config" -version = "1.0.0" +version = "1.5.0" description = "A plugin for configuration on nautobot" authors = ["Network to Code, LLC "] license = "Apache-2.0" readme = "README.md" -homepage = "https://github.com/nautobot/nautobot-plugin-golden-config" +homepage = "https://docs.nautobot.com/projects/golden-config/en/latest/" repository = "https://github.com/nautobot/nautobot-plugin-golden-config" +documentation = "https://docs.nautobot.com/projects/golden-config/en/latest/" keywords = ["nautobot", "nautobot-plugin"] classifiers = [ "Intended Audience :: Developers", @@ -25,10 +26,23 @@ packages = [ { include = "nautobot_golden_config" }, ] +[tool.poetry.urls] +"Changelog" = "https://docs.nautobot.com/projects/golden-config/en/latest/admin/release_notes/" +"Bug Tracker" = "https://github.com/nautobot/nautobot-plugin-golden-config/issues" + [tool.poetry.dependencies] python = ">=3.8,<3.12" -# Used for local development -nautobot = { version = "^1.4.0", optional = true } +deepdiff = ">=5.5.0,!=6.0,!=6.1,<7" +django-pivot = "^1.8.1" +matplotlib = "^3.3.2" +nautobot = ">=2.0.0-rc.2" # TODO: 2.0: Point to 2.x version +nautobot-plugin-nornir = { git = "https://github.com/nautobot/nautobot-plugin-nornir.git", branch = "next-2.0" } # TODO: 2.0: Point to 2.x version +nornir-nautobot = { git = "https://github.com/nautobot/nornir-nautobot.git", branch = "next-2.0" } # TODO: 2.0: Point to 2.x version + +toml = "^0.10.2" +netutils = "^1.5.0" +hier-config = "^2.2.2" +# nautobot-capacity-metrics = "2.0.0" TODO: 2.0: Turn on [tool.poetry.group.dev.dependencies] bandit = "*" @@ -41,8 +55,7 @@ ipython = "*" pydocstyle = "*" pylint = "*" pylint-django = "*" -pylint-nautobot = "*" -pytest = "*" +pylint-nautobot = { git = "https://github.com/nautobot/pylint-nautobot.git", branch = "develop" } # TODO: 2.0: Point to pypi python-dotenv = "^1.0.0" yamllint = "*" toml = "*" @@ -50,16 +63,13 @@ Markdown = "*" # Rendering docs to HTML mkdocs = "1.5.2" # Material for MkDocs theme -mkdocs-material = "9.1.15" +mkdocs-material = "9.2.4" # Render custom markdown for version added/changed/remove notes mkdocs-version-annotations = "1.0.0" # Automatic documentation from sources, for MkDocs mkdocstrings = "0.22.0" mkdocstrings-python = "1.5.2" -[tool.poetry.extras] -nautobot = ["nautobot"] - [tool.black] line-length = 120 target-version = ['py38', 'py39', 'py310', 'py311'] @@ -86,7 +96,10 @@ exclude = ''' [tool.pylint.master] # Include the pylint_django plugin to avoid spurious warnings about Django patterns load-plugins="pylint_django, pylint_nautobot" -ignore=".venv" +ignore = [ + "jinja_filters.py", + ".venv", +] [tool.pylint.basic] # No docstrings required for private methods (Pylint default), or for test_ functions, or for inner Meta classes. @@ -96,7 +109,9 @@ no-docstring-rgx="^(_|test_|Meta$)" # Line length is enforced by Black, so pylint doesn't need to check it. # Pylint and Black disagree about how to format multi-line arrays; Black wins. disable = """, - line-too-long + line-too-long, + too-few-public-methods, + duplicate-code, """ [tool.pylint.miscellaneous] @@ -106,11 +121,6 @@ notes = """, XXX, """ -[tool.pylint-nautobot] -supported_nautobot_versions = [ - "1.4.0" -] - [tool.pydocstyle] convention = "google" inherit = false @@ -121,7 +131,8 @@ match-dir = "(?!tests|migrations|development)[^\\.].*" # My docstring is on the line after the opening quotes instead of on the same line as them. # """ # We've discussed and concluded that we consider this to be a valid style choice. -add_ignore = "D212" +# TODO D417 is not in the template, verify this +add_ignore = "D212,D417" [build-system] requires = ["poetry_core>=1.0.0"] @@ -132,3 +143,6 @@ testpaths = [ "tests" ] addopts = "-vv --doctest-modules" + +[tool.pylint-nautobot] +supported_nautobot_versions = ["2"] diff --git a/tasks.py b/tasks.py index 99b59ba0..ce99d5a0 100644 --- a/tasks.py +++ b/tasks.py @@ -45,9 +45,9 @@ def is_truthy(arg): namespace.configure( { "nautobot_golden_config": { - "nautobot_ver": "latest", + "nautobot_ver": "2.0.0-rc.2", "project_name": "nautobot-golden-config", - "python_ver": "3.8", + "python_ver": "3.11", "local": False, "compose_dir": os.path.join(os.path.dirname(__file__), "development"), "compose_files": [ @@ -604,7 +604,7 @@ def bandit(context): @task def yamllint(context): - """Run yamllint to validate formating adheres to NTC defined YAML standards. + """Run yamllint to validate formatting adheres to NTC defined YAML standards. Args: context (obj): Used to run specific commands From c7c5ed8555448cee2f86cfda11fb04d909ceee22 Mon Sep 17 00:00:00 2001 From: Jan Snasel Date: Wed, 13 Sep 2023 11:45:15 +0000 Subject: [PATCH 3/9] fix: Syntax error --- nautobot_golden_config/jobs.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/nautobot_golden_config/jobs.py b/nautobot_golden_config/jobs.py index 09afa3c3..6b5fc8de 100644 --- a/nautobot_golden_config/jobs.py +++ b/nautobot_golden_config/jobs.py @@ -439,7 +439,7 @@ def receive_job_button(self, obj): """Run config plan deployment process.""" self.logger.debug("Starting config plan deployment job.") data = {"debug": False, "config_plan": ConfigPlan.objects.filter(id=obj.id)} - config_deployment(self, **data=True) + config_deployment(self, data, commit=True) # Conditionally allow jobs based on whether or not turned on. From 7210bd978a9b3d7dfd9e0f924d52a5c212d15884 Mon Sep 17 00:00:00 2001 From: Jan Snasel Date: Wed, 13 Sep 2023 11:47:17 +0000 Subject: [PATCH 4/9] fix: Black --- nautobot_golden_config/jobs.py | 4 +--- nautobot_golden_config/nornir_plays/config_compliance.py | 3 ++- 2 files changed, 3 insertions(+), 4 deletions(-) diff --git a/nautobot_golden_config/jobs.py b/nautobot_golden_config/jobs.py index 6b5fc8de..508b7429 100644 --- a/nautobot_golden_config/jobs.py +++ b/nautobot_golden_config/jobs.py @@ -163,9 +163,7 @@ def run(self, **data): # Instantiate a GitRepo object for each GitRepository in GoldenConfigSettings. intended_repos = get_refreshed_repos(job_obj=self, repo_type="intended_repository", data=data) - self.logger.debug( - "Building device settings mapping and running intended config nornir play." - ) + self.logger.debug("Building device settings mapping and running intended config nornir play.") config_intended(self, data) # Commit / Push each repo after job is completed. diff --git a/nautobot_golden_config/nornir_plays/config_compliance.py b/nautobot_golden_config/nornir_plays/config_compliance.py index 66fdb420..07db01a3 100644 --- a/nautobot_golden_config/nornir_plays/config_compliance.py +++ b/nautobot_golden_config/nornir_plays/config_compliance.py @@ -143,7 +143,8 @@ def run_compliance( # pylint: disable=too-many-arguments,too-many-locals platform = obj.platform.network_driver if not rules.get(platform): error_msg = ( - f"E3007: There is no defined `Configuration Rule` for platform network_driver `{platform}`, preemptively failed." + f"E3007: There is no defined `Configuration Rule` for platform network_driver `{platform}`, " + "preemptively failed." ) logger.log_error(error_msg, extra={"object": obj}) raise NornirNautobotException(error_msg) From 24dc06f9df1ffd87515f788b515dae281e5f43ed Mon Sep 17 00:00:00 2001 From: Jan Snasel Date: Wed, 13 Sep 2023 12:12:42 +0000 Subject: [PATCH 5/9] chore: Move docs changes to separate pr #584 --- .readthedocs.yaml | 4 +- docs/admin/install.md | 81 ------- docs/admin/uninstall.md | 18 -- docs/admin/upgrade.md | 10 - docs/assets/extra.css | 76 +----- docs/assets/overrides/partials/copyright.html | 2 - docs/dev/arch_decision.md | 7 - docs/dev/code_reference/api.md | 1 + docs/dev/code_reference/index.md | 3 - docs/dev/code_reference/package.md | 1 - docs/dev/contributing.md | 24 -- docs/dev/dev_environment.md | 38 +-- docs/dev/extending.md | 6 - docs/images/icon-nautobot-golden-config.png | Bin 74601 -> 0 bytes docs/requirements.txt | 4 +- docs/user/app_getting_started.md | 228 +++++++++++++++++- docs/user/app_overview.md | 38 +-- docs/user/app_use_cases.md | 207 +++++++++++++++- docs/user/external_interactions.md | 17 -- docs/user/faq.md | 1 - mkdocs.yml | 62 +++-- 21 files changed, 510 insertions(+), 318 deletions(-) delete mode 100644 docs/admin/install.md delete mode 100644 docs/admin/uninstall.md delete mode 100644 docs/admin/upgrade.md delete mode 100644 docs/dev/arch_decision.md delete mode 100644 docs/dev/code_reference/package.md delete mode 100644 docs/dev/contributing.md delete mode 100644 docs/dev/extending.md delete mode 100644 docs/images/icon-nautobot-golden-config.png delete mode 100644 docs/user/external_interactions.md delete mode 100644 docs/user/faq.md diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 9a0a64c7..a6334706 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -10,11 +10,11 @@ version: 2 build: os: "ubuntu-22.04" tools: - python: "3.10" + python: "3.11" mkdocs: configuration: "mkdocs.yml" - fail_on_warning: true + # fail_on_warning: true # Use our docs/requirements.txt during installation. python: diff --git a/docs/admin/install.md b/docs/admin/install.md deleted file mode 100644 index 2e06f44f..00000000 --- a/docs/admin/install.md +++ /dev/null @@ -1,81 +0,0 @@ -# Installing the App in Nautobot - -Here you will find detailed instructions on how to **install** and **configure** the App within your Nautobot environment. - -!!! warning "Developer Note - Remove Me!" - Detailed instructions on installing the App. You will need to update this section based on any additional dependencies or prerequisites. - -## Prerequisites - -- The plugin is compatible with Nautobot 1.4.0 and higher. -- Databases supported: PostgreSQL, MySQL - -!!! note - Please check the [dedicated page](compatibility_matrix.md) for a full compatibility matrix and the deprecation policy. - -### Access Requirements - -!!! warning "Developer Note - Remove Me!" - What external systems (if any) it needs access to in order to work. - -## Install Guide - -!!! note - Plugins can be installed manually or using Python's `pip`. See the [nautobot documentation](https://nautobot.readthedocs.io/en/latest/plugins/#install-the-package) for more details. The pip package name for this plugin is [`nautobot-golden-config`](https://pypi.org/project/nautobot-golden-config/). - -The plugin is available as a Python package via PyPI and can be installed with `pip`: - -```shell -pip install nautobot-golden-config -``` - -To ensure Golden Config is automatically re-installed during future upgrades, create a file named `local_requirements.txt` (if not already existing) in the Nautobot root directory (alongside `requirements.txt`) and list the `nautobot-golden-config` package: - -```shell -echo nautobot-golden-config >> local_requirements.txt -``` - -Once installed, the plugin needs to be enabled in your Nautobot configuration. The following block of code below shows the additional configuration required to be added to your `nautobot_config.py` file: - -- Append `"nautobot_golden_config"` to the `PLUGINS` list. -- Append the `"nautobot_golden_config"` dictionary to the `PLUGINS_CONFIG` dictionary and override any defaults. - -```python -# In your nautobot_config.py -PLUGINS = ["nautobot_golden_config"] - -# PLUGINS_CONFIG = { -# "nautobot_golden_config": { -# ADD YOUR SETTINGS HERE -# } -# } -``` - -Once the Nautobot configuration is updated, run the Post Upgrade command (`nautobot-server post_upgrade`) to run migrations and clear any cache: - -```shell -nautobot-server post_upgrade -``` - -Then restart (if necessary) the Nautobot services which may include: - -- Nautobot -- Nautobot Workers -- Nautobot Scheduler - -```shell -sudo systemctl restart nautobot nautobot-worker nautobot-scheduler -``` - -## App Configuration - -!!! warning "Developer Note - Remove Me!" - Any configuration required to get the App set up. Edit the table below as per the examples provided. - -The plugin behavior can be controlled with the following list of settings: - -| Key | Example | Default | Description | -| ------- | ------ | -------- | ------------------------------------- | -| `enable_backup` | `True` | `True` | A boolean to represent whether or not to run backup configurations within the plugin. | -| `platform_slug_map` | `{"cisco_wlc": "cisco_aireos"}` | `None` | A dictionary in which the key is the platform slug and the value is what netutils uses in any "network_os" parameter. | -| `per_feature_bar_width` | `0.15` | `0.15` | The width of the table bar within the overview report | diff --git a/docs/admin/uninstall.md b/docs/admin/uninstall.md deleted file mode 100644 index a30679d5..00000000 --- a/docs/admin/uninstall.md +++ /dev/null @@ -1,18 +0,0 @@ -# Uninstall the App from Nautobot - -Here you will find any steps necessary to cleanly remove the App from your Nautobot environment. - -## Database Cleanup - -Prior to removing the plugin from the `nautobot_config.py`, run the following command to roll back any migration specific to this plugin. - -```shell -nautobot-server migrate nautobot_plugin_golden_config zero -``` - -!!! warning "Developer Note - Remove Me!" - Any other cleanup operations to ensure the database is clean after the app is removed. Is there anything else that needs cleaning up, such as CFs, relationships, etc. if they're no longer desired? - -## Remove App configuration - -Remove the configuration you added in `nautobot_config.py` from `PLUGINS` & `PLUGINS_CONFIG`. diff --git a/docs/admin/upgrade.md b/docs/admin/upgrade.md deleted file mode 100644 index 3b87d56f..00000000 --- a/docs/admin/upgrade.md +++ /dev/null @@ -1,10 +0,0 @@ -# Upgrading the App - -Here you will find any steps necessary to upgrade the App in your Nautobot environment. - -## Upgrade Guide - -!!! warning "Developer Note - Remove Me!" - Add more detailed steps on how the app is upgraded in an existing Nautobot setup and any version specifics (such as upgrading between major versions with breaking changes). - -When a new release comes out it may be necessary to run a migration of the database to account for any changes in the data models used by this plugin. Execute the command `nautobot-server post-upgrade` within the runtime environment of your Nautobot installation after updating the `nautobot-golden-config` package via `pip`. diff --git a/docs/assets/extra.css b/docs/assets/extra.css index dfe2e4b1..131cef77 100644 --- a/docs/assets/extra.css +++ b/docs/assets/extra.css @@ -18,15 +18,6 @@ font-size: 0.7rem; } -/* -* The default max-width is 61rem which does not provide nearly enough space to present code examples or larger tables -*/ -.md-grid { - margin-left: auto; - margin-right: auto; - max-width: 95%; -} - .md-tabs__link { font-size: 0.8rem; } @@ -48,7 +39,7 @@ } img.logo { - height: 200px; + height: 100px; } img.copyright-logo { @@ -94,68 +85,3 @@ a.autorefs-external::after { a.autorefs-external:hover::after { background-color: var(--md-accent-fg-color); } - - -/* Customization for mkdocs-version-annotations */ -:root { - /* Icon for "version-added" admonition: Material Design Icons "plus-box-outline" */ - --md-admonition-icon--version-added: url('data:image/svg+xml;charset=utf-8,'); - /* Icon for "version-changed" admonition: Material Design Icons "delta" */ - --md-admonition-icon--version-changed: url('data:image/svg+xml;charset=utf-8,'); - /* Icon for "version-removed" admonition: Material Design Icons "minus-circle-outline" */ - --md-admonition-icon--version-removed: url('data:image/svg+xml;charset=utf-8,'); -} - -/* "version-added" admonition in green */ -.md-typeset .admonition.version-added, -.md-typeset details.version-added { - border-color: rgb(0, 200, 83); -} - -.md-typeset .version-added>.admonition-title, -.md-typeset .version-added>summary { - background-color: rgba(0, 200, 83, .1); -} - -.md-typeset .version-added>.admonition-title::before, -.md-typeset .version-added>summary::before { - background-color: rgb(0, 200, 83); - -webkit-mask-image: var(--md-admonition-icon--version-added); - mask-image: var(--md-admonition-icon--version-added); -} - -/* "version-changed" admonition in orange */ -.md-typeset .admonition.version-changed, -.md-typeset details.version-changed { - border-color: rgb(255, 145, 0); -} - -.md-typeset .version-changed>.admonition-title, -.md-typeset .version-changed>summary { - background-color: rgba(255, 145, 0, .1); -} - -.md-typeset .version-changed>.admonition-title::before, -.md-typeset .version-changed>summary::before { - background-color: rgb(255, 145, 0); - -webkit-mask-image: var(--md-admonition-icon--version-changed); - mask-image: var(--md-admonition-icon--version-changed); -} - -/* "version-removed" admonition in red */ -.md-typeset .admonition.version-removed, -.md-typeset details.version-removed { - border-color: rgb(255, 82, 82); -} - -.md-typeset .version-removed>.admonition-title, -.md-typeset .version-removed>summary { - background-color: rgba(255, 82, 82, .1); -} - -.md-typeset .version-removed>.admonition-title::before, -.md-typeset .version-removed>summary::before { - background-color: rgb(255, 82, 82); - -webkit-mask-image: var(--md-admonition-icon--version-removed); - mask-image: var(--md-admonition-icon--version-removed); -} diff --git a/docs/assets/overrides/partials/copyright.html b/docs/assets/overrides/partials/copyright.html index b92cf5e3..e0b77e5f 100644 --- a/docs/assets/overrides/partials/copyright.html +++ b/docs/assets/overrides/partials/copyright.html @@ -1,4 +1,3 @@ -
{% if config.copyright %}
@@ -19,4 +18,3 @@
- diff --git a/docs/dev/arch_decision.md b/docs/dev/arch_decision.md deleted file mode 100644 index e7bcbbe4..00000000 --- a/docs/dev/arch_decision.md +++ /dev/null @@ -1,7 +0,0 @@ -# Architecture Decision Records - -The intention is to document deviations from a standard Model View Controller (MVC) design. - -!!! warning "Developer Note - Remove Me!" - Optional page, remove if not applicable. - For examples see [Golden Config](https://github.com/nautobot/nautobot-plugin-golden-config/tree/develop/docs/dev/dev_adr.md) and [nautobot-plugin-reservation](https://github.com/networktocode/nautobot-plugin-reservation/blob/develop/docs/dev/dev_adr.md). diff --git a/docs/dev/code_reference/api.md b/docs/dev/code_reference/api.md index 2ce5c164..ae2a8545 100644 --- a/docs/dev/code_reference/api.md +++ b/docs/dev/code_reference/api.md @@ -3,3 +3,4 @@ ::: nautobot_golden_config.api options: show_submodules: True + #docstring_section_style: spacy diff --git a/docs/dev/code_reference/index.md b/docs/dev/code_reference/index.md index ebe9ff7d..473f2c40 100644 --- a/docs/dev/code_reference/index.md +++ b/docs/dev/code_reference/index.md @@ -1,6 +1,3 @@ # Code Reference Auto-generated code reference documentation from docstrings. - -!!! warning "Developer Note - Remove Me!" - Uses [mkdocstrings](https://mkdocstrings.github.io/) syntax to auto-generate code documentation from docstrings. Two example pages are provided ([api](api.md) and [package](package.md)), add new stubs for each module or package that you think has relevant documentation. diff --git a/docs/dev/code_reference/package.md b/docs/dev/code_reference/package.md deleted file mode 100644 index 8a3cfda5..00000000 --- a/docs/dev/code_reference/package.md +++ /dev/null @@ -1 +0,0 @@ -::: nautobot_golden_config diff --git a/docs/dev/contributing.md b/docs/dev/contributing.md deleted file mode 100644 index 2337f740..00000000 --- a/docs/dev/contributing.md +++ /dev/null @@ -1,24 +0,0 @@ -# Contributing to the App - -!!! warning "Developer Note - Remove Me!" - Information on how to contribute fixes, functionality, or documentation changes back to the project. - -The project is packaged with a light [development environment](dev_environment.md) based on `docker-compose` to help with the local development of the project and to run tests. - -The project is following Network to Code software development guidelines and is leveraging the following: - -- Python linting and formatting: `black`, `pylint`, `bandit`, `flake8`, and `pydocstyle`. -- YAML linting is done with `yamllint`. -- Django unit test to ensure the plugin is working properly. - -Documentation is built using [mkdocs](https://www.mkdocs.org/). The [Docker based development environment](dev_environment.md#docker-development-environment) automatically starts a container hosting a live version of the documentation website on [http://localhost:8001](http://localhost:8001) that auto-refreshes when you make any changes to your local files. - -## Branching Policy - -!!! warning "Developer Note - Remove Me!" - What branching policy is used for this project and where contributions should be made. - -## Release Policy - -!!! warning "Developer Note - Remove Me!" - How new versions are released. diff --git a/docs/dev/dev_environment.md b/docs/dev/dev_environment.md index a81a5c3c..1d55d564 100644 --- a/docs/dev/dev_environment.md +++ b/docs/dev/dev_environment.md @@ -1,11 +1,11 @@ # Building Your Development Environment -## Quickstart Guide +## Quickstart The development environment can be used in two ways: -1. **(Recommended)** All services, including Nautobot, are spun up using Docker containers and a volume mount so you can develop locally. -2. With a local Poetry environment if you wish to develop outside of Docker, with the caveat of using external services provided by Docker for the database (PostgreSQL by default, MySQL optionally) and Redis services. +1. `Recommended` All services are spun up using Docker and a local volume mount attached so you can develop locally, but Nautobot is spun up within the Docker container. +2. With a local poetry environment if you wish to develop outside of Docker with the caveat of using external services provided by Docker for PostgresQL and Redis. This is a quick reference guide if you're already familiar with the development environment provided, which you can read more about later in this document. @@ -14,8 +14,8 @@ This is a quick reference guide if you're already familiar with the development The [Invoke](http://www.pyinvoke.org/) library is used to provide some helper commands based on the environment. There are a few configuration parameters which can be passed to Invoke to override the default configuration: - `nautobot_ver`: the version of Nautobot to use as a base for any built docker containers (default: latest) -- `project_name`: the default docker compose project name (default: `nautobot-golden-config`) -- `python_ver`: the version of Python to use as a base for any built docker containers (default: 3.8) +- `project_name`: the default docker compose project name (default: `nautobot_golden_config`) +- `python_ver`: the version of Python to use as a base for any built docker containers (default: 3.11) - `local`: a boolean flag indicating if invoke tasks should be run on the host or inside the docker containers (default: False, commands will be run in docker containers) - `compose_dir`: the full path to a directory containing the project compose files - `compose_files`: a list of compose files applied in order (see [Multiple Compose files](https://docs.docker.com/compose/extends/#multiple-compose-files) for more information) @@ -66,7 +66,7 @@ Run the following commands: ```shell poetry shell poetry install --extras nautobot -export $(cat development/dev.env | xargs) +export $(cat development/development.env | xargs) export $(cat development/creds.env | xargs) invoke start && sleep 5 nautobot-server migrate @@ -101,9 +101,12 @@ The project features a CLI helper based on [Invoke](https://www.pyinvoke.org/) t Each command can be executed with `invoke `. All commands support the arguments `--nautobot-ver` and `--python-ver` if you want to manually define the version of Python and Nautobot to use. Each command also has its own help `invoke --help` +!!! note + To run the mysql (mariadb) development environment, set the environment variable as such `export NAUTOBOT_USE_MYSQL=1`. + #### Local Development Environment -``` +```shell build Build all docker images. debug Start Nautobot and its dependencies in debug mode. destroy Destroy all containers and volumes. @@ -114,7 +117,7 @@ Each command can be executed with `invoke `. All commands support the a #### Utility -``` +```shell cli Launch a bash shell inside the running Nautobot container. create-user Create a new user in django (default: admin), will prompt for password. makemigrations Run Make Migration in Django. @@ -123,7 +126,7 @@ Each command can be executed with `invoke `. All commands support the a #### Testing -``` +```shell bandit Run bandit to validate basic static code security analysis. black Run black to check that Python files adhere to its style standards. flake8 Run flake8 to check that Python files adhere to its style standards. @@ -158,6 +161,8 @@ The `poetry shell` command is used to create and enable a virtual environment ma For more details about Poetry and its commands please check out its [online documentation](https://python-poetry.org/docs/). + + ## Full Docker Development Environment This project is set up with a number of **Invoke** tasks consumed as simple CLI commands to get developing fast. You'll use a few `invoke` commands to get your environment up and running. @@ -182,7 +187,7 @@ The first thing you need to do is build the necessary Docker image for Nautobot #14 exporting layers #14 exporting layers 1.2s done #14 writing image sha256:2d524bc1665327faa0d34001b0a9d2ccf450612bf8feeb969312e96a2d3e3503 done -#14 naming to docker.io/nautobot-golden-config/nautobot:latest-py3.7 done +#14 naming to docker.io/nautobot-golden-config/nautobot:latest-py3.11 done ``` ### Invoke - Starting the Development Environment @@ -213,9 +218,9 @@ This will start all of the Docker containers used for hosting Nautobot. You shou ```bash ➜ docker ps ****CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES -ee90fbfabd77 nautobot-golden-config/nautobot:latest-py3.7 "nautobot-server rqw…" 16 seconds ago Up 13 seconds nautobot_golden_config_worker_1 -b8adb781d013 nautobot-golden-config/nautobot:latest-py3.7 "/docker-entrypoint.…" 20 seconds ago Up 15 seconds 0.0.0.0:8080->8080/tcp, :::8080->8080/tcp nautobot_golden_config_nautobot_1 -d64ebd60675d nautobot-golden-config/nautobot:latest-py3.7 "mkdocs serve -v -a …" 25 seconds ago Up 18 seconds 0.0.0.0:8001->8080/tcp, :::8001->8080/tcp nautobot_golden_config_docs_1 +ee90fbfabd77 nautobot-golden-config/nautobot:latest-py3.11 "nautobot-server rqw…" 16 seconds ago Up 13 seconds nautobot_golden_config_worker_1 +b8adb781d013 nautobot-golden-config/nautobot:latest-py3.11 "/docker-entrypoint.…" 20 seconds ago Up 15 seconds 0.0.0.0:8080->8080/tcp, :::8080->8080/tcp nautobot_golden_config_nautobot_1 +d64ebd60675d nautobot-golden-config/nautobot:latest-py3.11 "mkdocs serve -v -a …" 25 seconds ago Up 18 seconds 0.0.0.0:8001->8080/tcp, :::8001->8080/tcp nautobot_golden_config_docs_1 e72d63129b36 postgres:13-alpine "docker-entrypoint.s…" 25 seconds ago Up 19 seconds 0.0.0.0:5432->5432/tcp, :::5432->5432/tcp nautobot_golden_config_postgres_1 96c6ff66997c redis:6-alpine "docker-entrypoint.s…" 25 seconds ago Up 21 seconds 0.0.0.0:6379->6379/tcp, :::6379->6379/tcp nautobot_golden_config_redis_1 ``` @@ -316,6 +321,9 @@ When trying to debug an issue, one helpful thing you can look at are the logs wi !!! note The `-f` tag will keep the logs open, and output them in realtime as they are generated. +!!! info + Want to limit the log output even further? Use the `--tail <#>` command line argument in conjunction with `-f`. + So for example, our plugin is named `nautobot-golden-config`, the command would most likely be `docker logs nautobot_golden_config_nautobot_1 -f`. You can find the name of all running containers via `docker ps`. If you want to view the logs specific to the worker container, simply use the name of that container instead. @@ -391,7 +399,7 @@ namespace.configure( { "nautobot_golden_config": { ... - "python_ver": "3.7", + "python_ver": "3.11", ... } } @@ -410,7 +418,7 @@ namespace.configure( { "nautobot_golden_config": { ... - "nautobot_ver": "1.4.0", + "nautobot_ver": "1.0.2", ... } } diff --git a/docs/dev/extending.md b/docs/dev/extending.md deleted file mode 100644 index 49b89f46..00000000 --- a/docs/dev/extending.md +++ /dev/null @@ -1,6 +0,0 @@ -# Extending the App - -!!! warning "Developer Note - Remove Me!" - Information on how to extend the App functionality. - -Extending the application is welcome, however it is best to open an issue first, to ensure that a PR would be accepted and makes sense in terms of features and design. diff --git a/docs/images/icon-nautobot-golden-config.png b/docs/images/icon-nautobot-golden-config.png deleted file mode 100644 index 7e00cf6ae0ee76324adab30d68d64206678a85e1..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 74601 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
@5hb{hC=~cCz;d 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 diff --git a/docs/requirements.txt b/docs/requirements.txt index 8f550c99..e8e7f513 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,5 +1,5 @@ mkdocs==1.5.2 mkdocs-material==9.2.4 -mkdocstrings==0.22.0 -mkdocstrings-python==1.5.2 mkdocs-version-annotations==1.0.0 +mkdocstrings==0.22.0 +mkdocstrings-python==1.5.2 \ No newline at end of file diff --git a/docs/user/app_getting_started.md b/docs/user/app_getting_started.md index 24ea0099..c3d7ee19 100644 --- a/docs/user/app_getting_started.md +++ b/docs/user/app_getting_started.md @@ -1,19 +1,225 @@ -# Getting Started with the App +# Quick Start Guides -This document provides a step-by-step tutorial on how to get the App going and how to use it. +- [Quick Start Guides](#quick-start-guides) +- [Backup Configuration](#backup-configuration) +- [Intended Configuration](#intended-configuration) +- [Compliance](#compliance) +- [Load Properties from Git](#load-properties-from-git) -## Install the App +# Backup Configuration -To install the App, please follow the instructions detailed in the [Installation Guide](../admin/install.md). +Follow the steps below to get up and running for the configuration backup element of the plugin. -## First steps with the App +1. Enable the feature in the `PLUGIN_SETTINGS`. The configuration should have `"enable_backup": True` set in the `PLUGINS_CONFIG` dictionary for `nautobot_golden_config`. -!!! warning "Developer Note - Remove Me!" - What (with screenshots preferably) does it look like to perform the simplest workflow within the App once installed? +2. Add any git repositories that will be used to house the backup configurations. -## What are the next steps? + 1. In the UI `Extensibility -> Git Repositories`. Click Add. + 2. Populate the Git Repository data for the backup. [Git Settings](./app_use_cases.md#git-settings) + 3. Make sure to select the **Provides** called `backup configs`. + 4. Click Create. -!!! warning "Developer Note - Remove Me!" - After taking the first steps, what else could the users look at doing. +3. Next, make sure to create new or update existing Plugins **Settings** with the backup details. + 1. Navigate to `Golden Config -> Settings` under the Golden Configuration Section. + 2. Create new or select one of the existing `Settings` objects + 3. Fill out the Backup Repository. (The dropdown will show the repository that was just created.) + 4. Fill out Backup Path Template. Typically `{{obj.location.name}}/{{obj.name}}.cfg`, see [Setting Details](./app_use_cases.md#application-settings) + 5. Select whether or not to do a connectivity check per device. + 6. Click Save. -You can check out the [Use Cases](app_use_cases.md) section for more examples. +4. Create Configuration Removals and Replacements. + + 1. [Config Removals](./app_feature_backup.md#config-removals) + 2. [Config Replacements](./app_feature_backup.md#config-replacements) + +5. Execute the Backup. + + 1. Navigate to `Golden Config -> Home` under the Golden Configuration Section. + 2. Click on the `Execute` button and select `Backup`. + 3. Select what to run the backup on. + 4. Run the Job by clicking "Run Job" button. + +> For in-depth details see [Navigating Backup](./app_feature_backup.md) + +# Intended Configuration + +Follow the steps below to get up and running for the intended configuration element of the plugin. + +!!! note + Intended Configuration requires the `enable_intended` and `enabled_sotAgg` plugin features to be used. + +!!! note + If Secret Group is used for the Repositories the secrets type HTTP(S) is required for this plugin. + +1. Enable the feature in the `PLUGIN_SETTINGS`. The configuration should have `"enable_intended": True` set in the `PLUGINS_CONFIG` dictionary for `nautobot_golden_config`. + + +2. Add any git repositories that will be used to house the intended configurations. + + 1. In the UI `Extensibility -> Git Repositories`. Click Add. + 2. Populate the Git Repository data for the intended. [Git Settings](./app_feature_backup.md#git-settings) + 3. Make sure to select the **Provides** called `intended configs`. + 4. Click Create. + +3. Add the git repository that will be used to house the Jinja2 templates. + + 1. In the UI `Extensibility -> Git Repositories`. Click Add. + 2. Populate the Git Repository data for the jinja2 templates. [Git Settings](./app_feature_backup.md#git-settings) + 3. Make sure to select the **Provides** called `jinja templates`. + 4. Click Create. + +4. Next, make sure to create new or update existing Plugins **Settings** with the intended and jinja2 template details. + + 1. Navigate to `Golden Config -> Settings` under the Golden Configuration Section. + 2. Create new or select one of the existing `Settings` objects + 3. Fill out the Intended Repository. (The dropdown will show the repository that was just created.) + 4. Fill out Intended Path Template. Typically `{{obj.location.name}}/{{obj.name}}.cfg`, see [Setting Details](./app_feature_backup.md#application-settings) + 5. Fill out Jinja Repository. (The dropdown will show the repository that was just created.) + 6. Fill out Jinja Path Template. Typically `{{obj.platform.network_driver}}.j2`. + +5. Determine what data(variables) the Jinja2 templates need from Nautobot. + + 1. See [Source of Truth Agg Details](./app_feature_sotagg.md) + 2. In the UI `Extensibility -> GraphQL Queries`. Click Add. + 3. Populate the GraphQL data. + 4. Make sure to follow the format specified in the **GraphQL** section in [Source of Truth Agg Details](./app_feature_sotagg.md) + 5. Click Create. + 6. Navigate to `Golden Config -> Settings` under the Golden Configuration Section. + 7. Select a SoTAgg Saved Query. (The dropdown will show the GraphQL query that was just created.) + +6. Execute the Intended. + + 1. Navigate to `Golden Config -> Home`. + 2. Click on the `Execute` button and select `Intended`. + 3. Select what to run the intended generation on. + 4. Run the Job. + +> For in-depth details see [Navigating Intended](./app_feature_intended.md) + +# Compliance + +Compliance requires Backups and Intended Configurations in order to be executed. + +1. Enable the feature in the `PLUGIN_SETTINGS`. The configuration should have `"enable_compliance": True` set in the `PLUGINS_CONFIG` dictionary for `nautobot_golden_config`. +2. Follow the steps in [Backup Configuration](#backup-configuration). +3. Follow the steps in [Intended Configuration](#intended-configuration). +4. Create a Compliance Feature. + + 1. Navigate to `Golden Config -> Compliance Feature`. + 2. Click Add and give the feature a name. Typically this is based on the configuration snippet or section. E.g. "aaa". + +5. Create a Compliance Rule. + + 1. Navigate to `Golden Config -> Compliance Rules`. + 2. Click Add and populate the fields, make sure the rule is linked to the feature created previously. See [Configuration Compliance Settings](./app_feature_compliance.md#configuration-compliance-settings) for details. + +6. Execute Compliance Check. + + 1. Navigate to `Golden Config -> Configuration Compliance`. + 2. Click on the `Execute` button and select `Compliance`. + 3. Select what to run the compliance on. + 4. Run the Job. + +> For in-depth details see [Navigating Compliance](./app_feature_compliance.md) + +# Load Properties from Git + +Golden Config properties include: Compliance Features, Compliance Rules, Config Removals, and Config Replacements. They can be created via the UI, API, or alternatively you can load these properties from a Git repository, defined in YAML files following the this directory structure (you can skip any of them if not apply): + +```shell +├── golden_config +│ ├── compliance_features +│ ├── compliance_rules +│ ├── config_removes +│ ├── config_replaces +``` + +The files within these folders can follow any naming pattern or nested folder structure, all of them will be recursively taken into account. So it's up to you to decide how to you prefer to organize these files (within the previously stated directory structure): + +```shell +├── golden_config +│ ├── compliance_features +│ │ └── all.yml +│ ├── compliance_rules +│ │ ├── my_rule_for_cisco_ios +│ │ │ ├── some_rules.yml +│ │ │ └── some_other_rules.yml +│ │ └── juniper_junos.yml +│ ├── config_removes +│ │ ├── cisco_ios.yml +│ │ └── juniper_junos.yml +│ ├── config_replaces +│ │ ├── cisco_ios.yml +│ │ └── juniper_junos.yml +``` + +The `YAML` files will contain all the attributes necessary to identify an object (for instance, a `ComplianceRule` is identified by the `feature_slug` and the `platform_name` together) and the other attributes (the ones that are not used to identify the object). For example: + +`compliance_features` example: + +```yaml +--- +- name: "aaa" + slug: "aaa" + description: "aaa feature" +``` + +`compliance_rules` example: + +```yaml +--- +- feature_slug: "aaa" + platform_name: "Cisco IOS" + config_ordered: true + match_config: | + aaa + line + username + role + tacacs + config_type: "cli" +``` + +`config_removes` example: + +```yaml +--- +- platform_name: "Cisco IOS" + name: "Build config" + regex: '^Building\s+configuration.*\n' +``` + +`config_replaces` example: + +```yaml +--- +- name: "username" + platform_name: "Cisco IOS" + description: "username" + regex: '(username\s+\S+\spassword\s+5\s+)\S+(\s+role\s+\S+)' + replace: '\1\2' +``` + +CustomField data can be added using the `_custom_field_data` attribute, that takes a dictionary mapping custom_field names to their values: + +```yaml +--- +- name: "aaa" + slug: "aaa" + description: "aaa feature" + _custom_field_data: + custom_field_a: "abc" + custom_field_b: 123 +``` + +!!! note + For Foreign Key references to `ComplianceFeature` and `Platform` we use the keywords `feature_slug` and `platform_name` respectively. + +1. Add the Git repository that will be used to sync Git properties. + + 1. In the UI `Extensibility -> Git Repositories`. Click Add. + 2. Populate the Git Repository data for the GC properties. [Git Settings](./app_use_cases.md#git-settings) + 3. Make sure to select the **Provides** called `Golden Config properties`. + 4. Click Create (This step runs an automatic sync). + +2. Run `sync` and all the properties will be created/updated in a declarative way and following the right order to respect the dependencies between objects. The import task will raise a `warning` if the dependencies are not available yet (for instance, a referenced `Platform` is not created), so the `sync` process will continue, and you could then fix these warnings by reviewing the mismatch (maybe creating the required object) and run the `sync` process again. diff --git a/docs/user/app_overview.md b/docs/user/app_overview.md index 06ff5d32..74f02514 100644 --- a/docs/user/app_overview.md +++ b/docs/user/app_overview.md @@ -1,30 +1,38 @@ # App Overview -This document provides an overview of the App including critical information and import considerations when applying it to your Nautobot environment. +The golden configuration plugin is a Nautobot plugin that aims to solve common configuration management challenges. !!! note Throughout this documentation, the terms "app" and "plugin" will be used interchangeably. -## Description +## Description/Overview +When engineers are starting their network automation journey, everybody asks where and how they should start. Their immediate thought is coming up with methods of automating changes within their environments. However, doing so can be scary for those who are risk averse about automation making changes. The question then comes about how automation can be used to help solve some of the big problems facing network teams today. One of those problems that we’ve repeatedly heard from our customers and fellow network engineers is around configuration drift. This issue typically occurs for multiple reasons: -## Audience (User Personas) - Who should use this App? +- Lack of standardization for device configurations +- Multiple individuals independently making changes +- Mergers and acquisitions -!!! warning "Developer Note - Remove Me!" - Who is this meant for/ who is the common user of this app? +Thankfully, this issue can be addressed without making any changes on your devices. You might ask, “How do I do that?” That is where the Golden Configuration plugin for Nautobot comes in. The Golden Configuration plugin is comprised of four components: -## Authors and Maintainers +- Configuration Backup +- Source of Truth Aggregation +- Configuration Intended +- Configuration Compliance -!!! warning "Developer Note - Remove Me!" - Add the team and/or the main individuals maintaining this project. Include historical maintainers as well. +!!! info + The four components are not hard requirements, the application is flexible and can be updated to leverage any of these components if they already exist in another system or automated process. -## Nautobot Features Used +Utilizing these components, you can define the Golden Configuration standard for each of your devices and compare their adherence to that standard, otherwise known as their configuration compliance. -!!! warning "Developer Note - Remove Me!" - What is shown today in the Installed Plugins page in Nautobot. What parts of Nautobot does it interact with, what does it add etc. ? +## Audience (User Personas) - Who should use this App? -### Extras +- Network Engineers interested in Network Automation, Infrastructure as Code, etc. +- Network shops that have difficult time ensuring their configurations are to standard +- Network shops looking for a backup configuration solution +- Network shops looking for generating configurations + +## Authors and Maintainers -!!! warning "Developer Note - Remove Me!" - Custom Fields - things like which CFs are created by this app? - Jobs - are jobs, if so, which ones, installed by this app? +- Ken Celenza (@itdependsnetworks) +- Jeff Kala (@jeffkala) diff --git a/docs/user/app_use_cases.md b/docs/user/app_use_cases.md index dc06944f..ca9789f3 100644 --- a/docs/user/app_use_cases.md +++ b/docs/user/app_use_cases.md @@ -1,12 +1,209 @@ # Using the App -This document describes common use-cases and scenarios for this App. - ## General Usage -## Use-cases and common workflows +### Home + +The Home view is a portal to understand what the status of the devices are. + +![Home Overview](../images/ss_golden-overview.png) + +Some of the information described in this view, may not be immediately obvious. + +* The Backup/Intended/Compliance status will always show the last time the job was successfully ran for that device, but there are several conditions it may be in. + * Green with a date indicates that the run was successful, which was the last time the job ran. + * Red with a date indicates the last time the job ran successfully, with the last time the job was attempted shown when you mouse over the date. + * A red double-dashed icon indicated the job has never been successful +* The icons are provided in the following order, that largely matches the status. + * Backups + * Intended + * Unix Diff + * SoT aggregation data + * Run job + +The first four bring up a "modal" or "dialogue box" which has a detailed view for a dedicated page. The run job brings the user to a job to run all three +components against all of the devices. + +### Jobs + +There are a series of Jobs that are registered via the Plugin. They can be viewed from the standard Jobs view. + +![Job Overview](../images/job-overview.png) + +Each Job attempts to provide sane error handling, and respects the `debug` flag to provide more information. + +![Job Result](../images/job-result.png) + +### Application Settings + +The golden configuration plugin settings can be found by navigating to `Golden Config -> Settings` button. Select one of the Settings, under the `Golden Configuration` section. +Since Golden Configuration Plugin version 1.0, the plugin allows for multiple settings to be configured by the User. +Each of the settings, has the individual repositories and configuration details, as well as a Dynamic Group. +You could use a combination of settings to customize your Configuration Compliance behavior. +Settings have a name and a weight. The weight parameter indicates the priority of given Settings - the higher the weight, the device matching the Dynamic Group defined will be assigned to the scope. +At the same moment, each device will be matched up to maximum of only one `Settings.` In case of the same weight, the sorting is performed by the name. + +![Navigate to Settings](../images/navigate-compliance-rules.png) + +To create new settings click on the `+Add` button. +To update existing settings click on one of the `Settings` name. + + +|Setting|Explanation| +|:--|:--| +|Backup Repositories |The Git Repository where your backup configurations will be found. | +|Backup Path|A Jinja template which defines the path and name of backup files within the backup repository. The variable `obj` is available as the device instance object of a given device, as is the case for all Jinja templates. e.g. `{{obj.location.name}}/{{obj.name}}.cfg`| +|Intended Repositories |The Git Repository where your intended configuration state files will be found. | +|Intended Path|A Jinja template which defines the path and name of intended configuration state files within the intended state repository. e.g. `{{obj.location.name}}/{{obj.name}}.intended_cfg`| +|Jinja Repository |The Git Repository where your jinja templates will be found. | +|Jinja Path|A Jinja template which defines the path (within the repository) and name of the Jinja template file. e.g. `{{obj.platform.name}}/{{obj.role.name}}/main.j2`| +|Dynamic Group|The scope of devices on which Golden Config's jobs can operate. | +|GraphQL Query|A query that is evaluated and used to render the config. The query must start with `query ($device_id: ID!)`.| + +!!! note + Each of these will be further detailed in their respective sections. + +#### Dynamic Group + +!!! note + Starting in Golden Config v1.2 and onwards the original implementation of scope has been deprecated in favor of Dynamic Groups from Nautobot. During the migrations any Golden Config Setting scope attribute will be migrated to Dynamic Groups. All settings require a Dynamic Group, if the original scope is not set to allow ALL Devices a Dynamic Group will be created without a filter applied which will is the equivalent of all Devices. + +The [Dynamic Group](https://docs.nautobot.com/projects/core/en/stable/models/extras/dynamicgroup/) provides a filter that will limit the list of devices in scope of a Golden Config Setting. In the Golden Config Home view the Dynamic Group is used to limit the Devices that are displayed, if a Device does not match the filter of a Dynamic Group it is considered out of scope for GoldenConfig and will not show on the Golden Config Settings view. All jobs in Golden Config also use the Dynamic Group to know which Devices are in scope. A job can optionally further refine the scope, but the outer bound would be based on what is defined in the Dynamic Group. The options are best described by leveraging the Devices list view, search features (the filtering shown on the side of the Devices.) Building a query there, will provide the exact keys expected. + +##### Scope Of Devices + +Within the Detail view of a Golden Config Setting the section to denote the scope of devices links back to the Dynamic Group that is assigned and renders the filter attribute of the Dynamic Group as JSON. All updates to the scope of Devices must be done via the Dynamic Group not directly on the Golden Config Setting. + +![Dynamic Group](../images/setting-dynamic-group.png) + +The below configurations of scope can either be removed or specified for pre 1.2 only, the same logic applies in 1.2 and onwards but via DynamicGroups. + +Filtering to specific platforms, based on their name. + +```json +{ + "platform": [ + "Cisco IOS", + "Cisco NXOS", + "Arista EOS", + "Juniper Junos" + ] +} +``` + +Adding a "has_primary_ip" check. + +```json +{ + "platform": [ + "Cisco IOS", + "Cisco NXOS", + "Arista EOS", + "Juniper Junos" + ], + "has_primary_ip": "True" +} +``` + +When viewing the settings, the scope of devices is actually a link to the query built in the Devices view. Click that link to understand which devices are permitted by the filter. + +### Git Settings + +The plugin makes heavy use of the Nautobot git data sources feature. There are up to three repositories used in the application. This set of instructions will walk an operator through setting up the backup repository. The steps are the same, except for the "Provides" field name chosen. + +In order to setup this repository, go to Nautobot and navigate to the Data Sources Git integration. `Extensibility -> Git Repositories`. + +![Backup Git Navigation](../images/git-step1.png) + +From the Git Repositories page we can add the **Backup** repository. + +Click on `Add`. + +You will now be presented with a page to fill in the repository details. + +Parameters: + +|Field|Explanation| +|:--|:--| +|Name|User friendly name for the backup repo.| +|Slug|Auto-generated based on the `name` provided.| +|Remote URL|The URL pointing to the Git repo that stores the backup configuration files. Current git url usage is limited to `http` or `https`.| +|Branch|The branch in the Git repo to use. Defaults to `main`.| +|Token|The token is a personal access token for the `username` provided. For more information on generating a personal access token. [Github Personal Access Token](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token) +|Username|The Git username that corresponds with the personal access token above.| +|Provides|Valid providers for Git Repo.| + + +!!! note + If Secret Group is used for the Repositories the secrets type HTTP(S) is required for this plugin. + +![Example Git Backups](../images/backup-git-step2.png) + +Select `backup configs` and click on `Create`. + +Once you click `Create` and the repository syncs, the main page will now show the repo along with its status. +![Git Backup Repo Status](../images/backup-git-step3.png) + +For their respective features, the "Provides" field could be backup intended configs and jinja templates. + +### Plugins Buttons + +The plugins buttons provides you with the ability to navigate to Run the script, overview report, and detailed report. + +### Run Script + +This can be accessed via the Plugins drop-down via `Run Script` button of the `Home` view, the user will be provided a form of the Job (as described +above), which will allow the user to limit the scope of the request. + +### Device Template Content + +The plugin makes use of template content `right_page` in order to use display in-line the status of that device in the traditional Nautobot view. From here you can click the link to see the detail compliance view. + +### Location Template Content + +The plugin makes use of template content `right_page` in order to use display in-line the status of that entire location in the traditional Nautobot view. This sums the total for all locations for parent locations. + +### API + +To run the job programmatically, reference the [nautobot documentation](https://docs.nautobot.com/projects/core/en/stable/additional-features/jobs/#via-the-api) for the proper API call. Pay special attention to the `class_path` definition. + +### Feature Enablement + +Enabling features such as backup or compliance, will render those parts of the UI visible. It is worth noting that disabling features does not provide any +garbage collection and it is up to the operator to remove such data. + +### Network Operating System Support + +The version of OS's supported is documented in the [FAQ](./app_faq.md) and is controlled the platform network_driver. The platform network_driver must be exactly as expected or leverage +a configuration option--which is described the the FAQ--for the plugin to work. + +### Use-cases and common workflows + +This plugin enable four (4) key use cases. + +1. **Configuration Backups** - Is a Nornir process to connect to devices, optionally parse out lines/secrets, backup the configuration, and save to a Git repository. +2. **Intended Configuration** - Is a Nornir process to generate configuration based on a Git repo of Jinja files to combine with a GraphQL generated data and a Git repo to store the intended configuration. +3. **Source of Truth Aggregation** - Is a GraphQL query per device that creates a data structure used in the generation of configuration. +4. **Configuration Compliance** - Is a process to run comparison of the actual (via backups) and intended (via Jinja file creation) CLI configurations upon saving the actual and intended configuration. This is started by either a Nornir process for cli-like configurations or calling the API for json-like configurations + +!!! warning "Notice" + The operators of their own Nautobot instance are welcome to use any combination of these features. Though the appearance may seem like they are tightly coupled, this isn't actually the case. For example, one can obtain backup configurations from their current RANCID/Oxidized process and simply provide a Git Repo of the location of the backup configurations, and the compliance process would work the same way. Also, another user may only want to generate configurations, but not want to use other features, which is perfectly fine to do so. ## Screenshots -!!! warning "Developer Note - Remove Me!" - Ideally captures every view exposed by the App. Should include a relevant dataset. +There are many features and capabilities the plugin provides into the Nautobot ecosystem. The following screenshots are intended to provide a quick visual overview of some of these features. + +The golden configuration is driven by jobs that run a series of tasks and the result is captured in this overview. + +![Overview](../images/ss_golden-overview.png) + +The compliance report provides a high-level overview on the compliance of your network. +![Compliance Report](../images/ss_compliance-report.png) + +The compliance overview will provide a per device and feature overview on the compliance of your network devices. +![Compliance Overview](../images/ss_compliance-overview.png) + +Drilling into a specific device and feature, you can get an immediate detailed understanding of your device. +![Compliance Device](../images/ss_compliance-device.png) + +![Compliance Rule](../images/ss_compliance-rule.png) diff --git a/docs/user/external_interactions.md b/docs/user/external_interactions.md deleted file mode 100644 index eaba5b56..00000000 --- a/docs/user/external_interactions.md +++ /dev/null @@ -1,17 +0,0 @@ -# External Interactions - -This document describes external dependencies and prerequisites for this App to operate, including system requirements, API endpoints, interconnection or integrations to other applications or services, and similar topics. - -!!! warning "Developer Note - Remove Me!" - Optional page, remove if not applicable. - -## External System Integrations - -### From the App to Other Systems - -### From Other Systems to the App - -## Nautobot REST API endpoints - -!!! warning "Developer Note - Remove Me!" - API documentation in this doc - including python request examples, curl examples, postman collections referred etc. diff --git a/docs/user/faq.md b/docs/user/faq.md deleted file mode 100644 index 318b08dc..00000000 --- a/docs/user/faq.md +++ /dev/null @@ -1 +0,0 @@ -# Frequently Asked Questions diff --git a/mkdocs.yml b/mkdocs.yml index 4becad9c..95edbb3a 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,11 +1,11 @@ --- dev_addr: "127.0.0.1:8001" -edit_uri: "edit/main/nautobot-plugin-golden-config/docs" -site_dir: "nautobot_golden_config/static/nautobot_golden_config/docs" -site_name: "Golden Config Documentation" +edit_uri: "edit/main/docs" +site_dir: "golden-config/static/golden-config/docs" +site_name: "Golden Configuration Documentation" site_url: "https://docs.nautobot.com/projects/golden-config/en/latest/" repo_url: "https://github.com/nautobot/nautobot-plugin-golden-config" -copyright: "Copyright © The Authors" +copyright: "Copyright © 2023 The Authors" theme: name: "material" navigation_depth: 4 @@ -14,17 +14,14 @@ theme: - "django" - "yaml" features: - - "content.action.edit" - - "content.action.view" - "content.code.copy" - - "navigation.footer" - - "navigation.indexes" + - "navigation.tracking" - "navigation.tabs" - "navigation.tabs.sticky" - - "navigation.tracking" + - "search.suggest" - "search.highlight" - "search.share" - - "search.suggest" + - "navigation.indexes" favicon: "assets/favicon.ico" logo: "assets/nautobot_logo.svg" palette: @@ -82,10 +79,8 @@ markdown_extensions: - "pymdownx.inlinehilite" - "pymdownx.snippets" - "pymdownx.superfences" - - "footnotes" plugins: - "search" - - "mkdocs-version-annotations" - "mkdocstrings": default_handler: "python" handlers: @@ -100,25 +95,46 @@ nav: - Overview: "index.md" - User Guide: - App Overview: "user/app_overview.md" - - Getting Started: "user/app_getting_started.md" - Using the App: "user/app_use_cases.md" - - Frequently Asked Questions: "user/faq.md" - - External Interactions: "user/external_interactions.md" + - Navigate Backup: "user/app_feature_backup.md" + - Navigate Compliance: "user/app_feature_compliance.md" + - Navigate Compliance CLI: "user/app_feature_compliancecli.md" + - Navigate Compliance JSON: "user/app_feature_compliancejson.md" + - Navigate Compliance Custom: "user/app_feature_compliancecustom.md" + - Navigate Intended: "user/app_feature_intended.md" + - Navigate SoT Agg: "user/app_feature_sotagg.md" + - Navigate Configuration Post-Processing: "user/app_feature_config_postprocessing.md" + - Navigate Config Plans: "user/app_feature_config_plans.md" + - Navigate Remediation: "user/app_feature_remediation.md" + - Getting Started: "user/app_getting_started.md" + - Frequently Asked Questions: "user/app_faq.md" + - External Interactions: "user/app_external_interactions.md" + - Troubleshooting: + - General: "user/troubleshooting/troubleshoot_general.md" + - Credentials: "user/troubleshooting/troubleshoot_credentials.md" + - Dispatchers: "user/troubleshooting/troubleshoot_dispatchers.md" - Administrator Guide: - - Install and Configure: "admin/install.md" - - Upgrade: "admin/upgrade.md" - - Uninstall: "admin/uninstall.md" + - Install and Configure: "admin/admin_install.md" + - Upgrade: "admin/admin_upgrade.md" + - Uninstall: "admin/admin_uninstall.md" - Compatibility Matrix: "admin/compatibility_matrix.md" - Release Notes: - "admin/release_notes/index.md" + - v1.5: "admin/release_notes/version_1.5.md" + - v1.4: "admin/release_notes/version_1.4.md" + - v1.3: "admin/release_notes/version_1.3.md" + - v1.2: "admin/release_notes/version_1.2.md" + - v1.1: "admin/release_notes/version_1.1.md" - v1.0: "admin/release_notes/version_1.0.md" + - v0.10: "admin/release_notes/version_0.10.md" + - v0.9: "admin/release_notes/version_0.9.md" - Developer Guide: - - Extending the App: "dev/extending.md" - - Contributing to the App: "dev/contributing.md" + - Extending the App: "dev/dev_extending.md" + - Contributing to the App: "dev/dev_contributing.md" - Development Environment: "dev/dev_environment.md" - - Architecture Decision Records: "dev/arch_decision.md" + - Architecture Decision Record: "dev/dev_adr.md" - Code Reference: - "dev/code_reference/index.md" - - Package: "dev/code_reference/package.md" + - Models: "dev/code_reference/models.md" - API: "dev/code_reference/api.md" - - Nautobot Docs Home ↗︎: "https://docs.nautobot.com" + - Nautobot Docs Home ↗︎: "https://docs.nautobot.com/" From 38d4d1a1a14481e4601a5d250001e945625dd8c8 Mon Sep 17 00:00:00 2001 From: Jan Snasel Date: Wed, 13 Sep 2023 12:51:21 +0000 Subject: [PATCH 6/9] fix: Update poetry lock --- poetry.lock | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/poetry.lock b/poetry.lock index 2d82efe5..fb9944fb 100644 --- a/poetry.lock +++ b/poetry.lock @@ -4633,4 +4633,4 @@ testing = ["big-O", "jaraco.functools", "jaraco.itertools", "more-itertools", "p [metadata] lock-version = "2.0" python-versions = ">=3.8,<3.12" -content-hash = "35fdae64058d358266b3189b622c5cbe281947edc72e045aee5d6c392d808997" +content-hash = "e4fcff9be10ff04cb47ad77598e2ed2525993cc94f232b0dd98aed79a420d418" From 57c51dc969c28d5a2ddfc0617ae7923023626541 Mon Sep 17 00:00:00 2001 From: Jan Snasel Date: Wed, 13 Sep 2023 12:56:43 +0000 Subject: [PATCH 7/9] fix: Pylint --- nautobot_golden_config/jobs.py | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/nautobot_golden_config/jobs.py b/nautobot_golden_config/jobs.py index 508b7429..bd67b7fb 100644 --- a/nautobot_golden_config/jobs.py +++ b/nautobot_golden_config/jobs.py @@ -1,5 +1,7 @@ """Jobs to run backups, intended config, and compliance.""" # pylint: disable=too-many-function-args,logging-fstring-interpolation +# TODO: Remove the following ignore, added to be able to pass pylint in CI. +# pylint: disable=arguments-differ from datetime import datetime @@ -394,7 +396,7 @@ def run(self, **data): except NornirNautobotException as error: error_msg = str(error) self.logger.error(error_msg) - raise NornirNautobotException(error_msg) + raise NornirNautobotException(error_msg) from error if self._plan_type in ["intended", "missing", "remediation"]: self.logger.debug("Starting config plan generation for compliance features.") self._generate_config_plan_from_feature() From 976c43fc4a4e1fdec7a26ec2c37fcbb1b09fcd51 Mon Sep 17 00:00:00 2001 From: Jan Snasel Date: Wed, 13 Sep 2023 13:29:48 +0000 Subject: [PATCH 8/9] fix: PR comments --- .github/workflows/ci.yml | 4 +--- .github/workflows/upstream_testing.yml | 4 +--- nautobot_golden_config/jobs.py | 3 ++- nautobot_golden_config/tests/test_basic.py | 2 +- 4 files changed, 5 insertions(+), 8 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index d3f05cb2..45e563c6 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -13,9 +13,7 @@ on: # yamllint disable-line rule:truthy rule:comments pull_request: ~ env: - # TODO Fix to be repository name - # PLUGIN_NAME: "nautobot-plugin-golden-config" - PLUGIN_NAME: "nautobot-golden-config" + PLUGIN_NAME: "nautobot-plugin-golden-config" jobs: black: diff --git a/.github/workflows/upstream_testing.yml b/.github/workflows/upstream_testing.yml index 31c7c9d4..0deb8033 100644 --- a/.github/workflows/upstream_testing.yml +++ b/.github/workflows/upstream_testing.yml @@ -10,6 +10,4 @@ jobs: uses: "nautobot/nautobot/.github/workflows/plugin_upstream_testing_base.yml@develop" with: # Below could potentially be collapsed into a single argument if a concrete relationship between both is enforced invoke_context_name: "NAUTOBOT_GOLDEN_CONFIG" - # TODO Fix to be repository name - # plugin_name: "nautobot-plugin-golden-config" - plugin_name: "nautobot-golden-config" + plugin_name: "nautobot-plugin-golden-config" diff --git a/nautobot_golden_config/jobs.py b/nautobot_golden_config/jobs.py index bd67b7fb..f224d846 100644 --- a/nautobot_golden_config/jobs.py +++ b/nautobot_golden_config/jobs.py @@ -439,7 +439,8 @@ def receive_job_button(self, obj): """Run config plan deployment process.""" self.logger.debug("Starting config plan deployment job.") data = {"debug": False, "config_plan": ConfigPlan.objects.filter(id=obj.id)} - config_deployment(self, data, commit=True) + # pylint: disable-next=no-value-for-parameter + config_deployment(self, data) # Conditionally allow jobs based on whether or not turned on. diff --git a/nautobot_golden_config/tests/test_basic.py b/nautobot_golden_config/tests/test_basic.py index 26a8c5aa..4bb988c9 100644 --- a/nautobot_golden_config/tests/test_basic.py +++ b/nautobot_golden_config/tests/test_basic.py @@ -20,7 +20,7 @@ class TestDocsPackaging(unittest.TestCase): """Test Version in doc requirements is the same pyproject.""" def test_version(self): - """Verify that pyproject.toml dev dependecies have the same versions as in the docs requirements.txt.""" + """Verify that pyproject.toml dev dependencies have the same versions as in the docs requirements.txt.""" parent_path = os.path.dirname(os.path.dirname(os.path.dirname(os.path.realpath(__file__)))) poetry_path = os.path.join(parent_path, "pyproject.toml") poetry_details = toml.load(poetry_path)["tool"]["poetry"]["group"]["dev"]["dependencies"] From 7476c9305dfbe40c9e9c706798e1d89116d4a3d7 Mon Sep 17 00:00:00 2001 From: Jan Snasel Date: Wed, 13 Sep 2023 13:34:30 +0000 Subject: [PATCH 9/9] fix: Job invocation --- nautobot_golden_config/jobs.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/nautobot_golden_config/jobs.py b/nautobot_golden_config/jobs.py index f224d846..f17a6811 100644 --- a/nautobot_golden_config/jobs.py +++ b/nautobot_golden_config/jobs.py @@ -439,8 +439,8 @@ def receive_job_button(self, obj): """Run config plan deployment process.""" self.logger.debug("Starting config plan deployment job.") data = {"debug": False, "config_plan": ConfigPlan.objects.filter(id=obj.id)} - # pylint: disable-next=no-value-for-parameter - config_deployment(self, data) + # pylint: disable-next=unexpected-keyword-arg + config_deployment(self, **data) # Conditionally allow jobs based on whether or not turned on.