describe kapp-controller security design for App CR privileges

README.md

@@ -4,12 +4,13 @@
 - [Docs](docs/README.md) with topics about installation, config, etc.
 - Install: see [Install instructions](docs/install.md)
 
-kapp controller provides a way to specify which applications should run on your K8s cluster. It will install, and continiously apply updates.
+kapp controller provides a way to specify which applications should run on your K8s cluster via one or more App CRs. It will install, and continiously apply updates.
 
 Features:
 
-- supports fetching Helm charts (via `helm fetch`), git repos (via `git`), Docker images (via [imgpkg](https://github.com/k14s/imgpkg)), inline content within resource
+- supports fetching git repos (via `git`), Helm charts (via `helm fetch`), Docker images (via [imgpkg](https://github.com/k14s/imgpkg)), inline content within resource
 - supports templating of Helm charts, [ytt](https://get-ytt.io) configuration (let us know what else we should support...)
 - installs and syncs resources with [kapp](https://get-kapp.io)
+- [secure multi-tenant usage](docs/security-model.md) via service accounts and RBAC
 
 More details in [docs](docs/README.md).

docs/README.md

@@ -5,5 +5,6 @@
 - [Walkthrough](walkthrough.md)
 - [Config](config.md)
 - [App CRD spec](app-spec.md)
+- [Security model](security-model.md)
 - [Dangerous Flags](dangerous-flags.md)
 - [examples/ directory](../examples/)

docs/security-model.md

@@ -0,0 +1,20 @@
+## Security Model
+
+### App CR privileges
+
+kapp-controller container runs with a service account (named `kapp-controller-sa` inside `kapp-controller` namespace) that has access to all service accounts and secrets in the cluster. This service account *is not* used for deployment of app resources.
+
+Each App CR *must* specify either a
+
+- service account (via `spec.serviceAccountName`)
+- or, Secret with kubeconfig contents for some cluster (via `spec.cluster.kubeconfigSecretRef.name`)
+
+forcing App CR owner to explicitly provide needed privileges for management of app resources. This avoids a problem of privilege escalation commonly found in other general resource controllers which rely on a shared service account (often requiring cluster admin privileges) to deploy resources.
+
+Since App CR only allows to reference service account or kubeconfig Secret within the same namespace where App CR is located, kapp-controller is well suited for multi-tenant use where different users of App CRD have varied level of access (e.g. some may have cluster level privileges, and other may only have access to one or more namespace).
+
+Example:
+
+- User A has been granted access to namespace `a` (and no other namespace or cluster level access). User A can create an App CR with a service account located in namespace `a` to deploy resources into namespace `a`. It _is not_ possible for user A to create an App CR that would install cluster-wide resources or place resources into another namespace. (e.g. a user that just deploys web application to their namespace)
+
+- User B has been granted access to namespace `b` and ability to manage specifically named CRD (single scoped cluster-wide privilege). User B can create an App CR with a service account located in namespace `b` that installs app into namespace `b` and also manages single CRD lifecycle. (e.g. a user that manages another controller for other users)