From deffe2024aac488a4686cb0f90a2f7d3a15903ea Mon Sep 17 00:00:00 2001 From: Michelle Noorali Date: Thu, 3 Aug 2017 09:17:58 -0700 Subject: [PATCH 1/2] 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 ` 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 ` + +## 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 `. 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. From f1bd1e684ae5d501aa3f0c3a163d1768f450a09a Mon Sep 17 00:00:00 2001 From: Michelle Noorali Date: Fri, 4 Aug 2017 15:29:30 -0400 Subject: [PATCH 2/2] docs(service_accounts): add non cluster-admin ex --- docs/service_accounts.md | 87 ++++++++++++++++++++++++++++++++++++---- 1 file changed, 80 insertions(+), 7 deletions(-) diff --git a/docs/service_accounts.md b/docs/service_accounts.md index 19a2e2cb6..612074d03 100644 --- a/docs/service_accounts.md +++ b/docs/service_accounts.md @@ -1,39 +1,112 @@ # 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). +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 the official Kubernetes docs](https://kubernetes.io/docs/admin/authorization/rbac/#service-account-permissions). Bitnami also has a fantastic guide for [configuring RBAC in your cluster](https://docs.bitnami.com/kubernetes/how-to/configure-rbac-in-your-kubernetes-cluster/) that takes you through RBAC basics. You can add a service account to Tiller using the `--service-account ` 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 ` -## Example +## Example: Service account with cluster-admin role + +```console +$ kubectl create serviceaccount tiller --namespace kube-system +``` In `rbac-config.yaml`: ```yaml apiVersion: v1 kind: ServiceAccount metadata: - name: helm + name: tiller namespace: kube-system --- apiVersion: rbac.authorization.k8s.io/v1beta1 kind: ClusterRoleBinding metadata: - name: helm + name: tiller roleRef: apiGroup: rbac.authorization.k8s.io kind: ClusterRole name: cluster-admin subjects: - kind: ServiceAccount - name: helm + name: tiller namespace: kube-system ``` +_Note: The cluster-admin role is created by default in a Kubernetes cluster, so you don't have to define it explicitly._ ```console $ kubectl create -f rbac-config.yaml -$ helm init --service-account helm +$ helm init --service-account tiller +``` + +## Example: Service account restricted to a namespace +In the example above, we gave Tiller admin access to the entire cluster. You are not at all required to give Tiller cluster-admin access for it to work. Instead of specifying a ClusterRole or a ClusterRoleBinding, you can specify a Role and RoleBinding to limit Tiller's scope to a particular namespace. + +```console +$ kubectl create namespace tiller-world +namespace "tiller-world" created +$ kubectl create serviceaccount tiller --namespace tiller-world +serviceaccount "tiller" created +``` + +Define a Role like in `role-tiller.yaml`: +```yaml +kind: Role +apiVersion: rbac.authorization.k8s.io/v1beta1 +metadata: + namespace: tiller-world + name: tiller-manager +rules: +- apiGroups: ["", "extensions", "apps"] + resources: ["deployments", "replicasets", "pods", "configmaps", "secrets", "namespaces"] + verbs: ["get", "list", "watch", "create", "update", "patch", "delete"] # You can also use ["*"] +``` + +```console +$ kubectl create -f role-tiller.yaml +role "tiller-manager" created +``` + +In `rolebinding-tiller.yaml`, +```yaml +kind: RoleBinding +apiVersion: rbac.authorization.k8s.io/v1beta1 +metadata: + name: tiller-binding + namespace: tiller-world +subjects: +- kind: ServiceAccount + name: tiller + namespace: tiller-world +roleRef: + kind: Role + name: tiller-manager + apiGroup: rbac.authorization.k8s.io +``` + +```console +$ kubectl create -f rolebinding-tiller.yaml +rolebinding "tiller-binding" created +``` + +```console +$ helm init --service-account tiller --tiller-namespace tiller-world +$HELM_HOME has been configured at /Users/awesome-user/.helm. + +Tiller (the helm server side component) has been installed into your Kubernetes Cluster. +Happy Helming! + +$ helm install nginx --tiller-namespace tiller-world --namespace tiller-world +NAME: wayfaring-yak +LAST DEPLOYED: Mon Aug 7 16:00:16 2017 +NAMESPACE: tiller-world +STATUS: DEPLOYED + +RESOURCES: +==> v1/Pod +NAME READY STATUS RESTARTS AGE +wayfaring-yak-alpine 0/1 ContainerCreating 0 0s ``` -_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_