Add document outline how permissions work

Signed-off-by: tylerslaton <mtslaton1@gmail.com>
acorn-io · Nov 18, 2022 · ee8e714 · ee8e714
1 parent b5af26e
commit ee8e714
Show file tree

Hide file tree

Showing 2 changed files with 129 additions and 0 deletions.
diff --git a/docs/docs/100-reference/03-acornfile.md b/docs/docs/100-reference/03-acornfile.md
@@ -401,6 +401,50 @@ containers: web: {
 }
 ```
 
+### permissions
+
+`permissions` allow you to define what resources the container can interact with on-cluster and what it can do with them.
+
+```acorn
+containers: web: {
+    image: "nginx"
+    permissions: {
+		// These are permissions that will only be granted for this container in its namespace.
+		rules: [{
+			// Configure what actions you can do on the defined resources
+			verbs: [
+				"get", 
+				"list", 
+				"watch",
+				"create", 
+			]
+			// Define what API group the resources belong to
+			apiGroups: [
+				"api.sample.io"
+			]
+			// Configure which resources in the above apiGroups to apply the above verbs to
+			resources: [
+				"fooresource"
+			]
+		}]
+		// These are permissions that will be granted for this container in all namespaces.
+		clusterrules: [{
+			verbs: [
+				"get", 
+				"list", 
+				"watch",
+			]
+			apiGroups: [
+				"api.sample.io"
+			]
+			resources: [
+				"fooresource"
+			]
+		}]
+    }
+}
+```
+
 ## jobs
 `jobs` are containers that are run once to completion. If the configuration of the job changes, the will
 be ran once again.  All fields that apply to [containers](#containers) also apply to

diff --git a/docs/docs/38-authoring/09-permissions.md b/docs/docs/38-authoring/09-permissions.md
@@ -0,0 +1,85 @@
+---
+title: Permissions
+---
+
+When writing applications, you can run into a situation where your application needs to interact with on-cluster resources. In a typical Kubernetes environment you would need to go through a somewhat involved process to accomplish this. Luckily, `permissions` is a straight forward Acornfile definition that allows you to simplify that process.
+
+Let's take a look at an example. Here we have a `container`, named API, that we want to grant CRUD operations on the `FooResource` in the application's namespace. For all other namespaces, we want the `container` to only be able to retrieve `FooResources`.
+
+```acorn
+containers:{
+    api: {
+        // ...
+        permissions: {
+            rules: [{
+                verbs: [
+                    "get", 
+                    "list", 
+                    "watch",
+                    "create", 
+                    "update",
+                    "patch", 
+                    "delete"
+                ]
+                apiGroups: [
+                    "api.sample.io"
+                ]
+                resources: [
+                    "fooresource"
+                ]
+            }]
+            clusterrules: [{
+                verbs: [
+                    "get", 
+                    "list", 
+                    "watch",
+                ]
+                apiGroups: [
+                    "api.sample.io"
+                ]
+                resources: [
+                    "fooresource"
+                ]
+            }]
+        / ...
+    }
+}
+```
+
+:::info
+If you're curious, running this Acornfile creates a few `permissions` related things for us, such as a:
+- `ServiceAccount` bound to the `container`'s `Deployment`
+- `Role` with the `rules` we specified
+- `ClusterRole` with the `clusterrules` we specified
+- `RoleBinding` with `Role` bound to the `ServiceAccount`
+- `ClusterRoleBinding` with the `ClusterRole` bound to the `ServiceAccount`
+:::
+
+With this Acornfile, we accomplish our original goal. Breaking down the Acornfile a bit further, we get 5 keywords that are set to define permissions. Let's look at them one at a time.
+
+## Rules
+Physically defining the permissions of your application, `rules` get converted into a `Role` that then gets attached to your application's unique `ServiceAccount`. This is only applicable for your application's unique namespace and as a result the permissions will not work in other namespaces.
+
+## ClusterRules
+Similar to `rules`, `clusterrules` define the permissions application's namespace but with the added benefit of working in other ones as well. Instead of creating a `Role` that gets attached to your application's `ServiceAccount`, you get a `ClusterRole`. If you would like to allow your application to perform the defined rules in any namespace on the cluster then `clusterrules` are the way to go.
+
+## Verbs
+To define what actions your application can perform on a given resource, you define a `verb`. These `verbs` are words that allow you to declaritively define what actions your application can perform on given resources.
+
+:::info
+Wondering what verbs are available? Take a look!
+- get
+- list
+- watch
+- create
+- update
+- patch
+- delete
+- deletecollection
+:::
+
+## ApiGroups
+When interacting with on-cluster resources, related resources are typically grouped by an `apiGroup`. For the context of Acorn, we need to know what `apiGroup` the resource we're granting permissions for is in. In our original example this was `api.sample.io` and others will typically be in this format.
+
+## Resources
+Inside of `apiGroups` you'll find associated `resources`. With this field, you specify which `resources` the `rules` you are creating apply to. In our original example, this was `foo`.