Skip to content

Commit 8034bc7

Browse files
xrstfxrstf
authored
split dev env docs into 2 documents for easier navigation (#439)
1 parent 9b8bd78 commit 8034bc7

9 files changed

Lines changed: 323 additions & 276 deletions

File tree

‎docs/content/contributing/index.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@ contribution. See the [DCO](https://github.com/kube-bind/kube-bind/tree/main/DCO
2020
2. [Install Go](https://golang.org/doc/install) (currently 1.22).
2121
3. Install [kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl).
2222

23-
More on the development environment setup can be found in the [developer guide](../developers/dev-environments.md).
23+
More on the development environment setup can be found in the [developer guide](../developers/dev-environment/index.md).
2424

2525
## Finding Areas to Contribute
2626

‎docs/content/developers/.pages‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
nav:
22
- index.md
33
- Architecture: architecture.md
4-
- Development Environment: dev-environments.md
4+
- Development Environments: dev-environment
55
- Backend: backend
66
- Konnector: konnector
77
- Publishing a release: publishing-a-release.md
8-
- Testing changes: testing-changes.md
8+
- Testing changes: testing-changes.md

‎docs/content/developers/dev-environment/.pages‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
nav:
2+
- index.md
3+
- kcp.md
4+
- kind.md

‎docs/content/developers/dev-environment/index.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
---
2+
description: >
3+
How to setup a development environment for contributing to kube-bind.
4+
title: Development Environments
5+
---
6+
7+
# Development Environments
8+
9+
Due to the fact that kube-bind is by nature a multi-cluster system, for development purposes it's recommended to have multiple clusters running or use kcp to simulate multiple clusters. Below are instructions for both approaches.
10+
11+
All the instructions assume you have already cloned the kube-bind repository and have Go installed.
12+
13+
* You can use [kcp](kcp.md) for a lightweight backend system.
14+
* You can also use [kind](kind.md) for a more full-featured local Kubernetes cluster.

‎docs/content/developers/dev-environment/kcp.md‎

Lines changed: 171 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,171 @@
1+
---
2+
description: >
3+
How to setup a development environment for contributing to kube-bind.
4+
title: kcp
5+
---
6+
7+
# Development Environment using kcp
8+
9+
All the instructions assume you have already cloned the kube-bind repository and have Go installed.
10+
11+
kcp requires initial setup to be run before it can be used. This includes setting up workspace/provider
12+
and setting up all the `APIResourceSchemas` and `APIExports`.
13+
14+
This is not required if you are doing deeper integration, and controlling the setup with your own scripts.
15+
16+
It's good to have the kcp CLI installed to help with workspace management:
17+
18+
```bash
19+
kubectl krew index add kcp-dev https://github.com/kcp-dev/krew-index.git
20+
kubectl krew install kcp-dev/kcp
21+
kubectl krew install kcp-dev/ws
22+
kubectl krew install kcp-dev/create-workspace
23+
```
24+
25+
## Preparation
26+
27+
Start kcp:
28+
29+
```bash
30+
make run-kcp
31+
```
32+
33+
## Backend
34+
35+
### Bootstrap kcp
36+
37+
This is a dedicated step to set up kcp with required workspaces and `APIExports` for kube-bind:
38+
39+
```bash
40+
cp .kcp/admin.kubeconfig .kcp/backend.kubeconfig
41+
export KUBECONFIG=.kcp/backend.kubeconfig
42+
43+
./bin/kcp-init --kcp-kubeconfig $KUBECONFIG
44+
```
45+
46+
### Run the Backend
47+
48+
```bash
49+
kubectl ws use :root:kube-bind
50+
51+
go run ./cmd/backend \
52+
--multicluster-runtime-provider kcp \
53+
--oidc-issuer-url=http://127.0.0.1:8080/oidc \
54+
--oidc-callback-url=http://127.0.0.1:8080/api/callback \
55+
--oidc-type=embedded \
56+
--pretty-name="BigCorp.com" \
57+
--namespace-prefix="kube-bind-" \
58+
--schema-source apiresourceschemas \
59+
--consumer-scope=cluster
60+
```
61+
62+
Optionally add `--fronend=http://localhost:3000` to point to local frontend (must be running
63+
separately).
64+
65+
This process will keep running, so open a new terminal.
66+
67+
## Provider
68+
69+
### Kubeconfig Setup
70+
71+
Copy the kubeconfig to the provider and create provider workspace:
72+
73+
```bash
74+
cp .kcp/admin.kubeconfig .kcp/provider.kubeconfig
75+
export KUBECONFIG=.kcp/provider.kubeconfig
76+
kubectl ws use :root
77+
kubectl create-workspace provider --enter
78+
```
79+
80+
### APIExport
81+
82+
Bind the APIExport to the provider workspace:
83+
84+
```bash
85+
kubectl kcp bind apiexport root:kube-bind:kube-bind.io \
86+
--accept-permission-claim clusterrolebindings.rbac.authorization.k8s.io \
87+
--accept-permission-claim clusterroles.rbac.authorization.k8s.io \
88+
--accept-permission-claim customresourcedefinitions.apiextensions.k8s.io \
89+
--accept-permission-claim serviceaccounts.core \
90+
--accept-permission-claim configmaps.core \
91+
--accept-permission-claim secrets.core \
92+
--accept-permission-claim subjectaccessreviews.authorization.k8s.io \
93+
--accept-permission-claim namespaces.core \
94+
--accept-permission-claim roles.rbac.authorization.k8s.io \
95+
--accept-permission-claim rolebindings.rbac.authorization.k8s.io \
96+
--accept-permission-claim apiresourceschemas.apis.kcp.io
97+
```
98+
99+
### Create CRD in provider
100+
101+
```bash
102+
kubectl apply -f contrib/kcp/deploy/examples/apiexport.yaml
103+
kubectl apply -f contrib/kcp/deploy/examples/apiresourceschema-cowboys.yaml
104+
kubectl apply -f contrib/kcp/deploy/examples/apiresourceschema-sheriffs.yaml
105+
kubectl kcp bind apiexport root:provider:cowboys-stable
106+
107+
kubectl apply -f deploy/examples/template-cowboys.yaml
108+
kubectl apply -f deploy/examples/template-sheriffs.yaml
109+
kubectl apply -f deploy/examples/collection.yaml
110+
```
111+
112+
### Retrieve the LogicalCluster
113+
114+
```bash
115+
kubectl get logicalcluster
116+
# NAME PHASE URL
117+
# cluster Ready https://192.168.2.166:6443/clusters/2myqz7lt9i0u5kzb
118+
```
119+
120+
## Consumer
121+
122+
### Initialization
123+
124+
Now we gonna initiate consumer:
125+
126+
```bash
127+
cp .kcp/admin.kubeconfig .kcp/consumer.kubeconfig
128+
export KUBECONFIG=.kcp/consumer.kubeconfig
129+
130+
kubectl ws use :root
131+
kubectl ws create consumer --enter
132+
```
133+
134+
### Binding
135+
136+
Bind the thing:
137+
138+
```bash
139+
./bin/kubectl-bind login http://127.0.0.1:8080 --cluster 1nso4d2rvleempdp
140+
./bin/kubectl-bind --dry-run --cluster-identity-namespace default -o yaml > apiserviceexport.yaml
141+
142+
# Extract secret for binding process. Note that secret name is not the same as output from command above. Check secret
143+
# name by running `kubectl get secret -n kube-bind`
144+
kubectl get secrets -n kube-bind -o jsonpath='{.items[0].data.kubeconfig}' | base64 -d > remote.kubeconfig
145+
146+
namespace=$(yq '.contexts[0].context.namespace' remote.kubeconfig)
147+
148+
./bin/kubectl-bind apiservice \
149+
--remote-kubeconfig remote.kubeconfig \
150+
--remote-namespace "$namespace" \
151+
--skip-konnector \
152+
-f apiserviceexport.yaml \
153+
-v 6
154+
```
155+
156+
This will keep running, so switch to a new terminal.
157+
158+
### Launch Konnector
159+
160+
Start konnector:
161+
162+
```bash
163+
./bin/konnector --lease-namespace default --kubeconfig .kcp/consumer.kubeconfig --server-address ":9090"
164+
```
165+
166+
Create example resources in consumer:
167+
168+
```bash
169+
kubectl apply -f deploy/examples/cr-cowboy.yaml
170+
kubectl apply -f deploy/examples/cr-sheriff.yaml
171+
```

‎docs/content/developers/dev-environment/kind.md‎

Lines changed: 129 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,129 @@
1+
---
2+
description: >
3+
How to setup a development environment for contributing to kube-bind.
4+
title: kind
5+
---
6+
7+
# Development Environment using kind
8+
9+
All the instructions assume you have already cloned the kube-bind repository and have Go installed.
10+
11+
This guide will walk you through setting up kube-bind between two Kubernetes clusters, where
12+
13+
* **Provider cluster**:
14+
* Deploys kube-bind backend
15+
* Provides kube-bind compatible backend for MangoDB resources
16+
* **Consumer cluster**:
17+
* Provides an application consuming MangoDBs from the provider cluster
18+
19+
This guide works best on Linux. macOS and Windows users may need to adjust some commands accordingly.
20+
21+
## Pre-requisites
22+
23+
To start, you'll need the following tools available in your system:
24+
25+
* [`kind`](https://kind.sigs.k8s.io/docs/user/quick-start/#installation)
26+
* [`kubectl`](https://kubernetes.io/docs/tasks/tools/)
27+
* [`kubectl-bind`](https://github.com/kube-bind/kube-bind/releases/latest) (a kubectl plugin)
28+
* [`jq`](https://jqlang.github.io/jq/download/)
29+
* port 8080 and 6443 open on your localhost
30+
31+
To install `kubectl-bind` plugin, please download the archive for your platform from the link above,
32+
extract it, and place the `kubectl-bind` executable in your system's `$PATH`.
33+
34+
!!! note
35+
**Tip:** In case of encountering `Too many open files` error when deploying the Kind clusters,
36+
run following commands:
37+
38+
```sh
39+
sudo sysctl fs.inotify.max_user_watches=524288
40+
sudo sysctl fs.inotify.max_user_instances=512
41+
```
42+
43+
See the [kind documentation](https://kind.sigs.k8s.io/docs/user/known-issues/#pod-errors-due-to-too-many-open-files)
44+
for more details.
45+
46+
## Setup
47+
48+
Run `kubectl bind dev create`, which will automatically create two Kind clusters (provider and consumer),
49+
deploy kube-bind backend in the provider cluster, and print required commands to bind the consumer
50+
cluster to the provider.
51+
52+
This command will create two Kind clusters named `kind-provider` and `kind-consumer`, set up a
53+
Docker network for them to communicate, and install kube-bind backend in the provider cluster and
54+
establish right `hostAlias` entries for communication between clusters.
55+
56+
```sh
57+
kubectl bind dev create
58+
```
59+
60+
You should see output similar to this:
61+
62+
```sh
63+
kubectl bind dev create
64+
🧪 EXPERIMENTAL: kube-bind dev command is in preview
65+
📦 Requirements: Docker must be installed and running
66+
Warning: Could not automatically add host entry. Please run:
67+
echo '127.0.0.1 kube-bind.dev.local' | sudo tee -a /etc/hosts
68+
Kind cluster kind-provider already exists, skipping creation
69+
Wrote kubeconfig kind-provider.kubeconfig
70+
Helm chart installed successfully
71+
Provider cluster IP address: 192.168.155.2
72+
Creating kind cluster kind-consumer with network kube-bind-dev
73+
Kind cluster kind-consumer created
74+
Wrote kubeconfig kind-consumer.kubeconfig
75+
🚀 kube-bind dev environment is ready!
76+
77+
- Provider cluster kubeconfig: kind-provider.kubeconfig
78+
- Consumer cluster kubeconfig: kind-consumer.kubeconfig
79+
- kube-bind server URL: http://kube-bind.dev.local:8080
80+
- Next steps:
81+
1. Run login to authenticate to the provider cluster:
82+
83+
kubectl bind login http://kube-bind.dev.local:8080
84+
85+
2. Run bind to bind an API service from the provider to the consumer cluster:
86+
87+
KUBECONFIG=kind-consumer.kubeconfig kubectl bind --konnector-host-alias 192.168.155.2:kube-bind.dev.local
88+
```
89+
90+
!!! note
91+
Note `/etc/hosts` modification and 2 commands to run to bind the consumer cluster.
92+
93+
## Login to Provider Cluster
94+
95+
This should give you UI authorization screen.
96+
97+
```bash
98+
kubectl bind login http://kube-bind.dev.local:8080
99+
```
100+
101+
## Bind First Provider API Service
102+
103+
```bash
104+
export KUBECONFIG=kind-consumer.kubeconfig
105+
kubectl bind --konnector-host-alias 192.168.155.2:kube-bind.dev.local
106+
```
107+
108+
Now in the consumer cluster you should see these CRDs:
109+
110+
```bash
111+
kubectl get crd
112+
NAME CREATED AT
113+
apiservicebindings.kube-bind.io 2025-11-12T08:10:48Z
114+
mangodbs.mangodb.com 2025-11-12T08:10:56Z
115+
```
116+
117+
Try creating an example MangoDB resource and observe it being synced to provider clusters:
118+
119+
```bash
120+
kubectl bind dev example | kubectl create -f -
121+
KUBECONFIG=kind-consumer.kubeconfig kubectl get mangodbs.mangodb.com
122+
KUBECONFIG=kind-provider.kubeconfig kubectl get mangodbs.mangodb.com
123+
```
124+
125+
## Cleanup
126+
127+
```sh
128+
kind bind dev delete
129+
```

0 commit comments

Comments
 (0)