From a538dd725d3ea96dadcbd2ad55eb92de5bf71995 Mon Sep 17 00:00:00 2001 From: Han Yu Date: Tue, 9 Dec 2025 11:05:17 -0500 Subject: [PATCH 1/5] CMX unify + rename cmx-overview --- docs/intro-replicated.mdx | 8 +- docs/intro.mdx | 2 +- docs/partials/cmx/_prerequisites.mdx | 2 +- docs/release-notes/rn-vendor-platform.md | 2 +- docs/vendor/ci-overview.md | 2 +- docs/vendor/ci-workflows.mdx | 2 +- docs/vendor/cmx-airgap.md | 207 ++++++++ docs/vendor/cmx-develop.md | 171 +++++++ docs/vendor/cmx-networking.md | 265 ++++++++++ docs/vendor/cmx-overview.md | 41 ++ docs/vendor/cmx-vms.md | 469 ++++++++++++++++++ docs/vendor/environment-setup.mdx | 2 +- docs/vendor/kots-faq.mdx | 2 +- docs/vendor/policies-support-lifecycle.md | 2 +- docs/vendor/quick-start.mdx | 6 +- docs/vendor/replicated-onboarding.mdx | 2 +- docs/vendor/testing-about.md | 38 -- docs/vendor/testing-ci-cd.md | 10 +- docs/vendor/testing-cluster-addons.md | 3 +- docs/vendor/testing-how-to.md | 151 +----- docs/vendor/testing-network-policy.md | 115 +---- docs/vendor/testing-supported-clusters.md | 40 +- .../tutorial-embedded-cluster-automation.mdx | 4 +- docs/vendor/tutorial-helm-cli.mdx | 2 +- docusaurus.config.js | 2 +- sidebars.js | 12 +- static/js/generate-llms.js | 2 +- 27 files changed, 1231 insertions(+), 333 deletions(-) create mode 100644 docs/vendor/cmx-airgap.md create mode 100644 docs/vendor/cmx-develop.md create mode 100644 docs/vendor/cmx-networking.md create mode 100644 docs/vendor/cmx-overview.md create mode 100644 docs/vendor/cmx-vms.md delete mode 100644 docs/vendor/testing-about.md diff --git a/docs/intro-replicated.mdx b/docs/intro-replicated.mdx index 111a4409b5..10a04a0565 100644 --- a/docs/intro-replicated.mdx +++ b/docs/intro-replicated.mdx @@ -27,7 +27,7 @@ The following diagram demonstrates the process of using the Replicated Platform [View a larger version of this image](/images/replicated-platform.png) -The diagram above shows an application that is packaged with the [**Replicated SDK**](/vendor/replicated-sdk-overview). The application is tested in clusters provisioned with the [**Replicated Compatibility Matrix (CMX)**](/vendor/testing-about), then added to a new release in the [**Vendor Portal**](/vendor/releases-about) using an automated CI/CD pipeline. +The diagram above shows an application that is packaged with the [**Replicated SDK**](/vendor/replicated-sdk-overview). The application is tested in clusters provisioned with the [**Replicated Compatibility Matrix (CMX)**](/vendor/cmx-overview), then added to a new release in the [**Vendor Portal**](/vendor/releases-about) using an automated CI/CD pipeline. The application is then installed by a customer ("Big Bank") on a VM. To install, the customer downloads their license, which grants proxy access to the application images through the [**Replicated proxy registry**](/vendor/private-images-about). They also download the installation assets for the [**Replicated Embedded Cluster**](/vendor/embedded-overview) installer. @@ -103,7 +103,7 @@ The following shows an example of the Enterprise Portal dashboard: Replicated Compatibility Matrix (CMX) can be used to create VMs or Kubernetes clusters within minutes or less. You can interact with CMX through the Vendor Portal or the Replicated CLI, making it possible to integrate CMX into your existing CI/CD workflows to programmatically create test environments. -For more information, see [About CMX](/vendor/testing-about). +For more information, see [About CMX](/vendor/cmx-overview). The following shows the CMX page for creating a cluster: @@ -145,7 +145,7 @@ For more information about using the Replicated SDK, see [About the Replicated S The CMX can be used to quickly provision ephemeral VMs and Kubernetes clusters. When integrated into existing CI/CD workflows, the CMX can be used to automatically create a variety of customer-representative environments for testing code changes. -For more information, see [About CMX](/vendor/testing-about). +For more information, see [About CMX](/vendor/cmx-overview). ### License @@ -186,5 +186,5 @@ ISVs can also set up email and Slack notifications to get alerted of important i Support teams can use Replicated features to more quickly diagnose and resolve application issues. For example: - Customize and generate support bundles, which collect and analyze redacted information from the customer's cluster, environment, and application instance. See [About Preflight Checks and Support Bundles](/vendor/preflight-support-bundle-about). -- Provision customer-representative environments with CMX to recreate and diagnose issues. See [About CMX](/vendor/testing-about). +- Provision customer-representative environments with CMX to recreate and diagnose issues. See [About CMX](/vendor/cmx-overview). - Get insights into an instance's status by accessing telemetry data, which covers the health of the application, the current application version, and details about the infrastructure and cluster where the application is running. For more information, see [Customer Reporting](/vendor/customer-reporting). For more information, see [Customer Reporting](/vendor/customer-reporting). diff --git a/docs/intro.mdx b/docs/intro.mdx index 8f43eca92e..a7df1a2144 100644 --- a/docs/intro.mdx +++ b/docs/intro.mdx @@ -248,7 +248,7 @@ import clsx from 'clsx';
- Overview + Overview

Test your application across customer-representative environments

diff --git a/docs/partials/cmx/_prerequisites.mdx b/docs/partials/cmx/_prerequisites.mdx index 6e225add34..20fa041689 100644 --- a/docs/partials/cmx/_prerequisites.mdx +++ b/docs/partials/cmx/_prerequisites.mdx @@ -2,4 +2,4 @@ * Install the Replicated CLI and then authorize the CLI using your vendor account. See [Install the Replicated CLI](/reference/replicated-cli-installing). -* If you have a contract, you can purchase more credits by going to [**Compatibility Matrix > Buy additional credits**](https://vendor.replicated.com/compatibility-matrix). Otherwise, you can request credits by going to [**Compatibility Matrix > Request more credits**](https://vendor.replicated.com/compatibility-matrix) in the Vendor Portal. For more information, see [Billing and Credits](/vendor/testing-about#billing-and-credits). +* If you have a contract, you can purchase more credits by going to [**Compatibility Matrix > Buy additional credits**](https://vendor.replicated.com/compatibility-matrix). Otherwise, you can request credits by going to [**Compatibility Matrix > Request more credits**](https://vendor.replicated.com/compatibility-matrix) in the Vendor Portal. For more information, see [Billing and Credits](/vendor/cmx-overview#billing-and-credits). diff --git a/docs/release-notes/rn-vendor-platform.md b/docs/release-notes/rn-vendor-platform.md index 7d1c5d3c62..ae37f2e0ce 100644 --- a/docs/release-notes/rn-vendor-platform.md +++ b/docs/release-notes/rn-vendor-platform.md @@ -6,7 +6,7 @@ pagination_prev: null # Vendor Platform Release Notes -This topic contains release notes for the Replicated Vendor Platform, which includes the [Vendor Portal](/vendor/vendor-portal-creating-account), the [Replicated CLI](/reference/replicated-cli-installing), and [Compatibility Matrix](/vendor/testing-about). The release notes list new features, improvements, bug fixes, known issues, and breaking changes. +This topic contains release notes for the Replicated Vendor Platform, which includes the [Vendor Portal](/vendor/vendor-portal-creating-account), the [Replicated CLI](/reference/replicated-cli-installing), and [Compatibility Matrix](/vendor/cmx-overview). The release notes list new features, improvements, bug fixes, known issues, and breaking changes. diff --git a/docs/vendor/ci-overview.md b/docs/vendor/ci-overview.md index 42ffa426ba..99aaaefb11 100644 --- a/docs/vendor/ci-overview.md +++ b/docs/vendor/ci-overview.md @@ -16,7 +16,7 @@ The following are Replicated's best practices and recommendations for CI/CD: * Include unique workflows for development and for releasing your application. This allows you to run tests on every commit, and then to promote releases to internal and customer-facing channels only when ready. For more information about the workflows that Replicated recommends, see [Recommended CI/CD Workflows](ci-workflows). -* Integrate Replicated Compatibility Matrix (CMX) into your CI/CD workflows to quickly create multiple different types of clusters where you can deploy and test your application. Supported distributions include OpenShift, GKE, EKS, and more. For more information, see [About CMX](testing-about). +* Integrate Replicated Compatibility Matrix (CMX) into your CI/CD workflows to quickly create multiple different types of clusters where you can deploy and test your application. Supported distributions include OpenShift, GKE, EKS, and more. For more information, see [About CMX](cmx-overview). * If you use the GitHub Actions CI/CD platform, integrate the custom GitHub actions that Replicated maintains to replace repetitive tasks related to distributing application with Replicated or using CMX. For more information, see [Use Replicated GitHub Actions in CI/CD](/vendor/ci-workflows-github-actions). diff --git a/docs/vendor/ci-workflows.mdx b/docs/vendor/ci-workflows.mdx index 99bc5f1706..cd8de8505a 100644 --- a/docs/vendor/ci-workflows.mdx +++ b/docs/vendor/ci-workflows.mdx @@ -6,7 +6,7 @@ This topic provides Replicated's recommended development and release workflows f ## Overview -Replicated recommends that you maintain unique CI/CD workflows for development (continuous integration) and for releasing your software (continuous delivery). The development and release workflows in this topic describe the recommended steps and jobs to include in your own workflows, including how to integrate Replicated Compatibility Matrix (CMX) into your workflows for testing. For more information about CMX, see [About CMX](testing-about). +Replicated recommends that you maintain unique CI/CD workflows for development (continuous integration) and for releasing your software (continuous delivery). The development and release workflows in this topic describe the recommended steps and jobs to include in your own workflows, including how to integrate Replicated Compatibility Matrix (CMX) into your workflows for testing. For more information about CMX, see [About CMX](cmx-overview). For each step, the corresponding Replicated CLI command is provided. Additionally, for users of the GitHub Actions platform, a corresponding custom GitHub action that is maintained by Replicated is also provided. For more information about using the Replicated CLI, see [Install the Replicated CLI](/reference/replicated-cli-installing). For more information about the Replicated GitHub actions, see [Use Replicated GitHub Actions in CI/CD](ci-workflows-github-actions). diff --git a/docs/vendor/cmx-airgap.md b/docs/vendor/cmx-airgap.md new file mode 100644 index 0000000000..b0f4d822a6 --- /dev/null +++ b/docs/vendor/cmx-airgap.md @@ -0,0 +1,207 @@ +# Test in Air Gap Environments + +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. + +## Set Network Policy to `airgap` + +VMs and [VM-based clusters](/vendor/testing-supported-clusters#vm-clusters) created with CMX can use one of the following network policies: + +| Network Policy | Description | +| :---- | :---- | +| `open` | No restrictions on network traffic. | +| `airgap` | Restrict all network traffic. | + +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. + +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/cmx-vms#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). + +## 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: + +| Report Type | Contents | +|---|---| +| **Running Report**
See all network events
captured in near real-time | | +| **Report Summary**
Aggregated analysis of
captured network events| | + +### Vendor Portal + +To set the network policy and collect and view reports in the Vendor Portal: + +1. Go to **Compatibility Matrix** > **Network Policy**. + +2. To collect a network report, toggle on the switch under **Reporting**. + +3. (Optional) Toggle from `open` to `airgap` under **Policy Type** to block all network egress. + +4. Where available, click "View report" under **Report** to see the reporting table. You can also click "Export JSON" to download the raw report data. + + :::note + When reporting is **ON** for an active network, all network events display in a **Running Report**. Once the network is terminated, the **Report Summary** is automatically generated. + ::: + + **Running Report** + + ![Network Policy page with running report, showing all network events captured](/images/cmx-network-report.png) + + [View a larger version of this image](/images/cmx-network-report.png) + + **Report Summary** + + ![Network Policy page with report summary, showing domain names and destination IPs](/images/cmx-network-report-summary.png) + + [View a larger version of this image](/images/cmx-network-report-summary.png) + +### CLI + +To collect and view a network report from the CLI: + +1. Turn on network reporting: + + ```bash + replicated network update NETWORK_ID --collect-report + ``` + Where `NETWORK_ID` is the ID of the network. You can get the network ID by running `replicated network ls`. + +1. (Optional) Confirm that reporting is **ON** for the network: + + ```bash + replicated network ls + ``` + + **Example output:** + + ``` + ID NAME STATUS CREATED EXPIRES POLICY HAS REPORT + a1b2c3d4 example_network_1 running 2025-01-28 16:04 PST 2025-01-28 18:06 PST open off + e5f6g7h8 example_network_2 running 2025-01-28 12:10 PST 2025-01-28 20:11 PST airgap on + ``` +1. View the network report: + + See network event summary that aggregates all unique domains and destination IPs, with connection counts and other details (JSON format): + + ```bash + replicated network report NETWORK_ID --summary + ``` + + See all network events (JSON format): + + ```bash + replicated network report NETWORK_ID + ``` + + Watch as new network events occur (JSON format): + + ```bash + replicated network report NETWORK_ID --watch + ``` + + :::note + Network events are batched for display in the report, so appear with a short delay. + ::: + + +## Related Topics + +* [Air Gap Installation with Embedded Cluster](/enterprise/installing-embedded-air-gap) +* [Install and Update with Helm in Air Gap Environments](/vendor/helm-install-airgap) + + + diff --git a/docs/vendor/cmx-develop.md b/docs/vendor/cmx-develop.md new file mode 100644 index 0000000000..ed4d646244 --- /dev/null +++ b/docs/vendor/cmx-develop.md @@ -0,0 +1,171 @@ +import Prerequisites from "../partials/cmx/_prerequisites.mdx" + +# Develop with CMX + +This topic describes how to use Replicated Compatibility Matrix (CMX) to streamline application development and testing workflows. + +## About Developing with CMX + +CMX provides features that make it easy to quickly provision test environments and deploy your application for iterative development and testing. The `cluster prepare` command is particularly useful for reducing the number of steps required to get from code to a running application in a test cluster. + +## Prerequisites + +Before you can use CMX clusters, 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. + +## 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). + +## Access Clusters + +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. + +To access a cluster from the command line: + +1. Verify that the cluster is in a Running state: + + ```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). + +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) + +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 following example upgrades a kURL cluster from its previous version to version `9d5a44c`: + +```bash +replicated cluster upgrade cabb74d5 --version 9d5a44c +``` + +For command usage, see [cluster upgrade](/reference/replicated-cli-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](/reference/replicated-cli-cluster-ls). + +1. 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](/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). + +### Vendor Portal + +To delete a cluster using the Vendor Portal: + +1. Go to **Compatibility Matrix**. + +1. Under **Clusters**, in the vertical dots menu for the target cluster, click **Delete cluster**. + + Delete cluster button + + [View a larger version of this image](/images/cmx-delete-cluster.png) + + + diff --git a/docs/vendor/cmx-networking.md b/docs/vendor/cmx-networking.md new file mode 100644 index 0000000000..adb73407ba --- /dev/null +++ b/docs/vendor/cmx-networking.md @@ -0,0 +1,265 @@ +# CMX Networking + +This topic describes the networking options for accessing applications deployed on VMs and clusters created with Replicated Compatibility Matrix (CMX), including how to expose ports, use tunnels, and connect VMs and clusters on shared networks. + +## Overview + +CMX provides flexible networking options to help you access and test your applications across different deployment scenarios. The networking approach varies depending on whether you're using VMs, VM-based clusters, or cloud clusters. + +### Internal vs. External Access + +When working with CMX: + +* **Internal networking** (pod-to-pod): Handled automatically within clusters using standard Kubernetes networking +* **External access**: Requires specific configuration depending on the distribution type + +## Networking Options for Clusters + +After deploying your application into CMX clusters, you will want to execute your tests using your own test runner. In order to do this, you need to access your application. CMX offers several methods to access your application. + +Some standard Kubernetes networking options are available, but vary based on the distribution. For VM-based distributions, there is no default network route into the cluster, making inbound connections challenging to create. + +### Port Forwarding + +Port forwarding is a low-cost and portable mechanism to access your application. Port forwarding works on all clusters supported by CMX because the connection is initiated from the client, over the Kubernetes API server port. + +If you have a single service or pod and are not worried about complex routing, this is a good mechanism. The basic steps are to connect the port-forward, execute your tests against localhost, and then shut down the port-forward. + +### LoadBalancer + +If your application is only running on cloud services (EKS, GKE, AKS), you can create a service of type `LoadBalancer`. This will provision the cloud-provider specific load balancer. + +The `LoadBalancer` service will be filled by the in-tree Kubernetes functionality that's integrated with the underlying cloud provider. You can then query the service definition using `kubectl` and connect to and execute your tests over the `LoadBalancer` IP address. + +:::note +AKS clusters require the following additional annotations to be set on LoadBalancer services for traffic to be routed: +* `controller.service.externalTrafficPolicy` must be set to `Local` +* `service.beta.kubernetes.io/azure-load-balancer-health-probe-request-path` must be set to a health check endpoint that returns a successful HTTP response when your service is ready + +For more information about these annotations, see the [Use a public standard load balancer in Azure Kubernetes Service (AKS)](https://learn.microsoft.com/en-us/azure/aks/load-balancer-standard) in the Azure documentation. +::: + +### Ingress + +Ingress is a good way to recreate customer-representative environments, but the problem still remains on how to get inbound access to the IP address that the ingress controller allocates. + +Ingress is also not perfectly portable; each ingress controller might require different annotations in the ingress resource to work properly. Supported ingress controllers vary based on the distribution. + +CMX supports ingress controllers that are running as a `NodePort` service. + +### CMX Tunnels for VM-Based Clusters + +All VM-based CMX clusters support tunneling traffic into a `NodePort` service. When this option is used, Replicated is responsible for creating the DNS record and TLS certs. + +Replicated will route traffic from `:443` and/or `:80` into the `NodePort` service you defined. For more information about using tunnels, see [Expose Ports on VM-Based Clusters](#expose-ports-on-vm-based-clusters) below. + +## Expose Ports on VMs + +You can expose ports on a VM and make them accessible on the public internet. + +### Limitation + +Creating wildcard DNS entries for VMs is not supported. For feedback, contact Replicated support. + +### CLI + +```bash +replicated vm port expose VMID_OR_VMNAME --port PORT --protocol PROTOCOL +``` + +For example, to expose port 3000 with HTTP protocol: +```bash +replicated vm port expose VM_ID --port 30000 --protocol http +``` + +### Vendor Portal + +To update the ingress and ports settings for a VM: + +1. In the Vendor Portal, go to [**Compatibility Matrix**](https://vendor.replicated.com/compatibility-matrix). + +1. Create a VM. + +1. Open the dot menu for the VM and click **Edit VM**. + + ![Edit VM in the dot menu](/images/compatibility-matrix-edit-vm.png) + + [View a larger version of this image](/images/compatibility-matrix-edit-vm.png) + +1. Under **Ingress & Ports**, for **Add DNS record**, edit the fields as desired and click **Add** to create a DNS record. + + ![DNS record for a VM](/images/compatibility-matrix-ingress-ports.png) + [View a larger version of this image](/images/compatibility-matrix-ingress-ports.png) + + A DNS record and valid TLS cert are created and connected to the specified port. + +## Expose Ports on VM-Based Clusters + +After you have a node port available on the cluster, you can expose the node port to the public internet using the Replicated CLI. There is no limit to the number of tunnels you can create for a cluster and multiple tunnels can connect to a single service. + +:::note +You can expose a node port that does not yet exist in the cluster. This is useful if you have a deterministic node port, but need the DNS name as a value in your Helm chart. +::: + +The following diagram shows how the traffic is routed into the service using CMX tunnels: + +Compatibility Matrix ingress + +[View a larger version of this image](/images/compatibility-matrix-ingress.png) + +### 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). + +### 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..01ec2f0633 --- /dev/null +++ b/docs/vendor/cmx-overview.md @@ -0,0 +1,41 @@ +# 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 clusters and VMs from a unified interface. 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: +* [CMX Clusters](testing-supported-clusters) - Information about supported cluster distributions +* [Use CMX Clusters](testing-how-to) - How to create and manage clusters +* [CMX VMs](cmx-vms) - How to create and manage VMs + +## Architecture + +CMX uses two different infrastructure approaches to provision resources: + +* **Custom VMs**: VMs and VM-based clusters (such as kind, k3s, RKE2, and Red Hat OpenShift OKD) run on Replicated bare metal servers located in several data centers, including data centers physically in the European Union. This architecture provides you with full control over the operating system and allows testing of installation methods that require direct OS access. + +* **Warm Pool Cloud Clusters**: Cloud-based Kubernetes distributions (such as EKS, GKE, and AKS) are run in a Replicated managed and controlled cloud account to optimize and deliver 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. + +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 [CMX Clusters](testing-supported-clusters). + +For more information about supported VMs, see [CMX VMs](cmx-vms) + +## 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/cmx-vms.md b/docs/vendor/cmx-vms.md new file mode 100644 index 0000000000..9a0172f404 --- /dev/null +++ b/docs/vendor/cmx-vms.md @@ -0,0 +1,469 @@ +import Prerequisites from "../partials/cmx/_prerequisites.mdx" +import InstanceTypes from "../partials/cmx/_instance-types.mdx" + +# CMX VMs + +This topic describes how to use Replicated Compatibility Matrix (CMX) VMs, including information about supported types, creating and managing VMs, SSH access, and transferring files. + +## About CMX VMs + +CMX VMs provide isolated Linux environments for testing your applications. Unlike clusters, VMs give you full control over the operating system (OS) and allow you to test installation methods that require direct OS access. + +You can use CMX VMs for testing and troubleshooting VM-based installations for your application with [Replicated Embedded Cluster](/intro-replicated#embedded-cluster). + +For information about creating clusters with CMX to test Kubernetes-based deployments and Helm installations, see [CMX Clusters](testing-supported-clusters) and [Use CMX Clusters](testing-how-to). + +## Supported VM Types + +The following VM types are supported: + +| Distribution | Versions | Instance Types | +| :---- | :---- | :---- | +| ubuntu | 24.04, 22.04 | r1.small, r1.medium, r1.large, r1.xlarge, r1.2xlarge. See [Replicated Instance Types](#replicated-instance-types).| +| almalinux | 8, 9, 10 | r1.small, r1.medium, r1.large, r1.xlarge, r1.2xlarge. See [Replicated Instance Types](#replicated-instance-types). | + +## Replicated Instance Types + +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. + +## 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. + +## Set Up SSH Access + +To access VMs that you create with Compatibility Matrix, you need to set up SSH access. You can do this using your GitHub account, a personal public/private key, or a service account or bot with shared access. + +### Use Your GitHub Account + +:::note +Your GitHub usernames and SSH keys are synced to a VM when it is first created. If you update your GitHub username or keys after creating a VM, you can manually sync by updating your [Account Settings](https://vendor.replicated.com/account-settings) in the Vendor Portal and clicking **Save**. +::: + +To set up and verify SSH access for CMX VMs using your personal GitHub account: + +1. Log in to your GitHub account and add an SSH key if you do not have one already. For information about how to generate and add a new SSH key, see [Generate a new SSH key](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent#generati[…]w-ssh-key) and [Adding a new SSH key to your GitHub account](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account) in the GitHub documentation. + +1. Run the following command to verify that your public/private SSH key is properly set up with GitHub. + + ```bash + ssh -T git@github.com + ``` + + If successful, you will see: + + ``` + Hi ! You've successfully authenticated, but GitHub does not provide shell access. + ``` + +1. Log in to the Vendor Portal and go to [**Account Settings**](https://vendor.replicated.com/account-settings/info). + +1. On the **Account Settings > Account Information** page, for **GitHub username**, add your GitHub username. + +1. Verify that SSH access was set up successfully: + + 1. On the command line, authenticate with the Replicated CLI using your Vendor Portal account: + + ```bash + replicated login + ``` + :::note + To log out of an existing session, first run `replicated logout`. + ::: + + 1. Run the following command to verify that your SSH setup is working: + + ```bash + ssh -T replicated@replicatedvm.com + ``` + If successful, you will see a message similar to the following: + + ``` + Hi ! 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 Personal Public/Private Key + +To set up and verify SSH access for Compatibility Matrix VMs using a personal public/private key pair: + +1. If you do not already have a public and private key, generate a new public/private key pair. + +1. Log in to the Vendor Portal and go to [**Compatibility Matrix Settings**](https://vendor.replicated.com/compatibility-matrix/settings). + +1. On the **Compatibility Matrix Settings > SSH Public Keys** page, upload your public key. + +1. Verify that SSH access was set up successfully: + + 1. On the command line, authenticate with the Replicated CLI using your Vendor Portal account: + + ```bash + replicated login + ``` + :::note + To log out of an existing session, first run `replicated logout`. + ::: + + 1. Run the following command to verify that your SSH setup is working: + + ```bash + ssh -T replicated@replicatedvm.com + ``` + If successful, you will see a message similar to the following: + + ``` + Hi ! 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**. + + ![create vm page in the vendor portal](/images/compatibility-matrix-create-vm.png) + + [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: + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
OS distributionSelect the OS distribution for the VM.
VersionSelect the OS version. The options available are specific to the distribution selected.
Name (optional)Enter an optional name for the VM.
TagsAdd one or more tags to the VM as key-value pairs.
Set TTLSelect 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 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.
CountSelect 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 + +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. + +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 index 930aded4d0..316ec4e2cb 100644 --- a/docs/vendor/testing-cluster-addons.md +++ b/docs/vendor/testing-cluster-addons.md @@ -4,8 +4,7 @@ This topic describes the supported cluster add-ons for Replicated Compatibility ## 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. +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. ## CLI diff --git a/docs/vendor/testing-how-to.md b/docs/vendor/testing-how-to.md index 8f581b994a..80839938c8 100644 --- a/docs/vendor/testing-how-to.md +++ b/docs/vendor/testing-how-to.md @@ -12,7 +12,9 @@ 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). +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 information about using the `cluster prepare` command to streamline development workflows, see [Develop with CMX](cmx-develop). ## Limitations @@ -174,7 +176,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 +185,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`: @@ -194,151 +196,18 @@ To set the network policy of a VM-based cluster to `airgap`: ## 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). +For information about using the `cluster prepare` command to streamline development workflows, see [Develop with CMX](cmx-develop). ## Access Clusters -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. - -To access a cluster from the command line: - -1. Verify that the cluster is in a Running state: - - ```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). - -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 - ``` +## Access Clusters -1. Press Ctrl-D or type `exit` when done to end the shell and the connection to the server. +For information about accessing clusters to interact with kubectl, see [Access Clusters](/vendor/cmx-develop#access-clusters) in _Develop with CMX_. ## Upgrade Clusters (kURL Only) -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 following example upgrades a kURL cluster from its previous version to version `9d5a44c`: - -```bash -replicated cluster upgrade cabb74d5 --version 9d5a44c -``` - -For command usage, see [cluster upgrade](/reference/replicated-cli-cluster-upgrade). +For information about upgrading kURL clusters, see [Upgrade Clusters (kURL Only)](/vendor/cmx-develop#upgrade-clusters-kurl-only) in _Develop with CMX_. ## 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: - - ``` - 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). - -### Vendor Portal - -To delete a cluster using the Vendor Portal: - -1. Go to **Compatibility Matrix**. - -1. Under **Clusters**, in the vertical dots menu for the target cluster, click **Delete cluster**. - - Delete cluster button - - [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-supported-clusters.md b/docs/vendor/testing-supported-clusters.md index 5d168ccb45..06dc718ff0 100644 --- a/docs/vendor/testing-supported-clusters.md +++ b/docs/vendor/testing-supported-clusters.md @@ -1,19 +1,27 @@ import Pool from "../partials/cmx/_openshift-pool.mdx" import InstanceTypes from "../partials/cmx/_instance-types.mdx" -# CMX Cluster Types +# CMX Clusters 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 [Use 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/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..ae48ff3c73 100644 --- a/sidebars.js +++ b/sidebars.js @@ -198,19 +198,19 @@ const sidebars = { type: 'category', label: 'Compatibility Matrix', items: [ - 'vendor/testing-about', + 'vendor/cmx-overview', + 'vendor/cmx-vms', 'vendor/testing-supported-clusters', 'vendor/testing-how-to', - 'vendor/testing-ingress', 'vendor/testing-cluster-addons', - 'vendor/testing-vm-about', - 'vendor/testing-vm-create', - 'vendor/testing-vm-networking', + '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 From c0bbec72759da2f14df556245df21f8c2276ca0e Mon Sep 17 00:00:00 2001 From: Han Yu Date: Tue, 9 Dec 2025 13:13:47 -0500 Subject: [PATCH 2/5] Add overview table --- docs/vendor/cmx-overview.md | 36 ++++++++++++++++++++++++++---------- 1 file changed, 26 insertions(+), 10 deletions(-) diff --git a/docs/vendor/cmx-overview.md b/docs/vendor/cmx-overview.md index 01ec2f0633..fced4ff172 100644 --- a/docs/vendor/cmx-overview.md +++ b/docs/vendor/cmx-overview.md @@ -4,31 +4,47 @@ This topic describes Replicated Compatibility Matrix (CMX), including use cases, ## Overview -You can use CMX to quickly provision ephemeral clusters and VMs from a unified interface. 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. +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: -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 +* 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 -You can use CMX with the Replicated CLI or the Replicated Vendor Portal. For more information about how to use CMX, see: -* [CMX Clusters](testing-supported-clusters) - Information about supported cluster distributions -* [Use CMX Clusters](testing-how-to) - How to create and manage clusters -* [CMX VMs](cmx-vms) - How to create and manage VMs ## Architecture CMX uses two different infrastructure approaches to provision resources: -* **Custom VMs**: VMs and VM-based clusters (such as kind, k3s, RKE2, and Red Hat OpenShift OKD) run on Replicated bare metal servers located in several data centers, including data centers physically in the European Union. This architecture provides you with full control over the operating system and allows testing of installation methods that require direct OS access. +* **Custom VMs**: VMs and VM-based clusters (such as kind, k3s, RKE2, and Red Hat OpenShift OKD) run on Replicated bare metal servers located in several data centers, including data centers physically in the European Union. VMs give you full control over the operating system. * **Warm Pool Cloud Clusters**: Cloud-based Kubernetes distributions (such as EKS, GKE, and AKS) are run in a Replicated managed and controlled cloud account to optimize and deliver 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. +### Use Cases by Customer Installation Type + +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** |
    • [Embedded Cluster](/vendor/embedded-overview)
    • [kURL (Legacy)](/vendor/kurl-about)
    |
    • [Helm](/vendor/helm-install-overview)
    • [KOTS](/intro-kots)
    | +| **CMX Environment** | **[CMX Bare VM](cmx-vms)** | **[CMX Clusters](testing-supported-clusters)** | +| **How to Test** |
    • Create CMX VM
    • SSM into the VM
    • Install Embedded Cluster (to install Kubernetes and your application in one step)
    |
    • Create CMX cluster
    • Shell into the Cluster
    • Run `helm install` or `kots install` commands to simulate customer installation in their Kubernetes clusters
    | +| **CMX Notes** | Can test on [Ubuntu or AlmaLinux](cmx-vms#supported-vm-types)
    ([Embedded Cluster](testing-supported-clusters#embedded-cluster) and [kURL](testing-supported-clusters#kurl) let you skip the cluster install step to test your application install more quickly) | Can test on [EKS, GKE, AKS, OpenShift, and more](testing-supported-clusters) | + + +**Key Differences:** + +* **Warm Pool Cloud Clusters** (EKS, GKE, AKS, OKE) - Standard managed Kubernetes environments that are already running and ready for application installation. Use these to test installations where customers bring their own cloud-managed Kubernetes clusters. These clusters provision faster because control planes are pre-warmed. + +* **VM-Based Clusters** (kind, k3s, RKE2, OpenShift OKD, Embedded Cluster, kURL) - Kubernetes distributions that run on Replicated bare metal servers with Kubernetes already installed. Use these for quick testing of automated installer workflows. For Embedded Cluster and kURL, CMX runs the installer behind the scenes and provides access to a ready cluster with your application already installed. + +* **Custom VMs** (Ubuntu, AlmaLinux) - Bare Linux VMs without Kubernetes pre-installed. Use these when you need full control over the operating system to manually test the complete installation process. For Embedded Cluster and kURL installers, you run a single command that provisions Kubernetes and installs your application together. This is useful for detailed testing, troubleshooting installation issues, or validating the end-to-end customer experience. + 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 [CMX Clusters](testing-supported-clusters). -For more information about supported VMs, see [CMX VMs](cmx-vms) +For more information about supported VMs, see [CMX Bare VM](cmx-vms) ## Billing and Credits From 458237a301d83a05c29925cf495789bd19099505 Mon Sep 17 00:00:00 2001 From: Han Yu Date: Tue, 9 Dec 2025 13:22:46 -0500 Subject: [PATCH 3/5] clean up overview --- docs/vendor/cmx-overview.md | 27 +++++++++++---------------- 1 file changed, 11 insertions(+), 16 deletions(-) diff --git a/docs/vendor/cmx-overview.md b/docs/vendor/cmx-overview.md index fced4ff172..aadcc32caa 100644 --- a/docs/vendor/cmx-overview.md +++ b/docs/vendor/cmx-overview.md @@ -11,14 +11,6 @@ You can use CMX to quickly provision ephemeral VMs or clusters so you can develo * Reproduce a reported issue on a customer-representative environment for troubleshooting -## Architecture - -CMX uses two different infrastructure approaches to provision resources: - -* **Custom VMs**: VMs and VM-based clusters (such as kind, k3s, RKE2, and Red Hat OpenShift OKD) run on Replicated bare metal servers located in several data centers, including data centers physically in the European Union. VMs give you full control over the operating system. - -* **Warm Pool Cloud Clusters**: Cloud-based Kubernetes distributions (such as EKS, GKE, and AKS) are run in a Replicated managed and controlled cloud account to optimize and deliver 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. - ### Use Cases by Customer Installation Type The following table shows which CMX infrastructure option to use based on how your customers install your application: @@ -29,22 +21,25 @@ The following table shows which CMX infrastructure option to use based on how yo | **Installer** |
    • [Embedded Cluster](/vendor/embedded-overview)
    • [kURL (Legacy)](/vendor/kurl-about)
    |
    • [Helm](/vendor/helm-install-overview)
    • [KOTS](/intro-kots)
    | | **CMX Environment** | **[CMX Bare VM](cmx-vms)** | **[CMX Clusters](testing-supported-clusters)** | | **How to Test** |
    • Create CMX VM
    • SSM into the VM
    • Install Embedded Cluster (to install Kubernetes and your application in one step)
    |
    • Create CMX cluster
    • Shell into the Cluster
    • Run `helm install` or `kots install` commands to simulate customer installation in their Kubernetes clusters
    | -| **CMX Notes** | Can test on [Ubuntu or AlmaLinux](cmx-vms#supported-vm-types)
    ([Embedded Cluster](testing-supported-clusters#embedded-cluster) and [kURL](testing-supported-clusters#kurl) let you skip the cluster install step to test your application install more quickly) | Can test on [EKS, GKE, AKS, OpenShift, and more](testing-supported-clusters) | +| **CMX Notes** | Can test on [Ubuntu or AlmaLinux](cmx-vms#supported-vm-types)
    ([Embedded Cluster](testing-supported-clusters#embedded-cluster) and [kURL](testing-supported-clusters#kurl) help automate your application install)
    Run [`replicated vm versions`](/reference/replicated-cli-vm-versions) for current VM options | Can test on [EKS, GKE, AKS, OpenShift, and more](testing-supported-clusters)
    Run [`replicated cluster versions`](/reference/replicated-cli-cluster-versions) for current cluster options | + + +## Architecture + +CMX uses two different infrastructure approaches to provision resources: -**Key Differences:** -* **Warm Pool Cloud Clusters** (EKS, GKE, AKS, OKE) - Standard managed Kubernetes environments that are already running and ready for application installation. Use these to test installations where customers bring their own cloud-managed Kubernetes clusters. These clusters provision faster because control planes are pre-warmed. +* **Warm Pool Cloud Clusters** (EKS, GKE, AKS, OKE): Cloud-based Kubernetes distributions run in Replicated-managed cloud accounts. Control planes are pre-warmed and a node group is added when you request a cluster, delivering clusters faster than provisioning your own. Use these to test installations where customers bring their own cloud-managed Kubernetes clusters. -* **VM-Based Clusters** (kind, k3s, RKE2, OpenShift OKD, Embedded Cluster, kURL) - Kubernetes distributions that run on Replicated bare metal servers with Kubernetes already installed. Use these for quick testing of automated installer workflows. For Embedded Cluster and kURL, CMX runs the installer behind the scenes and provides access to a ready cluster with your application already installed. +* **VMs**: VMs run on Replicated bare metal servers located in several data centers, including data centers physically in the European Union. -* **Custom VMs** (Ubuntu, AlmaLinux) - Bare Linux VMs without Kubernetes pre-installed. Use these when you need full control over the operating system to manually test the complete installation process. For Embedded Cluster and kURL installers, you run a single command that provisions Kubernetes and installs your application together. This is useful for detailed testing, troubleshooting installation issues, or validating the end-to-end customer experience. + * **Bare VMs** (Ubuntu, AlmaLinux): Linux VMs without Kubernetes pre-installed. Use these when you need full control over the operating system to test the complete installation process, including cluster install. + + * **VM-based clusters**: VMs with Kubernetes already installed. Use these for a quick development environment (kind, k3s), to simualte end customer enivronments (RKE2, OpenShift OKD), or our automations for Embedded Cluster and kURL to run the installer behind the scenes and provide a ready cluster with your application already installed. -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 [CMX Clusters](testing-supported-clusters). -For more information about supported VMs, see [CMX Bare VM](cmx-vms) ## Billing and Credits From fd4622bb013fddc28878085af1f1f7596cbe47b6 Mon Sep 17 00:00:00 2001 From: Han Yu Date: Tue, 9 Dec 2025 13:35:59 -0500 Subject: [PATCH 4/5] consolidate cluster info + prereqs go into overview --- docs/intro.mdx | 2 +- docs/vendor/cmx-develop.md | 8 +- docs/vendor/cmx-networking.md | 7 +- docs/vendor/cmx-overview.md | 58 +++++++++++- docs/vendor/cmx-vms.md | 23 +---- docs/vendor/testing-cluster-addons.md | 77 ---------------- docs/vendor/testing-how-to.md | 105 ++++++++++++++++------ docs/vendor/testing-pricing.mdx | 2 +- docs/vendor/testing-supported-clusters.md | 4 +- docs/vendor/testing-vm-about.md | 14 +-- sidebars.js | 3 +- 11 files changed, 148 insertions(+), 155 deletions(-) delete mode 100644 docs/vendor/testing-cluster-addons.md diff --git a/docs/intro.mdx b/docs/intro.mdx index a7df1a2144..9264354ca3 100644 --- a/docs/intro.mdx +++ b/docs/intro.mdx @@ -272,7 +272,7 @@ import clsx from 'clsx';
    - Use CMX Clusters + CMX Clusters

    Create and manage Kubernetes clusters for testing

    diff --git a/docs/vendor/cmx-develop.md b/docs/vendor/cmx-develop.md index ed4d646244..fb3d6708b9 100644 --- a/docs/vendor/cmx-develop.md +++ b/docs/vendor/cmx-develop.md @@ -1,5 +1,3 @@ -import Prerequisites from "../partials/cmx/_prerequisites.mdx" - # Develop with CMX This topic describes how to use Replicated Compatibility Matrix (CMX) to streamline application development and testing workflows. @@ -10,11 +8,7 @@ CMX provides features that make it easy to quickly provision test environments a ## Prerequisites -Before you can use CMX clusters, 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_. ## Prepare Clusters diff --git a/docs/vendor/cmx-networking.md b/docs/vendor/cmx-networking.md index adb73407ba..6f0cb9fdc2 100644 --- a/docs/vendor/cmx-networking.md +++ b/docs/vendor/cmx-networking.md @@ -57,9 +57,7 @@ Replicated will route traffic from `:443` and/or `:80` into the `NodePort` servi You can expose ports on a VM and make them accessible on the public internet. -### Limitation - -Creating wildcard DNS entries for VMs is not supported. For feedback, contact Replicated support. +For limitations related to port exposure, see [Limitations](/vendor/cmx-overview#limitations) in _CMX Overview_. ### CLI @@ -109,8 +107,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/cmx-overview.md b/docs/vendor/cmx-overview.md index aadcc32caa..7b36fb274d 100644 --- a/docs/vendor/cmx-overview.md +++ b/docs/vendor/cmx-overview.md @@ -19,7 +19,7 @@ The following table shows which CMX infrastructure option to use based on how yo |-----------------|---------------------|----------------| | **Customer Environment** | Linux VM, with no existing Kubernetes cluster | Customer-managed Kubernetes cluster | | **Installer** | | | -| **CMX Environment** | **[CMX Bare VM](cmx-vms)** | **[CMX Clusters](testing-supported-clusters)** | +| **CMX Environment** | **[CMX Bare VM](cmx-vms)** | **[CMX Cluster](testing-supported-clusters)** | | **How to Test** | | | | **CMX Notes** | Can test on [Ubuntu or AlmaLinux](cmx-vms#supported-vm-types)
    ([Embedded Cluster](testing-supported-clusters#embedded-cluster) and [kURL](testing-supported-clusters#kurl) help automate your application install)
    Run [`replicated vm versions`](/reference/replicated-cli-vm-versions) for current VM options | Can test on [EKS, GKE, AKS, OpenShift, and more](testing-supported-clusters)
    Run [`replicated cluster versions`](/reference/replicated-cli-cluster-versions) for current cluster options | @@ -41,6 +41,62 @@ CMX uses two different infrastructure approaches to provision resources: +## Prerequisites + +Before you can use CMX, you must complete the following prerequisites: + +* Create an account in the Replicated Vendor Portal. See [Create a Vendor Account](/vendor/vendor-portal-creating-account). + +* Install the Replicated CLI and then authorize the CLI using your vendor account. See [Install the Replicated CLI](/reference/replicated-cli-installing). + +* If you have a contract, you can purchase more credits by going to [**Compatibility Matrix > Buy additional credits**](https://vendor.replicated.com/compatibility-matrix). Otherwise, you can request credits by going to [**Compatibility Matrix > Request more credits**](https://vendor.replicated.com/compatibility-matrix) in the Vendor Portal. For more information, see [Billing and Credits](#billing-and-credits) below. + +* 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. + +## Limitations + +CMX has the following limitations: + +### General Limitations + +* Creating VMs with CMX is a Beta feature. +* 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. +* 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). +* 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). + +### Distribution-Specific Limitations + +* On cloud clusters, node groups are not available for every distribution. For distribution-specific details, see [CMX Cluster Types](testing-supported-clusters). +* Multi-node support is not available for every distribution. For distribution-specific details, see [CMX Cluster Types](testing-supported-clusters). +* ARM instance types are only supported on Cloud Clusters. For distribution-specific details, see [CMX Cluster Types](testing-supported-clusters). +* GPU instance types are only supported on Cloud Clusters. For distribution-specific details, see [CMX Cluster Types](testing-supported-clusters). + +### Feature Limitations + +* 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 or Embedded Cluster distributions. + +### Networking Limitations + +* Creating wildcard DNS entries for VMs is not supported. +* Tunnels for exposing ports are not supported for cloud distributions (EKS, GKE, AKS). +* 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. + +### File Transfer Limitations + +* When transferring files using the CMX Forwarder, `scp` with flag `-O` (legacy scp protocol) is not supported. +* When transferring files using the CMX Forwarder, relative paths are not supported. +* When transferring files using the CMX Forwarder, file permissions are not inherited. + +For additional distribution-specific limitations, see [CMX Cluster Types](testing-supported-clusters). + ## 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. diff --git a/docs/vendor/cmx-vms.md b/docs/vendor/cmx-vms.md index 9a0172f404..998f9193f4 100644 --- a/docs/vendor/cmx-vms.md +++ b/docs/vendor/cmx-vms.md @@ -1,4 +1,3 @@ -import Prerequisites from "../partials/cmx/_prerequisites.mdx" import InstanceTypes from "../partials/cmx/_instance-types.mdx" # CMX VMs @@ -11,7 +10,7 @@ CMX VMs provide isolated Linux environments for testing your applications. Unlik You can use CMX VMs for testing and troubleshooting VM-based installations for your application with [Replicated Embedded Cluster](/intro-replicated#embedded-cluster). -For information about creating clusters with CMX to test Kubernetes-based deployments and Helm installations, see [CMX Clusters](testing-supported-clusters) and [Use CMX Clusters](testing-how-to). +For information about creating clusters with CMX to test Kubernetes-based deployments and Helm installations, see [CMX Cluster Types](testing-supported-clusters) and [CMX Clusters](testing-how-to). ## Supported VM Types @@ -30,20 +29,11 @@ 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_. ## Set Up SSH Access @@ -404,12 +394,7 @@ 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/testing-cluster-addons.md b/docs/vendor/testing-cluster-addons.md deleted file mode 100644 index 316ec4e2cb..0000000000 --- a/docs/vendor/testing-cluster-addons.md +++ /dev/null @@ -1,77 +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 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. - -## 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`). - - - - - - - - - - - - - - - - - - - - - - -
    TypeDescription
    Supported Kubernetes DistributionsEKS (AWS S3)
    CostFlat 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 80839938c8..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. @@ -16,33 +14,13 @@ For information about creating VMs with CMX to test Replicated Embedded Cluster For information about using the `cluster prepare` command to streamline development workflows, see [Develop with CMX](cmx-develop). -## 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 additional distribution-specific limitations, see [Supported CMX Cluster Types](testing-supported-clusters). - ## 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 @@ -194,14 +172,85 @@ 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. +## Cluster Add-ons (Alpha) + +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. + +### 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`). + + + + + + + + + + + + + + + + + + + + + + +
    TypeDescription
    Supported Kubernetes DistributionsEKS (AWS S3)
    CostFlat 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.
      • +
    +
    + ## Prepare Clusters For information about using the `cluster prepare` command to streamline development workflows, see [Develop with CMX](cmx-develop). ## Access Clusters -## Access Clusters - For information about accessing clusters to interact with kubectl, see [Access Clusters](/vendor/cmx-develop#access-clusters) in _Develop with CMX_. ## Upgrade Clusters (kURL Only) 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 1ff4c03668..2c80420eb6 100644 --- a/docs/vendor/testing-supported-clusters.md +++ b/docs/vendor/testing-supported-clusters.md @@ -1,7 +1,7 @@ import Pool from "../partials/cmx/_openshift-pool.mdx" import InstanceTypes from "../partials/cmx/_instance-types.mdx" -# CMX Clusters +# CMX Cluster Types 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). @@ -15,7 +15,7 @@ CMX can provision both custom VM-based clusters and warm pool cloud clusters to 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 [Use CMX Clusters](testing-how-to). +For information about creating and managing clusters, see [CMX Clusters](testing-how-to). ## VM-Based Clusters 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/sidebars.js b/sidebars.js index ae48ff3c73..def141895e 100644 --- a/sidebars.js +++ b/sidebars.js @@ -200,9 +200,8 @@ const sidebars = { items: [ 'vendor/cmx-overview', 'vendor/cmx-vms', - 'vendor/testing-supported-clusters', 'vendor/testing-how-to', - 'vendor/testing-cluster-addons', + 'vendor/testing-supported-clusters', 'vendor/cmx-networking', 'vendor/testing-network-policy', 'vendor/cmx-develop', From fba3180e4b336cbdfa71911ce07bb8eea1c5c07a Mon Sep 17 00:00:00 2001 From: Han Yu Date: Thu, 11 Dec 2025 22:31:33 -0500 Subject: [PATCH 5/5] concise limitations --- docs/vendor/cmx-overview.md | 65 ++++++++---------------- docs/vendor/testing-vm-networking.md | 3 +- docs/vendor/testing-vm-transfer-files.md | 8 +-- 3 files changed, 24 insertions(+), 52 deletions(-) diff --git a/docs/vendor/cmx-overview.md b/docs/vendor/cmx-overview.md index 7b36fb274d..64cc74d6b3 100644 --- a/docs/vendor/cmx-overview.md +++ b/docs/vendor/cmx-overview.md @@ -11,7 +11,7 @@ You can use CMX to quickly provision ephemeral VMs or clusters so you can develo * Reproduce a reported issue on a customer-representative environment for troubleshooting -### Use Cases by Customer Installation Type +## Use Cases The following table shows which CMX infrastructure option to use based on how your customers install your application: @@ -19,7 +19,7 @@ The following table shows which CMX infrastructure option to use based on how yo |-----------------|---------------------|----------------| | **Customer Environment** | Linux VM, with no existing Kubernetes cluster | Customer-managed Kubernetes cluster | | **Installer** |
    • [Embedded Cluster](/vendor/embedded-overview)
    • [kURL (Legacy)](/vendor/kurl-about)
    |
    • [Helm](/vendor/helm-install-overview)
    • [KOTS](/intro-kots)
    | -| **CMX Environment** | **[CMX Bare VM](cmx-vms)** | **[CMX Cluster](testing-supported-clusters)** | +| **CMX Environment** | **[CMX Bare VM](cmx-vms)** | **[CMX Cluster Types](testing-supported-clusters)** | | **How to Test** |
    • Create CMX VM
    • SSM into the VM
    • Install Embedded Cluster (to install Kubernetes and your application in one step)
    |
    • Create CMX cluster
    • Shell into the Cluster
    • Run `helm install` or `kots install` commands to simulate customer installation in their Kubernetes clusters
    | | **CMX Notes** | Can test on [Ubuntu or AlmaLinux](cmx-vms#supported-vm-types)
    ([Embedded Cluster](testing-supported-clusters#embedded-cluster) and [kURL](testing-supported-clusters#kurl) help automate your application install)
    Run [`replicated vm versions`](/reference/replicated-cli-vm-versions) for current VM options | Can test on [EKS, GKE, AKS, OpenShift, and more](testing-supported-clusters)
    Run [`replicated cluster versions`](/reference/replicated-cli-cluster-versions) for current cluster options | @@ -28,8 +28,6 @@ The following table shows which CMX infrastructure option to use based on how yo CMX uses two different infrastructure approaches to provision resources: - - * **Warm Pool Cloud Clusters** (EKS, GKE, AKS, OKE): Cloud-based Kubernetes distributions run in Replicated-managed cloud accounts. Control planes are pre-warmed and a node group is added when you request a cluster, delivering clusters faster than provisioning your own. Use these to test installations where customers bring their own cloud-managed Kubernetes clusters. * **VMs**: VMs run on Replicated bare metal servers located in several data centers, including data centers physically in the European Union. @@ -53,56 +51,35 @@ Before you can use CMX, 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. -## Limitations - -CMX has the following limitations: - -### General Limitations -* Creating VMs with CMX is a Beta feature. -* 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. -* 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). -* 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). - -### Distribution-Specific Limitations +## Billing and Credits -* On cloud clusters, node groups are not available for every distribution. For distribution-specific details, see [CMX Cluster Types](testing-supported-clusters). -* Multi-node support is not available for every distribution. For distribution-specific details, see [CMX Cluster Types](testing-supported-clusters). -* ARM instance types are only supported on Cloud Clusters. For distribution-specific details, see [CMX Cluster Types](testing-supported-clusters). -* GPU instance types are only supported on Cloud Clusters. For distribution-specific details, see [CMX Cluster Types](testing-supported-clusters). +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. -### Feature Limitations +For more information about pricing, see [CMX Pricing](testing-pricing). -* 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 or Embedded Cluster distributions. +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). -### Networking Limitations -* Creating wildcard DNS entries for VMs is not supported. -* Tunnels for exposing ports are not supported for cloud distributions (EKS, GKE, AKS). -* 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. +## Limitations -### File Transfer Limitations +* Each team has a quota limit on resources. Contact your account representative to increase limits. +* Team actions with CMX are not logged in the [Vendor Team Audit Log](https://vendor.replicated.com/team/audit-log). -* When transferring files using the CMX Forwarder, `scp` with flag `-O` (legacy scp protocol) is not supported. -* When transferring files using the CMX Forwarder, relative paths are not supported. -* When transferring files using the CMX Forwarder, file permissions are not inherited. -For additional distribution-specific limitations, see [CMX Cluster Types](testing-supported-clusters). +CMX VMs have the following limitations: -## Billing and Credits +* Creating VMs with CMX is a Beta feature. +* Installing Embedded Cluster on a VM is supported for Embedded Cluster versions 1.21.0 or later. +* [GitHub Actions](/vendor/testing-ci-cd#replicated-github-actions) and the [cluster prepare](/reference/replicated-cli-cluster-prepare) command are not supported for CMX VMs or Embedded Cluster distributions. -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. +CMX Clusters have the following limitations: -For more information about pricing, see [CMX Pricing](testing-pricing). +* Clusters cannot be resized or rebooted. Create a new cluster if you need to make changes. +* Cloud clusters (EKS, GKE, AKS) do not yet allow configuration of CNI, CSI, CRI, Ingress, or other plugins. +* Cloud clusters (EKS, GKE, AKS) do not yet support tunnels for exposing ports. +* The `cluster upgrade` feature is available only for kURL distributions. See [cluster upgrade](/reference/replicated-cli-cluster-upgrade). +* Multi-node, ARM, and GPU support varies by distribution. See [CMX Cluster Types](testing-supported-clusters). -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-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: