diff --git a/examples/README.md b/examples/README.md index b0cb5497b..ea8d8c0ac 100644 --- a/examples/README.md +++ b/examples/README.md @@ -88,3 +88,9 @@ Name | Description | Platform | Complexity Level -----| ----------- | ---------- | ---------------- custom-headers | set custom headers before send traffic to backends | nginx | Advanced configuration-snippets | customize nginx location configuration using annotations | nginx | Advanced + +## RBAC + +Name | Description | Platform | Complexity Level +-----| ----------- | ---------- | ---------------- +rbac | Configuring Role Base Access Control | nginx | intermediate diff --git a/examples/rbac/nginx/README.md b/examples/rbac/nginx/README.md new file mode 100644 index 000000000..dd9042d59 --- /dev/null +++ b/examples/rbac/nginx/README.md @@ -0,0 +1,137 @@ +# Role Based Access Control + +This example demontrates how to apply role based access control + +## Overview + +This example applies to nginx-ingress-controllers being deployed in an +environment with RBAC enabled. + +Role Based Access Control is comprised of four layers: + +1. `ClusterRole` - permissions assigned to a role that apply to an entire cluster +2. `ClusterRoleBinding` - binding a ClusterRole to a specific account +3. `Role` - permissions assigned to a role that apply to a specific namespace +4. `RoleBinding` - binding a Role to a specific account + +In order for RBAC to be applied to an nginx-ingress-controller, that controller +should be assigned to a `ServiceAccount`. That `ServiceAccount` should be +bound to the `Role`s and `ClusterRole`s defined for the +nginx-ingress-controller. + +## Service Accounts created in this example + +One ServiceAccount is created in this example, `nginx-ingress-serviceaccount`. + +## Permissions Granted in this example + +There are two sets of permissions defined in this example. Cluster-wide +permissions defined by the `ClusterRole` named `nginx-ingress-clusterrole`, and +namespace specific permissions defined by the `Role` named +`nginx-ingress-role`. + +### Cluster Permissions + +These permissions are granted in order for the nginx-ingress-controller to be +able to function as an ingress across the cluster. These permissions are +granted to the ClusterRole named `nginx-ingress-clusterrole` + +* `configmaps`, `endpoints`, `nodes`, `pods`, `secrets`: list, watch +* `services`, `ingresses`: get, list, watch +* `events`: create, patch +* `ingresses/status`: update + +### Namespace Permissions + +These permissions are granted specific to the nginx-ingress namespace. These +permissions are granted to the Role named `nginx-ingress-role` + +* `configmaps`, `pods`, `secrets`: get +* `endpoints`: create, get, update + +### Bindings + +The ServiceAccount `nginx-ingress-serviceaccount` is bound to the Role +`nginx-ingress-role` and the ClusterRole `nginx-ingress-clusterrole`. + +## Namespace created in this example + +The `Namespace` named `nginx-ingress` is defined in this example. The +namespace name can be changed arbitrarily as long as all of the references +change as well. + + +## Usage + +1. Create the `Namespace`, `Service Account`, `ClusterRole`, `Role`, +`ClusterRoleBinding`, and `RoleBinding`. + +```sh +kubectl create -f ./nginx-ingress-controller-rbac.yml +``` + +2. Create the nginx-ingress-controller + +For this example to work, the Service must be in the nginx-ingress namespace: + +```yaml +apiVersion: v1 +kind: Service +metadata: + name: nginx-ingress + namespace: nginx-ingress #match namespace of service account and role +spec: + type: LoadBalancer + ports: + - port: 80 + name: http + - port: 443 + name: https + selector: + k8s-app: nginx-ingress-lb +``` + +The serviceAccountName associated with the containers in the deployment must +match the serviceAccount from nginx-ingress-controller-rbac.yml The namespace +references in the Deployment metadata, container arguments, and POD_NAMESPACE +should be in the nginx-ingress namespace. + +```yaml +apiVersion: extensions/v1beta1 +kind: Deployment +metadata: + name: nginx-ingress-controller + #match namespace of service account and role + namespace: nginx-ingress +spec: + replicas: 2 + template: + metadata: + labels: + k8s-app: nginx-ingress-lb + spec: + #match name of service account + serviceAccountName: nginx-ingress-serviceaccount + containers: + - name: nginx-ingress-controller + image: gcr.io/google_containers/nginx-ingress-controller:version + #namespace matching is required in some arguments + args: + - /nginx-ingress-controller + - --default-backend-service=default/default-http-backend + - --default-ssl-certificate=$(POD_NAMESPACE)/tls-certificate + env: + - name: POD_NAME + valueFrom: + fieldRef: + fieldPath: metadata.name + #match namespace of service account and role + - name: POD_NAMESPACE + valueFrom: + fieldRef: + fieldPath: metadata.namespace + ports: + - containerPort: 80 + - containerPort: 443 + +``` diff --git a/examples/rbac/nginx/nginx-ingress-controller-rbac.yml b/examples/rbac/nginx/nginx-ingress-controller-rbac.yml new file mode 100644 index 000000000..fbe50f7ae --- /dev/null +++ b/examples/rbac/nginx/nginx-ingress-controller-rbac.yml @@ -0,0 +1,106 @@ +apiVersion: v1 +kind: Namespace +metadata: + name: nginx-ingress +--- +apiVersion: v1 +kind: ServiceAccount +metadata: + name: nginx-ingress-serviceaccount + namespace: nginx-ingress +--- +apiVersion: rbac.authorization.k8s.io/v1beta1 +kind: ClusterRole +metadata: + name: nginx-ingress-clusterrole +rules: + - apiGroups: + - "" + resources: + - configmaps + - endpoints + - nodes + - pods + - secrets + verbs: + - list + - watch + - apiGroups: + - "" + resources: + - services + verbs: + - get + - list + - watch + - apiGroups: + - "extensions" + resources: + - ingresses + verbs: + - get + - list + - watch + - apiGroups: + - "" + resources: + - events + verbs: + - create + - patch + - apiGroups: + - "extensions" + resources: + - ingresses/status + verbs: + - update +--- +apiVersion: rbac.authorization.k8s.io/v1beta1 +kind: Role +metadata: + name: nginx-ingress-role + namespace: nginx-ingress +rules: + - apiGroups: + - "" + resources: + - configmaps + - pods + - secrets + verbs: + - get + - apiGroups: + - "" + resources: + - endpoints + verbs: + - get + - create + - update +--- +apiVersion: rbac.authorization.k8s.io/v1beta1 +kind: RoleBinding +metadata: + name: nginx-ingress-role-nisa-binding + namespace: nginx-ingress +roleRef: + apiGroup: rbac.authorization.k8s.io + kind: Role + name: nginx-ingress-role +subjects: + - kind: ServiceAccount + name: nginx-ingress-serviceaccount + namespace: nginx-ingress +--- +apiVersion: rbac.authorization.k8s.io/v1beta1 +kind: ClusterRoleBinding +metadata: + name: nginx-ingress-clusterrole-nisa-binding +roleRef: + apiGroup: rbac.authorization.k8s.io + kind: ClusterRole + name: nginx-ingress-clusterrole +subjects: + - kind: ServiceAccount + name: nginx-ingress-serviceaccount + namespace: nginx-ingress