Skip to main content

Create and Manage Environments with CMX

This topic describes how to use Replicated Compatibility Matrix (CMX) to create and manage clusters and VMs.

This topic includes information about creating and managing environments with CMX 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.

Prerequisites​

Create Environments​

For information about how to create environments with the CLI, see replicated cluster create and replicated vm create.

To create an environment with CMX from the Vendor Portal:

  1. In the Vendor Portal, go to Compatibility Matrix.

  2. Click Create and choose Create Kubernetes cluster or Create VM:

    • Create Kubernetes cluster:

      1. On the Create a cluster page, choose the Kubernetes distribution and version.

      2. (Optional) Add a name for the cluster, add tags, and adjust the Time to Live (TTL).

      3. (Optional) For Nodes & Nodes Groups, add and configure additional nodes and node groups for the cluster.

      The following is an example of the Create a cluster page:

      Create a cluster page

      View a larger version of this image

    • Create VM:

      1. On the Create a Virtual Machine page, choose the OS distribution and version.

      2. (Optional) Add a name for the VM, add tags, and adjust the Time to Live (TTL).

      3. (Optional) For VM Config, choose the instance type and disk size. You can also create multiple VMs of the same type by increasing the Count.

        note

        You can create TLS certs and DNS records in the Ingress & Ports tab after the VM has been created. See Expose Ports on VMs.

      The following is an example of the Create a Virtual Machine page:

      create vm page in the vendor portal

      View a larger version of this image

  3. Click Create cluster or Create VM.

    The environment is displayed in the list on the Compatibility Matrix Overview page with a status of Assigned. When the environment is ready, the status is changed to Running.

Create Air-Gapped Environments (Beta)​

note

Using the airgap network policy to simulate an air-gapped environment is supported only for VMs and VM-based clusters. Clusters that use cloud-based distributions do not support the airgap network policy.

VMs and VM-based clusters created with CMX can use one of the following network policies:

Network PolicyDescription
openNo restrictions on network traffic.
airgapRestrict all network traffic.

By default, all VMs and VM-based clusters are created with an open network policy. You can change the network policy to airgap to block outbound network requests. This is useful for simulating an air-gapped environment with no outbound internet access so that you can test how your application performs.

Network policies are configured at the network level and apply to all VMs and environments connected to the network.

You can also use CMX to generate reports that track and summarize network activity on CMX networks. For more information, see Collect and View Network Reports.

VM-Based Cluster​

To create an air-gapped cluster:

  1. Create a cluster:

    replicated cluster create --distribution VM_BASED_DISTRIBUTION

    Where VM_BASED_DISTRIBUTION is the target VM-based cluster distribution. For a list of supported distributions, see VM Clusters.

  2. Watch until the cluster status is running:

    replicated cluster ls --watch

  3. Access the cluster in a shell:

    replicated cluster shell CLUSTER_ID

    Where CLUSTER_ID is the ID of the cluster that you created from the output of the cluster ls command.

  4. Change the network policy to airgap:

    replicated network update NETWORK_ID --policy airgap

    Where NETWORK_ID is the ID of the network from the output of the cluster ls command.

  5. Verify that the cluster's policy is airgap and the status is running:

    replicated cluster ls
    ID       NAME                STATUS       CREATED                 EXPIRES                POLICY   HAS REPORT
    bdeb3515 gifted_antonelli    running      2025-01-28 18:45 PST    2025-01-28 19:45 PST   airgap   off

  6. (Optional) Enable network reporting to track network activity. See Collect and View Network Reports.

VM​

To create an air-gapped VM:

  1. Create a VM:

    replicated vm create --distribution ubuntu

  2. Wait until the VM status is running:

    replicated vm ls

  3. SSH onto the VM:

    ssh VM_ID@replicatedvm.com

    Where VM_ID is the ID of the VM from the output of the vm ls command.

    For more information and additional options, see Connect to CMX VMs (SSH and File Transfer).

  4. Set the network policy to airgap:

    replicated network update NETWORK_ID --policy airgap

    Where NETWORK_ID is the ID of the network from the output of the vm ls command.

    Example:

    replicated network update 85eb50a8 --policy airgap
    ID       NAME                STATUS        CREATED                 EXPIRES                POLICY   HAS REPORT
    85eb50a8 silly_rosalind      updating      2025-01-28 16:16 PST    2025-01-28 17:18 PST   airgap   off

  5. (Optional) Enable network reporting to track network activity. See Collect and View Network Reports.

Access Environments​

After a CMX cluster or VM is running, you can access the environment using the replicated cluster shell or ssh command that is available in the Compatibility Matrix UI.

  • To access a cluster with kubectl:

    replicated cluster shell CLUSTER_ID

    Where CLUSTER_ID is the ID of the running cluster.

  • To SSH into a VM:

    1. If you have not done so already, set up SSH access using a public/private key pair. See Prerequisite: Set Up SSH in Connect to VMs (SSH and File Transfer).

    2. Run the following command:

      ssh VMID@replicatedvm.com

      Where VMID is the ID of the running VM.

    3. Respond to the prompts to add the fingerprint for replicatedvm.com and enter the passphrase for your SSH key.

Create Environments on the Same Network​

You can create VMs and clusters with CMX that use the same network.

Connect a VM with a Cluster on the Same Network​

You can make a CMX cluster available on the same network as a CMX VM.

Supported Cluster Distributions​

Openshift, K3s, RKE2, EC, kURL, kind

Requirement​

Replicated CLI 0.90.0 or later

To connect a VM with a cluster on the same network:

  1. Create a cluster:

    replicated cluster create --distribution K8S_DISTRIBUTION

    For example, replicated cluster create --distribution k3s.

  2. In the output of the cluster create command, under NETWORK, copy the network ID.

    Example:

    ID         NAME              DISTRIBUTION    VERSION    STATUS    NETWORK     CREATED                EXPIRES  COST
    6b14376c   ecstatic_raman    k3s             1.33.2     queued    accbd6a7    2025-08-04 13:20 PDT   -        $0.60

    In the example above, the network ID is accbd6a7.

  3. Create a VM on the same network:

    replicated vm create --distribution DISTRIBUTION --network NETWORK_ID

    Where NETWORK_ID is the network ID that you copied in the previous step.

    For example, replicated vm create --distribution ubuntu --network accbd6a7.

    Example output:

    ID         NAME                 DISTRIBUTION   VERSION   STATUS     NETWORK    CREATED                EXPIRES  COST
    760a30b1   suspicious_poitras   ubuntu         24.04     assigned   accbd6a7   2025-08-04 13:24 PDT   -        $0.60

Create VMs on the Same Network​

Use the --count flag to create multiple VMs with the same name, all running on the same Network ID.

replicated vm create --distribution ubuntu --count 3

Join VMs to an Existing Network​

To join one or more new VMs to the network of an existing VM:

  1. Run one of the following commands to get the ID of an existing VM network:

    • List VMs:

      replicated vm ls

    • List networks:

      replicated network ls

  2. In the output of the command, copy the network ID.

  3. Use the --network flag to create a new VM on the same network:

    replicated vm create --distribution ubuntu --network NETWORK_ID

    Where NETWORK_ID is the network ID that you copied in the previous step.

Create a Cluster and Install a Release with cluster prepare​

The cluster prepare command reduces the number of steps required to provision a cluster and then deploy a release to the cluster. 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.

Edit Environments​

You can make changes to an environment after creating it. For example, you could extent to TTL or add DNS records to expose ports on a VM.

To edit environments:

  1. In the Vendor Portal, go to Compatibility Matrix.

  2. In the vertical dots menu for the target environment, click Edit [VM/cluster].

    Dot menu with edit and delete options View a larger version of this image

  3. Make changes to the environment as needed.

Delete Environments​

For information about deleting environments using the Replicated CLI, see replicated cluster rm and replicated vm rm

To delete a cluster using the Vendor Portal:

  1. In the Vendor Portal, go to Compatibility Matrix.

  2. In the vertical dots menu for the target environment, click Delete [VM/cluster].

    Dot menu with edit and delete options View a larger version of this image

  3. In the dialog, click Delete [VM/cluster] again to confirm.