How aws/aws-application-networking-k8s works
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: stack_deployer.go Stack deployer · eventhandlers Event fanout · runtime Reconcile runtime · gateway_controller.go Gateway ctrl
Components 21
Kubernetes inputs
API objects watched by the controller.
- Gateway API · GatewayClass, Gateway, HTTPRoute, GRPCRoute, and TLSRoute resources.
- App CRDs · ServiceExport, ServiceImport, AccessLogPolicy, IAMAuthPolicy, TargetGroupPolicy, and VPCAssociationPolicy.
pkg/apis/applicationnetworking/v1alpha1 - Service/Pod · Standard Kubernetes Service and Pod objects participating in reconciliation.
Controller plane
Event handling, reconciliation, and lifecycle orchestration.
- Gateway ctrl · Primary Gateway and GatewayClass reconciliation entry points.
pkg/controllers/gateway_controller.go - Route ctrl · Reconciles HTTPRoute, GRPCRoute, and TLSRoute state into the model.
pkg/controllers/route_controller.go - Service ctrl · Handles service-facing reconciliation and ownership relationships.
pkg/controllers/service_controller.go - Policy ctrls · Reconcilers for access log, IAM auth, target group, and VPC association policies.
pkg/controllers - Event fanout · Maps secondary object events back to the owning Gateway, route, service, or policy.
pkg/controllers/eventhandlers - Predicates · Event filters that reduce unnecessary reconciles and guard controller triggers.
pkg/controllers/predicates - Reconcile runtime · Shared reconcile wrapper, error handling, and lifecycle behavior.
pkg/runtime - K8s helpers · Finalizers, event helpers, and policy utilities that support object lifecycle management.
pkg/k8s - Model builders · 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 · Generic stacks, routes, policies, and resource graph abstractions.
pkg/model/core - Resource graph · Orders and traverses resources by dependency before deployment.
pkg/model/core/graph - Lattice 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 · Serializes a computed stack and reconciles it against AWS.
pkg/deploy/stack_deployer.go - Lattice managers · Resource-specific managers and synthesizers for VPC Lattice objects.
pkg/deploy/lattice - ExternalDNS · Optional DNSEndpoint emission path for ExternalDNS.
pkg/deploy/externaldns
External systems
AWS services and auxiliary integrations outside the cluster.
Admission path
Mutating webhook flow that changes objects before reconciliation.
- Mutating webhook · Pod admission path that injects readiness gates before reconciliation.
pkg/webhook
Connections 29
- 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.