document Cluster Mode vs Namespace Mode RBAC

Adds explanation in the authorization.md document about the difference
between Cluster Mode and Namespace Mode when starting an ACK controller
including language that describes the various ClusterRole or Role
permissions required for controllers started in either mode.

Issue: #1173

Signed-off-by: Jay Pipes <jaypipes@gmail.com>

Author: jaypipes

docs/content/docs/user-docs/authorization.md

@@ -40,7 +40,78 @@ Refer to the following diagram for more details on running a Kubernetes API serv
 
 You will need to configure Kubernetes RBAC and AWS IAM permissions before using ACK service controllers.
 
-## Kubernetes RBAC for ACK controller
+## Kubernetes RBAC
+
+### Permissions required for the ACK service controller
+
+ACK service controllers may be started in either *Cluster Mode* or *Namespace
+Mode*. Controllers started in Cluster Mode watch for new, updated and deleted
+custom resources (CRs) in all Kubernetes `Namespaces`. Conversely, controllers
+started in Namespace Mode only watch for CRs in a single Kubernetes `Namespace`
+identified by the `--watch-namespace` flag.
+
+#### Namespace Mode
+
+When a service controller is started in Namespace Mode, the `--watch-namespace`
+flag is supplied and the controller will *only* watch for custom resources
+(CRs) in that Kubernetes Namespace.
+
+Controllers started in Namespace Mode require that the Kubernetes `Service
+Account` associated with the controller's `Deployment` have a `Role` with
+permissions to create, update/patch, delete, read, list and watch ACK custom
+resources matching the associated AWS service in the specific Kubernetes
+`Namespace` identified by the `--watch-namespace` flag.
+
+{{% hint type="info" title="The `installScope: namespace` Helm Chart value" %}}
+If you are installing an ACK service controller via the associated Helm Chart,
+you can simplify a Namespace Mode installation by setting the `installScope`
+value to `namespace`. This will cause the Helm Chart to install a
+namespace-scoped `RoleBinding` with the necessary permissions the controller
+needs to create, update, read, list and watch the ACK custom resources managed
+by the controller.
+{{% /hint %}}
+
+### Cluster Mode
+
+When a service controller is started in Cluster Mode, the `--watch-namespace`
+flag is not supplied and the controller will watch for ACK custom resources
+(CRs) across *all* Kubernetes `Namespaces`.
+
+Controllers started in Cluster Mode require that the Kubernetes `Service
+Account` associated with the controller's `Deployment` have a `ClusterRole`
+with permissions to create, update/patch, delete, read, list and watch ACK
+custom resources matching the associated AWS service in *all* Kubernetes
+`Namespaces`.
+
+To support cross-account resource management, controllers started in Cluster
+Mode require that the Kubernetes `Service Account` associated with the
+controller's `Deployment` have a `ClusterRole` with permissions to read, list
+and watch *all* `Namespace` objects.
+
+Additionally, the `ClusterRole` will need permissions to read `ConfigMap`
+resources in a specific Kubernetes `Namespace` identified by the environment
+variable `ACK_SYSTEM_NAMESPACE`, defaulting to `ack-system`.
+
+{{% hint type="info" title="Cross-account resource management requires Cluster Mode" %}}
+If you plan to use an ACK service controller to manage resources across many
+AWS accounts (cross-account resource management, or CARM), you *must* start the
+controller in Cluster Mode.
+{{% /hint %}}
+
+### Permission to read `Secret` objects
+
+Some ACK service controllers will replace plain-text values for some resource
+fields with the value of Kubernetes `Secret` keys.
+
+For controllers started in Namespace Mode, the `Role` must have permissions to
+read `Secret` objects in the Kubernetes `Namespace` identified by the
+`--watch-namespace` flag.
+
+For controllers started in Cluster Mode, the `ClusterRole` must have
+permissions to read `Secret` resources in *any Kubernetes `Namespace` within
+which ACK custom resources may be launched*.
+
+### Roles for reading and writing ACK custom resources
 
 As part of installation, Kubernetes `Role` resources are automatically created. These roles contain permissions to modify the Kubernetes custom resources (CRs) that the ACK service controller is responsible for.
 

docs/content/docs/user-docs/cross-account-resource-management.md

@@ -1,5 +1,5 @@
 ---
-title: "Manage Resources In Multiple AWS Accounts (CARM)"
+title: "Manage Resources In Multiple AWS Accounts"
 description: "Managing resources in different AWS accounts"
 lead: ""
 draft: false
@@ -18,6 +18,10 @@ ACK service controllers can manage resources in different AWS accounts. To enabl
 
 For detailed information about how ACK service controllers manage resources in multiple AWS accounts, please refer to the Cross-Account Resource Management (CARM) [design document](https://github.com/aws-controllers-k8s/community/blob/main/docs/design/proposals/carm/cross-account-resource-management.md).
 
+{{% hint type="note" title="To use CARM, `--watch-namespace` must be empty" %}}
+ACK service controllers may be started in either Cluster Mode or Namespace Mode. When a service controller is started in Namespace Mode, the `--watch-namespace` flag is supplied and the controller will *only* watch for custom resources (CRs) in that Kubernetes Namespace. Because the cross-account resource management feature requires the controller to watch for custom resources on many Kubernetes Namespaces, this feature is incompatible with the Namespace Mode of running a controller and thus the `--watch-namespace` flag must not be set (or be set to an empty string).
+{{% /hint %}}
+
 ## Step 1: Configure your AWS accounts
 
 AWS account administrators should create and configure IAM roles to allow ACK service controllers to assume roles in different AWS accounts.
@@ -41,7 +45,7 @@ apiVersion: v1
 kind: ConfigMap
 metadata:
   name: ack-role-account-map
-  namespace: ack-system
+  namespace: $ACK_SYSTEM_NAMESPACE
 data:
   "111111111111": arn:aws:iam::111111111111:role/s3FullAccess
 EOF

docs/content/docs/user-docs/install.md

@@ -38,7 +38,7 @@ Helm charts for individual ACK service controllers are tagged with their release
 [ack-ecr-gallery]: https://gallery.ecr.aws/aws-controllers-k8s
 [s3-ecr-chart]: https://gallery.ecr.aws/aws-controllers-k8s/s3-chart
 
-Before installing a Helm chart, you must first make the Helm chart available on the `Deployment` host. To do so, use the `helm pull` command and then extract the chart:
+Before installing a Helm chart, you must first make the Helm chart available on the dDeployment host. To do so, use the `helm pull` command and then extract the chart:
 
 ```bash
 export HELM_EXPERIMENTAL_OCI=1
@@ -63,16 +63,16 @@ different version, change the `RELEASE_VERSION` variable and execute the command
 Once the Helm chart is downloaded and exported, you can install a particular ACK service controller using the `helm install` command:
 
 ```bash
-export ACK_K8S_NAMESPACE=ack-system
+export ACK_SYSTEM_NAMESPACE=ack-system
 export AWS_REGION=us-west-2
 
-helm install --create-namespace --namespace $ACK_K8S_NAMESPACE ack-$SERVICE-controller \
+helm install --create-namespace --namespace $ACK_SYSTEM_NAMESPACE ack-$SERVICE-controller \
     --set aws.region="$AWS_REGION" \
     $CHART_EXPORT_PATH/$SERVICE-chart
 ```
 
-{{% hint type="info" title="Specify your region" %}}
-The commands above set the service region of the S3 controller to `us-west-2`. Be sure to specify your region in the `AWS_REGION` variable.
+{{% hint type="info" title="Specify your target service region" %}}
+The commands above set the target service region of the S3 controller to `us-west-2`. Be sure to specify your target service region in the `AWS_REGION` variable. This will be the *default* AWS region in which resources will be created by the ACK service controller. Note that a single ACK service controller can manage the lifecycle of resources in multiple AWS regions: simply add the `services.k8s.aws/region=$REGION` annotation to your resource. Alternately, you can add the `services.k8s.aws/region=$REGION` annotation to a Kubernetes `Namespace` and any resource launched in that `Namespace` will be created in that region by default.
 {{% /hint %}}
 
 The `helm install` command should return relevant installation information:
@@ -89,7 +89,7 @@ TEST SUITE: None
 To verify that the Helm chart was installed, use the `helm list` command:
 
 ```bash
-helm list --namespace $ACK_K8S_NAMESPACE -o yaml
+helm list --namespace $ACK_SYSTEM_NAMESPACE -o yaml
 ```
 
 The `helm list` command should return your newly-deployed Helm chart release information: