Updated readme

CODE_OF_CONDUCT.md

@@ -0,0 +1,73 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, gender identity and expression, level of experience,
+education, socio-economic status, nationality, personal appearance, race,
+religion, or sexual identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+  advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at team-balance [at] zalando [dot] de. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
+
+[homepage]: https://www.contributor-covenant.org

CONTRIBUTING.md

@@ -0,0 +1,11 @@
+# Contributing
+
+## Pull requests only
+
+**DON'T** push to the main branch directly. Always use feature branches and let people discuss changes in pull requests.
+Pull requests should only be merged after all discussions have been concluded and at least 1 reviewer has given their
+**approval**.
+
+## Guidelines
+
+- **every change** needs a test

README.md

@@ -2,17 +2,31 @@
 
 # k8s-custom-configmap
 
-`k8s-custom-configmap` is a custom k8s config-map resource which includes JSON data validation and create 
+`k8s-custom-configmap` is a custom k8s config-map resource which includes JSON data validation and create
 versioned config-maps as requested by the application.
 
-## Components
+## Objective
+
+Kubernetes (K8s) config maps are widely employed for managing both runtime and static configurations. However, their
+flexibility can pose challenges when it comes to maintaining and modifying them while simultaneously ensuring the
+stability of dependent applications.
+
+The core objective of this tooling is to implement a well-defined opinionated safety net. This includes the following principles:
+
+1. Ad-hoc changes to the data in config-map directly within the cluster should undergo validation before being mounted in the pods.
+
+2. Config map data must undergo validation during the continuous integration (CI) process before releasing the config maps.
+
+3. Each deployment should maintain its own version of a config-map. In the event of faulty changes to the config-map, this approach facilitates the seamless redirection of traffic to the last known working state with minimal impact. Additionally, this practice provides us with the capability to conduct A/B testing for new configurations.
 
 ### Custom config-map resource
 
-The custom config-map resource is an extension of the native k8s config-map resource. The custom resource has an additional required field `schema` 
+The custom config-map resource is an extension of the native k8s config-map resource. The custom resource has an
+additional required field `schema`
 where the users can define the schema for the respective data in the config map.
 
 **Example**
+
 ```yaml
 apiVersion: "rcube.com/v1"
 kind: ConfigMapCustomResource
@@ -22,56 +36,125 @@ metadata:
 spec:
   config:
     data:
-        application-toggles-config.json: |
-        {
+      application-toggles-config.json: |
+      {
         "startNewFlow": true
-        }
+      }
     schema:
-        application-toggles-config.json: |
-        {
-            "type": "object",
-            "properties": {
-                "startNewFlow": {
-                    "type": "boolean"
-                }
-            },
-            "required": [
-              "startNewFlow"
-            ]
+      application-toggles-config.json: |
+      {
+        "type": "object",
+        "properties": {
+          "startNewFlow": {
+            "type": "boolean"
           }
+        },
+        "required": [
+          "startNewFlow"
+        ]
+      }
 ```
 
 ### config-operator
 
-The config-operator watches config-map CRD resources and k8s deployment resources. The operator is responsible for the below operations.
+The config-operator watches config-map CRD resources and k8s deployment resources. The operator is responsible for the
+below operations.
+
 - Validate custom config-map resources against the schema
 - Create config-maps from the custom resource.
 - Restricts direct changes to the native config-map resource.
 - Create versioned custom config-map resources for the applications.
 
 ## Features
 
+| Terminology                                                                | Explanation                              |
+|----------------------------------------------------------------------------|------------------------------------------|
+| operator, config-operator                                                  | Refers to the config-operator            |
+| config-map, native config-map, k8s config-map                              | Refers to the k8s config-map             |
+| custom config-map resource, configmapcustomresources, k8s-custom-configmap | Refers to the custom config-map resource |
+
 ### Validate config-map JSON data against JSON schema
 
+The config operator validates the `data` in the config against the JSON `schema` before generating the necessary config
+map. The `schema` adheres to the [Draft-4](https://json-schema.org/specification-links#draft-4) convention.
+![Validation flow](./docs/validation.png)
 
 ### Restricts direct changes to the native config-map resource
-The config-operator monitors the dependent resources (k8s native config-map) of the custom config-map and resets any manual changes made to the dependent resources. This is done to ensure that config-maps can only be updated through changes to the custom config-map resource, thereby ensuring proper validations.
 
+The config-operator monitors the dependent resources (k8s native config-map) of the custom config-map and resets any
+manual changes made to the dependent resources. This is done to ensure that config-maps can only be updated through
+changes to the custom config-map resource, thereby ensuring proper validations.
+
+![Rollback flow](./docs/rollback-config.png)
 
 ### config-map versioning
 
+The operator offers the flexibility to deploy versioned config-maps and seamlessly integrate them into the application.
+This is achieved by specifying the desired configuration version in the deployment manifest labels and appending the
+corresponding version suffix to the referenced config-map within the volumes.
+
+An example deployment requesting a versioned config-map.
+
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: nginx-deployment
+  namespace: local
+  labels:
+    app: nginx
+    config-map-version: "v1.1.10"
+spec:
+  replicas: 2
+  selector:
+    matchLabels:
+      app: nginx
+  template:
+    metadata:
+      labels:
+        app: nginx
+    spec:
+      containers:
+        - name: nginx
+          image: nginx:1.14.2
+          volumeMounts:
+            - name: my-config
+              mountPath: /etc/config
+          ports:
+            - containerPort: 80
+      volumes:
+        - name: my-config
+          configMap:
+            name: "my-config-v1.1.10"
+```
+
+In the above example the deployment requests for config-map `my-config-v1.1.10` (in the
+format `{config-map}-{config-map-version}`). The deployment manifest also
+has a `label` with key value `config-map-version: "v1.1.10"` which is the pre-requisite to trigger versioning.
+
+When the deployment manifest is applied, the operator retrieves the specified config-map, which in this case
+is `my-config-v1.1.10`, from the deployment resource. It then checks if there's an existing `ConfigMapCustomResource`
+with the name `my-config-v1.1.10`. If this custom resource doesn't exist, the operator duplicates
+the `ConfigMapCustomResource` from the pre-existing `my-config` (which should already be present in the namespace).
+Subsequently, the operator creates another custom resource with the name `my-config-v1.1.10`, resulting in the
+generation of a corresponding native config-map named `my-config-v1.1.10`.
+
+![Versioning](./docs/versioning.png)
 
 ## Installation
 
-Apply the [CRD]() in your k8s cluster
+Apply the [CRD](./install/cluster/configmapcustomresources.rcube.com-v1.yml) in your k8s cluster
+
 ```shell
 kubectl apply -f ./install/cluster/configmapcustomresources.rcube.com-v1.yml
 ```
 
-Deploy [config-operator]() in your k8s cluster.
+Deploy [config-operator](./install/cluster/Config-Operator.yaml) in your k8s cluster.
+
 ```shell
 kubectl apply -f ./install/cluster/Config-Operator.yaml
 ```
+
 **Note**: The operator would create a namespace `configs-operator` in your cluster.
 
 ## Usage
@@ -87,23 +170,23 @@ metadata:
 spec:
   config:
     data:
-        application-toggles-config.json: |
-        {
+      application-toggles-config.json: |
+      {
         "startNewFlow": true
-        }
+      }
     schema:
-        application-toggles-config.json: |
-        {
-            "type": "object",
-            "properties": {
-                "startNewFlow": {
-                    "type": "boolean"
-                }
-            },
-            "required": [
-              "startNewFlow"
-            ]
+      application-toggles-config.json: |
+      {
+        "type": "object",
+        "properties": {
+          "startNewFlow": {
+            "type": "boolean"
           }
+        },
+        "required": [
+          "startNewFlow"
+        ]
+      }
 ```
 
 This would create a config-map with the name `application-toggles-config` as below.
@@ -121,4 +204,12 @@ data:
     {
       "startNewFlow": true
     }
-```
+```
+## Example
+Apply this [example](./install/testing/app-deployment.yaml) to play with the custom config-map resource.
+
+## Getting help
+If you have questions, concerns, bug reports, etc., please file an issue in this repository's [Issue Tracker](https://github.com/rameshmalla/k8s-custom-configmap/issues).
+
+## Getting involved/Contributing
+To contribute, simply make a pull request and add a brief description (1-2 sentences) of your addition or change. For more details check the contribution [guidelines](./CONTRIBUTING.md).

build.gradle

@@ -39,13 +39,13 @@ dependencies {
 }
 
 tasks.register('copyCRDResource', Copy) {
-    dependsOn('compileJava')
     description = "Copy generated CRD from build folder to install directory"
     from layout.buildDirectory.dir("classes/java/main/META-INF/fabric8")
     include "*.yml"
     into './install/cluster'
 }
 
 tasks.named('test') {
+    dependsOn('copyCRDResource')
     useJUnitPlatform()
 }

install/cluster/Config-Operator.yaml

@@ -28,8 +28,8 @@ spec:
       serviceAccountName: configs-operator
       containers:
         - name: operator
-          image: configs-operator:version-2
-          imagePullPolicy: Never
+          image: malla/configs-operator:main
+          imagePullPolicy: IfNotPresent
           resources:
             requests:
               memory: 512Mi

install/testing/app-deployment.yaml

@@ -39,7 +39,6 @@ metadata:
   namespace: local
   labels:
     app: nginx
-    config-handler: "true"
     config-map-version: "master-10"
 spec:
   replicas: 2

src/main/java/com/rcube/configmap/operator/DeploymentController.java

@@ -20,7 +20,7 @@
 @Slf4j
 @Component
 @AllArgsConstructor
-@ControllerConfiguration(labelSelector = "config-handler")
+@ControllerConfiguration(labelSelector = "config-map-version")
 public class DeploymentController implements Reconciler<Deployment> {
 
     private final KubernetesClient kubernetesClient;