Release v6.2.0

.github/workflows/trigger_scheduled_devel.yml

@@ -0,0 +1,36 @@
+---
+name: "Scheduled CI - ansible-core devel"
+on: # yamllint disable
+  schedule:
+    # Run every Wednesday at 03:20 UTC (offset from Monday stable run)
+    - cron: "20 3 * * 3"
+  workflow_dispatch:
+    inputs:
+      branch:
+        description: "The ansible-core branch to test against"
+        required: false
+        default: "devel"
+        type: string
+
+env:
+  ANSIBLE_CORE_BRANCH: "${{ inputs.branch || 'devel' }}"
+
+jobs:
+  unit:
+    runs-on: "ubuntu-latest"
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version:
+          - "3.12"
+    env:
+      INVOKE_NAUTOBOT_ANSIBLE_PYTHON_VER: "${{ matrix.python-version }}"
+    # Allow failures — devel breakage is expected and should not block anything
+    continue-on-error: true
+    steps:
+      - name: "Check out repository code"
+        uses: "actions/checkout@v4"
+      - name: "Install invoke"
+        run: "pip install -U pip && pip install invoke packaging"
+      - name: "Run tests against ansible-core ${{ env.ANSIBLE_CORE_BRANCH }}"
+        run: "invoke unit --ansible-core-branch ${{ env.ANSIBLE_CORE_BRANCH }} --skip lint"

CHANGELOG.md

@@ -4,6 +4,54 @@ This document describes all new features and changes in the release. The format
 
 <!-- towncrier release notes start -->
 
+## [v6.2.0](https://github.com/nautobot/nautobot-ansible/releases/tag/v6.2.0)
+
+### Added
+
+- [#696](https://github.com/nautobot/nautobot-ansible/issues/696) - Added meta/execution-environment.yml for Ansible Builder support.
+- [#705](https://github.com/nautobot/nautobot-ansible/issues/705) - Added graphql_info and graphql_facts modules to replace query_graphql, following Ansible naming conventions for info and facts modules.
+- [#711](https://github.com/nautobot/nautobot-ansible/issues/711) - Added provider_network module for managing provider networks within Nautobot.
+- [#728](https://github.com/nautobot/nautobot-ansible/issues/728) - Added the ability to assign secrets to a secrets group when using the `secrets_group` module.
+- [#728](https://github.com/nautobot/nautobot-ansible/issues/728) - Added the ability to assign static group associations when using the `dynamic_group` module.
+- [#728](https://github.com/nautobot/nautobot-ansible/issues/728) - Added the ability to assign prefixes to a cloud network when using the `cloud_network` module.
+- [#728](https://github.com/nautobot/nautobot-ansible/issues/728) - Added the ability to assign cloud networks to a cloud service when using the `cloud_service` module.
+- [#728](https://github.com/nautobot/nautobot-ansible/issues/728) - Added the ability to assign vrfs to a device, virtual machine, or virtual device context when using the respective module.
+- [#728](https://github.com/nautobot/nautobot-ansible/issues/728) - Added the ability to assign clusters to a device when using the `device` module.
+- [#728](https://github.com/nautobot/nautobot-ansible/issues/728) - Added the ability to assign ip addresses to a device interface or vm interface when using the respective module.
+- [#728](https://github.com/nautobot/nautobot-ansible/issues/728) - Added the ability to assign prefixes or vlans to a location when using the `location` module.
+- [#728](https://github.com/nautobot/nautobot-ansible/issues/728) - Added the ability to assign provider networks to a provider when using the `provider` module.
+- [#728](https://github.com/nautobot/nautobot-ansible/issues/728) - Added the ability to manage custom field choices to a custom field when using the `custom_field` module.
+- [#728](https://github.com/nautobot/nautobot-ansible/issues/728) - Added the ability to manage metadata choices to a metadata type when using the `metadata_type` module.
+
+### Deprecated
+
+- [#705](https://github.com/nautobot/nautobot-ansible/issues/705) - Deprecated query_graphql module. Use graphql_info (returns data only) or graphql_facts (sets ansible_facts) instead.
+- [#728](https://github.com/nautobot/nautobot-ansible/issues/728) - Deprecated the `secrets_groups_association` module. Use the `secrets` option of the `secrets_group` module instead.
+- [#728](https://github.com/nautobot/nautobot-ansible/issues/728) - Deprecated the `static_group_association` module. Use the `static_group_associations` option of the `dynamic_group` module instead.
+- [#728](https://github.com/nautobot/nautobot-ansible/issues/728) - Deprecated the `cloud_network_prefix_assignment` module. Use the `prefixes` option of the `cloud_network` module instead.
+- [#728](https://github.com/nautobot/nautobot-ansible/issues/728) - Deprecated the `cloud_service_network_assignment` module. Use the `cloud_networks` option of the `cloud_service` module instead.
+- [#728](https://github.com/nautobot/nautobot-ansible/issues/728) - Deprecated the `vrf_device_assignment` module. Use the `vrfs` option of the `device`, `virtual_machine`, or `virtual_device_context` module instead.
+- [#728](https://github.com/nautobot/nautobot-ansible/issues/728) - Deprecated the `device_cluster_assignment` module. Use the `clusters` option of the `device` module instead.
+- [#728](https://github.com/nautobot/nautobot-ansible/issues/728) - Deprecated the `ip_address_to_interface` module. Use the `ip_addresses` option of the `device_interface` or `vm_interface` module instead.
+- [#728](https://github.com/nautobot/nautobot-ansible/issues/728) - Deprecated the `prefix_location` module. Use the `prefixes` option of the `location` module instead.
+- [#728](https://github.com/nautobot/nautobot-ansible/issues/728) - Deprecated the `vlan_location` module. Use the `vlans` option of the `location` module instead.
+- [#728](https://github.com/nautobot/nautobot-ansible/issues/728) - Deprecated the `custom_field_choice` module. Use the `custom_field_choices` option of the `custom_field` module instead.
+- [#728](https://github.com/nautobot/nautobot-ansible/issues/728) - Deprecated the `metadata_choice` module. Use the `metadata_choices` option of the `metadata_type` module instead.
+- [#728](https://github.com/nautobot/nautobot-ansible/issues/728) - Deprecated the `provider_network` module. Use the `provider_networks` option of the `provider` module instead.
+
+### Documentation
+
+- [#694](https://github.com/nautobot/nautobot-ansible/issues/694) - Added Code of Conduct link to README for Ansible inclusion compliance.
+- [#695](https://github.com/nautobot/nautobot-ansible/issues/695) - Add CONTRIBUTING.md that links to the official documentation.
+- [#697](https://github.com/nautobot/nautobot-ansible/issues/697) - Updated Python and Ansible version requirements in README to reflect actual supported versions.
+- [#703](https://github.com/nautobot/nautobot-ansible/issues/703) - Added Communication section to README with Ansible Forum links per Ansible inclusion requirements.
+- [#709](https://github.com/nautobot/nautobot-ansible/issues/709) - Added missing RETURN block to the service module.
+
+### Housekeeping
+
+- [#709](https://github.com/nautobot/nautobot-ansible/issues/709) - Added unit tests to validate all modules have required Ansible documentation blocks (DOCUMENTATION, EXAMPLES, RETURN, version_added).
+- [#718](https://github.com/nautobot/nautobot-ansible/issues/718) - Added CI testing against ansible-core devel branch and `--ansible-core-branch` flag on `invoke unit` for local testing.
+
 ## [v6.1.1](https://github.com/nautobot/nautobot-ansible/releases/tag/v6.1.1)
 
 ### Added

CONTRIBUTING.md

@@ -0,0 +1,9 @@
+# Contributing
+
+Thank you for your interest in contributing to Nautobot Ansible!
+
+Please see the main contributing guide here:
+
+https://docs.nautobot.com/projects/ansible/en/stable/getting_started/
+
+That guide covers contributing guidelines, MkDocs documentation workflow, changelog fragments, and the release process. This file is intentionally brief and simply redirects to the authoritative docs.

Dockerfile

@@ -49,6 +49,15 @@ ENV SKIP_LINT_TESTS=${SKIP_LINT_TESTS}
 # Install dev dependencies
 RUN poetry install
 
+# Optionally install ansible-core from a specific branch (e.g. "devel" or "milestone")
+# This must come AFTER poetry install so the lock file version doesn't overwrite it.
+ARG ANSIBLE_CORE_BRANCH
+RUN if [ -n "${ANSIBLE_CORE_BRANCH}" ]; then \
+    pip install --upgrade pip setuptools && \
+    pip install --force-reinstall --no-deps \
+    "https://github.com/ansible/ansible/archive/${ANSIBLE_CORE_BRANCH}.tar.gz"; \
+    fi
+
 # Copy in the application source and everything not explicitly banned by .dockerignore
 COPY . .
 

README.md

@@ -69,13 +69,28 @@ This collection provides Ansible plugins (modules, inventory, lookup/filters) to
 
 Testing is completed via the GitHub actions located in the `.github/workflows` directory.
 
-## Contributing
+## Communication
 
-Check out the docs at https://docs.nautobot.com/projects/ansible/en/stable/getting_started/
+* Join the Ansible forum:
+  * [Get Help](https://forum.ansible.com/c/help/6): get help or help others. Please add the [`nautobot`](https://forum.ansible.com/tag/nautobot) tag if you start new discussions.
+  * [Posts tagged with 'nautobot'](https://forum.ansible.com/tag/nautobot): subscribe to participate in collection-related conversations.
+  * [Social Spaces](https://forum.ansible.com/c/chat/4): gather and interact with fellow enthusiasts.
+  * [News & Announcements](https://forum.ansible.com/c/news/5): track project-wide announcements including social events.
+
+* Additional community resources:
+  * [Network to Code Slack](https://networktocode.slack.com) ([sign up](https://slack.networktocode.com))
+  * [GitHub Issues](https://github.com/nautobot/nautobot-ansible/issues): report bugs or request features
+
+## Code of Conduct
+
+This project adheres to the [Network to Code Code of Conduct](CODE_OF_CONDUCT). By participating, you are expected to uphold this code.
 
 ## Support
+For more information about communication, see the [Ansible communication guide](https://docs.ansible.com/ansible/devel/community/communication.html).
+
+## Contributing
 
-For issues please use [GitHub Issues](https://github.com/nautobot/nautobot-ansible) to open any issue that you may have. Additional community is available at the [Network to Code Slack](https://networktocode.slack.com) and [sign up](https://slack.networktocode.com).
+Check out the docs at https://docs.nautobot.com/projects/ansible/en/stable/getting_started/
 
 ## Release Notes and Roadmap
 

changelogs/changelog.yaml

@@ -761,3 +761,60 @@ releases:
       minor_changes:
         - (#684) - Added tenant option to the `namespace` module so that tenants can be associated with namespaces.
         - (#685) - Added description option to the `rir` module so that descriptions can be configured with RIRs.
+  6.2.0:
+    changes:
+      release_summary: 'This release adds the ability to manage many-to-many fields inline on parent modules.
+
+        Previously, managing these associations required using separate standalone modules
+        (e.g., `vrf_device_assignment`, `prefix_location`, `secrets_groups_association`).
+        Now you can manage them inline on the parent module using the appropriate M2M field options.
+
+        M2M fields have a separate state (merge, replace, or delete) from the parent object to control the association state.'
+      minor_changes:
+        - (#696) - Added meta/execution-environment.yml for Ansible Builder support.
+        - (#705) - Added graphql_info and graphql_facts modules to replace query_graphql, following Ansible naming conventions for info and facts modules.
+        - (#711) - Added provider_network module for managing provider networks within Nautobot.
+        - (#728) - Added the ability to assign secrets to a secrets group when using the `secrets_group` module.
+        - (#728) - Added the ability to assign static group associations when using the `dynamic_group` module.
+        - (#728) - Added the ability to assign prefixes to a cloud network when using the `cloud_network` module.
+        - (#728) - Added the ability to assign cloud networks to a cloud service when using the `cloud_service` module.
+        - (#728) - Added the ability to assign vrfs to a device, virtual machine, or virtual device context when using the respective module.
+        - (#728) - Added the ability to assign clusters to a device when using the `device` module.
+        - (#728) - Added the ability to assign ip addresses to a device interface or vm interface when using the respective module.
+        - (#728) - Added the ability to assign prefixes or vlans to a location when using the `location` module.
+        - (#728) - Added the ability to assign provider networks to a provider when using the `provider` module.
+        - (#728) - Added the ability to manage custom field choices to a custom field when using the `custom_field` module.
+        - (#728) - Added the ability to manage metadata choices to a metadata type when using the `metadata_type` module.
+      deprecated_features:
+        - (#705) - Deprecated query_graphql module. Use graphql_info (returns data only) or graphql_facts (sets ansible_facts) instead.
+        - (#728) - Deprecated the `secrets_groups_association` module. Use the `secrets` option of the `secrets_group` module instead.
+        - (#728) - Deprecated the `static_group_association` module. Use the `static_group_associations` option of the `dynamic_group` module instead.
+        - (#728) - Deprecated the `cloud_network_prefix_assignment` module. Use the `prefixes` option of the `cloud_network` module instead.
+        - (#728) - Deprecated the `cloud_service_network_assignment` module. Use the `cloud_networks` option of the `cloud_service` module instead.
+        - (#728) - Deprecated the `vrf_device_assignment` module.
+          Use the `vrfs` option of the `device`, `virtual_machine`, or `virtual_device_context` module instead.
+        - (#728) - Deprecated the `device_cluster_assignment` module. Use the `clusters` option of the `device` module instead.
+        - (#728) - Deprecated the `ip_address_to_interface` module. Use the `ip_addresses` option of the `device_interface` or `vm_interface` module instead.
+        - (#728) - Deprecated the `prefix_location` module. Use the `prefixes` option of the `location` module instead.
+        - (#728) - Deprecated the `vlan_location` module. Use the `vlans` option of the `location` module instead.
+        - (#728) - Deprecated the `custom_field_choice` module. Use the `custom_field_choices` option of the `custom_field` module instead.
+        - (#728) - Deprecated the `metadata_choice` module. Use the `metadata_choices` option of the `metadata_type` module instead.
+        - (#728) - Deprecated the `provider_network` module. Use the `provider_networks` option of the `provider` module instead.
+      trivial:
+        - (#694) - Added Code of Conduct link to README for Ansible inclusion compliance.
+        - (#695) - Add CONTRIBUTING.md that links to the official documentation.
+        - (#697) - Updated Python and Ansible version requirements in README to reflect actual supported versions.
+        - (#703) - Added Communication section to README with Ansible Forum links per Ansible inclusion requirements.
+        - (#709) - Added missing RETURN block to the service module.
+        - (#709) - Added unit tests to validate all modules have required Ansible documentation blocks (DOCUMENTATION, EXAMPLES, RETURN, version_added).
+        - (#718) - Added CI testing against ansible-core devel branch and `--ansible-core-branch` flag on `invoke unit` for local testing.
+    modules:
+      - name: graphql_info
+        description: Returns the results of a GraphQL query from Nautobot
+        namespace: ''
+      - name: graphql_facts
+        description: Sets the results of a GraphQL query from Nautobot as ansible_facts
+        namespace: ''
+      - name: provider_network
+        description: Creates or removes provider networks from Nautobot
+        namespace: ''

docker-compose.yml

@@ -2,6 +2,7 @@
 x-args:
   &args
   PYTHON_VER: ${PYTHON_VER}
+  ANSIBLE_CORE_BRANCH: ${ANSIBLE_CORE_BRANCH:-}
   ANSIBLE_SANITY_ARGS: ${ANSIBLE_SANITY_ARGS:-}
   ANSIBLE_UNIT_ARGS: ${ANSIBLE_UNIT_ARGS:-}
   SKIP_LINT_TESTS: ${SKIP_LINT_TESTS:-}

docs/getting_started/contributing/modules/architecture.md

@@ -291,3 +291,49 @@ The next few lines manipulate the data and prepare it for sending to Nautobot.
 - Converts any fields that are namespaced to prevent conflicts when searching for them (e.g. device_role, ipam_role, rack_group, etc.)
 
 If all those pass, it sets the manipulated data to `self.data` that is used in the module util apps.
+
+## Inline M2M Fields
+
++++ 6.2.0
+
+Some parent modules support inline many-to-many (M2M) association fields. These are declared in the `M2M_FIELDS` global dict in `utils.py`, which maps each endpoint to its supported M2M fields and their association API endpoints:
+
+```python
+M2M_FIELDS = {
+    "devices": {
+        "vrfs": "vrf_device_assignments",
+        "clusters": "device_cluster_assignments",
+    },
+    "locations": {
+        "prefixes": "prefix_location_assignments",
+        "vlans": "vlan_location_assignments",
+    },
+    # ... etc.
+}
+```
+
+### How M2M Fields Are Processed
+
+During `__init__`, M2M fields are handled separately from regular fields to prevent collisions with `_find_ids`:
+
+1. **Extraction**: M2M field data is popped from the data dict *before* `_find_ids` runs on the parent data. This prevents M2M field names (like `prefixes`) from being mistakenly resolved as direct FK relationships.
+2. **Child resolution**: Each M2M object's child key (e.g., `vrf`, `prefix`, `ip_address`) is individually run through `_find_ids` to resolve names to UUIDs. This supports both simple strings (`vrf: "My VRF"`) and dicts for disambiguation (`ip_address: {address: "10.0.0.1/24", namespace: "Global"}`).
+3. **Payload stripping**: M2M field names are added to `remove_keys` so they are stripped from the REST API payload sent for the parent object.
+
+After the parent object is created or updated, `_ensure_object_exists` calls `_process_m2m_fields` which iterates through each M2M field and:
+
+- Fetches current associations from the API
+- Compares desired vs current using normalized comparison keys
+- Applies the requested state (`merge`, `replace`, or `delete`) via bulk create/delete operations
+
+### Adding M2M Support to a New Module
+
+If a new association endpoint is added to Nautobot and you want to support inline management:
+
+1. Add the mapping to `M2M_FIELDS` in `utils.py`
+2. Add the M2M argument to the parent module's `argument_spec` following the standard structure (state/objects/child_key suboptions)
+3. Add matching `DOCUMENTATION` with suboptions
+4. Ensure the child key is in `CONVERT_TO_ID` and has appropriate `QUERY_TYPES`, `ENDPOINT_NAME_MAPPING`, and `ALLOWED_QUERY_PARAMS` entries
+5. Add integration tests covering merge, replace, delete, and idempotency
+
+No changes to the module's `main()` function or constructor are needed -- the framework auto-detects M2M fields from `M2M_FIELDS` based on `self.endpoint`.

docs/getting_started/contributing/testing_locally.md

@@ -57,6 +57,22 @@ You can then run `invoke integration` to run the integration tests against Nauto
 ❯ invoke integration
 ```
 
+You can use `-t` to run only specific tagged tests, or `-s` to skip specific test categories. Use `-h` to see all available options.
+
+```shell
+# Run only graphql_info integration tests
+❯ invoke integration -t graphql_info
+
+# Run only graphql_info and graphql_facts tests
+❯ invoke integration -t graphql_info -t graphql_facts
+
+# Skip lint and sanity, only run integration tests
+❯ invoke integration -s lint -s sanity
+
+# See all available options
+❯ invoke integration -h
+```
+
 ## Using Environment Variables
 
 You can use the following environment variables to test against different Python or Nautobot versions.