From 883917cd9b5c03788532d88744e3668d54d15884 Mon Sep 17 00:00:00 2001 From: Teddy Andrieux Date: Tue, 4 Nov 2025 16:15:59 +0000 Subject: [PATCH] docs: Update README and add other docs Signed-off-by: Teddy Andrieux --- CONTRIBUTING.md | 89 +++++++++++++++++++ DESIGN.md | 16 ++++ README.md | 78 +++++----------- .../crl-operator_v1alpha1_managedcrl.yaml | 8 +- 4 files changed, 135 insertions(+), 56 deletions(-) create mode 100644 CONTRIBUTING.md create mode 100644 DESIGN.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..2be0b69 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,89 @@ +# Contributing to the Project + +This document contains and defines the rules that have to be followed by any +contributor to the project, in order for any change to be merged into the +stable branches. + +More information can be found via the [Kubebuilder Documentation](https://book.kubebuilder.io/introduction.html) + +## Workflow Guidelines + +### Committing Guidelines + +No restrictions are placed at this time on individual commits passing in the +CI and/or maintaining full functionality of the repository. + +Commit messages should: + +* have a short (< 50 characters) summary as title +* contain more explanations, if necessary, in the body +* contain a reference to the issue being tackled in the body + +A commit message should *not* contain a reference to the issue in the title. + +### Pull Request Guidelines + +Pull requests should contain in their body a reference to the GitHub issue +being targeted by the changeset introduced. + +### Signing your work + +In order to contribute to the project, you must sign your work. By signing your +work, you certify to the statements set out in the Developer Certificate of +Origin ([developercertificate.org](https://developercertificate.org/)) + +Signing your work is easy. Just add the following line at the end of each of +your commit messages. You must use your real name in your sign-off. + +``` +Signed-off-by: Jane Doe +``` + +If your `user.name` and `user.email` are set in your git configs, you can sign +each commit automatically by using the `git commit -s` command. + +## Reporting an issue + +This project uses Github issues to manage the issues. + +Before creating an issue: + +1. upgrade the operator to the latest supported release version, and check whether your bug is still present, +2. ensure the operator version is supported by the PowerDNS version you are using, +3. have a look in the opened issues if your problem is already known/tracked, and possibly contribute to the thread with your own information. + +If none of the above was met, open an issue directly in Github, select the appropriate issue template and fill-in each section when applicable. + +## Development Setup + +### Prerequisites + +- go version v1.25.0+ +- docker +- kubectl +- make +- operator-sdk +- Docker (for building) +- Kind (for running e2e tests) + +We recommend using the [devcontainer](https://code.visualstudio.com/docs/devcontainers/containers) +provided here that come with all necessary tools pre-installed. + +## Testing & Linting + +Run linting: +```sh +make lint +``` + +Run tests: +```sh +make test +``` + +Run e2e tests: +```sh +make test-e2e +``` + +**NOTE:** Run `make help` for more information on all potential `make` targets diff --git a/DESIGN.md b/DESIGN.md new file mode 100644 index 0000000..375f1ef --- /dev/null +++ b/DESIGN.md @@ -0,0 +1,16 @@ +# Design + +## Goal + +The goal of the CRL Operator is to provide automated management of +Certificate Revocation Lists (CRLs) within Kubernetes environments. It aims to simplify the +deployment, updating, and maintenance of CRLs as custom resources as well as +patching ClusterIssuer/Issuer resources from cert-manager to include CRL distribution points. + +## Technical Details + +The CRL Operator is built using the Operator SDK and follows the +Kubernetes Operator pattern. It defines a Custom Resource Definition (CRD) for +ManagedCRL resources, which represent individual CRLs to be managed by the operator. The operator +watches for changes to ManagedCRL resources and performs the necessary actions to +ensure that the CRLs are correctly deployed and updated within the cluster. diff --git a/README.md b/README.md index cbf5ef2..9c9b8ec 100644 --- a/README.md +++ b/README.md @@ -1,16 +1,30 @@ +[![Post Merge](https://github.com/scality/crl-operator/actions/workflows/post-merge.yaml/badge.svg)](https://github.com/scality/crl-operator/actions/workflows/post-merge.yaml) + # crl-operator -// TODO(user): Add simple overview of use/purpose + +A Kubernetes operator for managing Certificate Revocation Lists (CRLs) in your cluster +based on ClusterIssuer/Issuer resources from cert-manager. ## Description -// TODO(user): An in-depth paragraph about your project and overview of use + +The CRL Operator provides automated management of Certificate Revocation Lists within +Kubernetes environments. It enables cluster administrators to deploy, update, and maintain +CRLs as custom resources. + +The CRL can also be exposed in a Pod via an NGINX server, allowing clients to retrieve +the CRL using HTTP requests internally using a Kubernetes Service or externally via +an Ingress resource (that can be managed by the operator as well). + +The operator handles CRL lifecycle management, periodic updates, and patch of ClusterIssuer/Issuer +resources from cert-manager to include CRL distribution points. ## Getting Started ### Prerequisites - go version v1.25.0+ -- docker version 17.03+. -- kubectl version v1.11.3+. -- Access to a Kubernetes v1.11.3+ cluster. +- docker +- kubectl +- Access to a Kubernetes v1.32+ cluster ### To Deploy on the cluster **Build and push your image to the location specified by `IMG`:** @@ -21,7 +35,7 @@ make docker-build docker-push IMG=/crl-operator:tag **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. +Make sure you have the proper permission to the registry if the above commands don't work. **Install the CRDs into the cluster:** @@ -45,9 +59,10 @@ You can apply the samples (examples) from the config/sample: kubectl apply -k config/samples/ ``` ->**NOTE**: Ensure that the samples has default values to test it out. +>**NOTE**: Ensure to update the sample CRs to fit your needs before applying them to the cluster. ### To Uninstall + **Delete the instances (CRs) from the cluster:** ```sh @@ -66,56 +81,9 @@ make uninstall make undeploy ``` -## Project Distribution - -Following the options to release and provide this solution to the users. - -### By providing a bundle with all YAML files - -1. Build the installer for the image built and published in the registry: - -```sh -make build-installer IMG=/crl-operator: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//crl-operator//dist/install.yaml -``` - -### By providing a Helm Chart - -1. Build the chart using the optional helm plugin - -```sh -operator-sdk edit --plugins=helm/v1-alpha -``` - -2. See that a chart was generated under 'dist/chart', and users -can obtain this solution from there. - -**NOTE:** If you change the project, you need to update the Helm Chart -using the same command above to sync the latest changes. Furthermore, -if you create webhooks, you need to use the above command with -the '--force' flag and manually ensure that any custom configuration -previously added to 'dist/chart/values.yaml' or 'dist/chart/manager/manager.yaml' -is manually re-applied afterwards. - ## 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) +See [contributing](CONTRIBUTING.md) for details. ## License diff --git a/config/samples/crl-operator_v1alpha1_managedcrl.yaml b/config/samples/crl-operator_v1alpha1_managedcrl.yaml index b88134e..7f858f6 100644 --- a/config/samples/crl-operator_v1alpha1_managedcrl.yaml +++ b/config/samples/crl-operator_v1alpha1_managedcrl.yaml @@ -6,4 +6,10 @@ metadata: app.kubernetes.io/managed-by: kustomize name: managedcrl-sample spec: - # TODO(user): Add fields here + issuerRef: + name: my-ca-issuer + kind: ClusterIssuer + expose: + enabled: true + ingress: + host: crl.example.com