ga-plugins-cli 0.1.0 → 0.1.2

package/plugins/migration-safety/commands/strangler-plan.md

@@ -0,0 +1,356 @@
+# Command: strangler-plan
+
+Produce a step-by-step Strangler Fig traffic-cutover checklist for migrating a domain from Java/Spring Boot to Go at Garuda Airlines. The output is a human-actionable plan — not a script. All traffic switching is performed by the human team using their gateway tooling.
+
+---
+
+## Step 1: Identify the Domain
+
+Ask the user:
+
+> "What is the name of the domain or service group being migrated?
+> (e.g., `booking`, `check-in`, `loyalty-points`)"
+
+Record as `<domain-name>`.
+
+---
+
+## Step 2: Identify the Gateway Technology
+
+Ask the user:
+
+> "What gateway or routing technology routes traffic to your services?
+> Please choose or describe:
+>
+>   1. Kong Gateway
+>   2. Nginx (or OpenResty)
+>   3. AWS ALB (Application Load Balancer) with weighted target groups
+>   4. Istio / Envoy service mesh
+>   5. Custom (describe it)
+>   6. NEEDS DECISION — not yet decided
+>
+> If you choose NEEDS DECISION, a gateway-agnostic checklist with placeholders will be generated."
+
+Record as `<gateway-type>`. If the user selects NEEDS DECISION or 6, set `<gateway-agnostic> = true`.
+
+---
+
+## Step 3: List Endpoints Being Migrated in This Phase
+
+Ask the user:
+
+> "Which endpoints are being migrated to the Go service in this phase?
+> List them one per line, e.g.:
+>   POST /api/v1/bookings
+>   GET  /api/v1/bookings/{id}
+>   DELETE /api/v1/bookings/{id}
+>
+> Note: In the GA 10→1 consolidation, you may be migrating endpoint groups from multiple
+> Java services at once. List ALL endpoints being cut over in this phase."
+
+Record as `<endpoint-list>`.
+
+---
+
+## Step 4: Identify the Java and Go Service Coordinates
+
+Ask the user:
+
+> "What are the service names and host/port details for traffic routing?
+>   - Java service name (as known to your gateway): e.g., `booking-java-svc`
+>   - Go service name (as known to your gateway): e.g., `flight-ops-svc`
+>   - Java service host:port (in test/staging): e.g., `booking-java-svc.internal:8080`
+>   - Go service host:port (in test/staging): e.g., `flight-ops-svc.internal:8081`"
+
+Record as `<java-svc>`, `<go-svc>`, `<java-host>`, `<go-host>`.
+
+---
+
+## Step 5: Identify Monitoring Dashboard
+
+Ask the user:
+
+> "Where are your Grafana (or equivalent) dashboards for these services?
+> (URL or dashboard name — used to generate monitoring checklist items.
+> If unknown, enter UNKNOWN and placeholders will be used.)"
+
+Record as `<dashboard-url>`.
+
+---
+
+## Step 6: Generate the Strangler Fig Cutover Checklist
+
+Produce a Markdown file at `strangler-plans/<domain-name>-cutover-plan.md` with the following content:
+
+---
+
+### strangler-plans/<domain-name>-cutover-plan.md
+
+```markdown
+# Strangler Fig Cutover Plan: <domain-name>
+
+**Domain**: <domain-name>
+**Java service**: <java-svc> (<java-host>)
+**Go service**: <go-svc> (<go-host>)
+**Gateway**: <gateway-type>
+**Endpoints in this phase**: <endpoint-list>
+**Generated**: <ISO date>
+**Skill reference**: migration-safety/skills/strangler-fig.md
+
+> This plan describes incremental traffic cutover using the Strangler Fig pattern.
+> No big-bang switchover. Java and Go services run in parallel at all times until Step 7.
+> Rollback is always available until Step 7.
+
+---
+
+## Pre-Flight Checklist (Complete Before Starting)
+
+- [ ] Go service `<go-svc>` is deployed and healthy in the target environment
+- [ ] Go service passes ALL characterization tests (see `gen-characterization-test` output)
+- [ ] REVIEW.md has been signed off — all MUST DECIDE items resolved
+- [ ] Java service `<java-svc>` remains running and unchanged
+- [ ] Monitoring dashboard is open: <dashboard-url>
+- [ ] Team members on standby: __________________ (list names)
+- [ ] Rollback procedure has been tested: (yes/no) ______
+- [ ] Database migration (if any) is complete and both services can read the same schema: (yes/no) ______
+- [ ] On-call engineer notified: (yes/no) ______
+
+---
+
+## Step 1: Deploy Go Service (Both Running)
+
+**Goal**: Go service is live, receiving zero production traffic. Java service handles 100%.
+
+Actions:
+- [ ] Deploy `<go-svc>` to production environment
+- [ ] Verify health endpoint: `curl -f http://<go-host>/health`
+- [ ] Verify Go service connects to production database (read-only test query)
+- [ ] Verify Go service connects to all external dependencies (broker, external HTTP clients)
+- [ ] Confirm gateway can route to Go service (test with direct host access, bypassing gateway)
+
+**Checkpoint**: both `<java-svc>` and `<go-svc>` are running. 100% traffic still on Java.
+
+---
+
+## Step 2: Canary — Route 5% of Traffic to Go Service
+
+**Goal**: small percentage of real traffic hits the Go service. Observe for 30 minutes.
+**Rollback trigger**: error rate on Go service exceeds 0.1% OR p99 latency degrades >20%.
+
+```
+<GATEWAY-SPECIFIC CONFIG BLOCK>
+```
+
+<!-- For Kong: -->
+<!-- Add weighted route:
+  - Java upstream: weight 95
+  - Go upstream: weight 5
+  - Endpoints: <endpoint-list>
+  kong deck sync --state kong-canary-5pct.yaml
+-->
+
+<!-- For Nginx: -->
+<!-- upstream block with split_clients:
+  split_clients "${remote_addr}${uri}" $backend {
+    5%  go_upstream;
+    *   java_upstream;
+  }
+-->
+
+<!-- For AWS ALB: -->
+<!-- Weighted target group: Java TG weight=95, Go TG weight=5
+  aws elbv2 modify-rule --rule-arn <RULE_ARN> \
+    --actions Type=forward,ForwardConfig='{TargetGroups=[{TargetGroupArn=<JAVA_TG_ARN>,Weight=95},{TargetGroupArn=<GO_TG_ARN>,Weight=5}]}'
+-->
+
+<!-- For Istio: -->
+<!-- VirtualService weight split:
+  spec:
+    http:
+    - route:
+      - destination: host: <java-svc>, weight: 95
+      - destination: host: <go-svc>, weight: 5
+-->
+
+<!-- For GATEWAY_AGNOSTIC (NEEDS DECISION): -->
+<!-- TODO(human): implement 5% traffic split to <go-host> using your gateway.
+  The split should be by request percentage (random or hash-based), not by endpoint.
+  Endpoints affected: <endpoint-list>
+-->
+
+Monitor for 30 minutes:
+- [ ] Error rate on `<go-svc>`: ____% (target: < 0.1%)
+- [ ] p99 latency on `<go-svc>`: ____ms (target: within 20% of Java baseline)
+- [ ] Error rate on `<java-svc>`: ____% (should be unchanged from before)
+- [ ] Business KPIs (e.g., booking completion rate): ____ (should be unchanged)
+- [ ] No new error log lines in `<go-svc>` that were not present before
+
+**Checkpoint**: 30 minutes at 5% with no degradation. Proceed to Step 3.
+
+---
+
+## Step 3: Anti-Corruption Layer (If Needed)
+
+**Goal**: if request or response shapes differ between Java and Go, add translation layer.
+
+- [ ] Compare Java request schema with Go request schema for each endpoint in <endpoint-list>
+- [ ] Compare Java response schema with Go response schema for each endpoint
+- [ ] If schemas match: skip this step (document "schemas match" here)
+- [ ] If schemas differ:
+  - [ ] Implement ACL adapter (request transformation on ingress, response transformation on egress)
+  - [ ] Add ACL to the gateway layer OR as a sidecar on the Go service
+  - [ ] Re-run characterization tests with ACL in place
+  - [ ] Document which fields differ and the transformation applied: __________________
+
+ACL status: [ ] Not needed  [ ] Implemented — see: __________________
+
+---
+
+## Step 4: Ramp Traffic to 25% → 50% → 75%
+
+For each ramp increment, wait at least 1 hour and verify monitoring before proceeding.
+
+### 4a: Ramp to 25%
+
+- [ ] Update gateway: Go=25%, Java=75%
+- [ ] Wait 1 hour
+- [ ] Error rate on Go: ____% (target: < 0.1%)
+- [ ] p99 latency: ____ms
+- [ ] Business KPIs: ____
+
+### 4b: Ramp to 50%
+
+- [ ] Update gateway: Go=50%, Java=50%
+- [ ] Wait 1 hour
+- [ ] Error rate on Go: ____% (target: < 0.1%)
+- [ ] p99 latency: ____ms
+- [ ] Business KPIs: ____
+
+### 4c: Ramp to 75%
+
+- [ ] Update gateway: Go=75%, Java=25%
+- [ ] Wait 1 hour
+- [ ] Error rate on Go: ____% (target: < 0.1%)
+- [ ] p99 latency: ____ms
+- [ ] Business KPIs: ____
+
+**Checkpoint**: 75% Go traffic stable for 1 hour. Proceed to Step 5.
+
+---
+
+## Step 5: Full Cutover — 100% Traffic to Go Service
+
+**Goal**: all production traffic for <endpoint-list> is routed to `<go-svc>`.
+**Rollback window**: Java service stays running for 2 weeks after this step.
+
+- [ ] Update gateway: Go=100%, Java=0%
+
+  <!-- Gateway-specific 100% config: same as Step 2 but weight=100 for Go, weight=0 for Java -->
+  <!-- TODO(human): apply 100% routing config in your gateway -->
+
+- [ ] Verify: send test request to each endpoint in <endpoint-list>, confirm response from Go service
+  (check X-Service-Name or similar header if available)
+- [ ] Monitor for 2 hours:
+  - [ ] Error rate: ____% (target: < 0.1%)
+  - [ ] p99 latency: ____ms
+  - [ ] Business KPIs: ____
+  - [ ] No unexpected errors in Go service logs
+- [ ] Notify stakeholders: "Domain `<domain-name>` is now served 100% by Go service `<go-svc>`"
+
+**Checkpoint**: 2 hours at 100% stable. Java remains running as fallback.
+
+---
+
+## Step 6: Fallback Period — Keep Java Running for 2 Weeks
+
+**Goal**: Java service stays running and ready for immediate rollback if a hidden defect surfaces.
+
+- [ ] Do NOT stop or undeploy `<java-svc>`
+- [ ] Keep gateway routing config such that Java can be restored to 100% within 5 minutes
+- [ ] Daily monitoring checks during the 2-week fallback window:
+  - [ ] Day 1 check: __________________
+  - [ ] Day 3 check: __________________
+  - [ ] Day 7 check: __________________
+  - [ ] Day 14 check: __________________
+- [ ] At end of 2 weeks: team confirms no rollback was needed: (yes/no) ______
+
+**Rollback procedure** (if needed at any point before Step 7):
+1. Update gateway: Java=100%, Go=0% (reverse of Step 5)
+2. Notify team
+3. File incident report
+4. Do not retry Go cutover until root cause is identified and fixed
+
+---
+
+## Step 7: Decommission Java Service
+
+**HUMAN DECISION REQUIRED before this step.**
+This step is irreversible. Do not proceed until Step 6 is fully complete and signed off.
+
+- [ ] Team confirms: no rollback events during 2-week fallback window
+- [ ] Characterization tests are passing against Go service in production (or staging equivalent)
+- [ ] Archive Java source code to long-term storage (do not delete permanently yet)
+- [ ] Update gateway: remove Java upstream entirely
+- [ ] Stop and undeploy `<java-svc>`
+- [ ] Update team documentation, runbooks, and on-call guides
+- [ ] Decommission Java service infrastructure (scale down to zero)
+- [ ] Notify downstream teams that `<java-svc>` is decommissioned
+
+**Signed off by**: __________________
+**Date**: __________________
+
+---
+
+## Rollback Quick Reference
+
+| Situation | Action | Time to rollback |
+|-----------|--------|-----------------|
+| Go service crashes (Step 2-4) | Update gateway weight: Java=100%, Go=0% | < 5 min |
+| Silent data corruption detected (Step 5) | Gateway: Java=100%; investigate Go service | < 5 min |
+| Latency spike on Go (Step 5) | Gateway: Java=100%; profile Go service | < 5 min |
+| After Step 7 (decommissioned) | Redeploy Java from archive; restore DB if needed | > 1 hour |
+
+**Decision authority for rollback**: any engineer on the on-call rotation may initiate rollback
+without management approval. Speed is more important than process here.
+
+---
+
+## Monitoring Checklist (Reference During All Steps)
+
+Dashboard: <dashboard-url>
+
+| Metric | Java Baseline | Go Target | Alert Threshold |
+|--------|-------------|-----------|----------------|
+| Error rate (5xx) | ____% | ____% | > 0.1% |
+| p99 latency | ____ms | ____ms | > 20% above baseline |
+| Request throughput | ____ req/s | ____ req/s | < 10% of expected |
+| DB connection pool utilization | ____% | ____% | > 80% |
+| Business KPI: <domain-specific KPI> | ____ | ____ | > 1% delta |
+
+TODO(human): fill in baseline values from Java service before starting cutover.
+```
+
+---
+
+## Step 7: Print Summary
+
+After writing the plan file, print:
+
+```
+==========================================================================
+STRANGLER FIG CUTOVER PLAN GENERATED
+Domain: <domain-name>
+Gateway: <gateway-type>
+Endpoints: <endpoint-list>
+Output: strangler-plans/<domain-name>-cutover-plan.md
+
+BEFORE STARTING CUTOVER:
+  1. Complete the Pre-Flight Checklist in the plan
+  2. Ensure characterization tests pass (run: gen-characterization-test first)
+  3. Assign a rollback decision authority
+  4. Open your monitoring dashboard: <dashboard-url>
+
+This plan follows the Strangler Fig strategy — see migration-safety/skills/strangler-fig.md
+for the full rationale and pattern reference.
+==========================================================================
+```