Skip to content

Update design for PR #2636: feat(helm): adding property to define annotations on external service that would enable integration with external-dns #5

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
gauravagerwala wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Update design for PR #2636: feat(helm): adding property to define annotations on external service that would enable integration with external-dns #5

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 8 additions & 6 deletions .exp/design-workflow-3-helm-chart-deployment.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand All @@ -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.
Expand All @@ -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
Expand All @@ -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:<br/>Deployments, Services, Probes, Resources]
CheckFlags --> RenderServices[Render per-service templates:<br/>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]
Expand All @@ -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
Expand Down
86 changes: 86 additions & 0 deletions pr-analysis-2636.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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:<br/>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<br/>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.

Loading