Skip to main content

Create Clusters

This topic describes how to use Replicated Compatibility Matrix to create and manage ephemeral clusters to test your applications across different Kubernetes distributions and versions.

This topic includes information about creating and managing clusters with Compatibility Matrix using the Replicated Vendor Portal or the Replicated CLI. For information about creating and managing clusters with the Vendor API v3, see the clusters section in the Vendor API v3 documentation.

About Compatibility Matrix Clusters​

Compatibility Matrix supports both VM-based clusters (such as kind, k3s, RKE2, OpenShift, and Embedded Cluster) and cloud-managed clusters (such as EKS, GKE, and AKS). VM-based clusters run on Replicated bare metal servers, while cloud clusters are provisioned in Replicated-managed cloud accounts for faster delivery.

You can use Compatibility Matrix clusters for testing and troubleshooting Kubernetes-based deployments and Helm installations for your application.

For information about creating VMs with Compatibility Matrix to test Replicated Embedded Cluster installers, air-gap installations, or when you need full OS control, see Create VMs.

Prerequisites​

Before you can use Compatibility Matrix clusters, you must complete the following prerequisites:

  • Existing accounts must accept the TOS for the trial on the Compatibility Matrix page in the Replicated Vendor Portal.

Create Clusters​

You can create clusters with Compatibility Matrix using the Replicated CLI or the Vendor Portal.

With the Replicated CLI​

To create a cluster using the Replicated CLI:

  1. (Optional) View the available cluster distributions, including the supported Kubernetes versions, instance types, and maximum nodes for each distribution:

    replicated cluster versions

    For command usage, see cluster versions.

  2. Run the following command to create a cluster:

    replicated cluster create --distribution DISTRIBUTION

    To specify more options:

    replicated cluster create --name NAME --distribution K8S_DISTRO --version K8S_VERSION --disk DISK_SIZE --instance-type INSTANCE_TYPE [--license-id LICENSE_ID]

    Where:

    • NAME is any name for the cluster. If --name is excluded, a name is automatically generated for the cluster.
    • K8S_DISTRO is the Kubernetes distribution for the cluster.
    • K8S_VERSION is the Kubernetes version for the cluster if creating a standard Cloud or VM-based cluster. If creating an Embedded Cluster or kURL cluster type,--version is optional:
      • For Embedded Cluster types, --verison is the latest available release on the channel by default. Otherwise, to specify a different release, set --version to the Channel release sequence value for the release.
      • For kURL cluster types, --verison is the "latest" kURL Installer ID by default. Otherwise, to specify a different kURL Installer, set --version to the kURL Installer ID.
    • DISK_SIZE is the disk size (GiB) to request per node.
    • INSTANCE_TYPE is the instance type to use for each node.
    • (Embedded Cluster Only) LICENSE_ID is a valid customer license. Required to create an Embedded Cluster.

    For command usage and additional optional flags, see cluster create.

    Example:

    The following example creates a kind cluster with Kubernetes version 1.27.0, a disk size of 100 GiB, and an instance type of r1.small.

    replicated cluster create --name kind-example --distribution kind --version 1.27.0 --disk 100 --instance-type r1.small

  3. Verify that the cluster was created:

    replicated cluster ls CLUSTER_NAME

    Where CLUSTER_NAME is the name of the cluster that you created.

    In the output of the command, you can see that the STATUS of the cluster is assigned. When the kubeconfig for the cluster is accessible, the cluster's status is changed to running. For more information about cluster statuses, see Cluster Status in About Compatibility Matrix.

Vendor Portal​

To create a cluster using the Vendor Portal:

  1. Go to Compatibility Matrix > Create cluster.

    Create a cluster page

    View a larger version of this image

  2. On the Create a cluster page, complete the following fields:

    FieldDescription
    Kubernetes distributionSelect the Kubernetes distribution for the cluster.
    VersionSelect the Kubernetes version for the cluster. The options available are specific to the distribution selected.
    Name (optional)Enter an optional name for the cluster.
    TagsAdd one or more tags to the cluster as key-value pairs.
    Set TTLSelect the Time to Live (TTL) for the cluster. When the TTL expires, the cluster is automatically deleted. TTL can be adjusted after cluster creation with cluster update ttl.

  3. For Nodes & Nodes Groups, complete the following fields to configure nodes and node groups for the cluster:

    Instance typeSelect the instance type to use for the nodes in the node group. The options available are specific to the distribution selected.
    Disk sizeSelect the disk size in GiB to use per node.
    NodesSelect the number of nodes to provision in the node group. The options available are specific to the distribution selected.

  4. (Optional) Click Add node group to add additional node groups.

  5. Click Create cluster.

    The cluster is displayed in the list of clusters on the Compatibility Matrix page with a status of Assigned. When the kubeconfig for the cluster is accessible, the cluster's status is changed to Running.

    note

    If the cluster is not automatically displayed, refresh your browser window.

    Cluster configuration dialog

    View a larger version of this image

Prepare Clusters​

For applications distributed with the Replicated Vendor Portal, the cluster prepare command reduces the number of steps required to provision a cluster and then deploy a release to the cluster for testing. This is useful in continuous integration (CI) workflows that run multiple times a day. For an example workflow that uses the cluster prepare command, see Recommended CI/CD Workflows.

The cluster prepare command does the following:

  • Creates a cluster
  • Creates a release for your application based on either a Helm chart archive or a directory containing the application YAML files
  • Creates a temporary customer of type test
    note

    Test customers created by the cluster prepare command are not saved in your Vendor Portal team.

  • Installs the release in the cluster using either the Helm CLI or Replicated KOTS

The cluster prepare command requires either a Helm chart archive or a directory containing the application YAML files to be installed:

  • Install a Helm chart with the Helm CLI:

    replicated cluster prepare \
      --distribution K8S_DISTRO \
      --version K8S_VERSION \
      --chart HELM_CHART_TGZ

    The following example creates a kind cluster and installs a Helm chart in the cluster using the nginx-chart-0.0.14.tgz chart archive:

    replicated cluster prepare \
      --distribution kind \
      --version 1.27.0 \
      --chart nginx-chart-0.0.14.tgz \
      --set key1=val1,key2=val2 \
      --set-string s1=val1,s2=val2 \
      --set-json j1='{"key1":"val1","key2":"val2"}' \
      --set-literal l1=val1,l2=val2 \
      --values values.yaml

  • Install with KOTS from a YAML directory:

    replicated cluster prepare \
      --distribution K8S_DISTRO \
      --version K8S_VERSION \
      --yaml-dir PATH_TO_YAML_DIR

    The following example creates a k3s cluster and installs an application in the cluster using the manifest files in a local directory named config-validation:

    replicated cluster prepare \
      --distribution k3s \
      --version 1.26 \
      --namespace config-validation \
      --shared-password password \
      --app-ready-timeout 10m \
      --yaml-dir config-validation \
      --config-values-file conifg-values.yaml \
      --entitlements "num_of_queues=5"

For command usage, including additional options, see cluster prepare.

Access Clusters​

Compatibility Matrix provides the kubeconfig for clusters so that you can access clusters with the kubectl command line tool. For more information, see Command line tool (kubectl) in the Kubernetes documentation.

To access a cluster from the command line:

  1. Verify that the cluster is in a Running state:

    replicated cluster ls

    In the output of the command, verify that the STATUS for the target cluster is running. For command usage, see cluster ls.

  2. Run the following command to open a new shell session with the kubeconfig configured for the cluster:

    replicated cluster shell CLUSTER_ID

    Where CLUSTER_ID is the unique ID for the running cluster that you want to access.

    For command usage, see cluster shell.

  3. Verify that you can interact with the cluster through kubectl by running a command. For example:

    kubectl get ns

  4. Press Ctrl-D or type exit when done to end the shell and the connection to the server.

Upgrade Clusters (kURL Only)​

For kURL clusters provisioned with Compatibility Matrix, you can use the the cluster upgrade command to upgrade the version of the kURL installer specification used to provision the cluster. A recommended use case for the cluster upgrade command is for testing your application's compatibility with Kubernetes API resource version migrations after upgrade.

The following example upgrades a kURL cluster from its previous version to version 9d5a44c:

replicated cluster upgrade cabb74d5 --version 9d5a44c

For command usage, see cluster upgrade.

Delete Clusters​

You can delete clusters using the Replicated CLI or the Vendor Portal.

Replicated CLI​

To delete a cluster using the Replicated CLI:

  1. Get the ID of the target cluster:

    replicated cluster ls

    In the output of the command, copy the ID for the cluster.

    Example:

    ID        NAME              DISTRIBUTION   VERSION   STATUS    CREATED                        EXPIRES 
    1234abc   My Test Cluster   eks            1.27      running   2023-10-09 17:08:01 +0000 UTC  -

    For command usage, see cluster ls.

  2. Run the following command:

    replicated cluster rm CLUSTER_ID

    Where CLUSTER_ID is the ID of the target cluster. For command usage, see cluster rm.

  3. Confirm that the cluster was deleted:

    replicated cluster ls CLUSTER_ID --show-terminated

    Where CLUSTER_ID is the ID of the target cluster. In the output of the command, you can see that the STATUS of the cluster is terminated. For command usage, see cluster ls.

Vendor Portal​

To delete a cluster using the Vendor Portal:

  1. Go to Compatibility Matrix.

  2. Under Clusters, in the vertical dots menu for the target cluster, click Delete cluster.

    Delete cluster button

    View a larger version of this image