From d945809669c19417aa6c9d0c75d7ebc242a75d3c Mon Sep 17 00:00:00 2001 From: Leonardo Luz Almeida Date: Thu, 17 Oct 2024 17:49:31 -0400 Subject: [PATCH 1/4] docs: add main project documentation in the README file Signed-off-by: Leonardo Luz Almeida --- Makefile | 32 ++++++++--------- README.md | 70 ++++++++++++++++++++++++++++++++++-- scripts/manifests-release.sh | 5 +-- 3 files changed, 84 insertions(+), 23 deletions(-) diff --git a/Makefile b/Makefile index fb9c771..95f7c21 100644 --- a/Makefile +++ b/Makefile @@ -113,7 +113,10 @@ run-backend: build goreman ## 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 diff --git a/README.md b/README.md index 445c25e..52dad97 100644 --- a/README.md +++ b/README.md @@ -1,17 +1,81 @@ # 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. + +## How it Works + +## Installing + +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. + +```bash +kubectl apply -f https://github.com/argoproj-labs/argocd-ephemeral-access/releases/download//install.yaml +``` + +This command will create a new namespace `argocd-ephemeral-access` and +deploy the necessary resources. + +## 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 diff --git a/scripts/manifests-release.sh b/scripts/manifests-release.sh index 76946d9..767df47 100755 --- a/scripts/manifests-release.sh +++ b/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" From ca83bba7f74652a8a90426b8642cc1c44af7e315 Mon Sep 17 00:00:00 2001 From: Leonardo Luz Almeida Date: Thu, 24 Oct 2024 12:03:23 -0700 Subject: [PATCH 2/4] add more docs Signed-off-by: Leonardo Luz Almeida --- 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. From 47acdb3ab81233ce3d60d3be0a44cf70a58082ac Mon Sep 17 00:00:00 2001 From: Leonardo Luz Almeida Date: Fri, 25 Oct 2024 22:47:39 -0400 Subject: [PATCH 3/4] more docs Signed-off-by: Leonardo Luz Almeida --- README.md | 80 +++++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 66 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index 5b05d46..7b2ac50 100644 --- a/README.md +++ b/README.md @@ -15,14 +15,16 @@ 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: +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 the Argo CD RBAC policies that will be -associated with an Argo CD `AppProject`. +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 @@ -52,7 +54,7 @@ spec: - group1 if: "true" ordinal: 1 - friendlyName: "Devops (AB)" + friendlyName: "Devops (Write)" ``` ### AccessRequest @@ -64,17 +66,19 @@ metadata: name: some-application-username namespace: ephemeral spec: + application: + name: ephemeral + namespace: argocd duration: '1m' - targetRoleName: ephemeral-write-access - appProject: - name: some-argocd-appproject - namespace: some-namespace + role: + friendlyName: Devops (Write) + ordinal: 1 + templateName: devops subject: username: some_user@fakedomain.com ``` - -## Installing +## Installation The ephemeral-access functionality is provided by the following components that needs to be configured properly to achieve the desired @@ -85,9 +89,13 @@ behaviour: - 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. -Check the latest release in the [releases page][1] and replace the -`DESIRED_VERSION` in the command below. +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//install.yaml @@ -96,6 +104,49 @@ kubectl apply -f https://github.com/argoproj-labs/argocd-ephemeral-access/releas 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 @@ -153,3 +204,4 @@ IMAGE_NAMESPACE="my.company.com/argoproj-labs" IMAGE_TAG="$(git rev-parse --abbr #### Releasing [1]: https://github.com/argoproj-labs/argocd-ephemeral-access/releases +[2]: https://github.com/argoproj-labs/argocd-extension-installer From 8fc7c4d850cffbcd22e6a33a173406159aff3118 Mon Sep 17 00:00:00 2001 From: Leonardo Luz Almeida Date: Thu, 7 Nov 2024 09:39:58 -0500 Subject: [PATCH 4/4] fix template vars Signed-off-by: Leonardo Luz Almeida --- README.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 7b2ac50..c1fd0ab 100644 --- a/README.md +++ b/README.md @@ -11,7 +11,7 @@ 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`. +associated with an `AppProjects` different than `default`. ## How it Works @@ -32,12 +32,12 @@ kind: RoleTemplate metadata: name: devops spec: - description: write permission in application {{.Application}} - name: "DevOps (Write)" + 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 + - p, {{.role}}, applications, sync, {{.project}}/{{.application}}, allow + - p, {{.role}}, applications, action/*, {{.project}}/{{.application}}, allow + - p, {{.role}}, applications, delete/*/Pod/*, {{.project}}/{{.application}}, allow ``` ### AccessBinding