Add comprehensive AAP 2.6 components reference and advanced configuration

.claude/skills

@@ -0,0 +1 @@
+../.cursor/skills

aap-deploy/README.md

@@ -83,9 +83,14 @@ Solid lines denote active production paths on Site 1. The dashed link is the sta
 
 Create an opaque `Secret` in the **AAP namespace** with keys expected by the AAP Operator for **unmanaged** PostgreSQL. See [`openshift/postgres-configuration-secret.example.yaml`](openshift/postgres-configuration-secret.example.yaml) for a structural template (replace all placeholders; do not commit real credentials).
 
-Reference the secret from the **`AutomationController`** (and any other component that uses Postgres, e.g. **Automation Hub**) via:
+Reference the secrets from the **`AnsibleAutomationPlatform`** parent CR:
 
-`spec.postgres_configuration_secret: <secret-name>`
+- Gateway: `spec.database.database_secret: <gateway-secret-name>`
+- Controller: `spec.controller.postgres_configuration_secret: <controller-secret-name>`
+- Hub: `spec.hub.postgres_configuration_secret: <hub-secret-name>`
+- EDA: `spec.eda.database.database_secret: <eda-secret-name>`
+
+See `openshift/ansibleautomationplatform.yaml` for the complete example.
 
 Exact CRD field names can vary slightly by AAP release; confirm in your version’s “Installing on OpenShift” / customization guide.
 
@@ -161,6 +166,8 @@ To install **AAP 2.6** with the operator on **one** OpenShift cluster and use **
 
 Adjust `spec.hub.file_storage_storage_class` to a **ReadWriteMany** `StorageClass` before or after apply.
 
+**What gets deployed:** The default configuration deploys the complete AAP 2.6 platform including Platform Gateway, Automation Controller, Automation Hub, and Event-Driven Ansible. See the **[AAP Deployment Reference](../docs/aap-components-reference.md)** for deployment configuration, database setup, verification procedures, and troubleshooting. For component capabilities and usage, see [Red Hat AAP 2.6 Documentation](https://docs.redhat.com/en/documentation/red_hat_ansible_automation_platform/2.6).
+
 ## 9. Layout of this folder
 
 | Path | Purpose |

aap-deploy/openshift/README.md

@@ -2,6 +2,8 @@
 
 This flow installs the **Ansible Automation Platform operator** (`stable-2.6`) and an **`AnsibleAutomationPlatform`** instance that uses the CloudNativePG / EDB **`postgresql`** read-write Service **`postgresql-rw.edb-postgres.svc.cluster.local`** (adjust if you use different namespace or `Cluster` names) as a single PostgreSQL server with **four databases** (gateway, controller, hub, EDA).
 
+**What gets deployed:** This configuration deploys the complete AAP 2.6 platform including Platform Gateway, Automation Controller, Automation Hub, and Event-Driven Ansible. For deployment-specific configuration, verification, and troubleshooting, see the **[AAP Deployment Reference](../../docs/aap-components-reference.md)**. For component capabilities and features, see [Red Hat AAP 2.6 Documentation](https://docs.redhat.com/en/documentation/red_hat_ansible_automation_platform/2.6).
+
 Confirm fields and prerequisites in [Installing on OpenShift Container Platform 2.6](https://docs.redhat.com/en/documentation/red_hat_ansible_automation_platform/2.6/html-single/installing_on_openshift_container_platform/index).
 
 ## Prerequisites
@@ -81,11 +83,26 @@ oc get routes -n ansible-automation-platform
 | File | Purpose |
 |------|---------|
 | `kustomization.yaml` | Namespace, `OperatorGroup`, `Subscription` |
-| `ansibleautomationplatform.yaml` | Parent CR with external DB secret refs |
+| `ansibleautomationplatform.yaml` | Basic parent CR with external DB secret refs (recommended starting point) |
+| `ansibleautomationplatform-advanced.yaml` | Advanced CR example with HA, scaling, and resource tuning options |
 | `scripts/generate-postgres-secrets.sh` | Prints four `Secret` manifests |
 | `postgres-configuration-secret.example.yaml` | Optional single-secret structural template (placeholders; most flows use the generator script above) |
 | `../edb-bootstrap/create-aap-databases.sql` | Reference SQL (edit password before use) |
 
 ## Private CA (optional)
 
 If the controller must trust a custom CA for Postgres TLS, create **`bundle-ca.crt`** in a Secret and set **`spec.bundle_cacert_secret`** on `AnsibleAutomationPlatform` per product docs.
+
+## Component information
+
+This deployment includes all four AAP 2.6 components:
+
+- **Platform Gateway**: Unified authentication and UI
+- **Automation Controller**: Job execution and workflow orchestration
+- **Automation Hub**: Content management and collection distribution
+- **Event-Driven Ansible (EDA)**: Event-driven automation
+
+**Documentation:**
+
+- **Deployment reference** (database setup, verification, troubleshooting): [AAP Deployment Reference](../../docs/aap-components-reference.md)
+- **Component capabilities and usage**: [Red Hat AAP 2.6 Documentation](https://docs.redhat.com/en/documentation/red_hat_ansible_automation_platform/2.6)

aap-deploy/openshift/ansibleautomationplatform-advanced.yaml

@@ -0,0 +1,228 @@
+# Advanced configuration example for AAP 2.6 AnsibleAutomationPlatform CR
+# This file demonstrates additional configuration options beyond the basic deployment.
+# For basic deployment, use ansibleautomationplatform.yaml in this directory.
+# For complete component documentation, see: docs/aap-components-guide.md
+
+apiVersion: aap.ansible.com/v1alpha1
+kind: AnsibleAutomationPlatform
+metadata:
+  name: aap
+  namespace: ansible-automation-platform
+spec:
+  # ==================================================================================
+  # PLATFORM GATEWAY - Unified authentication and UI
+  # ==================================================================================
+  database:
+    database_secret: external-postgres-configuration-gateway
+
+  # Optional gateway settings
+  # service_type: ClusterIP              # Default: ClusterIP (use LoadBalancer for external LB)
+  # route_tls_termination_mechanism: Edge  # Default: Edge (options: Edge, Passthrough)
+  # ingress_type: Route                   # Default: Route (OpenShift); use Ingress for vanilla K8s
+
+  # ==================================================================================
+  # AUTOMATION CONTROLLER - Job execution and workflow orchestration
+  # ==================================================================================
+  controller:
+    postgres_configuration_secret: external-postgres-configuration-controller
+
+    # High-availability configuration
+    replicas: 2                          # Number of web/API pods (increase for HA)
+    task_replicas: 4                     # Number of job executor pods (increase for concurrency)
+
+    # Resource limits for web pods
+    web_resource_requirements:
+      requests:
+        cpu: "2000m"
+        memory: "4Gi"
+      limits:
+        cpu: "4000m"
+        memory: "8Gi"
+
+    # Resource limits for task pods (job executors)
+    task_resource_requirements:
+      requests:
+        cpu: "1000m"
+        memory: "2Gi"
+      limits:
+        cpu: "2000m"
+        memory: "4Gi"
+
+    # Execution environment (EE) image pull credentials
+    # ee_extra_env: |
+    #   - name: MY_CUSTOM_ENV_VAR
+    #     value: "custom-value"
+
+    # Node affinity (schedule pods on specific nodes)
+    # node_selector: |
+    #   node-role.kubernetes.io/worker: ""
+
+    # Tolerations for tainted nodes
+    # task_tolerations: |
+    #   - key: "dedicated"
+    #     operator: "Equal"
+    #     value: "automation"
+    #     effect: "NoSchedule"
+
+  # ==================================================================================
+  # AUTOMATION HUB - Content management and distribution
+  # ==================================================================================
+  hub:
+    # Storage configuration (REQUIRED - must be ReadWriteMany)
+    storage_type: file                                      # Options: file, s3, azure
+    file_storage_storage_class: ocs-storagecluster-cephfs   # MUST be RWX-capable
+    file_storage_size: 10Gi                                 # Adjust based on collection count
+
+    # Database configuration
+    postgres_configuration_secret: external-postgres-configuration-hub
+
+    # High-availability configuration
+    replicas: 2                          # Number of Hub API pods
+
+    # Resource limits
+    resource_requirements:
+      requests:
+        cpu: "1000m"
+        memory: "2Gi"
+      limits:
+        cpu: "2000m"
+        memory: "4Gi"
+
+    # Worker configuration (for async tasks like collection sync)
+    # worker_replicas: 2
+    # worker_resource_requirements:
+    #   requests:
+    #     cpu: "500m"
+    #     memory: "1Gi"
+    #   limits:
+    #     cpu: "1000m"
+    #     memory: "2Gi"
+
+    # Node affinity
+    # node_selector: |
+    #   node-role.kubernetes.io/worker: ""
+
+  # ==================================================================================
+  # Alternative Hub configuration with S3 storage (instead of file storage)
+  # ==================================================================================
+  # hub:
+  #   storage_type: s3
+  #   object_storage_s3_secret: hub-s3-credentials  # Secret with S3 credentials
+  #   postgres_configuration_secret: external-postgres-configuration-hub
+  #   replicas: 2
+  #
+  # Required keys in hub-s3-credentials secret:
+  # - s3-access-key-id
+  # - s3-secret-access-key
+  # - s3-bucket-name
+  # - s3-region
+  # - s3-endpoint (optional, for non-AWS S3-compatible storage)
+
+  # ==================================================================================
+  # EVENT-DRIVEN ANSIBLE (EDA) - Event-driven automation
+  # ==================================================================================
+  eda:
+    database:
+      database_secret: external-postgres-configuration-eda
+
+    # High-availability configuration
+    replicas: 2                          # Number of EDA API pods
+    worker_replicas: 5                   # Number of event processing workers
+
+    # Resource limits for API pods
+    resource_requirements:
+      requests:
+        cpu: "500m"
+        memory: "1Gi"
+      limits:
+        cpu: "2000m"
+        memory: "2Gi"
+
+    # Resource limits for worker pods
+    # worker_resource_requirements:
+    #   requests:
+    #     cpu: "500m"
+    #     memory: "1Gi"
+    #   limits:
+    #     cpu: "1000m"
+    #     memory: "2Gi"
+
+    # Controller integration (auto-configured via gateway, override if needed)
+    # automation_server_url: https://controller.example.com
+
+    # Node affinity
+    # node_selector: |
+    #   node-role.kubernetes.io/worker: ""
+
+  # ==================================================================================
+  # PLATFORM-WIDE SETTINGS
+  # ==================================================================================
+
+  # TLS/SSL custom CA bundle (optional)
+  # If your PostgreSQL server uses a custom CA, create a secret with "bundle-ca.crt" key
+  # bundle_cacert_secret: custom-ca-bundle
+
+  # Image pull secrets (for private container registries)
+  # image_pull_secrets:
+  #   - private-registry-credentials
+
+  # Platform-wide idle mode (scale all components to zero)
+  # Use this for maintenance windows or DR site standby mode
+  # idle_aap: false                      # Set to true to scale down all components
+
+  # Service account (operator creates one by default; override if needed)
+  # service_account_name: aap-custom-sa
+
+  # ==================================================================================
+  # CSRF SETTINGS (for external ingress, non-OpenShift Route scenarios)
+  # ==================================================================================
+  # If using external ingress/load balancer instead of OpenShift Routes:
+  # csrf_trusted_origins:
+  #   - https://aap.example.com
+  #   - https://gateway.example.com
+
+  # ==================================================================================
+  # ADDITIONAL ADVANCED OPTIONS
+  # ==================================================================================
+
+  # Garbage collection for old job artifacts
+  # controller:
+  #   garbage_collect_secrets: true
+
+  # LDAP/SAML/OAuth integration (configure via Controller UI or API, not CR)
+  # See AAP documentation for authentication configuration
+
+  # Route/Ingress annotations (platform-wide)
+  # route_annotations: |
+  #   haproxy.router.openshift.io/timeout: 2m
+
+  # Security context (for compliance or restricted environments)
+  # security_context_settings:
+  #   runAsUser: 1000
+  #   runAsGroup: 1000
+  #   fsGroup: 1000
+
+# ==================================================================================
+# NOTES
+# ==================================================================================
+#
+# 1. Resource sizing guidelines:
+#    - Small deployment (< 100 jobs/day): Use default resource requests
+#    - Medium deployment (100-500 jobs/day): 2x resources on controller tasks
+#    - Large deployment (> 500 jobs/day): 4x+ resources, consider horizontal scaling
+#
+# 2. Hub storage sizing:
+#    - Small (< 100 collections): 10-20Gi
+#    - Medium (100-500 collections): 50-100Gi
+#    - Large (> 500 collections, multiple EEs): 200Gi+
+#
+# 3. EDA worker scaling:
+#    - Base (< 10 active rulebooks): 2 workers
+#    - Medium (10-50 active rulebooks): 5 workers
+#    - High (> 50 active rulebooks): 10+ workers
+#
+# 4. For detailed component documentation, verification procedures, and
+#    troubleshooting, see: docs/aap-components-guide.md
+#
+# 5. Official AAP documentation:
+#    https://docs.redhat.com/en/documentation/red_hat_ansible_automation_platform/2.6

aap-deploy/openshift/postgres-configuration-secret.example.yaml

@@ -1,5 +1,10 @@
 # Example structure for an external (unmanaged) PostgreSQL secret used by the
-# Ansible Automation Platform operator (AutomationController / related CRs).
+# Ansible Automation Platform operator (AnsibleAutomationPlatform parent CR).
+# In AAP 2.6, secrets are referenced through the parent CR's spec fields:
+# - spec.database.database_secret (Gateway)
+# - spec.controller.postgres_configuration_secret (Controller)
+# - spec.hub.postgres_configuration_secret (Hub)
+# - spec.eda.database.database_secret (EDA)
 #
 # - Replace all REPLACE_* values; do not commit real credentials.
 # - Confirm key names and allowed sslmode values in Red Hat documentation for your AAP version.
@@ -19,6 +24,5 @@ stringData:
   username: aap_db_user
   password: aap_db_password
   sslmode: prefer
-  # Use read-write targeting when pointing at a primary; adjust if your topology requires it.
-  target_session_attrs: read-write
+  target_session_attrs: read-write  # Ensures connection to primary (not replica)
   type: unmanaged

aap-deploy/openshift/scripts/generate-postgres-secrets.sh

@@ -34,7 +34,7 @@ stringData:
   username: $PGUSER
   password: $PASS
   sslmode: $SSLMODE
-  target_session_attrs: read-write
+  target_session_attrs: read-write  # Ensures connection to primary (not replica)
   type: unmanaged
 ---
 EOF

docs/INDEX.md

@@ -47,6 +47,7 @@
 - [EDB Operator Installation](../db-deploy/olm-openshift/README.md) - CloudNativePG operator via OLM
 - [Cross-Cluster Replication](../db-deploy/cross-cluster/README.md) - DC1 → DC2 streaming replication
 - [AAP OpenShift Manifests](../aap-deploy/openshift/README.md) - Subscription and AnsibleAutomationPlatform CR
+- [AAP Deployment Reference](aap-components-reference.md) ⭐ **NEW** - Database setup, verification, troubleshooting (Gateway, Controller, Hub, EDA)
 - [EDB Operator Smoke Test](openshift-edb-operator-smoke-test.md) - Validation procedures
 
 ---
@@ -119,6 +120,7 @@ Choose based on your requirements:
 **Day-to-day operations:**
 
 - **[Operations Runbook](manual-scripts-doc.md)** - AAP cluster management procedures
+- **[AAP Deployment Reference](aap-components-reference.md)** ⭐ **NEW** - Deployment verification, troubleshooting, scaling
 - **[Script Reference](../scripts/README.md)** - All automation scripts documented
 - **[Troubleshooting Guide](troubleshooting.md)** - Common issues and diagnostics
 - **[EDB Failover Manager](enterprisefailovermanager.md)** - EFM integration and VIP management
@@ -286,10 +288,11 @@ Choose based on your requirements:
 ### 🎯 Application Developers
 
 **Essential Reading:**
-1. [AAP Deployment](../aap-deploy/README.md) - AAP usage and integration
-2. [Troubleshooting Guide](troubleshooting.md) - Common issues
-3. [Main README](../README.md) - System architecture
-4. [OpenShift AAP Architecture](openshift-aap-architecture.md) - Platform overview
+1. [AAP Deployment Reference](aap-components-reference.md) - Deployment verification and troubleshooting
+2. [AAP Deployment](../aap-deploy/README.md) - AAP usage and integration
+3. [Red Hat AAP Documentation](https://docs.redhat.com/en/documentation/red_hat_ansible_automation_platform/2.6) - Component capabilities and features
+4. [Troubleshooting Guide](troubleshooting.md) - Common issues
+5. [Main README](../README.md) - System architecture
 
 ---
 
@@ -313,6 +316,7 @@ Choose based on your requirements:
 - ✅ Scripts Library Reference (2026-04-03)
 - ✅ Scripts Hooks and CI/CD Guide (2026-04-03)
 - ✅ Scripts README reorganization (2026-04-03)
+- ✅ AAP Deployment Reference (2026-04-03) - Deployment-specific configuration and troubleshooting
 
 **Next Documentation Priorities:**
 1. Security Hardening Guide (Week 2)