diff --git a/.exp/design-workflow-3-helm-chart-deployment.md b/.exp/design-workflow-3-helm-chart-deployment.md
index 2ba4e5325e6..2a65b34db43 100644
--- a/.exp/design-workflow-3-helm-chart-deployment.md
+++ b/.exp/design-workflow-3-helm-chart-deployment.md
@@ -21,7 +21,7 @@ The chart is marked as experimental in the README, encouraging feedback via GitH
- Global settings: `images.repository`, 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.
- - Frontend-specific: `externalService: true` for LoadBalancer exposure, `virtualService.create: false` for Istio, branding/platform options.
+ - Frontend-specific: `externalService.create` (default true) for creating LoadBalancer Service with optional `externalService.annotations` map for custom metadata (e.g., external-dns integration for automatic DNS management), `virtualService.create: false` for Istio, branding (`cymbalBranding`), platform options.
- Observability: Flags for Google Cloud Operations (tracing, metrics, profiler) and OTEL collector.
- Security: `seccompProfile.enable: false`, `securityContext.enable: true`.
- **templates/** Directory:
@@ -34,6 +34,7 @@ The chart is marked as experimental in the README, encouraging feedback via GitH
### Deployed Resources
- **Core**: Deployments and Services for 11 microservices (adService, cartService, etc.) + loadGenerator.
- **Optional**:
+ - Frontend-external LoadBalancer Service if `frontend.externalService.create: true`, supporting custom annotations (e.g., for external-dns).
- In-cluster Redis StatefulSet if `cartDatabase.inClusterRedis.create: true`.
- NetworkPolicies per service if enabled.
- Istio AuthorizationPolicies.
@@ -55,14 +56,14 @@ sequenceDiagram
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->>H: Render templates (e.g., service Deployments, conditional policies and annotations)
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
+ Note over R: Microservices start up, perform gRPC health checks, and begin inter-service communication
+ R->>S: Pods become ready and Services get endpoints
S->>H: Confirmation of resource creation
- H->>U: Helm release status (success/failure); NOTES for frontend access
+ H->>U: Helm release status (success or failure) and NOTES for frontend access
```
### Component Creation Flowchart
@@ -74,7 +75,7 @@ flowchart TD
Load --> CheckFlags[Evaluate feature flags e.g. networkPolicies.create, cartDatabase.type]
CheckFlags -->|redis| CreateRedis[Create in-cluster Redis StatefulSet/Service]
CheckFlags -->|spanner| ConfigSpanner[Set env vars & annotations for Spanner connection]
- CheckFlags --> RenderServices[Render per-service templates:
Deployments, Services, Probes, Resources]
+ CheckFlags --> RenderServices[Render per-service templates:
Deployments, Services, Probes, Resources, conditional annotations on external services]
RenderServices -->|flags enabled| AddPolicies[Add NetworkPolicies, AuthPolicies, Sidecars]
RenderServices --> AddOTEL[Add OTEL Collector if create: true]
AddPolicies --> Apply[Apply all rendered resources to K8s API]
@@ -95,6 +96,7 @@ flowchart TD
- **Advanced with Spanner**: Set `cartservice.database.type=spanner`, provide `connectionString`, enable `serviceAccounts.create=true` with GCP IAM annotations for least-privilege access.
- **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.
+- **External DNS Management**: Configure `frontend.externalService.annotations` to add custom annotations for tools like external-dns, e.g., `--set 'frontend.externalService.annotations.external-dns\.alpha\.kubernetes\.io/hostname=onlineboutique.example.com'` for automatic DNS record creation based on LoadBalancer IP.
- **Security**: Enable `networkPolicies.create=true` for fine-grained traffic control; `seccompProfile.enable=true` for pod security.
### Flow of Information in Application
diff --git a/pr-analysis-2636.md b/pr-analysis-2636.md
new file mode 100644
index 00000000000..cd9183824df
--- /dev/null
+++ b/pr-analysis-2636.md
@@ -0,0 +1,86 @@
+# PR #2636: Workflow Design Impact Analysis
+
+## Affected Workflows
+- **Workflow 3: Helm Chart Deployment**: The PR directly modifies files in the `helm-chart/` directory, including `values.yaml` and `templates/frontend.yaml`, introducing new configuration options for the frontend external service annotations. This aligns with the workflow's relevant files (`helm-chart/`, `helm-chart/values.yaml`) and impacts the templating and customization mechanisms.
+
+- **Workflow 7: Release Process**: Changes to the Helm chart are incorporated into the release artifacts via `docs/releasing/make-helm-chart.sh`, which packages and pushes the chart to Artifact Registry. Thus, new releases will include the enhanced external service configuration.
+
+## Workflow 3 Analysis
+### Summary of design changes
+The PR adds support for custom annotations on the frontend-external LoadBalancer Service by restructuring `frontend.externalService` into an object with `create: true` (default) and `annotations: {}` fields in `values.yaml`. Template logic in `frontend.yaml` now conditionally applies these annotations and uses `.create` for service creation. Related updates in `README.md`, `NOTES.txt`, and CI workflows ensure consistency with the new structure. This enhances the workflow's flexibility for external integrations like external-dns, which can use annotations to automate DNS records for the service IP.
+
+**Affected aspects**: Values schema, template rendering for services, conditional resource creation, and documentation examples. The core deployment sequence remains intact, but rendering now includes annotation application as a new step/capability.
+
+**Implementation**: New values path and YAML templating with `{{- with .Values.frontend.externalService.annotations }}` block in service metadata.
+
+**Benefits/Implications**: Enables seamless DNS management in GKE/other clouds, reducing manual configuration for production deploys. Potential for broader annotation support in future services.
+
+The design document (`.exp/design-workflow-3-helm-chart-deployment.md`) has been updated to document the new feature in values description, deployed resources, customization examples, and diagram notes. No major structural changes to sequences or flows; minor textual updates to reflect added capability.
+
+### Pre-PR vs Post-PR Deployment Flow (Sequence Diagram Diff)
+The following updated sequence diagram highlights changes in green (additions) and yellow (modifications):
+
+```mermaid
+sequenceDiagram
+ participant U as User/CLI
+ 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
+ Note right of H: New: Merge includes frontend.externalService.annotations
+ H->>H: Render templates (e.g., service Deployments, conditional policies and annotations)
+ Note right of H: Change: Now applies annotations to external LoadBalancer Service if configured
+ 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 up, perform gRPC health checks, and begin inter-service communication
+ R->>S: Pods become ready and Services get endpoints
+ S->>H: Confirmation of resource creation
+ H->>U: Helm release status (success or failure) and NOTES for frontend access
+ Note right of U: NOTES updated for .create flag
+```
+
+- **Green additions**: Notes on new merge and render steps for annotations.
+- **Yellow changes**: Updated render message and NOTES reference.
+- **No removals**.
+
+### Pre-PR vs Post-PR Component Creation (Flowchart Diff)
+Updated flowchart with changes highlighted:
+
+```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]
+ CheckFlags -->|spanner| ConfigSpanner[Set env vars & annotations for Spanner connection]
+ CheckFlags --> RenderServices[[Render per-service templates:
Deployments, Services, Probes, Resources, conditional annotations on external services]]
+ RenderServices -->|flags enabled| AddPolicies[Add NetworkPolicies, AuthPolicies, Sidecars]
+ RenderServices --> AddOTEL[Add OTEL Collector if create: true]
+ AddPolicies --> Apply[Apply all rendered resources to K8s API]
+ AddOTEL --> Apply
+ CreateRedis --> Apply
+ ConfigSpanner --> Apply
+ Apply --> Deploy[Deploy Pods; Image pulls from repository/tag]
+ Deploy --> Expose[Expose frontend via LoadBalancer or VirtualService
with optional annotations]
+ Expose --> Ready[Application ready: Access via external IP]
+ style Start fill:#e1f5fe
+ style Ready fill:#e8f5e8
+ classDef change fill:#fff9c4
+ classDef addition fill:#e8f5e8
+ class RenderServices,Expose change
+```
+
+- **Yellow (change fill)**: RenderServices and Expose nodes updated to mention annotations support.
+- **Green (addition)**: No new nodes; integrated into existing.
+- **No red removals**.
+
+## Workflow 7 Analysis
+### Summary of design changes
+No structural changes to the release process scripts or logic. However, the PR's updates to `helm-chart/` are automatically included when running `make-helm-chart.sh`, which updates Chart.yaml, packages the chart, and pushes to OCI registry. Future releases will propagate the new annotations feature to users deploying from official charts.
+
+**Implications**: Enhances released Helm chart functionality without altering the release workflow itself. Benefits users of released artifacts with improved external service configuration options.
+
+No design documentation found for Workflow 7, so no diagrams or further updates performed. If a design doc exists or is added, it should note the inclusion of Helm chart enhancements in artifacts.
+