Merge pull request #966 from weaveworks/cross-namespace-docs

Explain `allowCrossNamespaceRefs` in chart README and docs/howto/

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.

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.

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)

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.