Skip to content

Commit 126a8f1

Browse files
gauravagerwalagauravagerwala
committed
initial design files
1 parent df963b2 commit 126a8f1

14 files changed

+1222
-0
lines changed

‎.exp/design-workflow-1-local-development-workflow.md‎

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
# High-Level Design: Local Development Workflow
2+
3+
## Overview
4+
5+
The Local Development Workflow enables developers to deploy and run the entire Online Boutique microservices application on a local Kubernetes cluster, such as Minikube, Kind, or Docker Desktop's Kubernetes. It uses Skaffold to automate the building of Docker images from source code in the `src/` directories, deployment of Kubernetes manifests from `kubernetes-manifests/`, and continuous watching for code changes to enable hot reloading. This facilitates rapid development iteration without the need for remote cloud resources or manual build/deploy steps.
6+
7+
Key benefits include:
8+
- Automated image builds using local Docker.
9+
- Declarative Kubernetes deployments via Kustomize.
10+
- Hot reload on file changes in service source code.
11+
- Support for debugging and optional configurations via Skaffold profiles.
12+
13+
Prerequisites:
14+
- Local Kubernetes cluster running.
15+
- Docker installed and configured.
16+
- Skaffold installed (CLI tool).
17+
18+
The workflow is initiated by running `skaffold dev` from the project root. Access the application via `kubectl port-forward deployment/frontend 8080:8080` and browse to `http://localhost:8080`.
19+
20+
## Components
21+
22+
- **Skaffold**: The core orchestrator defined in `skaffold.yaml`. It specifies build artifacts (one per microservice, with build contexts in `src/<service>`), manifest paths (`kubernetes-manifests/` processed via Kustomize), and deployment via `kubectl`. Supports multiple configs (main 'app' and 'loadgenerator') and profiles for customization.
23+
24+
- **Dockerfiles**: Service-specific Dockerfiles in `src/<service>/Dockerfile` (e.g., multi-stage Go builds for Go services, Node.js for JS services). Skaffold builds these locally using Docker CLI and Buildkit for efficiency.
25+
26+
- **Kubernetes Manifests**: YAML files in `kubernetes-manifests/` defining Deployments, Services, Pods, etc., for all 11 microservices, Redis (cart store), and loadgenerator. Image references (e.g., `image: frontend`) are updated by Skaffold with generated tags.
27+
28+
- **Kustomize**: Used by Skaffold to build manifests, allowing bases and patches (e.g., via profiles adding components like network policies).
29+
30+
- **Local Kubernetes Cluster**: Runs the deployed pods and services. Internal gRPC communication between services occurs over cluster networking.
31+
32+
- **Profiles and Patches**: Skaffold profiles enable modes like `debug` (swaps cartservice Dockerfile for debugging) or `network-policies` (adds Kustomize overlays).
33+
34+
- **Tag Policy**: `gitCommit` policy tags images with Git commit SHA for versioning.
35+
36+
## Sequence Diagram: Initial Deployment
37+
38+
```mermaid
39+
sequenceDiagram
40+
participant D as Developer
41+
participant S as Skaffold
42+
participant B as Docker Build
43+
participant K as K8s Cluster
44+
D->>S: skaffold dev
45+
S->>S: Load skaffold.yaml (artifacts, manifests)
46+
loop For each artifact
47+
S->>B: docker build -t <image>:<tag> src/<service>
48+
B->>B: Build image from Dockerfile
49+
end
50+
S->>K: kustomize build kubernetes-manifests/ | kubectl apply -f -
51+
K->>K: Create Deployments, Services, Pods
52+
Note over S,K: Pods pull local images and start
53+
D->>K: kubectl port-forward svc/frontend 8080:8080
54+
Note over D: Access app at http://localhost:8080
55+
```
56+
57+
This diagram illustrates the startup sequence: Skaffold builds all service images in parallel loops, deploys the cluster resources, and enables local access.
58+
59+
## Sequence Diagram: Hot Reload Cycle
60+
61+
```mermaid
62+
sequenceDiagram
63+
participant S as Skaffold (watching)
64+
participant Dev as Developer
65+
participant B as Docker Build
66+
participant K as K8s Cluster
67+
Note over S: File change detected in watched dir (e.g., src/frontend)
68+
S->>B: Rebuild affected image(s)
69+
B->>B: docker build -t <image>:new-tag
70+
S->>K: kubectl apply updated manifests (with new image tag)
71+
K->>K: Rolling update pods with new image
72+
Note over Dev: Code changes reflected without manual intervention
73+
```
74+
75+
During development, Skaffold monitors file changes in build contexts. Upon detection, it rebuilds only affected images and triggers a deployment update, typically a rolling pod update in Kubernetes.
76+
77+
## Additional High-Level Design Aspects
78+
79+
### Build Process Details
80+
- **Platforms**: Supports `linux/amd64` and `linux/arm64` for multi-arch builds.
81+
- **Local Build**: Uses `local` builder with `useDockerCLI: true` and `useBuildkit: true` for fast, cached builds without pushing to a registry.
82+
- **Dependencies**: Some services require proto generation (via `genproto.sh` scripts); generated files (e.g., `demo.pb.go`) are included in source trees and built into images. Changes to `.proto` files may require manual regeneration before rebuild.
83+
- **Load Generator**: Handled via a separate Skaffold config requiring the main 'app' config, ensuring it's deployed alongside services.
84+
85+
### Deployment and Runtime
86+
- **Manifest Updates**: Skaffold replaces image tags in manifests during deploy.
87+
- **Health Checks and Probes**: Defined in manifests (e.g., readiness probes in frontend.yaml) ensure pods are healthy before traffic routing.
88+
- **Service Discovery**: Kubernetes Services enable gRPC communication between pods using service names (e.g., frontend calls productcatalogservice).
89+
- **Persistence**: Redis Deployment/StatefulSet provides cart storage; local cluster must handle ephemeral data.
90+
91+
### Customization and Extensions
92+
- **Profiles**:
93+
- `debug`: Patches cartservice to use `Dockerfile.debug` for .NET debugging support.
94+
- `network-policies`: Adds Kustomize path to include network policy manifests.
95+
- Can combine profiles, e.g., `skaffold dev -p network-policies,debug`.
96+
- **Integration**: Compatible with IDEs for remote debugging. For service mesh (Istio), use additional Kustomize components or profiles.
97+
- **Testing**: Loadgenerator deploys simulated traffic; can be scaled or disabled.
98+
99+
### Limitations and Considerations
100+
- No file syncing configured in Skaffold, so changes require full image rebuild and redeploy (acceptable for most languages here).
101+
- Resource-intensive for local clusters with all services + load.
102+
- No automatic proto compilation in workflow; developers run scripts as needed.
103+
- For cloud-like features (e.g., AlloyDB instead of Redis), apply Kustomize overlays before Skaffold deploy.
104+
105+
This design promotes efficient local development while mirroring production deployment patterns through Skaffold and Kubernetes.

‎.exp/design-workflow-2-gke-deployment-workflow.md‎

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
# High-Level Design of GKE Deployment Workflow
2+
3+
## Overview
4+
5+
The GKE Deployment Workflow deploys the Online Boutique microservices to a Google Kubernetes Engine (GKE) cluster using Skaffold. Skaffold orchestrates building Docker images from source code, pushing them to a container registry (e.g., Artifact Registry), rendering Kubernetes manifests with updated image tags via Kustomize, and deploying to the cluster via kubectl.
6+
7+
This workflow supports local execution for developers or remote execution via Google Cloud Build for CI/CD pipelines. It assumes prerequisites like an existing GKE cluster, authenticated gcloud, and a registry repository. The entry point is `skaffold run --default-repo=<registry>`, with image tags generated from git commits for versioning.
8+
9+
Relevant codebase elements:
10+
- `skaffold.yaml`: Defines build artifacts, manifests, and profiles (e.g., `gcb` for cloud builds).
11+
- `kubernetes-manifests/`: Base Kubernetes YAMLs for services, aggregated by `kustomization.yaml`.
12+
- `cloudbuild.yaml`: Configuration for triggering the workflow in Cloud Build.
13+
- `src/*/Dockerfile`: Build contexts for each microservice.
14+
15+
Post-deployment, the frontend is accessible via the external IP of the `frontend-external` LoadBalancer service.
16+
17+
## Components
18+
19+
- **Skaffold**: Core orchestrator handling build-push-deploy cycle. Configured for multi-platform builds (linux/amd64, linux/arm64), local Docker/Buildkit, or Google Cloud Build via profiles.
20+
- **Dockerfiles**: Service-specific in `src/<service>/`, e.g., multi-stage builds for Java (adservice), Go (frontend), Node.js (currencyservice), etc.
21+
- **Container Registry**: Stores built images; specified via `--default-repo` (e.g., `us-docker.pkg.dev/PROJECT_ID/microservices-demo`).
22+
- **Kustomize**: Renders manifests from `kubernetes-manifests/`, allowing patches for image tags and optional components (e.g., Redis, Istio commented out).
23+
- **Kubernetes Resources**: Deployments, Services, ConfigMaps, etc., for 10+ microservices plus Redis. LoadGenerator deployed separately via Skaffold module.
24+
- **GKE and Tools**: GKE cluster as runtime; `gcloud` for auth/credentials; `kubectl` for apply.
25+
- **Cloud Build**: Optional CI/CD; uses `cloudbuild.yaml` to run Skaffold in a containerized builder, specifying cluster details via substitutions.
26+
27+
## Direct Deployment Sequence (Local Skaffold)
28+
29+
This diagram illustrates the flow when running Skaffold locally against a GKE context.
30+
31+
```mermaid
32+
sequenceDiagram
33+
participant U as User/CLI
34+
participant S as Skaffold
35+
participant B as Builder (Docker/Buildkit)
36+
participant R as Registry (Artifact Registry)
37+
participant K as Kustomize
38+
participant C as GKE Cluster (kubectl)
39+
U->>S: skaffold run --default-repo=<registry>
40+
Note over S: Parse skaffold.yaml<br/>Configs: app, loadgenerator
41+
loop For each service artifact
42+
S->>B: Build image from src/<service>/Dockerfile
43+
B->>B: Use local Docker or GCB profile
44+
B->>R: Tag & push <registry>/<service>:<tag>
45+
end
46+
Note over S: Update image tags in manifests
47+
S->>K: kustomize build kubernetes-manifests/
48+
K->>C: kubectl apply -f rendered.yaml
49+
C->>C: Deploy pods, services, etc.
50+
Note over C: Includes Redis if not customized
51+
U->>C: kubectl get service frontend-external
52+
C->>U: External IP for access
53+
```
54+
55+
## Cloud Build CI/CD Variant Sequence
56+
57+
For automated builds via `gcloud builds submit --config=cloudbuild.yaml`, the flow delegates building to Cloud Build.
58+
59+
```mermaid
60+
sequenceDiagram
61+
participant U as User/Cloud Build Trigger
62+
participant CB as Google Cloud Build
63+
participant S as Skaffold (inside CB)
64+
participant B as Cloud Build Workers
65+
participant R as Registry
66+
participant C as GKE Cluster
67+
U->>CB: gcloud builds submit --config=cloudbuild.yaml --substitutions=_ZONE=...,_CLUSTER=...
68+
CB->>S: Run steps: get-credentials, skaffold run --default-repo=gcr.io/$PROJECT_ID
69+
S->>B: Build images (remote)
70+
B->>R: Push images
71+
S->>C: kubectl apply manifests
72+
C->>CB: Deployment status
73+
CB->>U: Build logs and status
74+
```
75+
76+
## Additional Design Aspects
77+
78+
### Prerequisites
79+
- GCP project with GKE and Artifact Registry enabled.
80+
- `gcloud` authenticated and `kubectl` context set to GKE: `gcloud container clusters get-credentials <cluster> --zone=<zone>`.
81+
- Docker installed locally (or use `gcb` profile).
82+
- For Cloud Build: Service account with Kubernetes Engine Developer role; substitutions for `_ZONE` and `_CLUSTER`.
83+
84+
### Customization and Extensibility
85+
- **Profiles in Skaffold**: Activate via `-p <profile>`, e.g., `-p gcb` for remote builds, `-p network-policies` to patch manifests with additional Kustomize paths.
86+
- **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).
87+
- **Image Tagging**: Git commit-based for traceability; customizable via `tagPolicy` in `skaffold.yaml`.
88+
- **Load Generator**: Separate Skaffold config (`loadgenerator`) requiring `app`; deploys `loadgenerator.yaml` manifest.
89+
- **Multi-Architecture**: Builds for amd64 and arm64, useful for GKE Autopilot or diverse node pools.
90+
91+
### Error Handling and Best Practices
92+
- Skaffold provides verbose logging, dry-runs (`skaffold run --dry-run`), and cleanup (`skaffold delete`).
93+
- Monitor deployment with `kubectl get pods/services` or integrate with Cloud Operations.
94+
- For production, combine with release workflow for tagged images and Helm/Kustomize for config management.
95+
- Trade-offs: Local builds require significant resources; Cloud Build adds latency but scales and avoids local setup.
96+
97+
### Integration Points
98+
- **Terraform Workflow**: Provisions GKE cluster beforehand.
99+
- **Local Development**: Shares `skaffold.yaml` with `skaffold dev` for hot-reload.
100+
- **Release Process**: Uses similar build/push logic for official images.
101+
- **Kustomize Workflow**: Post-deploy customizations via `kubectl apply -k`.
102+
103+
This design promotes a seamless transition from development to GKE deployment, emphasizing automation and configurability.

0 commit comments

Comments
 (0)