Add cert-manager issuer integration guide (#181)

docs/10-certificate-key/20-integration-guides/40-cert-manager-issuer/01-overview.md

@@ -0,0 +1,37 @@
+# Overview
+
+This document outlines the steps necessary to be taken to integrate the CZERTAINLY with the [cert-manager](https://cert-manager.io/) `czertainly-issuer`.
+
+This integration guide was tested with:
+- Kubernetes 1.19+
+- cert-manager 1.7.0+
+
+## cert-manager
+
+cert-manager is a Kubernetes add-on to automate the management and issuance of TLS certificates from various issuing sources. It will ensure certificates are valid and up to date periodically, and attempt to renew certificates at an appropriate time before expiry.
+
+## CZERTAINLY Issuer
+
+The CZERTAINLY Issuer is a custom resource definition (CRD) that allows you to issue certificates from the CZERTAINLY platform using cert-manager interface.
+
+## Integration
+
+The following steps should be done to successfully integrate the CZERTAINLY with the cert-manager:
+
+| #     | Reference                                                | Short description                                              |
+|-------|----------------------------------------------------------|----------------------------------------------------------------|
+| **1** | [Install CZERTAINLY Issuer](./install-czertainly-issuer) | Install CZERTAINLY Issuer controller in the Kubernetes cluster |
+| **2** | [Create CZERTAINLY Issuer](./create-czertainly-issuer)   | Create CZERTAINLY Issuer resource                              |
+| **3** | [Create Certificate](./create-certificate)               | Create a certificate using the CZERTAINLY Issuer               |
+
+## Useful resources
+
+The following resources can be useful when integrating the CZERTAINLY with the cert-manager:
+
+| Resource                                                                                                                                  | Description                             |
+|-------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------|
+| [cert-manager](https://cert-manager.io/)                                                                                                  | cert-manager project website            |
+| [cert-manager installation guide](https://cert-manager.io/docs/installation/)                                                             | cert-manager installation guide         |
+| [cert-manager Certificate resource](https://cert-manager.io/docs/concepts/certificate/)                                                   | cert-manager Certificate resource guide |
+| [CZERTAINLY Issuer repository](https://github.com/CZERTAINLY/CZERTAINLY-Cert-Manager-Issuer)                                              | CZERTAINLY Issuer repository            |
+| [CZERTAINLY Issuer Helm chart](https://github.com/CZERTAINLY/CZERTAINLY-Cert-Manager-Issuer/tree/develop/deploy/charts/czertainly-issuer) | CZERTAINLY Issuer Helm chart repository | 

docs/10-certificate-key/20-integration-guides/40-cert-manager-issuer/03-install-czertainly-issuer.md

@@ -0,0 +1,26 @@
+# Install CZERTAINLY Issuer
+
+Before installing the CZERTAINLY issuer, make sure you have [`cert-manager`](https://cert-manager.io/docs/installation/) installed in your Kubernetes cluster.
+
+For more information on how to install the `cert-manager`, see the [cert-manager installation guide](https://cert-manager.io/docs/installation/).
+
+## Installation using Helm chart
+
+The Helm chart for the CZERTAINLY Issuer is available in the [CZERTAINLY Issuer Helm chart](https://github.com/CZERTAINLY/CZERTAINLY-Cert-Manager-Issuer/tree/master/deploy/charts) repository.
+
+To install the CZERTAINLY Issuer, run the following command:
+```bash
+helm install czertainly-issuer \
+  --namespace czertainly-issuer \
+  --create-namespace \
+  oci://harbor.3key.company/czertainly-helm/czertainly-issuer
+```
+
+This command will install the CZERTAINLY Issuer in the `czertainly-issuer` namespace with the default configuration, including the CZERTAINLY Issuer CRD and the CZERTAINLY Issuer controller.
+
+See the [CZERTAINLY Issuer Helm chart](https://github.com/CZERTAINLY/CZERTAINLY-Cert-Manager-Issuer/tree/master/deploy/charts) for more information on how to configure the CZERTAINLY Issuer installation using `values.yaml`, and available configuration options.
+
+You can check the status of the CZERTAINLY Issuer controller installation by running:
+```bash
+kubectl get pods -n czertainly-issuer
+```

docs/10-certificate-key/20-integration-guides/40-cert-manager-issuer/05-create-czertainly-issuer.md

@@ -0,0 +1,114 @@
+# Create CZERTAINLY Issuer
+
+The CZERTAINLY Issuer implements `czertainly-issuer.czertainly.com/v1alpha1` API that support both `CzertainlyClusterIssuer` and `CzertainlyIssuer` resources, and it allow you to configure the following `spec` field:
+
+| Field                | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | Mandatory                                     |
+|----------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------|
+| `apiUrl`             | URL to access CZERTAINLY platform API                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | <span class="badge badge--success">YES</span> |
+| `authSecretName`     | Reference to a `kubernetes.io/tls` Secret that is used to authenticate and authorize to CZERTAINLY platform. The `Secret` must be in the same namespace as the referent. If the referent is a `CzertainlyClusterIssuer`, the reference instead refers to the resource with the given name in the configured 'cluster resource namespace', which is set as a flag on the controller component (and defaults to the namespace that the controller runs in)                                              | <span class="badge badge--success">YES</span> |
+| `raProfileUuid`      | UUID of the RA profile to use when managing certificates. You can get the UUID of configured RA profile in the CZERTAINLY platform. The user should have permission to use the RA profile                                                                                                                                                                                                                                                                                                             | <span class="badge badge--success">YES</span> |
+| `raProfileName`      | Name of the RA profile to use when managing certificates. This is the name of configured RA profile in the CZERTAINLY platform. The user should have permission to use the RA profile                                                                                                                                                                                                                                                                                                                 | <span class="badge badge--danger">NO</span>   |
+| `caBundleSecretName` | Reference to a `Secret` that contains the CA bundle to use when verifying the CZERTAINLY platform's serving certificates. The Secret must be in the same namespace as the referent and must contain 'ca.crt' in data. If the referent is a `CzertainlyClusterIssuer`, the reference instead refers to the resource with the given name in the configured 'cluster resource namespace', which is set as a flag on the controller component (and defaults to the namespace that the controller runs in) | <span class="badge badge--danger">NO</span>   |
+
+## Authentication
+
+The CZERTAINLY Issuer uses the `authSecretName` referenced secret to authenticate and authorize to the CZERTAINLY platform. The secret must be a `kubernetes.io/tls` to establish mutual TLS connection with the CZERTAINLY platform.
+
+To create the `kubernetes.io/tls` secret, you can use your existing certificate and key pair and create the secret with the following command:
+```bash
+kubectl create secret tls czertainly-credentials \
+  --namespace czertainly-issuer \
+  --cert=<path-to-cert-file> \
+  --key=<path-to-key-file>
+```
+
+The secret with the name `czertainly-credentials` is created and can be used as the `authSecretName` in the CZERTAINLY Issuer.
+
+## CA Bundle
+
+The CZERTAINLY Issuer uses the `caBundleSecretName` referenced secret to verify the CZERTAINLY platform's serving certificates, if needed. The secret must contain the `ca.crt` in the `data` field.
+
+You can create `generic` secret with trusted certificates with the following command:
+```bash
+kubectl create secret generic issuer-czertainly-ca-bundle \
+  --namespace czertainly-issuer \
+  --from-file=ca.crt=<path-to-ca-bundle-file>
+```
+
+## Create `CzertainlyClusterIssuer` or `CzertainlyIssuer`
+
+The following is an example of the `CzertainlyClusterIssuer` resource:
+
+```yaml
+apiVersion: czertainly-issuer.czertainly.com/v1alpha1
+kind: CzertainlyClusterIssuer
+metadata:
+  labels:
+    app.kubernetes.io/name: czertainly-clusterissuer
+  name: czertainly-clusterissuer
+spec:
+  authSecretName: "czertainly-credentials"
+  apiUrl: "https://my.czertainly.com/api"
+  raProfileUuid: "9cb76b6a-c291-4e23-b11a-bb3da76adbc6"
+```
+
+The following is an example of the `CzertainlyIssuer` resource:
+
+```yaml
+apiVersion: czertainly-issuer.czertainly.com/v1alpha1
+kind: CzertainlyIssuer
+metadata:
+  labels:
+    app.kubernetes.io/name: czertainly-issuer
+  name: czertainly-issuer
+  namespace: default
+spec:
+  authSecretName: "czertainly-credentials"
+  apiUrl: "https://my.czertainly.com/api"
+  raProfileUuid: "9cb76b6a-c291-4e23-b11a-bb3da76adbc6"
+  raProfileName: "My RA Profile"
+  caBundleSecretName: "issuer-czertainly-ca-bundle"
+```
+
+To create the `CzertainlyClusterIssuer` or `CzertainlyIssuer`, save the resource definition to a file and apply it to the Kubernetes cluster:
+```bash
+kubectl apply -f czertainly-issuer.yaml
+```
+
+You can get all available `CzertainlyClusterIssuer` or `CzertainlyIssuer` resources by running:
+```bash
+kubectl get czertainlyclusterissuers.czertainly-issuer.czertainly.com
+kubectl get czertainlyissuers.czertainly-issuer.czertainly.com \
+  --namespace <namespace>
+```
+
+To validate the `CzertainlyClusterIssuer` or `CzertainlyIssuer` resource, you can describe the resource:
+```bash
+kubectl describe czertainlyclusterissuers.czertainly-issuer.czertainly.com czertainly-clusterissuer
+kubectl describe czertainlyissuers.czertainly-issuer.czertainly.com czertainly-issuer \
+  --namespace <namespace>
+```
+
+The status conditions of the resource will be updated once the CZERTAINLY Issuer is ready:
+
+```bash
+kubectl get czertainlyclusterissuers.czertainly-issuer.czertainly.com czertainly-issuer \
+  -o json \
+  | jq .status.conditions
+kubectl get czertainlyissuers.czertainly-issuer.czertainly.com czertainly-issuer \
+  --namespace <namespace> \
+  -o json \
+  | jq .status.conditions
+```
+
+```json
+[
+  {
+    "lastTransitionTime": "2024-11-14T10:28:23Z",
+    "message": "Success",
+    "reason": "IssuerReconciler",
+    "status": "True",
+    "type": "Ready"
+  }
+]
+```

docs/10-certificate-key/20-integration-guides/40-cert-manager-issuer/07-create-certificate.md

@@ -0,0 +1,44 @@
+# Create Certificate
+
+The certificate can be created as a cert-manager `Certificate` resource that will be automatically managed by the CZERTAINLY Issuer by specifying the `issuerRef` field.
+
+:::tip[Certificate resource]
+You can find more information about the `Certificate` resource in the [cert-manager Certificate resource](https://cert-manager.io/docs/concepts/certificate/) guide.
+:::
+
+
+## Issue `Certificate` from CZERTAINLY Issuer
+
+The following is an example of the `Certificate` resource:
+```yaml
+apiVersion: cert-manager.io/v1
+kind: Certificate
+metadata:
+  name: czertainly-crt
+spec:
+  secretName: czertainly-crt-secret
+  dnsNames:
+  - foo.example.com
+  - bar.example.com
+  issuerRef:
+    name: czertainly-issuer
+    kind: CzertainlyIssuer
+    group: czertainly-issuer.czertainly.com
+```
+
+To create the `Certificate`, save the resource definition to a file and apply it to the Kubernetes cluster:
+```bash
+kubectl apply -f czertainly-crt.yaml
+```
+
+You can get all available CZERTAINLY `Certificate` resources by running:
+```bash
+kubectl get certificates.cert-manager.io -o json | jq
+```
+
+To list all the certificates issued by the CZERTAINLY Issuer, you can run:
+```bash
+kubectl get certificates.cert-manager.io \
+  -o json \
+  | jq '.items[] | select(.spec.issuerRef.name == "czertainly-issuer")'
+```

docs/10-certificate-key/20-integration-guides/40-cert-manager-issuer/_category_.json

@@ -0,0 +1,7 @@
+{
+  "label": "Cert-Manager Issuer",
+  "link": {
+    "type": "doc",
+    "id": "overview"
+  }
+}

docusaurus.config.js

@@ -519,7 +519,7 @@ const config = {
       prism: {
         theme: lightCodeTheme,
         darkTheme: darkCodeTheme,
-        additionalLanguages: ['powershell','java','hcl','scala'],
+        additionalLanguages: ['powershell','java','hcl','scala','bash'],
       },
       algolia: {
         // The application ID provided by Algolia