You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This section contains several general notes about the update process.
38
+
39
+
### Provider types
40
+
41
+
This section reviews the changes to the provider types from v1alpha1 to v1alpha2.
42
+
43
+
#### Providers in v1alpha1
6
44
7
45
Providers in v1alpha1 wrap behavior specific to an environment to create the infrastructure and bootstrap instances into
8
46
Kubernetes nodes. Examples of environments that have integrated with Cluster API v1alpha1 include, AWS, GCP, OpenStack,
9
47
Azure, vSphere and others. The provider vendors in Cluster API's controllers, registers its own actuators with the
10
48
Cluster API controllers and runs a single manager to complete a Cluster API management cluster.
11
49
12
-
### v1alpha2
50
+
#### Providers in v1alpha2
13
51
14
52
v1alpha2 introduces two new providers and changes how the Cluster API is consumed. This means that in order to have a
15
53
complete management cluster that is ready to build clusters you will need three managers.
@@ -34,33 +72,194 @@ v1alpha1 "providers" have become Infrastructure providers. The Infrastructure pr
34
72
actual infrastructure (networking, load balancers, instances, etc) for a particular environment that can consume
35
73
bootstrap data to turn the infrastructure into a Kubernetes cluster.
36
74
37
-
## Actuators
38
-
39
-
### v1alpha1
40
-
41
-
Actuators are interfaces that the Cluster API controller calls. A provider pulls in the generic Cluster API controller
42
-
and then registers actuators to run specific infrastructure logic (calls to the provider cloud).
75
+
### `clusterctl`
43
76
44
-
### v1alpha2
77
+
The `clusterctl` program is also handled differently in v1alpha2.
45
78
46
-
Actuators are not used in this version. Cluster API's controllers are no longer shared across providers and therefore
47
-
they do not need to know about the actuator interface. Instead, providers communicate to each other via Cluster API's
48
-
central objects, namely Machine and Cluster. When a user modifies a Machine with a reference, each provider will notice
49
-
that update and respond in some way. For example, the Bootstrap provider may attach BootstrapData to a BootstrapConfig
50
-
which will then be attached to the Machine object via Cluster API's controllers or the Infrastructure provider may
51
-
create a cloud instance for Kubernetes to run on.
52
-
53
-
## `clusterctl`
54
-
55
-
### v1alpha1
79
+
#### `clusterctl` in v1alpha1
56
80
57
81
`clusterctl` was a command line tool packaged with v1alpha1 providers. The goal of this tool was to go from nothing to a
58
82
running management cluster in whatever environment the provider was built for. For example, Cluster-API-Provider-AWS
59
83
packaged a `clusterctl` that created a Kubernetes cluster in EC2 and installed the necessary controllers to respond to
60
84
Cluster API's APIs.
61
85
62
-
### v1alpha2
86
+
#### `clusterctl` in v1alpha2
63
87
64
88
`clusterctl` is likely becoming provider-agnostic meaning one clusterctl is bundled with Cluster API and can be reused
65
89
across providers. Work here is still being figured out but providers will not be packaging their own `clusterctl`
66
90
anymore.
91
+
92
+
### The new API groups
93
+
94
+
This section describes the API groups used by CAPI v1alpha2:
95
+
96
+
| Group | Description |
97
+
|---|---|
98
+
|`cluster.x-k8s.io`| The root CAPI API group |
99
+
|`infrastructure.cluster.x-k8s.io`| The API group for all resources related to CAPI infrastructure providers |
100
+
|`bootstrap.cluster.x-k8s.io`| The API group for all resources related to CAPI bootstrap providers |
101
+
102
+
Only SIG-sponsored providers may declare their components or resources to belong to any API group that ends with `x-k8s.io`.
103
+
104
+
Externally owned providers should use an appropriate API group for their ownership and would require additional RBAC rules to be configured and deployed for the common cluster-api components.
105
+
106
+
### Kubebuilder
107
+
108
+
While [kubebuilder](https://github.com/kubernetes-sigs/kubebuilder) v2 is available, the recommended approach for updating a CAPI provider to v1alpha2 is to stick with kubebuilder v1 during the update process and then reevaluate kubebuilder v2 after a successful migration to CAPI v1alpha2.
109
+
110
+
Please note if webhooks are required, it may necessitate migrating to kubebuilder v2 as part of the initial migration.
111
+
112
+
Additionally, kubebuilder v2 includes a lot of changes apart from just code, ex. the `Makefile`. If moving to v2 as part of this migration, please take a moment to read the kubebuilder book to understand all [the differences between v1 and v2](https://book.kubebuilder.io/migration/v1vsv2.html).
113
+
114
+
### Sample code and other examples
115
+
116
+
This document uses the CAPI provider for AWS ([CAPA](https://github.com/kubernetes-sigs/cluster-api-provider-aws)) for sample code and other examples.
117
+
118
+
## Create a branch for new v1alpha1 work
119
+
120
+
This document assumes the work required to update a provider to v1alpha2 will occur on the project's `master` branch. Therefore, the recommendation is to create a branch `release-MAJOR.MINOR` in the repository from the latest v1alpha1-based release. For example, if the latest release of a provider based on CAPI v1alpha1 was `v0.4.1` then the branch `release-0.4` should be created. Now the project's `master` branch is free to be a target for the work required to update the provider to v1alpha2, and fixes or backported features for the v1alpha1 version of the provider may target the `release-0.4` branch.
121
+
122
+
## Update the API group in the `PROJECT` file
123
+
124
+
Please update the `PROJECT` file at the root of the provider's repository to reflect the API group `cluster.x-k8s.io`:
125
+
126
+
```properties
127
+
version: "1"
128
+
domain: cluster.x-k8s.io
129
+
repo: sigs.k8s.io/cluster-api-provider-aws
130
+
```
131
+
132
+
## Create the provider's v1alpha2 resources
133
+
134
+
The new v1alpha2 types are located in `pkg/apis/infrastructure/v1alpha2`.
135
+
136
+
### The cluster and machine resources
137
+
138
+
Providers no longer store configuration and status data for clusters and machines in the CAPI `Cluster` and `Machine` resources. Instead, this information is stored in two, new, provider-specific CRDs:
Information related to kubeadm or certificates has been extracted and is now owned by the bootstrap provider and its corresponding resources, ex. `KubeadmConfig`.
160
+
161
+
#### Infrastructure provider cluster status fields
162
+
163
+
A CAPI v1alpha2 provider cluster status resource has two special fields, `ready` and `apiEndpoints`. For example, take the `AWSClusterStatus`:
164
+
165
+
```golang
166
+
// AWSClusterStatus defines the observed state of AWSCluster
167
+
typeAWSClusterStatusstruct {
168
+
Readybool`json:"ready"`
169
+
// APIEndpoints represents the endpoints to communicate with the control plane.
##### Infrastructure provider cluster status `ready`
176
+
177
+
A Provider`Cluster`'s `status` object must define a boolean field named `ready` and set the value to `true` only when the infrastructure required to provision a cluster is ready and available.
178
+
179
+
##### Infrastructure provider cluster status `apiEndpoints`
180
+
181
+
A Provider`Cluster`'s `status` object may optionally define a field named `apiEndpoints` that is a list of the following objects:
182
+
183
+
```golang
184
+
// APIEndpoint represents a reachable Kubernetes API endpoint.
185
+
typeAPIEndpointstruct {
186
+
// The hostname on which the API server is serving.
187
+
Hoststring`json:"host"`
188
+
189
+
// The port on which the API server is serving.
190
+
Portint`json:"port"`
191
+
}
192
+
```
193
+
194
+
If present, this field is automatically inspected in order to obtain an endpoint at which the Kubernetes cluster may be accessed.
195
+
196
+
## Create the infrastructure controllers
197
+
198
+
The actuator model from v1alpha1 has been replaced by the infrastructure controllers in v1alpha2:
### The infrastructure provider cluster controller
206
+
207
+
Instead of processing the CAPI `Cluster` resources like the old actuator model, the new provider cluster controller operates on the new provider `Cluster` CRD. However, the overall workflow should feel the same as the old cluster actuator. For example, take the `AWSCluster` controller's [reconcile function](https://github.com/kubernetes-sigs/cluster-api-provider-aws/blob/0a05127734a4fb955742b27c6e326a65821851ce/pkg/controller/awscluster/awscluster_controller.go#L105-L162), it:
208
+
209
+
1. Fetches the [`AWSCluster` resource](https://github.com/kubernetes-sigs/cluster-api-provider-aws/blob/0a05127734a4fb955742b27c6e326a65821851ce/pkg/controller/awscluster/awscluster_controller.go#L113-L121):
2. [Fetches the CAPI cluster resource](https://github.com/kubernetes-sigs/cluster-api-provider-aws/blob/0a05127734a4fb955742b27c6e326a65821851ce/pkg/controller/awscluster/awscluster_controller.go#L125-L133) that has a one-to-one relationship with the `AWSCluster` resource:
logger.Info("Waiting for Cluster Controller to set OwnerRef on AWSCluster")
231
+
return reconcile.Result{}, nil
232
+
}
233
+
```
234
+
235
+
If the `AWSCluster` resource does not have a corresponding CAPI cluster resource then the reconcile will be reissued once the OwnerRef is assigned to the `AWSCluster` resource by the CAPI controller, triggering a new reconcile event.
236
+
237
+
3. Uses a `defer` statement to [ensure the `AWSCluster` resource is always patched](https://github.com/kubernetes-sigs/cluster-api-provider-aws/blob/0a05127734a4fb955742b27c6e326a65821851ce/pkg/controller/awscluster/awscluster_controller.go#L148-L153) back to the API server:
4. Handles both [deleted and non-deleted](https://github.com/kubernetes-sigs/cluster-api-provider-aws/blob/0a05127734a4fb955742b27c6e326a65821851ce/pkg/controller/awscluster/awscluster_controller.go#L155-L161) clusters resources:
248
+
249
+
```golang
250
+
// Handle deleted clusters
251
+
if !awsCluster.DeletionTimestamp.IsZero() {
252
+
return reconcileDelete(clusterScope)
253
+
}
254
+
255
+
// Handle non-deleted clusters
256
+
return reconcileNormal(clusterScope)
257
+
```
258
+
259
+
### The infrastructure provider machine controller
260
+
261
+
The new provider machine controller is a slightly larger departure from the v1alpha1 machine actuator. This is because the machine actuator was based around a _Create_, _Read_, _Update_, _Delete_ (CRUD) model. Providers implementing the v1alpha1 machine actuator would implement each of those four functions. However, this was just an abstract way to represent a Kubernetes controller's reconcile loop.
262
+
263
+
The new, v1alpha2, provider machine controller merely takes the same CRUD model from the v1alpha1 machine actuator and applies it to a Kubernetes reconcile activity. The CAPI provider for vSphere (CAPV) actually includes a diagram that illustrates the v1alpha1 machine actuator CRUD operations as a reconcile loop.
0 commit comments