ansible.platform Collection: Configuration as Code for Ansible Automation Platform 2.7

By Luca Berton · Published 2026-06-29 · Category: installation

Guide to the ansible.platform collection for AAP 2.7: 22 CaC modules, action plugins on the controller, and the new http connection plugin.

Ansible Automation Platform 2.7 introduces the ansible.platform collection as the unified Configuration as Code (CaC) interface for managing all platform resources. Released alongside AAP 2.7 on June 3, 2026, it provides 22 modules and 1 lookup plugin that communicate exclusively through the platform gateway API.

Why ansible.platform Replaces Direct Component Access

Previous versions of AAP required managing resources by calling individual component APIs — automation controller, private automation hub, and EDA each had separate endpoints. The ansible.platform collection unifies all of these under a single gateway API, which aligns with the broader AAP 2.7 change that removes direct external routes to individual components.

This means:

One collection manages the entire platform
Authentication happens once at the gateway level
Component upgrades don't break your CaC playbooks

Breaking Change: Tasks Run on the Controller Node

All ansible.platform tasks now run as action plugins on the Ansible controller node, not on managed nodes. This is the most important behavioral change to understand before adopting this collection.

# CORRECT — target localhost with local connection
- name: Configure AAP platform resources
  hosts: localhost
  connection: local
  tasks:
    - name: Create a credential
      ansible.platform.credential:
        name: prod-vault-cred
        credential_type: HashiCorp Vault Secret Lookup
        organization: Default
        state: present

# THIS NO LONGER WORKS — delegate_to remote host is not supported
- name: Configure AAP (broken in 2.7)
  hosts: aap_controller
  tasks:
    - name: Create credential
      ansible.platform.credential:
        name: prod-vault-cred
      delegate_to: some-remote-host  # Ignored — still runs on controller

The ansible.platform.http Connection Plugin

A new connection mode, connection: ansible.platform.http, reuses authenticated sessions across all tasks in a play. Authentication happens once instead of per task — a significant performance improvement for large CaC deployments with many resources.

- name: Bulk platform configuration
  hosts: localhost
  connection: ansible.platform.http
  vars:
    controller_host: https://aap.example.com
    controller_username: admin
    controller_password: "{{ vault_aap_password }}"
  tasks:
    - name: Create organization
      ansible.platform.organization:
        name: "Platform Engineering"
        description: "Platform Engineering team"
        state: present

    - name: Create team
      ansible.platform.team:
        name: "infra-team"
        organization: "Platform Engineering"
        state: present

    - name: Assign role to team
      ansible.platform.role_team_assignment:
        role_definition: "Organization Admin"
        team: "infra-team"
        object_id: "Platform Engineering"
        state: present

With connection: ansible.platform.http, the session token obtained from the first module call is reused for all subsequent tasks, eliminating repeated authentication overhead.

New Modules in AAP 2.7

feature_flag — Runtime Feature Flags

Query and toggle platform feature flags at runtime without redeployment:

- name: Enable feature flag for new UI
  ansible.platform.feature_flag:
    name: new_unified_ui
    enabled: true
    state: present

This replaces the previous approach of setting feature flags only at installation time. In AAP 2.7, administrators can toggle flags directly from the UI or via CaC.

ca_certificate — Mutual TLS Certificate Management

Manage CA certificates for mTLS authentication between platform services:

- name: Register internal CA for mTLS
  ansible.platform.ca_certificate:
    name: "internal-ca"
    certificate: "{{ lookup('file', 'certs/internal-ca.pem') }}"
    state: present

role_team_assignment — Team RBAC with Batch Support

Assign roles to teams across specific resources or organizations. The new object_ids parameter enables batch operations in a single task:

- name: Grant team access to multiple projects
  ansible.platform.role_team_assignment:
    role_definition: "Project Admin"
    team: "infra-team"
    object_ids:
      - "project-alpha"
      - "project-beta"
      - "project-gamma"
    state: present

role_definition — Custom RBAC Role Definitions

Create custom RBAC roles with specific permissions scoped to a content type:

- name: Create custom playbook runner role
  ansible.platform.role_definition:
    name: "Playbook Runner"
    description: "Can execute job templates but not edit them"
    permissions:
      - execute_jobtemplate
      - view_jobtemplate
      - view_inventory
    content_type: jobtemplate
    state: present

ui_plugin_route — Front-End Plugin Routes

Configure routes for UI plugins that integrate with the platform gateway:

- name: Register custom dashboard plugin route
  ansible.platform.ui_plugin_route:
    name: "custom-dashboard"
    prefix: "/custom"
    service: "dashboard-service"
    request_timeout_seconds: 30
    idle_timeout_seconds: 60
    state: present

Enhanced Existing Modules

Mutual TLS for Service and Route Modules

The service and route modules now support enable_mtls for mutual TLS authentication between gateway-registered services:

- name: Register service with mTLS
  ansible.platform.service:
    name: "automation-hub"
    url: https://hub.internal:8443
    enable_mtls: true
    state: present

Route Timeout Configuration

Per-route timeout parameters are available in service, route, and ui_plugin_route:

- name: Configure route with custom timeouts
  ansible.platform.route:
    name: "slow-reports-api"
    service: "reporting-service"
    prefix: "/api/v1/reports"
    request_timeout_seconds: 120
    idle_timeout_seconds: 300
    state: present

OIDC User Identity in authenticator Module

The authenticator module supports OpenID Connect User Identity configuration for the platform gateway:

- name: Configure OIDC authenticator
  ansible.platform.authenticator:
    name: "corporate-oidc"
    type: keycloak
    configuration:
      SERVER_URL: https://keycloak.example.com
      KEY_CLOAK_HOST: https://keycloak.example.com
      SOCIAL_AUTH_KEYCLOAK_PUBLIC_KEY: "{{ lookup('file', 'certs/keycloak-public.pem') }}"
      SOCIAL_AUTH_KEYCLOAK_KEY: "{{ vault_oidc_client_id }}"
      SOCIAL_AUTH_KEYCLOAK_SECRET: "{{ vault_oidc_secret }}"
    enabled: true
    state: present

Batch Role Assignments for Users

The role_user_assignment module supports object_ids to assign a role to a user across multiple resources in one task:

- name: Grant user access to multiple inventories
  ansible.platform.role_user_assignment:
    role_definition: "Inventory Admin"
    user: "jsmith"
    object_ids:
      - "us-east-inventory"
      - "us-west-inventory"
      - "eu-central-inventory"
    state: present

Complete CaC Playbook Example

Here is a full day-1 platform configuration playbook using the ansible.platform collection:

---
- name: Day-1 AAP Platform Configuration
  hosts: localhost
  connection: ansible.platform.http
  vars:
    controller_host: "https://aap.example.com"
    controller_username: "admin"
    controller_password: "{{ vault_aap_admin_password }}"
  tasks:
    # Organizations
    - name: Create organizations
      ansible.platform.organization:
        name: "{{ item.name }}"
        description: "{{ item.description }}"
        state: present
      loop:
        - name: "Platform Engineering"
          description: "Infrastructure platform team"
        - name: "Application Teams"
          description: "Product application teams"

    # Custom Roles
    - name: Create playbook runner role
      ansible.platform.role_definition:
        name: "Job Executor"
        permissions:
          - execute_jobtemplate
          - view_jobtemplate
          - view_inventory
        content_type: jobtemplate
        state: present

    # Teams
    - name: Create teams
      ansible.platform.team:
        name: "{{ item.team }}"
        organization: "{{ item.org }}"
        state: present
      loop:
        - team: "infra-engineers"
          org: "Platform Engineering"
        - team: "app-developers"
          org: "Application Teams"

    # CA Certificates for mTLS
    - name: Register CA certificates
      ansible.platform.ca_certificate:
        name: "{{ item.name }}"
        certificate: "{{ lookup('file', item.cert_file) }}"
        state: present
      loop:
        - name: "internal-ca"
          cert_file: "certs/internal-ca.pem"

    # Feature Flags
    - name: Enable production feature flags
      ansible.platform.feature_flag:
        name: "{{ item }}"
        enabled: true
      loop:
        - unified_ui
        - oidc_user_identity

Migration from Direct Component APIs

If your existing CaC playbooks target automation controller, Automation Hub, or EDA APIs directly, migrate them to ansible.platform before upgrading to AAP 2.7. Red Hat provides the aap-detect-direct-component-access CLI utility to identify legacy direct-API usage in your scripts.

# Run the detection utility (containerized/operator installs only)
aap-detect-direct-component-access --scan-path /etc/tower/conf.d /opt/automation

The utility reports any API calls that bypass the gateway and need to be migrated.

Installing the Collection

ansible-galaxy collection install ansible.platform

# Or pin a specific version
ansible-galaxy collection install ansible.platform:==2.7.0

Add it to your requirements.yml for consistent team deployments:

collections:
  - name: ansible.platform
    version: ">=2.7.0"

FAQ

Do I need to change all my existing playbooks?

Any playbook using the old awx.awx or direct automationcontroller modules should be reviewed. The ansible.platform collection is the new standard — Red Hat will concentrate CaC development here going forward.

Can I still use connection: local instead of ansible.platform.http?

Yes. connection: local still works and is required if you need to mix platform tasks with other local tasks in the same play. Use connection: ansible.platform.http when a play contains only ansible.platform tasks and you want session reuse.

Is basic authentication still supported?

AAP 2.7 disables basic authentication and personal access tokens for automation controller, Automation Hub, and EDA. Use token-based authentication or OIDC with the ansible.platform collection.

Conclusion

The ansible.platform collection is the definitive way to manage Ansible Automation Platform 2.7 as code. With 22 modules covering the full platform lifecycle, the new HTTP connection plugin for session efficiency, and support for mTLS and OIDC, it provides a production-grade foundation for platform automation.

Category: installation

Browse all Ansible tutorials · AnsiblePilot Home

AnsiblePilot — Master Ansible Automation

Popular Topics

About Luca Berton