Merge pull request #142 from openshift-online/docs-remove-redundant

remove redundant docs

Author: openshift-merge-bot[bot]

README.md

@@ -1,5 +1,7 @@
 # rosa-regional-platform
 
+For the full architecture overview, see [docs/README.md](docs/README.md).
+
 ## Repository Structure
 
 ```
@@ -10,7 +12,7 @@ rosa-regional-platform/
 │       ├── management-cluster/       # Management cluster application templates
 │       ├── regional-cluster/         # Regional cluster application templates
 │       └── shared/                   # Shared configurations (ArgoCD, etc.)
-├── ci/                               # CI automation (janitor, etc.)
+├── ci/                               # CI automation (e2e tests, janitor)
 ├── deploy/                           # Per-environment deployment configs
 ├── docs/                             # Design documents and presentations
 ├── hack/                             # Developer utility scripts
@@ -22,30 +24,20 @@ rosa-regional-platform/
 
 ## Getting Started
 
-### Cluster Provisioning
+### Pipeline-Based Provisioning (CI/CD)
 
-Quick start (regional cluster):
+This is the standard way to provision a region. A central AWS account hosts CodePipelines that automatically provision Regional and Management Clusters when configuration is committed to Git.
 
-```bash
-# One-time setup: Copy and edit configurations
-cp terraform/config/regional-cluster/terraform.tfvars.example \
-   terraform/config/regional-cluster/terraform.tfvars
+See [Provision a New Central Pipeline](docs/central-pipeline-provisioning.md) for the full walkthrough.
 
-# Provision complete regional cluster environment based on the .tfvars file
-make provision-regional
-```
+### Local Provisioning (Development)
 
-Quick start (management cluster):
+> **Note:** Local provisioning is intended for development and debugging only. Prefer the pipeline-based approach above.
 
-```bash
-# One-time setup: Copy and edit configurations
-cp terraform/config/management-cluster/terraform.tfvars.example \
-   terraform/config/management-cluster/terraform.tfvars
+For manual provisioning using `make` targets and local `.tfvars` files, see [Local Region Provisioning](docs/full-region-provisioning.md). For all available `make` targets, run `make help`.
 
-# Provision complete management cluster environment based on the .tfvars file
-make provision-management
-```
+## CI
 
-### Available Make Targets
+CI is managed through the [OpenShift CI](https://docs.ci.openshift.org/) system (Prow + ci-operator). The job configuration lives in [openshift/release](https://github.com/openshift/release/tree/master/ci-operator/config/openshift-online/rosa-regional-platform).
 
-For all `make` targets, see `make help`.
+For the list of jobs, how to trigger them, AWS credentials setup, and local execution, see [ci/README.md](ci/README.md).

argocd/README.md

@@ -119,17 +119,6 @@ The ApplicationSet will automatically discover and deploy new charts. Run `./scr
 
 ## How It Works
 
-ArgoCD uses a **Matrix Generator** pattern with two generators:
+ArgoCD uses a **Matrix Generator** pattern combining a Git Generator (discovers Helm charts) with a Cluster Generator (reads cluster identity). Charts are sourced from either a pinned commit hash or the current git revision, while rendered values always come from the latest revision.
 
-- **Git Generator**: Discovers Helm charts by scanning `argocd/config/{cluster_type}/*` and `argocd/config/shared/*`
-- **Cluster Generator**: Uses cluster secrets created during EKS provisioning (contains cluster identity: cluster_type, environment, region)
-
-The Git Generator gets either:
-
-- **Pinned commit hash** (when `config_revision` specified) for snapshotted charts
-- **Current git_revision** (when no `config_revision`) for live charts
-
-**Application Sources:**
-
-- **Charts & Default Values**: From `argocd/config/` at pinned commit OR current git_revision
-- **Rendered Values**: From `deploy/<env>/<region_deployment>/argocd/` at current git_revision (always latest environment config)
+For the full architecture, alternatives considered, and implementation details, see [GitOps Cluster Configuration](../docs/design/gitops-cluster-configuration.md).

argocd/config/regional-cluster/hyperfleet-system/README.md

@@ -156,102 +156,16 @@ helm install hyperfleet-system ./argocd/config/regional-cluster/hyperfleet-syste
   --namespace hyperfleet-system
 ```
 
-## AWS Infrastructure Setup (Production Mode)
+## AWS Infrastructure Setup
 
-### Prerequisites
-
-Before deploying HyperFleet in production mode, provision AWS infrastructure using Terraform:
+Before deploying HyperFleet, provision the underlying AWS infrastructure (RDS, Amazon MQ, Secrets Manager, IAM roles) using Terraform. See the [HyperFleet Infrastructure module](../../../../terraform/modules/hyperfleet-infrastructure/README.md) for full details on resources created, configuration options, cost estimates, and troubleshooting.
 
 ```bash
 cd terraform/config/regional-cluster
-
-# Apply HyperFleet infrastructure module
 terraform apply
 ```
 
-This creates:
-
-- **Amazon RDS PostgreSQL** (db.t4g.micro for dev, configurable)
-- **Amazon MQ RabbitMQ** (mq.t3.micro for dev, configurable)
-- **AWS Secrets Manager** secrets (db-credentials, mq-credentials)
-- **IAM Roles** with Pod Identity associations (3 roles: API, Sentinel, Adapter)
-- **Security Groups** for RDS and Amazon MQ access from EKS
-
-### How Pod Identity Works
-
-1. **Service Account Annotation**: Each pod's service account is annotated with an IAM role ARN:
-
-   ```yaml
-   annotations:
-     eks.amazonaws.com/role-arn: arn:aws:iam::ACCOUNT:role/hyperfleet-api
-   ```
-
-2. **Pod Identity Agent**: EKS Pod Identity agent authenticates the pod to AWS using the role
-
-3. **SecretProviderClass**: AWS Secrets and Configuration Provider (ASCP) CSI driver mounts secrets:
-
-   ```yaml
-   apiVersion: secrets-store.csi.x-k8s.io/v1
-   kind: SecretProviderClass
-   spec:
-     provider: aws
-     parameters:
-       usePodIdentity: "true"
-       region: us-east-2
-       objects: |
-         - objectName: "hyperfleet/db-credentials"
-           objectType: "secretsmanager"
-   ```
-
-4. **Secret Mounting**: Secrets mounted at `/mnt/secrets-store/` contain credentials
-
-5. **Kubernetes Secret Creation**: SecretProviderClass also creates Kubernetes Secrets for environment variables:
-
-   ```yaml
-   secretObjects:
-     - secretName: hyperfleet-api-db-secret
-       type: Opaque
-       data:
-         - objectName: db.host
-           key: DB_HOST
-   ```
-
-6. **Application Access**: Pods read connection details via:
-   - **API**: Command-line flags pointing to mounted secret files (`--db-host-file=/mnt/secrets-store/db.host`)
-   - **Sentinel/Adapter**: Environment variable `BROKER_RABBITMQ_URL` from Kubernetes Secret
-
-### AWS Secrets Format
-
-**Database Secret** (`hyperfleet/db-credentials`):
-
-```json
-{
-  "username": "hyperfleet_admin",
-  "password": "GENERATED_PASSWORD",
-  "host": "rds-endpoint.us-east-2.rds.amazonaws.com",
-  "port": "5432",
-  "database": "hyperfleet"
-}
-```
-
-**Message Queue Secret** (`hyperfleet/mq-credentials`):
-
-```json
-{
-  "username": "hyperfleet_admin",
-  "password": "GENERATED_PASSWORD",
-  "host": "b-xxxxx.mq.us-east-2.on.aws",
-  "port": "5671",
-  "url": "amqps://hyperfleet_admin:PASSWORD@b-xxxxx.mq.us-east-2.on.aws:5671"
-}
-```
-
-**Important**: Passwords are URL-encoded in the `url` field to handle special characters.
-
-## Dependencies
-
-- **AWS Secrets and Configuration Provider (ASCP)** CSI driver (installed on EKS cluster)
-- **AWS Infrastructure** (RDS, Amazon MQ, Secrets Manager, IAM roles) provisioned via Terraform
+The ASCP CSI driver must be installed on the EKS cluster for Pod Identity secret mounting.
 
 ## Verification
 
@@ -342,70 +256,10 @@ kubectl get namespaces | grep test-cluster
 
 ## Production Considerations
 
-Before deploying to production:
-
-1. **Provision AWS Infrastructure**:
-   - Run Terraform to create RDS, Amazon MQ, IAM roles, and secrets
-   - Use appropriate instance sizes (not dev tier):
-     - RDS: `db.t4g.large` or higher
-     - Amazon MQ: `mq.m5.large` or higher with Multi-AZ deployment
-   - Enable deletion protection and automated backups
-
-2. **Configure Pod Identity Role ARNs**:
-   - Add role ARNs to `config.yaml` for your region deployment:
-
-   ```yaml
-   values:
-     regional-cluster:
-       hyperfleet-system:
-         hyperfleetApi:
-           aws:
-             podIdentity:
-               roleArn: "arn:aws:iam::ACCOUNT:role/hyperfleet-api"
-         hyperfleetSentinel:
-           aws:
-             podIdentity:
-               roleArn: "arn:aws:iam::ACCOUNT:role/hyperfleet-sentinel"
-         hyperfleetAdapter:
-           aws:
-             podIdentity:
-               roleArn: "arn:aws:iam::ACCOUNT:role/hyperfleet-adapter"
-   ```
-
-3. **Use Specific Image Tags**:
-
-   ```yaml
-   hyperfleetApi:
-     image:
-       tag: "v1.0.0" # Not "latest"
-   ```
-
-4. **Enable Multi-AZ for High Availability**:
-   - RDS: Set `db_multi_az = true` in Terraform
-   - Amazon MQ: Set `mq_deployment_mode = "CLUSTER_MULTI_AZ"` in Terraform
-
-5. **Enable Monitoring**:
-   - CloudWatch metrics for RDS (CPU, connections, storage)
-   - CloudWatch metrics for Amazon MQ (CPU, heap usage, queue depth)
-   - Set up CloudWatch alarms for critical thresholds
-
-6. **Configure Resource Limits** based on observed usage:
-
-   ```yaml
-   hyperfleetApi:
-     resources:
-       limits:
-         cpu: 1000m
-         memory: 1Gi
-       requests:
-         cpu: 500m
-         memory: 512Mi
-   ```
-
-7. **Secure Network Access**:
-   - RDS and Amazon MQ are VPC-only (no public access)
-   - Security groups restrict access to EKS cluster only
-   - TLS/SSL enforced for all connections (RDS: `sslMode=require`, MQ: AMQPS port 5671)
+1. **Provision AWS Infrastructure** with production-tier settings — see [HyperFleet Infrastructure module](../../../../terraform/modules/hyperfleet-infrastructure/README.md) for recommended instance sizes, Multi-AZ, and monitoring setup
+2. **Configure Pod Identity Role ARNs** in `config.yaml` for your region deployment (role ARNs come from Terraform outputs)
+3. **Use specific image tags** (not `latest`)
+4. **Configure resource limits** based on observed usage
 
 ## Deployment Notes
 
@@ -553,4 +407,4 @@ curl http://localhost:8000/api/hyperfleet/v1/clusters
 
 ## Related Documentation
 
-- **Terraform Infrastructure Module**: `terraform/modules/hyperfleet-infrastructure/README.md`
+- **Terraform Infrastructure Module**: [terraform/modules/hyperfleet-infrastructure/README.md](../../../../terraform/modules/hyperfleet-infrastructure/README.md)

ci/README.md

@@ -1,8 +1,25 @@
 # CI
 
+CI is managed through the [OpenShift CI](https://docs.ci.openshift.org/) system (Prow + ci-operator). The job configuration lives in [openshift/release](https://github.com/openshift/release/tree/master/ci-operator/config/openshift-online/rosa-regional-platform).
+
+## Jobs
+
+| Job                                                                                                                                                                                       | Schedule                  | Description                                                                                                    |
+| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| [`terraform-validate`](https://prow.ci.openshift.org/job-history/gs/test-platform-results/pr-logs/directory/pull-ci-openshift-online-rosa-regional-platform-main-terraform-validate)      | Pre-submit                | Runs `terraform validate` on all root modules                                                                  |
+| [`helm-lint`](https://prow.ci.openshift.org/job-history/gs/test-platform-results/pr-logs/directory/pull-ci-openshift-online-rosa-regional-platform-main-helm-lint)                        | Pre-submit                | Lints Helm charts                                                                                              |
+| [`check-rendered-files`](https://prow.ci.openshift.org/job-history/gs/test-platform-results/pr-logs/directory/pull-ci-openshift-online-rosa-regional-platform-main-check-rendered-files)  | Pre-submit                | Verifies rendered deploy files are up to date                                                                  |
+| [`on-demand-e2e`](https://prow.ci.openshift.org/job-history/gs/test-platform-results/pr-logs/directory/pull-ci-openshift-online-rosa-regional-platform-main-on-demand-e2e)                | Pre-submit (manual)       | Full e2e: provisions ephemeral environment, runs tests, tears down. Trigger with `/test on-demand-e2e` on a PR |
+| [`nightly`](https://prow.ci.openshift.org/job-history/gs/test-platform-results/logs/periodic-ci-openshift-online-rosa-regional-platform-main-nightly)                                     | Daily at 07:00 UTC        | End-to-end provisioning and test suite against `main`                                                          |
+| [`nightly-resources-janitor`](https://prow.ci.openshift.org/job-history/gs/test-platform-results/logs/periodic-ci-openshift-online-rosa-regional-platform-main-nightly-resources-janitor) | Weekly (Sunday 12:00 UTC) | Purges leaked AWS resources using [aws-nuke](https://github.com/ekristen/aws-nuke)                             |
+
+## Build Image
+
+The CI image is built from [ci/Containerfile](ci/Containerfile) and includes all required tools (Terraform, Helm, AWS CLI, Python/uv, etc.).
+
 ## Pre-merge / Ephemeral Environment
 
-The `ci/pre-merge.py` script manages ephemeral environments for CI testing. It supports two modes — provision and teardown — designed to run as separate CI steps with tests in between.
+The [ci/pre-merge.py](ci/pre-merge.py) script manages ephemeral environments for CI testing. It supports two modes — provision and teardown — designed to run as separate CI steps with tests in between.
 
 1. Creates a CI-owned git branch from the source repo/branch
 2. Bootstraps the pipeline-provisioner pointing at the CI branch
@@ -69,15 +86,12 @@ Logs are saved to `codebuild-logs-<ci-prefix>/`. The same download logic is used
 The e2e job uses three sets of AWS credentials (central, regional, and management accounts).
 
 Credentials are stored in Vault at `kv/selfservice/cluster-secrets-rosa-regional-platform-int/nightly-static-aws-credentials` and mounted at `/var/run/rosa-credentials/` with keys:
+
 - `ci_access_key`, `ci_secret_key`, `ci_assume_role_arn` — Central account (base credentials + AssumeRole)
 - `regional_access_key`, `regional_secret_key` — Regional sub-account
 - `management_access_key`, `management_secret_key` — Management sub-account
 - `github_token` — GitHub token with push access for creating CI branches
 
-### Where things are defined
-
-- **CI job config**: [`openshift/release` — `ci-operator/config/openshift-online/rosa-regional-platform/`](https://github.com/openshift/release/tree/master/ci-operator/config/openshift-online/rosa-regional-platform)
-
 ## Nightly Resources Janitor
 
 The e2e tests create AWS resources across multiple accounts. Teardown relies on `terraform destroy`, which can fail and leak resources. The **nightly-resources-janitor** job is a weekly fallback that purges everything except resources we need to keep between tests using [aws-nuke](https://github.com/ekristen/aws-nuke).
@@ -97,7 +111,3 @@ See `./ci/aws-nuke-config.yaml`.
 ```
 
 The script uses whatever AWS credentials are active in your environment. The account must be in the allowlist in `purge-aws-account.sh`.
-
-## Test Results
-
-Results are available on the [OpenShift CI Prow dashboard](https://prow.ci.openshift.org/?job=periodic-ci-openshift-online-rosa-regional-platform-main-nightly).