! You have successfully authenticated, use [VM_ID]@replicatedvm.com to access your VM.
+ ```
+
+ :::note
+ If you see the prompt `Are you sure you want to continue connecting (yes/no/[fingerprint])?`, type `yes` and press Enter to continue. You might see this prompt if it is the first time you are authenticating with the public/private SSH key in your GitHub account.
+ :::
+
+### Use a Service Account {#github-service-account}
+
+If you are setting up SSH access for VMs created in CI/CD workflows used by your team, you can use the SSH key of a service account or bot with shared access.
+
+To automate the creation of VMs in your CI/CD workflows, use the flag `--ssh-public-key` to provide the SSH public key. For example:
+
+```bash
+replicated vm create --distribution ubuntu --version 24.04 --ssh-public-key ~/.ssh/id_rsa.pub
+```
+
+Or, to use multiple SSH public keys:
+
+```bash
+replicated vm create --distribution ubuntu --version 24.04 --ssh-public-key ~/.ssh/id_rsa.pub --ssh-public-key ~/.ssh/id_ed25519.pub
+```
+
+## Create VMs
+
+### With the Replicated CLI
+
+To create VMs with CMX:
+
+1. (Optional) View the available VM distributions, including the supported VM distribution versions and instance types:
+
+ ```bash
+ replicated vm versions
+ ```
+ For command usage, see [vm versions](/reference/replicated-cli-vm-versions).
+
+
+1. Run the following command to create a VM:
+
+ ```bash
+ replicated vm create --distribution DISTRIBUTION
+ ```
+
+ To specify more options:
+
+
+ ```bash
+ replicated vm create --name NAME --distribution DISTRIBUTION --version VERSION --instance-type INSTANCE_TYPE --count COUNT --ttl TTL
+ ```
+
+ Where:
+ * `NAME` is any name for the VM. If `--name` is excluded, a name is automatically generated for the VM.
+ * `DISTRIBUTION` is the operating system distribution for the VM (e.g., ubuntu, almalinux).
+ * `VERSION` is the version of the distribution to provision (e.g., 22.04, 24.04 for Ubuntu).
+ * `INSTANCE_TYPE` is the instance type to use for the VM (e.g., r1.medium, r1.large).
+ * `COUNT` is the number of VMs to create. If `--count` is excluded, one VM is created by default.
+ * `TTL` is the VM Time-To-Live duration (maximum 48h). If `--ttl` is excluded, the default TTL is 1 hour.
+
+ For command usage and additional optional flags, see [vm create](/reference/replicated-cli-vm-create).
+
+ **Example:**
+
+ The following example creates an Ubuntu VM with version 22.04, a disk size of 50 GiB, and an instance type of `r1.medium`.
+
+ ```bash
+ replicated vm create --distribution ubuntu --version 22.04 --disk 50 --instance-type r1.medium
+ ```
+
+### With the Vendor Portal
+
+To create a VM from the Vendor Portal:
+
+1. In the Vendor Portal, go to [**Compatibility Matrix**](https://vendor.replicated.com/compatibility-matrix).
+
+1. Click **Create > Create VM**.
+
+ 
+
+ [View a larger version of this image](/images/compatibility-matrix-create-vm.png)
+
+1. On the **Create a Virtual Machine** page, complete the following fields:
+
+
+
+ | Field |
+ Description |
+
+
+ | OS distribution |
+ Select the OS distribution for the VM. |
+
+
+ | Version |
+ Select the OS version. The options available are specific to the distribution selected. |
+
+
+ | Name (optional) |
+ Enter an optional name for the VM. |
+
+
+ | Tags |
+ Add one or more tags to the VM as key-value pairs. |
+
+
+ | Set TTL |
+ Select the Time to Live (TTL) for the VM. When the TTL expires, the VM is automatically deleted. TTL can be adjusted after VM creation with [vm update ttl](/reference/replicated-cli-vm-update-ttl). |
+
+
+
+1. For **VM Config**, complete the following fields:
+
+
+
+ | Instance type |
+ Select the instance type to use for the nodes in the node group. The options available are specific to the distribution selected. |
+
+
+ | Disk size |
+ Select the disk size in GiB to use per node. |
+
+
+ | Count |
+ Select the number of VMs to provision. |
+
+
+
+1. Click **Create VM**.
+
+## Connect to a VM
+
+You can SSH into a VM using one of the following methods:
+
+* [**CMX Forwarder**](#compatibility-matrix-forwarder): To use the CMX Forwarder, you only need to know the VM ID to connect to the machine with SSH. This is more approachable for users less familiar with SSH clients.
+
+* [**Direct SSH**](#direct-ssh): When you connect to a VM using direct SSH, you can use your SSH tool of choice and pass any client supported flags, without any added connection lag of being routed through the CMX Forwarder. Example use cases for direct SSH include transferring large assets such as air gap bundles to the VM using SCP, or passing specific SHH flags during testing workflows.
+
+For information about how to copy files to a VM after connecting, see [Copy Files to a VM](#copy-files-to-a-vm) below.
+
+### CMX Forwarder
+
+To connect to a VM using the Forwarder:
+
+* SSH into the VM:
+
+ ```bash
+ ssh VMID@replicatedvm.com
+ ```
+
+ Where `VMID` is the ID of the VM.
+
+For information about copying files to the VM after connecting, see [Copy Files to a VM](#copy-files-to-a-vm) below.
+
+### Direct SSH
+
+Connecting to a VM with direct SSH requires Replicated CLI v0.104.0 or later.
+
+To connect to a VM using direct SSH:
+
+1. Get the SSH endpoint for the VM:
+
+ ```bash
+ replicated vm ssh-endpoint VMID_OR_VMNAME [--username GITHUB_USERNAME]
+ ```
+
+ Where:
+ * `VMID_OR_VMNAME` is the ID or name of the VM. Run `replicated vm ls`.
+ * (Optional) `GITHUB_USERNAME` is a GitHub username used to connect to the SSH endpoint. This is an optional flag that overrides the GitHub username listed in your Vendor Portal account. The `--username` flag is required if you want to:
+ * Use a different GitHub username than what is in Vendor Portal (or if there is no username set in the Vendor Portal)
+ * When creating a VM, you used the `--ssh-public-key` flag to associate the VM with a GitHub service account, and this doesn't match the GitHub username set in Vendor Portal
+
+ **Example:**
+
+ ```bash
+ replicated vm ssh-endpoint aba1acc2
+ ```
+
+ The output of the command displays the SSH endpoint that you can use to connect to the VM:
+
+ ```
+ ssh://[github-user-name]@[ssh-endpoint]:[port]
+ ```
+ For example, `ssh://yourusername@37.27.52.116:46795`.
+
+ :::note
+ You can also get the SSH endpoint and port in JSON format by running `replicated vm ls --output json`.
+ :::
+
+1. Copy the SSH endpoint.
+
+1. SSH into the VM using the SSH endpoint that you copied:
+
+ ```bash
+ ssh ssh://YOUR_GITHUB_USERNAME@SSH_ENDPOINT:PORT
+ ```
+ Where `GITHUB_USERNAME`, `SSH_ENDPOINT`, and `PORT` are all copied from the SSH endpoint that you retrieved.
+
+ **Example:**
+
+ ```bash
+ ssh ssh://yourusername@37.27.52.116:46795
+ ```
+
+ Alternatively, run the following command to SSH into the VM without needing to copy the endpoint:
+
+ ```bash
+ ssh $(replicated vm ssh-endpoint VMID_OR_VMNAME)
+ ```
+
+ **Example**
+
+ ```
+ ssh $(replicated vm ssh-endpoint aba1acc2)
+ ```
+
+## Copy Files to a VM
+
+This section describes how to transfer files to a VM created with CMX.
+
+You can copy files to a VM either using direct SSH and an SCP endpoint, or by using SCP after connecting to the VM with the CMX Forwarder. Transferring files using direct SSH allows you to use your SSH tool of choice, and pass any client-supported flags.
+
+### Using the SCP Endpoint
+
+To copy files to a VM using the scp endpoint:
+
+1. Run the following command to get the SCP endpoint:
+
+ ```bash
+ replicated vm scp-endpoint VMID_OR_VMNAME [--username GITHUB_USERNAME]
+ ```
+
+ Where
+ * `VMID_OR_VMNAME` is the ID or name of the VM.
+ * (Optional) `GITHUB_USERNAME` is a GitHub username used to connect to the SCP endpoint. This is an optional flag that overrides the GitHub username listed in your Vendor Portal account. The `--username` flag is required if you want to:
+ * Use a different GitHub username than what is in Vendor Portal (or if there is no username set in the Vendor Portal)
+ * When creating a VM, you used the `--ssh-public-key` flag to associate the VM with a GitHub service account, and this doesn't match the GitHub username set in Vendor Portal
+
+ **Example**
+ ```bash
+ replicated vm scp-endpoint aba1acc2
+ ```
+
+ The output of the command lists the SCP endpoint for the VM:
+
+ ```
+ scp://GITHUB_USERNAME@SSH_ENDPOINT:PORT
+ ```
+
+ For example, `scp://yourusername@37.27.52.116:46795`.
+
+1. Copy the SCP endpoint.
+
+1. SCP files into the VM:
+
+ ```bash
+ scp somefile scp://GITHUB_USERNAME@SSH_ENDPOINT:PORT//PATH
+ ```
+ Where:
+ * `GITHUB_USERNAME`, `SSH_ENDPOINT`, and `PORT` are all copied from the SCP endpoint that you retrieved.
+ * `PATH` is the destination path on the VM.
+
+ Alternatively, run the following command to SCP files into the VM without needing to copy the endpoint:
+
+ ```bash
+ scp somefile $(replicated vm scp-endpoint VMID_OR_VMNAME)//PATH
+ ```
+
+### After Connecting to the VM with the Forwarder
+
+:::note
+Transferring files using CMX Forwarder is slower than using direct SSH due to added latency. If you want to transfer large files such as air gap bundles onto the VM, use direct SSH in combination with SCP. See [Using the SCP Endpoint](#using-the-scp-endpoint) above.
+:::
+
+#### Limitations
+
+For limitations related to file transfers using the CMX Forwarder, see [Limitations](/vendor/cmx-overview#limitations) in _CMX Overview_.
+
+To copy files to the VM using SCP after connecting with the CMX Forwarder:
+
+1. SSH into the VM using the Forwarder:
+
+ ```bash
+ ssh VMID@replicatedvm.com
+ ```
+
+ Where `VMID` is the ID of the VM.
+
+1. Copy files onto the machine:
+ ```bash
+ scp FILENAME VMID@replicatedvm:PATH
+ ```
+
+ Where:
+ * `FILENAME` is the name of the file.
+ * `VMID` is the ID of the VM.
+ * `PATH` is the path on the VM where you want to copy the file. For example, `/home/folder/somefile`. Relative paths are not supported.
+
+ **Example:**
+
+ ```bash
+ scp somefile 123abc@replicatedvm:/home/folder/somefile
+ ```
+
+## Create Air Gap VMs
+
+You can create a VM that uses an air-gapped network by setting the network policy to `airgap`.
+
+For more information, see [Test in Air Gap Environments](cmx-airgap).
+
+To set the network policy of a VM to `airgap`:
+
+1. Create a VM:
+
+ ```bash
+ replicated vm create --distribution VM_DISTRIBUTION
+ ```
+
+1. After the VM is running, SSH onto the VM:
+
+ ```bash
+ 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 a VM](#connect-to-a-vm) above.
+
+1. Set the network policy to `airgap`:
+
+ ```bash
+ replicated network update NETWORK_ID --policy airgap
+ ```
+ Where `NETWORK_ID` is the ID of the network from the output of the `vm ls` command.
+
diff --git a/docs/vendor/environment-setup.mdx b/docs/vendor/environment-setup.mdx
index c0de6b750d..900eb671e4 100644
--- a/docs/vendor/environment-setup.mdx
+++ b/docs/vendor/environment-setup.mdx
@@ -271,7 +271,7 @@ Testing your releases is an important part of the commercial software distributi
You need access to a VM to test installations and updates with the [Replicated Embedded Cluster](/vendor/embedded-overview) installer:
-* **Option 1: Use Compatibility Matrix.** You can use Replicated Compatibility Matrix to create and SSH onto Linux VMs. For more information, see [Create a VM](/vendor/testing-vm-create).
+* **Option 1: Use Compatibility Matrix.** You can use Replicated Compatibility Matrix to create and SSH onto Linux VMs. For more information, see [CMX VMs](/vendor/cmx-vms).
* **Option 2: Bring your own VM.** Your VM must meet the following requirements to install with Embedded Cluster:
diff --git a/docs/vendor/kots-faq.mdx b/docs/vendor/kots-faq.mdx
index d62544127b..8b48690cb4 100644
--- a/docs/vendor/kots-faq.mdx
+++ b/docs/vendor/kots-faq.mdx
@@ -71,7 +71,7 @@ You can use Compatibility Matrix (CMX)to get kubectl access to running clusters
### How does billing work?
-Clusters created with CMX are billed by the minute. Per-minute billing begins when the cluster reaches a running status and ends when the cluster is deleted. For more information, see [Billing and Credits](/vendor/testing-about#billing-and-credits).
+Clusters created with CMX are billed by the minute. Per-minute billing begins when the cluster reaches a running status and ends when the cluster is deleted. For more information, see [Billing and Credits](/vendor/cmx-overview#billing-and-credits).
### How do I buy credits?
diff --git a/docs/vendor/policies-support-lifecycle.md b/docs/vendor/policies-support-lifecycle.md
index 3286115ce3..ca5643b5ac 100644
--- a/docs/vendor/policies-support-lifecycle.md
+++ b/docs/vendor/policies-support-lifecycle.md
@@ -41,7 +41,7 @@ Replicated will provide support for products per our terms and services until th
End of Life |
- | Compatibility Matrix |
+ Compatibility Matrix |
GA |
N/A |
N/A |
diff --git a/docs/vendor/quick-start.mdx b/docs/vendor/quick-start.mdx
index 5b111d70bb..83afadd7ca 100644
--- a/docs/vendor/quick-start.mdx
+++ b/docs/vendor/quick-start.mdx
@@ -39,13 +39,13 @@ Before you begin, do the following to set up your environment:
* **Option 1: Use Compatibility Matrix.** To use Replicated Compatibility Matrix (CMX) to create a VM, do the following before proceeding:
- * Request CMX credits. You can request credits by creating a Vendor Portal account and then going to [**Compatibility Matrix > Request more credits**](https://vendor.replicated.com/compatibility-matrix) in the Vendor Portal. For more information about creating an account, see [Create a Vendor Account](vendor-portal-creating-account). For more information about CMX credits, see [Billing and Credits](/vendor/testing-about#billing-and-credits).
+ * Request CMX credits. You can request credits by creating a Vendor Portal account and then going to [**Compatibility Matrix > Request more credits**](https://vendor.replicated.com/compatibility-matrix) in the Vendor Portal. For more information about creating an account, see [Create a Vendor Account](vendor-portal-creating-account). For more information about CMX credits, see [Billing and Credits](/vendor/cmx-overview#billing-and-credits).
:::note
If you are new to the Replicated platform, you might be eligible for $100 in free CMX credits. To request your free credits, reach out to our sales team at https://www.replicated.com/contact and note in the comments that you are completing the Replicated Quick Start.
:::
- * Ensure that you have an SSH key in your GitHub account. Then, add your GitHub username to your Vendor Portal [**Account Settings**](https://vendor.replicated.com/account-settings). This will provide SSH access to VMs that you create with CMX. For more information, see [Set Up SSH Access](/vendor/testing-vm-create#set-up-ssh-access) in _Create VMs_.
+ * Ensure that you have an SSH key in your GitHub account. Then, add your GitHub username to your Vendor Portal [**Account Settings**](https://vendor.replicated.com/account-settings). This will provide SSH access to VMs that you create with CMX. For more information, see [Set Up SSH Access](/vendor/cmx-vms#set-up-ssh-access) in _CMX VMs_.
After you complete the prerequisites above, continue to the [Quick Start](#quick-start). You will create the VM with CMX as part of the tutorial.
@@ -618,7 +618,7 @@ To get started, see [Onboard to the Replicated Platform](replicated-onboarding).
For more information about the Replicated Platform features mentioned in this quick start, see:
* [Embedded Cluster Overview](/vendor/embedded-overview)
-* [About CMX](/vendor/testing-about)
+* [About CMX](/vendor/cmx-overview)
* [About Preflight Checks and Support Bundles](/vendor/preflight-support-bundle-about)
* [About the Replicated SDK](/vendor/replicated-sdk-overview)
* [Manage Releases with the CLI](/vendor/releases-creating-cli)
diff --git a/docs/vendor/replicated-onboarding.mdx b/docs/vendor/replicated-onboarding.mdx
index da133f881a..f5eb2593d5 100644
--- a/docs/vendor/replicated-onboarding.mdx
+++ b/docs/vendor/replicated-onboarding.mdx
@@ -617,7 +617,7 @@ Replicated recommends that teams integrate the Replicated Platform into their ex
For more information, see:
* [About Integrating with CI/CD](/vendor/ci-overview)
-* [About CMX](/vendor/testing-about)
+* [About CMX](/vendor/cmx-overview)
* [Recommended CI/CD Workflows](/vendor/ci-workflows)
### Customize Release Channels
diff --git a/docs/vendor/testing-about.md b/docs/vendor/testing-about.md
deleted file mode 100644
index 3c5292629c..0000000000
--- a/docs/vendor/testing-about.md
+++ /dev/null
@@ -1,38 +0,0 @@
-# About CMX
-
-This topic describes Replicated Compatibility Matrix (CMX), including use cases, billing, limitations, and more.
-
-## Overview
-
-You can use CMX to quickly provision ephemeral clusters and VMs. CMX's networking features also provide kubectl or SSH access to clusters and VMs. This allows you to install and test your application in a range of different development environments before releasing to customers.
-
-Example use cases for CMX include:
-* Run tests before releasing a new version of your application to validate compatibility with supported Kubernetes distributions
-* Get access to a cluster or VM to develop on and quickly test changes
-* Reproduce a reported issue on a customer-representative environment for troubleshooting
-
-You can use CMX with the Replicated CLI or the Replicated Vendor Portal. For more information about how to use CMX, see [Create and Manage Clusters](testing-how-to) and [Create VMs](testing-vm-create).
-
-## Supported Clusters and VMs
-
-CMX can create VMs, VM-based clusters (such as kind, k3s, RKE2, and Red Hat OpenShift OKD), and cloud-managed clusters (such as EKS, GKE and AKS):
-
-* Cloud-based Kubernetes distributions are run in a Replicated managed and controlled cloud account to optimize and deliver a clusters quickly and reliably. The Replicated account has control planes ready and adds a node group when you request it, making the cluster available much faster than if you try to create your own cluster with your own cloud account.
-
-* VMs and VM-based clusters run on Replicated bare metal servers located in several data centers, including data centers physically in the European Union.
-
-You can run [`replicated cluster versions`](/reference/replicated-cli-cluster-versions) or [`replicated vm versions`](/reference/replicated-cli-vm-versions) for an up-to-date list of the available cluster distributions or VM types.
-
-For more information about the supported cluster distributions, see [Supported CMX Cluster Types](testing-supported-clusters).
-
-For more information about supported VMs, see [Supported VM Types](/vendor/testing-vm-create#supported-vm-types)
-
-## Billing and Credits
-
-Clusters and VMs created with CMX are billed by the minute, plus a startup charge. Per-minute billing begins when a `running` status is reached and ends when the cluster or VM is deleted.
-
-For more information about pricing, see [CMX Pricing](testing-pricing).
-
-To create clusters with CMX, you must have credits in your Vendor Portal account.
-If you have a contract, you can purchase credits by logging in to the Vendor Portal and going to [**Compatibility Matrix > Buy additional credits**](https://vendor.replicated.com/compatibility-matrix).
-Otherwise, to request credits, log in to the Vendor Portal and go to [**Compatibility Matrix > Request more credits**](https://vendor.replicated.com/compatibility-matrix).
\ No newline at end of file
diff --git a/docs/vendor/testing-ci-cd.md b/docs/vendor/testing-ci-cd.md
index 46ab565088..5fef8db041 100644
--- a/docs/vendor/testing-ci-cd.md
+++ b/docs/vendor/testing-ci-cd.md
@@ -1,12 +1,14 @@
import TestRecs from "../partials/ci-cd/_test-recs.mdx"
-# Test in CMX with CI/CD
+# CI/CD with CMX
-This topic describes how to integrate Replicated Compatibility Matrix (CMX) into your CI/CD workflows.
+This topic describes how to integrate Replicated Compatibility Matrix (CMX) into your CI/CD workflows for automated testing.
-## About Using CMX with CI/CD
+## About Integrating CMX with CI/CD
-Replicated recommends that you integrate CMX into your existing CI/CD workflow to automate the process of creating clusters to install your application and run tests. For more information, including additional best practices and recommendations for CI/CD, see [About Integrating with CI/CD](/vendor/ci-overview).
+Replicated recommends that you integrate CMX into your existing CI/CD workflow to automate the process of creating clusters to install your application and run tests. CMX's powerful automation capabilities help you validate your application across multiple Kubernetes distributions and versions efficiently.
+
+For more information, including additional best practices and recommendations for CI/CD, see [About Integrating with CI/CD](/vendor/ci-overview).
### Replicated GitHub Actions
diff --git a/docs/vendor/testing-cluster-addons.md b/docs/vendor/testing-cluster-addons.md
deleted file mode 100644
index 930aded4d0..0000000000
--- a/docs/vendor/testing-cluster-addons.md
+++ /dev/null
@@ -1,78 +0,0 @@
-# CMX Cluster Add-ons (Alpha)
-
-This topic describes the supported cluster add-ons for Replicated Compatibility Matrix (CMX).
-
-## Overview
-
-CMX enables you to extend your cluster with add-ons, to make use of by your application, such as an AWS S3 object store.
-This allows you to more easily provision dependencies required by your application.
-
-## CLI
-
-The Replicated CLI can be used to [create](/reference/replicated-cli-cluster-addon-create), [manage](/reference/replicated-cli-cluster-addon-ls) and [remove](/reference/replicated-cli-cluster-addon-rm) cluster add-ons.
-
-## Supported Add-ons
-
-This section lists the supported cluster add-ons for clusters created with CMX.
-
-### object-store (Alpha)
-
-The Replicated cluster object store add-on can be used to create S3 compatible object store buckets for clusters (currently only AWS S3 is supported for EKS clusters).
-
-Assuming you already have a cluster, run the following command with the cluster ID to create an object store bucket:
-
-```bash
-$ replicated cluster addon create object-store 4d2f7e70 --bucket-prefix mybucket
-05929b24 Object Store pending {"bucket_prefix":"mybucket"}
-$ replicated cluster addon ls 4d2f7e70
-ID TYPE STATUS DATA
-05929b24 Object Store ready {"bucket_prefix":"mybucket","bucket_name":"mybucket-05929b24-cmx","service_account_namespace":"cmx","service_account_name":"mybucket-05929b24-cmx","service_account_name_read_only":"mybucket-05929b24-cmx-ro"}
-```
-
-This will create two service accounts in a namespace, one read-write and the other read-only access to the object store bucket.
-
-Additional service accounts can be created in any namespace with access to the object store by annotating the new service account with the same `eks.amazonaws.com/role-arn` annotation found in the predefined ones (`service_account_name` and `service_account_name_read_only`).
-
-
-
- | Type |
- Description |
-
-
- | Supported Kubernetes Distributions |
- EKS (AWS S3) |
-
-
- | Cost |
- Flat fee of $0.50 per bucket. |
-
-
- | Options |
-
-
- - bucket_prefix (string): A prefix for the bucket name to be created (required)
-
- |
-
-
- | Data |
-
-
- - bucket_prefix: The prefix specified by the user for the bucket name
-
-
- - bucket_name: The actual bucket name
-
-
- - service_account_namespace: The namespace in which the service accounts (`service_account_name` and `service_account_name_read_only`) have been created.
-
-
- - service_account_name: The service account name for read-write access to the bucket.
-
-
- - service_account_name_read_only: The service account name for read-only access to the bucket.
-
- |
-
-
-
diff --git a/docs/vendor/testing-how-to.md b/docs/vendor/testing-how-to.md
index 8f581b994a..547ea4edbc 100644
--- a/docs/vendor/testing-how-to.md
+++ b/docs/vendor/testing-how-to.md
@@ -1,6 +1,4 @@
-import Prerequisites from "../partials/cmx/_prerequisites.mdx"
-
-# Use CMX Clusters
+# CMX Clusters
This topic describes how to use Replicated Compatibility Matrix (CMX) to create and manage ephemeral clusters to test your applications across different Kubernetes distributions and versions.
@@ -12,35 +10,17 @@ CMX supports both VM-based clusters (such as kind, k3s, RKE2, OpenShift, and Emb
You can use CMX clusters for testing and troubleshooting Kubernetes-based deployments and Helm installations for your application.
-For information about creating VMs with CMX to test Replicated Embedded Cluster installers or when you need full OS control, see [Create VMs](/vendor/testing-vm-create).
-
-## Limitations
-
-CMX has the following limitations:
-
-- Clusters cannot be resized. Create another cluster if you want to make changes, such as add another node.
-- Clusters cannot be rebooted. Create another cluster if you need to reset/reboot the cluster.
-- On cloud clusters, node groups are not available for every distribution. For distribution-specific details, see [Supported CMX Cluster Types](/vendor/testing-supported-clusters).
-- Multi-node support is not available for every distribution. For distribution-specific details, see [Supported CMX Cluster Types](/vendor/testing-supported-clusters).
-- ARM instance types are only supported on Cloud Clusters. For distribution-specific details, see [Supported CMX Cluster Types](/vendor/testing-supported-clusters).
-- GPU instance types are only supported on Cloud Clusters. For distribution-specific details, see [Supported CMX Cluster Types](/vendor/testing-supported-clusters).
-- There is no support for IPv6 as a single stack. Dual stack support is available on kind clusters.
-- The `cluster upgrade` feature is available only for kURL distributions. See [cluster upgrade](/reference/replicated-cli-cluster-upgrade).
-- Cloud clusters do not allow for the configuration of CNI, CSI, CRI, Ingress, or other plugins, add-ons, services, and interfaces.
-- The node operating systems for clusters created with CMX cannot be configured nor replaced with different operating systems.
-- The Kubernetes scheduler for clusters created with CMX cannot be replaced with a different scheduler.
-- Each team has a quota limit on the amount of resources that can be used simultaneously. This limit can be raised by messaging your account representative.
-- Team actions with CMX (for example, creating and deleting clusters and requesting quota increases) are not logged and displayed in the [Vendor Team Audit Log](https://vendor.replicated.com/team/audit-log).
+For information about creating VMs with CMX to test Replicated Embedded Cluster installers or when you need full OS control, see [CMX VMs](cmx-vms).
-For additional distribution-specific limitations, see [Supported CMX Cluster Types](testing-supported-clusters).
+For information about using the `cluster prepare` command to streamline development workflows, see [Develop with CMX](cmx-develop).
## Prerequisites
-Before you can use CMX clusters, you must complete the following prerequisites:
+For prerequisites, see [Prerequisites](/vendor/cmx-overview#prerequisites) in _CMX Overview_.
-
+## Limitations
-* Existing accounts must accept the TOS for the trial on the [**Compatibility Matrix**](https://vendor.replicated.com/compatibility-matrix) page in the Replicated Vendor Portal.
+For limitations, see [Limitations](/vendor/cmx-overview#limitations) in _CMX Overview_.
## Create Clusters
@@ -174,7 +154,7 @@ To create a cluster using the Vendor Portal:
For any VM-based cluster distributions, you can create a cluster that uses an air-gapped network by setting the network policy to `airgap`.
-For more information, see [Use Air Gap Networks (Beta)](testing-network-policy).
+For more information, see [Test in Air Gap Environments](cmx-airgap).
To set the network policy of a VM-based cluster to `airgap`:
@@ -183,7 +163,7 @@ To set the network policy of a VM-based cluster to `airgap`:
```bash
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](/vendor/testing-supported-clusters#vm-clusters).
+ Where `VM_BASED_DISTRIBUTION` is the target VM-based cluster distribution. For a list of supported distributions, see [VM-Based Clusters](/vendor/testing-supported-clusters#vm-based-clusters).
1. Change the network policy to `airgap`:
@@ -192,153 +172,91 @@ To set the network policy of a VM-based cluster to `airgap`:
```
Where `NETWORK_ID` is the ID of the network from the output of the `cluster ls` command.
-## Prepare Clusters
-
-For applications distributed with the Replicated Vendor Portal, the [`cluster prepare`](/reference/replicated-cli-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](/vendor/ci-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**:
-
- ```bash
- 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:
- ```bash
- 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**:
-
- ```bash
- 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`:
- ```bash
- 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](/reference/replicated-cli-cluster-prepare).
+## Cluster Add-ons (Alpha)
-## Access Clusters
+CMX enables you to extend your cluster with add-ons to make use of advanced features such as an AWS S3 object store. This allows you to more easily provision dependencies required by your application for testing in customer-representative environments.
-CMX 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)](https://kubernetes.io/docs/reference/kubectl/) in the Kubernetes documentation.
+### CLI
-To access a cluster from the command line:
+The Replicated CLI can be used to [create](/reference/replicated-cli-cluster-addon-create), [manage](/reference/replicated-cli-cluster-addon-ls) and [remove](/reference/replicated-cli-cluster-addon-rm) cluster add-ons.
-1. Verify that the cluster is in a Running state:
+### Supported Add-ons
- ```bash
- 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](/reference/replicated-cli-cluster-ls).
+This section lists the supported cluster add-ons for clusters created with CMX.
-1. Run the following command to open a new shell session with the kubeconfig configured for the cluster:
-
- ```bash
- 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](/reference/replicated-cli-cluster-shell).
-
-1. Verify that you can interact with the cluster through kubectl by running a command. For example:
-
- ```bash
- kubectl get ns
- ```
-
-1. Press Ctrl-D or type `exit` when done to end the shell and the connection to the server.
-
-## Upgrade Clusters (kURL Only)
+#### object-store (Alpha)
-For kURL clusters provisioned with CMX, 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 Replicated cluster object store add-on can be used to create S3 compatible object store buckets for clusters (currently only AWS S3 is supported for EKS clusters).
-The following example upgrades a kURL cluster from its previous version to version `9d5a44c`:
+Assuming you already have a cluster, run the following command with the cluster ID to create an object store bucket:
```bash
-replicated cluster upgrade cabb74d5 --version 9d5a44c
+$ replicated cluster addon create object-store 4d2f7e70 --bucket-prefix mybucket
+05929b24 Object Store pending {"bucket_prefix":"mybucket"}
+$ replicated cluster addon ls 4d2f7e70
+ID TYPE STATUS DATA
+05929b24 Object Store ready {"bucket_prefix":"mybucket","bucket_name":"mybucket-05929b24-cmx","service_account_namespace":"cmx","service_account_name":"mybucket-05929b24-cmx","service_account_name_read_only":"mybucket-05929b24-cmx-ro"}
```
-For command usage, see [cluster upgrade](/reference/replicated-cli-cluster-upgrade).
+This will create two service accounts in a namespace, one read-write and the other read-only access to the object store bucket.
+
+Additional service accounts can be created in any namespace with access to the object store by annotating the new service account with the same `eks.amazonaws.com/role-arn` annotation found in the predefined ones (`service_account_name` and `service_account_name_read_only`).
+
+
+
+ | Type |
+ Description |
+
+
+ | Supported Kubernetes Distributions |
+ EKS (AWS S3) |
+
+
+ | Cost |
+ Flat fee of $0.50 per bucket. |
+
+
+ | Options |
+
+
+ - bucket_prefix (string): A prefix for the bucket name to be created (required)
+
+ |
+
+
+ | Data |
+
+
+ - bucket_prefix: The prefix specified by the user for the bucket name
+
+
+ - bucket_name: The actual bucket name
+
+
+ - service_account_namespace: The namespace in which the service accounts (`service_account_name` and `service_account_name_read_only`) have been created.
+
+
+ - service_account_name: The service account name for read-write access to the bucket.
+
+
+ - service_account_name_read_only: The service account name for read-only access to the bucket.
+
+ |
+
+
-## 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](/reference/replicated-cli-cluster-ls).
-
-1. Run the following command:
+## Prepare Clusters
- ```
- replicated cluster rm CLUSTER_ID
- ```
- Where `CLUSTER_ID` is the ID of the target cluster.
- For command usage, see [cluster rm](/reference/replicated-cli-cluster-rm).
-1. 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](/reference/replicated-cli-cluster-ls).
+For information about using the `cluster prepare` command to streamline development workflows, see [Develop with CMX](cmx-develop).
-### Vendor Portal
+## Access Clusters
-To delete a cluster using the Vendor Portal:
+For information about accessing clusters to interact with kubectl, see [Access Clusters](/vendor/cmx-develop#access-clusters) in _Develop with CMX_.
-1. Go to **Compatibility Matrix**.
+## Upgrade Clusters (kURL Only)
-1. Under **Clusters**, in the vertical dots menu for the target cluster, click **Delete cluster**.
+For information about upgrading kURL clusters, see [Upgrade Clusters (kURL Only)](/vendor/cmx-develop#upgrade-clusters-kurl-only) in _Develop with CMX_.
- 
+## Delete Clusters
- [View a larger version of this image](/images/cmx-delete-cluster.png)
\ No newline at end of file
+For information about deleting clusters, see [Delete Clusters](/vendor/cmx-develop#delete-clusters) in _Develop with CMX_.
\ No newline at end of file
diff --git a/docs/vendor/testing-network-policy.md b/docs/vendor/testing-network-policy.md
index 9fc76d2033..cdde4b4ab0 100644
--- a/docs/vendor/testing-network-policy.md
+++ b/docs/vendor/testing-network-policy.md
@@ -1,117 +1,22 @@
-# Test in Air Gap Environments (Beta)
+# CMX Network Reports
-This topic describes how to change the network policy of a virtual machine (VM) or a VM-based cluster with Replicated Compatibility Matrix (CMX), and how to collect and analyze network events to understand your application's behavior in air-gapped environments.
+This topic describes how to use Replicated Compatibility Matrix (CMX) network reporting to collect and analyze network events from VMs and clusters, helping you understand your application's network behavior in different environments including air-gapped scenarios.
-## Set Network Policy to `airgap`
+For information about changing the network policy of a VM or cluster to simulate air-gapped environments, see [Test in Air Gap Environments](cmx-airgap).
-VMs and [VM-based clusters](/vendor/testing-supported-clusters#vm-clusters) created with CMX can use one of the following network policies:
+## Overview
-| Network Policy | Description |
-| :---- | :---- |
-| `open` | No restrictions on network traffic. |
-| `airgap` | Restrict all network traffic. |
+CMX network reporting helps you understand your application's network activity by capturing and analyzing network events from VMs and VM-based clusters. You can use network reporting to:
-By default, all VMs and clusters are created with an `open` network policy. You can change the network policy to `airgap` to simulate an air-gapped environment with no outbound internet access. This `airgap` network policy is particularly useful for previewing how your application will perform in air-gapped end customer environments.
+* Monitor network activity in real-time or review aggregated summaries
+* Identify unexpected network calls before deploying to production
+* Validate application behavior in air-gapped environments
+* Troubleshoot connectivity issues
-Network policies are configured at the network level and apply to all VMs and VM-based clusters within the network.
-
-### For VM-Based Clusters
-
-To set the network policy of a VM-based cluster:
-
-1. Create a cluster:
-
- ```bash
- 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](/vendor/testing-supported-clusters#vm-clusters).
-
-1. Watch until the cluster status is `running`:
-
- ```bash
- replicated cluster ls --watch
- ```
-
-1. 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.
-
-1. Change the network policy to `airgap`:
-
- ```bash
- replicated network update NETWORK_ID --policy airgap
- ```
- Where `NETWORK_ID` is the ID of the network from the output of the `cluster ls` command.
-
-1. Verify that the cluster's policy is `airgap` and the status is `running`:
-
- ```bash
- replicated cluster ls
- ```
-
- ```bash
- 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
- ```
-
- The air gap network is enabled when the status is `running`.
-
-1. (Optional) To verify that there is no outbound connectivity from the cluster, enable network reporting and view network events. See [Collect and View Network Reports](#collect-and-view-network-reports).
-
-1. (Optional) Test an air gap installation of your application in the cluster. See [Install and Update with Helm in Air Gap Environments](/vendor/helm-install-airgap).
-
-### For VMs
-
-To set the network policy of a VM:
-
-1. Create a VM:
-
- ```bash
- replicated vm create --distribution ubuntu
- ```
-
-1. Wait until the VM status is running:
-
- ```bash
- replicated vm ls
- ```
-
-1. SSH onto the VM:
-
- ```bash
- 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 a VM](/vendor/testing-vm-create#connect-to-a-vm).
-
-1. Set the network policy to `airgap`:
-
- ```bash
- 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:**
-
- ```bash
- replicated network update 85eb50a8 --policy airgap
- ```
-
- ```bash
- 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
- ```
-
-1. (Optional) To verify that there is no outbound connectivity from the VM, enable network reporting and view network events. See [Collect and View Network Reports](#collect-and-view-network-reports).
+To provide flexibility in testing, you can enable network reporting to capture all network activity, whether the network policy is set to `open` or `airgap`. Even when the network policy is set to `airgap` and network egress is blocked, all connection attempts and DNS queries are still captured in the report.
## Collect and View Network Reports
-CMX network reporting helps you understand your application's network activity. To provide flexibility in testing, you can enable network reporting to capture all network activity, whether the network policy is set to `open` or `airgap`. Even when the network policy is set to `airgap` and network egress is blocked, all connection attempts and DNS queries are still captured in the report. This helps you identify unexpected network calls before deploying to an air-gapped environment.
-
Network reporting is not enabled by default. For information about how to collect and view reports through the Vendor Portal or the Replicated CLI, see the sections below.
There are two types of network reports:
diff --git a/docs/vendor/testing-pricing.mdx b/docs/vendor/testing-pricing.mdx
index a2e2edc309..c4257897ca 100644
--- a/docs/vendor/testing-pricing.mdx
+++ b/docs/vendor/testing-pricing.mdx
@@ -18,7 +18,7 @@ The following provides more detail about the costs that are included in CMX usag
For VMs, a `running` status indicates an SSH endpoint is available. For clusters, a `running` status indicates a working kubeconfig for the cluster is accessible. Additionally, clusters are verified prior to transitioning to a `running` status. Verification includes checking that the cluster is healthy and running with the correct number of nodes, as well as passing sonobuoy tests in `--quick` mode.
:::
-* Additional charges when applicable for cluster [add-ons](/vendor/testing-cluster-addons).
+* Additional charges when applicable for cluster [add-ons](/vendor/testing-how-to#cluster-add-ons-alpha).
## Credit Balance
diff --git a/docs/vendor/testing-supported-clusters.md b/docs/vendor/testing-supported-clusters.md
index 331ad3facd..cc91d37e08 100644
--- a/docs/vendor/testing-supported-clusters.md
+++ b/docs/vendor/testing-supported-clusters.md
@@ -5,15 +5,23 @@ import InstanceTypes from "../partials/cmx/_instance-types.mdx"
This topic describes the supported Kubernetes distributions, Kubernetes versions, instance types, nodes, limitations, and common use cases for clusters created with Replicated Compatibility Matrix (CMX).
-CMX provisions cloud-based or virtual machine (VM) clusters.
+## Overview
-## VM Clusters
+CMX can provision both custom VM-based clusters and warm pool cloud clusters to meet different testing needs:
-This section lists the supported VM cluster distributions for clusters created with CMX.
+* **Custom VM-based clusters** (kind, k3s, RKE2, OpenShift OKD, Embedded Cluster, kURL) run on Replicated bare metal servers with the CMX cluster provisioner. This allows for greater flexibility than with cloud clusters. For example, with VM-based distributions, CMX offers warm pools to make OpenShift startup times very fast.
-VM-based clusters refers to clusters that run on Hetzner servers with the CMX cluster provisioner. This allows for greater flexibility than with Cloud Clusters like AWS, EKS, etc. For example, with VM-based distributions, CMX offers warm pools to make Openshift startup times very fast.
+* **Warm pool cloud clusters** (EKS, GKE, AKS, OKE) are provisioned in Replicated-managed cloud accounts with control planes ready to quickly add node groups when requested.
-For information about provisioning VMs, which come without pre-installed clusters and allow for more access to the OS, see [Create VMs](testing-vm-create).
+For information about provisioning VMs without pre-installed clusters that allow for more access to the OS, see [CMX VMs](cmx-vms).
+
+For information about creating and managing clusters, see [CMX Clusters](testing-how-to).
+
+## VM-Based Clusters
+
+This section lists the supported VM-based cluster distributions for clusters created with CMX.
+
+VM-based clusters refers to clusters that run on Hetzner servers with the CMX cluster provisioner. This allows for greater flexibility than with cloud clusters. For example, with VM-based distributions, CMX offers warm pools to make OpenShift startup times very fast.
### kind
@@ -50,7 +58,7 @@ CMX supports creating [kind](https://kind.sigs.k8s.io/) clusters.
| Limitations |
- See Limitations |
+ See Limitations |
| Common Use Cases |
@@ -97,7 +105,7 @@ CMX supports creating [k3s](https://k3s.io) clusters.
| Limitations |
- For additional limitations that apply to all distributions, see Limitations. |
+ For additional limitations that apply to all distributions, see Limitations. |
| Common Use Cases |
@@ -144,7 +152,7 @@ CMX supports creating [RKE2](https://docs.rke2.io/) clusters.
| Limitations |
- For additional limitations that apply to all distributions, see Limitations. |
+ For additional limitations that apply to all distributions, see Limitations. |
| Common Use Cases |
@@ -202,7 +210,7 @@ By default, kubeconfig context is set to the `kubeadmin` user. To switch to the
- For additional limitations that apply to all distributions, see Limitations.
+ For additional limitations that apply to all distributions, see Limitations.
@@ -251,7 +259,7 @@ CMX supports creating clusters with Replicated Embedded Cluster. For more inform
A valid customer license is required to create an Embedded Cluster.
The [cluster prepare](/vendor/testing-how-to#prepare-clusters) command is not supported.
- For additional limitations that apply to all distributions, see Limitations.
+ For additional limitations that apply to all distributions, see Limitations.
@@ -295,7 +303,7 @@ CMX supports creating [kURL](https://kurl.sh) clusters.
| Limitations |
- Does not work with the Longhorn add-on. For additional limitations that apply to all distributions, see Limitations. |
+ Does not work with the Longhorn add-on. For additional limitations that apply to all distributions, see Limitations. |
| Common Use Cases |
@@ -344,7 +352,7 @@ CMX supports creating [AWS EKS](https://aws.amazon.com/eks/?nc2=type_a) clusters
| Limitations |
- You can only choose a minor version, not a patch version. The EKS installer chooses the latest patch for that minor version. For additional limitations that apply to all distributions, see Limitations. |
+ You can only choose a minor version, not a patch version. The EKS installer chooses the latest patch for that minor version. For additional limitations that apply to all distributions, see Limitations. |
| Common Use Cases |
@@ -387,7 +395,7 @@ CMX supports creating [Google GKE](https://cloud.google.com/kubernetes-engine) c
| Limitations |
- You can choose only a minor version, not a patch version. The GKE installer chooses the latest patch for that minor version. For additional limitations that apply to all distributions, see Limitations. |
+ You can choose only a minor version, not a patch version. The GKE installer chooses the latest patch for that minor version. For additional limitations that apply to all distributions, see Limitations. |
| Common Use Cases |
@@ -430,7 +438,7 @@ CMX supports creating [Azure AKS](https://azure.microsoft.com/en-us/products/kub
| Limitations |
- You can choose only a minor version, not a patch version. The AKS installer chooses the latest patch for that minor version. For additional limitations that apply to all distributions, see Limitations. |
+ You can choose only a minor version, not a patch version. The AKS installer chooses the latest patch for that minor version. For additional limitations that apply to all distributions, see Limitations. |
| Common Use Cases |
@@ -473,7 +481,7 @@ CMX supports creating [Oracle Container Engine for Kubernetes (OKE)](https://doc
| Limitations |
- Provising an OKE cluster does take between 8 to 10 minutes. If needed, some timeouts in your CI pipelines might have to be adjusted. For additional limitations that apply to all distributions, see Limitations. |
+ Provising an OKE cluster does take between 8 to 10 minutes. If needed, some timeouts in your CI pipelines might have to be adjusted. For additional limitations that apply to all distributions, see Limitations. |
| Common Use Cases |
diff --git a/docs/vendor/testing-vm-about.md b/docs/vendor/testing-vm-about.md
index c87e3fc709..a6debaafd7 100644
--- a/docs/vendor/testing-vm-about.md
+++ b/docs/vendor/testing-vm-about.md
@@ -1,4 +1,3 @@
-import Prerequisites from "../partials/cmx/_prerequisites.mdx"
import InstanceTypes from "../partials/cmx/_instance-types.mdx"
# About CMX VMs (Beta)
@@ -30,17 +29,8 @@ The following describes the Replicated instance types for VMs:
## Limitations
-Creating VMs with CMX has the following limitations:
-
-- Creating VMs with CMX is a Beta feature.
-- Installing Embedded Cluster on a VM created with CMX is supported for Embedded Cluster versions 1.21.0 or later.
-- [GitHub Actions](/vendor/testing-ci-cd#replicated-github-actions) are not supported for CMX VMs.
-- The [cluster prepare](/reference/replicated-cli-cluster-prepare) command is not supported for CMX VMs.
+For limitations, see [Limitations](/vendor/cmx-overview#limitations) in _CMX Overview_.
## Prerequisites
-Before you can use CMX VMs, you must complete the following prerequisites:
-
-
-
-* Existing accounts must accept the TOS for the trial on the [**Compatibility Matrix**](https://vendor.replicated.com/compatibility-matrix) page in the Replicated Vendor Portal.
+For prerequisites, see [Prerequisites](/vendor/cmx-overview#prerequisites) in _CMX Overview_.
diff --git a/docs/vendor/testing-vm-networking.md b/docs/vendor/testing-vm-networking.md
index e15ed26bb9..fb794ae3c9 100644
--- a/docs/vendor/testing-vm-networking.md
+++ b/docs/vendor/testing-vm-networking.md
@@ -60,8 +60,7 @@ The following diagram shows how the traffic is routed into the service using CMX
### Limitations
-* A tunnel can only connect to one service. If you need fanout routing into different services, consider installing the nginx ingress controller as a `NodePort` service and exposing it.
-* Tunnels are not supported for cloud distributions (EKS, GKE, AKS).
+For limitations related to tunnels, see [Limitations](/vendor/cmx-overview#limitations) in _CMX Overview_.
### Supported Protocols
diff --git a/docs/vendor/testing-vm-transfer-files.md b/docs/vendor/testing-vm-transfer-files.md
index bb6fb4adfb..a59b84efda 100644
--- a/docs/vendor/testing-vm-transfer-files.md
+++ b/docs/vendor/testing-vm-transfer-files.md
@@ -57,12 +57,8 @@ Transferring files using CMX Forwarder is slower than using direct SSH due to ad
:::
#### Limitations
-Transferring files using the CMX Forwarder has the following limitations:
-- `scp` with flag `-O` (legacy scp protocol) is not supported.
-- Relative paths is not supported. For example:
- - Unsupported: `scp somefile VMID@replicatedvm.com:~`
- - Supported: `scp somefile VMID@replicatedvm:/home/folder/somefile`
-- File permissions are not inherited.
+
+For limitations related to file transfers using the CMX Forwarder, see [Limitations](/vendor/cmx-overview#limitations) in _CMX Overview_.
To copy files to the VM using SCP after connecting with the CMX Forwarder:
diff --git a/docs/vendor/tutorial-embedded-cluster-automation.mdx b/docs/vendor/tutorial-embedded-cluster-automation.mdx
index 0dbbcc90a8..b01f24d900 100644
--- a/docs/vendor/tutorial-embedded-cluster-automation.mdx
+++ b/docs/vendor/tutorial-embedded-cluster-automation.mdx
@@ -27,13 +27,13 @@ Before you begin, do the following to set up your environment:
* **Option 1: Use Compatibility Matrix.** To use Replicated Compatibility Matrix (CMX) to create a VM, do the following before proceeding:
- * Request CMX credits. You can request credits by creating a Vendor Portal account and then going to [**Compatibility Matrix > Request more credits**](https://vendor.replicated.com/compatibility-matrix) in the Vendor Portal. For more information about creating an account, see [Create a Vendor Account](vendor-portal-creating-account). For more information about CMX credits, see [Billing and Credits](/vendor/testing-about#billing-and-credits).
+ * Request CMX credits. You can request credits by creating a Vendor Portal account and then going to [**Compatibility Matrix > Request more credits**](https://vendor.replicated.com/compatibility-matrix) in the Vendor Portal. For more information about creating an account, see [Create a Vendor Account](vendor-portal-creating-account). For more information about CMX credits, see [Billing and Credits](/vendor/cmx-overview#billing-and-credits).
:::note
If you are new to the Replicated platform, you might be eligible for $100 in free CMX credits. To request your free credits, reach out to our sales team at https://www.replicated.com/contact and note in the comments that you are completing a Replicated tutorial.
:::
- * Ensure that you have an SSH key in your GitHub account. Then, add your GitHub username to your Vendor Portal [**Account Settings**](https://vendor.replicated.com/account-settings). This will provide SSH access to VMs that you create with CMX. For more information, see [Set Up SSH Access](/vendor/testing-vm-create#set-up-ssh-access) in _Create VMs_.
+ * Ensure that you have an SSH key in your GitHub account. Then, add your GitHub username to your Vendor Portal [**Account Settings**](https://vendor.replicated.com/account-settings). This will provide SSH access to VMs that you create with CMX. For more information, see [Set Up SSH Access](/vendor/cmx-vms#set-up-ssh-access) in _CMX VMs_.
After you complete the prerequisites above, continue to the [Tutorial](#tutorial). You will create the VM with CMX as part of the tutorial.
diff --git a/docs/vendor/tutorial-helm-cli.mdx b/docs/vendor/tutorial-helm-cli.mdx
index dce730ec09..b522c04233 100644
--- a/docs/vendor/tutorial-helm-cli.mdx
+++ b/docs/vendor/tutorial-helm-cli.mdx
@@ -26,7 +26,7 @@ Before you begin, do the following to set up your environment:
* Ensure that you have access to a Kubernetes cluster where you can test the installation using the Helm CLI:
- * **Option 1: Use Compatibility Matrix.** To use Replicated Compatibility Matrix (CMX) to create a cluster for this tutorial, first request CMX credits. You can request credits by creating a Vendor Portal account and then going to [**Compatibility Matrix > Request more credits**](https://vendor.replicated.com/compatibility-matrix) in the Vendor Portal. For more information about creating an account, see [Create a Vendor Account](vendor-portal-creating-account). For more information about CMX credits, see [Billing and Credits](/vendor/testing-about#billing-and-credits).
+ * **Option 1: Use Compatibility Matrix.** To use Replicated Compatibility Matrix (CMX) to create a cluster for this tutorial, first request CMX credits. You can request credits by creating a Vendor Portal account and then going to [**Compatibility Matrix > Request more credits**](https://vendor.replicated.com/compatibility-matrix) in the Vendor Portal. For more information about creating an account, see [Create a Vendor Account](vendor-portal-creating-account). For more information about CMX credits, see [Billing and Credits](/vendor/cmx-overview#billing-and-credits).
:::note
If you are new to the Replicated platform, you might be eligible for $100 in free CMX credits. To request your free credits, reach out to our sales team at https://www.replicated.com/contact and note in the comments that you are completing a Replicated tutorial.
diff --git a/docusaurus.config.js b/docusaurus.config.js
index e8584c6b95..2f5df9bbac 100644
--- a/docusaurus.config.js
+++ b/docusaurus.config.js
@@ -131,7 +131,7 @@ const config = {
items: [
{
type: 'doc',
- docId: 'vendor/testing-about',
+ docId: 'vendor/cmx-overview',
label: 'Compatibility Matrix',
},
{
diff --git a/sidebars.js b/sidebars.js
index d511a57aba..def141895e 100644
--- a/sidebars.js
+++ b/sidebars.js
@@ -198,19 +198,18 @@ const sidebars = {
type: 'category',
label: 'Compatibility Matrix',
items: [
- 'vendor/testing-about',
- 'vendor/testing-supported-clusters',
+ 'vendor/cmx-overview',
+ 'vendor/cmx-vms',
'vendor/testing-how-to',
- 'vendor/testing-ingress',
- 'vendor/testing-cluster-addons',
- 'vendor/testing-vm-about',
- 'vendor/testing-vm-create',
- 'vendor/testing-vm-networking',
+ 'vendor/testing-supported-clusters',
+ 'vendor/cmx-networking',
'vendor/testing-network-policy',
+ 'vendor/cmx-develop',
+ 'vendor/cmx-airgap',
'vendor/testing-ci-cd',
{
type: 'category',
- label: 'Managing Cost with CMX',
+ label: 'Manage Cost with CMX',
items: [
'vendor/testing-pricing',
'vendor/compatibility-matrix-usage',
diff --git a/static/js/generate-llms.js b/static/js/generate-llms.js
index a65626607d..23bbbe623d 100644
--- a/static/js/generate-llms.js
+++ b/static/js/generate-llms.js
@@ -18,7 +18,7 @@ const STATIC_HEADER = `# Replicated Documentation
const INCLUDED_FILES = [
// Add specific file paths, relative to the docs directory
// Compatibility Matrix docs
- 'vendor/testing-about.md',
+ 'vendor/cmx-overview.md',
'vendor/testing-how-to.md',
'vendor/testing-supported-clusters.md',
// Embedded Cluster docs
+
+[View a larger version of this image](/images/compatibility-matrix-ingress.png)
+
+### Limitations
+
+For limitations related to tunnels, see [Limitations](/vendor/cmx-overview#limitations) in _CMX Overview_.
+
+### Supported Protocols
+
+A tunnel can support one or more protocols. The supported protocols are HTTP, HTTPS, WS and WSS. GRPC and other protocols are not routed into the cluster.
+
+### Expose Ports with the CLI
+
+To expose a port on a cluster using the Replicated CLI:
+
+```bash
+replicated cluster port expose \
+ [cluster id] \
+ --port [node port] \
+ --protocol [protocol]
+```
+
+See [cluster port](/reference/replicated-cli-cluster-port).
+
+### Use Wildcard DNS
+
+Optionally, you can specify the `--wildcard` flag to expose this port with wildcard DNS and TLS certificate. This feature adds extra time to provision the port, so it should only be used if necessary.
+
+For example, if you have the nginx ingress controller installed and the node port is 32456:
+
+```bash
+% replicated cluster ls
+ID NAME DISTRIBUTION VERSION STATUS
+1e616c55 tender_ishizaka k3s 1.29.2 running
+
+% replicated cluster port expose \
+ 1e616c55 \
+ --port 32456 \
+ --protocol http \
+ --protocol https \
+ --wildcard
+```
+
+## View Exposed Ports
+
+To view all exposed ports, use the `replicated port ls` subcommand with the cluster or VM ID:
+
+```bash
+replicated cluster port ls CLUSTER_ID
+```
+
+```bash
+replicated vm port ls VMID_OR_VMNAME
+```
+
+## Remove Ports
+
+Exposed ports are automatically deleted when the cluster or VM terminates.
+
+If you want to remove a port (and the associated DNS records and TLS certs) prior to termination, run the `port rm` subcommand with the cluster or VM ID:
+
+```bash
+replicated cluster port rm PORT_ID --id CLUSTER_ID
+```
+
+```bash
+replicated vm port rm VMID_OR_VMNAME
+```
+
+You can remove just one protocol, or all. Removing all protocols also removes the DNS record and TLS cert.
+
+## Use Shared Networks
+
+This section explains how to create VMs and clusters with CMX on 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:
+
+ ```bash
+ replicated cluster create --distribution K8S_DISTRIBUTION
+ ```
+
+ For example, `replicated cluster create --distribution k3s`.
+
+1. 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`.
+
+1. Create a VM on the same network:
+
+ ```bash
+ 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.
+
+```bash
+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:
+ ```bash
+ replicated vm ls
+ ```
+
+ * List networks:
+ ```bash
+ replicated network ls
+ ```
+
+1. In the output of the command, copy the network ID.
+
+1. Use the `--network` flag to create a new VM on the same network:
+
+ ```bash
+ replicated vm create --distribution ubuntu --network NETWORK_ID
+ ```
+ Where `NETWORK_ID` is the network ID that you copied in the previous step.
+
+
+
diff --git a/docs/vendor/cmx-overview.md b/docs/vendor/cmx-overview.md
new file mode 100644
index 0000000000..64cc74d6b3
--- /dev/null
+++ b/docs/vendor/cmx-overview.md
@@ -0,0 +1,85 @@
+# CMX Overview
+
+This topic describes Replicated Compatibility Matrix (CMX), including use cases, architecture, billing, and more.
+
+## Overview
+
+You can use CMX to quickly provision ephemeral VMs or clusters so you can develop and test against a customer-representative environment. Example use cases for CMX include:
+
+* Quickly get a cluster or VM to develop on and quickly test changes
+* Run tests to validate that your application will install smoothly in the customer environment
+* Reproduce a reported issue on a customer-representative environment for troubleshooting
+
+
+## Use Cases
+
+The following table shows which CMX infrastructure option to use based on how your customers install your application:
+
+| | Install in Customer VM | Install in Customer Cluster |
+|-----------------|---------------------|----------------|
+| **Customer Environment** | Linux VM, with no existing Kubernetes cluster | Customer-managed Kubernetes cluster |
+| **Installer** |