This is unreleased documentation for Cluster API v0.28-dev.

Provider Test Suite

This section contains information on how you can leverage the existing E2E suite to integrate any CAPI provider with Turtles and verify that the provisioning and importing of clusters works as expected. The validation performs the following actions:

  1. Create a managment cluster.

  2. Install Rancher and Turtles with all prerequisites.

  3. Install additional CAPIProviders.

  4. Apply a CAPI Cluster template to provision a new Cluster.

  5. Verify that the CAPI Cluster is initialized correctly.

  6. Verify that the CAPI Cluster has been successfully imported in Rancher.

  7. Verify that the CAPI Cluster can be deleted correctly.

The test suite can be used for certification of providers not listed in the Certification table, as detailed in Provider Certification.

How to Use It

The Turtles Integration Suite Example repository contains an example on how to integrate a given CAPI provider with SUSE® Rancher Prime Cluster API and applies a series of checks to validate the basic CAPI provisioning functionality and cluster import into Rancher.

Before execution

If getting started with the test suite, we recommend you keep your configuration as simple as possible and limit the number of customizations so you can understand the process and its configuration details. You can start your journey on provider testing by cloning the sample repository:

git clone https://github.com/rancher/turtles-integration-suite-example.git

The simplest test execution you can run creates a local environment that does not use an internet-facing endpoint. This limits the checks to only local downstream clusters (effectively, CAPI clusters provisioned via CAPD) but it is enough to run the example integration:

make test-e2e

When checking the integration with other infrastructure providers (e.g. providers for cloud vendors), you will have to make your Rancher instance available via endpoint to the downstream clusters, which are no longer in your local environment. The MANAGEMENT_CLUSTER_ENVIRONMENT variable can be configured to provision clusters in other environments, like eks. For more information consult the test framework documentation. Alternatively it is possible to implement the ClusterProvider interface for more freedom on how to setup the test management cluster.

Basic Workflow

The following is a more detailed description of what each validation step performs:

  1. Create a managment cluster.

    • This is not a Turtles specific requirement as, when working with CAPI, there needs to be a management cluster that will be used to create resources that represent downstream clusters. This is the main part of the test environment and, depending on the environment variables passed to the test suite, it can either be hosted locally (using isolated-kind) or in the cloud (eks).

  2. Install Rancher and Turtles with all prerequisites.

    • Turtles is a default Rancher extension and, as such, it will be installed and managed by Rancher. Rancher Manager will be run in the management cluster we created in the first step and the Turtles chart will be installed automatically when Rancher is available. If using an internet-facing configuration, an ingress controller is needed to make Rancher reachable from an outside network (e.g. cluster deployed in the cloud). This is required for the cattle-cluster-agent running on the downstream cluster to contact Rancher using the server-url Setting, during the cluster import phase.

  3. Install additional CAPIProviders.

    • Before tests can start, the CAPI Providers (infrastructure, bootstrap, control plane, etc.) need to be installed first. All providers must be installed using the Turtles CAPIProvider API. This ensures the provider can be installed correctly and the provider lifecycle can be managed by Turtles. When deploying any of the already certified providers, make sure to pin the correct version according to the table.

  4. Apply a CAPI Cluster template to provision a new Cluster.

    • Once all required providers are deployed and ready, the CAPI Cluster can be created on the management cluster to start the provisioning process.

  5. Verify that the CAPI Cluster is initialized correctly.

    • The first cluster validation ensures the control plane is running and serving requests consuming the CAPI generated kubeconfig. Additionally this step will wait for the ControlPlaneInitialized status to be true.

  6. Verify that the CAPI Cluster has been successfully imported in Rancher.

    • After the control plane is initialized, Turtles should import the CAPI Cluster into Rancher. During this phase, a new management.cattle.io.Cluster will be created on the management cluster. The cattle-cluster-agent and fleet-agent will be deployed on the downstream cluster. Validation ensures that both agents are registered correctly to Rancher.

  7. Verify that the CAPI Cluster can be deleted correctly.

    • The last step in the validation process ensures that the CAPI Cluster can be deleted as expected, and no finalizers are preventing resources from being deleted indefinitely.