Links

Introduction

Overview

Crossplane Provider for IONOS Cloud gives the ability to manage IONOS Cloud infrastructure directly from Kubernetes. Crossplane extends a Kubernetes cluster to support orchestrating any infrastructure or managed service. Providers extend Crossplane to enable infrastructure resource provisioning of specific API.
The crossplane-provider-ionoscloud repository is the Crossplane infrastructure provider for IONOS Cloud. The provider that is built from the source code from the repository can be installed into a Crossplane control plane and adds the following new functionality:
  • Custom Resource Definitions (CRDs) that model IONOS Cloud infrastructure and services (e.g. Compute Engine, Kubernetes, Database As a Service Postgres, etc.)
  • Controllers to provision these resources in IONOS Cloud based on the users desired state captured in CRDs they create
  • Implementations of Crossplane's portable resource abstractions, enabling IONOS Cloud resources to fulfill a user's general need for cloud services

Getting Started and Documentation

For getting started with Crossplane usage and concepts, see the official Documentation.
For getting started with Crossplane Provider for IONOS Cloud, check out this step-by-step guide which provides details about the provisioning of a Postgres Cluster in IONOS Cloud.

Prerequisites

To use the Crossplane Provider IONOS Cloud you will need an IONOS Cloud account, the same account you may use with DCD or other config management tools.
Make sure you have a Kubernetes cluster and installed a Self-Hosted Crossplane into a namespace called crossplane-system.
In the examples guide, you can find information of how to install a Kubernetes Cluster locally (using kind or other lightweight Kubernetes) and Crossplane.

Authentication on IONOS Cloud

Crossplane Provider for IONOS Cloud requires credentials to be provided in order to authenticate to the IONOS Cloud APIs. This can be done using a base64-encoded static credentials in a Kubernetes Secret.

Environment Variables

Crossplane Provider IONOS Cloud uses a ProviderConfig in order to setup credentials via Secrets. You can use environments variables when creating the ProviderConfig resource.
Environment Variable
Description
IONOS_USERNAME
Specify the username used to login, to authenticate against the IONOS Cloud API
IONOS_PASSWORD
Specify the password used to login, to authenticate against the IONOS Cloud API
IONOS_TOKEN
Specify the token used to login, if a token is being used instead of username and password
IONOS_API_URL
Specify the API URL. It will overwrite the API endpoint default value api.ionos.com. Note: the host URL does not contain the /cloudapi/v6 path, so it should _ not_ be included in the IONOS_API_URL environment variable

Create Provider Secret

  • Using username and password:
export BASE64_PW=$(echo -n "${IONOS_PASSWORD}" | base64)
kubectl create secret generic --namespace crossplane-system example-provider-secret --from-literal=credentials="{\"user\":\"${IONOS_USERNAME}\",\"password\":\"${BASE64_PW}\"}"
  • Using token:
kubectl create secret generic --namespace crossplane-system example-provider-secret --from-literal=credentials="{\"token\":\"${IONOS_TOKEN}\"}"
Note: You can overwrite the default IONOS Cloud API endpoint, by setting the following option in credentials struct: credentials="{\"host_url\":\"${IONOS_API_URL}\"}".
Note: You can also set the IONOS_API_URL environment variable in the ControllerConfig of the provider globally for all resources. The following snipped shows how to set it globally in the ControllerConfig:
cat <<EOF | kubectl apply -f -
apiVersion: pkg.crossplane.io/v1alpha1
kind: ControllerConfig
metadata:
name: overwrite-ionos-api-url
spec:
env:
- name: IONOS_API_URL
value: "${IONOS_API_URL}"
EOF

Configure the Provider

We will create the following ProviderConfig to configure credentials for Crossplane Provider for IONOS Cloud:
cat <<EOF | kubectl apply -f -
apiVersion: ionoscloud.crossplane.io/v1alpha1
kind: ProviderConfig
metadata:
name: example
spec:
credentials:
source: Secret
secretRef:
namespace: crossplane-system
name: example-provider-secret
key: credentials
EOF

Installation

Install Provider

Install Provider using:
cat <<EOF | kubectl apply -f -
apiVersion: pkg.crossplane.io/v1
kind: Provider
metadata:
name: provider-ionos
spec:
package: ghcr.io/ionos-cloud/crossplane-provider-ionoscloud:latest
EOF

Check installation

Check if the Crossplane Provider IONOS Cloud is installed and healthy:
kubectl get providers
You should be able to see pods running in the crossplane-system namespace:
kubectl get pods -n crossplane-system

Provision Resources on IONOS Cloud

Now that you have the IONOS Cloud Provider configured, you can provision resources on IONOS Cloud directly from your Kubernetes Cluster, using Custom Resource Definitions(CRDs). All CRDs are Cluster Scoped (not being created in only one specific namespace, but on the entire cluster).
Check below to see an up-to-date list of the CRDs and corresponding IONOS Cloud Resources that Crossplane Provider IONOS Cloud supports as Managed Resources:

Compute Engine Managed Resources

Compute Engine Resources Custom Resource Definitions

RESOURCES IN IONOS CLOUD
CUSTOM RESOURCE DEFINITION
IPBlocks
ipblocks.compute.ionoscloud.crossplane.io
Datacenters
datacenters.compute.ionoscloud.crossplane.io
Servers
servers.compute.ionoscloud.crossplane.io
Volumes
volumes.compute.ionoscloud.crossplane.io
Lans
lans.compute.ionoscloud.crossplane.io
NICs
nics.compute.ionoscloud.crossplane.io
FirewallRules
firewallrules.compute.ionoscloud.crossplane.io
IPFailovers
ipfailovers.compute.ionoscloud.crossplane.io
See more details here.

Application Load Balancer Managed Resources

Application Load Balancer Resources Custom Resource Definitions

RESOURCES IN IONOS CLOUD
CUSTOM RESOURCE DEFINITION
ApplicationLoadBalancer
applicationloadbalancer.alb.ionoscloud.crossplane.io
ForwardingRule
forwardingrule.alb.ionoscloud.crossplane.io
TargetGroup
targetgroup.alb.ionoscloud.crossplane.io
See more details here.

Kubernetes Managed Resources

Kubernetes Resources Custom Resource Definitions

RESOURCES IN IONOS CLOUD
CUSTOM RESOURCE DEFINITION
K8s Clusters
clusters.k8s.ionoscloud.crossplane.io
K8s NodePools
nodepools.k8s.ionoscloud.crossplane.io
See more details here.

Backup Managed Resources

Backup Resources Custom Resource Definitions

RESOURCES IN IONOS CLOUD
CUSTOM RESOURCE DEFINITION
BackupUnit
backupunits.backup.ionoscloud.crossplane.io
See more details here.

DBaaS Postgres Managed Resources

DBaaS Postgres Resources Custom Resource Definitions

RESOURCES IN IONOS CLOUD
CUSTOM RESOURCE DEFINITION
DBaaS Postgres Clusters
postgresclusters.dbaas.ionoscloud.crossplane.io
See more details here.

References

References are used in order to reference other resources on which the new resources are dependent. Using referenced resources, the user can create for example, a datacenter and a lan using one command, without to manually update the lan CR specification file with the required datacenter ID.
The references are resolved only once, when the resource is created, and the resolvers are generated using crossplane-tools.
Example:
datacenterConfig:
datacenterIdRef:
name: <datacenter_CR_name>
The user can set the datacenter ID directly, using:
datacenterConfig:
datacenterId: <datacenter_ID>
Note: If both the datacenterId and the datacenterIdRef fields are set, the datacenterId value has priority.

Compositions and Claims

Composite Resources are designed to help you build your own platform and mix-and-match schemas for different providers. You define the schema of your Composite Resource(XR) and teach Crossplane which Managed Resources(CRs or Custom Resources) it should create when someone creates the XR.

Steps

Define Composite Resources

First step is to define the CompositeResourceDefinition so that Crossplane knows which XRs you would like to create and what fields that XRs should have. In the example provided, this is done in the definition file.

Configure Compositions

Next step is to teach Crossplane what to do when a Composite Resource is created. Compositions are linking an XR with one or multiple CRs (ipblocks, postgresclusters, nodepools, clusters, etc). Basically, the user controls the CRs for IONOS Cloud Resources via XRs: when an XR is created, updated or deleted, according to the Composition configured, Crossplane will create, update, or delete CRs. In the example provided, this is done in the composition file.

Claim Composite Resources

After defining Composite Resources and configuring Compositions, the next step is to create Composite Resource Claims ( aka claims). A difference between and XRs and claims is that claims are namespaced scoped, while XRs are cluster scoped. Also, an XR contains references to the CRs, while claim contains reference to the corresponding XR. In the example provided, a claim is defined in the claim file, while an XR in composite file.

Example

An example for creating a Datacenter, a Kubernetes Cluster and a Kubernetes NodePool via Compositions and Claims can be found here.

More Details

More details about Composite Resources can be found here:

Name Uniqueness Support for IONOS Cloud Resources

The Crossplane Provider IONOS Cloud has support for --unique-names flag, in order to enable name uniqueness support for IONOS Cloud Resources. If the --unique-names option is set, the Crossplane Provider for IONOS Cloud will check if a resource with the same name already exists. If multiple resources with the specified name are found, an error is thrown. If a single resource with the specified name is found, Crossplane Provider will perform an extra step and check if the immutable parameters are as expected. If the resource has the specified name, but different immutable parameters, an error is thrown. If no resource with the specified name is found, a new resource will be created.
Note: Resources will have unique names at their level, e.g. k8s clusters will have unique name per account, k8s node pools will have unique name per k8s cluster.
You can create a ControllerConfig:
cat <<EOF | kubectl apply -f -
apiVersion: pkg.crossplane.io/v1alpha1
kind: ControllerConfig
metadata:
name: provider-config
spec:
args:
- --unique-names
EOF
And reference it from the Provider:
cat <<EOF | kubectl apply -f -
apiVersion: pkg.crossplane.io/v1
kind: Provider
metadata:
name: provider-ionos
spec:
package: ghcr.io/ionos-cloud/crossplane-provider-ionoscloud:latest
controllerConfigRef:
name: provider-config
EOF

Debug Mode

Provider Logs

The Crossplane Provider IONOS Cloud has support for --debug flag.
You can create a ControllerConfig:
cat <<EOF | kubectl apply -f -
apiVersion: pkg.crossplane.io/v1alpha1
kind: ControllerConfig
metadata:
name: debug-config
spec:
args:
- --debug
EOF
And reference it from the Provider:
cat <<EOF | kubectl apply -f -
apiVersion: pkg.crossplane.io/v1
kind: Provider
metadata:
name: provider-ionos
spec:
package: ghcr.io/ionos-cloud/crossplane-provider-ionoscloud:latest
controllerConfigRef:
name: debug-config
EOF
In order to see logs of the Crossplane Provider IONOS Cloud controller's pod, use:
kubectl -n crossplane-system logs <name-of-ionoscloud-provider-pod>
More details here.

Testing

Crossplane Provider IONOS Cloud has end-to-end integration tests for the resources supported. See more details here.

Releases

Releases can be made on Crossplane Provider IONOS Cloud via tags or manual action of the CD workflow. The CD workflow will test and release the images. It will release images for controller and provider, with 2 tags each: latest and the corresponding release tag.

Conclusion

Main advantages of the Crossplane Provider IONOS Cloud are:
  • provisioning resources in IONOS Cloud from a Kubernetes Cluster - using CRDs (Custom Resource Definitions);
  • maintaining a healthy setup using controller and reconciling loops;
  • can be installed on a Crossplane Control Plane and add new functionality for the user along with other Cloud Providers.
There is always room for improvements, and we welcome feedback and contributions. Feel free to open an issue or PR with your idea.
Last modified 1yr ago