docs: add main project documentation in the README file

Makefile

@@ -113,7 +113,10 @@ run-backend: fmt vet ## Run the api backend server.
 ##@ Build
 
 .PHONY: build
-build: manifests generate fmt vet ## Build manager binary.
+build: build-ui build-go ## Build the UI extension and the ephemeral-access binary.
+
+.PHONY: build-go
+build-go: manifests generate fmt vet ## Build the ephemeral-access binary.
 	go build -o bin/ephemeral-access cmd/main.go
 
 # If you wish to build the manager image targeting other platforms you can use the --platform flag.
@@ -127,6 +130,15 @@ docker-build: ## Build docker image.
 docker-push: ## Push docker image.
 	$(CONTAINER_TOOL) push ${IMG}
 
+.PHONY: clean-ui
+clean-ui: ## delete the extension.tar file.
+	find ${UI_DIR} -type f -name extension.tar -delete
+
+.PHONY: build-ui
+build-ui: clean-ui ## build the Argo CD UI extension creating the ui/extension.tar file.
+	yarn --cwd ${UI_DIR} install
+	yarn --cwd ${UI_DIR} build
+
 .PHONY: goreleaser-build-local
 goreleaser-build-local: goreleaser ## Run goreleaser build locally. Use to validate the goreleaser configuration.
 	$(GORELEASER) build --snapshot --clean --single-target --verbose
@@ -148,15 +160,8 @@ docker-buildx: ## Build and push docker image for the manager for cross-platform
 	- $(CONTAINER_TOOL) buildx rm argocd-ephemeral-access-builder
 	rm Dockerfile.cross
 
-.PHONY: build-installer
-build-installer: manifests generate kustomize ## Generate a consolidated YAML with CRDs and deployment.
-	mkdir -p dist
-	cd config/default && $(KUSTOMIZE) edit set image argoproj-labs/argocd-ephemeral-access=${IMG}
-	$(KUSTOMIZE) build config/default > dist/install.yaml
-
 .PHONY: manifests-release
 manifests-release: generate manifests kustomize ## Generate the consolidated install.yaml with the release tag.
-	mkdir -p dist
 	./scripts/manifests-release.sh $(KUSTOMIZE) $(IMAGE_TAG)
 
 ##@ Deployment
@@ -175,7 +180,7 @@ uninstall: manifests kustomize ## Uninstall CRDs from the K8s cluster specified
 
 .PHONY: deploy
 deploy: manifests-release ## Deploy distribution to the K8s cluster specified in ~/.kube/config.
-	$(KUBECTL) apply -f dist/install.yaml
+	$(KUBECTL) apply -f install.yaml
 
 .PHONY: undeploy
 undeploy: kustomize ## Undeploy controller from the K8s cluster specified in ~/.kube/config. Call with ignore-not-found=true to ignore resource not found errors during deletion.
@@ -255,15 +260,6 @@ $(GOREMAN): $(LOCALBIN)
 generate-mocks: mockery ## Generate the mocks for the project as configured in .mockery.yaml
 	$(MOCKERY)
 
-.PHONY: clean-ui
-clean-ui:
-	find ${UI_DIR} -type f -name extension.tar -delete
-
-.PHONY: build-ui
-build-ui: clean-ui
-	yarn --cwd ${UI_DIR} install
-	yarn --cwd ${UI_DIR} build
-
 # go-install-tool will 'go install' any package with custom target and name of binary, if it doesn't exist
 # $1 - target path with name of binary (ideally with version)
 # $2 - package url which can be installed

README.md

@@ -1,17 +1,207 @@
 # argocd-ephemeral-access
 
-A kubernetes controller to manage Argo CD temporary access
+## Overview
+
+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. 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 an `AppProjects` different than `default`.
+
+## How it Works
+
+This project provides a set of CRDs that are used to configure the
+behaviour of how the Argo CD access can be elevated. The CRDs provided
+as part of this project are described below:
+
+### RoleTemplate
+
+The `RoleTemplate` defines a templated Argo CD RBAC policies. Once the
+elevated access is requested and approved, the policies will be
+rendered and dynamicaly associated with the AppProject related with
+the access request. 
+
+```yaml
+apiVersion: ephemeral-access.argoproj-labs.io/v1alpha1
+kind: RoleTemplate
+metadata:
+  name: devops
+spec:
+  description: write permission in application {{.application}}
+  name: "devops"
+  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 (Write)"
+```
+
+### AccessRequest
+
+```yaml
+apiVersion: ephemeral-access.argoproj-labs.io/v1alpha1
+kind: AccessRequest
+metadata:
+  name: some-application-username
+  namespace: ephemeral
+spec:
+  application:
+    name: ephemeral
+    namespace: argocd
+  duration: '1m'
+  role:
+    friendlyName: Devops (Write)
+    ordinal: 1
+    templateName: devops
+  subject:
+    username: [email protected]
+```
+
+## Installation
+
+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.
+
+### Installing the Backend and the Controller
+
+We provide a consolidated `install.yaml` asset file in every release.
+The `install.yaml` file contains all the resources required to run the
+backend service and the controller. Check the latest release in the
+[releases page][1] and replace the `DESIRED_VERSION` in the command
+below.
+
+```bash
+kubectl apply -f https://github.com/argoproj-labs/argocd-ephemeral-access/releases/download/<DESIRED_VERSION>/install.yaml
+```
+
+This command will create a new namespace `argocd-ephemeral-access` and
+deploy the necessary resources.
+
+### Install UI extension
+
+The UI extension needs to be installed by mounting the React component
+in Argo CD API server. This process can be automated by using the
+[argocd-extension-installer][2]. This installation method will run an
+init container that will download, extract and place the file in the
+correct location.
+
+The yaml file below is an example of how to define a kustomize patch
+to install this UI extension:
+
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: argocd-server
+spec:
+  template:
+    spec:
+      initContainers:
+        - name: extension-metrics
+          image: quay.io/argoprojlabs/argocd-extension-installer:v0.0.8@sha256:e7cb054207620566286fce2d809b4f298a72474e0d8779ffa8ec92c3b630f054
+          env:
+          - name: EXTENSION_URL
+            value: https://github.com/argoproj-labs/argocd-ephemeral-access/releases/download/v0.0.1/extension.tar.gz
+          - name: EXTENSION_CHECKSUM_URL
+            value: https://github.com/argoproj-labs/argocd-ephemeral-access/releases/download/v0.0.1/extension_checksums.txt
+          volumeMounts:
+            - name: extensions
+              mountPath: /tmp/extensions/
+          securityContext:
+            runAsUser: 1000
+            allowPrivilegeEscalation: false
+      containers:
+        - name: argocd-server
+          volumeMounts:
+            - name: extensions
+              mountPath: /tmp/extensions/
+      volumes:
+        - name: extensions
+          emptyDir: {}
+```
+
+## Usage
+
+## Contributing
 
 ### Development
 
-Build the image locally
+All necessary development tasks are available as `make targets`. Some
+of the targets will make use of external tools. All external tools
+used by this project will be automatically downloaded in the `bin`
+folder of this repo as required.
+
+#### Building
+
+For building all component of this project simply run `make` (which is
+an alias for `make build`). This target will:
+- Build the Go project. The binary will be placed in the `bin` folder
+  of this repo.
+- Build the UI extension. The UI extension will be packaged in the
+  `ui/extension.tar` file in this repo.
+
+There are specific targets that can be used to build each component:
+
+```bash
+make build-go # for building the Go project only
+make build-ui # for building the UI extension only
+```
+
+To build a docker image run one of the following commands:
+
+```bash
+make docker-build
+make docker-buildx
+```
+
+To build a docker image with custom namespace and tag run
 
 ```bash
 IMAGE_NAMESPACE="my.company.com/argoproj-labs" IMAGE_TAG="$(git rev-parse --abbrev-ref HEAD)" make docker-build
 ```
 
+#### Running
+
+```bash
+make run
+```
+
+#### Deploying
+
 Install in kubernetes cluster
 
 ```bash
-IMAGE_NAMESPACE="my.company.com/argoproj-labs" IMAGE_TAG="$(git rev-parse --abbrev-ref HEAD)" make deploy-local
+IMAGE_NAMESPACE="my.company.com/argoproj-labs" IMAGE_TAG="$(git rev-parse --abbrev-ref HEAD)" make deploy
 ```
+
+#### Releasing
+
+[1]: https://github.com/argoproj-labs/argocd-ephemeral-access/releases
+[2]: https://github.com/argoproj-labs/argocd-extension-installer

scripts/manifests-release.sh

@@ -16,9 +16,10 @@ if [ -z "$IMAGE_TAG" ]; then
     exit 1
 fi
 
-IMAGE_QUAY="quay.io/argoprojlabs/argocd-ephemeral-access:$IMAGE_TAG"
+IMAGE_NAMESPACE="${IMAGE_NAMESPACE:-quay.io/argoprojlabs/argocd-ephemeral-access}"
+IMAGE_FQN="$IMAGE_NAMESPACE:$IMAGE_TAG"
 
 $KUSTOMIZE version
-cd ${SRCROOT}/config/default && $KUSTOMIZE edit set image argoproj-labs/argocd-ephemeral-access=${IMAGE_QUAY}
+cd ${SRCROOT}/config/default && $KUSTOMIZE edit set image argoproj-labs/argocd-ephemeral-access=${IMAGE_FQN}
 echo "${AUTOGENMSG}" > "${SRCROOT}/install.yaml"
 $KUSTOMIZE build "${SRCROOT}/config/default" >> "${SRCROOT}/install.yaml"