sigs.k8s.io/cluster-api@v1.7.1/docs/book/src/developer/guide.md (about) 1 # Developer Guide 2 3 ## Pieces of Cluster API 4 5 Cluster API is made up of many components, all of which need to be running for correct operation. 6 For example, if you wanted to use Cluster API [with AWS][capa], you'd need to install both the [cluster-api manager][capi-manager] and the [aws manager][capa-manager]. 7 8 Cluster API includes a built-in provisioner, [Docker], that's suitable for using for testing and development. 9 This guide will walk you through getting that daemon, known as [CAPD], up and running. 10 11 Other providers may have additional steps you need to follow to get up and running. 12 13 [capa]: https://github.com/kubernetes-sigs/cluster-api-provider-aws 14 [capi-manager]: https://github.com/kubernetes-sigs/cluster-api/blob/main/main.go 15 [capa-manager]: https://github.com/kubernetes-sigs/cluster-api-provider-aws/blob/main/main.go 16 [Docker]: https://github.com/kubernetes-sigs/cluster-api/tree/main/test/infrastructure/docker 17 [CAPD]: https://github.com/kubernetes-sigs/cluster-api/blob/main/test/infrastructure/docker/README.md 18 19 ## Prerequisites 20 21 ### Docker 22 23 Iterating on the cluster API involves repeatedly building Docker containers. 24 You'll need the [docker daemon][docker] v19.03 or newer available. 25 26 [docker]: https://docs.docker.com/install/ 27 28 ### A Cluster 29 30 You'll likely want an existing cluster as your [management cluster][mcluster]. 31 The easiest way to do this is with [kind] v0.9 or newer, as explained in the quick start. 32 33 Make sure your cluster is set as the default for `kubectl`. 34 If it's not, you will need to modify subsequent `kubectl` commands below. 35 36 [mcluster]: ../reference/glossary.md#management-cluster 37 [kind]: https://github.com/kubernetes-sigs/kind 38 39 ### A container registry 40 41 If you're using [kind], you'll need a way to push your images to a registry so they can be pulled. 42 You can instead [side-load] all images, but the registry workflow is lower-friction. 43 44 Most users test with [GCR], but you could also use something like [Docker Hub][hub]. 45 If you choose not to use GCR, you'll need to set the `REGISTRY` environment variable. 46 47 [side-load]: https://kind.sigs.k8s.io/docs/user/quick-start/#loading-an-image-into-your-cluster 48 [GCR]: https://cloud.google.com/container-registry/ 49 [hub]: https://hub.docker.com/ 50 51 ### Kustomize 52 53 You'll need to [install `kustomize`][kustomize]. 54 There is a version of `kustomize` built into kubectl, but it does not have all the features of `kustomize` v3 and will not work. 55 56 [kustomize]: https://kubectl.docs.kubernetes.io/installation/kustomize/ 57 58 ### Kubebuilder 59 60 You'll need to [install `kubebuilder`][kubebuilder]. 61 62 [kubebuilder]: https://book.kubebuilder.io/quick-start.html#installation 63 64 ### Envsubst 65 66 You'll need [`envsubst`][envsubst] or similar to handle clusterctl var replacement. Note: drone/envsubst releases v1.0.2 and earlier do not have the binary packaged under cmd/envsubst. It is available in Go pseudo-version `v1.0.3-0.20200709231038-aa43e1c1a629` 67 68 We provide a make target to generate the `envsubst` binary if desired. See the [provider contract][provider-contract] for more details about how clusterctl uses variables. 69 70 ```bash 71 make envsubst 72 ``` 73 74 The generated binary can be found at ./hack/tools/bin/envsubst 75 76 [envsubst]: https://github.com/drone/envsubst 77 [provider-contract]: ./../clusterctl/provider-contract.md 78 79 ### Cert-Manager 80 81 You'll need to deploy [cert-manager] components on your [management cluster][mcluster], using `kubectl` 82 83 ```bash 84 kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.14.4/cert-manager.yaml 85 ``` 86 87 Ensure the cert-manager webhook service is ready before creating the Cluster API components. 88 89 This can be done by following instructions for [manual verification](https://cert-manager.io/docs/installation/verify/#manual-verification) 90 from the [cert-manager] web site. 91 Note: make sure to follow instructions for the release of cert-manager you are installing. 92 93 [cert-manager]: https://github.com/cert-manager/cert-manager 94 95 ## Development 96 97 ## Option 1: Tilt 98 99 [Tilt][tilt] is a tool for quickly building, pushing, and reloading Docker containers as part of a Kubernetes deployment. 100 Many of the Cluster API engineers use it for quick iteration. Please see our [Tilt instructions] to get started. 101 102 [tilt]: https://tilt.dev 103 [capi-dev]: https://github.com/chuckha/capi-dev 104 [Tilt instructions]: ../developer/tilt.md 105 106 ## Option 2: The Old-fashioned way 107 108 ```bash 109 # Build all the images 110 make docker-build 111 112 # Push images 113 make docker-push 114 115 # Apply the manifests 116 kustomize build config/default | ./hack/tools/bin/envsubst | kubectl apply -f - 117 kustomize build bootstrap/kubeadm/config/default | ./hack/tools/bin/envsubst | kubectl apply -f - 118 kustomize build controlplane/kubeadm/config/default | ./hack/tools/bin/envsubst | kubectl apply -f - 119 kustomize build test/infrastructure/docker/config/default | ./hack/tools/bin/envsubst | kubectl apply -f - 120 ``` 121 122 ## Testing 123 124 Cluster API has a number of test suites available for you to run. Please visit the [testing][testing] page for more 125 information on each suite. 126 127 [testing]: ./testing.md 128 129 ## That's it! 130 131 Now you can [create CAPI objects][qs]! 132 To test another iteration, you'll need to follow the steps to build, push, update the manifests, and apply. 133 134 [qs]: ../user/quick-start.md 135 136 ## Videos explaining CAPI architecture and code walkthroughs 137 138 **CAPI components and architecture** 139 140 * [Simplified Experience Of Building Cluster API Provider In Multitenant Cloud - October 2022](https://www.youtube.com/watch?v=1oj9BuV2dzA) 141 * [Cluster API Intro and Deep Dive - May 2022 v1beta1](https://www.youtube.com/watch?v=9H8flXm_lKk) 142 * [Cluster API Deep Dive - Dec 2020 v1alpha3](https://youtu.be/npFO5Fixqcc) 143 * [Cluster API Deep Dive - Sept 2020 v1alpha3](https://youtu.be/9SfuQQeeK6Q) 144 * [Declarative Kubernetes Clusters with Cluster API - Oct 2020 v1alpha3](https://youtu.be/i6OWn2zRsZg) 145 * [TGI Kubernetes 178: ClusterAPI - ClusterClass & Managed Topologies - Dec 2020 v1beta1](https://www.youtube.com/watch?v=U9CDND0nzRI&list=PL7bmigfV0EqQzxcNpmcdTJ9eFRPBe-iZa&index=5) 146 147 **Additional ClusterAPI KubeCon talks** 148 149 * [SIG Cluster Lifecycle Intro & Future - November 2023](https://www.youtube.com/watch?v=MM0YPhIel2M) 150 * [Cluster API Deep Dive: Improving Performance up to 2k Clusters - November 2023](https://www.youtube.com/watch?v=bRPfmviTi3s) 151 * [Leveraging Cluster-API for Production-Ready Multi-Regional Infrastructures - November 2023](https://www.youtube.com/watch?v=BDjhGEVJ0Gs) 152 * [The Stars Look Very Different Today”: Kubernetes and Cloud Native at the SKA Observatory - November 2023](https://www.youtube.com/watch?v=quW8FbW1fVM) 153 * [15,000 Minecraft Players Vs One K8s Cluster. Who Wins? - November 2023](https://www.youtube.com/watch?v=4YNp2vb9NTA) 154 * [Cluster API Providers: Intro, Deep Dive, and Community! - April 2023](https://www.youtube.com/watch?v=QA4OhqLKJn4) 155 * [Ephemeral Clusters as a Service with ClusterAPI and GitOps - April 2023](https://www.youtube.com/watch?v=cXIo8C7yWvg) 156 * [The Power of Self-Managing Clusters - April 2023](https://www.youtube.com/watch?v=tNUH_8MFyTc) 157 * [How to Turn Release Management from Duty to Fun - April 2023](https://www.youtube.com/watch?v=sgP3tyGJ5tQ) 158 * [Tilt Your World! Lessons Learned in Improving Dev Productivity with Tilt - April 2023](https://www.youtube.com/watch?v=h6llT5Bg97g) 159 * [How Adobe Planned For Scale With Argo CD, Cluster API, And VCluster - October 2022](https://www.youtube.com/watch?v=p8BluR5WT5w) 160 * [Bare-Metal Chronicles: Intertwinement Of Tinkerbell, Cluster API And GitOps - October 2022](https://www.youtube.com/watch?v=NCFUUjTw6hA) 161 * [Running Isolated VirtualClusters With Kata & Cluster API - October 2022](https://www.youtube.com/watch?v=T6w3YrExorY) 162 * [SIG Cluster Lifecycle Intro - October 2022](https://www.youtube.com/watch?v=0Zo0cWYU0fM) 163 * [How to Migrate 700 Kubernetes Clusters to Cluster API with Zero Downtime - May 2022](https://www.youtube.com/watch?v=KzYV-fJ_wH0) 164 * [Build Your Own Cluster API Provider the Easy Way - May 2022](https://www.youtube.com/watch?v=HSdgmcAAXa8) 165 166 **Tutorials** 167 168 * [kubectl Create Cluster: Production-ready Kubernetes with Cluster API 1.0 - October 2022](https://kccncna2022.sched.com/event/1BZDs) 169 170 [Source code](https://github.com/ykakarap/kubecon-na-22-capi-lab) 171 * [So You Want To Develop a Cluster API Provider? - October 2022](https://kccncna2022.sched.com/event/182Ha) 172 173 [Source code](https://capi-samples.github.io/kubecon-na-2022-tutorial/) 174 175 **Code walkthroughs** 176 177 * [CAPD Deep Dive - March 2021 v1alpha4](https://youtu.be/67kEp471MPk) 178 * [API conversion code walkthrough - January 2022](https://www.youtube.com/watch?v=Mk14N4SelNk) 179 180 **Let's chat about ...** 181 182 We are currently hosting "Let's chat about ..." sessions where we are talking about topics relevant to 183 contributors and users of the Cluster API project. For more details and an up-to-date list of recordings of past sessions please 184 see [Let's chat about ...](https://github.com/kubernetes-sigs/cluster-api/discussions/6106). 185 186 * [Local CAPI development and debugging with Tilt (EMEA/Americas) - February 2022](https://www.youtube.com/watch?v=tEIRGmJahWs) 187 * [Local CAPI development and debugging with Tilt (APAC/EMEA) - February 2022](https://www.youtube.com/watch?v=CM-dotO2nSU) 188 * [Code structure & Makefile targets (EMEA/Americas) - February 2022](https://www.youtube.com/watch?v=_prbOnziCJw) 189 * [Code structure & Makefile targets (APAC/EMEA) - February 2022](https://www.youtube.com/watch?v=Y6Gws65H1tE)