Merge pull request #1271 from SgtCoDFish/trustnamespace

Add docs on trust namespace

content/docs/projects/trust-manager/README.md

@@ -49,12 +49,12 @@ spec:
   # those issued by Let's Encrypt, Google, Amazon and others.
   - useDefaultCAs: true
 
-  # A Secret in the trust-manager namespace
+  # A Secret in the "trust" namespace; see "Trust Namespace" below for further details
   - secret:
       name: "my-db-tls"
       key: "ca.crt"
 
-  # A ConfigMap in the trust-manager namespace
+  # A ConfigMap in the "trust" namespace; see "Trust Namespace" below for further details
   - configMap:
       name: "my-org.net"
       key: "root-certs.pem"
@@ -138,6 +138,21 @@ We strongly recommend that you install trust-manager using Helm and we don't cur
 versions of trust-manager. This is so that we can focus on continuing to improve trust-manager with the resources
 we currently have available.
 
+### Trust Namespace
+
+One of the more important configuration options you might need to consider at install time is which "trust namespace" to use,
+which can be set via the Helm value `app.trust.namespace`.
+
+The trust namespace is the only one in which `Secret` and `ConfigMap` sources can be read. This restriction is in place
+for security reasons - we don't want to give trust-manager the permission to read all `Secret`s or `ConfigMap`s in all namespaces.
+
+The trust namespace defaults to `cert-manager`, but there's no need for it to be set to the namespace that cert-manager
+is installed in - trust-manager has no runtime dependency on cert-manager at all! - so we'd recommend setting the trust
+namespace to whichever is most appropriate for your environment.
+
+An ideal deployment would be a fresh namespace dedicated entirely to trust-manager, to minimize the number of actors in your
+cluster that can modify your trust sources.
+
 ## Quick Start Example
 
 Let's get started with an example of creating our own `Bundle`!