Skip to content

Commit

Permalink
fix: Add contribution documenation to project
Browse files Browse the repository at this point in the history 
Signed-off-by: Mateus Oliveira <[email protected]>
  • Loading branch information
@mateusoliveira43
mateusoliveira43 committed Mar 12, 2024
1 parent 8d07f9f commit 3ad00c8
Show file tree
Hide file tree
Showing 11 changed files with 266 additions and 265 deletions.
2 changes: 2 additions & 0 deletions .github/workflows/ci.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -68,3 +68,5 @@ jobs:

- name: Check all files format
run: make ec

# TODO do not allow overwrite of production image
3 changes: 3 additions & 0 deletions .gitignore
View file
Original file line number Diff line number Diff line change
Expand Up @@ -26,3 +26,6 @@ go.work
*.swp
*.swo
*~

# oadp-nac specifics
dev/*
25 changes: 19 additions & 6 deletions Makefile
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
290 changes: 36 additions & 254 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -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
```
<!-- TODO add Official documentation link once it is created -->

**Create OAuth file**
```sh
$ cat > oauth-nacuser.yaml <<EOF
apiVersion: config.openshift.io/v1
kind: OAuth
metadata:
name: cluster
spec:
identityProviders:
- name: oadp_nac_test_provider
mappingMethod: claim
type: HTPasswd
htpasswd:
fileData:
name: htpass-secret
EOF
```
**Apply the OAuth file to the cluster:**
```sh
$ oc apply -f oauth-nacuser.yaml
```

### Assigning NAC permissions to the user

Ensure you have appropriate Cluster Role available in youc cluster:
```shell
$ oc apply -f config/rbac/nonadminbackup_editor_role.yaml
```

**Create Role Binding for our test user within nac-testing namespace:**
**NOTE:** There could be also a ClusterRoleBinding for the nacuser or one of the groups
to which nacuser belongs to easy administrative tasks and allow use of NAC for wider audience. Please see next paragraph.
```sh
$ cat > nacuser-rolebinding.yaml <<EOF
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
name: nacuser-nonadminbackup
namespace: nac-testing
subjects:
- kind: User
name: nacuser
roleRef:
kind: ClusterRole
name: nonadminbackup-editor-role
apiGroup: rbac.authorization.k8s.io
EOF
```
**Apply the Cluster Role Binding file to the cluster:**
```sh
$ oc apply -f nacuser-rolebinding.yaml
```
Documentation in this repository are considered unofficial and for development purposes only.

**Alternatively Create Cluster Role Binding for our test user within nac-testing namespace:**
```sh
$ cat > nacuser-clusterrolebinding.yaml <<EOF
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
name: nacuser-nonadminbackup-cluster
subjects:
- kind: User
name: nacuser
roleRef:
kind: ClusterRole
name: nonadminbackup-editor-role
apiGroup: rbac.authorization.k8s.io
EOF
```
**Apply the Cluster Role Binding file to the cluster:**
```sh
$ oc apply -f nacuser-clusterrolebinding.yaml
```

### To Deploy on the cluster
**Build and push your image to the location specified by `IMG`:**

```sh
# Example to build with podman
export NAC_TAG="v0.0.1"
export IMG_REGISTRY="quay.io/<USER>/oadp-nac"
## Description

make docker-build docker-push IMG="${IMG_REGISTRY}:${NAC_REV}" CONTAINER_TOOL=podman
```
This open source controller adds the non admin feature to [OADP operator](https://github.com/openshift/oadp-operator). With it, cluster admins can configure which namespaces non admin users can backup/restore.

**NOTE:** This image ought to be published in the personal registry you specified.
And it is required to have access to pull the image from the working environment.
Make sure you have the proper permission to the registry if the above commands don’t work.
## Getting Started

**Install the CRDs into the cluster:**
### Prerequisites
- go version v1.21.0+
- oc
- Access to a OpenShift cluster
- [OADP operator](https://github.com/openshift/oadp-operator) installed in the cluster

```sh
make install
```
<!-- TODO update in future, probably will need to use unsupported override in DPA -->

**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/<USER>/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
Expand All @@ -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=<some-registry>/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 <URL for YAML BUNDLE> to install the project, i.e.:

```sh
kubectl apply -f https://raw.githubusercontent.com/<org>/oadp-nac/<tag or branch>/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).
Loading

0 comments on commit 3ad00c8

Please sign in to comment.