Skip to content

Commit 1979e17

Browse files
tuunittuunit
committed
docs: fix serve-book dependency and enhance clarity of the development guide
Signed-off-by: Jan Larwig <jan.larwig@digits.schwarz>
1 parent 1e3885d commit 1979e17

3 files changed

Lines changed: 112 additions & 37 deletions

File tree

‎docs/Makefile‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ build: $(BOOK_DEPS) ## Build the book
1515
$(MDBOOK) build .
1616

1717
.PHONY: serve
18-
serve:
18+
serve: $(BOOK_DEPS)
1919
$(MDBOOK) serve . --open
2020

2121
.PHONY: clean

‎docs/src/development/index.md‎

Lines changed: 83 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -1,71 +1,118 @@
11
# Developer Guide
22

3-
This guide is for contributors working from a local checkout.
3+
Use this guide to create a local development environment from a fresh checkout.
4+
It creates a Kind management cluster, installs Cluster API, and runs the
5+
STACKIT provider image you build from this repository. That management cluster
6+
then creates workload clusters in STACKIT, so use a project intended for
7+
development and expect the workload resources to incur cost.
48

5-
## Run against the current cluster
9+
## Before you start
610

7-
Install CRDs into the current cluster:
11+
Install:
812

9-
```sh
10-
make install
11-
```
13+
- Go
14+
- Docker
15+
- `kind`
16+
- `kubectl`
17+
- `clusterctl`
18+
- `base64`
1219

13-
Run the controller locally against the current kubeconfig context:
20+
You also need a STACKIT project, a service-account JSON key, an existing
21+
network, an image, and a machine type. The service account needs the permissions
22+
listed in [IAM permissions](../topics/iam-permissions.md).
1423

15-
```sh
16-
make run
17-
```
24+
Clone this repository and run the commands below from its root.
1825

19-
Build and deploy the controller image:
26+
## Create the management cluster
2027

21-
```sh
22-
export IMG=<registry>/cluster-api-provider-stackit:<tag>
23-
make docker-build docker-push IMG="$IMG"
24-
make deploy IMG="$IMG"
25-
```
28+
The management cluster runs the Cluster API controllers and the provider. It is
29+
not the Kubernetes cluster that will run your workload.
2630

27-
For a local kind management cluster, build and load the image instead of pushing it:
31+
### Enterprise proxies like Zscaler
32+
33+
If your network uses a TLS-intercepting proxy such as Zscaler, the Kind node
34+
must trust the proxy's root certificate. The host's certificate store does not
35+
automatically apply inside the Kind node. Create a local `kind-config.yaml`
36+
that mounts the host CA bundle into the node:
2837

2938
```sh
30-
export IMG=cluster-api-provider-stackit:dev
31-
make docker-build IMG="$IMG"
32-
kind load docker-image "$IMG" --name capi-stackit
33-
make deploy IMG="$IMG"
39+
cat > kind-config.yaml <<'EOF'
40+
kind: Cluster
41+
apiVersion: kind.x-k8s.io/v1alpha4
42+
nodes:
43+
- role: control-plane
44+
extraMounts:
45+
- hostPath: /etc/ssl/certs/ca-certificates.crt
46+
containerPath: /etc/ssl/certs/ca-certificates.crt
47+
readOnly: true
48+
EOF
49+
kind create cluster --name capi-stackit --config kind-config.yaml
3450
```
3551

36-
The local development cluster used during validation is `kind-capi-stackit`.
37-
38-
## Use locally built provider assets
39-
40-
Build a local clusterctl repository:
52+
Without such a proxy, create the cluster without the configuration file:
4153

4254
```sh
43-
export IMG=cluster-api-provider-stackit:dev
44-
make clusterctl-release IMG="${IMG}"
45-
export STACKIT_CLUSTERCTL_REPOSITORY="$(pwd)/dist/clusterctl"
55+
kind create cluster --name capi-stackit
4656
```
4757

48-
Create a Kind management cluster and install the local provider assets:
58+
Point `kubectl` at the new management cluster:
4959

5060
```sh
51-
kind create cluster --name capi-stackit
5261
kubectl config use-context kind-capi-stackit
62+
```
63+
64+
## Install Cluster API
65+
66+
Install Cluster API core, bootstrap, and control-plane providers into the management
67+
cluster:
5368

69+
```sh
5470
clusterctl init \
5571
--config hack/clusterctl-local.yaml \
5672
--core cluster-api \
5773
--bootstrap kubeadm \
58-
--control-plane kubeadm \
59-
--infrastructure stackit:v0.1.0
74+
--control-plane kubeadm
6075
```
6176

62-
Build and load the image, then deploy the controller:
77+
`hack/clusterctl-local.yaml` enables Cluster API features needed by the
78+
repository's templates, including ClusterClass and ClusterResourceSet.
79+
80+
## Build and deploy the local provider
81+
82+
Build the controller image, load it into the Kind node, and deploy the
83+
provider with that image:
6384

6485
```sh
86+
export IMG=cluster-api-provider-stackit:dev
6587
make docker-build IMG="${IMG}"
6688
kind load docker-image "${IMG}" --name capi-stackit
6789
make deploy IMG="${IMG}"
6890
```
6991

70-
`hack/clusterctl-local.yaml` enables `CLUSTER_TOPOLOGY` so ClusterClass and
71-
topology clusters can pass the Cluster API admission webhooks.
92+
Wait until the locally built provider is ready:
93+
94+
```sh
95+
kubectl rollout status \
96+
--namespace cluster-api-provider-stackit-system \
97+
deployment/cluster-api-provider-stackit-controller-manager
98+
```
99+
100+
## Configure STACKIT and create a workload cluster
101+
102+
The provider is now running from your checkout. Continue with the quick start
103+
from [set credentials and cluster settings](../quick-start.md#set-credentials-and-cluster-settings).
104+
Create the Secret in the `default` namespace used there, then continue with
105+
[create a workload cluster](../quick-start.md#create-a-workload-cluster).
106+
107+
## Run the controller on your host
108+
109+
For controller debugging, stop the deployed provider first, keep
110+
`kind-capi-stackit` as the active kubeconfig context, and run:
111+
112+
```sh
113+
make undeploy
114+
make run
115+
```
116+
117+
`make run` connects to the active management cluster. When you stop it, rebuild,
118+
load, and deploy the image again with the commands in the previous section.

‎docs/src/quick-start.md‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,8 +30,36 @@ EOF
3030

3131
## Create a management cluster
3232

33+
### Enterprise proxies like Zscaler
34+
35+
If your network uses a TLS-intercepting proxy such as Zscaler, the Kind node
36+
must trust the proxy's root certificate. The host's certificate store does not
37+
automatically apply inside the Kind node. Create a local `kind-config.yaml`
38+
that mounts the host CA bundle into the node:
39+
40+
```sh
41+
cat > kind-config.yaml <<'EOF'
42+
kind: Cluster
43+
apiVersion: kind.x-k8s.io/v1alpha4
44+
nodes:
45+
- role: control-plane
46+
extraMounts:
47+
- hostPath: /etc/ssl/certs/ca-certificates.crt
48+
containerPath: /etc/ssl/certs/ca-certificates.crt
49+
readOnly: true
50+
EOF
51+
kind create cluster --name capi-stackit --config kind-config.yaml
52+
```
53+
54+
Without such a proxy, create the cluster without the configuration file:
55+
3356
```sh
3457
kind create cluster --name capi-stackit
58+
```
59+
60+
Select the management-cluster context and install the provider:
61+
62+
```sh
3563
kubectl config use-context kind-capi-stackit
3664

3765
clusterctl init \

0 commit comments

Comments
 (0)