docs: document enableCrossNamespace Helm value and cross-link references

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**<br/>**(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
+```

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

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

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
 

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.

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',
+    },
   ],
 };
 

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;
+}