From 3ad00c888a5f85312eb46da382f8c116b8edcc30 Mon Sep 17 00:00:00 2001 From: Mateus Oliveira Date: Tue, 12 Mar 2024 14:09:47 -0300 Subject: [PATCH] fix: Add contribution documenation to project Signed-off-by: Mateus Oliveira --- .github/workflows/ci.yml | 2 + .gitignore | 3 + Makefile | 25 +- README.md | 290 +++--------------- config/default/kustomization.yaml | 2 +- config/manager/kustomization.yaml | 4 +- config/rbac/kustomization.yaml | 1 - docs/CONTRIBUTING.md | 89 ++++++ docs/architecture.md | 23 ++ docs/non_admin_user.md | 90 ++++++ .../controller/nonadminbackup_controller.go | 2 +- 11 files changed, 266 insertions(+), 265 deletions(-) create mode 100644 docs/CONTRIBUTING.md create mode 100644 docs/architecture.md create mode 100644 docs/non_admin_user.md diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index ba4176f..04cf21e 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -68,3 +68,5 @@ jobs: - name: Check all files format run: make ec + + # TODO do not allow overwrite of production image diff --git a/.gitignore b/.gitignore index 7a7feec..e483552 100644 --- a/.gitignore +++ b/.gitignore @@ -26,3 +26,6 @@ go.work *.swp *.swo *~ + +# oadp-nac specifics +dev/* diff --git a/Makefile b/Makefile index 5195038..d53ec1d 100644 --- a/Makefile +++ b/Makefile @@ -116,14 +116,11 @@ docker-buildx: ## Build and push docker image for the manager for cross-platform rm Dockerfile.cross .PHONY: build-installer +build-installer: DIR?=dist build-installer: manifests generate kustomize ## Generate a consolidated YAML with CRDs and deployment. - mkdir -p dist - @if [ -d "config/crd" ]; then \ - $(KUSTOMIZE) build config/crd > dist/install.yaml; \ - fi - echo "---" >> dist/install.yaml # Add a document separator before appending + mkdir -p $(DIR) cd config/manager && $(KUSTOMIZE) edit set image controller=${IMG} - $(KUSTOMIZE) build config/default >> dist/install.yaml + $(KUSTOMIZE) build config/default > $(DIR)/install.yaml ##@ Deployment @@ -204,7 +201,11 @@ endef ##@ oadp-nac specifics +## Tool Binaries +OC_CLI ?= $(shell which oc) EC ?= $(LOCALBIN)/ec-$(EC_VERSION) + +## Tool Versions EC_VERSION ?= 2.8.0 .PHONY: editorconfig @@ -241,3 +242,15 @@ check-manifests: manifests ## Check if 'make manifests' was run. .PHONY: ec ec: editorconfig ## Run file formatter checks against all project's files. $(EC) + +.PHONY: deploy-dev +deploy-dev: DEV_IMG?=ttl.sh/oadp-nac-controller-$(shell git rev-parse --short HEAD)-$(shell echo $$RANDOM):1h +deploy-dev: ## Build and push development controller image from current branch and deploy development controller to cluster + PROD_IMG=$(IMG) IMG=$(DEV_IMG) DIR=dev make docker-build docker-push build-installer + IMG=$(PROD_IMG) cd config/manager && $(KUSTOMIZE) edit set image controller=${IMG} && cd - + $(OC_CLI) apply -f dev/install.yaml + +# TODO prior delete CR instances, to avoid finalizers problem +.PHONY: undeploy-dev +undeploy-dev: ## Undeploy development controller from cluster + $(OC_CLI) delete -f dev/install.yaml diff --git a/README.md b/README.md index 6aa28eb..389111f 100644 --- a/README.md +++ b/README.md @@ -1,146 +1,41 @@ -# oadp-nac -// TODO(user): Add simple overview of use/purpose +# OADP NAC -## Description -// Non Admin controller +Non Admin Controller -## Getting Started +[![Continuos Integration](https://github.com/migtools/oadp-non-admin/actions/workflows/ci.yml/badge.svg)](https://github.com/migtools/oadp-non-admin/actions/workflows/ci.yml) -### Prerequisites -- go version v1.21.0+ -- docker version 17.03+. -- kubectl version v1.11.3+. -- Access to a Kubernetes v1.11.3+ cluster. - -### Creating Non Admin User on the OCP cluster -**Create sample Namespace:** -```sh -$ oc create ns nac-testing -``` - -**Create sample identity file:** -```sh -# Using user nacuser with sample pass -$ htpasswd -c -B -b ./users_file.htpasswd nacuser Mypassw0rd -``` - -**Create secret from the previously created htpasswd file in OpenShift** -```sh -$ oc create secret generic htpass-secret --from-file=htpasswd=./users_file.htpasswd -n openshift-config -``` + -**Create OAuth file** -```sh -$ cat > oauth-nacuser.yaml < nacuser-rolebinding.yaml < nacuser-clusterrolebinding.yaml < -**Deploy the Manager to the cluster with the image specified by `IMG`:** +### Install +To install latest OADP NAC in `oadp-nac-system` namespace in your cluster, run ```sh -export NAC_TAG="v0.0.1" -export IMG_REGISTRY="quay.io//oadp-nac" - -make deploy IMG="${IMG_REGISTRY}:${NAC_REV}" +make deploy ``` -**Check your deployment** - +To check the deployment, run ```sh oc get all -n oadp-nac-system ``` -Result: -```sh +you should have an output similar to this: +``` NAME READY STATUS RESTARTS AGE pod/oadp-nac-controller-manager-74bbf4577b-nssw4 2/2 Running 0 3m7s @@ -152,156 +47,43 @@ deployment.apps/oadp-nac-controller-manager 1/1 1 1 3 NAME DESIRED CURRENT READY AGE replicaset.apps/oadp-nac-controller-manager-74bbf4577b 1 1 1 3m7s - ``` -> **NOTE**: If you encounter RBAC errors, you may need to grant yourself cluster-admin -privileges or be logged in as admin. - -**Create instances of your solution** -You can apply the samples (examples) from the config/sample: +### Testing +To test NAC functionality, create non admin CRs. For example, run ```sh -kubectl apply -k config/samples/ +oc apply -f config/samples/nac_v1alpha1_nonadminbackup.yaml ``` ->**NOTE**: Ensure that the samples has default values to test it out. - -### To Uninstall -**Delete the instances (CRs) from the cluster:** - -```sh -kubectl delete -k config/samples/ -``` +To create a non admin user to test NAC, check [non admin user documentation](docs/non_admin_user.md). -**Delete the APIs(CRDs) from the cluster:** - -```sh -make uninstall -``` - -**UnDeploy the controller from the cluster:** +### Uninstall +To uninstall the previously installed OADP NAC in your cluster, run ```sh make undeploy ``` -## Project Distribution - -Following are the steps to build the installer and distribute this project to users. - -1. Build the installer for the image built and published in the registry: - -```sh -make build-installer IMG=/oadp-nac:tag -``` - -NOTE: The makefile target mentioned above generates an 'install.yaml' -file in the dist directory. This file contains all the resources built -with Kustomize, which are necessary to install this project without -its dependencies. - -2. Using the installer - -Users can just run kubectl apply -f to install the project, i.e.: - -```sh -kubectl apply -f https://raw.githubusercontent.com//oadp-nac//dist/install.yaml -``` +> **NOTE:** make sure there are no running instances of CRDs. Finalizers in those objects can fail the `undeploy` command. ## Contributing -// TODO(user): Add detailed information on how you would like others to contribute to this project -**NOTE:** Run `make help` for more information on all potential `make` targets - -More information can be found via the [Kubebuilder Documentation](https://book.kubebuilder.io/introduction.html) +Please check our [contributing documentation](docs/CONTRIBUTING.md) to propose changes to the repository. ## Architecture -The project was generated using kubebuilder version `v3.14.0`, running the following commands -```sh -kubebuilder init \ - --plugins go.kubebuilder.io/v4 \ - --project-version 3 \ - --project-name=oadp-nac \ - --repo=github.com/migtools/oadp-non-admin \ - --domain=oadp.openshift.io -kubebuilder create api \ - --plugins go.kubebuilder.io/v4 \ - --group nac \ - --version v1alpha1 \ - --kind NonAdminBackup \ - --resource --controller -make manifests -``` -> **NOTE:** The information about plugin and project version, as well as project name, repo and domain, is stored in [PROJECT](PROJECT) file - -To upgrade kubebuilder version, create kubebuilder structure using the current kubebuilder version and the upgrade version, using the same commands presented earlier, in two different folders. Then generate a `diff` file from the two folders and apply changes to project code. - -## Quality - -The quality checks of the project are reproduced by the continuos integration (CI) pipeline of the project. CI configuration in [`.github/workflows/ci.yml`](.github/workflows/ci.yml) file. - -To run all checks locally, run `make ci`. - -### Tests - -To run unit and integration tests, run -```sh -make simulation-test -``` - -TODO report, coverage and tests information - -### Linters and code formatters - -To run Go linters and check Go code format, run -```sh -make lint -``` - -To fix Go linters issues and format Go code, run -```sh -make lint-fix -``` - -Go linters and Go code formatters configuration in [`.golangci.yml`](.golangci.yml) file. - -To check all files format, run -```sh -make ec -``` - -Files format configuration in [`.editorconfig`](.editorconfig) file. +For a better understanding of the project, check our [architecture documentation](docs/architecture.md). -### Container file linter - -To run container file linter, run -```sh -make hadolint -``` +## OADP version compatibility -### Code generation +OADP NAC needs OADP operator to work. The relationship between compatible versions is presented below. -To check if project code was generated, run -```sh -make check-generate -make check-manifests -``` +| NAC version | OADP version | +|-------------|--------------| +| master | master | +| v0.1.0 | v1.4.0 | ## License -Copyright 2024. - -Licensed under the Apache License, Version 2.0 (the "License"); -you may not use this file except in compliance with the License. -You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - -Unless required by applicable law or agreed to in writing, software -distributed under the License is distributed on an "AS IS" BASIS, -WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -See the License for the specific language governing permissions and -limitations under the License. - +This repository is licensed under the terms of [Apache License Version 2.0](LICENSE). diff --git a/config/default/kustomization.yaml b/config/default/kustomization.yaml index dc2c7d2..fad9d72 100644 --- a/config/default/kustomization.yaml +++ b/config/default/kustomization.yaml @@ -1,5 +1,5 @@ # Adds namespace to all resources. -namespace: oadp-nac-system +namespace: oadp-nac-system # TODO change # Value of this field is prepended to the # names of all resources, e.g. a deployment named diff --git a/config/manager/kustomization.yaml b/config/manager/kustomization.yaml index 8ff4f65..ad13e96 100644 --- a/config/manager/kustomization.yaml +++ b/config/manager/kustomization.yaml @@ -4,5 +4,5 @@ apiVersion: kustomize.config.k8s.io/v1beta1 kind: Kustomization images: - name: controller - newName: quay.io/migi/oadp-nac-operator - newTag: v0.0.37 + newName: controller + newTag: latest diff --git a/config/rbac/kustomization.yaml b/config/rbac/kustomization.yaml index 5f1355c..731832a 100644 --- a/config/rbac/kustomization.yaml +++ b/config/rbac/kustomization.yaml @@ -9,7 +9,6 @@ resources: - role_binding.yaml - leader_election_role.yaml - leader_election_role_binding.yaml -- nonadminbackup_editor_role.yaml # Comment the following 4 lines if you want to disable # the auth proxy (https://github.com/brancz/kube-rbac-proxy) # which protects your /metrics endpoint. diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md new file mode 100644 index 0000000..2e96bff --- /dev/null +++ b/docs/CONTRIBUTING.md @@ -0,0 +1,89 @@ +# Contributing + +To contribute to the project, please first check if a issue/pull request does not already exist regarding the changes you are suggesting. If a issue exists, please link it to the pull request you are creating. + +If your changes involve controller logic, please test it prior to submitting, by following [install from source section](#install-from-source). + +If your changes involve code, please check [code quality and standardization section](#code-quality-and-standardization). + +If you are upgrading project's kubebuilder version, please follow [upgrade kubebuilder version section](#upgrade-kubebuilder-version). + +> **NOTE:** Run `make help` for more information on all potential `make` targets + +## Prerequisites +- go version v1.21.0+ +- docker version 17.03+ +- oc +- Access to a OpenShift cluster +- [OADP operator](https://github.com/openshift/oadp-operator) installed in the cluster + +## Install from source + +To install OADP NAC from current branch in `oadp-nac-system` namespace in your cluster, run +```sh +make deploy-dev +``` + +> **NOTE:** You can use a different development image by running `export DEV_IMG=quay.io/user/image-name:tag` prior to `deploy-dev` command. + +To create a non admin user to test NAC, check [non admin user documentation](non_admin_user.md). + +To uninstall the previously installed OADP NAC in your cluster, run +```sh +make deploy-dev +``` + +## Code quality and standardization + +The quality/standardization checks of the project are reproduced by the continuos integration (CI) pipeline of the project. CI configuration in [`.github/workflows/ci.yml`](../.github/workflows/ci.yml) file. + +To run all checks locally, run `make ci`. + +### Tests + +To run unit and integration tests, run +```sh +make simulation-test +``` + +TODO report, coverage and tests information + +### Linters and code formatters + +To run Go linters and check Go code format, run +```sh +make lint +``` + +To fix Go linters issues and format Go code, run +```sh +make lint-fix +``` + +Go linters and Go code formatters configuration in [`.golangci.yml`](../.golangci.yml) file. + +To check all files format, run +```sh +make ec +``` + +Files format configuration in [`.editorconfig`](../.editorconfig) file. + +### Container file linter + +To run container file linter, run +```sh +make hadolint +``` + +### Code generation + +To check if project code was generated, run +```sh +make check-generate +make check-manifests +``` + +## Upgrade kubebuilder version + +To upgrade kubebuilder version, create kubebuilder structure using the current kubebuilder version and the upgrade version, using the same commands presented in [kubebuilder architecture documentation](architecture.md#kubebuilder), in two different folders. Then generate a `diff` file from the two folders and apply changes to project code. diff --git a/docs/architecture.md b/docs/architecture.md new file mode 100644 index 0000000..4d08fed --- /dev/null +++ b/docs/architecture.md @@ -0,0 +1,23 @@ +# Architecture + +## Kubebuilder + +The project was generated using kubebuilder version `v3.14.0`, running the following commands +```sh +kubebuilder init \ + --plugins go.kubebuilder.io/v4 \ + --project-version 3 \ + --project-name=oadp-nac \ + --repo=github.com/migtools/oadp-non-admin \ + --domain=oadp.openshift.io +kubebuilder create api \ + --plugins go.kubebuilder.io/v4 \ + --group nac \ + --version v1alpha1 \ + --kind NonAdminBackup \ + --resource --controller +make manifests +``` +> **NOTE:** The information about plugin and project version, as well as project name, repo and domain, is stored in [PROJECT](PROJECT) file + +> **NOTE:** More information can be found via the [Kubebuilder Documentation](https://book.kubebuilder.io/introduction.html) diff --git a/docs/non_admin_user.md b/docs/non_admin_user.md new file mode 100644 index 0000000..986f09d --- /dev/null +++ b/docs/non_admin_user.md @@ -0,0 +1,90 @@ +# Creating non admin user on a OpenShift cluster + +Check your cloud provider documentation for more detailed information. + +## AWS + +**Create sample identity file:** +```sh +# Using user nacuser with sample pass +$ htpasswd -c -B -b ./users_file.htpasswd nacuser Mypassw0rd +``` + +**Create secret from the previously created htpasswd file in OpenShift** +```sh +$ oc create secret generic htpass-secret --from-file=htpasswd=./users_file.htpasswd -n openshift-config +``` + +**Create OAuth file** +```sh +$ cat > oauth-nacuser.yaml < nacuser-rolebinding.yaml < nacuser-clusterrolebinding.yaml <