From 6ec7f6c3c2cafcf75bfc6afd71132105dcceb571 Mon Sep 17 00:00:00 2001 From: Hamed Karbasi Date: Wed, 6 Dec 2023 15:08:53 +0330 Subject: [PATCH] Modify/readme (#27) * improved readme: first draft * improved readme: second draft * add badges to readme * fix badge in the readme * fix helm oci command --- README.md | 111 ++++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 95 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index a38d8e2..9e93e67 100644 --- a/README.md +++ b/README.md @@ -1,29 +1,100 @@ # S3 Operator +![License](https://img.shields.io/github/license/snapp-incubator/s3-operator) +![Test](https://github.com/snapp-incubator/s3-operator/actions/workflows/checks.yaml/badge.svg?branch=main) +![Release](https://github.com/snapp-incubator/s3-operator/actions/workflows/build-release.yaml/badge.svg) +![Tag](https://img.shields.io/github/v/tag/snapp-incubator/s3-operator?&logo=git) + ## Introduction -At Snapp! we are using Ceph object storage to have S3 for users, this operator is here -to make working with S3 easier and more fun. +The S3 Operator, an open-source endeavor, is crafted to streamline the management of S3 users and buckets within a Ceph cluster environment. It enhances efficiency and simplifies processes, rendering S3 usage on Ceph clusters more straightforward and user-friendly. + +## Features + +- S3 User Management +- Bucket Management +- Subuser Support +- Bucket policy Support +- Quota Management +- Webhook Integration +- E2E Testing +- Helm Chart and OLM Support + +## Installation + +### Using Makefile + +Deploy using a simple command: -## Design +```bash +make deploy +``` -For the detailed discription of the design and decisions, pelease see our [design-doc](docs/DESIGN.md). +### Using Helm -## Versioning +Deploy using Helm (version 3.8.0 or later), which supports OCI charts. To use the helm chart, edit the `values.yaml` file and set `controllerManagerConfig.configYaml` to your Ceph cluster configuration like [secret.yaml](config/manager/secret.yaml). -A new docker image will be created each time a tag starting with `v` is pushed to the main branch. +```bash +helm upgrade --install s3-operator oci://ghcr.io/snapp-incubator/s3-operator/helm-charts/s3-operator --version v0.3.5 +``` -For Helm charts, there's a relase job that will create a new -release [when a change is detected](https://helm.sh/docs/howto/chart_releaser_action/#github-actions-workflow) in -the `deploy/charts` directory. +### Using OLM + +All the operator releases are bundled and pushed to the [Snappcloud hub](https://github.com/snapp-incubator/snappcloud-hub) which is a hub for the catalog sources. Install using Operator Lifecycle Manager (OLM) by following these steps: + +1. Install [snappcloud hub catalog-source](https://github.com/snapp-incubator/snappcloud-hub/blob/main/catalog-source.yml) + +2. Override the `s3-operator-controller-manager-config-override` with your operator configuration. +3. Apply the subscription manifest as shown below: + + ```yaml + apiVersion: operators.coreos.com/v1alpha1 + kind: Subscription + metadata: + name: s3-operator + namespace: operators + spec: + channel: stable-v0 + installPlanApproval: Automatic + name: s3-operator + source: snappcloud-hub-catalog + sourceNamespace: openshift-marketplace + config: + resources: + limits: + cpu: 2 + memory: 2Gi + requests: + cpu: 1 + memory: 1Gi + volumes: + - name: config + secret: + items: + - key: config.yaml + path: config.yaml + secretName: s3-operator-controller-manager-config-override + volumeMounts: + - mountPath: /s3-operator/config/ + name: config + ``` + +## Usage and Documentation + +- CRD Examples: Located in the [samples](config/samples) folder. +- Detailed Documentation: Available on the [wiki](https://github.com/snapp-incubator/s3-operator/wiki). +- Design and Decision Insights: Refer to our [design doc](docs/DESIGN.md) for an in-depth understanding. + +## Versioning and Release + +A new docker image, bundle and helm chart will be created each time a tag starting with `v` is pushed to the main branch. ## Development -We follow [Kubebuilder](https://github.com/kubernetes-sigs/kubebuilder/blob/master/DESIGN.md#development) developement -principles, Specifically about testing in an environment similar to the real world and avoiding mocks as much as +We follow [Kubebuilder](https://github.com/kubernetes-sigs/kubebuilder/blob/master/DESIGN.md#development) development principles, Specifically about testing in an environment similar to the real world and avoiding mocks as much as possible. -For example, we don't mock RGW API. Instead, we use a simliar approach to +For example, we don't mock RGW API. Instead, we use a similar approach to what [go-ceph](https://github.com/ceph/go-ceph/) does. ### Building the testing image @@ -43,13 +114,13 @@ the chart run: make helm ``` -The chart will be created/updated in `deploy/charts/s3-operator` path +The chart will be created/updated in `charts/s3-operator` path ### Run locally -If you want to test the operator on your local environment, run the below instruction: +If you want to test the operator on your local environment, run the below instructions: -First setup the local ceph cluster: +First setup the local Ceph cluster: ```shell make setup-dev-env @@ -62,7 +133,7 @@ make run # Without webhook make run-with-webhook # With webhook ``` -At the end you can tear-down the operator and the ceph cluster: +At the end, you can tear down the operator and the Ceph cluster: ```shell make teardown-operator teardown-dev-env @@ -81,3 +152,11 @@ And to run the e2e tests with KUTTL performing the tests on a KIND cluster: ```shell kubectl-kuttl test ``` + +## Contributing + +Contributions are warmly welcomed. Feel free to submit issues or pull requests. + +## License + +This project is licensed under the [Apache License 2.0](https://github.com/snapp-incubator/s3-operator/blob/main/LICENSE).