Skip to content

[docs-agent] Fix stale naming, missing entries, and ASCII diagrams #91

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
redhat-chai-bot wants to merge 1 commit into from
Closed

[docs-agent] Fix stale naming, missing entries, and ASCII diagrams #91

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 12 additions & 9 deletions CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
32 changes: 25 additions & 7 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.

Expand All @@ -9,18 +9,21 @@ 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
- **Embedded templates**: CloudFormation templates embedded in binary using go:embed
- **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
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
```
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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

Expand All @@ -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
Expand All @@ -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

Expand All @@ -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
Expand All @@ -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
Expand All @@ -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:
Expand All @@ -546,28 +557,33 @@ 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
aws cloudformation describe-stack-events --stack-name rosa-my-cluster-vpc
```

**"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
Expand All @@ -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
```
Expand Down Expand Up @@ -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
Expand Down
36 changes: 22 additions & 14 deletions docs/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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)
Expand All @@ -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
Expand All @@ -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

Expand Down Expand Up @@ -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.)

Expand All @@ -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

---
Expand Down
Loading