add readme and helm chart

stackitcloud · Aug 25, 2023 · dde759c · dde759c
1 parent 6871391
commit dde759c
Show file tree

Hide file tree

Showing 11 changed files with 489 additions and 3 deletions.
diff --git a/README.md b/README.md
@@ -1,8 +1,102 @@
-# STACKIT Webhook - Cert Manager
-
+# STACKIT Webhook Integration for Cert Manager
 [![GoTemplate](https://img.shields.io/badge/go/template-black?logo=go)](https://github.com/golang-standards/project-layout)
+[![Go](https://img.shields.io/badge/go-1.21.0-blue?logo=go)](https://golang.org/)
+[![Helm](https://img.shields.io/badge/helm-3.12.3-blue?logo=helm)](https://helm.sh/)
+[![Kubernetes](https://img.shields.io/badge/kubernetes-1.28.0-blue?logo=kubernetes)](https://kubernetes.io/)
+[![Cert Manager](https://img.shields.io/badge/cert--manager-1.12.3-blue?logo=cert-manager)](https://cert-manager.io/)
+[![Releases](https://img.shields.io/github/v/release/stackitcloud/stackit-cert-manager-webhook?include_prereleases)](https://github.com/stackitcloud/stackit-cert-manager-webhook/releases)
 [![CI](https://github.com/stackitcloud/stackit-api-manager-cli/actions/workflows/main.yml/badge.svg)](https://github.com/stackitcloud/stackit-cert-manager-webhook/actions/workflows/main.yml)
 [![Semgrep](https://github.com/stackitcloud/stackit-api-manager-cli/actions/workflows/semgrep.yml/badge.svg)](https://github.com/stackitcloud/stackit-cert-manager-webhook/actions/workflows/semgrep.yml)
 [![Go Report Card](https://goreportcard.com/badge/github.com/stackitcloud/stackit-api-manager-cli)](https://goreportcard.com/report/github.com/stackitcloud/stackit-cert-manager-webhook)
 
-This is the stackit webhook for cert-manager to provide dns01 challenges for STACKIT DNS. 
+Facilitate a webhook integration for leveraging the STACKIT DNS alongside 
+its [API](https://docs.api.stackit.cloud/documentation/dns/version/v1) to act as a DNS01 
+ACME Issuer with [cert-manager](https://cert-manager.io/docs/).
+
+## Installation
+```bash
+helm install stackit-cert-manager-webhook \
+  --namespace cert-manager \
+  https://github.com/stackitcloud/stackit-cert-manager-webhook/releases/download/v0.1.0/stackit-cert-manager-webhook-v0.1.0.tgz
+```
+
+## Usage
+1. ***Initiation of STACKIT Authentication Token Secret:***
+    ```bash
+    kubectl create secret generic stackit-cert-manager-webhook \
+      --namespace=cert-manager \
+      --from-literal=auth-token=<STACKIT AUTH TOKEN>
+    ```
+
+2. ***Configuration of ClusterIssuer/Issuer:***   
+For scenarios wherein zones and record sets are encapsulated within a singular project, utilize a ClusterIssuer:
+    ```yaml
+    apiVersion: cert-manager.io/v1
+    kind: ClusterIssuer
+    metadata:
+      name: letsencrypt-prod
+    spec:
+      acme:
+        server: https://acme-v02.api.letsencrypt.org/directory
+        email: [email protected] # Replace this with your email address
+        privateKeySecretRef:
+          name: letsencrypt-prod
+        solvers:
+        - dns01:
+          webhook:
+            solverName: stackit
+            groupName: stackit.de
+            config:
+              projectId: <STACKIT PROJECT ID>
+    ```
+
+    For diverse project architectures where zones are spread across varying projects, necessitating distinct 
+    authentication tokens per project, the Issuer configuration becomes pertinent. This approach inherently 
+    tethers namespaces to individual projects.
+    ```bash
+    kubectl create secret generic stackit-cert-manager-webhook \
+      --namespace=default \
+      --from-literal=auth-token=<STACKIT AUTH TOKEN>
+    ```
+    ```yaml
+    apiVersion: cert-manager.io/v1
+    kind: Issuer
+    metadata:
+      name: letsencrypt-prod
+      namespace: default
+    spec:
+      acme:
+        server: https://acme-v02.api.letsencrypt.org/directory
+        email: [email protected] # Replace this with your email address
+        privateKeySecretRef:
+          name: letsencrypt-prod
+        solvers:
+        - dns01:
+          webhook:
+            solverName: stackit
+            groupName: stackit.de
+            config:
+              projectId: <STACKIT PROJECT ID>
+              authTokenSecretNamespace: default
+    ```
+    *Note:* Ensure the creation of an authentication token secret within the namespace linked to the issuer. 
+    The secret must be vested with permissions to access zones in the stipulated project configuration.
+
+## Test Procedures
+- Unit Testing:
+    ```bash
+    make test
+    ```
+
+- Unit Testing with Coverage Analysis:
+    ```bash
+    make coverage
+    ```
+
+- Linting:
+    ```bash
+    make lint
+    ```
+
+- End-to-End Testing Workflow:  
+Follow the comprehensive guide available [here](e2e_test/README.md).
diff --git a/deploy/stackit/.helmignore b/deploy/stackit/.helmignore
@@ -0,0 +1,21 @@
+# Patterns to ignore when building packages.
+# This supports shell glob matching, relative path matching, and
+# negation (prefixed with !). Only one pattern per line.
+.DS_Store
+# Common VCS dirs
+.git/
+.gitignore
+.bzr/
+.bzrignore
+.hg/
+.hgignore
+.svn/
+# Common backup files
+*.swp
+*.bak
+*.tmp
+*~
+# Various IDEs
+.project
+.idea/
+*.tmproj
diff --git a/deploy/stackit/Chart.yaml b/deploy/stackit/Chart.yaml
@@ -0,0 +1,5 @@
+apiVersion: v1
+appVersion: "1.0"
+description: A Helm chart for Kubernetes
+name: stackit-cert-manager-webhook
+version: 0.1.0
diff --git a/deploy/stackit/templates/Notes.txt b/deploy/stackit/templates/Notes.txt
diff --git a/deploy/stackit/templates/_helpers.tpl b/deploy/stackit/templates/_helpers.tpl
@@ -0,0 +1,48 @@
+{{/* vim: set filetype=mustache: */}}
+{{/*
+Expand the name of the chart.
+*/}}
+{{- define "stackit-cert-manager-webhook.name" -}}
+{{- default .Chart.Name .Values.nameOverride | trunc 63 | trimSuffix "-" -}}
+{{- end -}}
+
+{{/*
+Create a default fully qualified app name.
+We truncate at 63 chars because some Kubernetes name fields are limited to this (by the DNS naming spec).
+If release name contains chart name it will be used as a full name.
+*/}}
+{{- define "stackit-cert-manager-webhook.fullname" -}}
+{{- if .Values.fullnameOverride -}}
+{{- .Values.fullnameOverride | trunc 63 | trimSuffix "-" -}}
+{{- else -}}
+{{- $name := default .Chart.Name .Values.nameOverride -}}
+{{- if contains $name .Release.Name -}}
+{{- .Release.Name | trunc 63 | trimSuffix "-" -}}
+{{- else -}}
+{{- printf "%s-%s" .Release.Name $name | trunc 63 | trimSuffix "-" -}}
+{{- end -}}
+{{- end -}}
+{{- end -}}
+
+{{/*
+Create chart name and version as used by the chart label.
+*/}}
+{{- define "stackit-cert-manager-webhook.chart" -}}
+{{- printf "%s-%s" .Chart.Name .Chart.Version | replace "+" "_" | trunc 63 | trimSuffix "-" -}}
+{{- end -}}
+
+{{- define "stackit-cert-manager-webhook.selfSignedIssuer" -}}
+{{ printf "%s-selfsign" (include "stackit-cert-manager-webhook.fullname" .) }}
+{{- end -}}
+
+{{- define "stackit-cert-manager-webhook.rootCAIssuer" -}}
+{{ printf "%s-ca" (include "stackit-cert-manager-webhook.fullname" .) }}
+{{- end -}}
+
+{{- define "stackit-cert-manager-webhook.rootCACertificate" -}}
+{{ printf "%s-ca" (include "stackit-cert-manager-webhook.fullname" .) }}
+{{- end -}}
+
+{{- define "stackit-cert-manager-webhook.servingCertificate" -}}
+{{ printf "%s-webhook-tls" (include "stackit-cert-manager-webhook.fullname" .) }}
+{{- end -}}
diff --git a/deploy/stackit/templates/apiservice.yaml b/deploy/stackit/templates/apiservice.yaml
@@ -0,0 +1,19 @@
+apiVersion: apiregistration.k8s.io/v1
+kind: APIService
+metadata:
+  name: v1alpha1.{{ .Values.groupName }}
+  labels:
+    app: {{ include "stackit-cert-manager-webhook.name" . }}
+    chart: {{ include "stackit-cert-manager-webhook.chart" . }}
+    release: {{ .Release.Name }}
+    heritage: {{ .Release.Service }}
+  annotations:
+    cert-manager.io/inject-ca-from: "{{ .Release.Namespace }}/{{ include "stackit-cert-manager-webhook.servingCertificate" . }}"
+spec:
+  group: {{ .Values.groupName }}
+  groupPriorityMinimum: 1000
+  versionPriority: 15
+  service:
+    name: {{ include "stackit-cert-manager-webhook.fullname" . }}
+    namespace: {{ .Release.Namespace }}
+  version: v1alpha1
diff --git a/deploy/stackit/templates/deployment.yaml b/deploy/stackit/templates/deployment.yaml
@@ -0,0 +1,69 @@
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: {{ include "stackit-cert-manager-webhook.fullname" . }}
+  namespace: {{ .Release.Namespace | quote }}
+  labels:
+    app: {{ include "stackit-cert-manager-webhook.name" . }}
+    chart: {{ include "stackit-cert-manager-webhook.chart" . }}
+    release: {{ .Release.Name }}
+    heritage: {{ .Release.Service }}
+spec:
+  replicas: {{ .Values.replicaCount }}
+  selector:
+    matchLabels:
+      app: {{ include "stackit-cert-manager-webhook.name" . }}
+      release: {{ .Release.Name }}
+  template:
+    metadata:
+      labels:
+        app: {{ include "stackit-cert-manager-webhook.name" . }}
+        release: {{ .Release.Name }}
+    spec:
+      serviceAccountName: {{ include "stackit-cert-manager-webhook.fullname" . }}
+      containers:
+        - name: {{ .Chart.Name }}
+          image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"
+          imagePullPolicy: {{ .Values.image.pullPolicy }}
+          args:
+            - --tls-cert-file=/tls/tls.crt
+            - --tls-private-key-file=/tls/tls.key
+          env:
+            - name: GROUP_NAME
+              value: {{ .Values.groupName | quote }}
+          ports:
+            - name: https
+              containerPort: 443
+              protocol: TCP
+          livenessProbe:
+            httpGet:
+              scheme: HTTPS
+              path: /healthz
+              port: https
+          readinessProbe:
+            httpGet:
+              scheme: HTTPS
+              path: /healthz
+              port: https
+          volumeMounts:
+            - name: certs
+              mountPath: /tls
+              readOnly: true
+          resources:
+{{ toYaml .Values.resources | indent 12 }}
+      volumes:
+        - name: certs
+          secret:
+            secretName: {{ include "stackit-cert-manager-webhook.servingCertificate" . }}
+    {{- with .Values.nodeSelector }}
+      nodeSelector:
+{{ toYaml . | indent 8 }}
+    {{- end }}
+    {{- with .Values.affinity }}
+      affinity:
+{{ toYaml . | indent 8 }}
+    {{- end }}
+    {{- with .Values.tolerations }}
+      tolerations:
+{{ toYaml . | indent 8 }}
+    {{- end }}
diff --git a/deploy/stackit/templates/pki.yaml b/deploy/stackit/templates/pki.yaml
@@ -0,0 +1,76 @@
+---
+# Create a selfsigned Issuer, in order to create a root CA certificate for
+# signing webhook serving certificates
+apiVersion: cert-manager.io/v1
+kind: Issuer
+metadata:
+  name: {{ include "stackit-cert-manager-webhook.selfSignedIssuer" . }}
+  namespace: {{ .Release.Namespace | quote }}
+  labels:
+    app: {{ include "stackit-cert-manager-webhook.name" . }}
+    chart: {{ include "stackit-cert-manager-webhook.chart" . }}
+    release: {{ .Release.Name }}
+    heritage: {{ .Release.Service }}
+spec:
+  selfSigned: {}
+
+---
+
+# Generate a CA Certificate used to sign certificates for the webhook
+apiVersion: cert-manager.io/v1
+kind: Certificate
+metadata:
+  name: {{ include "stackit-cert-manager-webhook.rootCACertificate" . }}
+  namespace: {{ .Release.Namespace | quote }}
+  labels:
+    app: {{ include "stackit-cert-manager-webhook.name" . }}
+    chart: {{ include "stackit-cert-manager-webhook.chart" . }}
+    release: {{ .Release.Name }}
+    heritage: {{ .Release.Service }}
+spec:
+  secretName: {{ include "stackit-cert-manager-webhook.rootCACertificate" . }}
+  duration: 43800h # 5y
+  issuerRef:
+    name: {{ include "stackit-cert-manager-webhook.selfSignedIssuer" . }}
+  commonName: "ca.stackit-cert-manager-webhook.cert-manager"
+  isCA: true
+
+---
+
+# Create an Issuer that uses the above generated CA certificate to issue certs
+apiVersion: cert-manager.io/v1
+kind: Issuer
+metadata:
+  name: {{ include "stackit-cert-manager-webhook.rootCAIssuer" . }}
+  namespace: {{ .Release.Namespace | quote }}
+  labels:
+    app: {{ include "stackit-cert-manager-webhook.name" . }}
+    chart: {{ include "stackit-cert-manager-webhook.chart" . }}
+    release: {{ .Release.Name }}
+    heritage: {{ .Release.Service }}
+spec:
+  ca:
+    secretName: {{ include "stackit-cert-manager-webhook.rootCACertificate" . }}
+
+---
+
+# Finally, generate a serving certificate for the webhook to use
+apiVersion: cert-manager.io/v1
+kind: Certificate
+metadata:
+  name: {{ include "stackit-cert-manager-webhook.servingCertificate" . }}
+  namespace: {{ .Release.Namespace | quote }}
+  labels:
+    app: {{ include "stackit-cert-manager-webhook.name" . }}
+    chart: {{ include "stackit-cert-manager-webhook.chart" . }}
+    release: {{ .Release.Name }}
+    heritage: {{ .Release.Service }}
+spec:
+  secretName: {{ include "stackit-cert-manager-webhook.servingCertificate" . }}
+  duration: 8760h # 1y
+  issuerRef:
+    name: {{ include "stackit-cert-manager-webhook.rootCAIssuer" . }}
+  dnsNames:
+    - {{ include "stackit-cert-manager-webhook.fullname" . }}
+    - {{ include "stackit-cert-manager-webhook.fullname" . }}.{{ .Release.Namespace }}
+    - {{ include "stackit-cert-manager-webhook.fullname" . }}.{{ .Release.Namespace }}.svc