Skip to content

fix Crossplane integration guide #438

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
xrstf merged 2 commits into from
Jan 20, 2026
Merged

fix Crossplane integration guide #438

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
ad3afd7
fix Crossplane integration guide
xrstf Jan 19, 2026
664edba
apply the same style to the cert-manager example
xrstf Jan 19, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
54 changes: 45 additions & 9 deletions docs/content/usage/integrations/cert-manager.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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
Expand Down
93 changes: 63 additions & 30 deletions docs/content/usage/integrations/crossplane.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -181,6 +192,7 @@ spec:
EOF
```

{% raw %}
```yaml
kubectl apply -f - <<'EOF'
apiVersion: apiextensions.crossplane.io/v1
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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/).