From 048c1f3e584bee5d122aa916f40686b2834402e7 Mon Sep 17 00:00:00 2001 From: Chai Bot Date: Fri, 10 Jul 2026 03:20:45 +0000 Subject: [PATCH] [docs-agent] Fix stale naming, missing entries, and ASCII diagrams --- CLAUDE.md | 21 ++-- README.md | 32 +++++-- docs/README.md | 36 ++++--- docs/architecture/ARCHITECTURE.md | 153 ++++++++++++------------------ docs/guides/DEVELOPMENT.md | 39 +++++++- docs/guides/DOCUMENTATION.md | 84 +++++++++++----- docs/guides/VERSIONING.md | 20 ++-- docs/specs/reference-gist-1.md | 76 ++++++++------- docs/specs/references.md | 23 +++-- 9 files changed, 279 insertions(+), 205 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 53d2987..03ebe33 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -6,15 +6,18 @@ CLI tool (`rosactl`) for managing AWS infrastructure (VPC, IAM, OIDC) for ROSA h ## Key Directories -| Path | Purpose | -|------|---------| -| `cmd/rosactl/` | Binary entry point | -| `internal/commands/` | Cobra CLI subcommands (clustervpc, clusteriam, bootstrap, handler, version) | -| `internal/services/` | Business logic shared by CLI commands and Lambda handler | -| `internal/aws/cloudformation/` | CloudFormation client and stack operations | -| `internal/cloudformation/templates/` | Embedded CloudFormation templates (go:embed) | -| `test/localstack/` | Integration tests against LocalStack | -| `docs/` | Architecture, guides, and specs | +| Path | Purpose | +| ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | +| `cmd/rosactl/` | Binary entry point | +| `internal/commands/` | Cobra CLI subcommands (bootstrap, cluster, clusteriam, clusteroidc, clustervpc, handler, login, version) | +| `internal/services/` | Business logic shared by CLI commands and Lambda handler | +| `internal/services/cluster/` | Cluster lifecycle service (create, list, get-token, kubeconfig) | +| `internal/services/clusteroidc/` | OIDC management service | +| `internal/aws/cloudformation/` | CloudFormation client and stack operations | +| `internal/cloudformation/templates/` | Embedded CloudFormation templates (go:embed) | +| `internal/cloudformation/templates/cluster-oidc.yaml` | OIDC CloudFormation template | +| `test/localstack/` | Integration tests against LocalStack | +| `docs/` | Architecture, guides, and specs | ## Commands diff --git a/README.md b/README.md index 6c78c27..fb95f58 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # rosactl -A command-line tool for ROSA Regional Platform +A command-line tool for ROSA HyperFleet Manages AWS infrastructure for ROSA hosted clusters including VPC networking, IAM roles, and OIDC providers via CloudFormation stacks. @@ -9,6 +9,7 @@ Manages AWS infrastructure for ROSA hosted clusters including VPC networking, IA ## Features ### Cluster Infrastructure Management + - **VPC Networking**: Create and manage VPCs, subnets, NAT gateways, and security groups for hosted clusters - **IAM Resources**: Create OIDC providers and IAM roles for cluster control plane and worker nodes - **CloudFormation-based**: All resources deployed via CloudFormation stacks for consistency and rollback support @@ -16,11 +17,13 @@ Manages AWS infrastructure for ROSA hosted clusters including VPC networking, IA - **Direct execution**: No Lambda bootstrap required for basic operations ### Optional Lambda Bootstrap + - **Container-based Lambda**: Deploy rosactl as a Lambda function for event-driven workflows - **Automated deployments**: Integrate with CI/CD pipelines and AWS event sources - **Same binary**: Lambda uses the same rosactl binary packaged in a container ### Developer Experience + - **Semantic versioning**: Automated version management with conventional commits - **LocalStack testing**: Integration tests against LocalStack for CloudFormation validation - **Clear error messages**: User-friendly error reporting with CloudFormation event details @@ -32,8 +35,8 @@ Manages AWS infrastructure for ROSA hosted clusters including VPC networking, IA ```bash # Clone the repository -git clone https://github.com/openshift-online/rosa-regional-platform-cli.git -cd rosa-regional-platform-cli +git clone https://github.com/openshift-online/rosa-hyperfleet-cli.git +cd rosa-hyperfleet-cli # Build make build @@ -129,6 +132,7 @@ rosactl cluster-vpc create my-cluster \ ``` **What this creates:** + - VPC with configurable CIDR block (default: 10.0.0.0/16) - 3 public subnets across availability zones - 3 private subnets across availability zones @@ -166,6 +170,7 @@ rosactl cluster-iam create my-cluster \ ``` **What this creates:** + 1. IAM OIDC Provider (with auto-fetched TLS thumbprint) 2. 7 control plane IAM roles: - Ingress Operator Role @@ -227,6 +232,7 @@ Once deployed, the Lambda function accepts JSON event payloads: ``` Supported `action` values: + - `apply-cluster-vpc` - Create or update VPC CloudFormation stack - `delete-cluster-vpc` - Delete VPC stack - `apply-cluster-iam` - Create or update IAM CloudFormation stack @@ -346,9 +352,6 @@ export LOCALSTACK_AUTH_TOKEN=your-token-here # LocalStack integration tests (CLI tests + Lambda handler invocation tests) make test-localstack -# Run with verbose output -make test-localstack-verbose - # Install test dependencies make test-deps ``` @@ -381,7 +384,7 @@ git push origin v0.2.0 ## Project Structure ``` -rosa-regional-platform-cli/ +rosa-hyperfleet-cli/ ├── cmd/rosactl/ # Entry point ├── internal/ │ ├── commands/ # CLI commands @@ -464,6 +467,7 @@ rosactl uses a consistent naming convention for CloudFormation stacks: - **IAM stacks**: `rosa-{cluster-name}-iam` All stacks are tagged with: + - `Cluster`: cluster name - `ManagedBy`: rosactl - `red-hat-managed`: true @@ -473,6 +477,7 @@ All stacks are tagged with: ### OIDC Thumbprint Auto-Fetch When creating IAM resources with `cluster-iam create`, rosactl automatically fetches the TLS thumbprint from the OIDC issuer URL. This requires: + - The OIDC issuer URL to be publicly accessible over HTTPS - Valid TLS certificate on the OIDC endpoint @@ -481,6 +486,7 @@ When creating IAM resources with `cluster-iam create`, rosactl automatically fet The `cluster-iam create` command creates the following IAM resources via CloudFormation: **Control Plane Roles** (7): + - Ingress Operator Role - Kube Controller Manager Role - EBS CSI Driver Operator Role @@ -490,6 +496,7 @@ The `cluster-iam create` command creates the following IAM resources via CloudFo - Node Pool Management Role **Worker Node Resources**: + - Worker IAM Role - Worker Instance Profile @@ -498,6 +505,7 @@ All roles use OIDC federation for authentication with minimal required permissio ### VPC Resources Created The `cluster-vpc create` command creates isolated networking resources: + - Dedicated VPC with configurable CIDR - Public and private subnets across 3 availability zones - NAT Gateway(s) for outbound internet access from private subnets @@ -522,11 +530,13 @@ When using the optional Lambda bootstrap feature, rosactl automatically creates ### Lambda OIDC RSA Private Keys When creating OIDC Lambdas (`--handler oidc`), the RSA private key is saved to: + ``` /tmp/oidc-private-key-{KEY_ID}.pem ``` **Security best practices:** + - File permissions are set to `0600` (owner read/write only) - Move the key to a secure location (e.g., AWS Secrets Manager) for production use - Delete from `/tmp` when no longer needed @@ -537,6 +547,7 @@ When creating OIDC Lambdas (`--handler oidc`), the RSA private key is saved to: ### Common Issues **"Stack already exists" (cluster-vpc or cluster-iam create)** + - The command automatically attempts to update the existing stack - Check the stack status in CloudFormation console - If stuck in a failed state, delete and recreate: @@ -546,11 +557,13 @@ When creating OIDC Lambdas (`--handler oidc`), the RSA private key is saved to: ``` **"Failed to fetch TLS thumbprint" (cluster-iam create)** + - Ensure the OIDC issuer URL is publicly accessible over HTTPS - Verify the TLS certificate is valid - Check network connectivity to the OIDC endpoint **"Insufficient permissions" (CloudFormation errors)** + - Ensure your AWS credentials have the required permissions listed in Prerequisites - Check CloudFormation stack events for specific permission errors: ```bash @@ -558,16 +571,19 @@ When creating OIDC Lambdas (`--handler oidc`), the RSA private key is saved to: ``` **"NAT Gateway creation timeout" (LocalStack testing)** + - This is expected in LocalStack as NAT Gateway support is limited - Tests accept both CREATE_COMPLETE and CREATE_FAILED status for LocalStack - Real AWS environments should succeed **"Lambda container execution fails" (LocalStack testing)** + - Lambda container execution requires LocalStack Pro - Set `LOCALSTACK_AUTH_TOKEN=your-token-here` before starting LocalStack - Or create a `.env` file in the project root with `LOCALSTACK_AUTH_TOKEN=your-token-here` **AWS Configuration** + ```bash # Set AWS profile export AWS_PROFILE=your-profile-name @@ -579,6 +595,7 @@ export AWS_REGION=us-east-1 ``` **"go-semver-release not found"** + ```bash go install github.com/s0ders/go-semver-release@latest ``` @@ -616,6 +633,7 @@ Apache License 2.0 ## Acknowledgments Built with: + - [Cobra](https://github.com/spf13/cobra) - CLI framework - [AWS SDK for Go v2](https://github.com/aws/aws-sdk-go-v2) - AWS integration - [Ginkgo](https://github.com/onsi/ginkgo) - Testing framework diff --git a/docs/README.md b/docs/README.md index 9f07ae1..d2a971b 100644 --- a/docs/README.md +++ b/docs/README.md @@ -4,12 +4,12 @@ Welcome to the rosactl documentation! This directory contains all project docume ## 📚 Quick Links -| What do you want to do? | Start here | -|--------------------------|------------| +| What do you want to do? | Start here | +| ------------------------------- | ------------------------------------------------------------ | | **Understand the architecture** | [architecture/ARCHITECTURE.md](architecture/ARCHITECTURE.md) | -| **Build and contribute** | [guides/DEVELOPMENT.md](guides/DEVELOPMENT.md) | -| **Manage versions** | [guides/VERSIONING.md](guides/VERSIONING.md) | -| **Run integration tests** | [../test/localstack/README.md](../test/localstack/README.md) | +| **Build and contribute** | [guides/DEVELOPMENT.md](guides/DEVELOPMENT.md) | +| **Manage versions** | [guides/VERSIONING.md](guides/VERSIONING.md) | +| **Run integration tests** | [../test/localstack/README.md](../test/localstack/README.md) | ## 📁 Documentation Structure @@ -30,7 +30,9 @@ docs/ ## 🏗️ Architecture Documentation ### [ARCHITECTURE.md](architecture/ARCHITECTURE.md) + Complete system architecture including: + - Direct CloudFormation management with optional Lambda - Managed OIDC architecture (Red Hat-hosted) - Dual-mode Go binary (CLI and Lambda) @@ -41,21 +43,27 @@ Complete system architecture including: ## 📖 User & Developer Guides ### [DEVELOPMENT.md](guides/DEVELOPMENT.md) + Developer setup and contribution guide: + - Local development environment setup - Build and test instructions - Code organization and patterns - Pull request workflow ### [VERSIONING.md](guides/VERSIONING.md) + Semantic versioning with conventional commits: + - How to use `make release` for version management - Conventional commit message format - Version bump rules (feat, fix, BREAKING CHANGE) - Release workflow ### [DOCUMENTATION.md](guides/DOCUMENTATION.md) + Documentation writing guidelines: + - Documentation standards and style - How to write effective docs - Examples and anti-patterns @@ -64,16 +72,16 @@ Documentation writing guidelines: ### Feature Specifications -| Document | Purpose | -|----------|---------| +| Document | Purpose | +| -------------------------------------------------- | ------------------------------------------ | | [LocalStack Testing](../test/localstack/README.md) | LocalStack integration testing with Ginkgo | ### References -| Document | Purpose | -|----------|---------| -| [reference-gist-1.md](specs/reference-gist-1.md) | Deep dive into OIDC/STS cross-account authentication in ROSA HCP | -| [references.md](specs/references.md) | External project references (hypershift, rosa, rosa-regional-platform-api) | +| Document | Purpose | +| ------------------------------------------------ | ------------------------------------------------------------------- | +| [reference-gist-1.md](specs/reference-gist-1.md) | Deep dive into OIDC/STS cross-account authentication in ROSA HCP | +| [references.md](specs/references.md) | External project references (hypershift, rosa, rosa-hyperfleet-api) | ## 🚀 Getting Started @@ -156,7 +164,7 @@ See [DOCUMENTATION.md](guides/DOCUMENTATION.md) for detailed guidelines. ### Markdown Style - Use ATX-style headers (`#` not underlines) -- Fenced code blocks with language hints (```bash not ```) +- Fenced code blocks with language hints (`bash not `) - Tables for comparisons and structured data - Emoji for visual categorization (📚 📁 🚀 etc.) @@ -172,8 +180,8 @@ See [DOCUMENTATION.md](guides/DOCUMENTATION.md) for detailed guidelines. - [Main README](../README.md) - Project README - [LocalStack Testing Guide](../test/localstack/README.md) - Integration testing guide - [Makefile](../Makefile) - Build targets and commands -- [GitHub Repository](https://github.com/openshift-online/rosa-regional-platform-cli) -- [ROSA Regional Platform Terraform](https://github.com/openshift-online/rosa-regional-platform) - Reference implementation +- [GitHub Repository](https://github.com/openshift-online/rosa-hyperfleet-cli) +- [ROSA HyperFleet Terraform](https://github.com/openshift-online/rosa-hyperfleet) - Reference implementation - [HyperShift](https://github.com/openshift/hypershift) - OIDC implementation reference --- diff --git a/docs/architecture/ARCHITECTURE.md b/docs/architecture/ARCHITECTURE.md index 8993d1b..1073800 100644 --- a/docs/architecture/ARCHITECTURE.md +++ b/docs/architecture/ARCHITECTURE.md @@ -2,7 +2,7 @@ ## Overview -`rosactl` is a command-line tool for managing AWS infrastructure for ROSA Regional HCP (Hosted Control Plane) clusters. It provides direct CloudFormation management for VPC networking and IAM resources, with optional Lambda support for event-driven workflows. +`rosactl` is a command-line tool for managing AWS infrastructure for ROSA HyperFleet (Hosted Control Plane) clusters. It provides direct CloudFormation management for VPC networking and IAM resources, with optional Lambda support for event-driven workflows. ## Architecture Principles @@ -18,100 +18,32 @@ ### Primary Mode: Direct CloudFormation -``` -┌─────────────────────────────────────────────────────────────────┐ -│ Customer Environment │ -│ │ -│ ┌──────────────┐ │ -│ │ Developer │ │ -│ │ Machine │ │ -│ └──────┬───────┘ │ -│ │ │ -│ │ 1. rosactl cluster-vpc create my-cluster │ -│ │ (CLI with embedded CloudFormation templates) │ -│ ▼ │ -│ ┌──────────────────────┐ │ -│ │ CloudFormation │ │ -│ │ Stack (VPC) │ │ -│ │ rosa-my-cluster-vpc │ │ -│ └──────────┬───────────┘ │ -│ │ Creates │ -│ ▼ │ -│ ┌─────────────────────────────────────────┐ │ -│ │ VPC Resources │ │ -│ │ - VPC (10.0.0.0/16) │ │ -│ │ - 3 Public + 3 Private Subnets │ │ -│ │ - Internet Gateway, NAT Gateway(s) │ │ -│ │ - Route Tables, Security Groups │ │ -│ │ - Route53 Private Hosted Zone │ │ -│ └─────────────────────────────────────────┘ │ -│ │ -│ │ │ -│ │ 2. rosactl cluster-iam create my-cluster │ -│ │ --oidc-issuer-url https://d1234.cloudfront... │ -│ ▼ │ -│ ┌──────────────────────┐ │ -│ │ CloudFormation │ │ -│ │ Stack (IAM) │ │ -│ │ rosa-my-cluster-iam │ │ -│ └──────────┬───────────┘ │ -│ │ Creates │ -│ ▼ │ -│ ┌─────────────────────────────────────────┐ │ -│ │ IAM Resources │ │ -│ │ - IAM OIDC Provider │ │ -│ │ - 7 Control Plane Roles │ │ -│ │ - Worker Node Role + Instance Profile │ │ -│ └─────────────────────────────────────────┘ │ -│ │ -└─────────────────────────────────────────────────────────────────┘ - -┌─────────────────────────────────────────────────────────────────┐ -│ Red Hat Management Cluster │ -│ │ -│ ┌──────────────────────────────────────┐ │ -│ │ OIDC Issuer Infrastructure │ │ -│ │ - CloudFront Distribution │ │ -│ │ - Private S3 Bucket + OAC │ │ -│ │ - HyperShift-managed RSA Keys │ │ -│ └──────────────────────────────────────┘ │ -│ │ -│ Customer's IAM OIDC Provider points here ──────────────────────┤ -│ (e.g., https://d1234.cloudfront.net/cluster-name) │ -└─────────────────────────────────────────────────────────────────┘ +```mermaid +flowchart TD + subgraph Customer["Customer Environment"] + Dev["Developer Machine"] + Dev -->|"1. rosactl cluster-vpc create my-cluster
(CLI with embedded CF templates)"| CFvpc["CloudFormation Stack (VPC)
rosa-my-cluster-vpc"] + CFvpc -->|Creates| VPC["VPC Resources
- VPC (10.0.0.0/16)
- 3 Public + 3 Private Subnets
- Internet Gateway, NAT Gateway(s)
- Route Tables, Security Groups
- Route53 Private Hosted Zone"] + Dev -->|"2. rosactl cluster-iam create my-cluster
--oidc-issuer-url https://d1234.cloudfront..."| CFiam["CloudFormation Stack (IAM)
rosa-my-cluster-iam"] + CFiam -->|Creates| IAM["IAM Resources
- IAM OIDC Provider
- 7 Control Plane Roles
- Worker Node Role + Instance Profile"] + end + + subgraph RedHat["Red Hat Management Cluster"] + OIDC["OIDC Issuer Infrastructure
- CloudFront Distribution
- Private S3 Bucket + OAC
- HyperShift-managed RSA Keys"] + end + + IAM -.->|"IAM OIDC Provider points here
(e.g., https://d1234.cloudfront.net/cluster-name)"| OIDC ``` ### Optional Mode: Lambda for Event-Driven Workflows Lambda bootstrap is **optional** and used for CI/CD integration or event-driven automation. The same rosactl binary runs as a Lambda function via the `handler` subcommand. -```text -┌──────────────┐ -│ AWS Event │ -│ Source │ -└──────┬───────┘ - │ JSON event payload - ▼ { "action": "apply-cluster-vpc", ... } -┌──────────────────────┐ -│ Lambda Function │ -│ (Container: rosactl)│ -│ CMD: ["handler"] │ -│ - Embedded Templates│ -│ - Same Binary │ -└──────────┬───────────┘ - │ delegates to service layer - ▼ -┌──────────────────────┐ -│ Service Layer │ -│ clustervpc / │ -│ clusteriam │ -└──────────┬───────────┘ - │ - ▼ -┌──────────────────────┐ -│ CloudFormation │ -│ Stacks (VPC + IAM) │ -└──────────────────────┘ +```mermaid +flowchart TD + Event["AWS Event Source"] -->|"JSON event payload
{ action: apply-cluster-vpc, ... }"| Lambda["Lambda Function
(Container: rosactl)
CMD: [handler]
Embedded Templates / Same Binary"] + Lambda -->|"delegates to service layer"| Service["Service Layer
clustervpc / clusteriam"] + Service --> CF["CloudFormation
Stacks (VPC + IAM)"] ``` ## Components @@ -121,16 +53,36 @@ Lambda bootstrap is **optional** and used for CI/CD integration or event-driven Command-line interface built with Cobra framework. **Cluster VPC Management**: + - `cluster-vpc create` - Create VPC networking via CloudFormation - `cluster-vpc delete` - Delete VPC stack - `cluster-vpc list` - List all VPC stacks **Cluster IAM Management**: + - `cluster-iam create` - Create IAM resources (OIDC provider + roles) - `cluster-iam delete` - Delete IAM stack - `cluster-iam list` - List all IAM stacks +**Cluster Lifecycle Management**: + +- `cluster create` - Create a ROSA HyperFleet cluster +- `cluster list` - List clusters +- `cluster get-token` - Get cluster authentication token +- `cluster kubeconfig` - Generate kubeconfig for cluster access + +**Cluster OIDC Management**: + +- `cluster-oidc create` - Create OIDC provider +- `cluster-oidc delete` - Delete OIDC provider +- `cluster-oidc list` - List OIDC providers + +**Authentication**: + +- `login` - Authenticate with the ROSA HyperFleet API + **Optional Lambda Bootstrap**: + - `bootstrap create` - Deploy Lambda container function via CloudFormation - `handler` - Start the Lambda handler runtime (used as container CMD, hidden from help) @@ -140,12 +92,15 @@ Shared business logic used by both CLI commands and the Lambda handler: - `internal/services/clustervpc` - `CreateVPC()` and `DeleteVPC()` functions - `internal/services/clusteriam` - `CreateIAM()` and `DeleteIAM()` functions +- `internal/services/cluster` - Cluster lifecycle operations (create, list, get-token, kubeconfig) +- `internal/services/clusteroidc` - OIDC provider management (create, delete, list) The service layer accepts request structs with AWS config, making the same logic available to CLI commands and Lambda event handling without duplication. ### CloudFormation Client Handles direct CloudFormation stack management including: + - Stack creation with parameters, tags, and capabilities - Stack updates with automatic fallback from create failures - Stack deletion with wait for completion @@ -155,6 +110,7 @@ Handles direct CloudFormation stack management including: ### Template Management CloudFormation templates embedded in binary using go:embed directive: + - `cluster-vpc.yaml` - VPC networking stack - `cluster-iam.yaml` - IAM roles and OIDC provider stack - `lambda-bootstrap.yaml` - Lambda function stack (optional) @@ -174,12 +130,14 @@ Validates and strips `https://` prefix from OIDC issuer URL for use in CloudForm Event-driven execution mode invoked via `rosactl handler` (the container's default CMD). **Supported event actions**: + - `apply-cluster-vpc` - Create VPC CloudFormation stack - `delete-cluster-vpc` - Delete VPC stack - `apply-cluster-iam` - Create IAM CloudFormation stack - `delete-cluster-iam` - Delete IAM stack **Event payload structure**: + ```json { "action": "apply-cluster-vpc", @@ -193,11 +151,12 @@ Event-driven execution mode invoked via `rosactl handler` (the container's defau ``` **Response structure**: + ```json { "action": "apply-cluster-vpc", "stack_id": "arn:aws:cloudformation:...", - "outputs": { "VpcId": "vpc-...", "..." : "..." }, + "outputs": { "VpcId": "vpc-...", "...": "..." }, "error": "" } ``` @@ -246,6 +205,7 @@ The handler delegates to the service layer (`internal/services/clustervpc` and ` **Decision**: Extract VPC and IAM business logic into a dedicated service layer (`internal/services/`). **Rationale**: + - CLI commands and Lambda handler share identical CloudFormation logic - Single implementation means bug fixes and changes apply to both modes automatically - Service functions accept request structs with `aws.Config`, making them independently testable @@ -256,6 +216,7 @@ The handler delegates to the service layer (`internal/services/clustervpc` and ` **Decision**: CLI commands directly call CloudFormation API; Lambda deployment is optional. **Rationale**: + - Simpler user experience (no Lambda bootstrap required) - Faster execution (no Lambda cold start delay) - Direct CloudFormation error feedback @@ -268,6 +229,7 @@ The handler delegates to the service layer (`internal/services/clustervpc` and ` **Decision**: Embed CloudFormation templates in binary using go:embed directive. **Rationale**: + - Single portable binary with no external file dependencies - No runtime file path resolution issues (embedded files accessed by name) - Templates versioned with binary @@ -281,6 +243,7 @@ The handler delegates to the service layer (`internal/services/clustervpc` and ` **Decision**: All resources defined in CloudFormation templates, not direct SDK calls. **Rationale**: + - Declarative infrastructure (GitOps-friendly) - Automatic rollback on failure - Drift detection available @@ -295,6 +258,7 @@ The handler delegates to the service layer (`internal/services/clustervpc` and ` **Decision**: No support for customer-hosted OIDC issuers. **Rationale**: + - Aligns with ROSA HCP service architecture - Simpler key management (HyperShift handles RSA keys) - No RSA private keys in customer accounts @@ -308,12 +272,14 @@ The handler delegates to the service layer (`internal/services/clustervpc` and ` ### IAM Permissions Required **For CLI Execution**: + - **CloudFormation**: CreateStack, UpdateStack, DeleteStack, DescribeStacks, ListStacks, DescribeStackEvents - **EC2** (VPC creation): CreateVpc, CreateSubnet, CreateSecurityGroup, CreateNatGateway, CreateInternetGateway, CreateRoute, CreateRouteTable - **IAM** (cluster IAM): CreateRole, AttachRolePolicy, CreateInstanceProfile, CreateOpenIDConnectProvider - **Route53** (VPC): CreateHostedZone, DeleteHostedZone **For Lambda Execution** (optional): + - Same permissions as CLI execution - Lambda: CreateFunction, DeleteFunction, InvokeFunction - ECR: GetAuthorizationToken, BatchGetImage (for container images) @@ -329,10 +295,12 @@ The handler delegates to the service layer (`internal/services/clustervpc` and ` ### Stack Isolation All CloudFormation stacks follow naming convention `rosa-{cluster-name}-{type}`: + - VPC stacks: `rosa-my-cluster-vpc` - IAM stacks: `rosa-my-cluster-iam` All stacks tagged with: + - `Cluster`: cluster name - `ManagedBy`: rosactl - `red-hat-managed`: true @@ -342,6 +310,7 @@ All stacks tagged with: ### CloudFormation Stack Events Real-time stack events displayed during creation/deletion with: + - Progress indicators (emoji-based) - Stack status polling with timeout - Detailed error messages for failed resources @@ -350,6 +319,7 @@ Real-time stack events displayed during creation/deletion with: ### CLI Output Structured output format: + - Stack ID and status - Resource outputs (VPC ID, role ARNs, etc.) - Clear error messages with remediation suggestions @@ -358,6 +328,7 @@ Structured output format: ### CloudFormation Console Users can view: + - Full stack history and drift detection - Resource visualization - Change sets for preview @@ -377,7 +348,7 @@ Users can view: ## References -- [ROSA Regional Platform Terraform](https://github.com/openshift-online/rosa-regional-platform) +- [ROSA HyperFleet Terraform](https://github.com/openshift-online/rosa-hyperfleet) - [HyperShift OIDC Implementation](https://github.com/openshift/hypershift) - [AWS CloudFormation Best Practices](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/best-practices.html) - [AWS Lambda Container Images](https://docs.aws.amazon.com/lambda/latest/dg/images-create.html) diff --git a/docs/guides/DEVELOPMENT.md b/docs/guides/DEVELOPMENT.md index 5ebab25..fb03e30 100644 --- a/docs/guides/DEVELOPMENT.md +++ b/docs/guides/DEVELOPMENT.md @@ -3,6 +3,7 @@ ## Getting Started ### Prerequisites + - **Go 1.25+** - Required for building from source - **Make** - For using Makefile targets - **Docker or Podman** - Optional, for LocalStack testing and building Lambda container images @@ -12,6 +13,7 @@ - **go-semver-release** - Optional, for semantic versioning Install go-semver-release: + ```bash go install github.com/s0ders/go-semver-release@latest ``` @@ -19,24 +21,28 @@ go install github.com/s0ders/go-semver-release@latest ### Setup 1. Clone the repository + ```bash -git clone https://github.com/openshift-online/rosa-regional-platform-cli.git -cd rosa-regional-platform-cli +git clone https://github.com/openshift-online/rosa-hyperfleet-cli.git +cd rosa-hyperfleet-cli ``` 2. Install Go dependencies + ```bash go mod download ``` 3. Build the project + ```bash make build ``` -The binary will be available at `./rosactl`. +The binary will be available at `./bin/rosactl`. 4. Run tests + ```bash make test-localstack ``` @@ -44,6 +50,7 @@ make test-localstack ## Development Workflow ### Branch Strategy + - `main` - Production-ready code, protected branch - `feature/*` - New features and enhancements - `fix/*` - Bug fixes @@ -53,6 +60,7 @@ make test-localstack ### Making Changes 1. Create a feature branch from main + ```bash git checkout main git pull origin main @@ -61,11 +69,13 @@ git checkout -b feature/add-stack-outputs 2. Make your changes 3. Test locally with LocalStack + ```bash make test-localstack ``` 4. Build and test the binary + ```bash make build ./rosactl cluster-vpc create test --region us-east-1 --help @@ -87,6 +97,7 @@ footer ``` **Types** (affects version bump): + - `feat`: New feature (minor version bump) - `fix`: Bug fix (patch version bump) - `docs`: Documentation only (patch version bump) @@ -96,6 +107,7 @@ footer - `BREAKING CHANGE`: Breaking API change (major version bump) **Examples**: + ```bash # Feature (bumps 0.1.0 → 0.2.0) git commit -m "feat: add VPC peering support" @@ -117,12 +129,15 @@ See [docs/guides/VERSIONING.md](VERSIONING.md) for details. ## Code Style ### Formatting + Use `gofmt` for code formatting (enforced by Go toolchain): + ```bash gofmt -w . ``` ### Linting + ```bash # Run golangci-lint (if configured) golangci-lint run @@ -132,6 +147,7 @@ go vet ./... ``` ### Best Practices + - Use `aws.String()`, `aws.Int32()` for pointer conversions - Wrap errors with context: `fmt.Errorf("operation failed: %w", err)` - Use typed errors for CloudFormation states (StackAlreadyExistsError, NoChangesError) @@ -158,26 +174,31 @@ LocalStack tests validate CLI commands and Lambda handler invocations against a Lambda container execution tests require LocalStack Pro. 1. Set the LocalStack Pro auth token (required for Lambda tests): + ```bash export LOCALSTACK_AUTH_TOKEN=your-token-here ``` 2. Start LocalStack: + ```bash make localstack-up ``` 3. Run tests: + ```bash make test-localstack ``` 4. Stop LocalStack: + ```bash make localstack-down ``` **What the tests validate**: + - `cluster-vpc create` creates CloudFormation stack with VPC resources - `cluster-vpc delete` deletes VPC stack - `cluster-iam create` creates CloudFormation stack with IAM resources @@ -203,6 +224,7 @@ var _ = Describe("Feature", func() { ``` For CLI command tests: + - Use `exec.CommandContext()` to invoke rosactl binary - Use `gexec.Start()` to capture output - Verify both stdout and stderr @@ -213,6 +235,7 @@ For CLI command tests: ### Verbose AWS SDK Logging Set environment variables: + ```bash export AWS_SDK_LOG_LEVEL=debug export AWS_SDK_LOG_MODE=LogWithHTTPBody @@ -222,6 +245,7 @@ export AWS_SDK_LOG_MODE=LogWithHTTPBody ### CloudFormation Stack Events View stack events for troubleshooting: + ```bash aws cloudformation describe-stack-events \ --stack-name rosa-my-cluster-vpc \ @@ -238,6 +262,7 @@ aws cloudformation describe-stack-events \ ## Building ### Local Build + ```bash # Build for current platform make build @@ -246,6 +271,7 @@ make build ``` ### Build for Specific Platform + ```bash # Linux GOOS=linux GOARCH=amd64 go build -o rosactl cmd/rosactl/main.go @@ -258,6 +284,7 @@ GOOS=windows GOARCH=amd64 go build -o rosactl.exe cmd/rosactl/main.go ``` ### Release Build + ```bash # Check what version would be released make release-dry-run @@ -270,6 +297,7 @@ git push origin v0.2.0 ``` ### Docker Build (for Lambda deployment) + ```bash # Build container image docker build -f Dockerfile -t rosactl:latest . @@ -286,7 +314,7 @@ docker push .dkr.ecr.us-east-1.amazonaws.com/rosactl:latest ## Project Structure ```text -rosa-regional-platform-cli/ +rosa-hyperfleet-cli/ ├── cmd/rosactl/ # Entry point (main.go) ├── internal/ │ ├── commands/ # CLI command groups @@ -329,6 +357,7 @@ rosa-regional-platform-cli/ 4. Add tests in LocalStack test suite Example: + ```go // internal/commands/myfeature/myfeature.go package myfeature @@ -397,6 +426,7 @@ When making changes that affect user-facing behavior or architecture: ### Code Review Guidelines **For Reviewers**: + - Check for security issues (command injection, path traversal) - Verify CloudFormation templates are valid - Ensure error messages are helpful @@ -404,6 +434,7 @@ When making changes that affect user-facing behavior or architecture: - Check that documentation is updated **For Contributors**: + - Keep changes focused and atomic - Write clear commit messages - Add tests for new features diff --git a/docs/guides/DOCUMENTATION.md b/docs/guides/DOCUMENTATION.md index 74031dc..ad456d0 100644 --- a/docs/guides/DOCUMENTATION.md +++ b/docs/guides/DOCUMENTATION.md @@ -5,16 +5,19 @@ This guide defines the standards and best practices for writing documentation in ## Core Principles ### 1. Conciseness + - **Be direct and concise** - Remove unnecessary words - **One concept per paragraph** - Don't mix multiple ideas - **Use active voice** - "The CLI invokes the Lambda" not "The Lambda is invoked by the CLI" ### 2. Visual Over Text + - **Prioritize diagrams** - Use ASCII diagrams, flowcharts, and swimlanes - **Show, don't tell** - Include code examples and command outputs - **Tables over lists** - Use tables for comparisons and structured data ### 3. Examples First + - **Start with examples** - Show working code before explaining theory - **Real-world scenarios** - Use actual use cases, not abstract examples - **Include expected output** - Always show what the user should see @@ -26,27 +29,34 @@ This guide defines the standards and best practices for writing documentation in **Purpose**: Explain system design and structure **Format**: + ```markdown # Component Name ## Overview + [1-2 sentence description] ## Architecture Diagram + [ASCII or Mermaid diagram] ## Key Components + - Component A: [Purpose] - Component B: [Purpose] ## Data Flow + [Swimlane or sequence diagram] ## Trade-offs + [Design decisions and rationale] ``` **Examples**: + - `ARCHITECTURE.md` - System-wide architecture and design decisions --- @@ -56,28 +66,36 @@ This guide defines the standards and best practices for writing documentation in **Purpose**: Help users accomplish specific tasks **Format**: -```markdown + +````markdown # Task Name ## Quick Start + [30-second example] ## Detailed Steps + 1. Step 1 ```bash command example ``` - Expected output: - ``` - output example - ``` +```` + +Expected output: + +``` +output example +``` 2. Step 2 ... ## Common Issues + [Troubleshooting tips] -``` + +```` **Examples**: - `VERSIONING.md` - How to manage versions @@ -109,9 +127,10 @@ This guide defines the standards and best practices for writing documentation in ## Examples [Usage examples] -``` +```` **Examples**: + - `feature-e2e.md` - End-to-end testing --- @@ -121,40 +140,47 @@ This guide defines the standards and best practices for writing documentation in ### Commands and Code ✅ **Good**: -```markdown + +````markdown Bootstrap the Lambda function: + ```bash rosactl bootstrap create --image-uri 123456789012.dkr.ecr.us-east-1.amazonaws.com/rosa-cli:latest --region us-east-1 ``` +```` Output: + ``` -Creating CloudFormation stack: rosa-regional-platform-bootstrap +Creating CloudFormation stack: rosactl-bootstrap Lambda function created successfully! -ARN: arn:aws:lambda:us-east-1:123456789012:function:rosa-regional-platform-lambda -``` +ARN: arn:aws:lambda:us-east-1:123456789012:function:rosactl-lambda ``` +```` + ❌ **Bad**: ```markdown You can bootstrap the Lambda infrastructure by running the command with the container image URI. -``` +```` ### Diagrams ✅ **Good** (Swimlane diagram): + ```markdown -User CLI CloudFormation Lambda IAM - | | | | | - |-- create cmd --->| | | | - | |-- apply CF --->| | | - | | |-- invoke --->| | - | | | |-- create ---->| - | | | |<-- ARN -------| - |<--- outputs -----| | | | +User CLI CloudFormation Lambda IAM +| | | | | +|-- create cmd --->| | | | +| |-- apply CF --->| | | +| | |-- invoke --->| | +| | | |-- create ---->| +| | | |<-- ARN -------| +|<--- outputs -----| | | | ``` ❌ **Bad** (Wall of text): + ```markdown When the user runs the create command, the CLI applies a CloudFormation stack which invokes the Lambda function, and the Lambda creates IAM resources and returns their ARNs. ``` @@ -162,15 +188,17 @@ When the user runs the create command, the CLI applies a CloudFormation stack wh ### Comparisons ✅ **Good** (Table): + ```markdown -| Command | Purpose | Use Case | -|---------|---------|----------| -| bootstrap create | Deploy Lambda | One-time setup | -| cluster-iam create | Create IAM resources | Per cluster | -| cluster-iam delete | Remove IAM resources | Cleanup | +| Command | Purpose | Use Case | +| ------------------ | -------------------- | -------------- | +| bootstrap create | Deploy Lambda | One-time setup | +| cluster-iam create | Create IAM resources | Per cluster | +| cluster-iam delete | Remove IAM resources | Cleanup | ``` ❌ **Bad** (Long paragraphs): + ```markdown The bootstrap create command deploys the Lambda function and is used for one-time setup. The cluster-iam create command creates IAM resources for each cluster. The cluster-iam delete command removes IAM resources during cleanup. ``` @@ -224,9 +252,11 @@ git commit -m "docs: fix typos in architecture documentation" ### 1. Too Much Theory, Not Enough Practice ❌ **Bad**: + > "The IAM OIDC provider uses CloudFormation-based declarative infrastructure to establish federated trust relationships with the managed OIDC issuer in the Red Hat control plane..." ✅ **Good**: + ```bash # Create cluster IAM resources rosactl cluster-iam create my-cluster \ @@ -242,11 +272,13 @@ rosactl cluster-iam create my-cluster \ ### 2. Missing Context ❌ **Bad**: + ```bash rosactl bootstrap create --image-uri --region us-east-1 ``` ✅ **Good**: + ```bash # First, push the container image to ECR docker build -f Dockerfile -t rosa-cli:latest . @@ -262,11 +294,13 @@ rosactl bootstrap create \ ### 3. Outdated Examples ❌ **Bad** (references deleted commands): + ```bash rosactl oidc create my-cluster # This command no longer exists ``` ✅ **Good** (current syntax): + ```bash rosactl cluster-iam create my-cluster \ --oidc-issuer-url https://d1234.cloudfront.net/my-cluster \ diff --git a/docs/guides/VERSIONING.md b/docs/guides/VERSIONING.md index 0c558e9..2ad7ace 100644 --- a/docs/guides/VERSIONING.md +++ b/docs/guides/VERSIONING.md @@ -33,14 +33,14 @@ Versioning is based on [Conventional Commits](https://www.conventionalcommits.or The commit message **type** determines the version bump: -| Commit Type | Version Bump | Example | -|-------------|--------------|---------| -| `feat:` | **MINOR** (0.1.0 → 0.2.0) | `feat: add JWT signing command` | -| `fix:` | **PATCH** (0.1.0 → 0.1.1) | `fix: S3 timeout in e2e tests` | -| `perf:` | **PATCH** | `perf: optimize Lambda packaging` | -| `refactor:` | **PATCH** | `refactor: simplify OIDC creation` | -| `BREAKING CHANGE:` | **MAJOR** (0.1.0 → 1.0.0) | See below | -| `docs:`, `chore:`, `test:`, `build:`, `ci:` | **PATCH** | Documentation, tooling changes | +| Commit Type | Version Bump | Example | +| ------------------------------------------- | ------------------------- | ---------------------------------- | +| `feat:` | **MINOR** (0.1.0 → 0.2.0) | `feat: add JWT signing command` | +| `fix:` | **PATCH** (0.1.0 → 0.1.1) | `fix: S3 timeout in e2e tests` | +| `perf:` | **PATCH** | `perf: optimize Lambda packaging` | +| `refactor:` | **PATCH** | `refactor: simplify OIDC creation` | +| `BREAKING CHANGE:` | **MAJOR** (0.1.0 → 1.0.0) | See below | +| `docs:`, `chore:`, `test:`, `build:`, `ci:` | **PATCH** | Documentation, tooling changes | ### Breaking Changes @@ -168,7 +168,7 @@ name: Release on: push: tags: - - 'v*' + - "v*" jobs: release: runs-on: ubuntu-latest @@ -223,7 +223,7 @@ git log $(git describe --tags --abbrev=0)..HEAD --oneline branches: - name: main - name: rc - prerelease: true # Creates v0.2.0-rc.1, v0.2.0-rc.2, etc. + prerelease: true # Creates v0.2.0-rc.1, v0.2.0-rc.2, etc. ``` ## Reference diff --git a/docs/specs/reference-gist-1.md b/docs/specs/reference-gist-1.md index 83e57c7..8195bff 100644 --- a/docs/specs/reference-gist-1.md +++ b/docs/specs/reference-gist-1.md @@ -69,6 +69,7 @@ The two client IDs (`"openshift"` and `"sts.amazonaws.com"`) correspond to the t ### Step 3: IAM Roles With OIDC Trust Policies Are Created in the Customer Account For each control plane component that needs AWS access, an IAM role is created in the customer's account. Each role has: + - A **permissions policy** (what AWS actions it can perform) - A **trust policy** (who can assume it) @@ -76,34 +77,36 @@ The trust policy uses the OIDC provider as a federated principal and restricts a ```json { - "Version": "2012-10-17", - "Statement": [{ - "Effect": "Allow", - "Principal": { - "Federated": "" - }, - "Action": "sts:AssumeRoleWithWebIdentity", - "Condition": { - "StringEquals": { - ":sub": "system:serviceaccount::" - } + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Principal": { + "Federated": "" + }, + "Action": "sts:AssumeRoleWithWebIdentity", + "Condition": { + "StringEquals": { + ":sub": "system:serviceaccount::" } - }] + } + } + ] } ``` The key roles (defined in [`api/hypershift/v1beta1/aws.go:434+`](api/hypershift/v1beta1/aws.go#L434)) include: -| Role | Purpose | -|------|---------| -| `IngressARN` | Route53 + ELB operations | -| `ImageRegistryARN` | S3 bucket operations for image registry | -| `StorageARN` | EBS volume operations | -| `KubeCloudControllerARN` | EC2/ELB operations | -| `NodePoolManagementARN` | CAPA controller (EC2 instances for worker nodes) | -| `ControlPlaneOperatorARN` | VPC endpoint operations | -| `NetworkARN` | Network configuration | -| `KarpenterRoleARN` | Karpenter auto-scaling (optional) | +| Role | Purpose | +| ------------------------- | ------------------------------------------------ | +| `IngressARN` | Route53 + ELB operations | +| `ImageRegistryARN` | S3 bucket operations for image registry | +| `StorageARN` | EBS volume operations | +| `KubeCloudControllerARN` | EC2/ELB operations | +| `NodePoolManagementARN` | CAPA controller (EC2 instances for worker nodes) | +| `ControlPlaneOperatorARN` | VPC endpoint operations | +| `NetworkARN` | Network configuration | +| `KarpenterRoleARN` | Karpenter auto-scaling (optional) | --- @@ -118,6 +121,7 @@ The private key is stored as a Kubernetes secret referenced by `hc.Spec.ServiceA See [`hostedcluster_controller.go:4480-4501`](hypershift-operator/controllers/hostedcluster/hostedcluster_controller.go#L4480-L4501) and [`manifests.go:17-18`](hypershift-operator/controllers/manifests/controlplaneoperator/manifests.go#L17-L18). The hosted kube-apiserver is then started with: + - `--service-account-signing-key-file` pointing at the private key ([`kas/config.go:259`](control-plane-operator/controllers/hostedcontrolplane/v2/kas/config.go#L259)) - `--service-account-issuer` set to the S3 OIDC URL ([`kas/config.go:253`](control-plane-operator/controllers/hostedcontrolplane/v2/kas/config.go#L253)) @@ -156,6 +160,7 @@ token, err := clientset.CoreV1().ServiceAccounts(sa.GetNamespace()).CreateToken( ``` The resulting JWT has: + - `iss` = the S3-hosted OIDC issuer URL - `sub` = `system:serviceaccount::` - `aud` = `["openshift"]` @@ -176,6 +181,7 @@ region = us-east-1 ``` When the AWS SDK in the pod needs credentials, it: + 1. Reads the JWT from `web_identity_token_file` 2. Calls `STS:AssumeRoleWithWebIdentity` with the JWT and the `role_arn` 3. AWS STS fetches the OIDC discovery document from S3 @@ -364,22 +370,22 @@ flowchart LR ## Key Source Files -| Component | File | Lines | -|-----------|------|-------| -| OIDC document generation | [`support/oidc/oidc.go`](support/oidc/oidc.go) | 29-83 | -| OIDC provider creation | [`cmd/infra/aws/iam.go`](cmd/infra/aws/iam.go) | 988-1030 | -| Trust policy template | [`cmd/infra/aws/iam.go`](cmd/infra/aws/iam.go) | 1434-1451 | -| Private key reconciliation | [`hostedcluster_controller.go`](hypershift-operator/controllers/hostedcluster/hostedcluster_controller.go) | 4480-4501 | -| SA signing key secret | [`manifests.go`](hypershift-operator/controllers/manifests/controlplaneoperator/manifests.go) | 17-18 | -| KAS signing key flag | [`kas/config.go`](control-plane-operator/controllers/hostedcontrolplane/v2/kas/config.go) | 253-259 | -| Token minter | [`token-minter/tokenminter.go`](token-minter/tokenminter.go) | 38-228 | -| CAPA deployment (token minter + creds) | [`aws.go`](hypershift-operator/controllers/hostedcluster/internal/platform/aws/aws.go) | 34-39, 140-259 | -| STS AssumeRole helper | [`support/awsutil/sts.go`](support/awsutil/sts.go) | — | -| API role definitions | [`api/hypershift/v1beta1/aws.go`](api/hypershift/v1beta1/aws.go) | 434+ | +| Component | File | Lines | +| -------------------------------------- | ---------------------------------------------------------------------------------------------------------- | -------------- | +| OIDC document generation | [`support/oidc/oidc.go`](support/oidc/oidc.go) | 29-83 | +| OIDC provider creation | [`cmd/infra/aws/iam.go`](cmd/infra/aws/iam.go) | 988-1030 | +| Trust policy template | [`cmd/infra/aws/iam.go`](cmd/infra/aws/iam.go) | 1434-1451 | +| Private key reconciliation | [`hostedcluster_controller.go`](hypershift-operator/controllers/hostedcluster/hostedcluster_controller.go) | 4480-4501 | +| SA signing key secret | [`manifests.go`](hypershift-operator/controllers/manifests/controlplaneoperator/manifests.go) | 17-18 | +| KAS signing key flag | [`kas/config.go`](control-plane-operator/controllers/hostedcontrolplane/v2/kas/config.go) | 253-259 | +| Token minter | [`token-minter/tokenminter.go`](token-minter/tokenminter.go) | 38-228 | +| CAPA deployment (token minter + creds) | [`aws.go`](hypershift-operator/controllers/hostedcluster/internal/platform/aws/aws.go) | 34-39, 140-259 | +| STS AssumeRole helper | [`support/awsutil/sts.go`](support/awsutil/sts.go) | — | +| API role definitions | [`api/hypershift/v1beta1/aws.go`](api/hypershift/v1beta1/aws.go) | 434+ | ## External Documentation - [AWS: IAM OIDC Identity Providers](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_oidc.html) - [AWS: ROSA Getting Started with HCP](https://docs.aws.amazon.com/rosa/latest/userguide/getting-started-hcp.html) - [Kubernetes: Service Account Token Volume Projection](https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/#serviceaccount-token-volume-projection) -- [Kubernetes: TokenRequest API](https://kubernetes.io/docs/reference/kubernetes-api/authentication-resources/token-request-v1/) \ No newline at end of file +- [Kubernetes: TokenRequest API](https://kubernetes.io/docs/reference/kubernetes-api/authentication-resources/token-request-v1/) diff --git a/docs/specs/references.md b/docs/specs/references.md index 630c3c0..ff6908f 100644 --- a/docs/specs/references.md +++ b/docs/specs/references.md @@ -1,45 +1,48 @@ # Reference Projects -This document lists GitHub repositories that serve as guardrails and guidelines for the development of regional-cli. +This document lists GitHub repositories that serve as guardrails and guidelines for the development of hyperfleet-cli. ## Reference Repositories - ### [hypershift](https://github.com/openshift/hypershift) -**Purpose:** Implements the hypershift compoent + +**Purpose:** Implements the hypershift component **Key Takeaways:** -- the rosa regional hcp service deployes hypershift clusters + +- the rosa regional hcp service deploys hypershift clusters **Relevant Areas:** -- hypershift cli can create oidc provider in the customer account, some of our cli functions can draw from this repository +- hypershift cli can create oidc provider in the customer account, some of our cli functions can draw from this repository -### [rosa-regional-platform-api](https://github.com/openshift-online/rosa-regional-platform-api) +### [rosa-hyperfleet-api](https://github.com/openshift-online/rosa-hyperfleet-api) **Purpose:** Implements the backend passthrough api that this cli will connect to **Key Takeaways:** + - What patterns or approaches to follow - What to avoid - Specific implementation details to reference **Relevant Areas:** -- backend that this cli will connect too -- implements authz based on cedar policies - +- backend that this cli will connect to +- implements authz based on cedar policies ### [rosa](https://github.com/openshift/rosa) + **Purpose:** Implements the current rosa cli tool customers use to interact with the rosa hcp service. **Key Takeaways:** + - CLI structure and command organization - Authentication patterns - API client patterns **Relevant Areas:** + - Overall CLI architecture - Command structure - API integration -