From 238008e238e295df96ba65fbbaefd2d9308f9213 Mon Sep 17 00:00:00 2001 From: Dustin Lactin Date: Mon, 2 Mar 2026 14:11:52 -0700 Subject: [PATCH 1/5] refactor: moved various skill sections into references to reduce SKILL.md size, updated readme and add more detailed migration samples --- .../skills/mozcloud-chart-migration/README.md | 114 +++++-- .../skills/mozcloud-chart-migration/SKILL.md | 170 +++++++--- .../migration-directory-structure.md | 300 ++++++++++++++++++ .../references/mozcloud-chart-reference.md | 166 ++++++++++ .../references/troubleshooting.md | 250 +++++++++++++++ .../working-directory-management.md | 83 +++++ 6 files changed, 1020 insertions(+), 63 deletions(-) create mode 100644 claude/skills/mozcloud-chart-migration/references/migration-directory-structure.md create mode 100644 claude/skills/mozcloud-chart-migration/references/mozcloud-chart-reference.md create mode 100644 claude/skills/mozcloud-chart-migration/references/troubleshooting.md create mode 100644 claude/skills/mozcloud-chart-migration/references/working-directory-management.md diff --git a/claude/skills/mozcloud-chart-migration/README.md b/claude/skills/mozcloud-chart-migration/README.md index b424da1..11e6cd1 100644 --- a/claude/skills/mozcloud-chart-migration/README.md +++ b/claude/skills/mozcloud-chart-migration/README.md @@ -4,15 +4,21 @@ A Claude Code skill that assists with migrating custom tenant Helm charts to the ## Overview -This skill automates and guides the process of migrating custom Helm charts to use Mozilla's shared `mozcloud` chart, which is stored in the OCI repository `oci://us-west1-docker.pkg.dev/moz-fx-platform-artifacts/mozcloud-charts`. +This skill automates and guides the process of migrating custom Helm charts to use Mozilla's shared `mozcloud` chart, which is stored in the OCI repository `oci://us-west1-docker.pkg.dev/moz-fx-platform-artifacts/mozcloud-charts/mozcloud`. + +The migration follows an **ArgoCD-based deployment workflow**: +- All charts are deployed via ArgoCD +- Changes are isolated per environment using migration branches +- Rollback is simple: delete the branch or push fixes +- Once merged to main, changes deploy to the target environment The skill handles: -- Multi-environment migrations (dev, stage, prod) -- Resource name preservation -- Semantic diff validation -- Migration documentation and tracking +- Multi-environment migrations (dev, stage, prod) with isolated branches +- Resource name preservation (primary goal) +- Semantic diff validation with render-diff +- Comprehensive migration documentation and tracking - Template gating and values file conversion -- Regional values file support +- Regional values file support (multi-region deployments) ## Installation @@ -110,12 +116,20 @@ The skill will: The skill follows this process: -1. **Pre-flight Checks**: Verifies git status, required tools, and OCI registry access -2. **Setup**: Creates migration branch and `.migration/` directory -3. **Planning**: Analyzes current chart and creates detailed migration plan -4. **Execution**: Converts values files, updates Chart.yaml, gates templates -5. **Testing**: Runs render-diff and validates resource equivalence -6. **Documentation**: Updates migration tracking files +1. **Pre-flight Checks**: Verifies git status, Helm version (not v4), render-diff availability, and OCI registry access +2. **Setup**: Creates environment-specific migration branch and `.migration/` directory structure +3. **Planning**: Analyzes current chart, identifies values files, creates detailed migration plan for user review +4. **Execution**: + - Converts values files to mozcloud schema format + - Updates Chart.yaml with mozcloud dependency + - Gates custom templates (preserves for non-migrated environments) + - **Preserves original resource names** (requires approval for any changes) +5. **Testing**: + - Runs `render-diff` for semantic equivalence + - Validates resource count matches original + - Verifies non-migrated environments show no changes + - Creates detailed diff analysis +6. **Documentation**: Updates migration tracking files (STATUS.md, CHANGES_$ENV.md, DIFF_ANALYSIS_$ENV.md) ### Key Features @@ -147,10 +161,13 @@ Automatically handles multi-region deployments with files like `values-stage-eur The skill includes several safety mechanisms: -- **No automatic commits**: All changes require user review -- **No destructive commands**: Never runs `helm install`, `helm upgrade`, or `helm delete` -- **Non-environment isolation**: Verifies other environments show no changes -- **ArgoCD-aware**: Designed for ArgoCD deployment workflow with safe rollback +- **No automatic commits**: All changes require user review before committing +- **No destructive commands**: Never runs `helm install`, `helm upgrade`, `helm delete`, or other destructive operations +- **Environment isolation**: Verifies non-migrated environments show no changes +- **Scoped file writes**: Only writes to the chart being migrated and `.migration/` directory +- **ArgoCD-aware**: Designed for ArgoCD deployment workflow with simple rollback (delete branch or push fixes) +- **Resource name preservation**: Requires explicit approval for any resource name changes +- **Semantic validation**: Uses `render-diff` to verify resource equivalence before suggesting commit ## Troubleshooting @@ -166,8 +183,31 @@ gcloud auth configure-docker us-west1-docker.pkg.dev ### "Helm version 4 detected" Helm v4 has breaking changes. Please use Helm v3 for compatibility. -### Resource count mismatch -Check `.migration/DIFF_ANALYSIS_$ENV.md` for detailed resource comparison and verify mozcloud dependency is enabled. +### render-diff shows missing resources +- Check that mozcloud dependency is enabled in values for the migrated environment +- Verify workload names match original deployment names exactly +- Review template gating conditions to ensure custom templates are properly disabled + +### Chart.lock conflicts +- Run `helm dependency update` after modifying Chart.yaml +- Ensure OCI registry is accessible + +### Resource names changing unexpectedly +- Verify mozcloud workload key matches full original deployment name +- Check for `nameOverride` or `fullnameOverride` in values files +- Review mozcloud chart's naming conventions in `values.schema.json` +- The skill will ask for approval before implementing name changes + +### Non-migrated environments showing differences +- Ensure template gating is working correctly (templates wrapped in conditional logic) +- Verify mozcloud dependency is disabled for non-migrated environments +- Run `render-diff -f values-.yaml` for each non-migrated environment + +### Files created in wrong location +This should be prevented by the Working Directory Management implementation. If encountered: +- Check that `$CHART_DIR` variable is set correctly +- Verify all file operations use absolute paths with `$CHART_DIR` +- See Technical References section above ## Examples @@ -192,11 +232,49 @@ cd charts/my-app # Skill reads .migration/README.md and continues where left off ``` +## Technical References + +Detailed implementation documentation is available in the `references/` directory: + +### [Working Directory Management](references/working-directory-management.md) +**Critical for preventing files from being created in wrong locations.** + +The skill maintains a consistent working directory by: +- Capturing `$CHART_DIR` at the start of migration +- Using absolute paths for all file operations +- Verifying location after helm operations (which may change directory context) +- Safety checks before creating files + +### [Mozcloud Chart Reference](references/mozcloud-chart-reference.md) +Complete documentation about the mozcloud chart: +- **OCI Repository**: `oci://us-west1-docker.pkg.dev/moz-fx-platform-artifacts/mozcloud-charts/mozcloud` +- Chart structure and schema details +- Common migration patterns +- Values file conventions +- Troubleshooting chart-specific issues + +### [Migration Directory Structure](references/migration-directory-structure.md) +Detailed breakdown of the `.migration/` directory: +- Purpose of each file (README.md, STATUS.md, CHANGES_*.md, etc.) +- Example content for each file type +- Best practices for documentation +- When and how to update files + +### [Troubleshooting Guide](references/troubleshooting.md) +Comprehensive troubleshooting reference: +- Render-diff issues +- OCI registry authentication +- Resource naming problems +- Template gating issues +- Helm version compatibility +- And more... + ## Additional Resources - **Mozcloud Chart Repository**: https://github.com/mozilla/helm-charts - **Render-diff Tool**: https://github.com/mozilla/mozcloud/tree/main/tools/render-diff - **Migration Documentation**: See `.migration/README.md` in any migrated chart for detailed progress and decisions +- **Complete Skill Documentation**: See `SKILL.md` for full implementation details ## Support diff --git a/claude/skills/mozcloud-chart-migration/SKILL.md b/claude/skills/mozcloud-chart-migration/SKILL.md index 6ae2794..c35d191 100644 --- a/claude/skills/mozcloud-chart-migration/SKILL.md +++ b/claude/skills/mozcloud-chart-migration/SKILL.md @@ -33,10 +33,12 @@ Our main goal is to end up with a chart that has no templates if possible. The v ## Mozcloud Chart Context -- Download the latest version of the `mozcloud` chart from this OCI repository: `oci://us-west1-docker.pkg.dev/moz-fx-platform-artifacts/mozcloud-charts` +- Download the latest version of the `mozcloud` chart from this OCI repository: `oci://us-west1-docker.pkg.dev/moz-fx-platform-artifacts/mozcloud-charts/mozcloud` - Use the most recent values.yaml and values.schema.json from the `mozcloud` chart when converting charts to the mozcloud format - The mozcloud chart follows a specific schema that must be adhered to for successful migration +**See [references/mozcloud-chart-reference.md](references/mozcloud-chart-reference.md) for complete chart details, schema information, and migration patterns.** + ## Custom Chart Context Custom charts will generally have templates and values files. @@ -75,35 +77,95 @@ Before starting the migration, verify the following: ``` 4. **OCI Registry Access**: Verify mozcloud chart is accessible from OCI registry: ```bash - helm show chart oci://us-west1-docker.pkg.dev/moz-fx-platform-artifacts/mozcloud-charts/mozcloud --version + helm show chart oci://us-west1-docker.pkg.dev/moz-fx-platform-artifacts/mozcloud-charts/application --version ``` +## Working Directory Management + +**CRITICAL**: Always use absolute paths with `$CHART_DIR` variable to prevent files from being created in wrong locations. + +Quick reference: +```bash +# Capture chart root at start +CHART_DIR=$(pwd) + +# Always use absolute paths +mkdir -p $CHART_DIR/.migration/manifests/dev +helm template . -f $CHART_DIR/values.yaml > $CHART_DIR/.migration/manifests/dev/original.yaml + +# Return to chart root after helm operations +cd $CHART_DIR && pwd +``` + +**See [references/working-directory-management.md](references/working-directory-management.md) for complete guidance on directory management, safety checks, and why this matters.** + ## Setup -- Using `git` create a new branch called `claude-migration-$CHART_NAME-$ENV` where `$CHART_NAME` and `$ENV` match the target chart and environment values file. - - Example: `claude-migration-cicd-demos-dev` - - For uniqueness, you may append a date if needed: `claude-migration-$CHART_NAME-$ENV-$(date +%Y%m%d)` -- Create a `.migration` directory inside the chart that we are migrating if it does not already exist. - - Store any temporary files, migration documentation, and related files in this directory for easy cleanup after the migration is complete. +**Step 1: Capture chart root directory:** + +```bash +CHART_DIR=$(pwd) +echo "Chart root: $CHART_DIR" + +# Verify we're in a chart directory +if [ ! -f "$CHART_DIR/Chart.yaml" ]; then + echo "ERROR: Chart.yaml not found. Not in a chart directory." + exit 1 +fi +``` + +**Step 2: Create migration branch:** + +Using `git` create a new branch called `claude-migration-$CHART_NAME-$ENV` where `$CHART_NAME` and `$ENV` match the target chart and environment values file. +- Example: `claude-migration-cicd-demos-dev` +- For uniqueness, you may append a date if needed: `claude-migration-$CHART_NAME-$ENV-$(date +%Y%m%d)` + +**Step 3: Create migration directory structure:** + +```bash +# Use absolute path with $CHART_DIR variable +mkdir -p $CHART_DIR/.migration/manifests/{dev,stage,prod} + +# Verify directory was created in correct location +ls -la $CHART_DIR/.migration/ +``` + +**Step 4: Download mozcloud reference chart:** + +```bash +# Download to .migration directory using absolute path +helm pull oci://us-west1-docker.pkg.dev/moz-fx-platform-artifacts/mozcloud-charts/mozcloud \ + --version \ + --untar \ + --untardir $CHART_DIR/.migration/ + +# IMPORTANT: Return to chart root (helm operations may change directory) +cd $CHART_DIR +pwd # Verify location + +# Verify mozcloud chart was downloaded correctly +ls -la $CHART_DIR/.migration/mozcloud/ +``` + +Store any temporary files, migration documentation, and related files in the `.migration` directory for easy cleanup after the migration is complete. ## Migration Directory Structure -The `.migration` directory will maintain all migration-related documentation and artifacts: +The `.migration` directory maintains all migration-related documentation and artifacts: ``` .migration/ -├── README.md # Current status, next steps, decisions (ENTRY POINT) +├── README.md # ENTRY POINT - current status, next steps ├── STATUS.md # Multi-environment progress tracker -├── SUMMARY.md # High-level migration overview (optional) -├── MIGRATION_PLAN_$ENV.md # Detailed plan for each environment -├── CHANGES_$ENV.md # Resource name changes per environment -├── DIFF_ANALYSIS_$ENV.md # Structured diff analysis per environment -└── manifests/ # Original rendered manifests for comparison - ├── dev/ - ├── stage/ - └── prod/ +├── MIGRATION_PLAN_$ENV.md # Detailed plan per environment +├── CHANGES_$ENV.md # Change log per environment +├── DIFF_ANALYSIS_$ENV.md # Diff analysis per environment +├── mozcloud/ # Downloaded mozcloud chart reference +└── manifests/$ENV/ # Original & migrated manifests ``` +**See [references/migration-directory-structure.md](references/migration-directory-structure.md) for complete details, file purposes, and examples.** + ## Resuming a Migration **ALWAYS start by reading `.migration/README.md` first** - it is the entry point for understanding current state. @@ -171,7 +233,18 @@ When continuing work on an existing migration: - Render the helm chart with the current values files using `helm template` - Store the rendered manifests in `.migration/manifests/$ENV/` directory ```bash - helm template . -f values.yaml -f values-$ENV.yaml > .migration/manifests/$ENV/original.yaml + # Ensure we have the chart root path + CHART_DIR=$(pwd) + + # Render using absolute paths + helm template . \ + -f $CHART_DIR/values.yaml \ + -f $CHART_DIR/values-$ENV.yaml \ + > $CHART_DIR/.migration/manifests/$ENV/original.yaml + + # Verify file was created in correct location + ls -lh $CHART_DIR/.migration/manifests/$ENV/original.yaml + wc -l $CHART_DIR/.migration/manifests/$ENV/original.yaml ``` 4. **Create initial diff analysis template:** @@ -288,7 +361,14 @@ After completing the migration, perform these validation steps in order: - Document any semantic differences in `.migration/CHANGES_$ENV.md` 2. **Enhanced Diff Analysis**: - - Render the new chart: `helm template . -f values.yaml -f values-$ENV.yaml > .migration/manifests/$ENV/migrated.yaml` + - Render the new chart using absolute paths: + ```bash + CHART_DIR=$(pwd) + helm template . \ + -f $CHART_DIR/values.yaml \ + -f $CHART_DIR/values-$ENV.yaml \ + > $CHART_DIR/.migration/manifests/$ENV/migrated.yaml + ``` - Perform detailed comparison and populate `.migration/DIFF_ANALYSIS_$ENV.md`: ```markdown ## Resource Impact Summary @@ -320,7 +400,12 @@ After completing the migration, perform these validation steps in order: - These should show zero differences 4. **Visual Manifest Comparison**: - - Compare with original: `diff .migration/manifests/$ENV/original.yaml .migration/manifests/$ENV/migrated.yaml` + - Compare with original using absolute paths: + ```bash + CHART_DIR=$(pwd) + diff $CHART_DIR/.migration/manifests/$ENV/original.yaml \ + $CHART_DIR/.migration/manifests/$ENV/migrated.yaml + ``` - Review any differences and ensure they are intentional 5. **Regional Values Files** (if applicable): @@ -362,32 +447,27 @@ After ALL environments have been successfully migrated: ## Troubleshooting Common Issues -### Render-diff shows missing resources -- Check that mozcloud dependency is enabled in values -- Verify workload names match original deployment names -- Review template gating conditions - -### Chart.lock conflicts -- Run `helm dependency update` after modifying Chart.yaml -- Ensure helm-charts repository is accessible - -### Resource names changing unexpectedly -- Verify mozcloud workload key matches full original name -- Check for nameOverride or fullnameOverride in values -- Review mozcloud chart's naming conventions in values.schema.json +Common issues and solutions: +- **Render-diff shows missing resources**: Check mozcloud dependency enabled, verify workload names match original +- **Chart.lock conflicts**: Run `helm dependency update` after modifying Chart.yaml +- **Resource names changing**: Verify workload key matches full original deployment name +- **Non-migrated environments showing differences**: Check template gating and mozcloud.enabled flag -### Non-migrated environments showing differences -- Ensure template gating is working correctly -- Verify conditional logic in templates -- Check that mozcloud dependency is disabled for those environments +**See [references/troubleshooting.md](references/troubleshooting.md) for complete troubleshooting guide with detailed solutions.** ## Summary -1. Always read `.migration/README.md` first - it is the entry point -2. Use `.migration` directory for all migration artifacts -3. Preserve resource names as PRIMARY goal -4. Test thoroughly with `render-diff` - - Use `helm template` to compare manifests if `render-diff` fails or is unavailable -5. Document all decisions and changes -6. Never commit - user reviews first -7. Update README.md at milestones for clear handoff +### Critical Principles +1. **Working Directory Management**: Always use `$CHART_DIR` variable with absolute paths (see [references/working-directory-management.md](references/working-directory-management.md)) +2. **Entry Point**: Always read `.migration/README.md` first when resuming work +3. **Resource Names**: Preserve original names as PRIMARY goal - require approval for any changes +4. **Environment Isolation**: Migrate one environment at a time, verify others show no changes +5. **Validation**: Test thoroughly with `render-diff` before suggesting commit +6. **Documentation**: Update migration docs at each milestone for clear handoff +7. **Safety**: Never commit - user reviews first + +### Reference Documentation +- [Mozcloud Chart Reference](references/mozcloud-chart-reference.md) - Chart details, schema, patterns +- [Working Directory Management](references/working-directory-management.md) - Absolute paths, safety checks +- [Migration Directory Structure](references/migration-directory-structure.md) - File purposes, examples +- [Troubleshooting](references/troubleshooting.md) - Common issues and solutions diff --git a/claude/skills/mozcloud-chart-migration/references/migration-directory-structure.md b/claude/skills/mozcloud-chart-migration/references/migration-directory-structure.md new file mode 100644 index 0000000..f37b1c9 --- /dev/null +++ b/claude/skills/mozcloud-chart-migration/references/migration-directory-structure.md @@ -0,0 +1,300 @@ +# Migration Directory Structure + +The `.migration` directory maintains all migration-related documentation and artifacts during the migration process. + +## Directory Layout + +``` +.migration/ +├── README.md # Current status, next steps, decisions (ENTRY POINT) +├── STATUS.md # Multi-environment progress tracker +├── SUMMARY.md # High-level migration overview (optional) +├── MIGRATION_PLAN_$ENV.md # Detailed plan for each environment +├── CHANGES_$ENV.md # Resource name changes per environment +├── DIFF_ANALYSIS_$ENV.md # Structured diff analysis per environment +├── mozcloud/ # Reference copy of mozcloud chart +│ ├── Chart.yaml +│ ├── values.yaml +│ ├── values.schema.json +│ └── templates/ +└── manifests/ # Original rendered manifests for comparison + ├── dev/ + │ ├── original.yaml + │ └── migrated.yaml + ├── stage/ + │ ├── original.yaml + │ └── migrated.yaml + └── prod/ + ├── original.yaml + └── migrated.yaml +``` + +## File Purposes + +### README.md (Entry Point) +**Purpose**: Single source of truth for current migration state + +**Contents**: +- Current environment being migrated +- Migration branch name +- What's been completed +- What's pending +- Next steps +- Blockers or decisions needed +- Important notes and context + +**Example**: +```markdown +# Migration Status + +**Current Environment**: dev +**Branch**: claude-migration-my-app-dev +**Started**: 2024-01-15 + +## Completed +- ✅ Pre-flight checks passed +- ✅ Migration plan created and approved +- ✅ Values files converted to mozcloud format +- ✅ Templates gated for dev environment + +## In Progress +- 🔄 Testing with render-diff +- 🔄 Reviewing diff analysis + +## Next Steps +1. Address any semantic differences found +2. Get user approval on final changes +3. Update STATUS.md +4. Prepare for stage environment migration + +## Important Notes +- Preserved all original deployment names +- Added one new ExternalSecret for database credentials +- No changes to stage/prod environments confirmed + +## Blockers +None +``` + +### STATUS.md (Multi-Environment Tracker) +**Purpose**: Track progress across all environments + +**Example**: +```markdown +# Migration Progress + +| Environment | Status | Branch | Merged | Notes | +|-------------|--------|--------|--------|-------| +| dev | Completed | claude-migration-my-app-dev | 2024-01-16 | All tests passed | +| stage | In Progress | claude-migration-my-app-stage | - | Started 2024-01-17 | +| stage-europe-west1 | Not Started | - | - | Blocked: waiting for stage | +| prod | Not Started | - | - | Blocked: waiting for stage | + +## Current Focus +- **Environment**: stage +- **Branch**: claude-migration-my-app-stage +- **Started**: 2024-01-17 +- **Expected Completion**: TBD + +## Lessons Learned +- Dev migration revealed nginx version mismatch (resolved) +- Template gating pattern works well +- render-diff caught subtle label differences +``` + +### MIGRATION_PLAN_$ENV.md (Per-Environment Plan) +**Purpose**: Detailed implementation plan for specific environment + +**Example**: +```markdown +# Migration Plan: dev Environment + +## Current State Analysis + +### Existing Resources +- 1 Deployment: `my-app` +- 1 Service: `my-app-service` +- 1 ConfigMap: `my-app-config` +- 1 ExternalSecret: `my-app-db-secret` +- 1 HTTPRoute: `my-app-route` + +### Dependencies +- Chart.yaml lists: common-0.1.0 (will be replaced) + +## Proposed Changes + +### Chart.yaml +- Add mozcloud dependency with condition +- Remove common chart dependency +- Version: keep current chart version + +### values.yaml +- Add `mozcloud.enabled: false` as default +- Keep all existing values for non-migrated envs + +### values-dev.yaml +- Set `mozcloud.enabled: true` +- Convert deployment config to `mozcloud.workloads.my-app` +- Convert service config to `mozcloud.services.my-app-service` +- Convert config to `mozcloud.configMaps.my-app-config` +- Convert secret to `mozcloud.externalSecrets.my-app-db-secret` +- Convert route to `mozcloud.httpRoutes.my-app-route` + +### Templates +- Wrap deployment.yaml in `{{- if not .Values.mozcloud.enabled }}` +- Wrap service.yaml in `{{- if not .Values.mozcloud.enabled }}` +- Wrap configmap.yaml in `{{- if not .Values.mozcloud.enabled }}` +- Wrap externalsecret.yaml in `{{- if not .Values.mozcloud.enabled }}` +- Wrap httproute.yaml in `{{- if not .Values.mozcloud.enabled }}` + +## Resource Name Mapping +All names preserved - no changes required: +- Deployment: `my-app` → `workloads.my-app` +- Service: `my-app-service` → `services.my-app-service` +- ConfigMap: `my-app-config` → `configMaps.my-app-config` +- ExternalSecret: `my-app-db-secret` → `externalSecrets.my-app-db-secret` +- HTTPRoute: `my-app-route` → `httpRoutes.my-app-route` + +## Testing Strategy +1. render-diff for dev environment +2. render-diff for stage/prod (should show no changes) +3. Manual review of generated manifests +4. Validate resource count matches + +## Risks +- Low risk: straightforward migration +- All resource names preserved +- Templates properly gated +``` + +### CHANGES_$ENV.md (Change Log) +**Purpose**: Detailed log of all changes made + +**Example**: +```markdown +# Changes Log: dev Environment + +## Chart.yaml +- Added mozcloud dependency (version 1.2.3) +- Added condition: `mozcloud.enabled` +- Removed common chart dependency + +## values.yaml +- Added `mozcloud.enabled: false` (default off) + +## values-dev.yaml +- Set `mozcloud.enabled: true` +- Added complete mozcloud configuration: + - workloads.my-app (Deployment) + - services.my-app-service + - configMaps.my-app-config + - externalSecrets.my-app-db-secret + - httpRoutes.my-app-route + +## Templates Modified +- templates/deployment.yaml: wrapped in mozcloud.enabled check +- templates/service.yaml: wrapped in mozcloud.enabled check +- templates/configmap.yaml: wrapped in mozcloud.enabled check +- templates/externalsecret.yaml: wrapped in mozcloud.enabled check +- templates/httproute.yaml: wrapped in mozcloud.enabled check + +## Resource Name Changes +None - all original names preserved. + +## New Resources +None - 1:1 mapping from original. + +## Deleted Resources +None - templates preserved for other environments. + +## Configuration Changes +- Image tag updated from 1.0.0 to 1.0.1 (intentional) +- Added new environment variable: DATABASE_POOL_SIZE=10 +``` + +### DIFF_ANALYSIS_$ENV.md (Diff Analysis) +**Purpose**: Structured analysis of differences between original and migrated + +**Example**: +```markdown +# Diff Analysis: dev Environment + +## Resource Impact Summary +- **Added**: 0 resources +- **Modified**: 1 resource +- **Deleted**: 0 resources +- **Unchanged**: 4 resources + +## Modified Resources + +### Deployment "my-app" +**Changes**: +- Environment variable added: `DATABASE_POOL_SIZE=10` +- Image tag changed: `1.0.0` → `1.0.1` + +**Impact**: Will trigger pod restart + +**Reason**: Intentional updates from user + +## Unchanged Resources +- Service "my-app-service" - No changes +- ConfigMap "my-app-config" - No changes +- ExternalSecret "my-app-db-secret" - No changes +- HTTPRoute "my-app-route" - No changes + +## Changes That May Trigger Pod Restarts +1. Deployment "my-app": + - Environment variable addition + - Image tag change + +## Critical Changes Requiring Review +None - all changes are intentional and expected. + +## Semantic Differences +None detected by render-diff. + +## Validation Results +✅ Resource count: 5 original → 5 migrated +✅ Resource names: All preserved +✅ Non-migrated environments: No changes detected +✅ render-diff: Semantic equivalence confirmed +``` + +## Best Practices + +### Always Start with README.md +When resuming work or understanding current state, read `.migration/README.md` first. + +### Keep Documentation Current +Update files after each major milestone: +- Complete a phase → Update README.md +- Finish environment → Update STATUS.md +- Make changes → Update CHANGES_$ENV.md +- Review diffs → Update DIFF_ANALYSIS_$ENV.md + +### Use for Handoffs +When pausing work or handing off to another engineer: +1. Update README.md with current status +2. Document blockers and decisions needed +3. List clear next steps +4. Note any important context + +### Clean Up After Completion +After ALL environments are migrated: +- Archive `.migration/` directory or delete it +- Key documentation can be moved to repo wiki/docs if needed +- Manifest comparisons no longer needed once all envs are live + +## Storage Location +The `.migration/` directory should be in the chart root: +``` +charts/my-app/ +├── .migration/ # ← Here +├── Chart.yaml +├── values.yaml +├── values-dev.yaml +├── templates/ +└── ... +``` + +Use `$CHART_DIR/.migration/` to ensure correct location. diff --git a/claude/skills/mozcloud-chart-migration/references/mozcloud-chart-reference.md b/claude/skills/mozcloud-chart-migration/references/mozcloud-chart-reference.md new file mode 100644 index 0000000..5324a7e --- /dev/null +++ b/claude/skills/mozcloud-chart-migration/references/mozcloud-chart-reference.md @@ -0,0 +1,166 @@ +# Mozcloud Chart Reference + +## Chart Location + +- **OCI Repository**: `oci://us-west1-docker.pkg.dev/moz-fx-platform-artifacts/mozcloud-charts/mozcloud` +- **Chart Type**: Application chart (not library) +- **Version Strategy**: Always use the latest version + +## Downloading the Chart + +During migration setup, download the latest mozcloud chart for reference: + +```bash +# Check latest version +helm show chart oci://us-west1-docker.pkg.dev/moz-fx-platform-artifacts/mozcloud-charts/mozcloud + +# Download to migration directory +helm pull oci://us-west1-docker.pkg.dev/moz-fx-platform-artifacts/mozcloud-charts/mozcloud \ + --version \ + --untar \ + --untardir $CHART_DIR/.migration/ + +# Return to chart root +cd $CHART_DIR +``` + +## Key Files to Reference + +Once downloaded to `.migration/mozcloud/`, reference these files: + +1. **`values.yaml`** - Default values and structure +2. **`values.schema.json`** - Schema validation and documentation +3. **`templates/`** - Understanding what resources mozcloud generates + +## Chart Dependency Configuration + +Add mozcloud as a dependency in the target chart's `Chart.yaml`: + +```yaml +dependencies: + - name: mozcloud + version: "" + repository: "oci://us-west1-docker.pkg.dev/moz-fx-platform-artifacts/mozcloud-charts" + condition: mozcloud.enabled +``` + +## Values File Structure + +The mozcloud chart expects values in this general structure: + +```yaml +mozcloud: + enabled: true # Toggle for environment-specific migrations + + # Workloads (Deployments/Rollouts/CronJobs) + workloads: + : # Use FULL original deployment name + type: deployment # or rollout, cronjob + image: + repository: ... + tag: ... + # ... other workload config + + # Services + services: + : + # ... service config + + # Ingress/HTTPRoutes + httpRoutes: + : + # ... routing config + + # ConfigMaps/Secrets + configMaps: + : + # ... config + + externalSecrets: + : + # ... secret config +``` + +## Important Notes + +### Version Compatibility +- Check for nginx image version: if custom chart uses `us-west1-docker.pkg.dev/moz-fx-platform-artifacts/platform-shared-images/nginx-unprivileged:1.22`, use the latest from mozcloud instead +- Mozcloud chart may have newer versions of common dependencies + +### Naming Conventions +- **Workload names become Deployment names**: Use full original names as workload keys +- **Service names**: Typically match workload names unless explicitly different +- **ConfigMap/Secret names**: Preserve exact original names to avoid reference breaks + +### Schema Validation +- The `values.schema.json` file provides validation rules +- Review it to understand required vs optional fields +- Check for enum values (e.g., workload types, service types) + +## Common Migration Patterns + +### Converting a Deployment +```yaml +# Original custom chart +# templates/deployment.yaml with values.yaml: +# image: my-app:v1.0.0 +# replicas: 3 + +# Mozcloud equivalent +mozcloud: + workloads: + my-app-deployment: # Preserve full original name + type: deployment + image: + repository: my-app + tag: v1.0.0 + replicas: 3 +``` + +### Converting a Service +```yaml +# Original custom chart +# templates/service.yaml + +# Mozcloud equivalent +mozcloud: + services: + my-app-service: # Preserve original service name + ports: + - name: http + port: 8080 + targetPort: 8080 +``` + +### Converting HTTPRoute/Ingress +```yaml +# Original custom chart +# templates/ingress.yaml or httproute.yaml + +# Mozcloud equivalent +mozcloud: + httpRoutes: + my-app-route: + hostnames: + - my-app.example.com + rules: + - backendRefs: + - name: my-app-service + port: 8080 +``` + +## Troubleshooting Chart Issues + +### Chart Not Found +- Verify OCI registry authentication: `gcloud auth configure-docker us-west1-docker.pkg.dev` +- Check network connectivity to GCP Artifact Registry + +### Schema Validation Errors +- Run `helm lint` to see schema violations +- Compare your values structure with `.migration/mozcloud/values.yaml` +- Check `values.schema.json` for required fields + +### Unexpected Resource Names +- Review mozcloud templates to understand naming logic +- Check for `nameOverride` or `fullnameOverride` in values +- Ensure workload keys match full original deployment names diff --git a/claude/skills/mozcloud-chart-migration/references/troubleshooting.md b/claude/skills/mozcloud-chart-migration/references/troubleshooting.md new file mode 100644 index 0000000..67bdf28 --- /dev/null +++ b/claude/skills/mozcloud-chart-migration/references/troubleshooting.md @@ -0,0 +1,250 @@ +# Troubleshooting Common Issues + +## Render-diff shows missing resources + +**Symptoms:** +- `render-diff` reports fewer resources in migrated chart +- Expected resources not appearing in output + +**Solutions:** +- Check that mozcloud dependency is enabled in values +- Verify workload names match original deployment names +- Review template gating conditions +- Ensure custom templates are properly disabled for migrated environment +- Run `helm template` manually to see what's being rendered: + ```bash + helm template . -f values.yaml -f values-dev.yaml | grep -E "^kind:" + ``` + +## Chart.lock conflicts + +**Symptoms:** +- `helm template` fails with dependency errors +- Chart.lock shows wrong versions +- "dependency update needed" messages + +**Solutions:** +- Run `helm dependency update` after modifying Chart.yaml +- Ensure OCI registry is accessible +- Delete Chart.lock and regenerate: + ```bash + rm Chart.lock + helm dependency update + ``` +- Verify dependency versions match Chart.yaml + +## Resource names changing unexpectedly + +**Symptoms:** +- Deployment names differ from original +- Service names don't match expected values +- ConfigMap/Secret references break + +**Solutions:** +- Verify mozcloud workload key matches full original name + - Use `gha-fxa-profile-worker`, NOT `profile-worker` +- Check for `nameOverride` or `fullnameOverride` in values +- Review mozcloud chart's naming conventions in `values.schema.json` +- Compare rendered manifests side-by-side: + ```bash + diff <(kubectl get all --dry-run -o yaml) .migration/manifests/dev/migrated.yaml + ``` + +## Non-migrated environments showing differences + +**Symptoms:** +- `render-diff -f values-stage.yaml` shows changes when only dev was migrated +- Other environments rendering mozcloud resources unexpectedly + +**Solutions:** +- Ensure template gating is working correctly +- Verify conditional logic in templates: + ```yaml + {{- if not .Values.mozcloud.enabled }} + # original template content + {{- end }} + ``` +- Check that mozcloud dependency is disabled for those environments: + ```yaml + # values-stage.yaml + mozcloud: + enabled: false + ``` +- Verify Chart.yaml dependency condition: + ```yaml + dependencies: + - name: mozcloud + condition: mozcloud.enabled # Must be present + ``` + +## Files created in wrong location + +**Symptoms:** +- `.migration/` directory appears in wrong place +- Migration artifacts scattered across repo +- Can't find generated files + +**Solutions:** +- Verify `$CHART_DIR` variable is set correctly: + ```bash + echo $CHART_DIR + ls -la $CHART_DIR/Chart.yaml # Should exist + ``` +- Always use absolute paths with `$CHART_DIR` +- Return to chart root after helm operations: + ```bash + cd $CHART_DIR + pwd + ``` +- See [Working Directory Management](./working-directory-management.md) for complete guidance + +## Helm version 4 compatibility issues + +**Symptoms:** +- `helm version` shows v4.x.x +- Unexpected behavior or errors + +**Solutions:** +- Helm v4 has breaking changes +- Use Helm v3 for compatibility: + ```bash + # Check version + helm version --short + + # If v4, install v3 (example for macOS) + brew install helm@3 + ``` + +## OCI registry authentication failures + +**Symptoms:** +- "unauthorized" errors when pulling mozcloud chart +- "failed to authorize" messages +- Cannot access artifact registry + +**Solutions:** +- Authenticate to GCP Artifact Registry: + ```bash + gcloud auth configure-docker us-west1-docker.pkg.dev + ``` +- Verify you have access to the project: + ```bash + gcloud projects list + ``` +- Check active account: + ```bash + gcloud auth list + ``` +- Try pulling chart manually: + ```bash + helm pull oci://us-west1-docker.pkg.dev/moz-fx-platform-artifacts/mozcloud-charts/mozcloud + ``` + +## render-diff tool not found + +**Symptoms:** +- `which render-diff` returns nothing +- Command not found errors + +**Solutions:** +- Install from mozcloud repository: + ```bash + cd /path/to/mozcloud/tools/render-diff + go install + ``` +- Verify installation: + ```bash + which render-diff + render-diff --help + ``` +- Add to PATH if needed: + ```bash + export PATH="$PATH:$(go env GOPATH)/bin" + ``` + +## Schema validation errors + +**Symptoms:** +- `helm lint` fails +- Schema validation errors during template rendering +- "does not match schema" messages + +**Solutions:** +- Review `.migration/mozcloud/values.schema.json` +- Compare your values structure with schema requirements +- Check for: + - Required fields that are missing + - Incorrect value types (string vs number) + - Invalid enum values +- Run detailed validation: + ```bash + helm lint . -f values.yaml -f values-dev.yaml + ``` + +## Resource count mismatch + +**Symptoms:** +- Original chart renders 10 resources, migrated chart renders 8 +- Missing resources in diff + +**Solutions:** +- List resources in both versions: + ```bash + # Original + helm template . -f values.yaml -f values-dev.yaml | grep -E "^kind:" | sort + + # Migrated (ensure mozcloud enabled) + helm template . -f values.yaml -f values-dev.yaml | grep -E "^kind:" | sort + ``` +- Check `.migration/DIFF_ANALYSIS_dev.md` for detailed comparison +- Verify all resource types are configured in mozcloud values +- Check if mozcloud auto-generates resources (like ExternalSecrets) + +## Regional values files not working + +**Symptoms:** +- Multi-region deployments failing +- `values-stage-europe-west1.yaml` not being applied + +**Solutions:** +- Test with both files: + ```bash + render-diff -f values-stage.yaml -f values-stage-europe-west1.yaml -su + ``` +- Ensure proper layering (base → environment → region): + ```bash + helm template . \ + -f values.yaml \ + -f values-stage.yaml \ + -f values-stage-europe-west1.yaml + ``` +- Verify regional overrides are properly structured + +## Git merge conflicts in Chart.lock + +**Symptoms:** +- Merge conflicts when updating Chart.lock +- Lock file out of sync + +**Solutions:** +- Always regenerate Chart.lock after merging: + ```bash + git checkout --theirs Chart.lock # or --ours + helm dependency update + git add Chart.lock + ``` +- Never manually edit Chart.lock +- Ensure Chart.yaml is correct before regenerating lock + +## Migration documentation out of sync + +**Symptoms:** +- `.migration/README.md` doesn't reflect current state +- Confusion about what's been completed + +**Solutions:** +- Always read `.migration/README.md` first before making changes +- Update documentation after each major milestone +- Keep STATUS.md current with environment progress +- Use CHANGES_*.md to track all modifications +- Review and update before handing off or pausing work diff --git a/claude/skills/mozcloud-chart-migration/references/working-directory-management.md b/claude/skills/mozcloud-chart-migration/references/working-directory-management.md new file mode 100644 index 0000000..d606160 --- /dev/null +++ b/claude/skills/mozcloud-chart-migration/references/working-directory-management.md @@ -0,0 +1,83 @@ +# Working Directory Management + +**CRITICAL**: Maintain consistent working directory throughout the migration to avoid creating files in wrong locations. + +## Capture Chart Root Directory + +At the start of migration, capture and verify the chart root directory: + +```bash +CHART_DIR=$(pwd) +echo "Chart directory: $CHART_DIR" + +# Verify Chart.yaml exists +if [ ! -f "$CHART_DIR/Chart.yaml" ]; then + echo "ERROR: Chart.yaml not found in $CHART_DIR" + exit 1 +fi +``` + +## Always Use Absolute Paths + +**For ALL file operations, use the $CHART_DIR variable:** + +✓ **GOOD Examples:** +```bash +# Creating directories +mkdir -p $CHART_DIR/.migration/manifests/dev + +# Rendering manifests +helm template . -f $CHART_DIR/values.yaml -f $CHART_DIR/values-dev.yaml > $CHART_DIR/.migration/manifests/dev/original.yaml + +# Writing documentation +cat > $CHART_DIR/.migration/README.md < .migration/manifests/dev/original.yaml +``` + +## Verify Working Directory After Helm Operations + +Some helm operations may change the working directory context. Always verify location after: + +```bash +# After helm pull +helm pull oci://... --untar --untardir $CHART_DIR/.migration/ +cd $CHART_DIR # Return to chart root +pwd # Verify we're in the correct location + +# After any helm command that might change context +cd $CHART_DIR +``` + +## Directory Creation Safety Check + +Before creating any files in `.migration/`, verify location: + +```bash +# Sanity check before file operations +if [ ! -f "$CHART_DIR/Chart.yaml" ]; then + echo "ERROR: Not in chart directory. Current: $(pwd)" + exit 1 +fi + +# Now safe to create files +mkdir -p $CHART_DIR/.migration/manifests/dev +``` + +**Why this matters:** Some helm operations (particularly `helm pull`) may change the working directory context. Using absolute paths with the `$CHART_DIR` variable prevents accidentally creating migration artifacts in nested or incorrect locations. + +## Summary + +1. **Capture `$CHART_DIR` at the start** of every migration session +2. **Use absolute paths** with `$CHART_DIR` for all file operations +3. **Verify location** after helm commands that might change directory +4. **Sanity check** before creating migration artifacts From 6d8ed8b92bd7a5be4e562c63455b1258dde6fd04 Mon Sep 17 00:00:00 2001 From: Dustin Lactin Date: Mon, 2 Mar 2026 14:36:11 -0700 Subject: [PATCH 2/5] fix: fixed chart name in OCI registry access command --- claude/skills/mozcloud-chart-migration/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/claude/skills/mozcloud-chart-migration/SKILL.md b/claude/skills/mozcloud-chart-migration/SKILL.md index c35d191..2919245 100644 --- a/claude/skills/mozcloud-chart-migration/SKILL.md +++ b/claude/skills/mozcloud-chart-migration/SKILL.md @@ -77,7 +77,7 @@ Before starting the migration, verify the following: ``` 4. **OCI Registry Access**: Verify mozcloud chart is accessible from OCI registry: ```bash - helm show chart oci://us-west1-docker.pkg.dev/moz-fx-platform-artifacts/mozcloud-charts/application --version + helm show chart oci://us-west1-docker.pkg.dev/moz-fx-platform-artifacts/mozcloud-charts/mozcloud --version ``` ## Working Directory Management From d5cdc7684b6a1b94806d3490663a01ee5accd7a7 Mon Sep 17 00:00:00 2001 From: Dustin Lactin Date: Mon, 2 Mar 2026 14:59:08 -0700 Subject: [PATCH 3/5] refactor: removed emojis, updated docs and added tools-and-permimssions reference --- .../skills/mozcloud-chart-migration/README.md | 7 + .../skills/mozcloud-chart-migration/SKILL.md | 29 ++- .../migration-directory-structure.md | 20 +- .../references/tools-and-permissions.md | 244 ++++++++++++++++++ .../working-directory-management.md | 57 +++- 5 files changed, 340 insertions(+), 17 deletions(-) create mode 100644 claude/skills/mozcloud-chart-migration/references/tools-and-permissions.md diff --git a/claude/skills/mozcloud-chart-migration/README.md b/claude/skills/mozcloud-chart-migration/README.md index 11e6cd1..e8b8cdf 100644 --- a/claude/skills/mozcloud-chart-migration/README.md +++ b/claude/skills/mozcloud-chart-migration/README.md @@ -236,6 +236,13 @@ cd charts/my-app Detailed implementation documentation is available in the `references/` directory: +### [Tools and Permissions](references/tools-and-permissions.md) +Lists tools that can be used without user prompts: +- Read-only commands (pwd, ls, git status, etc.) +- Helm commands (helm version, helm template, etc.) +- Validation tools (render-diff, diff) +- Prohibited commands that require approval + ### [Working Directory Management](references/working-directory-management.md) **Critical for preventing files from being created in wrong locations.** diff --git a/claude/skills/mozcloud-chart-migration/SKILL.md b/claude/skills/mozcloud-chart-migration/SKILL.md index 2919245..3ca7876 100644 --- a/claude/skills/mozcloud-chart-migration/SKILL.md +++ b/claude/skills/mozcloud-chart-migration/SKILL.md @@ -62,6 +62,15 @@ We want to convert environments one at a time starting with `values-dev.yaml` if - Map their response to the corresponding values file (e.g., "dev" → "values-dev.yaml") - Default to values-dev.yaml only if it exists and no other selection is made +## Tools and Permissions + +**Critical Rules:** +- Read-only commands (pwd, ls, git status, helm template, render-diff, etc.) can be used freely +- NEVER use: Environment access (env, echo $VAR), Helm deployments (helm install/upgrade/delete), kubectl commands +- Require approval: Git modifications (git commit/push), file operations + +**See [references/tools-and-permissions.md](references/tools-and-permissions.md) for complete list, examples, and how to handle prohibited command requests.** + ## Pre-flight Checks Before starting the migration, verify the following: @@ -439,11 +448,20 @@ After ALL environments have been successfully migrated: ## Security -- **Never commit any changes to git** - user will review and commit -- **Never run `helm upgrade`, `helm install`, `helm delete`** or any other destructive commands -- Do not write to any directories outside of the chart being migrated - - Any writes should be to the values files, templates and helpers we're migrating or in the local `.migration` directory -- Always verify changes with render-diff before suggesting the user commit +**Strictly Prohibited (Never Use, Even With Approval):** +- **Never access environment variables** (`env`, `printenv`, `echo $VAR`, `export`) - risk of exposing secrets +- **Never run Helm deployment commands** (`helm install`, `helm upgrade`, `helm delete`, `helm rollback`) - deployments happen via ArgoCD +- **Never run kubectl commands** - this skill prepares configurations, ArgoCD handles deployment +- If user requests these, politely refuse and explain why (see [references/tools-and-permissions.md](references/tools-and-permissions.md)) + +**General Security Practices:** +- **Never commit changes** - user will review and commit +- **Scope file writes strictly** to current chart directory (`$CHART_DIR`) only: + - Allowed: `$CHART_DIR/values.yaml`, `$CHART_DIR/.migration/*`, `$CHART_DIR/templates/*` + - Prohibited: Parent directories (`../`), other tenant directories, absolute paths outside chart, system directories + - If user requests writes outside current directory, refuse and explain scope restriction +- **Verify changes** with render-diff before suggesting the user commit +- **Preserve resource names** to avoid unintended service disruptions ## Troubleshooting Common Issues @@ -467,6 +485,7 @@ Common issues and solutions: 7. **Safety**: Never commit - user reviews first ### Reference Documentation +- [Tools and Permissions](references/tools-and-permissions.md) - Approved tools, prohibited commands - [Mozcloud Chart Reference](references/mozcloud-chart-reference.md) - Chart details, schema, patterns - [Working Directory Management](references/working-directory-management.md) - Absolute paths, safety checks - [Migration Directory Structure](references/migration-directory-structure.md) - File purposes, examples diff --git a/claude/skills/mozcloud-chart-migration/references/migration-directory-structure.md b/claude/skills/mozcloud-chart-migration/references/migration-directory-structure.md index f37b1c9..e82b986 100644 --- a/claude/skills/mozcloud-chart-migration/references/migration-directory-structure.md +++ b/claude/skills/mozcloud-chart-migration/references/migration-directory-structure.md @@ -52,14 +52,14 @@ The `.migration` directory maintains all migration-related documentation and art **Started**: 2024-01-15 ## Completed -- ✅ Pre-flight checks passed -- ✅ Migration plan created and approved -- ✅ Values files converted to mozcloud format -- ✅ Templates gated for dev environment +- [x] Pre-flight checks passed +- [x] Migration plan created and approved +- [x] Values files converted to mozcloud format +- [x] Templates gated for dev environment ## In Progress -- 🔄 Testing with render-diff -- 🔄 Reviewing diff analysis +- [ ] Testing with render-diff +- [ ] Reviewing diff analysis ## Next Steps 1. Address any semantic differences found @@ -254,10 +254,10 @@ None - all changes are intentional and expected. None detected by render-diff. ## Validation Results -✅ Resource count: 5 original → 5 migrated -✅ Resource names: All preserved -✅ Non-migrated environments: No changes detected -✅ render-diff: Semantic equivalence confirmed +- Resource count: 5 original → 5 migrated +- Resource names: All preserved +- Non-migrated environments: No changes detected +- render-diff: Semantic equivalence confirmed ``` ## Best Practices diff --git a/claude/skills/mozcloud-chart-migration/references/tools-and-permissions.md b/claude/skills/mozcloud-chart-migration/references/tools-and-permissions.md new file mode 100644 index 0000000..fb195c3 --- /dev/null +++ b/claude/skills/mozcloud-chart-migration/references/tools-and-permissions.md @@ -0,0 +1,244 @@ +# Tools and Permissions + +This document lists tools that can be used **without prompting** the user for permission during migration operations. + +## Read-Only Commands + +These basic shell commands are safe to use freely: + +- `pwd` - Print working directory +- `ls`, `ls -la`, `ls -lh` - List files and directories +- `wc -l` - Count lines in files +- `which` - Locate command binaries +- `find` - Find files (though prefer Glob tool for better performance) +- `grep` - Search content (though prefer Grep tool for better performance) + +**Note**: `echo` is **NOT** in this list due to security concerns - it could expose sensitive environment variables. Use explicit text output instead, or ask for approval first. + +## Git Commands (Read-Only) + +Git commands that only read repository state: + +- `git status` - Check repository status (staged, unstaged, untracked files) +- `git branch` - List branches (local and remote) +- `git log` - View commit history +- `git diff` - View differences between commits, working tree, etc. +- `git show` - Show commits, tags, and other objects +- `git rev-parse` - Parse git revision information + +**Examples:** +```bash +# Check if working directory is clean +git status + +# View recent commits +git log --oneline -10 + +# See what changed in a specific file +git diff HEAD -- values.yaml +``` + +## Helm Commands (Read-Only) + +Helm commands that only read or render locally without modifying state: + +- `helm version` - Check Helm version +- `helm show chart ` - Display chart metadata (Chart.yaml) +- `helm show values ` - Display default values from chart +- `helm show all ` - Display all chart information +- `helm template ` - Render templates locally (does not install) +- `helm lint ` - Validate chart structure and syntax +- `helm dependency list` - List chart dependencies +- `helm dependency build` - Build dependencies (downloads, does not install) +- `helm pull ` - Download chart (does not install) + +**Examples:** +```bash +# Check Helm version +helm version --short + +# View chart metadata +helm show chart oci://us-west1-docker.pkg.dev/.../mozcloud + +# Render templates locally +helm template . -f values.yaml -f values-dev.yaml + +# Validate chart +helm lint . +``` + +## Validation Tools + +Migration-specific validation tools: + +- `render-diff` - Compare rendered manifests (all flags and options) + - `render-diff -f values-dev.yaml` - Compare original vs migrated + - `render-diff -f values-dev.yaml -su` - Show semantic differences + - `render-diff -f values.yaml -f values-regional.yaml` - Multi-file comparison +- `diff` - Compare text files +- `kubectl diff` - Compare manifests (if cluster access available, read-only) + +**Examples:** +```bash +# Check semantic differences +render-diff -f values-dev.yaml -su + +# Manual file comparison +diff .migration/manifests/dev/original.yaml .migration/manifests/dev/migrated.yaml +``` + +## File Operations (Read-Only) + +Commands for viewing file contents (prefer dedicated tools when available): + +- `head` - View first lines of file (prefer Read tool) +- `tail` - View last lines of file (prefer Read tool) +- `cat` - Display file contents (prefer Read tool) +- `stat` - Show file information (size, permissions, timestamps) +- `file` - Determine file type + +**Note**: For reading files during migration, prefer using the Read tool over these commands, as it provides better integration with Claude Code. + +## Directory Operations + +Commands for inspecting directory structure: + +- `tree` - Display directory tree (if available) +- `du -sh` - Show directory size +- `find -type f -name "*.yaml"` - Find specific files (prefer Glob tool) + +## Strictly Prohibited Commands (NEVER Use) + +**CRITICAL**: The following commands should **NEVER** be used, even if the user requests or approves them. The skill must refuse and explain why. + +### Environment Variable Access (Security Risk) +- `env` - Lists all environment variables (exposes secrets) +- `printenv` - Prints environment variables (exposes secrets) +- `echo $VAR` - Prints variable values (exposes secrets) +- `export` - Shows/sets environment variables (exposes secrets) +- `set` - Shows all variables including environment (exposes secrets) + +**Why Prohibited**: Environment variables often contain sensitive credentials (API keys, passwords, database credentials, tokens). Exposing these could compromise security. + +**What to do instead**: If the user needs to check a value, ask them to verify it themselves in their terminal. + +### Helm Deployment Commands (Out of Scope) +- `helm install ` - Installs charts to cluster +- `helm upgrade ` - Upgrades releases +- `helm delete` / `helm uninstall` - Deletes releases +- `helm rollback` - Rolls back releases +- Any `helm` command with `--install` or `--atomic` flags + +**Why Prohibited**: This skill prepares migration configurations. **Deployments happen via ArgoCD**, not directly via Helm. Running these commands would: +- Bypass the ArgoCD deployment workflow +- Skip team review and approval processes +- Potentially deploy untested configurations +- Create state conflicts with ArgoCD + +**What to do instead**: Prepare the configuration files and let the user commit them. ArgoCD will handle deployment after merge to main. + +### Kubernetes Commands (Out of Scope) +- `kubectl apply` - Apply configuration +- `kubectl create` - Create resources +- `kubectl delete` - Delete resources +- `kubectl edit` - Edit resources +- `kubectl patch` - Patch resources +- `kubectl replace` - Replace resources +- `kubectl scale` - Scale resources +- `kubectl set` - Set resource properties +- `kubectl exec` - Execute commands in pods +- `kubectl port-forward` - Forward ports +- **Any `kubectl` command that modifies cluster state** + +**Why Prohibited**: Same reasoning as Helm commands - this skill prepares configurations, it does not deploy them. All deployments go through ArgoCD. + +**What to do instead**: Focus on generating correct values files and templates. Let ArgoCD deploy after merge. + +### Process Information (Security Risk) +- `ps aux` - Shows running processes (may reveal secrets in arguments) +- `top`, `htop` - Process viewers (may show sensitive information) + +**Why Prohibited**: Process lists may reveal secrets passed as command-line arguments. + +## How to Handle User Requests for Prohibited Commands + +If a user asks you to run a prohibited command: + +1. **Politely refuse**: Explain that the command is outside the scope of this skill +2. **Explain why**: Reference the specific reason (security risk, deployment workflow, etc.) +3. **Suggest alternatives**: + - For env/secrets: "Please check this value in your terminal" + - For deployments: "This migration prepares the configuration. After you commit and merge, ArgoCD will handle deployment" + - For kubectl: "This skill focuses on preparing Helm charts, not deploying them" + +**Example Response:** +``` +I cannot run `helm install` as this skill is designed to prepare migration +configurations, not deploy them. Your deployment workflow uses ArgoCD, which +will automatically deploy once you commit these changes and merge to main. + +This ensures proper review and follows your established deployment process. +``` + +## Commands That Require User Approval + +The following commands modify state and require explicit user approval before use: + +### Git Commands (Modifying) +- `git add` - Stage changes +- `git commit` - Create commits +- `git push` - Push to remote +- `git pull` - Pull from remote +- `git merge` - Merge branches +- `git rebase` - Rebase commits +- `git reset` - Reset state +- `git checkout` - Switch branches or restore files +- `git rm` - Remove files +- `git clean` - Clean untracked files + +**Note**: While these require approval, they are within scope for migration workflow (e.g., creating migration branches, staging files). Use judiciously and only when needed. + +### File System Commands (Modifying) +- `rm` - Remove files (dangerous, use with extreme caution) +- `mv` - Move files (prefer Edit/Write tools) +- `cp` - Copy files (only for migration artifacts) +- `mkdir` - Create directories (typically only for `.migration/` structure) + +**CRITICAL RESTRICTION**: All file writes (whether via bash commands or Write/Edit tools) must be within the current chart directory (`$CHART_DIR`). + +**Prohibited**: +- Writing to parent directories (`../`) +- Writing to absolute paths outside chart directory (`/tmp/`, `/home/`, etc.) +- Writing to other tenant directories +- Writing to system directories + +**Allowed**: +- Chart files: `$CHART_DIR/values.yaml`, `$CHART_DIR/Chart.yaml`, `$CHART_DIR/templates/*` +- Migration directory: `$CHART_DIR/.migration/*` + +**If user requests writes outside chart directory**: Refuse and explain that the skill is scoped to the current tenant chart only. + +**Note**: Prefer using Claude Code's Write, Edit, and other file tools instead of shell commands when possible. + +### Package Management (Rarely Needed) +- `brew install` / `apt install` / `yum install` - Install packages +- Any package manager commands + +**Note**: Only if user is missing required tools (render-diff, helm, etc.) and requests installation assistance. + +## Best Practices + +1. **Use dedicated tools first**: Prefer Glob over `find`, Grep over `grep`, Read over `cat` +2. **Read-only by default**: Always use read-only commands unless modification is explicitly required +3. **User approval for changes**: Any command that modifies files, git state, or remote systems requires approval +4. **Verify before acting**: Use read-only commands to verify state before suggesting modifications +5. **Document tool usage**: When using specialized tools like `render-diff`, explain what they're checking + +## Adding New Tools + +If additional tools are needed during migration: + +1. **Verify it's read-only**: Ensure the tool doesn't modify state +2. **Document its purpose**: Add to this reference with examples +3. **Update SKILL.md**: Add a brief mention in the main skill file +4. **Get user approval first**: If unsure, ask the user before using a new tool diff --git a/claude/skills/mozcloud-chart-migration/references/working-directory-management.md b/claude/skills/mozcloud-chart-migration/references/working-directory-management.md index d606160..8784d72 100644 --- a/claude/skills/mozcloud-chart-migration/references/working-directory-management.md +++ b/claude/skills/mozcloud-chart-migration/references/working-directory-management.md @@ -75,9 +75,62 @@ mkdir -p $CHART_DIR/.migration/manifests/dev **Why this matters:** Some helm operations (particularly `helm pull`) may change the working directory context. Using absolute paths with the `$CHART_DIR` variable prevents accidentally creating migration artifacts in nested or incorrect locations. +## File Write Restrictions + +**CRITICAL SECURITY REQUIREMENT**: All file writes must be scoped to the current chart directory. + +### Allowed Write Locations +- Chart configuration: `$CHART_DIR/values.yaml`, `$CHART_DIR/values-*.yaml` +- Chart definition: `$CHART_DIR/Chart.yaml`, `$CHART_DIR/Chart.lock` +- Templates: `$CHART_DIR/templates/*` +- Helpers: `$CHART_DIR/templates/_helpers.tpl` +- Migration artifacts: `$CHART_DIR/.migration/*` + +### Prohibited Write Locations +- Parent directories: `../anything` +- Other tenant charts: `/path/to/other-chart/` +- System directories: `/tmp/`, `/var/`, `/etc/`, `/home/` +- Absolute paths outside chart: `/Users/`, `/opt/`, etc. +- Root directory: Any path not starting with `$CHART_DIR` + +### Validation Before Writing + +Always validate write path before creating files: + +```bash +# Validate path is within chart directory +TARGET_PATH="/proposed/path/to/file" +if [[ "$TARGET_PATH" != "$CHART_DIR"* ]]; then + echo "ERROR: Cannot write outside chart directory" + echo "Target: $TARGET_PATH" + echo "Chart dir: $CHART_DIR" + exit 1 +fi +``` + +### Handling User Requests to Write Outside Chart + +If a user requests writing files outside the current chart directory: + +1. **Refuse politely**: Explain the scope restriction +2. **Explain why**: Security and scope - skill is for migrating this chart only +3. **Suggest alternatives**: If they need to affect other charts, run the skill from that chart's directory + +**Example Response:** +``` +I cannot write to that location as it's outside the current chart directory. +This skill is scoped to migrate only the chart in the current directory +($CHART_DIR) to prevent accidental modifications to other tenants or system files. + +If you need to migrate another chart, please run the skill from that chart's +directory instead. +``` + ## Summary 1. **Capture `$CHART_DIR` at the start** of every migration session 2. **Use absolute paths** with `$CHART_DIR` for all file operations -3. **Verify location** after helm commands that might change directory -4. **Sanity check** before creating migration artifacts +3. **Validate write paths** are within `$CHART_DIR` before creating files +4. **Refuse writes outside chart directory** and explain scope restriction +5. **Verify location** after helm commands that might change directory +6. **Sanity check** before creating migration artifacts From dac61ef967fb3cc07cbe31a5e06d1c9104879ca9 Mon Sep 17 00:00:00 2001 From: Dustin Lactin Date: Tue, 3 Mar 2026 15:43:55 -0700 Subject: [PATCH 4/5] feat: added additional referenes after cicd-demos migration, updated skill and readme --- .../skills/mozcloud-chart-migration/README.md | 23 +- .../skills/mozcloud-chart-migration/SKILL.md | 14 ++ .../references/configuration-patterns.md | 230 ++++++++++++++++++ .../references/preview-environment-guide.md | 154 ++++++++++++ 4 files changed, 414 insertions(+), 7 deletions(-) create mode 100644 claude/skills/mozcloud-chart-migration/references/configuration-patterns.md create mode 100644 claude/skills/mozcloud-chart-migration/references/preview-environment-guide.md diff --git a/claude/skills/mozcloud-chart-migration/README.md b/claude/skills/mozcloud-chart-migration/README.md index e8b8cdf..6199275 100644 --- a/claude/skills/mozcloud-chart-migration/README.md +++ b/claude/skills/mozcloud-chart-migration/README.md @@ -42,23 +42,32 @@ Before installing this skill, ensure you have: ### Setup Instructions -1. **Copy the skill to your project's Claude skills directory:** +1. **Add the skill to your infra project's Claude skills directory:** + You can either copy or symlink the skill. Symlinking is recommended if you want the skill to automatically stay in sync with updates in the mozcloud repository. + + **Option A: Symlink (Recommended)** ```bash - # From the sandbox-infra repository root + # From your infra repository root (e.g., sandbox-infra) mkdir -p .claude/skills - cp -r /path/to/mozcloud/claude/skills/mozcloud-chart-migration .claude/skills/ + ln -s /path/to/mozcloud/claude/skills/mozcloud-chart-migration .claude/skills/mozcloud-chart-migration ``` - Or if you're already in the mozcloud repository: + **Option B: Copy** + ```bash + # From your infra repository root (e.g., sandbox-infra) + mkdir -p .claude/skills + cp -r /path/to/mozcloud/claude/skills/mozcloud-chart-migration .claude/skills/ + ``` + If you're already in the mozcloud repository and want to set up the symlink: ```bash - # Navigate to your sandbox-infra project + # Navigate to your infra project cd /path/to/sandbox-infra - # Copy the skill + # Create the symlink (adjust the path to mozcloud as needed) mkdir -p .claude/skills - cp -r /path/to/mozcloud/claude/skills/mozcloud-chart-migration .claude/skills/ + ln -s ../mozcloud/claude/skills/mozcloud-chart-migration .claude/skills/mozcloud-chart-migration ``` 2. **Verify installation:** diff --git a/claude/skills/mozcloud-chart-migration/SKILL.md b/claude/skills/mozcloud-chart-migration/SKILL.md index 3ca7876..bc91f0a 100644 --- a/claude/skills/mozcloud-chart-migration/SKILL.md +++ b/claude/skills/mozcloud-chart-migration/SKILL.md @@ -48,6 +48,20 @@ We will have a shared `values.yaml` file and one for each environment: `values-d - If regional values files are found, we want to migrate both the `values-stage.yaml` on its own as well as with the regional values file. We want to convert environments one at a time starting with `values-dev.yaml` if it exists. +**Important Context for Preview Environments:** + +Preview environments have different requirements than dev/stage. See [references/preview-environment-guide.md](references/preview-environment-guide.md) for complete details on: +- Resource naming differences (preserve names in dev/stage, prefix with PR# in preview) +- Preview-specific configuration patterns +- Critical validation points + +**Important Context for Nginx Configuration:** + +Mozcloud provides default nginx configuration. See [references/configuration-patterns.md](references/configuration-patterns.md) for guidance on: +- When to use mozcloud default nginx (recommended) +- How to handle custom nginx configurations +- Decision guide for static vs templated configs + ## Determine Target Chart to Migrate - This skill should be run while in the target chart directory. diff --git a/claude/skills/mozcloud-chart-migration/references/configuration-patterns.md b/claude/skills/mozcloud-chart-migration/references/configuration-patterns.md new file mode 100644 index 0000000..2346b8f --- /dev/null +++ b/claude/skills/mozcloud-chart-migration/references/configuration-patterns.md @@ -0,0 +1,230 @@ +# Mozcloud Configuration Patterns + +This guide documents common configuration patterns for mozcloud chart migrations. + +## Mozcloud Default Nginx + +Mozcloud provides a **default nginx configuration** for sidecar containers. Use mozcloud's default unless you have specific customization requirements. + +### When to Use Mozcloud Default Nginx + +**Recommended for most cases**: +- Standard reverse proxy to application container +- No special nginx configuration requirements +- Want to stay current with platform standards + +**Benefits**: +- Automatically maintained by platform team +- Security updates applied centrally +- Standard configuration across all tenants +- Reduces chart complexity + +### Using Mozcloud Default (Recommended) + +Simply define the nginx container **without custom ConfigMaps**: + +```yaml +mozcloud: + workloads: + my-app: + containers: + nginx: + # No image specification - mozcloud provides default nginx version + # No configMaps - mozcloud provides default nginx.conf + + ports: + - name: http + containerPort: 8080 + protocol: TCP + + resources: + cpu: 100m + memory: 256Mi + + healthCheck: + readiness: + enabled: true + path: /__lbheartbeat__ + liveness: + enabled: true + path: /__nginxheartbeat__ +``` + +Mozcloud will automatically: +- Provide the latest stable nginx image +- Generate a standard nginx.conf +- Mount it as a ConfigMap volume +- Handle all nginx configuration + +### When Custom Nginx Config is Needed + +**Only use custom nginx configuration if you require**: +- Custom log formats beyond mozcloud defaults +- Special proxy settings or headers +- Custom location blocks or rewrites +- Specific nginx modules or directives + +### Custom Nginx Configuration (If Required) + +When custom nginx configuration is needed, choose the appropriate approach based on complexity: + +#### Option 1: Simple Static Config → Values File + +For **simple, static nginx configurations** without Helm templating: + +```yaml +mozcloud: + configMaps: + my-app-nginx: + data: + nginx.conf: | + # Static nginx configuration here + server { + listen 8080; + location / { + proxy_pass http://localhost:8000; + } + } + + workloads: + my-app: + containers: + nginx: + volumes: + - name: my-app-nginx + type: configMap + key: nginx.conf + path: /etc/nginx/nginx.conf + readOnly: true +``` + +**Use this when**: +- Config is short and readable +- No Helm templating needed (no `{{ .Values.* }}`) +- Config is fully static + +#### Option 2: Complex or Templated Config → Keep in Templates + +For **complex configurations or configs using Helm templating**, keep the ConfigMap in the templates directory: + +```yaml +# templates/nginx-configmap.yaml +{{- if not (index .Values "mozcloud" "enabled" | default false) }} +apiVersion: v1 +kind: ConfigMap +metadata: + name: {{ include "application.fullname" . }}-nginx + labels: + {{- include "application.labels" . | nindent 4 }} +data: + nginx.conf: | + # Complex nginx config using Helm values + upstream backend { + server 127.0.0.1:{{ .Values.appPort }}; + } + + server { + listen {{ .Values.nginxPort }}; + client_max_body_size {{ .Values.maxBodySize }}; + + location / { + proxy_pass http://backend; + {{- if .Values.customHeaders }} + {{- range .Values.customHeaders }} + proxy_set_header {{ .name }} {{ .value }}; + {{- end }} + {{- end }} + } + } +{{- end }} +``` + +**Use this when**: +- Config uses Helm templating (`{{ .Values.* }}`, `{{ include }}`, etc.) +- Config is very long (>50 lines) +- Config has complex logic or conditionals +- Config needs to be generated dynamically + +**Important**: Gate the template with `{{ if not .Values.mozcloud.enabled }}` so it only renders when using custom templates, not when mozcloud is enabled. + +### Decision Guide + +When migrating, ask: + +1. **Does the nginx ConfigMap use Helm templating?** + - Yes (has `{{ }}` syntax) → **Keep in templates/** (Option 2) + - No (fully static) → Continue to step 2 + +2. **Is the config complex or very long?** + - Yes (>50 lines, complex logic) → **Keep in templates/** (Option 2) + - No (simple, short) → **Move to values** (Option 1) + +**Example decision message**: +``` +Found custom nginx ConfigMap in templates/nginx-configmap.yaml: +- Uses Helm templating: {{ .Values.appPort }}, {{ .Values.maxBodySize }} +- Length: 120 lines +- Has conditional logic + +Recommendation: Keep nginx ConfigMap in templates directory (gated with mozcloud.enabled check) +- Preserves Helm templating functionality +- Keeps values file readable +- Easier to maintain complex config + +Proceeding with templates approach. +``` + +### Important Notes + +- Define ConfigMap in global `configMaps` section for static configs (Option 1) +- Keep in `templates/` directory for templated configs (Option 2) +- Use `volumes` array (NOT `configMaps` array) to mount as file +- ConfigMap is mounted as a **file volume**, not environment variables + +## ConfigMap vs Volumes + +Mozcloud has two ways to use ConfigMaps in containers: + +### Pattern 1: Environment Variables (use `configMaps` array) + +Use when ConfigMap contains key-value pairs that should be environment variables: + +```yaml +configMaps: + my-app-config: + data: + PORT: "8080" + ENV: "production" + +workloads: + my-app: + containers: + app: + configMaps: + - my-app-config # Mounted as environment variables +``` + +### Pattern 2: File Volumes (use `volumes` array) + +Use when ConfigMap contains files that should be mounted in the filesystem: + +```yaml +configMaps: + nginx-config: + data: + nginx.conf: | + # file content here + +workloads: + my-app: + containers: + nginx: + volumes: + - name: nginx-config + type: configMap + key: nginx.conf + path: /etc/nginx/nginx.conf + readOnly: true +``` + +**Never use both** `configMaps` and `volumes` arrays for the same ConfigMap - choose one pattern based on whether you need environment variables or file mounts. diff --git a/claude/skills/mozcloud-chart-migration/references/preview-environment-guide.md b/claude/skills/mozcloud-chart-migration/references/preview-environment-guide.md new file mode 100644 index 0000000..a049833 --- /dev/null +++ b/claude/skills/mozcloud-chart-migration/references/preview-environment-guide.md @@ -0,0 +1,154 @@ +# Preview Environment Migration Guide + +This guide explains how preview environment migrations differ from dev/stage migrations. + +## Overview + +Preview environments require **DIFFERENT** resource naming patterns than dev/stage environments because multiple PR deployments must coexist without conflicts. + +## Resource Naming Patterns + +| Aspect | Dev/Stage | Preview | Rationale | +|--------|-----------|---------|-----------| +| **Resource Names** | Preserve original | Prefix with PR# | Preview needs isolation between PRs | +| **Target Secret** | Preserve if possible | Prefix with PR# | Each PR needs own secrets | +| **ServiceAccount** | Preserve if possible | Prefix with PR# | Each PR needs own ServiceAccount | +| **ConfigMaps** | Preserve names | Prefix with PR# | Isolation between PR deployments | +| **Hostname** | Static domain | Dynamic PR hostname | ArgoCD ApplicationSet managed | +| **Strategy** | Minimize changes | Enable isolation | Different goals | + +## Dev/Stage Pattern: Preserve Original Names + +For dev/stage environments, **preserve resource names whenever possible**: + +```yaml +# Original custom chart +Deployment: cicd-demos +ExternalSecret: external-secret-cicd-demos → cicd-demos-secrets (rename for mozcloud pattern) +ServiceAccount: cicd-demos + +# After mozcloud migration +Deployment: cicd-demos (preserved) +ExternalSecret: cicd-demos-secrets (minimal change - target Secret name unchanged) +ServiceAccount: cicd-demos (preserved) +``` + +**Goal**: Minimize resource name changes to avoid service disruption. + +## Preview Pattern: Prefix All Resources with PR Number + +For preview environments, **all resources are prefixed** with the PR number for isolation: + +```yaml +# Original custom chart (preview) +Deployment: cicd-demos +ExternalSecret: external-secret-cicd-demos +ServiceAccount: cicd-demos +HTTPRoute: cicd-demos-cicd-demos + +# After mozcloud migration (with global.preview.pr: "13") +Deployment: pr13-cicd-demos (PR-prefixed) +ExternalSecret: pr13-cicd-demos-secrets (PR-prefixed) +Target Secret: pr13-cicd-demos-secrets (MUST ALSO be prefixed) +ServiceAccount: pr13-cicd-demos (PR-prefixed) +HTTPRoute: pr13-cicd-demos (PR-prefixed) +``` + +**Goal**: Isolate each PR deployment so multiple preview environments can coexist. + +**Why Different**: +- **Dev/Stage**: Single deployment per environment - stability and minimal changes matter +- **Preview**: Multiple PR deployments coexist - isolation prevents conflicts + +## Preview-Specific Configuration + +Preview environments use `global.preview` configuration: + +```yaml +global: + preview: + pr: "13" # Placeholder for local testing + host: "pr13-example.preview.mozilla.cloud" # Placeholder - ArgoCD overrides + +mozcloud: + enabled: true + + preview: + enabled: true + # httpRoute defaults are typically correct: + # - gateway.name: sandbox-high-preview-gateway + # - gateway.namespace: preview-shared-infrastructure + # - endpointCheck.enabled: true +``` + +**Important Notes**: +- `global.preview.pr` and `global.preview.host` are **placeholders for local testing** +- ArgoCD ApplicationSet **overrides these values** at deployment time with actual PR number and hostname +- Mozcloud automatically prefixes all resources with the PR number from `global.preview.pr` + +## Critical Validation Points + +When migrating preview environments, verify: + +1. **All resources are PR-prefixed** + ```bash + helm template . -f values-preview.yaml | grep "name: pr.*-" + ``` + +2. **Target Secret name matches pod reference** + - ExternalSecret target: `pr13-cicd-demos-secrets` + - Pods secretRef: `pr13-cicd-demos-secrets` + - Both must match with PR prefix + +3. **ServiceAccount name matches pod reference** + - ServiceAccount: `pr13-cicd-demos` + - Deployment serviceAccountName: `pr13-cicd-demos` + - Both must match with PR prefix + +## When to Approve Name Changes + +**Dev/Stage Migrations**: +- Approve only if technically required (rare) +- Question any name changes - they should be minimal +- Goal: Preserve original names + +**Preview Migrations**: +- Always expect PR prefixing (normal and required) +- Verify target Secret name is ALSO prefixed +- Verify ServiceAccount is ALSO prefixed +- Goal: Enable isolation + +## Preview HTTPRoute Configuration + +Preview environments typically use HTTPRoute with a shared gateway: + +```yaml +preview: + enabled: true + httpRoute: + enabled: true + gateway: + name: sandbox-high-preview-gateway + namespace: preview-shared-infrastructure + endpointCheck: + enabled: true + checkPath: "__heartbeat__" +``` + +**Default gateway settings** are typically correct - no override needed unless your infrastructure uses different gateway names. + +## Common Preview Issues + +### Secret Reference Mismatch +**Symptom**: Pods can't find secret - reference `cicd-demos-secrets` but secret is `pr13-cicd-demos-secrets` + +**Cause**: Mozcloud version issue or misconfiguration + +**Solution**: Verify mozcloud is correctly prefixing the target Secret name and pod references + +### Resource Conflicts Between PRs +**Symptom**: PR deployments interfere with each other + +**Cause**: Resources not properly prefixed + +**Solution**: Verify all resources have PR prefix by checking `global.preview.pr` is set and mozcloud is applying it From 31d2e8f1bdf982658ecf639c14d282564501d2fc Mon Sep 17 00:00:00 2001 From: Dustin Lactin Date: Tue, 3 Mar 2026 15:54:48 -0700 Subject: [PATCH 5/5] feat: added cleanup to migration skill --- .../skills/mozcloud-chart-migration/SKILL.md | 30 ++ .../references/cleanup-phase.md | 332 ++++++++++++++++++ 2 files changed, 362 insertions(+) create mode 100644 claude/skills/mozcloud-chart-migration/references/cleanup-phase.md diff --git a/claude/skills/mozcloud-chart-migration/SKILL.md b/claude/skills/mozcloud-chart-migration/SKILL.md index bc91f0a..ee9d8fe 100644 --- a/claude/skills/mozcloud-chart-migration/SKILL.md +++ b/claude/skills/mozcloud-chart-migration/SKILL.md @@ -67,6 +67,9 @@ Mozcloud provides default nginx configuration. See [references/configuration-pat - This skill should be run while in the target chart directory. - If it is not, ask the user to change to the target chart directory and run again. - Ensure the current directory has a `Chart.yaml` file and prompt for confirmation that this is the intended chart to migrate. + +### Regular Migration (Environment-Specific) + - List all available values files in the directory (values-*.yaml): - Use `ls values-*.yaml` to find all environment values files - Display them to the user with a clear list @@ -76,6 +79,33 @@ Mozcloud provides default nginx configuration. See [references/configuration-pat - Map their response to the corresponding values file (e.g., "dev" → "values-dev.yaml") - Default to values-dev.yaml only if it exists and no other selection is made +### Cleanup Mode + +If the user invokes with `cleanup` argument: +```bash +/mozcloud-chart-migration cleanup +``` + +**Prerequisites Check**: +- Verify all environment migrations are merged to main (check git branch history) +- Confirm Chart.yaml has mozcloud dependency with `condition: mozcloud.enabled` +- Ask user to confirm environments are deployed and stable + +**Actions** (see [references/cleanup-phase.md](references/cleanup-phase.md) for detailed guide): +1. Consolidate duplicate values from `values-{env}.yaml` into `values.yaml` +2. Remove unused custom templates (those fully replaced by mozcloud) +3. Simplify Chart.yaml (remove `condition: mozcloud.enabled`) +4. Remove `mozcloud.enabled: true` from all values files +5. Run `helm dependency update` +6. Archive `.migration/` directory (move to `.migration-archive`) +7. Validate all changes with render-diff for each environment (must show zero differences) +8. Create cleanup branch for review + +**Important**: +- Cleanup is optional and low-urgency +- Functionality remains identical (validated by render-diff) +- Makes future maintenance easier by reducing duplication + ## Tools and Permissions **Critical Rules:** diff --git a/claude/skills/mozcloud-chart-migration/references/cleanup-phase.md b/claude/skills/mozcloud-chart-migration/references/cleanup-phase.md new file mode 100644 index 0000000..a88aa69 --- /dev/null +++ b/claude/skills/mozcloud-chart-migration/references/cleanup-phase.md @@ -0,0 +1,332 @@ +# Cleanup Phase Guide + +## Overview + +After all environments are migrated to mozcloud and merged to main, run a final cleanup phase to: +1. Consolidate duplicate values into `values.yaml` +2. Remove unused custom templates +3. Simplify Chart.yaml dependencies +4. Archive migration documentation + +## When to Run Cleanup + +**Prerequisites**: +- All environment migrations merged to main +- All environments deployed and validated +- Team confirms environments are stable + +**Do NOT run cleanup**: +- While environments are on separate branches +- Before all environments are deployed +- During active rollback or troubleshooting + +## Invocation + +```bash +cd /path/to/chart/directory +/mozcloud-chart-migration cleanup +``` + +## Cleanup Actions + +### 1. Values Consolidation + +**Goal**: Move common configuration from environment files to base `values.yaml` + +**Process**: +1. Identify configuration duplicated across all `values-{env}.yaml` files +2. Move common config to `values.yaml` +3. Keep only environment-specific overrides in `values-{env}.yaml` +4. Validate with render-diff (must show zero changes) + +**Common configuration to consolidate**: +- `mozcloud.app.name`, `realm`, `projectId` +- Base workload configuration (container image, ports, common env vars) +- ServiceAccount annotations (if using templating for env-specific values) +- Common HPA settings +- ConfigMap and ExternalSecret base configuration +- BackendConfig/FrontendConfig common settings + +**Environment-specific overrides to keep**: +- `mozcloud.enabled` flag (if environments at different migration stages) +- Ingress/HTTPRoute hostnames +- Container image tags +- Resource limits/requests (if different per environment) +- Environment-specific environment variables +- Preview-specific configuration (`preview.enabled`, `preview.httpRoute`, etc.) + +### 2. Template Removal + +**Goal**: Remove custom templates fully replaced by mozcloud + +**Templates typically removed**: +- `templates/rollout.yaml` or `templates/deployment.yaml` +- `templates/service.yaml` +- `templates/configmap.yaml` +- `templates/externalsecret.yaml` +- `templates/serviceaccount.yaml` +- `templates/hpa.yaml` +- `templates/ingress.yaml` +- `templates/backendconfig.yaml` +- `templates/frontendconfig.yaml` +- `templates/managedcert.yaml` +- `templates/preview-environments/httproute.yaml` +- `templates/preview-environments/endpoint-check.yaml` + +**Templates to review (may keep)**: +- AnalysisTemplate resources (if planning to re-enable with Rollouts) +- Custom monitoring resources not provided by mozcloud +- Application-specific resources not part of workload + +**Process**: +1. Review each template file +2. Verify mozcloud provides equivalent functionality +3. Delete template file if fully replaced +4. Run render-diff to confirm no changes + +### 3. Chart.yaml Simplification + +**Current state** (during migration): +```yaml +dependencies: + - name: mozcloud + version: "0.7.x" + repository: "oci://us-west1-docker.pkg.dev/moz-fx-platform-artifacts/mozcloud-charts" + condition: mozcloud.enabled # Conditional during migration +``` + +**After cleanup**: +```yaml +dependencies: + - name: mozcloud + version: "0.7.x" + repository: "oci://us-west1-docker.pkg.dev/moz-fx-platform-artifacts/mozcloud-charts" + # No condition - mozcloud always enabled +``` + +**Process**: +1. Remove `condition: mozcloud.enabled` from Chart.yaml +2. Remove `mozcloud.enabled: true` from all values files (no longer needed) +3. Run `helm dependency update` to regenerate Chart.lock +4. Validate with render-diff + +### 4. Migration Directory Cleanup + +**Options**: + +**Option A: Archive** (Recommended for first 1-3 months) +```bash +mv .migration .migration-archive +# Keep in git for reference +``` + +**Option B: Remove Completely** +```bash +rm -rf .migration +# Migration docs preserved in git history +``` + +**What's in .migration/**: +- Migration plans and documentation +- Original and migrated manifests for comparison +- Diff analyses +- Change logs +- Downloaded mozcloud chart reference + +**Recommendation**: Archive initially, remove after team confirms no longer needed + +## Validation Strategy + +After each cleanup step, run comprehensive validation: + +### 1. Render-diff for All Environments +```bash +render-diff -f values-dev.yaml -su +render-diff -f values-stage.yaml -su +render-diff -f values-prod.yaml -su +render-diff -f values-preview.yaml -su +``` + +**Expected**: Zero differences (semantic equivalence) + +### 2. Resource Count Check +```bash +helm template . -f values.yaml -f values-dev.yaml | grep "^kind:" | wc -l +helm template . -f values.yaml -f values-stage.yaml | grep "^kind:" | wc -l +helm template . -f values.yaml -f values-prod.yaml | grep "^kind:" | wc -l +``` + +**Expected**: Same resource counts as before cleanup + +### 3. Visual Inspection +```bash +helm template . -f values.yaml -f values-dev.yaml > /tmp/dev-post-cleanup.yaml +diff .migration/manifests/dev/migrated.yaml /tmp/dev-post-cleanup.yaml +``` + +**Expected**: No differences in actual resource definitions + +## Cleanup Branch Strategy + +Create a cleanup branch for review: +```bash +git checkout -b cleanup-mozcloud-migration-$(date +%Y%m%d) +``` + +This allows: +- Team review before applying +- Easy rollback if issues found +- Clear separation from environment migrations + +## Success Criteria + +- [ ] Values consolidated (no unnecessary duplication) +- [ ] Custom templates removed (only mozcloud or custom resources remain) +- [ ] Chart.yaml simplified (no conditional mozcloud enablement) +- [ ] All environments render identical manifests post-cleanup +- [ ] render-diff shows zero changes for all environments +- [ ] Migration directory archived or removed +- [ ] Cleanup changes committed on separate branch +- [ ] Team review completed +- [ ] Cleanup branch merged to main + +## Rollback Plan + +If cleanup causes unexpected issues: + +1. **Git revert** the cleanup commit +2. **Redeploy** via ArgoCD sync +3. **Review** what went wrong +4. **Fix** and re-attempt + +Cleanup is purely cosmetic - rollback should be simple. + +## Example: Values Consolidation + +### Before Cleanup + +`values.yaml`: +```yaml +# Minimal base configuration +``` + +`values-dev.yaml`: +```yaml +mozcloud: + enabled: true + app: + name: myapp + realm: nonprod + workloads: + myapp: + replicas: 2 + containers: + - name: app + image: myregistry/myapp + tag: dev-latest + resources: + limits: + cpu: 100m + memory: 128Mi +``` + +`values-stage.yaml`: +```yaml +mozcloud: + enabled: true + app: + name: myapp # Duplicate + realm: nonprod # Duplicate + workloads: + myapp: + replicas: 2 # Duplicate + containers: + - name: app # Duplicate + image: myregistry/myapp # Duplicate + tag: stage-latest + resources: + limits: + cpu: 200m + memory: 128Mi +``` + +### After Cleanup + +`values.yaml`: +```yaml +mozcloud: + app: + name: myapp + realm: nonprod + + workloads: + myapp: + replicas: 2 + containers: + - name: app + image: myregistry/myapp + # tag: defined per environment + # resources: defined per environment +``` + +`values-dev.yaml`: +```yaml +mozcloud: + workloads: + myapp: + containers: + - name: app + tag: dev-latest + resources: + limits: + cpu: 100m + memory: 128Mi +``` + +`values-stage.yaml`: +```yaml +mozcloud: + workloads: + myapp: + containers: + - name: app + tag: stage-latest + resources: + limits: + cpu: 200m + memory: 128Mi +``` + +**Result**: Cleaner separation of common vs environment-specific config + +## Important Notes + +- **Cleanup is optional** - Functionality remains identical with or without cleanup +- **No urgency** - Can defer cleanup if team bandwidth is limited +- **Low risk** - All changes validated with render-diff before applying +- **Makes maintenance easier** - Reduces duplication and simplifies future updates +- **Team decision** - Timing of cleanup is up to the team, not prescribed + +## Troubleshooting + +**Issue**: render-diff shows differences after values consolidation + +**Solution**: Review the diff carefully - ensure environment-specific overrides are preserved in the right files + +--- + +**Issue**: Templates removed but resources missing + +**Solution**: Verify mozcloud provides the resource type - may need to keep custom template + +--- + +**Issue**: Chart.lock conflicts after Chart.yaml changes + +**Solution**: Run `helm dependency update` to regenerate Chart.lock + +--- + +**Issue**: Team wants to keep templates for future use + +**Solution**: Archive templates in a separate directory (e.g., `templates-archive/`) instead of deleting