From deffe2024aac488a4686cb0f90a2f7d3a15903ea Mon Sep 17 00:00:00 2001
From: Michelle Noorali <michelle@deis.com>
Date: Thu, 3 Aug 2017 09:17:58 -0700
Subject: [PATCH] chore(docs): add guide for service accounts

* closes #2224
---
 docs/service_accounts.md | 39 +++++++++++++++++++++++++++++++++++++++
 docs/using_helm.md       |  2 +-
 2 files changed, 40 insertions(+), 1 deletion(-)
 create mode 100644 docs/service_accounts.md

diff --git a/docs/service_accounts.md b/docs/service_accounts.md
new file mode 100644
index 000000000..19a2e2cb6
--- /dev/null
+++ b/docs/service_accounts.md
@@ -0,0 +1,39 @@
+# Tiller and Service Accounts
+
+In Kubernetes, granting a role to an application-specific service account is a best practice to ensure that your application is operating in the scope that you have specified. Read more about service account permissions in Kubernetes [here](https://kubernetes.io/docs/admin/authorization/rbac/#service-account-permissions).
+
+You can add a service account to Tiller using the `--service-account <NAME>` flag while you're configuring helm. As a prerequisite, you'll have to create a role binding which specifies a [role](https://kubernetes.io/docs/admin/authorization/rbac/#role-and-clusterrole) and a [service account](https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/) name that have been set up in advance.
+
+Once you have satisfied the pre-requisite and have a service account with the correct permissions, you'll run a command like this: `helm init --service-account <NAME>`
+
+## Example
+
+In `rbac-config.yaml`:
+```yaml
+apiVersion: v1
+kind: ServiceAccount
+metadata:
+  name: helm
+  namespace: kube-system
+---
+apiVersion: rbac.authorization.k8s.io/v1beta1
+kind: ClusterRoleBinding
+metadata:
+  name: helm
+roleRef:
+  apiGroup: rbac.authorization.k8s.io
+  kind: ClusterRole
+  name: cluster-admin
+subjects:
+  - kind: ServiceAccount
+    name: helm
+    namespace: kube-system
+```
+
+
+```console
+$ kubectl create -f rbac-config.yaml
+$ helm init --service-account helm
+```
+
+_Note: You do not have to specify a ClusterRole or a ClusterRoleBinding. You can specify a Role and RoleBinding instead to limit Tiller's scope to a particular namespace_
diff --git a/docs/using_helm.md b/docs/using_helm.md
index 777661ea5..502f51bc4 100755
--- a/docs/using_helm.md
+++ b/docs/using_helm.md
@@ -494,7 +494,7 @@ accepts chart source code, and (after audit) packages those for you.
 In some cases you may wish to scope Tiller or deploy multiple Tillers to a single cluster. Here are some best practices when operating in those circumstances.
 
 1. Tiller can be [installed](install.md) into any namespace. By default, it is installed into kube-system. You can run multiple Tillers provided they each run in their own namespace.
-2. Limiting Tiller to only be able to install into specific namespaces and/or resource types is controlled by Kubernetes [RBAC](https://kubernetes.io/docs/admin/authorization/rbac/) roles and rolebindings.
+2. Limiting Tiller to only be able to install into specific namespaces and/or resource types is controlled by Kubernetes [RBAC](https://kubernetes.io/docs/admin/authorization/rbac/) roles and rolebindings. You can add a service account to Tiller when configuring Helm via `helm init --service-acount <NAME>`. You can find more information about that [here](service_accounts.md).
 3. Release names are unique PER TILLER INSTANCE.
 4. Charts should only contain resources that exist in a single namespace.
 5. It is not recommended to have multiple Tillers configured to manage resources in the same namespace.
-- 
GitLab