AWS eks: Document ACK capability cross-namespace and disabled services options
Summary
Adds a section describing optional ACK capability configuration fields, including enableCrossNamespace (default false) and disabledServices, with notes on behavior, CRDs, finalizers, and drift.
Security assessment
The new option documents that cross-namespace resource references are disabled by default, which limits ACK controllers from resolving references outside their namespace and reduces unintended cross-namespace access. It also documents disabledServices behavior, but the security-relevant part is the namespace isolation default.
Evidence
`enableCrossNamespace` | Boolean | Controls whether ACK controllers resolve resource references to resources in a different Kubernetes namespace. Cross-namespace references are disabled by default. Set this field to `true` if you want references to resolve across namespaces. When the field is `false`, references must stay in the same namespace, and ACK reports out-of-namespace references as unresolved. When you create a capability without this field, the capability is created with the field set to `false`, and `describe-capability` returns `false`. For more information, see [Cross-namespace resource references](./ack-concepts.html#ack-cross-namespace-references).
Diff
diff --git a/eks/latest/userguide/create-ack-capability.md b/eks/latest/userguide/create-ack-capability.md index 57706ed..00845b9 100644 --- a//eks/latest/userguide/create-ack-capability.md +++ b//eks/latest/userguide/create-ack-capability.md @@ -7 +7 @@ -PrerequisitesChoose your toolWhat happens when you create an ACK capabilityNext steps +PrerequisitesChoose your toolWhat happens when you create an ACK capabilityACK capability configuration optionsNext steps @@ -75,0 +76,66 @@ The automatically created access entry includes the `AmazonEKSACKPolicy` which g +## ACK capability configuration options + +ACK capabilities accept optional type-specific settings in the `ack` object of the capability `configuration`. These settings are optional. If you omit the `configuration` when you create a capability, cross-namespace references are disabled and all supported ACK service controllers run. You can set these options when you create a capability with the AWS Management Console, the AWS CLI, the AWS API, or AWS CloudFormation, and you can change them later with the `update-capability` command. For the steps to set these options at creation, see [Create an ACK capability using the AWS CLI](./ack-create-cli.html) or [Create an ACK capability using the Console](./ack-create-console.html). To change them on an existing capability, see [Update ACK capability configuration](./working-with-capabilities.html#ack-update-configuration). + +The `ack` configuration object supports the following fields. + +Field | Type | Description +---|---|--- +`enableCrossNamespace` | Boolean | Controls whether ACK controllers resolve resource references to resources in a different Kubernetes namespace. Cross-namespace references are disabled by default. Set this field to `true` if you want references to resolve across namespaces. When the field is `false`, references must stay in the same namespace, and ACK reports out-of-namespace references as unresolved. When you create a capability without this field, the capability is created with the field set to `false`, and `describe-capability` returns `false`. For more information, see [Cross-namespace resource references](./ack-concepts.html#ack-cross-namespace-references). +`disabledServices` | Array of strings | A list of ACK service names whose controllers are turned off for this capability, for example `s3`, `ec2`, or `iam`. The controller for a disabled service does not run, and resources of that service are not reconciled until you re-enable the service by removing it from the list. Each service name is lowercase alphanumeric and is 1–63 characters long. The list can contain up to 200 service names. When you create a capability without this field or with an empty list, all supported ACK service controllers run. + +###### Note + +Capabilities that were resolving cross-namespace references before `enableCrossNamespace` became available have the field set to `true`, so their behavior doesn’t change. Capabilities that you create now have cross-namespace references disabled unless you set the field to `true`. + +Whether the capability installs a disabled service’s custom resource definitions (CRDs) depends on when you turn the service off: + + * If you turn a service off **when you create the capability** , the capability doesn’t install that service’s CRDs at all. + + * If you turn a service off **after creation** , the CRDs that the capability already installed remain in your cluster. + + + + +Shared CRDs in the `services.k8s.aws` group are always installed and can’t be turned off. + +Turning services off is how you run the capability alongside ACK controllers that you manage yourself, either while you migrate to the capability one service at a time, or to keep a particular service self-managed for the long term. For the recommended procedure, see [Coexist with self-managed controllers (recommended)](./ack-comparison.html#ack-migration-coexist). + +###### Note + +On `update-capability`, `disabledServices` replaces the previous list instead of merging with it: + + * Omit the field to leave the previous list unchanged. + + * Specify a list to replace the previous list entirely, so include every service that you want turned off. + + * To turn all services back on, specify an empty list. + + + + +To turn a single service back on, specify the list of services that you want to remain turned off, without that service. + +###### Note + +A service name that doesn’t correspond to a supported ACK service is ignored rather than rejected. The request succeeds and the name is stored, but no service is turned off for it. As a result, a misspelled name silently leaves that service running. Check your spelling carefully, because `describe-capability` returns the list exactly as you supplied it and doesn’t identify unrecognized names. + +To confirm that a service is actually turned off, verify that its resources are no longer reconciled. A resource that you create for a turned-off service gets no status conditions at all, and no AWS resource is created for it. + +###### Important + +Turning off a service doesn’t delete anything, and AWS doesn’t check whether the capability is currently managing resources of that service before turning it off. The Kubernetes custom resources and the AWS resources that they represent both remain, but nothing reconciles them, so the AWS resources can drift from the state that’s declared in your cluster. + +Neither retention setting applies while a service is turned off: + + * `deletePropagationPolicy` is set on the capability and takes effect only when you delete the **capability**. + + * The `services.k8s.aws/deletion-policy` annotation is set on an individual resource and takes effect only when a running controller processes the deletion of that **Kubernetes resource**. For more information, see [ACK considerations for EKS](./ack-considerations.html). + + + + +If you delete a Kubernetes resource while its service is turned off, no controller is running to process the resource’s finalizer. The resource stays in the `Terminating` state indefinitely and its AWS resource is never deleted, even if you set `services.k8s.aws/deletion-policy` to `delete`. Re-enable the service before you delete its resources, or delete the resources before you turn the service off. To recover a resource that is already stuck, see [Troubleshoot issues with ACK capabilities](./ack-troubleshooting.html). + +Creating a resource while its service is turned off also has no effect, because no controller processes it. No AWS resource is created, and the Kubernetes resource stays unreconciled until you re-enable the service. +