From 4a3ec5a0c8228219222469156f8834ae727d8131 Mon Sep 17 00:00:00 2001 From: Rahul Raj Date: Thu, 21 May 2026 22:16:10 +0000 Subject: [PATCH 1/2] docs: add breaking changes page and contributor guideline for cross-namespace default change - Add Breaking Changes page at top-level sidebar (same level as Overview, Getting Started) - Add Documenting Breaking Changes guideline to Contributing section - Add New badge to Breaking Changes and Contributing - Remove New badge from EKS Capabilities, Granular IAM Roles, Using ACK with kro --- website/docs/breaking-changes.md | 48 ++++++++++++++++++++++++++++++ website/docs/contributing/index.md | 12 ++++++++ website/sidebars.ts | 10 +++++-- website/src/css/custom.css | 16 ++++++++++ 4 files changed, 83 insertions(+), 3 deletions(-) create mode 100644 website/docs/breaking-changes.md diff --git a/website/docs/breaking-changes.md b/website/docs/breaking-changes.md new file mode 100644 index 00000000..1f204f72 --- /dev/null +++ b/website/docs/breaking-changes.md @@ -0,0 +1,48 @@ +--- +title: "Breaking Changes" +sidebar_position: 99 +--- + +# Breaking Changes + +This page tracks upcoming breaking changes to ACK controller defaults and behavior. Review this page before upgrading your controllers. + +## Cross-Namespace References Default Change + +:::warning[Breaking Change Notice] +The default value of `--enable-cross-namespace` will change from `true` to `false` in a future release. The warning condition serves as a deprecation notice of existing default functionality. +::: + +### Summary + +Cross-namespace resource references (including `*Ref` fields, `SecretKeyReference`, and `FieldExport` targets across namespaces) will require explicit opt-in to improve namespace isolation. + +### Timeline + +| Phase | Description | +|:------|:------------| +| **Phase 1 (current)** | Flag added with default `true`. Warning condition set on resources using cross-namespace references | +| **Phase 2**
**(future release)** | Flag default changes to `false`. Cross-namespace references rejected unless opted in | + +### Who is affected + +You are affected if any of your ACK resources: +- Use `*Ref` fields pointing to resources in a **different namespace** +- Use `SecretKeyReference` with a `namespace` field different from the resource's namespace +- Use `FieldExport` CRs targeting ConfigMaps/Secrets in a different namespace than the source + +If all your references are within the same namespace, **no action is needed**. + +### Action required + +If you use cross-namespace references, explicitly opt in before upgrading to the Phase 2 release: + +```yaml +# values.yaml +enableCrossNamespace: true +``` + +Or via controller flag: +``` +--enable-cross-namespace=true +``` diff --git a/website/docs/contributing/index.md b/website/docs/contributing/index.md index 8a666107..11ab0c0f 100644 --- a/website/docs/contributing/index.md +++ b/website/docs/contributing/index.md @@ -40,6 +40,18 @@ The [ack-dev-skills](https://github.com/aws-controllers-k8s/ack-dev-skills) proj If you use AI coding tools (Claude Code, Kiro, Cursor, etc.), installing this skill will significantly improve the quality of AI-assisted ACK development work. See the [ack-dev-skills README](https://github.com/aws-controllers-k8s/ack-dev-skills) for installation instructions. +## Documenting Breaking Changes + +If your PR introduces a breaking change (e.g., changing a default value, removing a flag, altering reconciliation behavior), you must update the [Breaking Changes](/docs/breaking-changes) page. + +Add an entry with: +- A clear description of what is changing +- Timeline (if phased rollout) +- Who is affected +- Action required for users to migrate + +This ensures users are informed before upgrading their controllers. + ## Community - [GitHub Issues](https://github.com/aws-controllers-k8s/community/issues) — Bug reports and feature requests diff --git a/website/sidebars.ts b/website/sidebars.ts index 4fb6bc3e..079a454c 100644 --- a/website/sidebars.ts +++ b/website/sidebars.ts @@ -29,7 +29,6 @@ const sidebars: SidebarsConfig = { type: 'doc', id: 'getting-started-eks', label: 'Using EKS Capabilities', - className: 'sidebar-item-new', }, { type: 'doc', @@ -81,7 +80,6 @@ const sidebars: SidebarsConfig = { type: 'doc', id: 'guides/cross-account', label: 'Granular IAM Roles', - className: 'sidebar-item-new', }, { type: 'doc', @@ -97,7 +95,6 @@ const sidebars: SidebarsConfig = { type: 'doc', id: 'guides/kro', label: 'Using ACK with kro', - className: 'sidebar-item-new', }, ], }, @@ -114,6 +111,7 @@ const sidebars: SidebarsConfig = { { type: 'category', label: 'Contributing', + className: 'sidebar-category-new', collapsed: true, items: [ 'contributing/index', @@ -135,6 +133,12 @@ const sidebars: SidebarsConfig = { 'contributing/releasing', ], }, + { + type: 'doc', + id: 'breaking-changes', + label: 'Breaking Changes', + className: 'sidebar-item-new', + }, ], }; diff --git a/website/src/css/custom.css b/website/src/css/custom.css index 46d35a2a..536507d1 100644 --- a/website/src/css/custom.css +++ b/website/src/css/custom.css @@ -191,3 +191,19 @@ pre { overflow-x: auto; } + +/* New badge for category headers only (not children) */ +.sidebar-category-new > .menu__list-item-collapsible > .menu__link > span::after { + content: 'New'; + padding: 2px 6px; + margin-left: 8px; + font-size: 0.65rem; + font-weight: 600; + text-transform: uppercase; + background: linear-gradient(135deg, #ff9520 0%, #ff6b00 100%); + color: white; + border-radius: 4px; + white-space: nowrap; + position: absolute; + right: 30px; +} From 51238915d43068d42cabfe27b7378e4990cbed1c Mon Sep 17 00:00:00 2001 From: Hao Wang Date: Tue, 23 Jun 2026 16:40:08 -0700 Subject: [PATCH 2/2] docs: document enableCrossNamespace Helm value and cross-link references Add an enableCrossNamespace entry to the Helm chart values reference and cross-link it from the Field References concept and the Field Export guide, covering the resource reference, secret reference, and field export behaviors gated by the --enable-cross-namespace flag. --- website/docs/concepts.md | 4 ++++ website/docs/guides/field-export.md | 4 +++- website/docs/guides/helm-values.md | 11 +++++++++++ 3 files changed, 18 insertions(+), 1 deletion(-) diff --git a/website/docs/concepts.md b/website/docs/concepts.md index e0c05cfc..86395afe 100644 --- a/website/docs/concepts.md +++ b/website/docs/concepts.md @@ -363,6 +363,10 @@ spec: The controller resolves these references at reconciliation time. See the [API Reference](/services) for available reference fields on each CRD. +:::warning +Resource and Secret references can point to a different namespace by setting a `namespace` field on the reference. This cross-namespace behavior is gated by the `enableCrossNamespace` Helm value (`--enable-cross-namespace` flag), whose default will change from `true` to `false` in a future release. See [Breaking Changes](/breaking-changes) and the [Helm value reference](/guides/helm-values#cross-namespace-references) for details. +::: + For complex resource orchestration and dependencies, we recommend using [kro (Kube Resource Orchestrator)](https://kro.run). ## Release Phases diff --git a/website/docs/guides/field-export.md b/website/docs/guides/field-export.md index 8d52ae88..eef8c134 100644 --- a/website/docs/guides/field-export.md +++ b/website/docs/guides/field-export.md @@ -108,7 +108,9 @@ spec: ## Security Considerations -`FieldExport` only exports fields from resources in the **same namespace** as the `FieldExport` resource. This prevents users from exporting fields from resources they don't have access to in other namespaces. +By default, `FieldExport` can target a ConfigMap or Secret in a different namespace than the source resource. This cross-namespace behavior is gated by the `enableCrossNamespace` Helm value (`--enable-cross-namespace` flag), whose default will change from `true` to `false` in a future release. When disabled, `FieldExport` only operates within the **same namespace** as the source resource, which prevents users from exporting fields to namespaces they don't have access to. + +See [Breaking Changes](/breaking-changes) and the [Helm value reference](/guides/helm-values#cross-namespace-references) for details. ## Next Steps diff --git a/website/docs/guides/helm-values.md b/website/docs/guides/helm-values.md index 3ef69854..f1b516b2 100644 --- a/website/docs/guides/helm-values.md +++ b/website/docs/guides/helm-values.md @@ -284,6 +284,17 @@ serviceAccount: For cross-account resource management, use the **IAMRoleSelector** feature gate (recommended) or CARM feature gates. See [Granular IAM Roles](/guides/cross-account) for setup instructions. +## Cross-Namespace References + +### `enableCrossNamespace` +- **Type**: Boolean +- **Default**: `true` +- **Description**: Enable cross-namespace behavior including resource references (`*Ref` fields), secret references (`SecretKeyReference`), and `FieldExport` targets. When `false`, the controller rejects any operation that crosses namespace boundaries. Maps to the `--enable-cross-namespace` controller flag. + +:::warning +The default for `enableCrossNamespace` will change from `true` to `false` in a future release. If you rely on cross-namespace references, explicitly set `enableCrossNamespace: true` before upgrading. See [Breaking Changes](/breaking-changes) for details. +::: + ## Feature Gates Feature gates allow you to enable experimental or optional controller features.