docs: add provider certif and e2e reuse sections

Signed-off-by: Carlos Salas <[email protected]>

docs/reference-guides/test-suite/intro.md

@@ -0,0 +1,14 @@
+---
+sidebar_position: 1
+---
+
+# Introduction
+
+This section contains information on how you can leverage the existing E2E suite to integrate any CAPI providers with Turtles and verify that the provisioning and importing of clusters works as expected. The validation performs the following actions:
+
+- Create a management cluster in the desired environment.
+- Install Rancher and Turtles with all prerequisites.
+- Install Gitea.
+- Run the suite that will create a git repo, apply cluster template using Fleet and verify the cluster is created and successfully imported in Rancher.
+
+The test suite can be used for certification of providers not listed in the [Certification table](../../reference-guides/providers/certified.md), as detailed in [Provider Certification](../../tasks/provider-certification/intro.md).

docs/reference-guides/test-suite/usage.md

@@ -0,0 +1,106 @@
+---
+sidebar_position: 1
+---
+
+# Test suite guide
+
+The main reference for reusing the test suite is [this repository](https://github.com/rancher-sandbox/turtles-integration-suite-example), which contains an example on how to integrate a given CAPI provider with Rancher Turtles and applies a series of checks based on a GitOps workflow.
+
+### Before execution
+
+The end-to-end test environment used in Turtles provides a number of configuration alternatives depending on the type of test you are running and the type of checks you are performing. 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-sandbox/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. You can simply run this local version by specifying that you intend to run it locally.
+
+```
+MANAGEMENT_CLUSTER_ENVIRONMENT="isolated-kind" make test
+```
+
+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 we used before, supports the following values:
+
+```
+MANAGEMENT_CLUSTER_ENVIRONMENT: "kind" # supported options are eks, isolated-kind, kind
+```
+
+`isolated-kind`, which is the value we used for local testing, and `kind` will deploy equivalent local environments. The difference is that `kind` will also configure a publicly accessible endpoint via [ngrok](https://ngrok.com/). You can get a free (limited) `ngrok` endpoint and use it for executing tests. Before running `make test`, you will also need to set the following environment variables:
+
+```
+NGROK_API_KEY: ""
+NGROK_AUTHTOKEN: ""
+```
+
+Using this configuration, during environment creation, the Rancher instance will be configured to be accessible via your `ngrok` endpoint and downstream clusters will be able to communicate with it.
+
+The [Other options](#other-options) section contains more information on what you can configure before execution.
+
+### Basic Workflow
+
+In previous sections we introduced the main actions performed in the sample test integration:
+
+#### Create a management cluster in the desired environment.
+
+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 `kind`) or in the cloud (`eks`).
+
+#### Install Rancher and Turtles with all prerequisites.
+
+Turtles is a Rancher extension and, as such, it needs a Rancher installation to be deployed. Rancher Manager will be run in the management cluster we created in the first step and the Turtles chart will be installed when Rancher is available. If using an internet-facing configuration, an ingress controller will make Rancher reachable from an outside network (e.g. cluster deployed in the cloud).
+
+#### Run the suite that will create a git repo, apply cluster template using Fleet and verify the cluster is created and successfully imported in Rancher.
+
+The main test suite, and the one used as an example, is based on a GitOps flow and uses [Fleet](https://github.com/rancher/fleet) as a GitOps orchestrator tool. Based on the cluster templates provided (you can check the ones that come with the example integration [here](https://github.com/rancher-sandbox/turtles-integration-suite-example/tree/main/suites/data/cluster-templates)), it will create the CAPI clusters defined in the YAML files. Once this/these cluster/s are available, they will be configured to be [imported into Rancher using Turtles](../../getting-started/create-first-cluster/using_fleet.md) and it will verify that the downstream cluster/s is/are accessible via Rancher. It will also check that deletion can be performed on downstream clusters and that they are no longer available in Rancher.
+
+### Other options
+
+You can take a look at the `config.yaml` [file](https://github.com/rancher-sandbox/turtles-integration-suite-example/blob/main/config/config.yaml) in the `turtles-integration-suite-example` repository, which contains a list of environment variables used during test environment deployment and test execution. The following is a truncated version of the above mentioned YAML file:
+
+```
+...
+variables:
+  CLUSTERCTL_BINARY_PATH: ""
+  USE_EXISTING_CLUSTER: "false"
+  SKIP_RESOURCE_CLEANUP: "false"
+  ARTIFACTS_FOLDER: "_artifacts"
+  MANAGEMENT_CLUSTER_ENVIRONMENT: "kind" # supported options are eks, isolated-kind, kind
+  RANCHER_VERSION: "v2.8.1"
+  KUBERNETES_VERSION: "v1.28.6"
+  KUBERNETES_MANAGEMENT_VERSION: "v1.27.0"
+  KUBERNETES_MANAGEMENT_AWS_REGION: "eu-west-2"
+  RKE2_VERSION: "v1.28.1+rke2r1"
+  TURTLES_PATH: "turtles/rancher-turtles"
+  TURTLES_REPO_NAME: "turtles"
+  TURTLES_URL: https://rancher.github.io/turtles
+  TURTLES_VERSION: "v0.10.0"
+  RANCHER_HOSTNAME: "localhost"
+  RANCHER_FEATURES: ""
+  RANCHER_PATH: "rancher-latest/rancher"
+  RANCHER_REPO_NAME: "rancher-latest"
+  RANCHER_URL: "https://releases.rancher.com/server-charts/latest"
+  CERT_MANAGER_URL: "https://charts.jetstack.io"
+  CERT_MANAGER_REPO_NAME: "jetstack"
+  CERT_MANAGER_PATH: "jetstack/cert-manager"
+  ...
+  ...
+  ...
+  HELM_BINARY_PATH: "helm"
+  HELM_EXTRA_VALUES_FOLDER: "/tmp"
+  # Additional setup for establishing rancher ingress
+  NGROK_REPO_NAME: "ngrok"
+  NGROK_URL: "https://ngrok.github.io/kubernetes-ingress-controller"
+  NGROK_PATH: "ngrok/kubernetes-ingress-controller"
+  NGROK_API_KEY: ""
+  NGROK_AUTHTOKEN: ""
+  GITEA_REPO_NAME: "gitea-charts"
+  GITEA_REPO_URL: "https://dl.gitea.com/charts/"
+  GITEA_CHART_NAME: "gitea"
+  GITEA_CHART_VERSION: "9.4.0"
+  ...
+```
+
+:::tip
+You can refer to [Turtles repository](https://github.com/rancher/turtles/tree/main/test/e2e#e2e-tests) to see all the suites and parameters you can use to customize test execution. We recommend doing this only if you are familiar with the deployment/configuration of the test environment and have specific integration requirements.
+:::
+

docs/tasks/provider-certification/intro.md

@@ -0,0 +1,26 @@
+---
+sidebar_position: 1
+---
+
+# What is a Certified Provider?
+
+As most CAPI providers are upstream projects maintained by the open community, there is no safe way to guarantee that any clusters provisioned with a given provider can be imported into Rancher via Turtles. However, we do implement a certification process for those providers that:
+- Are actively tested as part of our E2E suites.
+- These tests are kept up-to-date to validate recent versions of the provider.
+- Satisfy the prerequisites in the certification process. 
+
+## Certify your custom provider
+
+Additionally, if you are a provider developer or simply want to use a different provider that is not listed as certified, you can [reuse](../../reference-guides/test-suite/intro.md) the existing Turtles E2E suite to get started with the certification status request or simply verify that Turtles is a viable solution for you to use Rancher and CAPI together. You can read about the certification process and requirements in the [Provider Certification Guide](./process.md).
+
+#### Why would I want to validate my provider?
+
+The number of CAPI providers keeps growing and the community is coming up with new projects for different infrastructure hosts. This openness helps enrich the CAPI ecosystem but makes it impossible to control and test all providers Turtles will work with across the whole CAPI project. Developers of Turtles will maintain a [list of certified providers](../../reference-guides/providers/certified.md) that are actively tested and validated by CI mechanisms but this list will be limited to key and well-known providers. That is why we encourage users of providers not listed to reuse Turtles' test suite and validate the integration between the provider and Turtles.
+
+#### Can I use Turtles with an uncertified provider?
+
+Turtles is a project that aims to be agnostic and integrate with the whole CAPI ecosystem and you are free to use it without validating any providers. Chances are you will probably find no issues with most upstream projects.
+
+#### What is the difference between certified and supported?
+
+As CAPI providers are projects maintained by the Kubernetes community, we cannot guarantee support for a given provider. This is why we opt for focusing on constant validation of [Certified Providers](../../reference-guides/providers/certified.md) and offer users the possibility of integrating with the existing test suite to verify their providers of choice.

docs/tasks/provider-certification/process.md

@@ -0,0 +1,36 @@
+---
+sidebar_position: 1
+---
+
+# Provider Certification Guide
+
+The process of certification is based on verifying Rancher Turtles integration with CAPI providers. To simplify this task, we prepared a generic test that validates the provisioning and importing of a downstream CAPI cluster.
+
+:::tip
+We recommend you refer to this [example](https://github.com/rancher-sandbox/turtles-integration-suite-example) on how to use Turtles' test suite.
+:::
+
+## Test & Certify your provider
+
+The first step in validating that your provider is compatible with Turtles and that you can provision CAPI clusters and import them into Rancher via Turtles is to integrate with our test suite. We provide a repository with an [integration example](https://github.com/rancher-sandbox/turtles-integration-suite-example) that you can use as a reference for your integration.
+
+Turtles as a project contains a [number of suites](https://github.com/rancher/turtles/tree/main/test/e2e/suites) to verify different features and processes but, for provider certification, we require you to run only one test that uses a GitOps flow. Turtles is a project that integrates well with a GitOps approach for cluster provisioning and that is why this is our primary way of validating provider integration with Rancher. Running the full suite for a given CAPI provider will:
+
+- Create a management cluster in the desired environment.
+- Install Rancher and Turtles with all prerequisites.
+- Install Gitea.
+- Run the suite that will create a git repo, apply cluster template using Fleet and verify the cluster is created and successfully imported in Rancher.
+
+### Test configuration
+
+To successfully run the test suite, you will have to provide a number of environment variables. Some of these are agnostic, which means they are required for any provider you want to test, but others will be specific for the provider you are validating. Please, be aware of the particular specifications of the provider being tested, such as credentials, endpoints, etc.
+
+:::tip
+Next, we recommend you read the [Test suite guide](../../reference-guides/test-suite/usage.md)
+:::
+
+## Request for certification
+
+Integrating with Turtles' test suite and running checks on your provider of interest is enough to validate that it is compatible with Rancher Turtles. As it is not feasible for us to continuously test every CAPI provider, this certification workflow will allow you as a user to verify the expected functionality. However, as we are not actively testing newer iterations of the provider (with newer versions of Turtles), the support and guarantee for the given provider is limited, and you will be responsible for validating future releases.
+
+If, after successfully running checks on your provider, you would like to request it be added to the table of [Certified Providers](../../reference-guides/providers/certified.md), hence being added to the project's periodic E2E suite, you can request so via GitHub issue, using the [Request for Certification template](https://github.com/rancher/turtles/issues/new/choose). The proposal will be studied by the community and we will decide on the feasibility of adding the provider to the certification matrix.

sidebars.js

@@ -93,6 +93,15 @@ const sidebars = {
             'reference-guides/providers/addon-provider-fleet',
           ]
         },
+        {
+          type: 'category',
+          label: 'Test suite',
+          collapsed: true,
+          items: [
+            'reference-guides/test-suite/intro',
+            'reference-guides/test-suite/usage',
+          ]
+        },
       ],
     },
     {
@@ -125,6 +134,15 @@ const sidebars = {
             'tasks/maintenance/automigrate_to_v3_import'
           ]
         },
+        {
+          type: 'category',
+          label: 'Provider Certification',
+          collapsed: true,
+          items: [
+            'tasks/provider-certification/intro',
+            'tasks/provider-certification/process',
+          ]
+        },
       ]
     },
     {