From 389258fab9f15efc7c1d335d1ea228fd3248abba Mon Sep 17 00:00:00 2001
From: Ashish Amarnath <ashish.amarnath@gmail.com>
Date: Wed, 27 Feb 2019 11:42:25 -0800
Subject: [PATCH] Document the 'namespace' cli flag to capa controller (#615)

* document the 'namespace' cli flag to capa controller

https://github.com/kubernetes-sigs/cluster-api-provider-aws/pull/607

* fixes

* Update docs/reconcile-in-custom-namespace.md

Co-Authored-By: ashish-amarnath <ashish.amarnath@gmail.com>
---
 docs/README.md                        |  5 +++
 docs/reconcile-in-custom-namespace.md | 52 +++++++++++++++++++++++++++
 2 files changed, 57 insertions(+)
 create mode 100644 docs/reconcile-in-custom-namespace.md

diff --git a/docs/README.md b/docs/README.md
index 7ce4153031..48f818bb2d 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -11,6 +11,11 @@
 
 - [Development instructions](development.md)
 
+## Special use cases
+
+- [Creating multinode control plane clusters](creating-multinode-controlplane-clusters.md)
+- [Reconcile Cluster-API objects in a restricted namespace](reconcile-in-custom-namespace.md)
+
 ## Project Documentation
 
 - [Initial feature model](proposal/features.md)
diff --git a/docs/reconcile-in-custom-namespace.md b/docs/reconcile-in-custom-namespace.md
new file mode 100644
index 0000000000..191561f2d7
--- /dev/null
+++ b/docs/reconcile-in-custom-namespace.md
@@ -0,0 +1,52 @@
+# Reconcile Cluster-API Objects In Custom Namespace <!-- omit in toc -->
+
+Cluster-api-provider-aws controllers by default, reconcile cluster-api objects
+across all namespaces in the cluster. However, it is possible to restrict
+reconciliation to a single namespace and this document tells you how.
+
+## Contents <!-- omit in toc -->
+
+- [Use cases](#use-cases)
+- [Configuring `cluster-api-provider-aws` controllers](#configuring-cluster-api-provider-aws-controllers)
+
+## Use cases
+
+- Grouping clusters into a namespace based on the AWS account will allow
+  managing clusters across multiple AWS accounts. This will require each
+  `cluster-api-provider-aws` controller to have credentials to their respective
+  AWS accounts. These credentials can be created as kubernetes secret and be
+  mounted in the pod at `/root/.aws` or as environment variables.
+- Grouping clusters into a namespace based on their environment, (test,
+  qualification, canary, production) will allow a phased rolling out of
+  `cluster-api-provider-aws` releases.
+- Grouping clusters into a namespace based on the infrastructure provider will
+  allow running multiple cluster-api provider implementations side-by-side and
+  manage clusters across infrastructure providers.
+
+## Configuring `cluster-api-provider-aws` controllers
+
+- Create the namespace that `cluster-api-provider-aws` controller will watch for
+  cluster-api objects
+
+```(bash)
+cat <<EOF | kubectl apply -f -
+apiVersion: v1
+kind: Namespace
+metadata:
+  name: my-pet-clusters #edit if necessary
+EOF
+```
+
+- Deploy/edit `aws-provider-controller-manager` controller statefulset
+
+Specifically, edit the container spec for `cluster-api-aws-controller`, in the
+`aws-provider-controller-manager` statefulset, to pass a value to the `namespace`
+CLI flag.
+
+```(bash)
+        - -namespace=my-pet-clusters # edit this if necessary
+```
+
+Once the `aws-provider-controller-manager-0` pod restarts,
+`cluster-api-provider-aws` controllers will only reconcile the cluster-api
+objects in the `my-pet-clusters` namespace.