Chapter 7: Platform control plane foundations

Introduction

Introduces self-healing as a foundation for Epetech’s engineering platform and explains why Kubernetes serves as its control plane.

• Self-healing platform resilience: Explain why Epetech wants its platform services and customer applications to be self-healing, rather than relying only on redundancy.
  Why it matters: Self-healing supports the goal of letting developers build, release, and operate software with less friction.
• Kubernetes control plane role: Explain why the section calls Kubernetes the control plane, using its orchestration behavior and extensible API.
  Why it matters: Kubernetes offers both familiar service recovery and orchestration the platform can extend.

Key terms: resilient, self-healing, actual state, desired state, Kubernetes, Kubernetes API, orchestration logic, control plane

7.1 Cloud account baseline

Defines the cloud account baseline as a domain for account-wide configuration and distinguishes it from administrative identity.

• Account baseline scope: Explain what the book means by an account and which requirements belong in its baseline configuration.
  Why it matters: This scope helps separate common account setup from configuration specific to a workload or environment.
• Baseline and identity domains: Distinguish the cloud account baseline domain from administrative identity and give examples of resources included in the baseline.
  Why it matters: The distinction clarifies why not all once-per-account configuration belongs to the same platform domain.

Key terms: accounts, account baseline configuration, administrative identity, cloud account baseline domain, account-level resources

7.1.1 Account baseline security scanning

This section explains who can own account-level security baselines, what those baselines can include, and how recurring scans and configuration jobs keep accounts compliant.

• Account baseline ownership: Explain when a separate security team can manage account-level baseline security and when platform engineers must implement it instead.
  Why it matters: Clear ownership ensures that platform accounts receive the required security configuration even when the security team cannot implement it.
• Enterprise account baseline controls: Describe the enterprise-wide basis for the security baseline and give examples of account-level controls or log collection it may include.
  Why it matters: The baseline applies enterprise security expectations to platform accounts rather than inventing separate rules for them.
• Recurring scans and correction: Explain the recommended pairing of recurring scans with an idempotent baseline-configuration job.
  Why it matters: The scan makes changes visible before the automated job restores the required baseline.

Key terms: account-level baseline security configuration, infrastructure-provider accounts, cloud account baseline domain, baseline security configuration, permission boundaries, account-level logs, centralized log aggregator, recurring, idempotent job, recurring scan, automatically corrected

7.1.2 Account baseline observability

This section explains where account-level observability begins in the platform build and why customer identity matters when choosing observability tools.

• Account-level observability baseline: Describe why cloud account-level components are needed early in the Epetech platform build and how observability fits into ongoing deployment.
  Why it matters: It places observability in the account baseline without treating the exercises as a complete observability implementation.
• Observability tool identity fit: Explain why customer identity and self-service access matter when comparing cloud-vendor observability services with other tools.
  Why it matters: A tool’s identity integration affects whether developers can use observability features securely and without platform-team intervention.

Key terms: Platform and Cloud Cost axes, cloud account-level components, AWS account-level services, customer identity, cloud provider infrastructure IAM, self-serve, identity integration point

7.1.3 Hosted zones and delegated domains

This section connects service naming and traffic conventions to a self-serve DNS strategy, then shows how Epetech delegates hosted zones across accounts and releases the configuration.

• Service naming as product design: Explain why domain, subdomain, and URL-path conventions should reflect a product’s structure rather than emerge independently from each team.
  Why it matters: A predictable URL structure makes services easier for internal and external developers to find and use.
• Platform-managed domain boundaries: Describe Epetech’s initial self-serve domain pattern and the traffic conventions it establishes for production and preproduction services.
  Why it matters: Clear platform-owned boundaries give teams self-service without letting DNS naming become inconsistent.
• External API gateway tradeoff: Explain when an API gateway adds value to Epetech’s external traffic and why the example platform leaves it out.
  Why it matters: The gateway decision changes both the value provided to external developers and where API DNS traffic would be directed.
• Cross-account hosted zone delegation: Trace where the primary domain and a delegated subdomain are configured when they are managed in different AWS accounts.
  Why it matters: Delegation lets a subdomain be managed in the appropriate account without moving the primary domain.
• DNS release pipeline checks: Describe the proposed pipeline stages for releasing the hosted-zone and delegation configuration, including the limit on testing it beforehand.
  Why it matters: The staged checks and cross-account identity provide a repeatable way to release DNS changes despite the testing limitation.

Key terms: left-of-domain strategy, right-of-domain strategy, subdomain, resource, platform-managed domains, epetech.io, api.epetech.io, Dev, QA, Prod

7.2 Transit network layer

The section explains how a dedicated transit network domain supports expanding platform connectivity, why EKS still needs VPCs, and which VPC tradeoffs Epetech makes for its example platform.

• Dedicated networking domain: Explain why platform networking belongs in a dedicated domain rather than being handled separately by each service.
  Why it matters: A shared networking strategy helps platform services connect without competing network designs.
• Expandable transit connections: Describe how the proposed transit network lets newly provisioned accounts connect with low friction, and how an approval step could be automated.
  Why it matters: New accounts can gain connectivity without making every connection a manual platform-team task.
• CloudWAN and VPC roles: Distinguish what CloudWAN can simplify from what VPCs must still provide for EKS clusters and services.
  Why it matters: Automating connections between networks does not remove the need for a network that hosts the cluster.
• Epetech VPC simplifications: Explain how Epetech pares down the general VPC design and the cost-versus-resilience tradeoff of its NAT gateway choice.
  Why it matters: The example's simpler, cheaper network is a deliberate choice rather than a general recommendation for resilient deployments.

Key terms: dedicated domain, communication modes, transit network, transit gateways, TGW, lambda function, CloudWAN, VPCs, Elastic Kubernetes Service (EKS), private ingress subnet

7.2.1 Role-based network structure

This section explains how to structure and provision VPCs for platform clusters while keeping the platform’s infrastructure code independent of unrelated enterprise use cases.

• Role-based VPC structure: Explain how dedicated VPCs relate to clusters and why a role such as Prod may eventually span multiple clusters and networks.
  Why it matters: Planning for a role rather than just its first cluster leaves room for regional growth.
• Cluster-aligned VPC naming: Describe why VPC names should follow cluster names and what the example naming convention identifies.
  Why it matters: Consistent names make the right cluster network easier to identify as instances multiply.
• Platform environment roles: Distinguish the purposes of the development and QA, preview, and product management environments in the fuller account structure.
  Why it matters: Separate environments let platform changes be tested and exposed progressively without placing platform product services in customer environments.
• Example VPC pipeline: Describe the requested exercise pipeline and the network-address consideration given for AWS CNI.
  Why it matters: The exercise turns the network structure into a releasable infrastructure change and calls out an address-capacity risk.
• Independent platform infrastructure code: Justify keeping the platform VPC pipeline dedicated to platform use rather than making it a shared enterprise VPC implementation.
  Why it matters: Independent code lets the team change the platform to meet its own product needs without waiting on unrelated use cases.

Key terms: role-based network structure, VPC, Prod, IP space, cluster naming convention, Terraform data resource, role, region, development and quality assurance, preview environment

7.3 Customer identity

This section explains why engineering-platform customers need an identity separate from cloud administrative identity, while retaining organizational sign-on and team-based access.

• Separate platform customer identity: Explain why platform customers have an identity separate from the underlying cloud provider’s IAM and the platform’s administrative identity. Use the Netflix example to describe how a service can act on a customer’s behalf without assigning that customer an infrastructure identity.
  Why it matters: Customers can use the platform without their identities being tied directly to its infrastructure provider.
• Organizational sign-on and team permissions: Distinguish the proposed authentication step from the authorization step: authentication remains tied to the organization’s authoritative source for single sign-on, while access permissions depend on a developer’s team membership.
  Why it matters: It clarifies how developers can sign in consistently while receiving access appropriate to their teams.

Key terms: platform customer identity, administrative identity, cloud vendor IAM, authentication, authorization, authoritative source, single sign-on (SSO), team membership

7.3.1 Authentication and authorization

This section explains how team membership can drive a self-service access experience across platform tools and infrastructure.

• Team-oriented platform access: Explain why the platform onboards teams rather than managing each user's access separately, and what access a user should gain when added to a team.
  Why it matters: Team-based access makes joining and managing a platform team a coherent self-service experience.
• GitHub membership for tool access: Distinguish corporate SSO authentication from GitHub's role in maintaining teams, and describe how other platform tools can use that membership information.
  Why it matters: A tool needs a way to use team membership before self-managed teams can govern access to it.
• Team authorization beyond tools: Explain why tool access alone is insufficient and how the proposed identity approach would use GitHub team information to govern platform infrastructure access.
  Why it matters: Team membership must govern infrastructure and API access as well as access to the tools surrounding them.

Key terms: team-oriented user experience, self-manage members, team resources, corporate identity, SSO, GitHub, RBAC, passthrough authentication, context permissions, OAuth2

7.3.2 OpenID Connect device-auth-flow and team membership claims

This section explains why a platform CLI uses an OAuth device flow, how GitHub team membership becomes a JWT claim, and how to configure Auth0 for that use case.

• Device authorization for CLI access: Explain why the platform CLI uses the OAuth 2.0 device-authorization grant rather than relying on a browser-only interaction.
  Why it matters: It connects the authentication choice to how developers actually use the platform.
• GitHub team claims in JWTs: Trace how successful GitHub authentication leads to a verifiable JWT containing the user's team memberships, and distinguish the access token's role from the ID token's role.
  Why it matters: Team claims let the platform connect an authenticated user to their team's resources.
• Auth0 device flow configuration: Describe the main Auth0 and GitHub configuration needed for the future CLI, including the application, connection, and post-authentication Action.
  Why it matters: These configuration pieces make the proposed CLI authentication and team claims possible.

Key terms: CLI, OAuth 2.0 device-authorization-grant, terminal, GitHub, IDP, access token, ID token, JWT, team claim, Auth0

7.4 Cloud service control plane base

This section defines a narrowly scoped, vendor-managed cloud control plane base and explains why its provisioning and health checks are kept distinct from other platform services.

• Vendor-managed control plane boundary: Explain why the cloud service control plane base includes only operationally vendor-managed elements and why they are provisioned together.
  Why it matters: This boundary keeps the foundational pipeline focused on components the cloud vendor operates.
• Control plane implementation choices: Distinguish Kubernetes as an effective control plane for distributed-service platforms from the non-Kubernetes alternatives described here.
  Why it matters: The control plane’s role matters more than a requirement to use Kubernetes.
• Base provisioning dependencies and modules: Describe the inputs and reusable modules identified for provisioning the EKS base, including the caution about module sources.
  Why it matters: Provisioning depends on existing network and identity foundations, while reusable modules still need scrutiny.
• Managed service health checks: Distinguish checks that AWS resources exist and managed services report ready from tests of whether those services perform their expected functions.
  Why it matters: A ready status is useful evidence, but it does not prove that an add-on works as intended.

Key terms: Cloud service control plane base, vendor-managed, aws-control-plane-base pipeline, Kubernetes, cloud vendors’ API, built-in extensibility, service interface, VPCs, OpenID Connect (OIDC) provider, Terraform modules

7.4.1 AWS managed node groups

This section identifies an AWS-managed node group as a way to provide nodes for EKS-managed cluster services.

• Nodes for cluster services: Explain why the cluster needs nodes before EKS-managed services can run, and describe where the AWS-managed node group definition can be added.
  Why it matters: The node group supplies a place for the cluster services to run.

Key terms: EKS-managed services, AWS-managed node group, EKS module

7.4.2 Dependencies for AWS-managed EKS services

Identifies the AWS dependencies needed for an EFS storage class and Karpenter services in the EKS control plane.

• EFS storage class target: Explain why the EFS storage class needs an EFS target and describe the single-target arrangement presented for most situations.
  Why it matters: Without the target, the storage class cannot create persistent volumes.
• Karpenter AWS service dependencies: Describe Karpenter's use of event information for Spot instances and what its EKS module submodule provisions.
  Why it matters: Karpenter depends on supporting AWS services and node role configuration, not just its installation in EKS.

Key terms: EFS target, storage class, volume claims, namespace permissions, Karpenter, Spot instance, Karpenter submodule, EKS node role configurations

7.4.3 AWS managed EKS add-ons

This section explains which EKS services belong in the control plane base pipeline, when to take newer managed add-on versions, and how testing and architecture choices affect that approach.

• Control plane add-on selection: Explain why AWS-managed EKS add-ons fit in the control plane base pipeline and why a service such as Karpenter can also fit despite not yet being fully managed. Describe the limited use of AWS Blueprints for these add-ons.
  Why it matters: The base pipeline’s scope affects how much work the team must take on to maintain it.
• Latest add-on version practice: Explain what most_recent=true selects and why the authors use it in this routinely run, vendor-managed pipeline rather than treating infrequent releases as the safer default.
  Why it matters: The version setting makes sense only together with the team’s release and testing practices.
• Staged upgrade safeguards: Describe how change-plan review and early testing environments support add-on upgrades, and why production promotion must use explicit versions.
  Why it matters: Early testing does not establish that production has the same add-on version available.
• Limits of automatic upgrades: Explain why the latest-version practice may require pinning when releases are infrequent or the EKS architecture departs from supported defaults, using the self-managed CNI example.
  Why it matters: Pinning may be necessary, but it can also reveal a gap in release practices or a cost introduced by customization.
• Karpenter Helm deployment exception: Explain why the authors generally avoid wrapping Helm in Terraform for application deployments, yet use a Helm resource for Karpenter in this vendor-managed pipeline.
  Why it matters: The Karpenter choice is a narrow maintenance trade-off, not a general recommendation to deploy applications through Terraform.

Key terms: AWS-managed EKS add-ons, Karpenter, Blueprints, base pipeline, most_recent=true, AWS-managed add-ons, Kubernetes version, vendor-managed pipeline, change plan, nondeveloper-facing testing environments

7.4.4 Integrating an OIDC provider with the control plane base

The section explains how OIDC integration enables cluster access controls and shows how the two cluster environments are configured.

• OIDC integration and access: Explain how integrating the previously configured OIDC provider with the control plane enables developer access controls and single sign-on across clusters.
  Why it matters: This connection makes the identity provider’s team-based access usable at the clusters.
• Separate cluster environment values: Describe why the two Epetech clusters have separate environment value files and identify the production cluster values stated here.
  Why it matters: Separate value files let the same cluster definition be provisioned for distinct environments.
• Exercise management node choices: Distinguish the exercise’s low-cost management node settings from the suggested real-world starting scale, and describe when AMD may be preferable.
  Why it matters: The inexpensive exercise settings should not be mistaken for the recommended starting point in a real deployment.

Key terms: OIDC provider, IDP, GitHub team memberships, SSO, Kubernetes API, environment value files, tfvars, prod-i01-aws-us-east-2, aws-account-1, us-east-2

7.4.5 Post-Terraform configuration

This section configures cluster access and initial Kubernetes resources after Terraform creates the cluster, including storage defaults and Karpenter compute pools.

• Post-apply cluster configuration: Describe why the pipeline needs a post-Terraform configuration step and how it preserves the kubeconfig and cluster-specific values for subsequent configuration.
  Why it matters: These saved values connect the newly provisioned cluster to the resources configured after provisioning.
• Team administrator binding: Explain how the post-apply configuration grants the platform engineering team administrator access through the previously configured identity provider.
  Why it matters: The binding turns the team's existing identity into usable administrator access to the cluster.
• Initial namespaces and storage defaults: Describe the system namespaces and storage classes added during base configuration, and explain why the storage classes are defined directly in the script.
  Why it matters: Simple defaults make common storage available without adding unnecessary configuration machinery at this stage.
• Default Karpenter compute pools: Explain the purpose of the initial Karpenter node classes and pools and the choice to offer both ARM and Intel architectures.
  Why it matters: The initial pools give developers practical compute choices without requiring a customized pool for every workload.
• Pool capacity and instance choices: Describe how the section approaches Spot versus on-demand capacity, initial instance-type selection, and pool-limit alerts.
  Why it matters: These choices keep the initial pool economical and flexible while giving operators time to respond to unexpected demand.
• Automatic node replacement benefits: Explain why the section uses Karpenter's regular node replacement as part of its security and maintenance approach.
  Why it matters: Automated replacement helps keep nodes patched without making routine node upkeep a manual task.

Key terms: terraform apply, kubeconfig, Terraform outputs, base_configuration.sh, secrets store, base64 encoding, IDP, GitHub team, administrative cluster role binding, kubectl

7.4.6 Strategy for testing EKS base

This section shows how to test EKS base services through workloads, maintain the cluster and its dependencies through upgrades, and build a CLI for customer access.

• EBS storage health test: Describe how a workload tests the EBS storage class by claiming storage, writing to it, and increasing the claim size.
  Why it matters: The test checks that storage works for an application, not just that its supporting service appears to be running.
• EFS shared storage test: Explain why the EFS test uses two pods with one claim and how it differs from the EBS test.
  Why it matters: A shared-claim test exercises the particular EFS capability the platform expects to provide.
• Karpenter provisioning test limits: Describe how workloads test the default Karpenter node pools and explain why a workload that runs may not prove new-node provisioning.
  Why it matters: A passing workload test can give false confidence if it never requires Karpenter to provision a node.
• Cluster and add-on upgrades: Explain how the section updates Kubernetes, EKS add-ons, Karpenter, and customer-node images, distinguishing what AWS handles automatically from what the pipeline must trigger.
  Why it matters: The upgrade path differs across the control plane, official add-ons, Karpenter, and customer nodes.
• Management node refresh: Describe how to refresh the AWS-managed management node group through Terraform and what protects workloads during replacement.
  Why it matters: Management nodes need their own refresh path even though Karpenter manages customer node pools.
• Customer access CLI exercise: Describe the CLI experience proposed for obtaining a customer identity token and kubeconfig, and the cluster information it needs.
  Why it matters: The CLI makes the previously tested identity flow usable for developers who need kubectl access.

Key terms: EBS storage class, persistent volume claim, PVC, EFS storage class, write-many, volume claim, Karpenter, default node pool, ARM node pool, tfvars

7.5 Summary