From ad3afd7eeca416222567cc550b61b27ff66b84f6 Mon Sep 17 00:00:00 2001
From: Christoph Mewes <christoph@kubermatic.com>
Date: Mon, 19 Jan 2026 17:37:40 +0100
Subject: [PATCH 1/2] fix Crossplane integration guide

On-behalf-of: @SAP christoph.mewes@sap.com
---
 docs/content/usage/integrations/crossplane.md | 93 +++++++++++++------
 1 file changed, 63 insertions(+), 30 deletions(-)

diff --git a/docs/content/usage/integrations/crossplane.md b/docs/content/usage/integrations/crossplane.md
index 42cd20619..f09a42e3f 100644
--- a/docs/content/usage/integrations/crossplane.md
+++ b/docs/content/usage/integrations/crossplane.md
@@ -7,16 +7,27 @@ weight: 20
 
 # Crossplane Integration
 
-This document provides an example deployment walkthrough showing how to integrate kube-bind with Crossplane and how to deploy a sample managed MySQL resource using two kind clusters: a provider cluster (where Crossplane runs and kube-bind backend to export APIs) and a consumer cluster (which allows to bind those APIs using kube-bind konnector).
+This document provides an example deployment walkthrough showing how to integrate kube-bind with
+Crossplane and how to deploy a sample managed MySQL resource using two kind clusters: a provider
+cluster (where Crossplane runs and kube-bind backend to export APIs) and a consumer cluster (which
+allows to bind those APIs using kube-bind konnector).
 
 !!! note
-        Currently for permission claims to work properly, it is required to run namespaced Crossplane resources.
-
+    Currently for permission claims to work properly, it is required to run namespaced Crossplane
+    resources.
 
 ![Crossplane example architecture diagram](crossplane.png)
 
-1. **Install Crossplane** in your Kubernetes cluster where the kube-bind backend will run.
-   You can follow the official installation guide [here](https://docs.crossplane.io/v2.1/get-started/install).
+## Setup
+
+The following sections will guide you through the one-time setup that is required for providing
+MySQL databases using Crossplane and kube-bind.
+
+### Install Crossplane
+
+Install Crossplace in your Kubernetes cluster where the kube-bind backend will run. You can follow
+the [official installation guide](https://docs.crossplane.io/v2.1/get-started/install) from the
+Crossplane documentation.
 
 ```bash
 helm repo add crossplane-stable https://charts.crossplane.io/stable
@@ -27,9 +38,9 @@ helm install crossplane crossplane-stable/crossplane \
   --create-namespace
 ```
 
-2. **Install a Crossplane provider-sql**
+### Install Crossplane provider-sql
 
-   In the example, we will set up mysql database:
+In this example, we will set up MySQL database:
 
 ```yaml
 kubectl apply -f - <<EOF
@@ -55,10 +66,10 @@ spec:
 EOF
 ```
 
+### Setup the MySQL Deployment
 
-3. **Set up the mysql deployment in the provider cluster**
-
-    Create and set up Deployment, PersistentVolume, PersistentVolumeClaim and Service for MySQL instance
+Create and set up `Deployment`, `PersistentVolume`, `PersistentVolumeClaim` and `Service` for the
+MySQL instance.
 
 ```yaml
 kubectl apply -f - <<EOF
@@ -135,9 +146,9 @@ spec:
 EOF
 ```
 
-4. **Create a Crossplane XRD and Composition for a managed MySQL database**
+### Configure Crossplane
 
-    Apply both manifests:
+Time to create a Crossplane XRD and Composition for a managed MySQL database. Apply both manifests:
 
 ```yaml
 kubectl apply -f - <<EOF
@@ -181,6 +192,7 @@ spec:
 EOF
 ```
 
+{% raw %}
 ```yaml
 kubectl apply -f - <<'EOF'
 apiVersion: apiextensions.crossplane.io/v1
@@ -317,9 +329,11 @@ spec:
     step: create-mysql-resources
 EOF
 ```
+{% endraw %}
+
+### Export the Database API
 
-5. **Export the database API using kube-bind.**
-   Create an APIServiceExportTemplate for the mysqldatabase.mangodb.com resource:
+Create an `APIServiceExportTemplate` for the `mysqldatabase.mangodb.com` resource:
 
 ```yaml
 kubectl apply -f - <<EOF
@@ -344,16 +358,28 @@ spec:
 EOF
 ```
 
-6. **Login to kube-bind and request a binding to the exported database API.**
+## Usage
 
-    ```bash
-    kubectl bind login https://kube-bind.example.com
-    # Authenticate and select the mysqldatabase export
-    kubectl bind
-    ```
+Now that everything is set up, users can begin to bind to your backend and begin consuming the new
+API.
 
+### Login to kube-bind
 
-7. **Wait for the binding to be established.** Once the binding is active, you can create `MySQLDatabase` resources in your consumer cluster, and you will get `MySQLDatabase` objects synced from the provider cluster.
+```bash
+kubectl bind login https://kube-bind.example.com
+```
+
+### Request a Binding
+
+```bash
+# Authenticate and select the mysqldatabase export
+kubectl bind
+```
+
+### Wait for the Binding to be Established
+
+Once the binding is active, you can create `MySQLDatabase` resources in your consumer cluster,
+and you will get `MySQLDatabase` objects synced from the provider cluster.
 
 ```bash
 kubectl bind
@@ -373,14 +399,17 @@ Created 1 APIServiceBinding(s):
 Resources bound successfully!
 ```
 
-8. **Create a managed database in your consumer cluster.**
-    Verify that mysqldatabases.mangodb.com CRD is synced to the consumer cluster:
+### Create a Managed Database
+
+Verify that a `mysqldatabases.mangodb.com` CRD is synced to the consumer cluster:
+
 ```bash
 k get crd mysqldatabases.mangodb.com
 NAME                         CREATED AT
 mysqldatabases.mangodb.com   2025-11-27T14:22:18Z
 ```
-    Order a new consumer-database instance in the provider cluster
+
+Order a new consumer database instance in the provider cluster:
 
 ```yaml
 kubectl apply -f - <<EOF
@@ -394,7 +423,10 @@ spec:
 EOF
 ```
 
-9. **Observe the provisioned database and connection secret in the provider cluster.**
+### Wait for Provisioning
+
+The kube-bind konnector and the CloudNativePG operator should now be busy provisioning your
+database. You can observe the provisioned database and connection Secret in the provider cluster:
 
 ```bash
 kubectl get mysqldatabases.mangodb.com kube-bind-bp52k-consumer-database
@@ -415,6 +447,7 @@ kube-bind-bp52k-consumer-database-credentials                     Opaque
 ```bash
 kubectl get mysqldatabases.mangodb.com kube-bind-bp52k-consumer-database -o yaml
 ```
+
 ```yaml
 apiVersion: mangodb.com/v1
 kind: MySQLDatabase
@@ -472,18 +505,18 @@ status:
   ready: true
 ```
 
-You should see your MySQL instance created in the provider cluster and a secret with connection details, once Crossplane finishes provisioning of the database.
+You should see your MySQL instance created in the provider cluster and a secret with connection
+details, once Crossplane finishes provisioning of the database.
 
-Observe that the requested secret with connection details for user is synced to consumer cluster.
+Observe that the requested Secret with connection details for user is synced to consumer cluster.
 
 ```bash
 kubectl get secrets
 
-NAMESPACE     NAME                            TYPE                            DATA   AGE
-default       consumer-database-credentials   Opaque                          4      5m21s
+NAMESPACE     NAME                            TYPE      DATA   AGE
+default       consumer-database-credentials   Opaque    4      5m21s
 ```
 
-
 ---
 
 For troubleshooting and more information, check the [kube-bind documentation](https://kube-bind.io/docs/).

From 664edba8c8f8313d03ea76b90a010b9e60aa8565 Mon Sep 17 00:00:00 2001
From: Christoph Mewes <christoph@kubermatic.com>
Date: Mon, 19 Jan 2026 17:49:22 +0100
Subject: [PATCH 2/2] apply the same style to the cert-manager example

On-behalf-of: @SAP christoph.mewes@sap.com
---
 .../usage/integrations/cert-manager.md        | 54 +++++++++++++++----
 1 file changed, 45 insertions(+), 9 deletions(-)

diff --git a/docs/content/usage/integrations/cert-manager.md b/docs/content/usage/integrations/cert-manager.md
index 831927df1..d4922079c 100644
--- a/docs/content/usage/integrations/cert-manager.md
+++ b/docs/content/usage/integrations/cert-manager.md
@@ -7,15 +7,25 @@ weight: 10
 
 # Cert-Manager Integration
 
-1. **Install cert-manager** in your Kubernetes cluster, where kube-bind backend is running, if you haven't already. You can follow the official installation guide [here](https://cert-manager.io/docs/installation/kubernetes/).
+## Setup
 
-2. **Add kube-bind export label** to certificate CRD.
+The following sections will guide you through the one-time setup that is required for providing
+certificates using cert-manager and kube-bind.
+
+### Install cert-manager
+
+Install cert-manager in your Kubernetes cluster, where kube-bind backend is running, if you haven't
+already. You can follow the [official installation guide](https://cert-manager.io/docs/installation/kubernetes/).
+
+### Export the Certificate CRD
+
+To export the cert-manager `Certificate` CRD, add the kube-bind export label to it:
 
 ```bash
 kubectl label crd certificates.cert-manager.io kube-bind.io/exported=true --overwrite
 ```
 
-3. **Create SelfSigned issuer** in the provider cluster.
+### Create a SelfSigned Issuer
 
 ```yaml
 kubectl apply -f - <<EOF
@@ -28,7 +38,10 @@ spec:
 EOF
 ```
 
-4. **Create a `kube-bind` template for `Certificate` resources** to allow service consumers to request TLS certificates. Below is an example template:
+### Create a APIServiceExportTemplate
+
+It's now time to configure kube-bind to export the certificate resource. To do so, create a
+kube-bind `APIServiceExportTemplate` for `Certificate` resources like this one:
 
 ```yaml
 kubectl apply -f - <<EOF
@@ -57,15 +70,31 @@ spec:
 EOF
 ```
 
-5. **Login into the kube-bind CLI** and request a binding to the `certificate` template created above. This will allow you to create `Certificate` resources in your consumer cluster.
+## Usage
+
+Now that everything is set up, users can begin to bind to your backend and begin consuming the new
+API.
+
+### Login to kube-bind
 
 ```bash
 kubectl bind login https://kube-bind.example.com
+```
+
+### Request a Binding
+
+Request a binding to the `certificate` template created above. This will allow you to create
+`Certificate` objects in your consumer cluster.
+
+```bash
 # you will get redirected to UI to authenticate and pick the template
 kubectl bind
 ```
 
-6. **Wait for the binding to be established.** Once the binding is active, you can create `Certificate` resources in your consumer cluster, and you will get `Certificate` objects synced from the provider cluster.
+### Wait for the Binding to be Established
+
+Once the binding is active, you can create `Certificate` objects in your consumer cluster, and you
+will get `Certificate` objects synced from the provider cluster.
 
 ```bash
 kubectl bind
@@ -87,10 +116,13 @@ Created 1 APIServiceBinding(s):
 Resources bound successfully!
 ```
 
-7. **Create a `Certificate` resource** in your consumer cluster. The cert-manager in the provider cluster will handle the issuance and management of the TLS certificate.
+### Create a Certificate
+
+Now you can finally create a `Certificate` object in your consumer cluster. The cert-manager in the
+provider cluster will handle the issuance and management of the TLS certificate.
 
 !!! note
-        my-selfsigned-issuer must be present in the provider cluster for this example to work.
+    `my-selfsigned-issuer` must be present in the provider cluster for this example to work.
 
 ```yaml
 kubectl apply -f - <<EOF
@@ -109,12 +141,16 @@ spec:
 EOF
 ```
 
-8. Observe that the `Certificate` resource is created in the consumer cluster and the corresponding TLS secret is generated.
+### Wait for Provisioning
+
+Observe that the `Certificate` object is created in the consumer cluster and the corresponding TLS
+Secret is generated:
 
 ```bash
 kubectl get certificates
 NAME          READY   SECRET        AGE
 my-tls-cert   True    my-tls-cert   6m55s
+
 kubectl get secrets
 NAME          TYPE                DATA   AGE
 my-tls-cert   kubernetes.io/tls   3      6m33s