Merge pull request #28 from manzil-infinity180/webhook-helm-docs

wip: Webhook helm docs

Author: manzil-infinity180

Readme.md

@@ -1,55 +1,92 @@
-## The Architecture of Controllers
-Since controllers are in charge of meeting the desired state of the resources in Kubernetes, they somehow need to be informed about the changes on the resources and perform certain operations if needed. For this, controllers follow a special architecture to
+<div align="center">
+<p align="center">
+<img width="960" height="309" alt="final-k8s" src="https://github.com/user-attachments/assets/e5ef535e-a07a-4cd5-9fbd-926a0c62cf39" />
+</p>
 
-1) observe the resources,
-2) inform any events (updating, deleting, adding) done on the resources,
-3) keep a local cache to decrease the load on API Server,
-4) keep a work queue to pick up events,
-5) run workers to perform reconciliation on resources picked up from work queue.
+[![Watch the demo video](https://github.com/user-attachments/assets/4ba51960-d9d2-4ac4-9272-c4ee3c5cf262)](https://www.youtube.com/watch?v=mAr62XBVbmg)
+</div>
 
- <a href="https://www.nakamasato.com/kubernetes-training/kubernetes-operator/client-go/informer/" >
-    <h4 class="text-yellow-300 text-lg">Ref: Official Docs</h4>
-    </a>
- <a href="https://github.com/kubernetes/community/blob/8cafef897a22026d42f5e5bb3f104febe7e29830/contributors/devel/controllers.md">
-    <h4 class="text-yellow-300 text-lg">Writing Controllers (Imp)</h4>
-    </a>
+> 📽️ Click the image above to watch the full 25-minute walkthrough on YouTube.  
+> It includes setup, explanation, CVE scan demo, and auto resource creation.
 
-# Factory & Informers
 
-![image](https://github.com/user-attachments/assets/bb09fdaf-a1d8-4f9b-bfd4-a7914ebe6eba)
+# 🛡️ Kubernetes CVE Scanner with Custom Controller + Admission Webhook
 
-# Single Informer
+This project includes a **Kubernetes custom controller** that:
+- Automatically creates **Services** and **Ingresses** for every `Deployment`.
+- Integrates with a **Validating Admission Webhook** to scan container images using **Trivy**.
+- Optionally allows skipping CVE checks with an environment variable.
 
-![image](https://github.com/user-attachments/assets/bfc1720a-aab4-4595-bb4b-9559a3e98d74)
+---
 
-![image](https://github.com/user-attachments/assets/1af2d969-5b93-40f4-b375-219342c16041)
+## 🚀 Installation Guide
 
+### 1️⃣ Create a Kubernetes Cluster
 
-[//]: # (https://github.com/user-attachments/assets/851d2b2b-d268-4894-a15a-dbe8b501b3cc)
+Make sure you have a running Kubernetes cluster (like KinD, Minikube, or EKS).
 
-## Definition : Informer
 
-Informer monitors the changes of target resource. An informer is created for each of the target resources if you need to handle multiple resources (e.g. podInformer, deploymentInformer).
+### 2️⃣ Install `cert-manager`
 
+```bash
+kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.18.2/cert-manager.yaml
+```
+This will install the necessary CRDs and controllers for certificate management.
 
+### 3️⃣ Deploy Trivy as a Service
+```bash
+kubectl apply -f docs/trivy-manifest/deployment.yml
+kubectl apply -f docs/trivy-manifest/service.yml
+```
+Trivy will act as the backend scanner for your webhook.
+> Note: We are running using trivy client you can see the command [here](https://github.com/aquasecurity/trivy/discussions/2119)
 
-```md
-1) Initialize the Controller
-	* The NewController function sets up the Kubernetes controller with a work queue, informer, and WebSocket connection.
-	* It listens for Deployment events (Add, Update, Delete) and enqueues them.
+### 4️⃣ Create Cluster Role & Bindings
+* Grant required permissions for:
+    - Deployments
+    - Services 
+    - Secrets 
+    - Ingresses 
+    - ValidatingWebhookConfigurations
+```bash
+kubectl apply -f manifest/cluster-permission.yaml
 
-2) Run the Controller
-	* The Run method waits for cache synchronization and starts the worker loop.
-	* It continuously processes events from the work queue.
+```
 
-3) Process Deployment Events
-	* The processItem method retrieves Deployment events from the queue and determines the necessary action.
-	* It fetches the Deployment details and handles errors, deletions, and updates.
+### 5️⃣ Deploy Controller + Webhook
+* This manifest includes:
+    - Namespace
+    - Deployment
+    - Service
+    - TLS Issuers + Certs
+    - ValidatingWebhookConfiguration
 
-4) Handle Deployment Changes
-	* `handleAdd`, `handleUpdate`, and `handleDel` respond to Deployment changes.
-	* Updates track Replica count and Image changes and send logs via WebSocket.
+```ts
+kubectl apply -f manifest/k8s-controller-webhook.yaml
+```
+### 6️⃣ Test Webhook
+```ts
+# contain cve
+$ kubectl apply -f manifest/webhook-example/initContainerDeployment.yml
+# look for first time it might fail (look at the logs of the application (k8s-custom-controller) and 
+# see if they return a long list of CVE -> then start creating again (Working on to optimize) 
 
-5) Send Updates via WebSocket
-	* The updateLogs function logs and sends JSON messages about Deployment changes.
-	* The WebSocket connection ensures real-time updates for external systems.
+# pure zero cve (does not contain cve) 
+$ kubectl apply -f manifest/webhook-example/pureZeroCVE.yml
+
+# contain cve but bypass (i mean create the deployment even after having CVE) 
+# due to this parameter `name: BYPASS_CVE_DENIED` set as yes or true
+$ kubectl apply -f manifest/webhook-example/ZeroInitCVE.yml
+```
+> Todo:
+> Better docs and guide
+
+<p align="center">
+<img width="450" height="450" alt="image" src="https://github.com/user-attachments/assets/92fe17a5-bffe-469d-beb3-0769bb85d4a5" />
+</p>
+
+## Author
+
+Built with 💙 by **Rahul Vishwakarma**
+
+> Happy Scan-ing!

chart/templates/cert-manager.yaml

@@ -0,0 +1,24 @@
+# for running this you need to have cert-manager install on your cluster
+# Installation: https://cert-manager.io/docs/installation/
+---
+apiVersion: cert-manager.io/v1
+kind: Issuer
+metadata:
+  name: selfsigned
+  namespace: {{ .Values.image.namespace }}
+spec:
+  selfSigned: {}
+---
+apiVersion: cert-manager.io/v1
+kind: Certificate
+metadata:
+  name: "{{ .Values.webhook.name }}-certificate" #webhook1-certificate
+  namespace: {{ .Values.image.namespace }}
+spec:
+  secretName: "{{ .Chart.Name }}-tls"            # Secret mounted in deployment
+  dnsNames:
+    - "{{ include "chart.fullname" . }}.{{ .Values.image.namespace }}.svc"
+    - "{{ include "chart.fullname" . }}.{{ .Values.image.namespace }}.svc.cluster.local"
+  issuerRef:
+    name: selfsigned
+---

chart/templates/clusterrole.yaml

@@ -5,10 +5,16 @@ metadata:
 rules:
   - apiGroups: ["apps"]
     resources: ["deployments"]
-    verbs: ["get", "list", "watch"]
+    verbs: [ "get", "list", "watch", "create", "update", "patch" ]
   - apiGroups: [""]
     resources: ["services"]
     verbs: ["get", "list", "watch", "create", "update"]
   - apiGroups: ["networking.k8s.io"]
     resources: ["ingresses"]
     verbs: ["get", "list", "watch", "create", "update"]
+  - apiGroups: [ "admissionregistration.k8s.io" ]
+    resources: [ "validatingwebhookconfigurations" ]
+    verbs: [ "get", "list", "watch", "create", "update", "patch" ]
+  - apiGroups: [ "" ]
+    resources: [ "secrets" ]
+    verbs: [ "get", "list", "watch", "create", "update", "patch" ]

chart/templates/clusterrolebinding.yaml

@@ -4,9 +4,9 @@ metadata:
   name: {{ include "chart.fullname" . }}
 subjects:
   - kind: ServiceAccount
-    name: {{ include "chart.serviceAccountName" . }}
-    namespace: {{ .Release.Namespace }}
+    name: default
+    namespace: {{ .Values.image.namespace }}
 roleRef:
   kind: ClusterRole
   name: {{ include "chart.fullname" . }}
-  apiGroup: rbac.authorization.k8s.io
+  apiGroup: rbac.authorization.k8s.io

chart/templates/deployment.yaml

@@ -2,72 +2,32 @@ apiVersion: apps/v1
 kind: Deployment
 metadata:
   name: {{ include "chart.fullname" . }}
-  labels:
-    {{- include "chart.labels" . | nindent 4 }}
+  namespace: {{ .Values.image.namespace }}
 spec:
-  {{- if not .Values.autoscaling.enabled }}
-  replicas: {{ .Values.replicaCount }}
-  {{- end }}
+  replicas: 1
   selector:
     matchLabels:
-      {{- include "chart.selectorLabels" . | nindent 6 }}
+      k8s.custom.controller: k8s-custom-controller
   template:
     metadata:
-      {{- with .Values.podAnnotations }}
-      annotations:
-        {{- toYaml . | nindent 8 }}
-      {{- end }}
       labels:
-        {{- include "chart.labels" . | nindent 8 }}
-        {{- with .Values.podLabels }}
-        {{- toYaml . | nindent 8 }}
-        {{- end }}
+        k8s.custom.controller: k8s-custom-controller
     spec:
-      {{- with .Values.imagePullSecrets }}
-      imagePullSecrets:
-        {{- toYaml . | nindent 8 }}
-      {{- end }}
-      serviceAccountName: {{ include "chart.serviceAccountName" . }}
-      {{- with .Values.podSecurityContext }}
-      securityContext:
-        {{- toYaml . | nindent 8 }}
-      {{- end }}
       containers:
         - name: {{ .Chart.Name }}
-          {{- with .Values.securityContext }}
-          securityContext:
-            {{- toYaml . | nindent 12 }}
-          {{- end }}
           image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"
+          volumeMounts:
+            - name: {{ .Values.webhook.volumeMounts }}
+              mountPath: /certs
+              readOnly: true
           env:
+            - name: TLS_CERT_FILE
+              value: "/certs/tls.crt"
+            - name: TLS_KEY_FILE
+              value: "/certs/tls.key"
             - name: CONTEXT
-              value: {{ .Values.context | quote }}
-          imagePullPolicy: {{ .Values.image.pullPolicy }}
-          ports:
-            - name: http
-              containerPort: {{ .Values.service.port }}
-              protocol: TCP
-          {{- with .Values.resources }}
-          resources:
-            {{- toYaml . | nindent 12 }}
-          {{- end }}
-          {{- with .Values.volumeMounts }}
-          volumeMounts:
-            {{- toYaml . | nindent 12 }}
-          {{- end }}
-      {{- with .Values.volumes }}
+              value: "kind-practice"
       volumes:
-        {{- toYaml . | nindent 8 }}
-      {{- end }}
-      {{- with .Values.nodeSelector }}
-      nodeSelector:
-        {{- toYaml . | nindent 8 }}
-      {{- end }}
-      {{- with .Values.affinity }}
-      affinity:
-        {{- toYaml . | nindent 8 }}
-      {{- end }}
-      {{- with .Values.tolerations }}
-      tolerations:
-        {{- toYaml . | nindent 8 }}
-      {{- end }}
+        - name: {{ .Values.webhook.volumeMounts }}
+          secret:
+            secretName: "{{ .Chart.Name }}-tls"

chart/templates/ingress.yaml

@@ -0,0 +1,4 @@
+apiVersion: v1
+kind: Namespace
+metadata:
+  name: {{ .Values.image.namespace }}

chart/templates/namespace.yaml

@@ -2,14 +2,12 @@ apiVersion: v1
 kind: Service
 metadata:
   name: {{ include "chart.fullname" . }}
-  labels:
-    {{- include "chart.labels" . | nindent 4 }}
+  namespace: {{ .Values.image.namespace }}
 spec:
-  type: {{ .Values.service.type }}
-  ports:
-    - port: {{ .Values.service.port }}
-      targetPort: 8000 #http
-      protocol: TCP
-      name: http
   selector:
-    {{- include "chart.selectorLabels" . | nindent 4 }}
+    k8s.custom.controller: k8s-custom-controller
+  ports:
+    - protocol: TCP
+      port: {{ .Values.service.port }}
+      targetPort: 8000
+  type: ClusterIP

chart/templates/service.yaml

@@ -0,0 +1,30 @@
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: {{ .Values.trivy.name }}
+  labels:
+    app: {{ .Values.trivy.name }}
+spec:
+  replicas: 1 # You can adjust the number of replicas for high availability
+  selector:
+    matchLabels:
+      app: {{ .Values.trivy.name }}
+  template:
+    metadata:
+      labels:
+        app: {{ .Values.trivy.name }}
+    spec:
+      containers:
+        - name: {{ .Values.trivy.name }}
+          image: "{{ .Values.trivy.image }}:{{ .Values.trivy.tag }}"# aquasec/trivy:latest # Use a specific version instead of latest in production
+          args: ["server", "--listen", "0.0.0.0:8080"] # Listen on all interfaces
+          ports:
+            - containerPort: 8080
+              name: http
+#          volumeMounts:
+#            - name: trivy-cache
+#              mountPath: /root/.cache/trivy
+#      volumes:
+#        - name: trivy-cache
+#          persistentVolumeClaim:
+#            claimName: trivy-cache-pvc

chart/templates/trivy-deployment.yaml

@@ -0,0 +1,14 @@
+apiVersion: v1
+kind: Service
+metadata:
+  name: "{{ .Values.trivy.name }}-service"
+  labels:
+    app: {{ .Values.trivy.name }}
+spec:
+  selector:
+    app: {{ .Values.trivy.name }}
+  ports:
+    - protocol: TCP
+      port: 8080
+      targetPort: 8080
+  type: ClusterIP