feat: add EC2NodeClass placement group support

Author: rocketbitz

charts/karpenter-crd/templates/karpenter.k8s.aws_ec2nodeclasses.yaml

@@ -76,6 +76,7 @@ func main() {
 			cloudProvider,
 			op.SubnetProvider,
 			op.SecurityGroupProvider,
+			op.PlacementGroupProvider,
 			op.InstanceProfileProvider,
 			op.InstanceProvider,
 			op.PricingProvider,

cmd/controller/main.go

@@ -0,0 +1,84 @@
+# Placement Group Support
+
+## Context
+
+Amazon EC2 placement groups let operators influence instance placement for low-latency (`cluster`), failure-domain isolation (`partition`), and small critical workloads (`spread`). The long-standing request in https://github.com/aws/karpenter-provider-aws/issues/3324 is to make these groups usable from `EC2NodeClass`.
+
+Karpenter already treats `EC2NodeClass` as launch configuration for existing AWS resources such as subnets, security groups, AMIs, and instance profiles. Placement groups fit best when modeled the same way.
+
+## Problem
+
+Users can launch Karpenter-managed nodes into subnets, security groups, and capacity reservations, but cannot direct those nodes into an existing placement group. This blocks workloads that already rely on EC2 placement-group semantics, for example:
+
+- tightly-coupled clusters that need cluster placement-group networking
+- replicated systems that want partition placement-group isolation
+- small critical workloads that want spread placement-group separation
+
+The previously proposed design in #5389 focused on Karpenter creating placement groups. That adds a new EC2 resource lifecycle to reconcile and exposes strategy-specific creation APIs that users may rely on long term.
+
+## Options
+
+### Option 1: Karpenter creates and owns placement groups
+
+Pros:
+
+- users can describe strategy directly in `EC2NodeClass`
+- Karpenter could validate strategy-specific configuration at reconciliation time
+
+Cons:
+
+- introduces new lifecycle ownership for EC2 resources outside the current launch path
+- expands the stable API surface with strategy creation details such as `cluster`, `spread`, `partition`, partition count, and spread level
+- complicates shared placement groups and future AWS-specific variants
+- makes rollback and drift semantics harder because the placement group becomes a controller-managed dependency
+
+### Option 2: Karpenter references an existing placement group
+
+Pros:
+
+- matches how `EC2NodeClass` already models other AWS launch dependencies
+- keeps the API small: identify the group and optionally pin a partition
+- works for user-managed, shared, and externally tagged placement groups
+- avoids inventing a placement-group controller lifecycle before demand is proven
+
+Cons:
+
+- users must provision the placement group out of band
+- Karpenter cannot configure placement-group strategy on behalf of the user
+
+## Recommendation
+
+Add an optional `spec.placementGroup` field on `EC2NodeClass`:
+
+```yaml
+spec:
+  placementGroup:
+    name: analytics-partition
+    partition: 2
+```
+
+Behavior:
+
+- `name` or `id` identifies the existing placement group; the fields are mutually exclusive
+- `id` supports shared placement groups, which require `GroupId` during launch
+- `partition` is optional and only meaningful for partition placement groups
+- Karpenter resolves the configured group into `status.placementGroup`
+- launch templates include the placement-group reference so both `CreateFleet` and `RunInstances` honor it
+
+## Key Decisions
+
+- Karpenter does not create, tag, delete, or mutate placement groups in this design
+- placement-group strategy remains an operator concern because it belongs to the EC2 placement-group resource, not the instance launch request
+- partition selection is the only launch-time knob worth exposing initially because AWS applies it at instance launch and it is useful even when the placement group is created elsewhere
+
+## User Guidance
+
+- Use `name` for placement groups in the same account and `id` for shared placement groups
+- Pair cluster placement groups with subnet or topology constraints that keep launches in a single Availability Zone
+- Omit `partition` to let EC2 distribute instances across partitions, or set it when the workload needs explicit partition affinity
+
+## Future Work
+
+- richer status surfacing for placement-group strategy and readiness
+- strategy-aware validation and scheduling hints
+- a separate proposal for Karpenter-managed placement-group lifecycle if real demand justifies the larger API

designs/placement-groups.md

@@ -0,0 +1,38 @@
+apiVersion: karpenter.sh/v1
+kind: NodePool
+metadata:
+  name: placement-group
+spec:
+  template:
+    spec:
+      requirements:
+        - key: topology.kubernetes.io/zone
+          operator: In
+          values:
+            - us-west-2a
+      nodeClassRef:
+        group: karpenter.k8s.aws
+        kind: EC2NodeClass
+        name: placement-group
+---
+apiVersion: karpenter.k8s.aws/v1
+kind: EC2NodeClass
+metadata:
+  name: placement-group
+spec:
+  amiFamily: AL2023
+  role: "KarpenterNodeRole-${CLUSTER_NAME}"
+  subnetSelectorTerms:
+    - tags:
+        karpenter.sh/discovery: "${CLUSTER_NAME}"
+  securityGroupSelectorTerms:
+    - tags:
+        karpenter.sh/discovery: "${CLUSTER_NAME}"
+  amiSelectorTerms:
+    - alias: al2023@latest
+  placementGroup:
+    # Use `name` for placement groups in the same account.
+    # Use `id` instead when launching into a shared placement group.
+    name: analytics-partition
+    # Optional, only valid for partition placement groups.
+    partition: 2

examples/v1/placement-group.yaml

@@ -91,6 +91,7 @@ func main() {
 			cloudProvider,
 			op.SubnetProvider,
 			op.SecurityGroupProvider,
+			op.PlacementGroupProvider,
 			op.InstanceProfileProvider,
 			op.InstanceProvider,
 			op.PricingProvider,

kwok/main.go

@@ -61,6 +61,7 @@ import (
 	"github.com/aws/karpenter-provider-aws/pkg/providers/instanceprofile"
 	"github.com/aws/karpenter-provider-aws/pkg/providers/instancetype"
 	"github.com/aws/karpenter-provider-aws/pkg/providers/launchtemplate"
+	"github.com/aws/karpenter-provider-aws/pkg/providers/placementgroup"
 	"github.com/aws/karpenter-provider-aws/pkg/providers/pricing"
 	"github.com/aws/karpenter-provider-aws/pkg/providers/securitygroup"
 	ssmp "github.com/aws/karpenter-provider-aws/pkg/providers/ssm"
@@ -83,6 +84,7 @@ type Operator struct {
 	RecreationCache             *cache.Cache
 	SubnetProvider              subnet.Provider
 	SecurityGroupProvider       securitygroup.Provider
+	PlacementGroupProvider      placementgroup.Provider
 	InstanceProfileProvider     instanceprofile.Provider
 	AMIProvider                 amifamily.Provider
 	AMIResolver                 amifamily.Resolver
@@ -138,6 +140,7 @@ func NewOperator(ctx context.Context, operator *operator.Operator) (context.Cont
 		cfg.Region,
 		false,
 	)
+	placementGroupProvider := placementgroup.NewDefaultProvider(ec2api, cache.New(awscache.DefaultTTL, awscache.DefaultCleanupInterval))
 	versionProvider := version.NewDefaultProvider(operator.KubernetesInterface, eksapi)
 	// Ensure we're able to hydrate the version before starting any reliant controllers.
 	// Version updates are hydrated asynchronously after this, in the event of a failure
@@ -205,6 +208,7 @@ func NewOperator(ctx context.Context, operator *operator.Operator) (context.Cont
 		RecreationCache:             recreationCache,
 		SubnetProvider:              subnetProvider,
 		SecurityGroupProvider:       securityGroupProvider,
+		PlacementGroupProvider:      placementGroupProvider,
 		InstanceProfileProvider:     instanceProfileProvider,
 		AMIProvider:                 amiProvider,
 		AMIResolver:                 amiResolver,