karpenter: clarify createServiceAccount semantics in docs, schema, and runtime log (#8720)

The karpenter.createServiceAccount flag controls which component
creates the 'karpenter' service account (eksctl vs the Karpenter
Helm chart), not whether a service account is created. A SA always
ends up on the cluster either way. The previous docs ("create a
service account or not") and silent log output for the true case
made this confusing.

This change:
- Rewrites the CreateServiceAccount struct-field comment in
  pkg/apis/eksctl.io/v1alpha5/types.go to describe the actual
  behavior, and regenerates schema.json.
- Adds a dedicated 'createServiceAccount' subsection to
  userdocs/src/usage/eksctl-karpenter.md explaining both modes.
- Adds Info-level log output at runtime so eksctl reports which
  component will create the SA.

No behavior changes.

Author: cheeseandcereal

pkg/actions/karpenter/create.go

@@ -60,7 +60,13 @@ func (i *Installer) Create(ctx context.Context) error {
 	}
 	if api.IsEnabled(i.Config.Karpenter.CreateServiceAccount) {
 		// Create the service account role only.
+		// The Karpenter Helm chart will create the Kubernetes service
+		// account (serviceAccount.create=true is passed to the chart in
+		// pkg/karpenter/karpenter.go).
 		iamServiceAccount.RoleOnly = api.Enabled()
+		logger.Info("karpenter.createServiceAccount=true: eksctl will create only the IAM role; the Karpenter Helm chart will create the %q service account in namespace %q", karpenter.DefaultServiceAccountName, karpenter.DefaultNamespace)
+	} else {
+		logger.Info("karpenter.createServiceAccount=false: eksctl will create both the IAM role and the %q service account in namespace %q", karpenter.DefaultServiceAccountName, karpenter.DefaultNamespace)
 	}
 	karpenterServiceAccountTaskTree := i.StackManager.NewTasksToCreateIAMServiceAccounts([]*api.ClusterIAMServiceAccount{iamServiceAccount}, i.OIDC, clientSetGetter)
 	logger.Info(karpenterServiceAccountTaskTree.Describe())

pkg/apis/eksctl.io/v1alpha5/assets/schema.json

@@ -1549,8 +1549,8 @@
       "properties": {
         "createServiceAccount": {
           "type": "boolean",
-          "description": "create a service account or not.",
-          "x-intellij-html-description": "create a service account or not."
+          "description": "controls which component creates the \"karpenter\" service account in the \"karpenter\" namespace. When true, eksctl creates only the IAM role via an iamserviceaccount CloudFormation stack and delegates service account creation to the Karpenter Helm chart (which is installed with serviceAccount.create=true). When false (the default), eksctl creates both the IAM role and the Kubernetes service account, and the Helm chart is installed with serviceAccount.create=false. Either way a \"karpenter\" service account exists on the cluster after installation; this flag does not prevent the service account from being created.",
+          "x-intellij-html-description": "controls which component creates the "karpenter" service account in the "karpenter" namespace. When true, eksctl creates only the IAM role via an iamserviceaccount CloudFormation stack and delegates service account creation to the Karpenter Helm chart (which is installed with serviceAccount.create=true). When false (the default), eksctl creates both the IAM role and the Kubernetes service account, and the Helm chart is installed with serviceAccount.create=false. Either way a "karpenter" service account exists on the cluster after installation; this flag does not prevent the service account from being created."
         },
         "defaultInstanceProfile": {
           "type": "string",

pkg/apis/eksctl.io/v1alpha5/types.go

@@ -1136,7 +1136,16 @@ type Karpenter struct {
 	// Version defines the Karpenter version to install
 	// +required
 	Version string `json:"version"`
-	// CreateServiceAccount create a service account or not.
+	// CreateServiceAccount controls which component creates the "karpenter"
+	// service account in the "karpenter" namespace. When true, eksctl creates
+	// only the IAM role via an iamserviceaccount CloudFormation stack and
+	// delegates service account creation to the Karpenter Helm chart (which
+	// is installed with serviceAccount.create=true). When false (the default),
+	// eksctl creates both the IAM role and the Kubernetes service account,
+	// and the Helm chart is installed with serviceAccount.create=false.
+	// Either way a "karpenter" service account exists on the cluster after
+	// installation; this flag does not prevent the service account from being
+	// created.
 	// +optional
 	CreateServiceAccount *bool `json:"createServiceAccount,omitempty"`
 	// DefaultInstanceProfile override the default IAM instance profile

userdocs/src/usage/eksctl-karpenter.md

@@ -35,11 +35,30 @@ to be set:
 ```yaml
 karpenter:
   version: '1.2.1'
-  createServiceAccount: true # default is false
+  createServiceAccount: true # default is false; see note below on its meaning
   defaultInstanceProfile: 'KarpenterNodeInstanceProfile' # default is to use the IAM instance profile created by eksctl
   withSpotInterruptionQueue: true # adds all required policies and rules for supporting Spot Interruption Queue, default is false
 ```
 
+### `createServiceAccount`
+
+This flag controls *which component* creates the `karpenter` service account in
+the `karpenter` namespace. It does **not** prevent the service account from
+being created — a `karpenter` service account will always exist on the cluster
+after installation.
+
+* `createServiceAccount: false` (default) — eksctl creates both the IAM role
+  (via an `iamserviceaccount` CloudFormation stack) and the Kubernetes service
+  account, and installs the Karpenter Helm chart with
+  `serviceAccount.create=false` so the chart reuses the existing service
+  account.
+* `createServiceAccount: true` — eksctl creates only the IAM role and installs
+  the Helm chart with `serviceAccount.create=true`, letting the chart create
+  the service account (annotated with the IAM role ARN for IRSA).
+
+Either mode results in a working `karpenter` service account; the choice
+affects only which tool owns the Kubernetes object.
+
 OIDC must be defined in order to install Karpenter.
 
 Once Karpenter is successfully installed, add [NodePool(s)](https://karpenter.sh/docs/concepts/nodepools/) and [NodeClass(es)](https://karpenter.sh/docs/concepts/nodeclasses/) to allow Karpenter