Clarify that object storage should per-cluster

Signed-off-by: Dave Parfitt <[email protected]>

docs/aws-config.md

@@ -11,7 +11,7 @@ If you do not have the `aws` CLI locally installed, follow the [user guide][5] t
 
 ## Create S3 bucket
 
-Heptio Ark requires an object storage bucket to store backups in. Create an S3 bucket, replacing placeholders appropriately:
+Heptio Ark requires an object storage bucket to store backups in, preferrably unique to a single Kubernetes cluster (see the [FAQ][20] for more details). Create an S3 bucket, replacing placeholders appropriately:
 
 ```bash
 aws s3api create-bucket \
@@ -36,6 +36,8 @@ For more information, see [the AWS documentation on IAM users][14].
     ```bash
     aws iam create-user --user-name heptio-ark
     ```
+
+    > If you'll be using Ark to backup multiple clusters with multiple S3 buckets, it may be desirable to create a unique username per cluster rather than the default `heptio-ark`.
 
 2. Attach policies to give `heptio-ark` the necessary permissions:
 
@@ -271,3 +273,4 @@ It can be set up for Ark by creating a role that will have required permissions,
 [5]: https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-welcome.html
 [6]: config-definition.md#aws
 [14]: http://docs.aws.amazon.com/IAM/latest/UserGuide/introduction.html
+[20]: faq.md

docs/azure-config.md

@@ -49,9 +49,12 @@ az storage account create \
     --https-only true \
     --kind BlobStorage \
     --access-tier Hot
+```
+
+Create the blob container named `ark`. Feel free to use a different name, preferrably unique to a single Kubernetes cluster. See the [FAQ][20] for more details. You'll need to
+adjust the `bucket` field under `backupStorageProvider` in the Ark Config accordingly if you do.
 
-# Create the blob container named "ark". Feel free to use a different name; you'll need to
-# adjust the `bucket` field under `backupStorageProvider` in the Ark Config accordingly if you do.
+```bash
 az storage container create -n ark --public-access off --account-name $AZURE_STORAGE_ACCOUNT_ID
 
 # Obtain the storage access key for the storage account just created
@@ -92,6 +95,8 @@ To integrate Ark with Azure, you must create an Ark-specific [service principal]
 
 1. Create a service principal with `Contributor` role. This will have subscription-wide access, so protect this credential. You can specify a password or let the `az ad sp create-for-rbac` command create one for you.
 
+    > If you'll be using Ark to backup multiple clusters with multiple blob containers, it may be desirable to create a unique username per cluster rather than the default `heptio-ark`.
+
     ```bash
     # Create service principal and specify your own password
     AZURE_CLIENT_SECRET=super_secret_and_high_entropy_password_replace_me_with_your_own
@@ -165,4 +170,5 @@ In the root of your Ark directory, run:
   [8]: config-definition.md#azure
   [17]: https://docs.microsoft.com/en-us/azure/active-directory/develop/active-directory-application-objects
   [18]: https://docs.microsoft.com/en-us/cli/azure/install-azure-cli
-  [19]: https://docs.microsoft.com/en-us/azure/architecture/best-practices/naming-conventions#storage
+  [19]: https://docs.microsoft.com/en-us/azure/architecture/best-practices/naming-conventions#storage
+  [20]: faq.md

docs/gcp-config.md

@@ -9,7 +9,7 @@ If you do not have the `gcloud` and `gsutil` CLIs locally installed, follow the
 
 ## Create GCS bucket
 
-Heptio Ark requires an object storage bucket in which to store backups. Create a GCS bucket, replacing placeholder appropriately:
+Heptio Ark requires an object storage bucket in which to store backups, preferrably unique to a single Kubernetes cluster (see the [FAQ][20] for more details). Create a GCS bucket, replacing placeholder appropriately:
 
 ```bash
 gsutil mb gs://<YOUR_BUCKET>/
@@ -34,6 +34,8 @@ To integrate Heptio Ark with GCP, create an Ark-specific [Service Account][15]:
         --display-name "Heptio Ark service account"
     ```
 
+    > If you'll be using Ark to backup multiple clusters with multiple GCS buckets, it may be desirable to create a unique username per cluster rather than the default `heptio-ark`.
+
     Then list all accounts and find the `heptio-ark` account you just created:
     ```bash
     gcloud iam service-accounts list
@@ -118,5 +120,6 @@ In the root of your Ark directory, run:
   [7]: config-definition.md#gcp
   [15]: https://cloud.google.com/compute/docs/access/service-accounts
   [16]: https://cloud.google.com/sdk/docs/
+  [20]: faq.md
   [22]: https://cloud.google.com/kubernetes-engine/docs/how-to/role-based-access-control#prerequisites_for_using_role-based_access_control