## Developing Runtime Extensions
Runtime Extensions are HTTPS only and require a certificate setup - this process is automated when deploying the Runtime Extension inside the management cluster which is the recommended development flow.
To deploy a working Runtime extensions a number of artifacts are needed:
1. Enabling both the `CLUSTER_TOPOLOGY` and `EXP_RUNTIME_SDK` flags for Cluster API.
2. Working Runtime Extension code with a Docker build
3. Kubernetes manifests including Service, RBAC, Deployment,
4. ExtensionConfig for registering a runtime extension
### Tilt workflow
The Tilt development workflow for Runtime SDK is available on [this branch](https://github.com/killianmuldoon/cluster-api/tree/tilt/add-addon-deployment).
First follow the [Tilt setup guidelines for Cluster API](https://cluster-api.sigs.k8s.io/developer/tilt.html).
A minimal tilt-settings.yaml for running tilt with the Docker provider and a cluster already in existence looks like:
```yaml=
default_registry: localhost:5000
deploy_kind_cluster: false
deploy_cert_manager: true
enable_providers:
- docker
- kubeadm-bootstrap
- kubeadm-control-plane
kustomize_substitutions:
EXP_CLUSTER_RESOURCE_SET: 'true'
EXP_MACHINE_POOL: 'true'
CLUSTER_TOPOLOGY: 'true'
EXP_RUNTIME_SDK: 'true'
```
The Test Extension is a Runtime Extension that's used for Cluster API end-to-end testing. It registered every available Hook - Patches and Lifcycle hooks. Currently it only does one patch - changing the loadBalancer image repository - but this will expand soon.
The test extension is built into our Tilt workflow.
To deploy it with Tilt simply modify the tilt-settings.yaml to:
```yaml=
default_registry: localhost:5000
deploy_kind_cluster: false
deploy_cert_manager: true
enable_providers:
- docker
- kubeadm-bootstrap
- kubeadm-control-plane
kustomize_substitutions:
EXP_CLUSTER_RESOURCE_SET: 'true'
EXP_MACHINE_POOL: 'true'
CLUSTER_TOPOLOGY: 'true'
EXP_RUNTIME_SDK: 'true'
deploy_addons:
- "test-extension"
```
The test extension will now be deployed. The deployment includes the ExtensionConfig required for registering the extension with Cluster API.
The test extension implements lifecycle hooks by reading the desired response directly from a configmap. This behaviour is part of the test extension implementation and is not shared by other runtime extensions.
This configmap is initially deployed by Tilt automatically, but the default configuration will block all lifecycle operations - including Cluster Create.
To change the result from the Lifecycle hooks the configmap can be edited. Changes can be re-applied by running:
```shell=
kubectl apply -f test/extension/hookresponses-configmap.yaml
```
---
### Using the sample extension
To create a new runtime extension the sample extension is a good starting point. It's a minimal extension which simply logs that a request has been received. It's not part of the Cluster API codebase and can be developed independently from it, unlike the test extension.
https://github.com/killianmuldoon/cluster-api-sample-runtime-extension
The sample extension can be deployed with Tilt. It integrates with tilt by including a [`tilt-addons.yaml`](https://github.com/killianmuldoon/cluster-api-sample-runtime-extension/blob/main/tilt-addon.yaml) which is read by our Tilt setup.
To deploy the sample extension first clone it to `~/home/go/src/github.com/killianmuldoon/cluster-api-sample-runtime-extension`
To surface the extension to tilt use a tilt-settings.yaml like:
```yaml=
default_registry: localhost:5000
deploy_kind_cluster: false
deploy_cert_manager: true
enable_providers:
- docker
- kubeadm-bootstrap
- kubeadm-control-plane
kustomize_substitutions:
EXP_CLUSTER_RESOURCE_SET: 'true'
EXP_MACHINE_POOL: 'true'
CLUSTER_TOPOLOGY: 'true'
EXP_RUNTIME_SDK: 'true'
addon_repos:
- "/Users/kmuldoon/project/cluster-api-sample-runtime-extension"
deploy_addons:
- "sample-extension"
```
To start creating your own extension a good starting point is to start making code changes in the sample extension.
---
### Developing a Runtime Extension without Tilt
When not using Tilt the development process for Runtime Extensions is less automated, and iteration will take longer. To deploy the test extension:
1. Export the correct tags for the image and build the templates for the extension and the cluster:
```shell=
export REGISTRY=gcr.io/k8s-staging-cluster-api
export TAG=dev
export ARCH=arm64
export PULL_POLICY=IfNotPresent
make -C test/e2e cluster-templates
make -C test/e2e test-extension-deployment
make docker-build
make docker-build-test-extension
```
2. Load the image to the kind cluster (this may be different depending on the underlying management cluster / registry situation):
```shell
kind load --name capi-test docker-image gcr.io/k8s-staging-cluster-api/test-extension-arm64:dev
```
3. Deploy the Runtime ExtensionConfig and the special test-extension ConfigMap:
```shell=
kubectl apply -f test/extension/extensionconfig.yaml
kubectl apply -f test/extension/hookresponses-configmap.yaml
```
// Currently not working as we need to substitute the namespace in the deployment files.
4. Deploy the test extension:
```shell=
kubectl apply -f test/e2e/data/test-extension/
```
Note: When making changes to the test extension and re-deploying you will need to rebuild the docker image and redeploy by deleting existing replicas:
```shell=
export REGISTRY=gcr.io/k8s-staging-cluster-api
export TAG=dev
export ARCH=arm64
export PULL_POLICY=IfNotPresent
make docker-build-test-extension
kind load --name capi-test docker-image gcr.io/k8s-staging-cluster-api/test-extension-arm64:dev
kubectl delete pods -l app=test-extension
```
{"metaMigratedAt":"2023-06-17T06:27:16.020Z","metaMigratedFrom":"Content","title":"Untitled","breaks":true,"contributors":"[{\"id\":\"00c92199-a6b6-4e3c-92c5-8fca7bb7602b\",\"add\":6312,\"del\":579}]"}