|
1 | 1 | # Cluster Controller |
2 | 2 |
|
3 | | - |
4 | | - |
5 | | -The Cluster controller's main responsibilities are: |
6 | | - |
7 | | -* Setting an OwnerReference on the infrastructure object referenced in `Cluster.spec.infrastructureRef`. |
8 | | -* Setting an OwnerReference on the control plane object referenced in `Cluster.spec.controlPlaneRef`. |
9 | | -* Cleanup of all owned objects so that nothing is dangling after deletion. |
10 | | -* Keeping the Cluster's status in sync with the infrastructureCluster's status. |
11 | | -* Creating a kubeconfig secret for [workload clusters](../../../reference/glossary.md#workload-cluster). |
12 | | - |
13 | | -## Contracts |
14 | | - |
15 | | -### Infrastructure Provider |
16 | | - |
17 | | -The general expectation of an infrastructure provider is to provision the necessary infrastructure components needed to |
18 | | -run a Kubernetes cluster. As an example, the AWS infrastructure provider, specifically the AWSCluster reconciler, will |
19 | | -provision a VPC, some security groups, an ELB, a bastion instance and some other components all with AWS best practices |
20 | | -baked in. Once that infrastructure is provisioned and ready to be used the AWSMachine reconciler takes over and |
21 | | -provisions EC2 instances that will become a Kubernetes cluster through some bootstrap mechanism. |
22 | | - |
23 | | -The cluster controller will set an OwnerReference on the infrastructureCluster. This controller should normally take no action during reconciliation until it sees the OwnerReference. |
24 | | - |
25 | | -An infrastructureCluster controller is expected to either supply a controlPlaneEndpoint (via its own `spec.controlPlaneEndpoint` field), |
26 | | -or rely on `spec.controlPlaneEndpoint` in its parent [Cluster](./cluster.md) object. |
| 3 | +The Cluster controller is responsible for reconciling the Cluster resource. |
27 | 4 |
|
28 | | -If an endpoint is not provided, the implementer should exit reconciliation until it sees `cluster.spec.controlPlaneEndpoint` populated. |
| 5 | +In order to allow Cluster provisioning on different type of infrastructure, The Cluster resource references |
| 6 | +an InfraCluster object, e.g. AWSCluster, GCPCluster etc. |
29 | 7 |
|
30 | | -The Cluster controller bubbles up `spec.controlPlaneEndpoint` and `status.ready` into `status.infrastructureReady` from the infrastructureCluster. |
| 8 | +The [InfraCluster resource contract](../../providers/contracts/infra-cluster.md) defines a set of rules a provider is expected to comply in order to allow |
| 9 | +the expected interactions with the Cluster controller. |
31 | 10 |
|
32 | | -#### Required `status` fields |
| 11 | +Among those rules: |
| 12 | +- InfraCluster SHOULD report a [controlplane endpoint](../../providers/contracts/infra-cluster.md#infracluster-control-plane-endpoint) for the Cluster |
| 13 | +- InfraCluster SHOULD report available [failure domains](../../providers/contracts/infra-cluster.md#infracluster-failure-domains) where machines should be placed in |
| 14 | +- InfraCluster MUST report when Cluster's infrastructure is [fully provisioned](../../providers/contracts/infra-cluster.md#infracluster-initialization-completed) |
| 15 | +- InfraCluster SHOULD report [conditions](../../providers/contracts/infra-cluster.md#infracluster-conditions) |
| 16 | +- InfraCluster SHOULD report [terminal failures](../../providers/contracts/infra-cluster.md#infracluster-terminal-failures) |
33 | 17 |
|
34 | | -The InfrastructureCluster object **must** have a `status` object. |
| 18 | +Similarly, in order to support different solutions for control plane management, The Cluster resource references |
| 19 | +an ControlPlane object, e.g. KubeadmControlPlane, EKSControlPlane etc. |
35 | 20 |
|
36 | | -The `spec` object **must** have the following fields defined: |
| 21 | +The [ControlPlane resource contract](../../providers/contracts/control-plane.md) defines a set of rules a provider is expected to comply in order to allow |
| 22 | +the expected interactions with the Cluster controller. |
37 | 23 |
|
38 | | -- `controlPlaneEndpoint` - identifies the endpoint used to connect to the target's cluster apiserver. |
| 24 | +Considering all the info above, the Cluster controller's main responsibilities are: |
39 | 25 |
|
40 | | -The `status` object **must** have the following fields defined: |
41 | | - |
42 | | -- `ready` - a boolean field that is true when the infrastructure is ready to be used. |
43 | | - |
44 | | -#### Optional `status` fields |
45 | | - |
46 | | -The `status` object **may** define several fields that do not affect functionality if missing: |
47 | | - |
48 | | -* `failureReason` - is a string that explains why a fatal error has occurred, if possible. |
49 | | -* `failureMessage` - is a string that holds the message contained by the error. |
50 | | -* `failureDomains` - is a `FailureDomains` type indicating the failure domains that machines should be placed in. `FailureDomains` |
51 | | -is a map, defined as `map[string]FailureDomainSpec`. A unique key must be used for each `FailureDomainSpec`. |
52 | | -`FailureDomainSpec` is defined as: |
53 | | - - `controlPlane` (bool): indicates if failure domain is appropriate for running control plane instances. |
54 | | - - `attributes` (`map[string]string`): arbitrary attributes for users to apply to a failure domain. |
| 26 | +* Setting an OwnerReference on the infrastructure object referenced in `Cluster.spec.infrastructureRef`. |
| 27 | +* Setting an OwnerReference on the control plane object referenced in `Cluster.spec.controlPlaneRef`. |
| 28 | +* Keeping the Cluster's status in sync with the InfraCluster and ControlPlane's status. |
| 29 | +* If no ControlPlane object is referenced, create a kubeconfig secret for [workload clusters](../../../reference/glossary.md#workload-cluster). |
| 30 | +* Cleanup of all owned objects so that nothing is dangling after deletion. |
55 | 31 |
|
56 | | -Note: once any of `failureReason` or `failureMessage` surface on the cluster who is referencing the infrastructureCluster object, |
57 | | -they cannot be restored anymore (it is considered a terminal error; the only way to recover is to delete and recreate the cluster). |
| 32 | + |
58 | 33 |
|
59 | | -Example: |
60 | | -```yaml |
61 | | -kind: MyProviderCluster |
62 | | -apiVersion: infrastructure.cluster.x-k8s.io/v1alpha3 |
63 | | -spec: |
64 | | - controlPlaneEndpoint: |
65 | | - host: example.com |
66 | | - port: 6443 |
67 | | -status: |
68 | | - ready: true |
69 | | -``` |
| 34 | +### Kubeconfig Secrets |
70 | 35 |
|
71 | | -### Secrets |
| 36 | +In order to create a kubeconfig secret, it is required to have a certificate authority (CA) for the cluster. |
72 | 37 |
|
73 | 38 | If you are using the kubeadm bootstrap provider you do not have to provide any Cluster API secrets. It will generate |
74 | | -all necessary CAs (certificate authorities) for you. |
| 39 | +all necessary CAs for you. |
75 | 40 |
|
76 | | -However, if you provide a CA for the cluster then Cluster API will be able to generate a kubeconfig secret. |
77 | | -This is useful if you have a custom CA or do not want to use the bootstrap provider's generated self-signed CA. |
| 41 | +As alternative users can provide custom CA as described in [Using Custom Certificates](../../../tasks/certs/using-custom-certificates.md). |
78 | 42 |
|
79 | | -| Secret name | Field name | Content | |
80 | | -|:---:|:---:|:---:| |
81 | | -|`<cluster-name>-ca`|`tls.crt`|base64 encoded TLS certificate in PEM format| |
82 | | -|`<cluster-name>-ca`|`tls.key`|base64 encoded TLS private key in PEM format| |
83 | | - |
84 | | -Alternatively can entirely bypass Cluster API generating a kubeconfig entirely if you provide a kubeconfig secret |
| 43 | +Last option, is to entirely bypass Cluster API kubeconfig generation by providing a kubeconfig secret |
85 | 44 | formatted as described below. |
86 | 45 |
|
87 | | -| Secret name | Field name | Content | |
88 | | -|:---:|:---:|:---:| |
89 | | -|`<cluster-name>-kubeconfig`|`value`|base64 encoded kubeconfig| |
| 46 | +| Secret name | Field name | Content | |
| 47 | +|:---------------------------:|:----------:|:-------------------------:| |
| 48 | +| `<cluster-name>-kubeconfig` | `value` | base64 encoded kubeconfig | |
| 49 | + |
| 50 | +Notes: |
| 51 | +- Also renewal of the above certificate should be taken care out of band. |
| 52 | +- This option does not prevent from providing a cluster CA which is required also for other purposes. |
0 commit comments