From 593ea06ac99da3a7ea2f4929865e3feae7ae4768 Mon Sep 17 00:00:00 2001 From: Gaurav Agerwala Date: Sun, 7 Dec 2025 09:22:08 -0800 Subject: [PATCH] Update design for PR #2636: feat(helm): adding property to define annotations on external service that would enable integration with external-dns --- ...design-workflow-3-helm-chart-deployment.md | 14 +-- pr-analysis-2636.md | 86 +++++++++++++++++++ 2 files changed, 94 insertions(+), 6 deletions(-) create mode 100644 pr-analysis-2636.md 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. +