gauravagerwala · gauravagerwala · Dec 7, 2025
diff --git a/.exp/design-workflow-3-helm-chart-deployment.md b/.exp/design-workflow-3-helm-chart-deployment.md
@@ -18,9 +18,9 @@ The chart is marked as experimental in the README, encouraging feedback via GitH
 ### Helm Chart Structure
 - **Chart.yaml**: Defines the chart's metadata, including name (`onlineboutique`), version (`0.10.4`), and type (`application`). No external dependencies.
 - **values.yaml**: Comprehensive configuration file with defaults for:
-  - Global settings: `images.repository`, service accounts creation/annotation, feature flags (e.g., `networkPolicies.create: false`, `opentelemetryCollector.create: false`).
+  - Global settings: `images.repository`, `images.tag: ""` (to override the chart's appVersion), `images.imagePullSecrets: []` (Kubernetes secrets for pulling images from private registries or proxies), service accounts creation/annotation, feature flags (e.g., `networkPolicies.create: false`, `opentelemetryCollector.create: false`).
   - Per-service configs: Resource requests/limits for each microservice (e.g., `adService.resources.requests.cpu: 200m`), enable/disable flags (`create: true`).
-  - Database: `cartDatabase.type: redis` (default in-cluster Redis) or `spanner` with connection string and IAM annotations.
+  - Database: `cartDatabase.type: redis` (default in-cluster Redis, configurable via `inClusterRedis.imageRepository: ''` for custom repositories like Docker Hub proxies and `publicRepository: true` for direct Docker Hub pulls) or `spanner` with connection string and IAM annotations.
   - Frontend-specific: `externalService: true` for LoadBalancer exposure, `virtualService.create: false` for Istio, branding/platform options.
   - Observability: Flags for Google Cloud Operations (tracing, metrics, profiler) and OTEL collector.
   - Security: `seccompProfile.enable: false`, `securityContext.enable: true`.
@@ -32,14 +32,15 @@ The chart is marked as experimental in the README, encouraging feedback via GitH
 - **README.md**: Provides basic and advanced installation examples, links to blog posts on advanced scenarios (e.g., Spanner integration, gRPC health probes).
 
 ### Deployed Resources
-- **Core**: Deployments and Services for 11 microservices (adService, cartService, etc.) + loadGenerator.
+- **Core**: Deployments and Services for 11 microservices (adService, cartService, etc.) + loadGenerator. Pod specifications include optional `imagePullSecrets` for secure image pulling.
 - **Optional**:
-  - In-cluster Redis StatefulSet if `cartDatabase.inClusterRedis.create: true`.
+  - In-cluster Redis StatefulSet if `cartDatabase.inClusterRedis.create: true`, with configurable image repository for proxy support.
   - NetworkPolicies per service if enabled.
   - Istio AuthorizationPolicies.
   - Sidecars (e.g., for TLS origination to external Redis).
   - ServiceAccounts with annotations (e.g., for GCP Workload Identity).
-- **Integration Points**: Supports external databases, custom images (e.g., from Artifact Registry), and Istio gateways.
+  - imagePullSecrets applied to all Deployments and StatefulSets if `images.imagePullSecrets` is configured.
+- **Integration Points**: Supports external databases, custom images (e.g., from Artifact Registry, private registries via `imagePullSecrets`, or Docker Hub proxies via `cartDatabase.inClusterRedis.imageRepository`), and Istio gateways.
 
 ## Sequence Diagrams
 
@@ -52,17 +53,17 @@ sequenceDiagram
     participant H as Helm Client
     participant S as Kubernetes Server (API)
     participant R as Resources (Pods, Services, etc.)
-    U->>H: helm upgrade --install [options] [values overrides]
-    H->>H: Load chart from OCI registry or local path
-    H->>H: Merge default values.yaml with user overrides
-    H->>H: Render templates (e.g., service Deployments, conditional policies)
-    H->>S: Apply rendered YAMLs (e.g., Deployments, Services, Redis if enabled)
-    S->>R: Create/Update Kubernetes objects
-    S->>R: Schedule Pods, pull images, run init containers if needed
-    Note over R: Microservices start; gRPC health checks; inter-service communication begins
-    R->>S: Pods become ready; Services get endpoints
-    S->>H: Confirmation of resource creation
-    H->>U: Helm release status (success/failure); NOTES for frontend access
+    U->>H: "helm upgrade --install [options] [values overrides incl. imagePullSecrets & custom image repos]"
+    H->>H: "Load chart from OCI registry or local path"
+    H->>H: "Merge default values.yaml with user overrides"
+    H->>H: "Render templates (e.g., service Deployments, conditional policies, imagePullSecrets)"
+    H->>S: "Apply rendered YAMLs (e.g., Deployments, Services, Redis if enabled)"
+    S->>R: "Create/Update Kubernetes objects"
+    S->>R: "Schedule Pods, pull images using configured secrets & repos, run init containers if needed"
+    Note over R: "Microservices start, gRPC health checks, inter-service communication begins"
+    R->>S: "Pods become ready, Services get endpoints"
+    S->>H: "Confirmation of resource creation"
+    H->>U: "Helm release status (success/failure), NOTES for frontend access"
 ```
 
 ### Component Creation Flowchart
@@ -71,17 +72,20 @@ This flowchart shows decision points based on values.yaml flags during template
 ```mermaid
 flowchart TD
     Start[User runs helm install/upgrade with values] --> Load[Load Chart.yaml, values.yaml, templates/]
-    Load --> CheckFlags[Evaluate feature flags e.g. networkPolicies.create, cartDatabase.type]
-    CheckFlags -->|redis| CreateRedis[Create in-cluster Redis StatefulSet/Service]
+    Load --> CheckFlags[Evaluate feature flags e.g. networkPolicies.create, cartDatabase.type, images.imagePullSecrets]
+    CheckFlags -->|redis| CreateRedis[Create in-cluster Redis StatefulSet/Service with configurable image repo]
     CheckFlags -->|spanner| ConfigSpanner[Set env vars & annotations for Spanner connection]
     CheckFlags --> RenderServices[Render per-service templates:<br/>Deployments, Services, Probes, Resources]
+    RenderServices --> RenderImage[Render image configs:<br/>- imagePullSecrets in pod specs if set<br/>- Redis image repo logic]
     RenderServices -->|flags enabled| AddPolicies[Add NetworkPolicies, AuthPolicies, Sidecars]
     RenderServices --> AddOTEL[Add OTEL Collector if create: true]
+    RenderImage --> AddPolicies
+    RenderImage --> AddOTEL
     AddPolicies --> Apply[Apply all rendered resources to K8s API]
     AddOTEL --> Apply
     CreateRedis --> Apply
     ConfigSpanner --> Apply
-    Apply --> Deploy[Deploy Pods; Image pulls from repository/tag]
+    Apply --> Deploy[Deploy Pods; Image pulls from repository/tag using secrets if configured]
     Deploy --> Expose[Expose frontend via LoadBalancer or VirtualService]
     Expose --> Ready[Application ready: Access via external IP]
     style Start fill:#e1f5fe
@@ -96,6 +100,7 @@ flowchart TD
 - **Service Mesh Integration**: Enable `authorizationPolicies.create=true`, `frontend.virtualService.create=true` with Istio gateway details.
 - **Observability**: Set `opentelemetryCollector.create=true`, `googleCloudOperations.tracing=true` for metrics/traces export to Cloud Operations.
 - **Security**: Enable `networkPolicies.create=true` for fine-grained traffic control; `seccompProfile.enable=true` for pod security.
+- **Private Image Registries and Proxies**: Set `images.imagePullSecrets: [{"name": "regcred"}]` to enable pulling from private registries or proxies (requires pre-creating the named secret in the namespace). For the Redis image (from Docker Hub), set `cartDatabase.inClusterRedis.imageRepository: "proxy.example.com/library"` and `inClusterRedis.publicRepository: false` to use a mirrored version.
 
 ### Flow of Information in Application
 Once deployed, information flows as per the system architecture (see project-overview.md):

diff --git a/docs/pr-analysis-2760.md b/docs/pr-analysis-2760.md
@@ -0,0 +1,75 @@
+# PR #2760: Workflow Design Impact Analysis
+
+## Affected Workflows
+- **Workflow 3 - Helm Chart Deployment**: The PR directly modifies `helm-chart/values.yaml` and multiple templates in `helm-chart/templates/`, which are the primary files for this workflow. These changes introduce new configuration options for image pulling, impacting how deployments handle container images.
+- **Workflow 7 - Release Process**: Although not directly listed in relevant_files, the release script `docs/releasing/make-helm-chart.sh` packages the entire `helm-chart/` directory into an OCI artifact. Changes to templates and values affect the released Helm chart version.
+- **Workflow 8 - Adding New Microservice**: This workflow requires updating the Helm chart (step 7 in `docs/adding-new-microservice.md`). The PR's additions to templates (e.g., imagePullSecrets blocks) provide a model for new service templates and enhance configurability for image sources in new services.
+
+No other workflows are affected, as their relevant files (e.g., skaffold.yaml, kustomize/, terraform/) remain unchanged, and the PR is scoped to Helm-specific configurations.
+
+## Workflow 3 Analysis
+### Summary of design changes
+The PR adds support for Kubernetes `imagePullSecrets` across all microservice deployments and the optional Redis StatefulSet, enabling pulls from private registries or proxy caches. It also introduces a dedicated `imageRepository` for the cart service's Redis image to handle Docker Hub mirroring separately from the global GCR-based repository.
+
+- **Affected aspects**: Configuration in `values.yaml` (new fields under `images` and `cartDatabase.inClusterRedis`), template rendering logic (conditional `imagePullSecrets` in pod specs, extended image selection for Redis).
+- **Implementation**: Global list of secrets rendered via Helm templating into every pod template; Redis image uses priority: custom repo > global repo > public Docker Hub sha if `publicRepository: true`.
+- **Benefits**: Improves deployability in secured environments (e.g., enterprise clusters with internal registries), reduces external dependencies, no breaking changes (options default to empty/off).
+- **Implications**: Users must provision secrets in the target namespace; future releases include these features; aligns with K8s best practices for image security.
+
+The design document `.exp/design-workflow-3-helm-chart-deployment.md` has been updated to document these changes in sections on values.yaml, deployed resources, customization examples, and both Mermaid diagrams (sequence and flowchart) to reflect new configuration and rendering steps.
+
+### Changes to Deployment Flow Sequence Diagram
+This diagram highlights additions (green) and changes (yellow) from the PR in the original sequence diagram.
+
+```mermaid
+flowchart TD
+    subgraph Additions [Additions - Green]
+        A1[New input values: imagePullSecrets list & Redis imageRepository]:::add
+        A2[New template logic: conditional imagePullSecrets in all pod specs]:::add
+        A3[New template logic: conditional Redis image repo in cartservice template]:::add
+    end
+    subgraph Changes [Changes/Enhancements - Yellow]
+        C1[Merge step now includes new image config values]:::change
+        C2[Render step now generates secrets fields & custom image refs]:::change
+        C3[Apply step includes YAML with secrets/image configs]:::change
+        C4[Pull images step now uses secrets & potentially custom repos for pulls]:::change
+    end
+    classDef add fill:#d4edda,stroke:#28a745,stroke-width:2px
+    classDef change fill:#fff3cd,stroke:#ffc107,stroke-width:2px
+```
+
+### Changes to Component Creation Flowchart
+This diagram shows additions and changes to the original flowchart.
+
+```mermaid
+flowchart TD
+    subgraph Additions [Additions - Green]
+        NA1[Evaluate new flags: images.imagePullSecrets, cartDatabase.inClusterRedis.imageRepository]:::add
+        NA2[New node: RenderImage - add imagePullSecrets to pod specs & Redis image logic]:::add
+        NA3[Enhanced CreateRedis: include image repo config]:::add
+    end
+    subgraph Changes [Changes - Yellow]
+        NC1[CheckFlags now includes new image-related flags]:::change
+        NC2[Deploy now specifies using secrets for image pulls]:::change
+    end
+    classDef add fill:#d4edda,stroke:#28a745,stroke-width:2px
+    classDef change fill:#fff3cd,stroke:#ffc107,stroke-width:2px
+```
+
+## Workflow 7 Analysis
+### Summary of design changes
+Changes to `helm-chart/` indirectly affect this workflow, as the Helm chart is built, versioned (via Chart.yaml updates in script), packaged, and pushed to OCI registry during release. The new options will be part of future releases, allowing downstream users to leverage private image support without manual patches.
+
+No design document exists in `.exp/` for this workflow, so no diagrams updated. The core release steps remain unchanged, but the artifact now includes enhanced configurability.
+
+No Mermaid diagrams to update.
+
+## Workflow 8 Analysis
+### Summary of design changes
+When adding a new microservice, step 7 involves creating/updating Helm templates and values for the new service. The PR demonstrates adding `imagePullSecrets` to pod specs and provides a pattern for handling special image sources (like the Redis example), which new services can adopt for consistency.
+
+No design document exists in `.exp/` for this workflow (though operational guide in `docs/adding-new-microservice.md`). Thus, no diagrams updated, but future integrations benefit from the enhanced chart structure.
+
+No Mermaid diagrams to update.
+
+[PR #2760](https://github.com/GoogleCloudPlatform/microservices-demo/pull/2760)