ESO-83: Adds API reference guide and make target for generating it

Author: bharath-b-rh

Makefile

@@ -158,7 +158,7 @@ build: manifests generate fmt vet build-operator ## Build manager binary.
 
 .PHONY: run
 run: manifests generate fmt vet ## Run a controller from your host.
-	go run ./cmd/external-secrets-operator/main.go
+	go run ./cmd/external-secrets-operator/main.go --v=5
 
 # If you wish to build the manager image targeting other platforms you can use the --platform flag.
 # (i.e. docker build --platform linux/arm64). However, you must enable docker buildKit for it.
@@ -232,6 +232,7 @@ ENVTEST ?= $(LOCALBIN)/setup-envtest
 GOLANGCI_LINT = $(LOCALBIN)/golangci-lint
 YQ = $(LOCALBIN)/yq
 HELM ?= $(LOCALBIN)/helm
+REFERENCE_DOC_GENERATOR ?= $(LOCALBIN)/crd-ref-docs
 
 ## Tool Versions
 YQ_VERSION = v4.45.2
@@ -257,6 +258,10 @@ golangci-lint: $(GOLANGCI_LINT) ## Download golangci-lint locally if necessary.
 $(GOLANGCI_LINT): $(LOCALBIN)
 	$(call go-install-tool,$(GOLANGCI_LINT),github.com/golangci/golangci-lint/cmd/golangci-lint)
 
+.PHONY: crd-ref-docs
+crd-ref-docs: $(LOCALBIN) ## Download crd-ref-docs locally if necessary.
+	$(call go-install-tool,$(REFERENCE_DOC_GENERATOR),github.com/elastic/crd-ref-docs)
+
 # 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
 # $2 - package url which can be installed
@@ -369,9 +374,14 @@ verify: vet fmt golangci-lint verify-bindata verify-bindata-assets verify-genera
 
 ## update the relevant data based on new changes.
 .PHONY: update
-update: generate manifests update-operand-manifests update-bindata
+update: generate manifests update-operand-manifests update-bindata bundle docs
 
 ## checks for any uncommitted changes.
 .PHONY: check-git-diff
-check-git-diff: manifests generate update-operand-manifests bundle
+check-git-diff: update
 	./hack/check-git-diff-clean.sh
+
+## generate internal docs.
+.PHONY: docs
+docs: crd-ref-docs
+	$(REFERENCE_DOC_GENERATOR) --source-path=api/v1alpha1/ --renderer=markdown --config=hack/docs/config.yaml --output-path=docs/api_reference.md

README.md

@@ -1,28 +1,61 @@
-# external-secrets-operator for OpenShift
+# external-secrets-operator for Red Hat OpenShift
+This repository contains External Secrets Operator for Red Hat OpenShift. The operator runs in `external-secrets-operator` namespace.
+The External Secrets Operator provides the ability to deploy [`external-secrets`](https://github.com/openshift/external-secrets) using different configurations
 
-This repository contains External Secrets Operator designed for OpenShift. The operator runs in `external-secrets-operator` namespace.
-
-The operator based on operator-sdk framework to install external-secrets operator helm chart from https://github.com/openshift/external-secrets
+The External Secrets Operator for Red Hat OpenShift operates as a cluster-wide service to deploy and manage the external-secrets
+application. The external-secrets application integrates with external secrets management systems and performs secret fetching,
+refreshing, and provisioning within the cluster.
 
 ## Description
-// TODO(user): An in-depth paragraph about your project and overview of use
+Use the External Secrets Operator for Red Hat OpenShift to integrate external-secrets application with the
+OpenShift Container Platform cluster. The external-secrets application fetches secrets stored in the external providers such as
+AWS Secrets Manager, HashiCorp Vault, Google Secrets Manager, Azure Key Vault, IBM Cloud Secrets Manager,
+AWS Systems Manager Parameter Store and integrates them with Kubernetes in a secure manner.
+
+Using the External Secrets Operator ensures the following:
+- Decouples applications from the secret-lifecycle management.
+- Centralizes secret storage to support compliance requirements.
+- Enables secure and automated secret rotation.
+- Supports multi-cloud secret sourcing with fine-grained access control.
+- Centralizes and audits access control.
+
+The External Secrets Operator for Red Hat OpenShift uses the [`external-secrets`](https://github.com/openshift/external-secrets) helm charts
+to install application. The operator has three controllers to achieve the same:
+- `external_secrets_manager` controller: This is responsible for
+  * reconciling the `externalsecretsmanagers.openshift.operator.io` resource.
+  * providing the status of other controllers.
+- `external_secrets` controller: This is responsible for
+  * reconciling the `externalsecrets.openshift.operator.io` resource.
+  * installing and managing the `external-secrets` application based on the user defined configurations in `externalsecrets.openshift.operator.io` resource.
+  * reconciling the `externalsecretsmanagers.openshift.operator.io` resource for the global configurations and updates the `external-scerets` deployment accordingly.
+- `crd_annotator` controller:
+  * This is responsible for adding `cert-manager.io/inject-ca-from` annotation in the `external-secrets` provided CRDs.
+  * This is an optional controller, which will be activated only when [`cert-manager`](https://cert-manager.io/) is installed.
+  * When `cert-manager` is installed after External Secrets Operator installation, `external-secrets-operator-controller-manager` deployment must be restarted to activate the controller.
+
+The operator automatically creates a cluster-scoped `externalsecretsmanagers.openshift.operator.io` object named `cluster`.
+
+For more information about
+- `external-secrets-operator for Red Hat OpenShift`, refer to the [link](https://docs.redhat.com/en/documentation/openshift_container_platform/latest/html/security_and_compliance/external-secrets-operator-for-red-hat-openshift)
+- `external-secrets` application, refer to the [link](https://external-secrets.io/latest/).
+- `cert-manager Operator for Red Hat OpenShift`, refer to the [link](https://docs.redhat.com/en/documentation/openshift_container_platform/latest/html/security_and_compliance/cert-manager-operator-for-red-hat-openshift)
 
 ## Getting Started
 
 ### Prerequisites
-- go version v1.22.0+
+- go version 1.23.6+
 - docker version 17.03+.
-- kubectl version v1.11.3+.
-- Access to a Kubernetes v1.11.3+ cluster.
+- kubectl version v1.32.1+.
+- Access to a Kubernetes v1.32.1+ cluster.
 
 ### To Deploy on the cluster
 **Build and push your image to the location specified by `IMG`:**
 
 ```sh
-make docker-build docker-push IMG=<some-registry>/external-secrets-operator:tag
+make docker-build docker-push IMG=<some-registry>/external-secrets-operator:<tag>
 ```
 
-**NOTE:** This image ought to be published in the personal registry you specified.
+> **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.
 
@@ -35,10 +68,10 @@ make install
 **Deploy the Manager to the cluster with the image specified by `IMG`:**
 
 ```sh
-make deploy IMG=<some-registry>/external-secrets-operator:tag
+make deploy IMG=<some-registry>/external-secrets-operator:<tag>
 ```
 
-> **NOTE**: If you encounter RBAC errors, you may need to grant yourself cluster-admin
+> **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**
@@ -48,7 +81,7 @@ 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 that the samples has default values to test it out.
 
 ### To Uninstall
 **Delete the instances (CRs) from the cluster:**
@@ -79,7 +112,7 @@ Following are the steps to build the installer and distribute this project to us
 make build-installer IMG=<some-registry>/external-secrets-operator:tag
 ```
 
-NOTE: The makefile target mentioned above generates an 'install.yaml'
+> **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.
@@ -92,12 +125,20 @@ Users can just run kubectl apply -f <URL for YAML BUNDLE> to install the project
 kubectl apply -f https://raw.githubusercontent.com/<org>/external-secrets-operator/<tag or branch>/dist/install.yaml
 ```
 
+> **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)
+
 ## Contributing
-// TODO(user): Add detailed information on how you would like others to contribute to this project
+We welcome contributions from the community! To contribute:
 
-**NOTE:** Run `make help` for more information on all potential `make` targets
+- Fork this repository and create a new branch.
+- Make your changes and test them thoroughly.
+- Run make targets to verify the behavior.
+- Submit a Pull Request describing your changes and the motivation behind them.
+- Run make help to view all available development targets.
 
-More information can be found via the [Kubebuilder Documentation](https://book.kubebuilder.io/introduction.html)
+We appreciate issues, bug reports, feature requests, and feedback!
 
 ## License