diff --git a/.exp/design-workflow-1-local-development-workflow.md b/.exp/design-workflow-1-local-development-workflow.md index 2fa3ae092cc..b670e7a4c18 100644 --- a/.exp/design-workflow-1-local-development-workflow.md +++ b/.exp/design-workflow-1-local-development-workflow.md @@ -29,7 +29,7 @@ The workflow is initiated by running `skaffold dev` from the project root. Acces - **Local Kubernetes Cluster**: Runs the deployed pods and services. Internal gRPC communication between services occurs over cluster networking. -- **Profiles and Patches**: Skaffold profiles enable modes like `debug` (swaps cartservice Dockerfile for debugging) or `network-policies` (adds Kustomize overlays). +- **Profiles and Patches**: Skaffold profiles enable modes like `debug` (patches build configs for multi-service debugging including cartservice `Dockerfile.debug` swap and `SKAFFOLD_PY_DEBUG=true` arg for Python services emailservice, recommendationservice, loadgenerator to install debugpy) or `network-policies` (adds Kustomize overlays). - **Tag Policy**: `gitCommit` policy tags images with Git commit SHA for versioning. @@ -41,19 +41,25 @@ sequenceDiagram participant S as Skaffold participant B as Docker Build participant K as K8s Cluster - D->>S: skaffold dev - S->>S: Load skaffold.yaml (artifacts, manifests) + D->>S: skaffold dev or debug + S->>S: Load skaffold.yaml (artifacts, manifests, activate profiles if debug) loop For each artifact - S->>B: docker build -t : src/ - B->>B: Build image from Dockerfile + alt Debug profile active + S->>B: docker build with debug patches (e.g., debugpy arg, special Dockerfile) + B->>B: Build image including debugging tools (debugpy for Python, .NET debug for cartservice) + else Standard dev + S->>B: docker build -t : src/ + B->>B: Build image from standard Dockerfile + end end S->>K: kustomize build kubernetes-manifests/ | kubectl apply -f - K->>K: Create Deployments, Services, Pods - Note over S,K: Pods pull local images and start + Note over S,K: Pods pull local images and start (debug-enabled if applicable) D->>K: kubectl port-forward svc/frontend 8080:8080 - Note over D: Access app at http://localhost:8080 + Note over D: Access app at http://localhost:8080; attach debugger to pods if debug mode ``` + This diagram illustrates the startup sequence: Skaffold builds all service images in parallel loops, deploys the cluster resources, and enables local access. ## Sequence Diagram: Hot Reload Cycle @@ -90,7 +96,11 @@ During development, Skaffold monitors file changes in build contexts. Upon detec ### Customization and Extensions - **Profiles**: - - `debug`: Patches cartservice to use `Dockerfile.debug` for .NET debugging support. + - `debug`: Provides debugging support via artifact patches activated by `skaffold debug`: + - cartservice: Uses `Dockerfile.debug` for .NET debugging (fixed override). + - emailservice, recommendationservice: Adds build arg `SKAFFOLD_PY_DEBUG=true` to install `debugpy` in Python runtime. + - loadgenerator: Dedicated profile adds build arg for `debugpy` support. + Extends prior cartservice-only functionality to prevent Python service failures in debug mode. - `network-policies`: Adds Kustomize path to include network policy manifests. - Can combine profiles, e.g., `skaffold dev -p network-policies,debug`. - **Integration**: Compatible with IDEs for remote debugging. For service mesh (Istio), use additional Kustomize components or profiles. diff --git a/.exp/design-workflow-2-gke-deployment-workflow.md b/.exp/design-workflow-2-gke-deployment-workflow.md index 6d8df079df8..466a73c475a 100644 --- a/.exp/design-workflow-2-gke-deployment-workflow.md +++ b/.exp/design-workflow-2-gke-deployment-workflow.md @@ -82,7 +82,7 @@ sequenceDiagram - For Cloud Build: Service account with Kubernetes Engine Developer role; substitutions for `_ZONE` and `_CLUSTER`. ### Customization and Extensibility -- **Profiles in Skaffold**: Activate via `-p `, e.g., `-p gcb` for remote builds, `-p network-policies` to patch manifests with additional Kustomize paths. +- **Profiles in Skaffold**: Activate via `-p `, e.g., `-p gcb` for remote builds using Google Cloud Build, `-p debug` to enable service debugging (adds debugpy to Python images, special Dockerfile for cartservice), `-p network-policies` to patch manifests with additional Kustomize paths. - **Kustomize Overlays**: Uncomment or add components in `kubernetes-manifests/kustomization.yaml` for features like service mesh (Istio), alternative databases (AlloyDB/Spanner), or observability (Cloud Operations). - **Image Tagging**: Git commit-based for traceability; customizable via `tagPolicy` in `skaffold.yaml`. - **Load Generator**: Separate Skaffold config (`loadgenerator`) requiring `app`; deploys `loadgenerator.yaml` manifest. diff --git a/docs/pr-analysis-3094.md b/docs/pr-analysis-3094.md new file mode 100644 index 00000000000..b343b693c48 --- /dev/null +++ b/docs/pr-analysis-3094.md @@ -0,0 +1,80 @@ +# PR #3094: Workflow Design Impact Analysis + +## Affected Workflows +- **Local Development Workflow**: Directly impacted as the PR fixes and extends the `debug` profile documented in its design for `skaffold debug`, enabling debugging for additional services. +- **GKE Deployment Workflow**: Indirectly impacted through shared `skaffold.yaml`; the enhanced `debug` profile can be optionally used with `skaffold run -p debug`. + +## Local Development Workflow Analysis +### Summary of design changes +The PR enhances the debugging capabilities in the local development workflow by correcting the cartservice debug Dockerfile override and adding support for Python services and loadgenerator. + +Specific aspects affected: +- Skaffold `debug` profile patches: Extended to include build args for Python services to install `debugpy`, and added profile to loadgenerator config. +- Dockerfiles for emailservice, recommendationservice, loadgenerator: Added conditional `debugpy` installation based on build arg. +- cartservice: Fixed patch and added/updated Dockerfile.debug. +- Base skaffold.yaml: Removed explicit Dockerfile for cartservice to avoid conflicts. + +The PR implements these via Skaffold JSON patches activated on `debug` command and Dockerfile ARGs/RUN conditions. + +Benefits: Fixes crashes in debug mode for Python services, enables IDE debugging for more services, improves local dev experience. +Implications: Debug builds include extra dependencies; standard dev unaffected. + +## GKE Deployment Workflow Analysis +### Summary of design changes +The PR updates `skaffold.yaml`, which is central to this workflow, primarily enhancing the optional `debug` profile: + +- Extended `debug` profile now supports Python services and loadgenerator alongside fixed cartservice support, available for use with `skaffold run -p debug --default-repo=`. +- Minor config cleanup for cartservice base artifact. +- Dockerfiles updated to support debug builds universally. + +Specific aspects: Profiles section in design doc now should include `debug` as an example alongside `gcb` and `network-policies`. + +How PR implements: Same Skaffold patches and Dockerfile changes. + +Benefits: Allows debugging deployments to GKE for services under test. Implications: Not standard for production deploys; debug features may not be suitable for GKE security contexts. + +```mermaid +flowchart TD + subgraph Shared ["Shared Skaffold Config Changes"] + DebugExt["Enhanced debug profile: multi-service support (cartservice fix + Python debugpy)"] + ConfigClean["Cleaned cartservice base artifact"] + style DebugExt fill:#green + style ConfigClean fill:#yellow + end + Standard["Standard skaffold run unaffected"] + Optional["Optional: skaffold run -p debug for debug images to GKE"] + style Standard fill:#blue + style Optional fill:#green +``` + +## Design Document Updates Performed +- Updated `.exp/design-workflow-1-local-development-workflow.md`: Enhanced descriptions of `debug` profile and patches; updated Initial Deployment sequence diagram to illustrate debug variant. +- Updated `.exp/design-workflow-2-gke-deployment-workflow.md`: Added mention of `debug` profile in customization examples. +- All updated Mermaid diagrams validated with `mmdc` for syntax correctness. + +``` + + +```mermaid +flowchart TD + subgraph Before ["Before PR - Debug Support"] + Carts["cartservice: replace /artifacts/7/docker/dockerfile = Dockerfile.debug"] + Python["Python services: No support - crash on debug"] + Load["loadgenerator: No debug profile"] + style Carts fill:#yellow + style Python fill:#red + style Load fill:#red + end + subgraph After ["After PR - Enhanced Debug Support"] + Carts2["cartservice: add /artifacts/8/docker dockerfile: Dockerfile.debug"] + Python2["emailservice, recommendationservice: add /artifacts/[0,2]/docker buildArgs: SKAFFOLD_PY_DEBUG=true"] + Load2["loadgenerator: new debug profile add /artifacts/0/docker buildArgs: SKAFFOLD_PY_DEBUG=true"] + Debugpy["Dockerfiles: ARG SKAFFOLD_PY_DEBUG=false + if true pip install debugpy"] + style Carts2 fill:#yellow + style Python2 fill:#green + style Load2 fill:#green + style Debugpy fill:#green + end + BaseChange["Base cartservice artifact: remove explicit docker dockerfile: Dockerfile"] + style BaseChange fill:#yellow +```