change module names to plural

README.md

@@ -1,113 +1,210 @@
-# Ansible Platform Collection
-
-## Changelog for v2.7.20260313
-
-* Added OIDC User Identity support for Ansible Automation Platform Gateway
-* New modules: feature_flag, ca_certificates, role_team_assignment, role_definition
-* Add request_timeout_seconds and idle_timeout_seconds to route modules
-* Add enable_mtls attribute to route module for mutual TLS support
-* Add associated_authenticators parameter to users module
-* Add Gateway UI plugin Route Collection Module
-* Enhanced organization association logic and auditor user support
-* Multiple bug fixes for role assignment, object deletion, and URL handling
-* Deprecated authenticator_uid and authenticators fields
+# Ansible Platform Collection (`ansible.platform`)
 
 ## Description
 
-This collection contains modules that can be used to automate the creation of resources on an install of Ansible Automation Platform.
+The `ansible.platform` collection provides idempotent resource modules for managing
+[Red Hat Ansible Automation Platform](https://www.redhat.com/en/technologies/management/ansible)
+(AAP) Gateway resources. It targets the AAP Gateway API and enables teams to define
+infrastructure-as-code for users, organizations, teams, authentication, services,
+routing, and access control — all through standard Ansible playbooks.
 
+The collection follows the **resource module** pattern: each module accepts a desired
+`config` list and a `state` (`merged`, `replaced`, `overridden`, `deleted`, or
+`gathered`), making it easy to enforce declarative configuration at scale.
 
 ## Requirements
 
-This collection supports python versions >=3.11 and requires an ansible-core version of >=2.16.0. 
-
-It also requires an existing install of Ansible Automation Platform as a target. 
+| Requirement | Version |
+|---|---|
+| Python | >= 3.11 |
+| ansible-core | >= 2.16.0 |
+| Red Hat Ansible Automation Platform | Current release |
 
+No additional Python package dependencies are required beyond what is bundled with
+`ansible-core`.
 
 ## Installation
 
-Before using this collection, you need to install it with the Ansible Galaxy command-line tool:
+Install the collection from Ansible Galaxy:
 
-```
+```bash
 ansible-galaxy collection install ansible.platform
 ```
 
-You can also include it in a requirements.yml file and install it with ansible-galaxy collection install -r requirements.yml, using the format:
+To pin a specific version:
 
-
-```yaml
-collections:
-  - name: ansible.platform.
+```bash
+ansible-galaxy collection install ansible.platform:==2.7.20260313
 ```
 
-Note that if you install any collections from Ansible Galaxy, they will not be upgraded automatically when you upgrade the Ansible package.
-To upgrade the collection to the latest available version, run the following command:
+To upgrade an already-installed collection:
 
-```
+```bash
 ansible-galaxy collection install ansible.platform --upgrade
 ```
 
-You can also install a specific version of the collection, for example, if you need to downgrade when something is broken in the latest version (please report an issue in this repository). Use the following syntax to install version 2.5.0:
+You can also declare it in a `requirements.yml` file:
 
-```
-ansible-galaxy collection install ansible.platform:==2.5.0
+```yaml
+collections:
+  - name: ansible.platform
 ```
 
-See [using Ansible collections](https://docs.ansible.com/ansible/devel/user_guide/collections_using.html) for more details.
+Then install with:
 
-## Use Cases
-
-This collection can be used to automate to the creation of resources inside of the Ansible Automation Platform. Things such as users, organizations and teams can be created using this collection. 
+```bash
+ansible-galaxy collection install -r requirements.yml
+```
 
-Adding services (Controller, Event Driven Automation, Automation) can also be done with this collection. Nodes for those services can also be added. 
+See [Using Ansible collections](https://docs.ansible.com/ansible/devel/user_guide/collections_using.html)
+for further details.
 
-## Authenticating to AAP in a playbook
+## Use Cases
 
-Connecting to AAP requires specifying authentication variables (the ones prefixed by `aap_` here) in the task. Alternatively, `AAP_` environment variables can also be set. For a complete list of authentication variables that can be used, please refer to the module specific documentations.
+The collection is intended for platform engineers and automation architects who need to
+manage AAP Gateway configuration programmatically. Common use cases include:
+
+- **Day-0 provisioning** — bootstrap a fresh AAP installation with organizations,
+  teams, users, and authenticators defined in source control.
+- **Day-2 operations** — enforce desired state across environments; detect and
+  remediate configuration drift with `state: overridden`.
+- **Audit and reporting** — use `state: gathered` to read current platform state
+  into Ansible variables for downstream processing.
+- **CI/CD pipelines** — gate deployments on AAP configuration being exactly as
+  expected before running automation.
+
+## Included Content
+
+### Modules
+
+| Module | Description |
+|---|---|
+| `ansible.platform.applications` | Manage Gateway application (OAuth2 app) resources |
+| `ansible.platform.authenticators` | Manage Gateway authenticator resources |
+| `ansible.platform.authenticator_maps` | Manage Gateway authenticator map resources |
+| `ansible.platform.authenticator_users` | Manage Gateway authenticator user resources |
+| `ansible.platform.ca_certificates` | Manage Gateway CA certificate resources |
+| `ansible.platform.feature_flags` | Manage Gateway feature flag resources |
+| `ansible.platform.http_ports` | Manage Gateway HTTP port resources |
+| `ansible.platform.organizations` | Manage Gateway organization resources |
+| `ansible.platform.role_definitions` | Manage Gateway role definition resources |
+| `ansible.platform.role_team_assignments` | Manage Gateway role-to-team assignment resources |
+| `ansible.platform.role_user_assignments` | Manage Gateway role-to-user assignment resources |
+| `ansible.platform.routes` | Manage Gateway route resources |
+| `ansible.platform.services` | Manage Gateway service resources |
+| `ansible.platform.service_clusters` | Manage Gateway service cluster resources |
+| `ansible.platform.service_keys` | Manage Gateway service key resources |
+| `ansible.platform.service_nodes` | Manage Gateway service node resources |
+| `ansible.platform.service_types` | Manage Gateway service type resources |
+| `ansible.platform.settings` | Manage Gateway settings resources |
+| `ansible.platform.teams` | Manage Gateway team resources |
+| `ansible.platform.tokens` | Manage Gateway OAuth2 token resources |
+| `ansible.platform.ui_plugin_routes` | Manage Gateway UI plugin route resources |
+| `ansible.platform.users` | Manage Gateway user resources |
+
+### Connection Plugins
+
+| Plugin | Description |
+|---|---|
+| `ansible.platform.http` | Persistent HTTP connection plugin for the AAP Gateway API |
+
+## Authenticating to AAP Gateway
+
+Each module accepts connection parameters directly in the task. You can also export
+them as environment variables (prefixed `AAP_`).
 
 ```yaml
-- name: Manage AAP
+- name: Manage AAP Gateway resources
   hosts: localhost
   tasks:
-    - name: Example for auth
-      ansible.platform.<module-name>:
-        your-module-parameters: parameter-values
-        aap_hostname: your-hostname
-        aap_username: your-username
-        aap_password: your-password
+    - name: Ensure an organization exists
+      ansible.platform.organizations:
+        config:
+          - name: "my-org"
+            description: "Managed by Ansible"
+        state: merged
+        gateway_hostname: "https://your-aap-hostname"
+        gateway_username: "admin"
+        gateway_password: "{{ vault_aap_password }}"
+        gateway_validate_certs: true
 ```
 
+### Supported connection parameters
+
+| Parameter | Environment variable | Description |
+|---|---|---|
+| `gateway_hostname` | `GATEWAY_HOSTNAME` | URL of the AAP Gateway |
+| `gateway_username` | `GATEWAY_USERNAME` | Username for authentication |
+| `gateway_password` | `GATEWAY_PASSWORD` | Password for authentication |
+| `gateway_validate_certs` | `GATEWAY_VALIDATE_CERTS` | Validate TLS certificates (default: `true`) |
+
 ## Testing
 
-This collection is tested using integration tests which can be called via `ansible-test integration`. If you wish to run the tests manually, we recommend using the parent Makefile via `make collection-test`. It will require a running version of Ansible Automation Platform.
+The collection is tested with:
+
+- **Sanity tests** — PEP8, pylint, validate-modules, yamllint, and shebang checks via
+  `ansible-test sanity`.
+- **Molecule integration tests** — per-state scenarios (`merged`, `replaced`,
+  `overridden`, `gathered`, `deleted`, and `check` mode) for every module, run against
+  a mock Gateway server.
+
+To run sanity tests locally, the collection must reside under the correct namespace
+path:
+
+```bash
+mkdir -p ~/ansible_collections/ansible/platform
+ln -s /path/to/this/repo ~/ansible_collections/ansible/platform
+
+cd ~/ansible_collections/ansible/platform
+ansible-test sanity --python 3.12
+```
+
+To run the full lint suite (matches CI):
+
+```bash
+make collection-lint
+```
 
-The collection is tested against current version of Ansible Automation Platform.
+To run Molecule integration tests:
 
+```bash
+make collection-test
+```
+
+A running Ansible Automation Platform instance is required for integration tests.
 
 ## Support
 
-This collection is supported by RedHat Engineering. Support cases can be opened at: https://access.redhat.com/support/
+This collection is supported by Red Hat Engineering. Support cases can be opened at
+<https://access.redhat.com/support/>.
+
+For bugs and feature requests, open an issue in the
+[project repository](https://github.com/ansible/ansible.platform).
 
 ## Release Notes and Roadmap
 
-Changelogs can be found in the changelogs directory. 
+Full release notes are available in [CHANGELOG.rst](https://github.com/ansible/ansible.platform/blob/main/CHANGELOG.rst).
 
+The `changelogs/` directory contains individual release fragments and the compiled
+`changelog.yaml`.
 
 ## Related Information
 
-Please refer to Ansible Automation Platform Documentation for further documentation needs: https://docs.redhat.com/en/documentation/red_hat_ansible_automation_platform/2.5
-
+- [Red Hat Ansible Automation Platform Documentation](https://docs.redhat.com/en/documentation/red_hat_ansible_automation_platform)
+- [Using Ansible Collections](https://docs.ansible.com/ansible/devel/user_guide/collections_using.html)
+- [Ansible Resource Modules](https://docs.ansible.com/ansible/latest/network/user_guide/network_resource_modules.html)
+- [AAP Gateway API Reference](https://access.redhat.com/documentation/en-us/red_hat_ansible_automation_platform)
 
 ## License Information
 
-[GPLv3](https://github.com/ansible/ansible.platform/COPYING)
+[GPL-3.0-or-later](https://github.com/ansible/ansible.platform/blob/main/COPYING)
 
 ## Authors
 
-[Sean Sullivan](https://github.com/sean-m-sullivan)
-[Martin Slemr](https://github.com/slemrmartin)
-[Jake Jackson](https://github.com/thedboubl3j)
-[Brennan Paciorek](https://github.com/brennanpaciorek)
-[John Westcott](https://github.com/john-westcott-iv)
-[Jessica Steurer](https://github.com/jay-steurer)
-[Bryan Havenstein](https://github.com/bhavenst)
+- [Sean Sullivan](https://github.com/sean-m-sullivan)
+- [Martin Slemr](https://github.com/slemrmartin)
+- [Jake Jackson](https://github.com/thedboubl3j)
+- [Brennan Paciorek](https://github.com/brennanpaciorek)
+- [John Westcott](https://github.com/john-westcott-iv)
+- [Jessica Steurer](https://github.com/jay-steurer)
+- [Bryan Havenstein](https://github.com/bhavenst)

docs/01-overview.md

@@ -68,7 +68,7 @@ whether the underlying API has changed between AAP versions.
 **Example:**
 ```yaml
 - name: Ensure engineering team exists in the platform
-  ansible.platform.team:
+  ansible.platform.teams:
     name: engineering
     organization: Red Hat
     state: present

docs/02-resource-module-pattern.md

@@ -37,7 +37,7 @@ Fields you do **not** specify are left exactly as they are.
 ```yaml
 # First run — user does not exist → POST → changed: true
 - name: Create user alice
-  ansible.platform.user:
+  ansible.platform.users:
     config:
       - username: "alice"
         email: "alice@example.com"
@@ -58,7 +58,7 @@ Fields you do **not** specify are left exactly as they are.
 ```yaml
 # Second run — user exists, nothing changed → changed: false
 - name: Create user alice (idempotency)
-  ansible.platform.user:
+  ansible.platform.users:
     config:
       - username: "alice"
         email: "alice@example.com"
@@ -74,7 +74,7 @@ Fields you do **not** specify are left exactly as they are.
 ```yaml
 # Update one field — alice exists but email changed → PATCH → changed: true
 - name: Update alice's email
-  ansible.platform.user:
+  ansible.platform.users:
     config:
       - username: "alice"
         email: "alice-new@example.com"
@@ -100,7 +100,7 @@ return `changed: true`. Running deleted twice is always idempotent.
 ```yaml
 # First run — alice exists → DELETE → changed: true
 - name: Remove user alice
-  ansible.platform.user:
+  ansible.platform.users:
     config:
       - username: "alice"
     state: deleted
@@ -113,7 +113,7 @@ return `changed: true`. Running deleted twice is always idempotent.
 ```yaml
 # Second run — alice is already gone → changed: false
 - name: Remove user alice again (idempotency)
-  ansible.platform.user:
+  ansible.platform.users:
     config:
       - username: "alice"
     state: deleted
@@ -136,7 +136,7 @@ updates, or deletes anything. Always returns `changed: false`.
 ```yaml
 # Gather all users
 - name: Read all users
-  ansible.platform.user:
+  ansible.platform.users:
     state: gathered
     gateway_hostname: "https://gateway.example.com"
     gateway_username: "admin"
@@ -155,7 +155,7 @@ updates, or deletes anything. Always returns `changed: false`.
 ```yaml
 # Gather a specific user (filter by config)
 - name: Check if alice exists
-  ansible.platform.user:
+  ansible.platform.users:
     config:
       - username: "alice"
     state: gathered
@@ -178,7 +178,7 @@ resource to have exactly and only the fields you declare.
 ```yaml
 # alice currently has: first_name=Alice, last_name=Smith, is_superuser=false
 - name: Replace alice's record (unspecified fields will be nulled)
-  ansible.platform.user:
+  ansible.platform.users:
     config:
       - username: "alice"
         email: "alice-replaced@example.com"
@@ -210,7 +210,7 @@ exist are created. Existing resources that differ are updated.
 # Current platform state: [admin, alice, charlie]
 # After overridden, ONLY alice and bob will exist
 - name: Enforce exact user set
-  ansible.platform.user:
+  ansible.platform.users:
     config:
       - username: "alice"
         email: "alice@example.com"
@@ -253,11 +253,11 @@ Without the resource module pattern, a playbook author would need to:
 3. If creating, call the POST endpoint.
 4. If updating, call the PATCH endpoint with only changed fields.
 
-The `ansible.platform.user` module encapsulates all of this:
+The `ansible.platform.users` module encapsulates all of this:
 
 ```yaml
 - name: Ensure user alice exists          # one task
-  ansible.platform.user:
+  ansible.platform.users:
     username: alice
     email: alice@example.com
     organizations: [engineering, ops]
@@ -398,7 +398,7 @@ collection that works across all of them. The resource module pattern, combined
 the versioned data model, makes this possible. The playbook author writes:
 
 ```yaml
-ansible.platform.user:
+ansible.platform.users:
   username: alice
   state: present
 ```
@@ -413,7 +413,7 @@ baseline. `state: enforced` on a resource module is their tool:
 
 ```yaml
 - name: Enforce approved HTTP ports only
-  ansible.platform.http_port:
+  ansible.platform.http_ports:
     port: 443
     state: enforced
   loop: "{{ approved_ports }}"

docs/04-data-model-transformation.md

@@ -40,7 +40,7 @@ place where version-specific and resource-specific logic lives.
 
 ### Concrete Example: User Create (`state: merged`)
 
-The same data as it appears at each tier for `ansible.platform.user`:
+The same data as it appears at each tier for `ansible.platform.users`:
 
 **Tier 1 — what the playbook author writes:**
 ```yaml