diff --git a/charts/tf-controller/README.md b/charts/tf-controller/README.md
index dcb6f7eb..bc7381f0 100644
--- a/charts/tf-controller/README.md
+++ b/charts/tf-controller/README.md
@@ -18,6 +18,10 @@ helm upgrade -i tf-controller tf-controller/tf-controller \
     --namespace flux-system
 ```
 
+### Using cross-namespace references
+
+The Terraform CRD for TF-controller includes references to other objects, for example to a Flux source, which can be in a different namespace to the Terraform. However, being able to access objects in another namespace is usually considered a security risk, so references crossing namespaces are (since version 0.16.0) disallowed by default. If you want to allow them, set the Helm chart value `allowCrossNamespaceRefs: true` (see the table below).
+
 ## Configuration
 
 The following table lists the configurable parameters of the TF-controller chart and their default values.
diff --git a/charts/tf-controller/README.md.gotmpl b/charts/tf-controller/README.md.gotmpl
index 677c0745..c6d8f52c 100644
--- a/charts/tf-controller/README.md.gotmpl
+++ b/charts/tf-controller/README.md.gotmpl
@@ -18,6 +18,10 @@ helm upgrade -i tf-controller tf-controller/tf-controller \
     --namespace flux-system
 ```
 
+### Using cross-namespace references
+
+The Terraform CRD for TF-controller includes references to other objects, for example to a Flux source, which can be in a different namespace to the Terraform. However, being able to access objects in another namespace is usually considered a security risk, so references crossing namespaces are (since version 0.16.0) disallowed by default. If you want to allow them, set the Helm chart value `allowCrossNamespaceRefs: true` (see the table below).
+
 ## Configuration
 
 The following table lists the configurable parameters of the TF-controller chart and their default values.
diff --git a/docs/how_to/index.md b/docs/how_to/index.md
index 73f07b8f..913a4a66 100644
--- a/docs/how_to/index.md
+++ b/docs/how_to/index.md
@@ -5,3 +5,4 @@
   - [How does the interval and retryInterval work?](interval_and_retryInterval.md)
   - [How does the resource deletion work?](resource_deletion.md)
   - [How to integrate with Flux Receivers and Alerts?](flux_receiver_and_alert.md)
+  - [How to enable cross-namespace references](use-cross-namespace-refs.md)
diff --git a/docs/how_to/use-cross-namespace-refs.md b/docs/how_to/use-cross-namespace-refs.md
new file mode 100644
index 00000000..745443a9
--- /dev/null
+++ b/docs/how_to/use-cross-namespace-refs.md
@@ -0,0 +1,20 @@
+# Using cross-namespace references
+
+The Terraform CRD in the API for TF-controller includes fields which are references to other objects:
+
+| Name | Purpose |
+|------|---------|
+| .spec.sourceRef | Refers to a Flux source |
+| .spec.dependsOn[*] | Each entry refers to a dependency |
+| .spec.cliConfigSecretRef | Secret with `tf` config to use |
+
+The branch planner configuration can also have cross-namespace references:
+
+| Name | Purpose |
+|------|---------|
+| .secretNamespace | Namespace of secret containing a GitHub token |
+| .resources[*] | Each entry refers to a Terraform object to include in branch planning |
+
+All of these can refer to an object in a namespace different to that of the Terraform object. However, giving access to objects in other namespaces is generally considered a security risk, so this is disallowed by default. Only references that mention the same namespace, or omit the namespace field, will be accepted. References using a different namespace will cause the controller to stop processing the Terraform object and put it in a non-Ready state.
+
+To **allow** cross-namespace references, use the flag `--allow-cross-namespace-refs` with the controller and branch-planner. When using the Helm chart to install or update the controller and branch-planner, the value `allowCrossNamespaceRefs` will allow cross-namespace references for both.