From 63e66ca3ae2d3a0a83911fba31090ab01d7a5f24 Mon Sep 17 00:00:00 2001
From: Leonardo Luz Almeida <leonardo_almeida@intuit.com>
Date: Thu, 24 Oct 2024 12:03:23 -0700
Subject: [PATCH] add more docs

Signed-off-by: Leonardo Luz Almeida <leonardo_almeida@intuit.com>
---
 README.md | 76 ++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 75 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 52dad97..5b05d46 100644
--- a/README.md
+++ b/README.md
@@ -5,12 +5,86 @@
 This project is an Argo CD extension to allow ephemeral access in Argo
 CD UI. It can be viewed as something similar to the functionality that
 `sudo` command provides as users can execute actions that require
-higher permissions.
+higher permissions. The exact access the user is allowed to be
+elevated to and for how long the access should be granted are
+configurable. The elevated access are automatically managed by
+creating and updating Argo CD AppProject roles. 
+
+Note: This project requires that the Argo CD `Applications` are
+associated with `AppProjects` different than `default`.
 
 ## How it Works
 
+This project provides a new set of CRDs that are used to configure the
+behaviour of how the access can be elevated. The CRDs provided as part of
+this project are described below:
+
+### RoleTemplate
+
+The `RoleTemplate` defines the Argo CD RBAC policies that will be
+associated with an Argo CD `AppProject`. 
+
+```yaml
+apiVersion: ephemeral-access.argoproj-labs.io/v1alpha1
+kind: RoleTemplate
+metadata:
+  name: devops
+spec:
+  description: write permission in application {{.Application}}
+  name: "DevOps (Write)"
+  policies:
+  - p, {{.Role}}, applications, sync, {{.Project}}/{{.Application}}, allow
+  - p, {{.Role}}, applications, action/*, {{.Project}}/{{.Application}}, allow
+  - p, {{.Role}}, applications, delete/*/Pod/*, {{.Project}}/{{.Application}}, allow
+```
+
+### AccessBinding
+
+```yaml
+apiVersion: ephemeral-access.argoproj-labs.io/v1alpha1
+kind: AccessBinding
+metadata:
+  name: some-access-binding
+spec:
+  roleTemplateRef:
+    name: devops
+  subjects: 
+    - group1
+  if: "true"
+  ordinal: 1
+  friendlyName: "Devops (AB)"
+```
+
+### AccessRequest
+
+```yaml
+apiVersion: ephemeral-access.argoproj-labs.io/v1alpha1
+kind: AccessRequest
+metadata:
+  name: some-application-username
+  namespace: ephemeral
+spec:
+  duration: '1m'
+  targetRoleName: ephemeral-write-access
+  appProject: 
+    name: some-argocd-appproject
+    namespace: some-namespace
+  subject:
+    username: some_user@fakedomain.com
+```
+
+
 ## Installing
 
+The ephemeral-access functionality is provided by the following
+components that needs to be configured properly to achieve the desired
+behaviour:
+
+- ui: Argo CD UI extension that provides users with the functionality
+  to request elevated access to an Argo CD Application.
+- backend: Serves the REST API used by the UI extension.
+- controller: Responsible for reconciling the AccessRequest resource.
+
 We provide a consolidated `install.yaml` asset file in every release.
 Check the latest release in the [releases page][1] and replace the
 `DESIRED_VERSION` in the command below.