sigs.k8s.io/cluster-api@v1.7.1/docs/book/src/developer/architecture/controllers/cluster.md (about)

     1  # Cluster Controller
     2  
     3  ![](../../../images/cluster-admission-cluster-controller.png)
     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 eventually have its `spec.controlPlaneEndpoint` set by the user/controller.
    26  
    27  The Cluster controller bubbles up `spec.controlPlaneEndpoint` and `status.ready` into `status.infrastructureReady` from the infrastructureCluster.
    28  
    29  #### Required `status` fields
    30  
    31  The InfrastructureCluster object **must** have a `status` object.
    32  
    33  The `spec` object **must** have the following fields defined:
    34  
    35  - `controlPlaneEndpoint` - identifies the endpoint used to connect to the target's cluster apiserver.
    36  
    37  The `status` object **must** have the following fields defined:
    38  
    39  - `ready` - a boolean field that is true when the infrastructure is ready to be used.
    40  
    41  #### Optional `status` fields
    42  
    43  The `status` object **may** define several fields that do not affect functionality if missing:
    44  
    45  * `failureReason` - is a string that explains why a fatal error has occurred, if possible.
    46  * `failureMessage` - is a string that holds the message contained by the error.
    47  * `failureDomains` - is a `FailureDomains` type indicating the failure domains that machines should be placed in. `FailureDomains`
    48  is a map, defined as `map[string]FailureDomainSpec`. A unique key must be used for each `FailureDomainSpec`.
    49  `FailureDomainSpec` is defined as:
    50      - `controlPlane` (bool): indicates if failure domain is appropriate for running control plane instances.
    51      - `attributes` (`map[string]string`): arbitrary attributes for users to apply to a failure domain.
    52  
    53  Example:
    54  ```yaml
    55  kind: MyProviderCluster
    56  apiVersion: infrastructure.cluster.x-k8s.io/v1alpha3
    57  spec:
    58    controlPlaneEndpoint:
    59      host: example.com
    60      port: 6443
    61  status:
    62      ready: true
    63  ```
    64  
    65  ### Secrets
    66  
    67  If you are using the kubeadm bootstrap provider you do not have to provide any Cluster API secrets. It will generate
    68  all necessary CAs (certificate authorities) for you.
    69  
    70  However, if you provide a CA for the cluster then Cluster API will be able to generate a kubeconfig secret.
    71  This is useful if you have a custom CA or do not want to use the bootstrap provider's generated self-signed CA.
    72  
    73  | Secret name | Field name | Content |
    74  |:---:|:---:|:---:|
    75  |`<cluster-name>-ca`|`tls.crt`|base64 encoded TLS certificate in PEM format|
    76  |`<cluster-name>-ca`|`tls.key`|base64 encoded TLS private key in PEM format|
    77  
    78  Alternatively can entirely bypass Cluster API generating a kubeconfig entirely if you provide a kubeconfig secret
    79  formatted as described below.
    80  
    81  | Secret name | Field name | Content |
    82  |:---:|:---:|:---:|
    83  |`<cluster-name>-kubeconfig`|`value`|base64 encoded kubeconfig|