# aws/aws-application-networking-k8s architecture

> Architecture diagram of the GitHub repository aws/aws-application-networking-k8s, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aws/aws-application-networking-k8s
- Repository: https://github.com/aws/aws-application-networking-k8s

## Overview

1. **What this repo is**
   - This is a Kubernetes controller that implements the Gateway API for AWS VPC Lattice.
   - The runtime boundary is a cluster-resident control plane: it watches Kubernetes API objects, computes desired AWS Lattice state, and reconciles AWS resources through SDK-backed service clients.

2. **Primary Kubernetes inputs**
   - The controller consumes Gateway API objects such as `GatewayClass`, `Gateway`, `HTTPRoute`, `GRPCRoute`, and `TLSRoute`.
   - It also watches application and policy CRDs defined in this repo: `ServiceExport`, `ServiceImport`, `AccessLogPolicy`, `IAMAuthPolicy`, `TargetGroupPolicy`, and `VPCAssociationPolicy`.
   - Standard Kubernetes `Service` and `Pod` objects are part of the reconciliation model as well.

3. **Controller layer**
   - `pkg/controllers` contains the individual reconcilers for each resource type plus shared event handlers and predicates.
   - The controllers do not directly talk to AWS; they translate object changes into internal reconciliation work and manage lifecycle concerns like finalizers, owner references, and cross-resource mapping.
   - `pkg/runtime` provides common reconcile plumbing and error handling.

4. **Event-to-reconcile fanout**
   - The `eventhandlers` and `predicates` packages are the glue between Kubernetes events and controller work queues.
   - These handlers map secondary resources back to the owning `Gateway`, route, service, or policy so that a change in one object triggers the right dependent reconciliation.
   - This is important for the diagram because a single AWS-side resource often depends on multiple Kubernetes objects.

5. **Internal desired-state model**
   - `pkg/model/core` and `pkg/model/lattice` define the controller’s internal representation of desired infrastructure.
   - `core` holds generic concepts like stacks, routes, policies, and resource graphs; `lattice` specializes those into VPC Lattice resources such as services, listeners, rules, target groups, targets, service networks, and access-log subscriptions.
   - `pkg/model/core/graph` shows that reconciliation is graph-driven: resources are ordered and traversed based on dependencies before being deployed.

6. **Translation from Kubernetes objects to model**
   - `pkg/gateway` contains the builders that convert Kubernetes objects into the internal Lattice model.
   - Separate builders exist for services, listeners, rules, target groups, targets, and access-log subscriptions, which makes the architecture split cleanly between “Kubernetes intent” and “AWS desired state.”
   - This layer is where Gateway API semantics, annotations, and policy objects are resolved into concrete infrastructure decisions.

7. **AWS deployment layer**
   - `pkg/deploy/lattice` is the application engine that turns the model into AWS API actions.
   - It is organized around resource-specific managers and synthesizers for service networks, services, listeners, rules, target groups, targets, IAM auth policies, and access-log subscriptions.
   - `pkg/deploy/stack_deployer.go`, `stack_marshaller.go`, and `stack_schema_builder.go` indicate a stack-oriented apply model: the controller computes a stack, serializes it, and reconciles that stack against AWS.
   - `pkg/deploy/externaldns` is an auxiliary integration that can emit `DNSEndpoint` resources for ExternalDNS.

8. **AWS service boundary**
   - `pkg/aws/services` wraps the external AWS APIs used by the controller, including VPC Lattice, ACM/certificate discovery, and tagging.
   - `pkg/aws/cloud.go` is the higher-level cloud abstraction used by the deployers and managers.
   - The controller also relies on EC2 metadata/config helpers in `pkg/config`, which matters for environment-specific AWS behavior.

9. **Admission webhook path**
   - `pkg/webhook` provides a mutating webhook, centered on pod readiness-gate injection.
   - This is a separate control path from reconciliation: it modifies incoming Kubernetes objects at admission time rather than reconciling them after persistence.
   - The webhook is packaged and deployed alongside the controller in `config/webhook` and Helm manifests.

10. **Kubernetes lifecycle helpers**
   - `pkg/k8s` contains shared utilities for events, finalizers, and policy handling.
   - Finalizers are the cleanup boundary that ensures AWS resources are deleted before Kubernetes objects disappear.
   - The readiness-gate and pod-related helpers show that pod health is part of the control plane, not just route publishing.

11. **Packaging and deployment surfaces**
   - `config`, `helm`, and `files/controller-installation` contain the installable manifests, CRDs, RBAC, webhook config, and versioned deployment YAMLs.
   - `docs`, `files/examples`, and `test/suites/integration` are not runtime components, but they document and verify the supported architecture and supported object flows.

12. **How to draw the main diagram**
   - Left side: Kubernetes API server with Gateway API objects, service/policy CRDs, and Pods.
   - Middle: controllers, event mapping, model builders, stack graph, and deployers.
   - Right side: AWS APIs for VPC Lattice, ACM, and tagging, plus optional ExternalDNS integration.
   - A separate side path should show the mutating webhook injecting pod readiness gates before the normal reconcile loop sees the objects.

Main entry points: [`pkg/deploy/stack_deployer.go`](https://github.com/aws/aws-application-networking-k8s/blob/main/pkg/deploy/stack_deployer.go) (Stack deployer), [`pkg/controllers/eventhandlers`](https://github.com/aws/aws-application-networking-k8s/tree/main/pkg/controllers/eventhandlers) (Event fanout), [`pkg/runtime`](https://github.com/aws/aws-application-networking-k8s/tree/main/pkg/runtime) (Reconcile runtime), [`pkg/controllers/gateway_controller.go`](https://github.com/aws/aws-application-networking-k8s/blob/main/pkg/controllers/gateway_controller.go) (Gateway ctrl)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_k8s["Kubernetes inputs"]
  node_gateway_api["Gateway API<br/>k8s api"]
  node_app_policies["App CRDs<br/>k8s crds"]
  node_service_pod["Service/Pod<br/>k8s core"]
end

subgraph group_group_control["Controller plane"]
  node_gateway_controller["Gateway ctrl<br/>reconciler"]
  node_route_controller["Route ctrl<br/>reconciler"]
  node_service_controller["Service ctrl<br/>reconciler"]
  node_policy_controllers["Policy ctrls<br/>reconcilers"]
  node_eventhandlers["Event fanout<br/>mapping"]
  node_predicates["Predicates<br/>filters"]
  node_runtime["Reconcile runtime<br/>control plumbing"]
  node_k8s_helpers["K8s helpers<br/>lifecycle utils"]
  node_gateway_builders["Model builders<br/>translation"]
end

subgraph group_group_model["Desired state model"]
  node_core_model["Core model<br/>domain model"]
  node_resource_graph["Resource graph<br/>dependency graph"]
  node_lattice_model["Lattice model<br/>domain model"]
end

subgraph group_group_deploy["AWS deployment"]
  node_stack_deployer["Stack deployer<br/>apply engine<br/>[stack_deployer.go]"]
  node_lattice_managers["Lattice managers"]
  node_externaldns["ExternalDNS<br/>integration"]
end

subgraph group_group_boundary["External systems"]
  node_aws_cloud["AWS cloud<br/>cloud boundary<br/>[cloud.go]"]
  node_aws_services["AWS APIs<br/>sdk wrappers"]
end

subgraph group_group_admission["Admission path"]
  node_webhook["Mutating webhook<br/>admission"]
end

node_gateway_api -->|"watch"| node_gateway_controller
node_gateway_api -->|"watch"| node_route_controller
node_service_pod -->|"watch"| node_service_controller
node_app_policies -->|"watch"| node_policy_controllers
node_gateway_controller -->|"fanout"| node_eventhandlers
node_route_controller -->|"fanout"| node_eventhandlers
node_service_controller -->|"fanout"| node_eventhandlers
node_policy_controllers -->|"fanout"| node_eventhandlers
node_eventhandlers -->|"filter"| node_predicates
node_gateway_controller -->|"run via"| node_runtime
node_route_controller -->|"run via"| node_runtime
node_service_controller -->|"run via"| node_runtime
node_policy_controllers -->|"run via"| node_runtime
node_runtime -->|"lifecycle"| node_k8s_helpers
node_gateway_controller -->|"build"| node_gateway_builders
node_route_controller -->|"build"| node_gateway_builders
node_policy_controllers -->|"build"| node_gateway_builders
node_gateway_builders -->|"emit"| node_core_model
node_core_model -->|"order"| node_resource_graph
node_core_model -->|"specialize"| node_lattice_model
node_resource_graph -->|"plan"| node_stack_deployer
node_lattice_model -->|"apply"| node_stack_deployer
node_stack_deployer -->|"invoke"| node_aws_cloud
node_aws_cloud -->|"backed by"| node_aws_services
node_stack_deployer -->|"manage"| node_lattice_managers
node_lattice_managers -->|"sdk calls"| node_aws_services
node_stack_deployer -.->|"optional"| node_externaldns
node_webhook -->|"mutate"| node_service_pod
node_webhook -->|"uses"| node_k8s_helpers

click node_app_policies "https://github.com/aws/aws-application-networking-k8s/tree/main/pkg/apis/applicationnetworking/v1alpha1"
click node_gateway_controller "https://github.com/aws/aws-application-networking-k8s/blob/main/pkg/controllers/gateway_controller.go"
click node_route_controller "https://github.com/aws/aws-application-networking-k8s/blob/main/pkg/controllers/route_controller.go"
click node_service_controller "https://github.com/aws/aws-application-networking-k8s/blob/main/pkg/controllers/service_controller.go"
click node_policy_controllers "https://github.com/aws/aws-application-networking-k8s/tree/main/pkg/controllers"
click node_eventhandlers "https://github.com/aws/aws-application-networking-k8s/tree/main/pkg/controllers/eventhandlers"
click node_predicates "https://github.com/aws/aws-application-networking-k8s/tree/main/pkg/controllers/predicates"
click node_runtime "https://github.com/aws/aws-application-networking-k8s/tree/main/pkg/runtime"
click node_k8s_helpers "https://github.com/aws/aws-application-networking-k8s/tree/main/pkg/k8s"
click node_gateway_builders "https://github.com/aws/aws-application-networking-k8s/tree/main/pkg/gateway"
click node_core_model "https://github.com/aws/aws-application-networking-k8s/tree/main/pkg/model/core"
click node_resource_graph "https://github.com/aws/aws-application-networking-k8s/tree/main/pkg/model/core/graph"
click node_lattice_model "https://github.com/aws/aws-application-networking-k8s/tree/main/pkg/model/lattice"
click node_stack_deployer "https://github.com/aws/aws-application-networking-k8s/blob/main/pkg/deploy/stack_deployer.go"
click node_lattice_managers "https://github.com/aws/aws-application-networking-k8s/tree/main/pkg/deploy/lattice"
click node_externaldns "https://github.com/aws/aws-application-networking-k8s/tree/main/pkg/deploy/externaldns"
click node_aws_cloud "https://github.com/aws/aws-application-networking-k8s/blob/main/pkg/aws/cloud.go"
click node_aws_services "https://github.com/aws/aws-application-networking-k8s/tree/main/pkg/aws/services"
click node_webhook "https://github.com/aws/aws-application-networking-k8s/tree/main/pkg/webhook"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_gateway_api,node_app_policies,node_service_pod toneBlue
class node_gateway_controller,node_route_controller,node_service_controller,node_policy_controllers,node_eventhandlers,node_predicates,node_runtime,node_k8s_helpers,node_gateway_builders toneAmber
class node_core_model,node_resource_graph,node_lattice_model toneMint
class node_stack_deployer,node_lattice_managers,node_externaldns toneRose
class node_aws_cloud,node_aws_services toneIndigo
class node_webhook toneTeal
```

## Components

### Kubernetes inputs

API objects watched by the controller.

- **Gateway API**: k8s api · GatewayClass, Gateway, HTTPRoute, GRPCRoute, and TLSRoute resources.
- [App CRDs](https://github.com/aws/aws-application-networking-k8s/tree/main/pkg/apis/applicationnetworking/v1alpha1): k8s crds · ServiceExport, ServiceImport, AccessLogPolicy, IAMAuthPolicy, TargetGroupPolicy, and VPCAssociationPolicy. · `pkg/apis/applicationnetworking/v1alpha1`
- **Service/Pod**: k8s core · Standard Kubernetes Service and Pod objects participating in reconciliation.

### Controller plane

Event handling, reconciliation, and lifecycle orchestration.

- [Gateway ctrl](https://github.com/aws/aws-application-networking-k8s/blob/main/pkg/controllers/gateway_controller.go): reconciler · Primary Gateway and GatewayClass reconciliation entry points. · `pkg/controllers/gateway_controller.go`
- [Route ctrl](https://github.com/aws/aws-application-networking-k8s/blob/main/pkg/controllers/route_controller.go): reconciler · Reconciles HTTPRoute, GRPCRoute, and TLSRoute state into the model. · `pkg/controllers/route_controller.go`
- [Service ctrl](https://github.com/aws/aws-application-networking-k8s/blob/main/pkg/controllers/service_controller.go): reconciler · Handles service-facing reconciliation and ownership relationships. · `pkg/controllers/service_controller.go`
- [Policy ctrls](https://github.com/aws/aws-application-networking-k8s/tree/main/pkg/controllers): reconcilers · Reconcilers for access log, IAM auth, target group, and VPC association policies. · `pkg/controllers`
- [Event fanout](https://github.com/aws/aws-application-networking-k8s/tree/main/pkg/controllers/eventhandlers): mapping · Maps secondary object events back to the owning Gateway, route, service, or policy. · `pkg/controllers/eventhandlers`
- [Predicates](https://github.com/aws/aws-application-networking-k8s/tree/main/pkg/controllers/predicates): filters · Event filters that reduce unnecessary reconciles and guard controller triggers. · `pkg/controllers/predicates`
- [Reconcile runtime](https://github.com/aws/aws-application-networking-k8s/tree/main/pkg/runtime): control plumbing · Shared reconcile wrapper, error handling, and lifecycle behavior. · `pkg/runtime`
- [K8s helpers](https://github.com/aws/aws-application-networking-k8s/tree/main/pkg/k8s): lifecycle utils · Finalizers, event helpers, and policy utilities that support object lifecycle management. · `pkg/k8s`
- [Model builders](https://github.com/aws/aws-application-networking-k8s/tree/main/pkg/gateway): translation · Converts Kubernetes intent and policies into Lattice model objects. · `pkg/gateway`

### Desired state model

Internal graph and resource abstractions used to plan deployment.

- [Core model](https://github.com/aws/aws-application-networking-k8s/tree/main/pkg/model/core): domain model · Generic stacks, routes, policies, and resource graph abstractions. · `pkg/model/core`
- [Resource graph](https://github.com/aws/aws-application-networking-k8s/tree/main/pkg/model/core/graph): dependency graph · Orders and traverses resources by dependency before deployment. · `pkg/model/core/graph`
- [Lattice model](https://github.com/aws/aws-application-networking-k8s/tree/main/pkg/model/lattice): domain model · VPC Lattice-specific services, listeners, rules, target groups, targets, and subscriptions. · `pkg/model/lattice`

### AWS deployment

Stack apply logic and AWS-side resource managers.

- [Stack deployer](https://github.com/aws/aws-application-networking-k8s/blob/main/pkg/deploy/stack_deployer.go): apply engine · Serializes a computed stack and reconciles it against AWS. · `pkg/deploy/stack_deployer.go`
- [Lattice managers](https://github.com/aws/aws-application-networking-k8s/tree/main/pkg/deploy/lattice): managers · Resource-specific managers and synthesizers for VPC Lattice objects. · `pkg/deploy/lattice`
- [ExternalDNS](https://github.com/aws/aws-application-networking-k8s/tree/main/pkg/deploy/externaldns): integration · Optional DNSEndpoint emission path for ExternalDNS. · `pkg/deploy/externaldns`

### External systems

AWS services and auxiliary integrations outside the cluster.

- [AWS cloud](https://github.com/aws/aws-application-networking-k8s/blob/main/pkg/aws/cloud.go): cloud boundary · Higher-level AWS abstraction used by deployers and managers. · `pkg/aws/cloud.go`
- [AWS APIs](https://github.com/aws/aws-application-networking-k8s/tree/main/pkg/aws/services): sdk wrappers · Wrappers for VPC Lattice, ACM/certificate discovery, and tagging APIs. · `pkg/aws/services`

### Admission path

Mutating webhook flow that changes objects before reconciliation.

- [Mutating webhook](https://github.com/aws/aws-application-networking-k8s/tree/main/pkg/webhook): admission · Pod admission path that injects readiness gates before reconciliation. · `pkg/webhook`

## Connections

- Gateway API → Gateway ctrl: watch · Gateway API objects trigger controller reconciliation.
- Gateway API → Route ctrl: watch · Route objects drive desired-state updates.
- Service/Pod → Service ctrl: watch · Service and Pod changes feed service reconciliation.
- App CRDs → Policy ctrls: watch · CRD updates trigger policy reconciliation.
- Gateway ctrl → Event fanout: fanout · Primary reconciler uses mappers to enqueue dependents.
- Route ctrl → Event fanout: fanout · Route reconciliation depends on secondary object mapping.
- Service ctrl → Event fanout: fanout · Service changes are propagated through mapped dependents.
- Policy ctrls → Event fanout: fanout · Policy changes are routed to affected resources.
- Event fanout → Predicates: filter · Predicates narrow which events become reconcile work.
- Gateway ctrl → Reconcile runtime: run via · Controllers execute through shared reconcile plumbing.
- Route ctrl → Reconcile runtime: run via · Route reconciliation uses common runtime error handling.
- Service ctrl → Reconcile runtime: run via · Service reconciliation uses shared runtime behavior.
- Policy ctrls → Reconcile runtime: run via · Policy reconcilers share the same runtime boundary.
- Reconcile runtime → K8s helpers: lifecycle · Runtime relies on finalizers and Kubernetes helpers for cleanup and status work.
- Gateway ctrl → Model builders: build · Gateway objects are translated into internal desired state.
- Route ctrl → Model builders: build · Routes are converted into model resources and rules.
- Policy ctrls → Model builders: build · Policies influence access, networking, and target-group decisions.
- Model builders → Core model: emit · Builders create generic stacks, routes, and policies.
- Core model → Resource graph: order · The stack is organized as a dependency graph.
- Core model → Lattice model: specialize · Core abstractions are specialized into VPC Lattice resources.
- Resource graph → Stack deployer: plan · Graph traversal determines deployment order.
- Lattice model → Stack deployer: apply · Desired lattice resources are handed to the stack apply engine.
- Stack deployer → AWS cloud: invoke · Deployment issues cloud operations through the AWS abstraction.
- AWS cloud → AWS APIs: backed by · Cloud operations are implemented by service wrappers and SDK-backed clients.
- Stack deployer → Lattice managers: manage · Resource-specific managers synthesize and reconcile AWS objects.
- Lattice managers → AWS APIs: sdk calls · Managers talk to VPC Lattice, ACM, and tagging APIs.
- Stack deployer → ExternalDNS: optional · Deployment can emit DNS endpoints for ExternalDNS.
- Mutating webhook → Service/Pod: mutate · Admission injects pod readiness gates before normal reconciliation.
- Mutating webhook → K8s helpers: uses · Webhook shares common Kubernetes utilities and conditions.
