Add feature_flag module for Automation Platform Gateway

[fao89]

Description

• What is being changed? Add a new feature_flag module to manage Automation Platform Gateway feature flags
• Why is this change needed? To provide Ansible users with the ability to view and configure runtime feature flags in AAP Gateway, enabling better control over platform features
• How does this change address the issue? Implements a complete module with supporting utilities, comprehensive documentation, integration tests, and practical examples for managing feature flags

This PR introduces comprehensive support for feature flag management, including:

• New ansible.platform.feature_flag module for managing AAP Gateway feature flags
• Supporting utility classes (AAPFeatureFlag) with proper API integration
• Safety checks to prevent modification of install-time flags
• Comprehensive integration tests covering all use cases
• Example playbook demonstrating common feature flag operations

Type of Change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update
• Test update
• Refactoring (no functional changes)
• Development environment change
• Configuration change

Self-Review Checklist

• I have performed a self-review of my code
• I have added relevant comments to complex code sections
• I have updated documentation where needed
• I have considered the security impact of these changes
• I have considered performance implications
• I have thought about error handling and edge cases
• I have tested the changes in my local environment

Testing Instructions

Prerequisites

• AAP Gateway instance running and accessible
• Runtime feature flags enabled in AAP Gateway settings (RUNTIME_FEATURE_FLAGS=True)
• Valid authentication credentials (username/password or token)
• At least one runtime feature flag available for testing

Steps to Test

Basic Functionality Test

1. Run the example playbook:

   ansible-playbook examples/feature_flag_management.yml -e gateway_admin_password=<password>

Integration Test

1. Install the collection locally:

   make collection-install

2. Run the feature flag integration tests:

   make collection-test-integration TARGET=feature_flags_test

Manual Module Testing

1. Check if a feature flag exists:

   - name: Check feature flag
     ansible.platform.feature_flag:
       name: FEATURE_EXAMPLE_ENABLED
       state: exists

2. Update a runtime feature flag:

   - name: Enable feature flag
     ansible.platform.feature_flag:
       name: FEATURE_EXAMPLE_ENABLED
       value: "True"
       state: present

Expected Results

• Module should successfully retrieve feature flag information for exists state
• Runtime feature flags can be enabled/disabled with present state
• Install-time feature flags should fail with appropriate error message when attempting to modify
• Integration tests should pass with no errors
• Check mode should work correctly without making actual changes
• Idempotency should be maintained (no changes when value is already correct)

Additional Context

Key Features

• Safety First: Prevents modification of install-time feature flags and validates runtime flag settings
• Comprehensive State Management: Supports exists, present, enforced, and absent states (though absent is blocked for safety)
• Validation: Checks if runtime feature flags are enabled and validates boolean values
• Idempotency: Module is fully idempotent and supports check mode
• Error Handling: Comprehensive error handling for common scenarios (missing flags, invalid values, disabled runtime flags)

Implementation Details

• Follows existing collection patterns using AAPObject base class
• Uses PATCH method for updates (as required by AAP Gateway API)
• Includes comprehensive documentation with examples and return values
• Integration tests cover all supported operations and error conditions

API Integration

• Uses /api/gateway/v1/feature_flags/ endpoint
• Validates against settings endpoint to ensure runtime flags are enabled
• Properly handles AAP Gateway authentication patterns

Required Actions

• Requires documentation updates
• Requires downstream repository changes
• Requires infrastructure/deployment changes
• Requires coordination with other teams
• Blocked by PR/MR: #XXX

Screenshots/Logs

Module output example:

{
  "id": 1,
  "name": "FEATURE_EXAMPLE_ENABLED",
  "ui_name": "Example Feature",
  "condition": "boolean",
  "value": "True",
  "toggle_type": "run-time",
  "description": "Enables example functionality",
  "changed": true
}

[github-actions]

DVCS PR Check Results:

PR appears valid (JIRA key(s) found)

[fao89]

@rohitthakur2590 could you please merge?