diff --git a/docs/book/provider_implementations/building_running_and_testing.md b/docs/book/provider_implementations/building_running_and_testing.md index 011ed944039a..8f1faa031257 100644 --- a/docs/book/provider_implementations/building_running_and_testing.md +++ b/docs/book/provider_implementations/building_running_and_testing.md @@ -14,12 +14,99 @@ The approach most Cluster API projects is using [a `Makefile` that uses `sed` to ## Deployment +### Cluster API + Before you can deploy the infrastructure controller, you'll need to deploy Cluster API itself. -You can clone `cluster-api` for the latest version, or just [use a precompiled manifest][install]. +You can [use a precompiled manifest][install], or clone [`cluster-api`][capi] and apply its manifests using `kustomize`. + +``` shell +cd cluster-api +kustomize build config/default | kubectl apply -f- +``` + +Check the status of the manager to make sure it's running properly + +```shell +$ kubectl describe -n capi-system pod | grep -A 5 Conditions +Conditions: + Type Status + Initialized True + Ready True + ContainersReady True + PodScheduled True +``` [install]: https://cluster-api.sigs.k8s.io/tasks/installation.html#install-cluster-api +### Your provider + +Now you can apply your provider as well: + +``` +$ cd cluster-api-provider-mailgun +$ kustomize build config/default | envsubst | kubectl apply -f- +$ kubectl describe -n cluster-api-provider-mailgun-system pod | grep -A 5 Conditions +Conditions: + Type Status + Initialized True + Ready True + ContainersReady True + PodScheduled True +``` + +{% hint style="info" %} +Tiltfile: Cluster API development requires a lot of iteration, and the "build, tag, push, update deployment" workflow can be very tedious. +[Tilt](https://tilt.dev) makes this process much simpler by watching for updates, then automatically building and deploying them. + +You can visit [some example repositories][capidev], but you can get started by writing out a yaml manifest and using the following [`Tiltfile`][tiltfile] +`kustomize build config/default | envsubst > capm.yaml` + +[capidev]: https://github.com/chuckha/capi-dev +[tiltfile]: https://docs.tilt.dev/tiltfile_concepts.html + +```starlark +allow_k8s_contexts('kubernetes-admin@luna') + +k8s_yaml('capm.yaml') + +docker_build('/cluster-api-controller-mailgun-amd64', '.') +``` + +You can then use Tilt to watch the logs coming off your container +{% endhint %} + + +## Your first Cluster + +Let's try our cluster out. We'll make some simple YAML: + +```yaml +apiVersion: cluster.x-k8s.io/v1alpha2 +kind: Cluster +metadata: + name: hello-mailgun +spec: + clusterNetwork: + pods: + cidrBlocks: ["192.168.0.0/16"] + infrastructureRef: + apiVersion: infrastructure.cluster.x-k8s.io/v1alpha3 + kind: MailgunCluster + name: hello-mailgun +--- +apiVersion: infrastructure.cluster.x-k8s.io/v1alpha3 +kind: MailgunCluster +metadata: + name: hello-mailgun +spec: + priority: "ExtremelyUrgent" + request: "Please make me a cluster, with sugar on top?" + requester: "cluster-admin@example.com" +``` +We apply it as normal with `kubectl apply -f .yaml`. +If all goes well, you should be getting an email to the address you configured when you set up your management cluster: +![An email from mailgun urgently requesting a cluster](cluster-email.png) diff --git a/docs/book/provider_implementations/cluster-email.png b/docs/book/provider_implementations/cluster-email.png new file mode 100644 index 000000000000..896d3b5afb93 Binary files /dev/null and b/docs/book/provider_implementations/cluster-email.png differ diff --git a/docs/book/provider_implementations/configure_and_deploy.md b/docs/book/provider_implementations/configure_and_deploy.md index d8ebaacc58f5..39bf0ce579ba 100644 --- a/docs/book/provider_implementations/configure_and_deploy.md +++ b/docs/book/provider_implementations/configure_and_deploy.md @@ -1,4 +1,4 @@ -# Configure and Deploy +# Configure ## YAML @@ -100,6 +100,45 @@ You can now (hopefully) generate your yaml! kustomize build config/default ``` +## RBAC Role + +The default [RBAC role][role] contains permissions for accessing your cluster infrastructure CRDs, but not for accessing Cluster API resources. +You'll need to add these to `config/rbac/role.yaml` + +[role]: https://kubernetes.io/docs/reference/access-authn-authz/rbac/ + +```diff +diff --git a/config/rbac/role.yaml b/config/rbac/role.yaml +index e9352ce..29008db 100644 +--- a/config/rbac/role.yaml ++++ b/config/rbac/role.yaml +@@ -6,6 +6,24 @@ metadata: + creationTimestamp: null + name: manager-role + rules: ++- apiGroups: ++ - cluster.x-k8s.io ++ resources: ++ - clusters ++ - clusters/status ++ verbs: ++ - get ++ - list ++ - watch ++- apiGroups: ++ - cluster.x-k8s.io ++ resources: ++ - machines ++ - machines/status ++ verbs: ++ - get ++ - list ++ - watch + - apiGroups: + - infrastructure.cluster.x-k8s.io + resources: +``` + ## EnvSubst {% hint style="info" %}