Skip to content

Enhance CLAUDE.md with comprehensive repository documentation #2593

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

Open
dustman9000 wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Enhance CLAUDE.md with comprehensive repository documentation #2593

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
179 changes: 147 additions & 32 deletions CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,60 +10,116 @@ This is a **Kubernetes/OpenShift configuration management repository** for Red H

### Build and Template Generation
```bash
# Generate all templates for all environments
# Generate all templates for all environments (runs in container by default)
make

# Generate templates for specific environment
make integration # or 'stage', 'production'
# Generate OAuth templates from HTML sources
make generate-oauth-templates

# Run in container (recommended for consistency)
make container-build
# Generate ROSA brand logo configmap
make generate-rosa-brand-logo

# Generate ACM policies
make policies
# Enforce backplane access rules
make enforce-backplane-rules

# Validate all configurations
make validate
# Check links in documentation
make checklinks
```

### Testing and Validation
```bash
# Validate configurations using OpenShift CLI
oc apply --dry-run=client -f /path/to/config.yaml

# Run backplane rules enforcement
# Run backplane rules enforcement directly
python scripts/enforce-backplane-rules.py
```

# Check links in documentation
make check-links
### Manual Script Execution
```bash
# Generate Hive SelectorSyncSet templates
scripts/generate_template.py -t scripts/templates/ -y deploy -d hack/ -r managed-cluster-config

# Generate ACM policy configurations
scripts/generate-policy-config.py

# Generate SubjectPermissions policy configurations
scripts/generate-subjectpermissions-policy-config.py

# Generate CMO (Cluster Monitoring Operator) config
scripts/generate-cmo-config.py
```

## Architecture Overview

### Directory Structure
- **`/deploy`**: Source of truth containing 100+ component directories with raw YAML configurations
- **`/hack`**: Generated Hive templates for different environments (integration/stage/production)
- **`/deploy/acm-policies`**: Generated ACM (Advanced Cluster Management) policy files (50-GENERATED-*.yaml)
- Each subdirectory must contain a `config.yaml` file (mandatory since OSD-15267)
- **`/hack`**: Generated Hive SelectorSyncSet templates for different environments
- `00-osd-managed-cluster-config-integration.yaml.tmpl`
- `00-osd-managed-cluster-config-stage.yaml.tmpl`
- `00-osd-managed-cluster-config-production.yaml.tmpl`
- **`/scripts`**: Python build automation scripts for template generation and validation
- Uses Python 3.9 with `oyaml` library
- All scripts run in containers by default for consistency
- **`/resources`**: Shared resource templates and Prometheus rules
- **`/source`**: HTML templates for OAuth branding customization
- `prometheusrules/`: SRE-specific monitoring rules and alerts
- `sts/`: AWS STS (Security Token Service) configurations
- `wif/`: Workload Identity Federation configurations
- **`/source/html`**: OAuth login page HTML templates
- `osd/`: OpenShift Dedicated branding (login.html, providers.html, errors.html)
- `rosa/`: ROSA branding and logo (rosa-brand-logo.svg)

### Configuration Pattern
Every directory in `/deploy` requires a `config.yaml` file with structure:
Every directory in `/deploy` requires a `config.yaml` file (mandatory). Structure:
```yaml
deploymentMode: "SelectorSyncSet" # or "Policy"
selectorSyncSet:
matchExpressions:
matchLabels: {} # Optional: adds matchLabels to clusterDeploymentSelector
matchExpressions: # Optional: selector matching conditions
- key: api.openshift.com/product
operator: NotIn # or In
values: ["rosa"] # Product targeting
resourceApplyMode: "Sync" # or "Upsert"
values: ["rosa"] # Product targeting (rosa, osd)
- key: hive.openshift.io/cluster-platform
operator: In
values: ["aws"] # Platform targeting (aws, gcp, azure)
resourceApplyMode: "Sync" # "Sync" (full sync, removes extra resources) or "Upsert" (only creates/updates)
matchLabelsApplyMode: "AND" # "AND" (single SSS) or "OR" (separate SSS per label)
applyBehavior: null # Optional: sets SelectorSyncSet's applyBehavior (see Hive docs)

# Optional: Policy configuration for ACM policy generation
policy:
destination: "acm-policies" # Enable ACM policy generation
complianceType: "mustonlyhave" # or "musthave", "mustnothave"
metadataComplianceType: "musthave" # Compliance type for metadata
```

**Real-world example** (version-specific deployment):
```yaml
deploymentMode: "SelectorSyncSet"
selectorSyncSet:
resourceApplyMode: Sync
matchExpressions:
- key: hive.openshift.io/version
operator: In
values: ["4.14.0-rc.3", "4.14.0-rc.4", "4.15.0-ec.0"]
```

### Build Process Flow
```
Raw configs (/deploy) → Template Generation → Environment templates (/hack) → Hive Deployment
1. Source files (/deploy/*.yaml + config.yaml)
2. OAuth template generation (source/html → deploy/*-oauth-templates-*)
3. Policy generation (config.yaml with policy.destination → deploy/acm-policies/50-GENERATED-*)
4. SelectorSyncSet generation (scripts/generate_template.py → hack/00-osd-managed-cluster-config-*.yaml.tmpl)
5. Hive applies templates to target clusters based on selectors
```

**Container-based build** (default):
- All builds run in UBI8 Python 3.9 containers for consistency
- PolicyGenerator binary (v1.12.4) downloaded during build
- SELinux volume mount flags handled automatically (`:z` on Linux, none on macOS with Podman)

## Key Technical Details

### Template Generation
Expand All @@ -79,32 +135,91 @@ Raw configs (/deploy) → Template Generation → Environment templates (/hack)
- **Hypershift**: Hosted control plane support

### Deployment Targeting
Configurations use selector-based targeting:
- `api.openshift.com/product`: Product type (rosa, osd)
- `hive.openshift.io/cluster-platform`: Cloud platform (aws, gcp, azure)
Configurations use selector-based targeting with matchLabels and matchExpressions:

**Common selector keys:**
- `api.openshift.com/product`: Product type
- Values: `rosa`, `osd`
- Use `NotIn: ["rosa"]` for OSD-only, `In: ["rosa"]` for ROSA-only
- `hive.openshift.io/cluster-platform`: Cloud platform
- Values: `aws`, `gcp`, `azure`
- `api.openshift.com/fedramp`: FedRAMP compliance level
- Values: `true`, `moderate`, `high`
- `hive.openshift.io/version`: OpenShift version
- Values: Specific versions like `4.14.0-rc.3`, `4.15.0-ec.0`
- `ext-hypershift.openshift.io/cluster-type`: Hypershift cluster type
- Values: `management-cluster`, `service-cluster`, `hosted-cluster`

**Example selector combinations:**
```yaml
# ROSA on AWS only
matchExpressions:
- key: api.openshift.com/product
operator: In
values: ["rosa"]
- key: hive.openshift.io/cluster-platform
operator: In
values: ["aws"]

# OSD (excluding ROSA) on any platform
matchExpressions:
- key: api.openshift.com/product
operator: NotIn
values: ["rosa"]
```

### Resource Apply Modes
- **Sync**: Full synchronization - removes resources not in template
- **Upsert**: Only creates/updates resources, never removes

## Development Workflow

### Adding a New SelectorSyncSet
1. **Create directory** under `/deploy` with descriptive name
2. **Add YAML manifests** for Kubernetes resources
3. **Create config.yaml** with appropriate selectors and apply mode
4. **Run `make`** to generate templates
5. **Validate** the generated template in `/hack`
6. **Test in integration** before promoting to production

### Adding an ACM Policy
**Option 1 - Convert existing manifest to policy:**
1. Add `policy.destination: "acm-policies"` to existing object's `config.yaml`
2. Run `make` to generate policy in `deploy/acm-policies/50-GENERATED-*.yaml`

**Option 2 - Create new policy-only manifest:**
1. Create new directory under `/deploy`
2. Add manifests and `config.yaml` with `policy.destination: "acm-policies"`
3. Set `deploymentMode: "Policy"` if you want ONLY policy deployment (no SelectorSyncSet)
4. Run `make` to generate policy

### Updating OAuth Templates
1. **Edit HTML** files in `source/html/osd/` or `source/html/rosa/`
2. **Run `make generate-oauth-templates`** to regenerate secrets
3. **Run `make`** to update full templates
4. Templates are automatically split into separate secrets (login, providers, errors) to avoid size limits

### Standard Development Flow
1. **Modify configurations** in `/deploy` directories
2. **Update config.yaml** if changing deployment targeting
3. **Run `make validate`** to check configuration syntax
4. **Run `make`** to generate templates and verify build
5. **Test in integration environment** before promoting to production
6. **Follow team ownership** patterns defined in OWNERS files
3. **Run `make`** to generate templates and verify build
4. **Test in integration environment** before promoting to production
5. **Follow team ownership** patterns defined in OWNERS files

## Important Constraints

- All builds run in containers for consistency
- Every `/deploy` subdirectory must have a `config.yaml` file
- Template generation is automatic via GitHub Actions on push
- Configurations must pass OpenShift CLI validation
- Changes affecting production require team review per OWNERS files
- Never manually modify files with path `hack/00-osd-managed-cluster-config*.yaml.tmpl` or `deploy/acm-policies/50-GENERATED-*.yaml`, as they're generated with `make generate`.
- **Mandatory config.yaml**: Every `/deploy` subdirectory must have a `config.yaml` file (enforced since OSD-15267)
- Build will fail with error if missing: `ERROR : Missing config.yaml for resource defined in deploy/...`
- Configuration is NOT inherited by subdirectories
- **Generated files**: Never manually edit these files as they're auto-generated:
- `hack/00-osd-managed-cluster-config-*.yaml.tmpl` (generated from deploy/)
- `deploy/acm-policies/50-GENERATED-*.yaml` (generated by PolicyGenerator)
- `deploy/*-oauth-templates-*/` (generated from source/html/)
- **Container builds**: All builds run in containers for consistency (Docker/Podman)
- **Validation**: Configurations must pass OpenShift CLI dry-run validation
- **GitHub Actions**: Template generation runs automatically on push
- **Code review**: Changes affecting production require team review per OWNERS files
- **OAuth templates**: HTML files are converted to Kubernetes secrets, one per file (login, providers, errors) to avoid annotation size limits

## Dependencies

Expand Down