The task of a provider implementation is building a bridge between the machine-controller and a cloud API. This mainly means creating, configuring, retrieving, and deleting of machine instances. To do so a defined interface has to be implemented and integrated. Additionally the new provider has to provide an example manifest and finally integrated into the CI.
The interface a cloud provider has to implement is located in the package
github.com/kubermatic/machine-controller/pkg/cloudprovider/cloud. It is named Provider and
defines a small set of functions:
AddDefaults(spec v1alpha1.MachineSpec) (v1alpha1.MachineSpec, error)
AddDefaults will read the MachineSpec and checks the defined values for needed fields. In case
they are not set or invalid defaults can be applied.
Validate(spec v1alpha1.MachineSpec) error
Validate validates the given machine’s specification. In case of any error a terminal error
should be set. See v1alpha1.MachineStatus for more info.
Get(machine *v1alpha1.Machine) (instance.Instance, error)
Get retrieves a node that is associated with the given machine. Note that this method can return a
so called terminal error, which indicates that a manual interaction is required to recover from
this state. See v1alpha1.MachineStatus for more info and errors.TerminalError type.
In case the instance cannot be found, the returned error has to be
github.com/kubermatic/machine-controller/pkg/cloudprovider/errors.ErrInstanceNotFound for proper
evaluation by the machine-controller.
GetCloudConfig(spec v1alpha1.MachineSpec) (config string, name string, err error)
GetCloudConfig will return the cloud provider specific cloud-config, which gets consumed by the
kubelet.
Create(machine *v1alpha1.Machine, data *cloud.MachineCreateDeleteData, userdata string) (instance.Instance, error)
Create creates a cloud instance according to the given machine.
Cleanup(machine *v1alpha1.Machine, data *cloud.MachineCreateDeleteData) (bool, error)
Cleanup will delete the instance associated with the machine and all associated resources. If all
resources have been cleaned up, true will be returned. In case the cleanup involves asynchronous
deletion of resources & those resources are not gone yet, false should be returned. This is to
indicate that the cleanup is not done, but needs to be called again at a later point.
MachineMetricsLabels(machine *v1alpha1.Machine) (map[string]string, error)
MachineMetricsLabels returns labels used for the Prometheus metrics about created machines, e.g.
instance type, instance size, region or whatever the provider deems interesting. Should always
return a “size” label. This should not do any API calls to the cloud provider.
MigrateUID(machine *v1alpha1.Machine, new types.UID) error
MigrateUID is called when the controller migrates types and the UID of the machine object changes.
All cloud providers that use Machine.UID to uniquely identify resources must implement this.
SetMetricsForMachines(machines v1alpha1.MachineList) error
SetMetricsForMachines allows providers to provide provider-specific metrics. This may be
implemented as no-op.
Provider implementations are located in individual packages in
github.com/kubermatic/machine-controller/pkg/cloudprovider/provider. Here see e.g. hetzner as a
straight-forward and easily understandable implementation. Other implementations are there too,
helping to understand the needed tasks inside and around the Provider interface implementation.
When retrieving the individual configuration from the provider specification a type for unmarshalling
is needed. Here first the provider configuration is read and based on it the individual values of
the configuration are retrieved. Typically the access data (token, ID/key combination, document with
all information) alternatively can be passed via an environment variable. According methods of the
used providerconfig.ConfigVarResolver do support this.
For creation of new machines the support of the possible information has to be checked. The
machine-controller supports CentOS, Flatcar and Ubuntu. In case one or more aren’t supported
by the cloud infrastructure the error providerconfig.ErrOSNotSupported has to be returned.
For each cloud provider a unique string constant has to be defined in file types.go in package
github.com/kubermatic/machine-controller/pkg/providerconfig. Registration based on this constant
is done in file provider.go in package github.com/kubermatic/machine-controller/pkg/cloudprovider.
For documentation of the different configuration options an according example manifest with helpful
comments has to be added to github.com/kubermatic/machine-controller/examples. The naming scheme is
<package-name>-machinedeployment.yaml.
Like the example manifest a more concrete one named machinedeployment-<package-name>.yaml has to
be added to github.com/kubermatic/machine-controller/test/e2e/provisioning/testdata. Additionally
file all_e2e_test.go in package github.com/kubermatic/machine-controller/test/e2e/provisioning
contains all provider tests. Like the existing ones the test for the new provider has to be placed
here. Mainly it’s the retrieval of test data, especially the access data, from the environment and
the starting of the test scenarios.
Now the provider is ready to be added into the project for CI tests.