From fe6b97543364dafb2b9d9a4999343b26b088fd65 Mon Sep 17 00:00:00 2001 From: Han Yu Date: Mon, 28 Jul 2025 10:34:55 -0400 Subject: [PATCH 01/24] Add direct port of VM beta --- docs/vendor/testing-vm-create.md | 333 +++++++++++++++++++++++++++++++ sidebars.js | 1 + 2 files changed, 334 insertions(+) create mode 100644 docs/vendor/testing-vm-create.md diff --git a/docs/vendor/testing-vm-create.md b/docs/vendor/testing-vm-create.md new file mode 100644 index 0000000000..5fe8f4e60c --- /dev/null +++ b/docs/vendor/testing-vm-create.md @@ -0,0 +1,333 @@ +# Create VMs (Alpha) + +The Compatibility Matrix (CMX) platform allows you to create VMs with no Kubernetes pre-installed on them. This is particularly useful for testing VM-based installs such as the [Replicated Embedded Cluster](https://docs.replicated.com/intro-replicated#embedded-cluster). + +| ⚠️ Current Limitations [GitHub Actions](https://docs.replicated.com/vendor/testing-how-to#replicated-github-actions) do not yet work with Compatibility Matrix VMs. [Cluster prepare](https://docs.replicated.com/reference/replicated-cli-cluster-prepare) is not yet supported with Compatibility Matrix VMs. → To try out VMs (Alpha), [email](mailto:han@replicated.com) Replicated for access & support. | +| :---- | + +## Create VMs + +To create [3] [Ubuntu] VMs: + +```bash +replicated vm create --distribution ubuntu --count 3 +``` + +List supported distributions and versions: + +```bash +replicated vm versions +``` + +Supported VM types: + +| Distribution | Versions | Instance Types | +| :---- | :---- | :---- | +| ubuntu | 24.04, 22.04 | r1.small, r1.medium, r1.large, r1.xlarge, r1.2xlarge | +| almalinux | 8 | r1.small, r1.medium, r1.large, r1.xlarge, r1.2xlarge | + +## Prerequisites + +Before you can use Compatibility Matrix VMs, you must complete the following prerequisites: + +### Connect GitHub Account + +Before you can SSH into a VM: + +1. Configure your GitHub username in Replicated Vendor Portal ([Replicated Docs](https://docs.replicated.com/vendor/team-management-github-username#procedure)) +2. Make sure you've added your SSH key in your GitHub account ([GitHub instructions](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account)) + +| GitHub usernames and SSH keys are synced every 24hrs. To immediately sync: → [Account Settings](https://vendor.replicated.com/account-settings/info) > click Save Keys are synced to the VM at time of creation, so any updates after creation are ignored. | +| :---- | + +To confirm your GitHub username and SSH key have been set up successfully: + +```bash +ssh -T replicated@replicatedvm.com +``` + +If successful, you'll see: + +``` +You've successfully authenticated, use [VM_ID]@replicatedvm.com to access your VM. +``` + +If you do not see this message, your public/private key likely was not available. + +### Use a Service GitHub Account + +To automate VMs in your CI, or otherwise avoid using a personal GitHub account, use the flag `--ssh-public-key` when you first create a VM: + +```bash +replicated vm create --distribution ubuntu --version 20.04 --ssh-public-key ~/.ssh/id_rsa.pub +``` + +Using multiple SSH public keys: + +```bash +replicated vm create --distribution ubuntu --version 20.04 --ssh-public-key ~/.ssh/id_rsa.pub --ssh-public-key ~/.ssh/id_ed25519.pub +``` + +## Connect to a VM + +There are currently two supported methods to SSH into a VM: + +1. [**CMX Forwarder**](#cmx-forwarder) + * Easier – You only need to know the VM ID to connect to the machine via SSH. This is more approachable for users less familiar with SSH clients. + * Example Use Case – Run an online Embedded Cluster install command + +2. [**Direct SSH**](#direct-ssh) + * More Flexible – Leverage 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 Case – SCP large assets to the VM, such as air gap bundles. + Pass specific SHH flags during testing workflows + +### CMX Forwarder + +| Transferring files using CMX Forwarder is slower than Direct SSH. CMX servers run on EKS, so depending on your location going through the forwarder will add latency. If you're transferring large files onto the VM, use [Direct SSH](#direct-ssh) in combination with SCP. | +| :---- | + +SSH into the VM: + +```bash +ssh [VMID]@replicatedvm.com +``` + +If needed, copy files onto the machine: + +```bash +scp somefile [VMID]@replicatedvm:/home/folder/somefile +``` + +| Alpha Limitations: scp with flag -O (legacy scp protocol) is not supported. Relative paths is not supported `❌ scp somefile [VMID]@replicatedvm.com:~ ✅ scp somefile [VMID]@replicatedvm:/home/folder/somefile` File permissions are not inherited. | +| :---- | + +### Direct SSH + +| Transferring files using Direct SSH allows you to use your SSH tool of choice, and pass any client-supported flags. Note: Requires Replicated CLI v0.104.0 or later. | +| :---- | + +Get the SSH endpoint for the VM: + +```bash +replicated vm ssh-endpoint [VMID or VMNAME] +``` + +If successful, you'll see: + +``` +ssh://[github-user-name]@[ssh-endpoint]:[port] +``` + +**Example** – `ssh://MyName@37.27.52.116:46795` + +⚠️ The username for SSH should match the GitHub username in Vendor Portal. ([override info](#override-username)) + +SSH into the VM: + +```bash +ssh $(replicated vm ssh-endpoint [VMID or VMNAME]) +``` + +**Example** – `ssh $(replicated vm ssh-endpoint aba1acc2)` + +### Copy Files to the VM (SCP) + +Request the scp endpoint: + +```bash +replicated vm scp-endpoint [VMID or VMNAME] +``` + +**Example** – `replicated vm scp-endpoint aba1acc2` + +If successful, you'll see: + +``` +scp://[github-user-name]@[ssh-endpoint]:[port] +``` + +**Example** – `scp://MyName@37.27.52.116:46795` + +⚠️ The username for SSH should match the GitHub username in Vendor Portal. ([override info](#override-username)) + +SCP files into the VM: + +```bash +scp somefile $(replicated vm scp-endpoint [VMID or VMNAME])//[PATH] +``` + +**Example** – `scp somefile $(replicated vm scp-endpoint aba1acc2)//home/MyName/somefile` + +#### Override Username + +**Note:** You can override the username used for the endpoint with the `--username` flag. +Useful if you want to: + +* Use a different GitHub username than what is in Vendor Portal. (Or no username set.) +* 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. ([more info](#use-a-service-github-account)) + +```bash +replicated vm ssh-endpoint [VMID or VMNAME] --username [github-user-name] +``` + +**Example** – `replicated vm ssh-endpoint aba1acc2 --username MyName` + +## Connect to a VM Manually + +You may need an alternate method if the above options don't work with your preferred SSH client. + +When a VM is created, a random port is assigned to each machine within each group of the VM. +To connect with the machine over SSH: + +```bash +replicated vm ls --output json +``` + +If successful, you'll see: + +```json +[ + { + "id": "e32aafa1", + "name": "sad_black", + "distribution": "ubuntu", + "version": "24.04", + "status": "running", + "created_at": "2024-10-24T15:00:37Z", + "expires_at": "2024-10-24T16:01:10Z", + "ttl": "1h", + "credits_per_hour_per_vm": 0, + "flat_fee": 50000, + "total_credits": 0, + "estimated_cost": 0, + "direct_ssh_port": 33655, + "direct_ssh_endpoint": "95.217.47.21", + "tags": [] + } +] +``` + +To connect with them, you can run: + +```bash +ssh -p [direct_ssh_port] [github_username]@[direct_ssh_endpoint] +``` + +**Example** – `ssh -p 33655 myName@95.217.47.21` + +## Compatibility Matrix Tunnels + +| ⚠️Creating wildcard DNS entries for VMs is not currently supported. ([email](mailto:han@replicated.com) feedback) | +| :---- | + +You can expose ports on a VM and make them accessible on the public internet. +(Learn about a similar feature: [Compatibility Matrix Tunnels for Clusters](https://docs.replicated.com/vendor/testing-ingress#compatibility-matrix-tunnels-beta)) + +### Create a Tunnel + +```bash +replicated vm port expose [VMID or VMNAME] +``` + +**Example** – Expose port 3000 with HTTP protocol +`replicated vm port expose VM_ID --port 30000 --protocol http` + +### List Tunnels + +```bash +replicated vm port ls [VMID or VMNAME] +``` + +### Remove a Tunnel + +```bash +replicated vm port rm [VMID or VMNAME] +``` + +## Connect a CMX VM with a CMX Cluster + +You can make a CMX Cluster available on the same network as a CMX VM. + +**Compatible Clusters:** Openshift, K3s, RKE2, EC, kURL +**Requirement:** Replicated CLI 0.90.0 or higher. +**NOTE:** Create the cluster first, then attach the new VM to that existing network. + +### Create a Cluster + +```bash +replicated cluster create --distribution [K8s Distribution] +``` + +**Example** – `replicated cluster create --distribution k3s` + +If successful, you'll see: + +``` +ID NAME DISTRIBUTION VERSION STATUS CREATED +EXPIRES COST +b09cf035 affect_mend k3s 1.32.0 queued 2025-01-28 16:04 PST - $0.60 +``` + +### Check the Network + +```bash +replicated network ls +``` + +If successful, you'll see: + +``` +ID NAME STATUS CREATED EXPIRES +accbd6a7 affect_mend running 2025-01-28 16:04 PST 2025-01-28 17:05 PST +``` + +### Create CMX VM on same Network + +```bash +replicated vm create --distribution [Distribution] --network [Network ID] +``` + +**Example** – `replicated vm create --distribution ubuntu --network accbd6a7` + +If successful, you'll see: + +``` +ID NAME DISTRIBUTION VERSION STATUS CREATED EXPIRES COST +760a30b1 laughing_tu ubuntu 24.04 queued 2025-01-28 16:07 PST - $0.60 +``` + +**Example** – Both the cluster `b09cf035` and the VM `760a30b1` are now on the same tailnet. + +## Connect CMX VMs on a Shared 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 VM network + +First, get the ID of an existing VM network: + +```bash +replicated vm ls +``` + +Or + +```bash +replicated network ls +``` + +Use the `--network` flag to create new VMs on the same network + +```bash +replicated vm create --distribution ubuntu --network [NETWORK_ID] +``` + +## Install Embedded Cluster on a CMX VM + +* Only available for [EC **1.21.x**](https://github.com/replicatedhq/embedded-cluster/releases/tag/1.21.0%2Bk8s-1.30) or later. +* You can now reboot a CMX VM. e.g., when running the [Embedded Cluster reset command](https://docs.replicated.com/vendor/embedded-using#reset-a-node). +* For **multi-node** Embedded Cluster initial install: you **no longer** need the flag `--network-interface tailscale0` as part of your [Embedded Cluster install command](https://docs.replicated.com/reference/embedded-cluster-install), which was needed to make sure the nodes can reach the api-server. This was due to an [upstream issue](https://github.com/tailscale/tailscale/issues/14706) with the Calico CNI on a Tailscale network. As of Jul 2, 2025, we have a new overlay network that makes this flag obsolete. \ No newline at end of file diff --git a/sidebars.js b/sidebars.js index 233c57fa5f..dfc1c34c51 100644 --- a/sidebars.js +++ b/sidebars.js @@ -233,6 +233,7 @@ const sidebars = { 'vendor/testing-cluster-addons', 'vendor/compatibility-matrix-usage', 'vendor/testing-how-to', + 'vendor/testing-vm-create', 'vendor/testing-ingress', ], }, From 492c3742babb6f335ba641faffbd8a9128ae00d2 Mon Sep 17 00:00:00 2001 From: Han Yu Date: Mon, 28 Jul 2025 10:41:58 -0400 Subject: [PATCH 02/24] VMs are in Beta --- docs/vendor/testing-vm-create.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/vendor/testing-vm-create.md b/docs/vendor/testing-vm-create.md index 5fe8f4e60c..f69d89a907 100644 --- a/docs/vendor/testing-vm-create.md +++ b/docs/vendor/testing-vm-create.md @@ -1,8 +1,8 @@ -# Create VMs (Alpha) +# Create VMs (Beta) The Compatibility Matrix (CMX) platform allows you to create VMs with no Kubernetes pre-installed on them. This is particularly useful for testing VM-based installs such as the [Replicated Embedded Cluster](https://docs.replicated.com/intro-replicated#embedded-cluster). -| ⚠️ Current Limitations [GitHub Actions](https://docs.replicated.com/vendor/testing-how-to#replicated-github-actions) do not yet work with Compatibility Matrix VMs. [Cluster prepare](https://docs.replicated.com/reference/replicated-cli-cluster-prepare) is not yet supported with Compatibility Matrix VMs. → To try out VMs (Alpha), [email](mailto:han@replicated.com) Replicated for access & support. | +| ⚠️ Current Limitations [GitHub Actions](https://docs.replicated.com/vendor/testing-how-to#replicated-github-actions) do not yet work with Compatibility Matrix VMs. [Cluster prepare](https://docs.replicated.com/reference/replicated-cli-cluster-prepare) is not yet supported with Compatibility Matrix VMs. → To try out VMs (Beta), [email](mailto:han@replicated.com) Replicated for access & support. | | :---- | ## Create VMs @@ -98,7 +98,7 @@ If needed, copy files onto the machine: scp somefile [VMID]@replicatedvm:/home/folder/somefile ``` -| Alpha Limitations: scp with flag -O (legacy scp protocol) is not supported. Relative paths is not supported `❌ scp somefile [VMID]@replicatedvm.com:~ ✅ scp somefile [VMID]@replicatedvm:/home/folder/somefile` File permissions are not inherited. | +| Beta Limitations: scp with flag -O (legacy scp protocol) is not supported. Relative paths is not supported `❌ scp somefile [VMID]@replicatedvm.com:~ ✅ scp somefile [VMID]@replicatedvm:/home/folder/somefile` File permissions are not inherited. | | :---- | ### Direct SSH From 6f0c43fda07af36918b617ca65e55e28698cd4f5 Mon Sep 17 00:00:00 2001 From: Han Yu Date: Mon, 28 Jul 2025 11:36:08 -0400 Subject: [PATCH 03/24] Update tone and format for consistenct --- docs/vendor/testing-vm-create.md | 281 +++++++++++++++++++------------ 1 file changed, 176 insertions(+), 105 deletions(-) diff --git a/docs/vendor/testing-vm-create.md b/docs/vendor/testing-vm-create.md index f69d89a907..020bd7801b 100644 --- a/docs/vendor/testing-vm-create.md +++ b/docs/vendor/testing-vm-create.md @@ -1,31 +1,10 @@ # Create VMs (Beta) -The Compatibility Matrix (CMX) platform allows you to create VMs with no Kubernetes pre-installed on them. This is particularly useful for testing VM-based installs such as the [Replicated Embedded Cluster](https://docs.replicated.com/intro-replicated#embedded-cluster). +The Compatibility Matrix (CMX) platform allows you to create VMs with no Kubernetes pre-installed on them. This is useful for testing VM-based installs such as the [Replicated Embedded Cluster](https://docs.replicated.com/intro-replicated#embedded-cluster). | ⚠️ Current Limitations [GitHub Actions](https://docs.replicated.com/vendor/testing-how-to#replicated-github-actions) do not yet work with Compatibility Matrix VMs. [Cluster prepare](https://docs.replicated.com/reference/replicated-cli-cluster-prepare) is not yet supported with Compatibility Matrix VMs. → To try out VMs (Beta), [email](mailto:han@replicated.com) Replicated for access & support. | | :---- | -## Create VMs - -To create [3] [Ubuntu] VMs: - -```bash -replicated vm create --distribution ubuntu --count 3 -``` - -List supported distributions and versions: - -```bash -replicated vm versions -``` - -Supported VM types: - -| Distribution | Versions | Instance Types | -| :---- | :---- | :---- | -| ubuntu | 24.04, 22.04 | r1.small, r1.medium, r1.large, r1.xlarge, r1.2xlarge | -| almalinux | 8 | r1.small, r1.medium, r1.large, r1.xlarge, r1.2xlarge | - ## Prerequisites Before you can use Compatibility Matrix VMs, you must complete the following prerequisites: @@ -68,6 +47,41 @@ Using multiple SSH public keys: replicated vm create --distribution ubuntu --version 20.04 --ssh-public-key ~/.ssh/id_rsa.pub --ssh-public-key ~/.ssh/id_ed25519.pub ``` +## Create VMs + +To create VMs with Compatibility Matrix: + +1. Run the following command to create VMs: + + ```bash + replicated vm create --distribution DISTRIBUTION --count COUNT + ``` + + Where: + * `DISTRIBUTION` is the Linux distribution for the VM (e.g., ubuntu, almalinux) + * `COUNT` is the number of VMs to create + + **Example:** + + ```bash + replicated vm create --distribution ubuntu --count 3 + ``` + +1. List supported distributions and versions: + + ```bash + replicated vm versions + ``` + +### 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 | +| almalinux | 8 | r1.small, r1.medium, r1.large, r1.xlarge, r1.2xlarge | + ## Connect to a VM There are currently two supported methods to SSH into a VM: @@ -89,16 +103,20 @@ There are currently two supported methods to SSH into a VM: SSH into the VM: ```bash -ssh [VMID]@replicatedvm.com +ssh VMID@replicatedvm.com ``` +Where `VMID` is the ID of the VM. + If needed, copy files onto the machine: ```bash -scp somefile [VMID]@replicatedvm:/home/folder/somefile +scp somefile VMID@replicatedvm:/home/folder/somefile ``` -| Beta Limitations: scp with flag -O (legacy scp protocol) is not supported. Relative paths is not supported `❌ scp somefile [VMID]@replicatedvm.com:~ ✅ scp somefile [VMID]@replicatedvm:/home/folder/somefile` File permissions are not inherited. | +Where `VMID` is the ID of the VM. + +| Beta Limitations: scp with flag -O (legacy scp protocol) is not supported. Relative paths is not supported `❌ scp somefile VMID@replicatedvm.com:~ ✅ scp somefile VMID@replicatedvm:/home/folder/somefile` File permissions are not inherited. | | :---- | ### Direct SSH @@ -108,68 +126,83 @@ scp somefile [VMID]@replicatedvm:/home/folder/somefile Get the SSH endpoint for the VM: -```bash -replicated vm ssh-endpoint [VMID or VMNAME] -``` +1. Run the following command to get the SSH endpoint: -If successful, you'll see: + ```bash + replicated vm ssh-endpoint VMID_OR_VMNAME + ``` -``` -ssh://[github-user-name]@[ssh-endpoint]:[port] -``` + Where `VMID_OR_VMNAME` is the ID or name of the VM. -**Example** – `ssh://MyName@37.27.52.116:46795` + If successful, you'll see: -⚠️ The username for SSH should match the GitHub username in Vendor Portal. ([override info](#override-username)) + ``` + ssh://[github-user-name]@[ssh-endpoint]:[port] + ``` -SSH into the VM: + **Example** – `ssh://MyName@37.27.52.116:46795` -```bash -ssh $(replicated vm ssh-endpoint [VMID or VMNAME]) -``` + ⚠️ The username for SSH should match the GitHub username in Vendor Portal. For more information about overriding the username, see [Override Username](#override-username). + +1. SSH into the VM: + + ```bash + ssh $(replicated vm ssh-endpoint VMID_OR_VMNAME) + ``` -**Example** – `ssh $(replicated vm ssh-endpoint aba1acc2)` + **Example** – `ssh $(replicated vm ssh-endpoint aba1acc2)` ### Copy Files to the VM (SCP) Request the scp endpoint: -```bash -replicated vm scp-endpoint [VMID or VMNAME] -``` +1. Run the following command to get the SCP endpoint: -**Example** – `replicated vm scp-endpoint aba1acc2` + ```bash + replicated vm scp-endpoint VMID_OR_VMNAME + ``` -If successful, you'll see: + Where `VMID_OR_VMNAME` is the ID or name of the VM. -``` -scp://[github-user-name]@[ssh-endpoint]:[port] -``` + **Example** – `replicated vm scp-endpoint aba1acc2` -**Example** – `scp://MyName@37.27.52.116:46795` + If successful, you'll see: -⚠️ The username for SSH should match the GitHub username in Vendor Portal. ([override info](#override-username)) + ``` + scp://[github-user-name]@[ssh-endpoint]:[port] + ``` -SCP files into the VM: + **Example** – `scp://MyName@37.27.52.116:46795` -```bash -scp somefile $(replicated vm scp-endpoint [VMID or VMNAME])//[PATH] -``` + ⚠️ The username for SSH should match the GitHub username in Vendor Portal. For more information about overriding the username, see [Override Username](#override-username). + +1. SCP files into the VM: -**Example** – `scp somefile $(replicated vm scp-endpoint aba1acc2)//home/MyName/somefile` + ```bash + scp somefile $(replicated vm scp-endpoint VMID_OR_VMNAME)//PATH + ``` + + Where `PATH` is the destination path on the VM. + + **Example** – `scp somefile $(replicated vm scp-endpoint aba1acc2)//home/MyName/somefile` #### Override Username -**Note:** You can override the username used for the endpoint with the `--username` flag. -Useful if you want to: +You can override the username used for the endpoint with the `--username` flag. This is useful if you want to: * Use a different GitHub username than what is in Vendor Portal. (Or no username set.) -* 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. ([more info](#use-a-service-github-account)) +* 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. For more information, see [Use a Service GitHub Account](#use-a-service-github-account). + +To override the username: ```bash -replicated vm ssh-endpoint [VMID or VMNAME] --username [github-user-name] +replicated vm ssh-endpoint VMID_OR_VMNAME --username GITHUB_USERNAME ``` +Where: +* `VMID_OR_VMNAME` is the ID or name of the VM +* `GITHUB_USERNAME` is the GitHub username to use for the endpoint + **Example** – `replicated vm ssh-endpoint aba1acc2 --username MyName` ## Connect to a VM Manually @@ -179,40 +212,47 @@ You may need an alternate method if the above options don't work with your prefe When a VM is created, a random port is assigned to each machine within each group of the VM. To connect with the machine over SSH: -```bash -replicated vm ls --output json -``` - -If successful, you'll see: - -```json -[ - { - "id": "e32aafa1", - "name": "sad_black", - "distribution": "ubuntu", - "version": "24.04", - "status": "running", - "created_at": "2024-10-24T15:00:37Z", - "expires_at": "2024-10-24T16:01:10Z", - "ttl": "1h", - "credits_per_hour_per_vm": 0, - "flat_fee": 50000, - "total_credits": 0, - "estimated_cost": 0, - "direct_ssh_port": 33655, - "direct_ssh_endpoint": "95.217.47.21", - "tags": [] - } -] -``` +1. Run the following command to list VMs: + + ```bash + replicated vm ls --output json + ``` + + If successful, you'll see: + + ```json + [ + { + "id": "e32aafa1", + "name": "sad_black", + "distribution": "ubuntu", + "version": "24.04", + "status": "running", + "created_at": "2024-10-24T15:00:37Z", + "expires_at": "2024-10-24T16:01:10Z", + "ttl": "1h", + "credits_per_hour_per_vm": 0, + "flat_fee": 50000, + "total_credits": 0, + "estimated_cost": 0, + "direct_ssh_port": 33655, + "direct_ssh_endpoint": "95.217.47.21", + "tags": [] + } + ] + ``` To connect with them, you can run: ```bash -ssh -p [direct_ssh_port] [github_username]@[direct_ssh_endpoint] +ssh -p DIRECT_SSH_PORT GITHUB_USERNAME@DIRECT_SSH_ENDPOINT ``` +Where: +* `DIRECT_SSH_PORT` is the port number from the JSON output +* `GITHUB_USERNAME` is your GitHub username +* `DIRECT_SSH_ENDPOINT` is the endpoint from the JSON output + **Example** – `ssh -p 33655 myName@95.217.47.21` ## Compatibility Matrix Tunnels @@ -225,25 +265,40 @@ You can expose ports on a VM and make them accessible on the public internet. ### Create a Tunnel +To create a tunnel: + ```bash -replicated vm port expose [VMID or VMNAME] +replicated vm port expose VMID_OR_VMNAME --port PORT --protocol PROTOCOL ``` -**Example** – Expose port 3000 with HTTP protocol +Where: +* `VMID_OR_VMNAME` is the ID or name of the VM +* `PORT` is the port number to expose +* `PROTOCOL` is the protocol to use (e.g., http, tcp) + +**Example** – Expose port 3000 with HTTP protocol: `replicated vm port expose VM_ID --port 30000 --protocol http` ### List Tunnels +To list tunnels for a VM: + ```bash -replicated vm port ls [VMID or VMNAME] +replicated vm port ls VMID_OR_VMNAME ``` +Where `VMID_OR_VMNAME` is the ID or name of the VM. + ### Remove a Tunnel +To remove a tunnel: + ```bash -replicated vm port rm [VMID or VMNAME] +replicated vm port rm VMID_OR_VMNAME ``` +Where `VMID_OR_VMNAME` is the ID or name of the VM. + ## Connect a CMX VM with a CMX Cluster You can make a CMX Cluster available on the same network as a CMX VM. @@ -254,10 +309,14 @@ You can make a CMX Cluster available on the same network as a CMX VM. ### Create a Cluster +To create a cluster: + ```bash -replicated cluster create --distribution [K8s Distribution] +replicated cluster create --distribution K8S_DISTRIBUTION ``` +Where `K8S_DISTRIBUTION` is the Kubernetes distribution for the cluster. + **Example** – `replicated cluster create --distribution k3s` If successful, you'll see: @@ -270,6 +329,8 @@ b09cf035 affect_mend k3s 1.32.0 queued 2025-01-28 16:04 ### Check the Network +To check the network: + ```bash replicated network ls ``` @@ -283,10 +344,16 @@ accbd6a7 affect_mend running 2025-01-28 16:04 PST 2025-01-28 17:05 PST ### Create CMX VM on same Network +To create a VM on the same network: + ```bash -replicated vm create --distribution [Distribution] --network [Network ID] +replicated vm create --distribution DISTRIBUTION --network NETWORK_ID ``` +Where: +* `DISTRIBUTION` is the Linux distribution for the VM +* `NETWORK_ID` is the ID of the network from the previous step + **Example** – `replicated vm create --distribution ubuntu --network accbd6a7` If successful, you'll see: @@ -308,26 +375,30 @@ replicated vm create --distribution ubuntu --count 3 ### Join VMs to an Existing VM network -First, get the ID of an existing VM network: +To join VMs to an existing network: -```bash -replicated vm ls -``` +1. Get the ID of an existing VM network: -Or + ```bash + replicated vm ls + ``` -```bash -replicated network ls -``` + Or -Use the `--network` flag to create new VMs on the same network + ```bash + replicated network ls + ``` -```bash -replicated vm create --distribution ubuntu --network [NETWORK_ID] -``` +1. Use the `--network` flag to create new VMs on the same network: + + ```bash + replicated vm create --distribution ubuntu --network NETWORK_ID + ``` + + Where `NETWORK_ID` is the ID of the existing network. ## Install Embedded Cluster on a CMX VM * Only available for [EC **1.21.x**](https://github.com/replicatedhq/embedded-cluster/releases/tag/1.21.0%2Bk8s-1.30) or later. * You can now reboot a CMX VM. e.g., when running the [Embedded Cluster reset command](https://docs.replicated.com/vendor/embedded-using#reset-a-node). -* For **multi-node** Embedded Cluster initial install: you **no longer** need the flag `--network-interface tailscale0` as part of your [Embedded Cluster install command](https://docs.replicated.com/reference/embedded-cluster-install), which was needed to make sure the nodes can reach the api-server. This was due to an [upstream issue](https://github.com/tailscale/tailscale/issues/14706) with the Calico CNI on a Tailscale network. As of Jul 2, 2025, we have a new overlay network that makes this flag obsolete. \ No newline at end of file +* For **multi-node** Embedded Cluster initial install: you **no longer** need the flag `--network-interface tailscale0` as part of your Embedded Cluster install command, which was needed to make sure the nodes can reach the api-server. This was due to an [upstream issue](https://github.com/tailscale/tailscale/issues/14706) with the Calico CNI on a Tailscale network. A new overlay network is available that makes this flag obsolete. For more information about the Embedded Cluster install command, see [Embedded Cluster Install](https://docs.replicated.com/reference/embedded-cluster-install). \ No newline at end of file From 5ee95017d763bcdec560de77835de953c9ba0767 Mon Sep 17 00:00:00 2001 From: Han Yu Date: Mon, 28 Jul 2025 12:11:29 -0400 Subject: [PATCH 04/24] Split up the "Use Compatibility Matrix" page --- docs/vendor/testing-ci-cd.md | 29 ++++++++++++++++ ...{testing-how-to.md => testing-clusters.md} | 33 +++---------------- sidebars.js | 11 +++++-- 3 files changed, 42 insertions(+), 31 deletions(-) create mode 100644 docs/vendor/testing-ci-cd.md rename docs/vendor/{testing-how-to.md => testing-clusters.md} (84%) diff --git a/docs/vendor/testing-ci-cd.md b/docs/vendor/testing-ci-cd.md new file mode 100644 index 0000000000..afbbf53642 --- /dev/null +++ b/docs/vendor/testing-ci-cd.md @@ -0,0 +1,29 @@ +import TestRecs from "../partials/ci-cd/_test-recs.mdx" + +# CI/CD + +This topic describes how to integrate Replicated Compatibility Matrix into your CI/CD workflows. + +## About Using Compatibility Matrix with CI/CD + +Replicated recommends that you integrate Compatibility Matrix 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 GitHub Actions + +Replicated maintains a set of custom GitHub actions that are designed to replace repetitive tasks related to using Compatibility Matrix and distributing applications with Replicated. + +If you use GitHub Actions as your CI/CD platform, you can include these custom actions in your workflows rather than using Replicated CLI commands. Integrating the Replicated GitHub actions into your CI/CD pipeline helps you quickly build workflows with the required inputs and outputs, without needing to manually create the required CLI commands for each step. + +To view all the available GitHub actions that Replicated maintains, see the [replicatedhq/replicated-actions](https://github.com/replicatedhq/replicated-actions/) repository in GitHub. + +For more information, see [Use Replicated GitHub Actions in CI/CD](/vendor/ci-workflows-github-actions). + +### Recommended Workflows + +Replicated recommends that you maintain unique CI/CD workflows for development (continuous integration) and for releasing your software (continuous delivery). For example development and release workflows that integrate Compatibility Matrix for testing, see [Recommended CI/CD Workflows](/vendor/ci-workflows). + +### Test Script Recommendations + +Incorporating code tests into your CI/CD workflows is important for ensuring that developers receive quick feedback and can make updates in small iterations. Replicated recommends that you create and run all of the following test types as part of your CI/CD workflows: + + \ No newline at end of file diff --git a/docs/vendor/testing-how-to.md b/docs/vendor/testing-clusters.md similarity index 84% rename from docs/vendor/testing-how-to.md rename to docs/vendor/testing-clusters.md index 4f9dce091d..ee28b040a8 100644 --- a/docs/vendor/testing-how-to.md +++ b/docs/vendor/testing-clusters.md @@ -1,13 +1,12 @@ -import TestRecs from "../partials/ci-cd/_test-recs.mdx" import Prerequisites from "../partials/cmx/_prerequisites.mdx" -# Use Compatibility Matrix +# Clusters -This topic describes how to use Replicated Compatibility Matrix to create ephemeral clusters. +This topic describes how to use Replicated Compatibility Matrix to create and manage ephemeral clusters. ## Prerequisites -Before you can use Compatibility Matrix, you must complete the following prerequisites: +Before you can use Compatibility Matrix clusters, you must complete the following prerequisites: @@ -286,28 +285,4 @@ To delete a cluster using the Vendor Portal: Delete cluster button - [View a larger version of this image](/images/cmx-delete-cluster.png) - -## About Using Compatibility Matrix with CI/CD - -Replicated recommends that you integrate Compatibility Matrix 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 GitHub Actions - -Replicated maintains a set of custom GitHub actions that are designed to replace repetitive tasks related to using Compatibility Matrix and distributing applications with Replicated. - -If you use GitHub Actions as your CI/CD platform, you can include these custom actions in your workflows rather than using Replicated CLI commands. Integrating the Replicated GitHub actions into your CI/CD pipeline helps you quickly build workflows with the required inputs and outputs, without needing to manually create the required CLI commands for each step. - -To view all the available GitHub actions that Replicated maintains, see the [replicatedhq/replicated-actions](https://github.com/replicatedhq/replicated-actions/) repository in GitHub. - -For more information, see [Use Replicated GitHub Actions in CI/CD](/vendor/ci-workflows-github-actions). - -### Recommended Workflows - -Replicated recommends that you maintain unique CI/CD workflows for development (continuous integration) and for releasing your software (continuous delivery). For example development and release workflows that integrate Compatibility Matrix for testing, see [Recommended CI/CD Workflows](/vendor/ci-workflows). - -### Test Script Recommendations - -Incorporating code tests into your CI/CD workflows is important for ensuring that developers receive quick feedback and can make updates in small iterations. Replicated recommends that you create and run all of the following test types as part of your CI/CD workflows: - - + [View a larger version of this image](/images/cmx-delete-cluster.png) \ No newline at end of file diff --git a/sidebars.js b/sidebars.js index dfc1c34c51..55ca2e52ea 100644 --- a/sidebars.js +++ b/sidebars.js @@ -232,8 +232,15 @@ const sidebars = { 'vendor/testing-supported-clusters', 'vendor/testing-cluster-addons', 'vendor/compatibility-matrix-usage', - 'vendor/testing-how-to', - 'vendor/testing-vm-create', + { + type: 'category', + label: 'Use Compatibility Matrix', + items: [ + 'vendor/testing-clusters', + 'vendor/testing-vm-create', + 'vendor/testing-ci-cd', + ], + }, 'vendor/testing-ingress', ], }, From 94f8991564cc36d20e0266255cb68c8aa4f8e8c6 Mon Sep 17 00:00:00 2001 From: Han Yu Date: Mon, 28 Jul 2025 13:03:07 -0400 Subject: [PATCH 05/24] Reorder sidebar --- docs/vendor/testing-ci-cd.md | 2 +- docs/vendor/{testing-clusters.md => testing-how-to.md} | 2 +- sidebars.js | 6 +++--- 3 files changed, 5 insertions(+), 5 deletions(-) rename docs/vendor/{testing-clusters.md => testing-how-to.md} (99%) diff --git a/docs/vendor/testing-ci-cd.md b/docs/vendor/testing-ci-cd.md index afbbf53642..1749e06b5e 100644 --- a/docs/vendor/testing-ci-cd.md +++ b/docs/vendor/testing-ci-cd.md @@ -1,6 +1,6 @@ import TestRecs from "../partials/ci-cd/_test-recs.mdx" -# CI/CD +# Use Compatibility Matrix with CI/CD This topic describes how to integrate Replicated Compatibility Matrix into your CI/CD workflows. diff --git a/docs/vendor/testing-clusters.md b/docs/vendor/testing-how-to.md similarity index 99% rename from docs/vendor/testing-clusters.md rename to docs/vendor/testing-how-to.md index ee28b040a8..c102113005 100644 --- a/docs/vendor/testing-clusters.md +++ b/docs/vendor/testing-how-to.md @@ -1,6 +1,6 @@ import Prerequisites from "../partials/cmx/_prerequisites.mdx" -# Clusters +# Create Clusters This topic describes how to use Replicated Compatibility Matrix to create and manage ephemeral clusters. diff --git a/sidebars.js b/sidebars.js index 55ca2e52ea..16a255101e 100644 --- a/sidebars.js +++ b/sidebars.js @@ -230,17 +230,17 @@ const sidebars = { 'vendor/testing-about', 'vendor/testing-pricing', 'vendor/testing-supported-clusters', - 'vendor/testing-cluster-addons', - 'vendor/compatibility-matrix-usage', { type: 'category', label: 'Use Compatibility Matrix', items: [ - 'vendor/testing-clusters', + 'vendor/testing-how-to', 'vendor/testing-vm-create', 'vendor/testing-ci-cd', ], }, + 'vendor/testing-cluster-addons', + 'vendor/compatibility-matrix-usage', 'vendor/testing-ingress', ], }, From 3748c27034c00af17267f2fb08c348aafb8538e6 Mon Sep 17 00:00:00 2001 From: Han Yu Date: Mon, 28 Jul 2025 18:32:37 -0400 Subject: [PATCH 06/24] Clean up VM docs --- docs/vendor/testing-vm-create.md | 265 ++++--------------------------- 1 file changed, 27 insertions(+), 238 deletions(-) diff --git a/docs/vendor/testing-vm-create.md b/docs/vendor/testing-vm-create.md index 020bd7801b..a8d11fa91c 100644 --- a/docs/vendor/testing-vm-create.md +++ b/docs/vendor/testing-vm-create.md @@ -1,39 +1,44 @@ # Create VMs (Beta) -The Compatibility Matrix (CMX) platform allows you to create VMs with no Kubernetes pre-installed on them. This is useful for testing VM-based installs such as the [Replicated Embedded Cluster](https://docs.replicated.com/intro-replicated#embedded-cluster). +This topic describes how to use Replicated Compatibility Matrix to create and manage ephemeral VMs, which allows greater flexibility in testing VM-based installs such as the [Replicated Embedded Cluster](https://docs.replicated.com/intro-replicated#embedded-cluster). -| ⚠️ Current Limitations [GitHub Actions](https://docs.replicated.com/vendor/testing-how-to#replicated-github-actions) do not yet work with Compatibility Matrix VMs. [Cluster prepare](https://docs.replicated.com/reference/replicated-cli-cluster-prepare) is not yet supported with Compatibility Matrix VMs. → To try out VMs (Beta), [email](mailto:han@replicated.com) Replicated for access & support. | -| :---- | +## About Compatibility Matrix VMs + +Compatibility Matrix VMs provide isolated Linux environments for testing your applications. Unlike clusters, VMs give you full control over the operating system and allow you to test installation methods that require direct OS access. + +**When to use VMs vs Clusters:** +* **Use VMs** for testing Embedded Cluster installers, air-gap installations, or when you need full OS control +* **Use Clusters** for testing Kubernetes-based deployments and Helm installations ## Prerequisites Before you can use Compatibility Matrix VMs, you must complete the following prerequisites: -### Connect GitHub Account +* [Configure your GitHub username in Replicated Vendor Portal](team-management-github-username#procedure) -Before you can SSH into a VM: +* Make sure you have added your SSH key in your GitHub account. For instructions, see [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. Configure your GitHub username in Replicated Vendor Portal ([Replicated Docs](https://docs.replicated.com/vendor/team-management-github-username#procedure)) -2. Make sure you've added your SSH key in your GitHub account ([GitHub instructions](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account)) +:::note +GitHub usernames and SSH keys are synced every 24hrs. To immediately sync: → [Account Settings](https://vendor.replicated.com/account-settings) > click Save. Keys are synced to the VM at time of creation, so any updates after creation are ignored. +::: -| GitHub usernames and SSH keys are synced every 24hrs. To immediately sync: → [Account Settings](https://vendor.replicated.com/account-settings/info) > click Save Keys are synced to the VM at time of creation, so any updates after creation are ignored. | -| :---- | +## Set Up SSH Access -To confirm your GitHub username and SSH key have been set up successfully: +After completing the prerequisites, verify your SSH access is working: ```bash ssh -T replicated@replicatedvm.com ``` -If successful, you'll see: +If successful, you will see: ``` -You've successfully authenticated, use [VM_ID]@replicatedvm.com to access your VM. +You have successfully authenticated, use [VM_ID]@replicatedvm.com to access your VM. ``` If you do not see this message, your public/private key likely was not available. -### Use a Service GitHub Account +### Alternative: Use a Service GitHub Account To automate VMs in your CI, or otherwise avoid using a personal GitHub account, use the flag `--ssh-public-key` when you first create a VM: @@ -97,8 +102,9 @@ There are currently two supported methods to SSH into a VM: ### CMX Forwarder -| Transferring files using CMX Forwarder is slower than Direct SSH. CMX servers run on EKS, so depending on your location going through the forwarder will add latency. If you're transferring large files onto the VM, use [Direct SSH](#direct-ssh) in combination with SCP. | -| :---- | +:::note +Transferring files using CMX Forwarder is slower than Direct SSH. CMX servers run on EKS, so depending on your location going through the forwarder will add latency. If you're transferring large files onto the VM, use [Direct SSH](#direct-ssh) in combination with SCP. +::: SSH into the VM: @@ -116,13 +122,15 @@ scp somefile VMID@replicatedvm:/home/folder/somefile Where `VMID` is the ID of the VM. -| Beta Limitations: scp with flag -O (legacy scp protocol) is not supported. Relative paths is not supported `❌ scp somefile VMID@replicatedvm.com:~ ✅ scp somefile VMID@replicatedvm:/home/folder/somefile` File permissions are not inherited. | -| :---- | +:::note +**Beta Limitations:** scp with flag -O (legacy scp protocol) is not supported. Relative paths is not supported `❌ scp somefile VMID@replicatedvm.com:~ ✅ scp somefile VMID@replicatedvm:/home/folder/somefile` File permissions are not inherited. +::: ### Direct SSH -| Transferring files using Direct SSH allows you to use your SSH tool of choice, and pass any client-supported flags. Note: Requires Replicated CLI v0.104.0 or later. | -| :---- | +:::note +Transferring files using Direct SSH allows you to use your SSH tool of choice, and pass any client-supported flags. Note: Requires Replicated CLI v0.104.0 or later. +::: Get the SSH endpoint for the VM: @@ -183,222 +191,3 @@ Request the scp endpoint: ``` Where `PATH` is the destination path on the VM. - - **Example** – `scp somefile $(replicated vm scp-endpoint aba1acc2)//home/MyName/somefile` - -#### Override Username - -You can override the username used for the endpoint with the `--username` flag. This is useful if you want to: - -* Use a different GitHub username than what is in Vendor Portal. (Or no username set.) -* 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. For more information, see [Use a Service GitHub Account](#use-a-service-github-account). - -To override the username: - -```bash -replicated vm ssh-endpoint VMID_OR_VMNAME --username GITHUB_USERNAME -``` - -Where: -* `VMID_OR_VMNAME` is the ID or name of the VM -* `GITHUB_USERNAME` is the GitHub username to use for the endpoint - -**Example** – `replicated vm ssh-endpoint aba1acc2 --username MyName` - -## Connect to a VM Manually - -You may need an alternate method if the above options don't work with your preferred SSH client. - -When a VM is created, a random port is assigned to each machine within each group of the VM. -To connect with the machine over SSH: - -1. Run the following command to list VMs: - - ```bash - replicated vm ls --output json - ``` - - If successful, you'll see: - - ```json - [ - { - "id": "e32aafa1", - "name": "sad_black", - "distribution": "ubuntu", - "version": "24.04", - "status": "running", - "created_at": "2024-10-24T15:00:37Z", - "expires_at": "2024-10-24T16:01:10Z", - "ttl": "1h", - "credits_per_hour_per_vm": 0, - "flat_fee": 50000, - "total_credits": 0, - "estimated_cost": 0, - "direct_ssh_port": 33655, - "direct_ssh_endpoint": "95.217.47.21", - "tags": [] - } - ] - ``` - -To connect with them, you can run: - -```bash -ssh -p DIRECT_SSH_PORT GITHUB_USERNAME@DIRECT_SSH_ENDPOINT -``` - -Where: -* `DIRECT_SSH_PORT` is the port number from the JSON output -* `GITHUB_USERNAME` is your GitHub username -* `DIRECT_SSH_ENDPOINT` is the endpoint from the JSON output - -**Example** – `ssh -p 33655 myName@95.217.47.21` - -## Compatibility Matrix Tunnels - -| ⚠️Creating wildcard DNS entries for VMs is not currently supported. ([email](mailto:han@replicated.com) feedback) | -| :---- | - -You can expose ports on a VM and make them accessible on the public internet. -(Learn about a similar feature: [Compatibility Matrix Tunnels for Clusters](https://docs.replicated.com/vendor/testing-ingress#compatibility-matrix-tunnels-beta)) - -### Create a Tunnel - -To create a tunnel: - -```bash -replicated vm port expose VMID_OR_VMNAME --port PORT --protocol PROTOCOL -``` - -Where: -* `VMID_OR_VMNAME` is the ID or name of the VM -* `PORT` is the port number to expose -* `PROTOCOL` is the protocol to use (e.g., http, tcp) - -**Example** – Expose port 3000 with HTTP protocol: -`replicated vm port expose VM_ID --port 30000 --protocol http` - -### List Tunnels - -To list tunnels for a VM: - -```bash -replicated vm port ls VMID_OR_VMNAME -``` - -Where `VMID_OR_VMNAME` is the ID or name of the VM. - -### Remove a Tunnel - -To remove a tunnel: - -```bash -replicated vm port rm VMID_OR_VMNAME -``` - -Where `VMID_OR_VMNAME` is the ID or name of the VM. - -## Connect a CMX VM with a CMX Cluster - -You can make a CMX Cluster available on the same network as a CMX VM. - -**Compatible Clusters:** Openshift, K3s, RKE2, EC, kURL -**Requirement:** Replicated CLI 0.90.0 or higher. -**NOTE:** Create the cluster first, then attach the new VM to that existing network. - -### Create a Cluster - -To create a cluster: - -```bash -replicated cluster create --distribution K8S_DISTRIBUTION -``` - -Where `K8S_DISTRIBUTION` is the Kubernetes distribution for the cluster. - -**Example** – `replicated cluster create --distribution k3s` - -If successful, you'll see: - -``` -ID NAME DISTRIBUTION VERSION STATUS CREATED -EXPIRES COST -b09cf035 affect_mend k3s 1.32.0 queued 2025-01-28 16:04 PST - $0.60 -``` - -### Check the Network - -To check the network: - -```bash -replicated network ls -``` - -If successful, you'll see: - -``` -ID NAME STATUS CREATED EXPIRES -accbd6a7 affect_mend running 2025-01-28 16:04 PST 2025-01-28 17:05 PST -``` - -### Create CMX VM on same Network - -To create a VM on the same network: - -```bash -replicated vm create --distribution DISTRIBUTION --network NETWORK_ID -``` - -Where: -* `DISTRIBUTION` is the Linux distribution for the VM -* `NETWORK_ID` is the ID of the network from the previous step - -**Example** – `replicated vm create --distribution ubuntu --network accbd6a7` - -If successful, you'll see: - -``` -ID NAME DISTRIBUTION VERSION STATUS CREATED EXPIRES COST -760a30b1 laughing_tu ubuntu 24.04 queued 2025-01-28 16:07 PST - $0.60 -``` - -**Example** – Both the cluster `b09cf035` and the VM `760a30b1` are now on the same tailnet. - -## Connect CMX VMs on a Shared 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 VM network - -To join VMs to an existing network: - -1. Get the ID of an existing VM network: - - ```bash - replicated vm ls - ``` - - Or - - ```bash - replicated network ls - ``` - -1. Use the `--network` flag to create new VMs on the same network: - - ```bash - replicated vm create --distribution ubuntu --network NETWORK_ID - ``` - - Where `NETWORK_ID` is the ID of the existing network. - -## Install Embedded Cluster on a CMX VM - -* Only available for [EC **1.21.x**](https://github.com/replicatedhq/embedded-cluster/releases/tag/1.21.0%2Bk8s-1.30) or later. -* You can now reboot a CMX VM. e.g., when running the [Embedded Cluster reset command](https://docs.replicated.com/vendor/embedded-using#reset-a-node). -* For **multi-node** Embedded Cluster initial install: you **no longer** need the flag `--network-interface tailscale0` as part of your Embedded Cluster install command, which was needed to make sure the nodes can reach the api-server. This was due to an [upstream issue](https://github.com/tailscale/tailscale/issues/14706) with the Calico CNI on a Tailscale network. A new overlay network is available that makes this flag obsolete. For more information about the Embedded Cluster install command, see [Embedded Cluster Install](https://docs.replicated.com/reference/embedded-cluster-install). \ No newline at end of file From 2c7fa0dda10235e8c117eb727b3ff1c5fe436777 Mon Sep 17 00:00:00 2001 From: Han Yu Date: Tue, 29 Jul 2025 10:58:05 -0400 Subject: [PATCH 07/24] Restore missing content --- docs/vendor/testing-vm-create.md | 172 +++++++++++++++++++++++++++++++ 1 file changed, 172 insertions(+) diff --git a/docs/vendor/testing-vm-create.md b/docs/vendor/testing-vm-create.md index a8d11fa91c..d8615580fe 100644 --- a/docs/vendor/testing-vm-create.md +++ b/docs/vendor/testing-vm-create.md @@ -191,3 +191,175 @@ Request the scp endpoint: ``` Where `PATH` is the destination path on the VM. + +### Override Username + +You can override the username used for the endpoint with the `--username` flag. This is useful if you want to: + +* Use a different GitHub username than what is in Vendor Portal (or no username set) +* 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 + +```bash +replicated vm ssh-endpoint VMID_OR_VMNAME --username GITHUB_USER_NAME +``` + +**Example** – `replicated vm ssh-endpoint aba1acc2 --username MyName` + +## Connect to a VM Manually + +You may need an alternate method if the above options don't work with your preferred SSH client. + +When a VM is created, a random port is assigned to each machine within each group of the VM. To connect with the machine over SSH: + +```bash +replicated vm ls --output json +``` + +If successful, you'll see: + +```json +[ + { + "id": "e32aafa1", + "name": "sad_black", + "distribution": "ubuntu", + "version": "24.04", + "status": "running", + "created_at": "2024-10-24T15:00:37Z", + "expires_at": "2024-10-24T16:01:10Z", + "ttl": "1h", + "credits_per_hour_per_vm": 0, + "flat_fee": 50000, + "total_credits": 0, + "estimated_cost": 0, + "direct_ssh_port": 33655, + "direct_ssh_endpoint": "95.217.47.21", + "tags": [] + } +] +``` + +To connect with them, you can run: + +```bash +ssh -p DIRECT_SSH_PORT GITHUB_USERNAME@DIRECT_SSH_ENDPOINT +``` + +**Example** – `ssh -p 33655 myName@95.217.47.21` + +## Compatibility Matrix Tunnels + +:::note +Creating wildcard DNS entries for VMs is not currently supported. For feedback, contact Replicated support. +::: + +You can expose ports on a VM and make them accessible on the public internet. For more information about a similar feature, see [Compatibility Matrix Tunnels for Clusters](testing-ingress#compatibility-matrix-tunnels-beta). + +### Create a Tunnel + +```bash +replicated vm port expose VMID_OR_VMNAME --port PORT --protocol PROTOCOL +``` + +**Example** – Expose port 3000 with HTTP protocol +`replicated vm port expose VM_ID --port 30000 --protocol http` + +### List Tunnels + +```bash +replicated vm port ls VMID_OR_VMNAME +``` + +### Remove a Tunnel + +```bash +replicated vm port rm VMID_OR_VMNAME +``` + +## Connect a CMX VM with a CMX Cluster + +You can make a CMX Cluster available on the same network as a CMX VM. + +**Compatible Clusters:** Openshift, K3s, RKE2, EC, kURL +**Requirement:** Replicated CLI 0.90.0 or higher +**Note:** Create the cluster first, then attach the new VM to that existing network. + +### Create a Cluster + +```bash +replicated cluster create --distribution K8S_DISTRIBUTION +``` + +**Example** – `replicated cluster create --distribution k3s` + +If successful, you'll see: + +``` +ID NAME DISTRIBUTION VERSION STATUS CREATED +EXPIRES COST +b09cf035 affect_mend k3s 1.32.0 queued 2025-01-28 16:04 PST - $0.60 +``` + +### Check the Network + +```bash +replicated network ls +``` + +If successful, you'll see: + +``` +ID NAME STATUS CREATED EXPIRES +accbd6a7 affect_mend running 2025-01-28 16:04 PST 2025-01-28 17:05 PST +``` + +### Create CMX VM on Same Network + +```bash +replicated vm create --distribution DISTRIBUTION --network NETWORK_ID +``` + +**Example** – `replicated vm create --distribution ubuntu --network accbd6a7` + +If successful, you'll see: + +``` +ID NAME DISTRIBUTION VERSION STATUS CREATED EXPIRES COST +760a30b1 laughing_tu ubuntu 24.04 queued 2025-01-28 16:07 PST - $0.60 +``` + +**Example** – Both the cluster `b09cf035` and the VM `760a30b1` are now on the same tailnet. + +## Connect CMX VMs on a Shared 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 VM Network + +First, get the ID of an existing VM network: + +```bash +replicated vm ls +``` + +Or + +```bash +replicated network ls +``` + +Use the `--network` flag to create new VMs on the same network: + +```bash +replicated vm create --distribution ubuntu --network NETWORK_ID +``` + +## Install Embedded Cluster on a CMX VM + +* Only available for [EC **1.21.x**](https://github.com/replicatedhq/embedded-cluster/releases/tag/1.21.0%2Bk8s-1.30) or later +* You can now reboot a CMX VM. For example, when running the [Embedded Cluster reset command](embedded-using#reset-a-node) +* For **multi-node** Embedded Cluster initial install: you **no longer** need the flag `--network-interface tailscale0` as part of your [Embedded Cluster install command](reference/embedded-cluster-install), which was needed to make sure the nodes can reach the api-server. This was due to an [upstream issue](https://github.com/tailscale/tailscale/issues/14706) with the Calico CNI on a Tailscale network. As of Jul 2, 2025, we have a new overlay network that makes this flag obsolete From 4e3a726ca44b9968e26087cb133753cf00d060ec Mon Sep 17 00:00:00 2001 From: Han Yu Date: Tue, 29 Jul 2025 11:05:13 -0400 Subject: [PATCH 08/24] Edit limitations --- docs/vendor/testing-vm-create.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/vendor/testing-vm-create.md b/docs/vendor/testing-vm-create.md index d8615580fe..ab003ec78e 100644 --- a/docs/vendor/testing-vm-create.md +++ b/docs/vendor/testing-vm-create.md @@ -358,8 +358,9 @@ Use the `--network` flag to create new VMs on the same network: replicated vm create --distribution ubuntu --network NETWORK_ID ``` -## Install Embedded Cluster on a CMX VM +## Limitations -* Only available for [EC **1.21.x**](https://github.com/replicatedhq/embedded-cluster/releases/tag/1.21.0%2Bk8s-1.30) or later -* You can now reboot a CMX VM. For example, when running the [Embedded Cluster reset command](embedded-using#reset-a-node) -* For **multi-node** Embedded Cluster initial install: you **no longer** need the flag `--network-interface tailscale0` as part of your [Embedded Cluster install command](reference/embedded-cluster-install), which was needed to make sure the nodes can reach the api-server. This was due to an [upstream issue](https://github.com/tailscale/tailscale/issues/14706) with the Calico CNI on a Tailscale network. As of Jul 2, 2025, we have a new overlay network that makes this flag obsolete +- Installing Embedded Cluster is for [EC **1.21.x**](https://github.com/replicatedhq/embedded-cluster/releases/tag/1.21.0%2Bk8s-1.30) or later + - To reboot a CMX VM, run the [Embedded Cluster reset command](embedded-using#reset-a-node) +- [GitHub Actions](https://docs.replicated.com/vendor/testing-how-to#replicated-github-actions) do not yet work with Compatibility Matrix VMs. +- [Cluster prepare](https://docs.replicated.com/reference/replicated-cli-cluster-prepare) is not yet supported with Compatibility Matrix VMs. \ No newline at end of file From 89befa3270b9b6d9539849ae7e4444ef3109c4ef Mon Sep 17 00:00:00 2001 From: Han Yu Date: Tue, 29 Jul 2025 11:12:36 -0400 Subject: [PATCH 09/24] Split VM docs into 2 pages --- docs/vendor/testing-vm-create.md | 111 -------------------------- docs/vendor/testing-vm-networking.md | 114 +++++++++++++++++++++++++++ sidebars.js | 1 + 3 files changed, 115 insertions(+), 111 deletions(-) create mode 100644 docs/vendor/testing-vm-networking.md diff --git a/docs/vendor/testing-vm-create.md b/docs/vendor/testing-vm-create.md index ab003ec78e..657a00f3ec 100644 --- a/docs/vendor/testing-vm-create.md +++ b/docs/vendor/testing-vm-create.md @@ -247,117 +247,6 @@ ssh -p DIRECT_SSH_PORT GITHUB_USERNAME@DIRECT_SSH_ENDPOINT **Example** – `ssh -p 33655 myName@95.217.47.21` -## Compatibility Matrix Tunnels - -:::note -Creating wildcard DNS entries for VMs is not currently supported. For feedback, contact Replicated support. -::: - -You can expose ports on a VM and make them accessible on the public internet. For more information about a similar feature, see [Compatibility Matrix Tunnels for Clusters](testing-ingress#compatibility-matrix-tunnels-beta). - -### Create a Tunnel - -```bash -replicated vm port expose VMID_OR_VMNAME --port PORT --protocol PROTOCOL -``` - -**Example** – Expose port 3000 with HTTP protocol -`replicated vm port expose VM_ID --port 30000 --protocol http` - -### List Tunnels - -```bash -replicated vm port ls VMID_OR_VMNAME -``` - -### Remove a Tunnel - -```bash -replicated vm port rm VMID_OR_VMNAME -``` - -## Connect a CMX VM with a CMX Cluster - -You can make a CMX Cluster available on the same network as a CMX VM. - -**Compatible Clusters:** Openshift, K3s, RKE2, EC, kURL -**Requirement:** Replicated CLI 0.90.0 or higher -**Note:** Create the cluster first, then attach the new VM to that existing network. - -### Create a Cluster - -```bash -replicated cluster create --distribution K8S_DISTRIBUTION -``` - -**Example** – `replicated cluster create --distribution k3s` - -If successful, you'll see: - -``` -ID NAME DISTRIBUTION VERSION STATUS CREATED -EXPIRES COST -b09cf035 affect_mend k3s 1.32.0 queued 2025-01-28 16:04 PST - $0.60 -``` - -### Check the Network - -```bash -replicated network ls -``` - -If successful, you'll see: - -``` -ID NAME STATUS CREATED EXPIRES -accbd6a7 affect_mend running 2025-01-28 16:04 PST 2025-01-28 17:05 PST -``` - -### Create CMX VM on Same Network - -```bash -replicated vm create --distribution DISTRIBUTION --network NETWORK_ID -``` - -**Example** – `replicated vm create --distribution ubuntu --network accbd6a7` - -If successful, you'll see: - -``` -ID NAME DISTRIBUTION VERSION STATUS CREATED EXPIRES COST -760a30b1 laughing_tu ubuntu 24.04 queued 2025-01-28 16:07 PST - $0.60 -``` - -**Example** – Both the cluster `b09cf035` and the VM `760a30b1` are now on the same tailnet. - -## Connect CMX VMs on a Shared 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 VM Network - -First, get the ID of an existing VM network: - -```bash -replicated vm ls -``` - -Or - -```bash -replicated network ls -``` - -Use the `--network` flag to create new VMs on the same network: - -```bash -replicated vm create --distribution ubuntu --network NETWORK_ID -``` - ## Limitations - Installing Embedded Cluster is for [EC **1.21.x**](https://github.com/replicatedhq/embedded-cluster/releases/tag/1.21.0%2Bk8s-1.30) or later diff --git a/docs/vendor/testing-vm-networking.md b/docs/vendor/testing-vm-networking.md new file mode 100644 index 0000000000..645a7d7b89 --- /dev/null +++ b/docs/vendor/testing-vm-networking.md @@ -0,0 +1,114 @@ +# VM Networking (Beta) + +This topic describes advanced networking features for Replicated Compatibility Matrix VMs, including port exposure, VM-to-cluster connections, and shared networks. + +## Compatibility Matrix Tunnels + +:::note +Creating wildcard DNS entries for VMs is not currently supported. For feedback, contact Replicated support. +::: + +You can expose ports on a VM and make them accessible on the public internet. For more information about a similar feature, see [Compatibility Matrix Tunnels for Clusters](testing-ingress#compatibility-matrix-tunnels-beta). + +### Create a Tunnel + +```bash +replicated vm port expose VMID_OR_VMNAME --port PORT --protocol PROTOCOL +``` + +**Example** – Expose port 3000 with HTTP protocol +`replicated vm port expose VM_ID --port 30000 --protocol http` + +### List Tunnels + +```bash +replicated vm port ls VMID_OR_VMNAME +``` + +### Remove a Tunnel + +```bash +replicated vm port rm VMID_OR_VMNAME +``` + +## Connect a CMX VM with a CMX Cluster + +You can make a CMX Cluster available on the same network as a CMX VM. + +**Compatible Clusters:** Openshift, K3s, RKE2, EC, kURL +**Requirement:** Replicated CLI 0.90.0 or higher +**Note:** Create the cluster first, then attach the new VM to that existing network. + +### Create a Cluster + +```bash +replicated cluster create --distribution K8S_DISTRIBUTION +``` + +**Example** – `replicated cluster create --distribution k3s` + +If successful, you'll see: + +``` +ID NAME DISTRIBUTION VERSION STATUS CREATED +EXPIRES COST +b09cf035 affect_mend k3s 1.32.0 queued 2025-01-28 16:04 PST - $0.60 +``` + +### Check the Network + +```bash +replicated network ls +``` + +If successful, you'll see: + +``` +ID NAME STATUS CREATED EXPIRES +accbd6a7 affect_mend running 2025-01-28 16:04 PST 2025-01-28 17:05 PST +``` + +### Create CMX VM on Same Network + +```bash +replicated vm create --distribution DISTRIBUTION --network NETWORK_ID +``` + +**Example** – `replicated vm create --distribution ubuntu --network accbd6a7` + +If successful, you'll see: + +``` +ID NAME DISTRIBUTION VERSION STATUS CREATED EXPIRES COST +760a30b1 laughing_tu ubuntu 24.04 queued 2025-01-28 16:07 PST - $0.60 +``` + +**Example** – Both the cluster `b09cf035` and the VM `760a30b1` are now on the same tailnet. + +## Connect CMX VMs on a Shared 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 VM Network + +First, get the ID of an existing VM network: + +```bash +replicated vm ls +``` + +Or + +```bash +replicated network ls +``` + +Use the `--network` flag to create new VMs on the same network: + +```bash +replicated vm create --distribution ubuntu --network NETWORK_ID +``` \ No newline at end of file diff --git a/sidebars.js b/sidebars.js index 16a255101e..d2e94507d7 100644 --- a/sidebars.js +++ b/sidebars.js @@ -236,6 +236,7 @@ const sidebars = { items: [ 'vendor/testing-how-to', 'vendor/testing-vm-create', + 'vendor/testing-vm-networking', 'vendor/testing-ci-cd', ], }, From 93b995073a640e6992d6d35a9e0f3dd48aca0450 Mon Sep 17 00:00:00 2001 From: Han Yu Date: Wed, 30 Jul 2025 09:54:19 -0400 Subject: [PATCH 10/24] Intro note for when to use Clusters vs VMs --- docs/vendor/testing-how-to.md | 12 +++++++++++- docs/vendor/testing-vm-create.md | 2 +- 2 files changed, 12 insertions(+), 2 deletions(-) diff --git a/docs/vendor/testing-how-to.md b/docs/vendor/testing-how-to.md index c102113005..2f70bd7fec 100644 --- a/docs/vendor/testing-how-to.md +++ b/docs/vendor/testing-how-to.md @@ -2,7 +2,17 @@ import Prerequisites from "../partials/cmx/_prerequisites.mdx" # Create Clusters -This topic describes how to use Replicated Compatibility Matrix to create and manage ephemeral clusters. +This topic describes how to use Replicated Compatibility Matrix to create and manage ephemeral clusters to test your applications across different Kubernetes distributions and versions + + +## About Compatibility Matrix Clusters + +Compatibility Matrix supports both VM-based clusters (such as kind, k3s, RKE2, OpenShift, and Embedded Cluster) and cloud-managed clusters (such as EKS, GKE, and AKS). VM-based clusters run on Replicated bare metal servers, while cloud clusters are provisioned in Replicated-managed cloud accounts for faster delivery. + +**When to use Clusters vs VMs:** +* **Use Clusters** for testing Kubernetes-based deployments and Helm installations +* **Use VMs** for testing Embedded Cluster installers, air-gap installations, or when you need full OS control. For more information about creating and managing VMs, see [Create VMs](/vendor/testing-vm-create). + ## Prerequisites diff --git a/docs/vendor/testing-vm-create.md b/docs/vendor/testing-vm-create.md index 657a00f3ec..964fff085c 100644 --- a/docs/vendor/testing-vm-create.md +++ b/docs/vendor/testing-vm-create.md @@ -8,7 +8,7 @@ Compatibility Matrix VMs provide isolated Linux environments for testing your ap **When to use VMs vs Clusters:** * **Use VMs** for testing Embedded Cluster installers, air-gap installations, or when you need full OS control -* **Use Clusters** for testing Kubernetes-based deployments and Helm installations +* **Use Clusters** for testing Kubernetes-based deployments and Helm installations. For more information about creating and managing clusters, see [Create Clusters](/vendor/testing-how-to). ## Prerequisites From 6f0952f79ef46fb68707ba363d78ba1117ce5895 Mon Sep 17 00:00:00 2001 From: Han Yu Date: Thu, 31 Jul 2025 17:20:57 -0400 Subject: [PATCH 11/24] No "CMX" shorthand --- docs/vendor/testing-vm-create.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/docs/vendor/testing-vm-create.md b/docs/vendor/testing-vm-create.md index 964fff085c..f78aef6d4b 100644 --- a/docs/vendor/testing-vm-create.md +++ b/docs/vendor/testing-vm-create.md @@ -8,6 +8,7 @@ Compatibility Matrix VMs provide isolated Linux environments for testing your ap **When to use VMs vs Clusters:** * **Use VMs** for testing Embedded Cluster installers, air-gap installations, or when you need full OS control + * **Use Clusters** for testing Kubernetes-based deployments and Helm installations. For more information about creating and managing clusters, see [Create Clusters](/vendor/testing-how-to). ## Prerequisites @@ -91,19 +92,19 @@ The following VM types are supported: There are currently two supported methods to SSH into a VM: -1. [**CMX Forwarder**](#cmx-forwarder) +1. [**Compatibility Matrix Forwarder**](#compatibility-matrix-forwarder) * Easier – You only need to know the VM ID to connect to the machine via SSH. This is more approachable for users less familiar with SSH clients. * Example Use Case – Run an online Embedded Cluster install command 2. [**Direct SSH**](#direct-ssh) - * More Flexible – Leverage your SSH tool of choice and pass any client supported flags, without any added connection lag of being routed through the CMX Forwarder. + * More Flexible – Leverage your SSH tool of choice and pass any client supported flags, without any added connection lag of being routed through the Compatibility Matrix Forwarder. * Example Use Case – SCP large assets to the VM, such as air gap bundles. Pass specific SHH flags during testing workflows -### CMX Forwarder +### Compatibility Matrix Forwarder :::note -Transferring files using CMX Forwarder is slower than Direct SSH. CMX servers run on EKS, so depending on your location going through the forwarder will add latency. If you're transferring large files onto the VM, use [Direct SSH](#direct-ssh) in combination with SCP. +Transferring files using Compatibility Matrix Forwarder is slower than Direct SSH. Compatibility Matrix servers run on EKS, so depending on your location going through the forwarder will add latency. If you're transferring large files onto the VM, use [Direct SSH](#direct-ssh) in combination with SCP. ::: SSH into the VM: @@ -250,6 +251,6 @@ ssh -p DIRECT_SSH_PORT GITHUB_USERNAME@DIRECT_SSH_ENDPOINT ## Limitations - Installing Embedded Cluster is for [EC **1.21.x**](https://github.com/replicatedhq/embedded-cluster/releases/tag/1.21.0%2Bk8s-1.30) or later - - To reboot a CMX VM, run the [Embedded Cluster reset command](embedded-using#reset-a-node) + - To reboot a Compatibility Matrix VM, run the [Embedded Cluster reset command](embedded-using#reset-a-node) - [GitHub Actions](https://docs.replicated.com/vendor/testing-how-to#replicated-github-actions) do not yet work with Compatibility Matrix VMs. - [Cluster prepare](https://docs.replicated.com/reference/replicated-cli-cluster-prepare) is not yet supported with Compatibility Matrix VMs. \ No newline at end of file From 58c442474afe872cd1f556e5baef0bd6dcfd2ad7 Mon Sep 17 00:00:00 2001 From: Han Yu Date: Thu, 31 Jul 2025 18:16:23 -0400 Subject: [PATCH 12/24] Small fixes for Cluster page --- docs/vendor/testing-how-to.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/vendor/testing-how-to.md b/docs/vendor/testing-how-to.md index 2f70bd7fec..2371384115 100644 --- a/docs/vendor/testing-how-to.md +++ b/docs/vendor/testing-how-to.md @@ -10,8 +10,8 @@ This topic describes how to use Replicated Compatibility Matrix to create and ma Compatibility Matrix supports both VM-based clusters (such as kind, k3s, RKE2, OpenShift, and Embedded Cluster) and cloud-managed clusters (such as EKS, GKE, and AKS). VM-based clusters run on Replicated bare metal servers, while cloud clusters are provisioned in Replicated-managed cloud accounts for faster delivery. **When to use Clusters vs VMs:** -* **Use Clusters** for testing Kubernetes-based deployments and Helm installations -* **Use VMs** for testing Embedded Cluster installers, air-gap installations, or when you need full OS control. For more information about creating and managing VMs, see [Create VMs](/vendor/testing-vm-create). +* **Use Clusters** for testing Kubernetes-based deployments and Helm installations. +* **Use VMs** for testing Embedded Cluster installers, air-gap installations, or when you need full OS control. See [Create VMs](/vendor/testing-vm-create). ## Prerequisites @@ -45,7 +45,7 @@ To create a cluster using the Replicated CLI: 1. Run the following command to create a cluster: - ``` + ```bash replicated cluster create --name NAME --distribution K8S_DISTRO --version K8S_VERSION --disk DISK_SIZE --instance-type INSTANCE_TYPE [--license-id LICENSE_ID] ``` Where: From 503b3bbdaf70eb881ea86660428bec91a731160f Mon Sep 17 00:00:00 2001 From: Han Yu Date: Thu, 31 Jul 2025 18:16:54 -0400 Subject: [PATCH 13/24] Review VMs page --- docs/vendor/testing-vm-create.md | 61 ++++++++++++++++++++++---------- 1 file changed, 42 insertions(+), 19 deletions(-) diff --git a/docs/vendor/testing-vm-create.md b/docs/vendor/testing-vm-create.md index f78aef6d4b..d1d7d43fb0 100644 --- a/docs/vendor/testing-vm-create.md +++ b/docs/vendor/testing-vm-create.md @@ -1,3 +1,5 @@ +import Prerequisites from "../partials/cmx/_prerequisites.mdx" + # Create VMs (Beta) This topic describes how to use Replicated Compatibility Matrix to create and manage ephemeral VMs, which allows greater flexibility in testing VM-based installs such as the [Replicated Embedded Cluster](https://docs.replicated.com/intro-replicated#embedded-cluster). @@ -7,20 +9,27 @@ This topic describes how to use Replicated Compatibility Matrix to create and ma Compatibility Matrix VMs provide isolated Linux environments for testing your applications. Unlike clusters, VMs give you full control over the operating system and allow you to test installation methods that require direct OS access. **When to use VMs vs Clusters:** -* **Use VMs** for testing Embedded Cluster installers, air-gap installations, or when you need full OS control - -* **Use Clusters** for testing Kubernetes-based deployments and Helm installations. For more information about creating and managing clusters, see [Create Clusters](/vendor/testing-how-to). +* **Use VMs** for testing Embedded Cluster installers, air-gap installations, or when you need full OS control. +* **Use Clusters** for testing Kubernetes-based deployments and Helm installations. See [Create Clusters](/vendor/testing-how-to). ## Prerequisites Before you can use Compatibility Matrix VMs, you must complete the following prerequisites: -* [Configure your GitHub username in Replicated Vendor Portal](team-management-github-username#procedure) + + +* 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. + + +Prerequisites for SSH access to VMs: + +* [Configure your GitHub username or GitHub service account in Replicated Vendor Portal](team-management-github-username#procedure) * Make sure you have added your SSH key in your GitHub account. For instructions, see [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. :::note -GitHub usernames and SSH keys are synced every 24hrs. To immediately sync: → [Account Settings](https://vendor.replicated.com/account-settings) > click Save. Keys are synced to the VM at time of creation, so any updates after creation are ignored. +Troubleshooting +Your GitHub usernames and SSH keys are synced to the VM when you first create it. If you update your GitHub username or keys after VM creation, you can manually sync by going to [Account Settings](https://vendor.replicated.com/account-settings) > click "Save." ::: ## Set Up SSH Access @@ -37,7 +46,19 @@ If successful, you will see: You have successfully authenticated, use [VM_ID]@replicatedvm.com to access your VM. ``` -If you do not see this message, your public/private key likely was not available. +If you do not see this message, check if your public/private key has been 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. +``` + + ### Alternative: Use a Service GitHub Account @@ -57,27 +78,29 @@ replicated vm create --distribution ubuntu --version 20.04 --ssh-public-key ~/.s To create VMs with Compatibility Matrix: -1. Run the following command to create VMs: + +1. (Optional) View the available VM distributions, including the supported VM distribution versions and instance types: ```bash - replicated vm create --distribution DISTRIBUTION --count COUNT + replicated vm versions ``` + For command usage, see [vm versions](/reference/replicated-cli-vm-versions). - Where: - * `DISTRIBUTION` is the Linux distribution for the VM (e.g., ubuntu, almalinux) - * `COUNT` is the number of VMs to create - **Example:** - ```bash - replicated vm create --distribution ubuntu --count 3 - ``` +2. Run the following command to create VMs: + +```bash +replicated vm create --distribution DISTRIBUTION --count COUNT +``` -1. List supported distributions and versions: +Where: +* `DISTRIBUTION` is the Linux distribution for the VM (e.g., ubuntu, almalinux). +* `COUNT` is the number of VMs to create + + +replicated vm versions - ```bash - replicated vm versions - ``` ### Supported VM Types From fc03b4af5e4fc1166ae30ae28b183d122d38ebc2 Mon Sep 17 00:00:00 2001 From: Han Yu Date: Thu, 31 Jul 2025 18:28:41 -0400 Subject: [PATCH 14/24] Review Cluster and VM create info --- docs/vendor/testing-how-to.md | 7 +++++++ docs/vendor/testing-vm-create.md | 35 ++++++++++++++++++++++++-------- 2 files changed, 34 insertions(+), 8 deletions(-) diff --git a/docs/vendor/testing-how-to.md b/docs/vendor/testing-how-to.md index 2371384115..7b63b31629 100644 --- a/docs/vendor/testing-how-to.md +++ b/docs/vendor/testing-how-to.md @@ -45,6 +45,13 @@ To create a cluster using the Replicated CLI: 1. Run the following command to create a cluster: + + ```bash + replicated cluster create --distribution DISTRIBUTION + ``` + + To specify more options: + ```bash replicated cluster create --name NAME --distribution K8S_DISTRO --version K8S_VERSION --disk DISK_SIZE --instance-type INSTANCE_TYPE [--license-id LICENSE_ID] ``` diff --git a/docs/vendor/testing-vm-create.md b/docs/vendor/testing-vm-create.md index d1d7d43fb0..5e13cdd40f 100644 --- a/docs/vendor/testing-vm-create.md +++ b/docs/vendor/testing-vm-create.md @@ -88,18 +88,37 @@ To create VMs with Compatibility Matrix: -2. Run the following command to create VMs: +2. Run the following command to create a VM: -```bash -replicated vm create --distribution DISTRIBUTION --count COUNT -``` + ```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 cluster. + * `DISTRIBUTION` is the operating system distribution for the VM (e.g., ubuntu, almalinux). + * `VERSION` is the version of the distribution to provision (e.g., 20.04, 22.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). -Where: -* `DISTRIBUTION` is the Linux distribution for the VM (e.g., ubuntu, almalinux). -* `COUNT` is the number of VMs to 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 + ``` -replicated vm versions ### Supported VM Types From 4984433bf46545bc09a52f83376b549420ff3112 Mon Sep 17 00:00:00 2001 From: Han Yu Date: Thu, 31 Jul 2025 18:43:35 -0400 Subject: [PATCH 15/24] Read through VM doc --- docs/vendor/testing-vm-create.md | 40 ++++++++++++++++++++------------ 1 file changed, 25 insertions(+), 15 deletions(-) diff --git a/docs/vendor/testing-vm-create.md b/docs/vendor/testing-vm-create.md index 5e13cdd40f..8716a4db55 100644 --- a/docs/vendor/testing-vm-create.md +++ b/docs/vendor/testing-vm-create.md @@ -135,12 +135,12 @@ The following VM types are supported: There are currently two supported methods to SSH into a VM: 1. [**Compatibility Matrix Forwarder**](#compatibility-matrix-forwarder) - * Easier – You only need to know the VM ID to connect to the machine via SSH. This is more approachable for users less familiar with SSH clients. - * Example Use Case – Run an online Embedded Cluster install command + * **Easier** – You only need to know the VM ID to connect to the machine via SSH. This is more approachable for users less familiar with SSH clients. + * **Example Use Case** – Run an online Embedded Cluster install command 2. [**Direct SSH**](#direct-ssh) - * More Flexible – Leverage your SSH tool of choice and pass any client supported flags, without any added connection lag of being routed through the Compatibility Matrix Forwarder. - * Example Use Case – SCP large assets to the VM, such as air gap bundles. + * **More Flexible** – Leverage your SSH tool of choice and pass any client supported flags, without any added connection lag of being routed through the Compatibility Matrix Forwarder. + * **Example Use Case** – SCP large assets to the VM, such as air gap bundles. Pass specific SHH flags during testing workflows ### Compatibility Matrix Forwarder @@ -155,7 +155,7 @@ SSH into the VM: ssh VMID@replicatedvm.com ``` -Where `VMID` is the ID of the VM. +- Where `VMID` is the ID of the VM. If needed, copy files onto the machine: @@ -163,27 +163,33 @@ If needed, copy files onto the machine: scp somefile VMID@replicatedvm:/home/folder/somefile ``` -Where `VMID` is the ID of the VM. +- Where `VMID` is the ID of the VM. :::note -**Beta Limitations:** scp with flag -O (legacy scp protocol) is not supported. Relative paths is not supported `❌ scp somefile VMID@replicatedvm.com:~ ✅ scp somefile VMID@replicatedvm:/home/folder/somefile` File permissions are not inherited. +**Beta Limitations:** +- `scp` with flag `-O` (legacy scp protocol) is not supported. +- Relative paths is not supported + - Unsupported: `scp somefile VMID@replicatedvm.com:~` + - Supported: `scp somefile VMID@replicatedvm:/home/folder/somefile` +- File permissions are not inherited. ::: ### Direct SSH +Transferring files using Direct SSH allows you to use your SSH tool of choice, and pass any client-supported flags. + + :::note -Transferring files using Direct SSH allows you to use your SSH tool of choice, and pass any client-supported flags. Note: Requires Replicated CLI v0.104.0 or later. +Requires Replicated CLI v0.104.0 or later. ::: -Get the SSH endpoint for the VM: - -1. Run the following command to get the SSH endpoint: +1. Get the SSH endpoint for the VM: ```bash replicated vm ssh-endpoint VMID_OR_VMNAME ``` - Where `VMID_OR_VMNAME` is the ID or name of the VM. + - Where `VMID_OR_VMNAME` is the ID or name of the VM. Run `replicated vm ls` If successful, you'll see: @@ -191,9 +197,11 @@ Get the SSH endpoint for the VM: ssh://[github-user-name]@[ssh-endpoint]:[port] ``` - **Example** – `ssh://MyName@37.27.52.116:46795` + - **Example** – `ssh://MyName@37.27.52.116:46795` - ⚠️ The username for SSH should match the GitHub username in Vendor Portal. For more information about overriding the username, see [Override Username](#override-username). + :::note + Make sure the username for SSH matches the GitHub username in Vendor Portal. For more information about overriding the username, see [Override Username](#override-username). + ::: 1. SSH into the VM: @@ -225,7 +233,9 @@ Request the scp endpoint: **Example** – `scp://MyName@37.27.52.116:46795` - ⚠️ The username for SSH should match the GitHub username in Vendor Portal. For more information about overriding the username, see [Override Username](#override-username). +:::note +Make sure the username for SSH matches the GitHub username in Vendor Portal. For more information about overriding the username, see [Override Username](#override-username). +::: 1. SCP files into the VM: From a32257b6e06aa7991e981c656c3f4e08393058f5 Mon Sep 17 00:00:00 2001 From: Han Yu Date: Thu, 31 Jul 2025 18:56:13 -0400 Subject: [PATCH 16/24] Fewer notes --- docs/vendor/testing-vm-create.md | 16 ++-------------- 1 file changed, 2 insertions(+), 14 deletions(-) diff --git a/docs/vendor/testing-vm-create.md b/docs/vendor/testing-vm-create.md index 8716a4db55..724e2edf1e 100644 --- a/docs/vendor/testing-vm-create.md +++ b/docs/vendor/testing-vm-create.md @@ -28,8 +28,7 @@ Prerequisites for SSH access to VMs: * Make sure you have added your SSH key in your GitHub account. For instructions, see [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. :::note -Troubleshooting -Your GitHub usernames and SSH keys are synced to the VM when you first create it. If you update your GitHub username or keys after VM creation, you can manually sync by going to [Account Settings](https://vendor.replicated.com/account-settings) > click "Save." +Your GitHub usernames and SSH keys are synced to the VM when you first create it. If you update your GitHub username or keys after VM creation, you can manually sync by going to [Account Settings](https://vendor.replicated.com/account-settings) > click "Save." ::: ## Set Up SSH Access @@ -145,9 +144,7 @@ There are currently two supported methods to SSH into a VM: ### Compatibility Matrix Forwarder -:::note Transferring files using Compatibility Matrix Forwarder is slower than Direct SSH. Compatibility Matrix servers run on EKS, so depending on your location going through the forwarder will add latency. If you're transferring large files onto the VM, use [Direct SSH](#direct-ssh) in combination with SCP. -::: SSH into the VM: @@ -176,12 +173,7 @@ scp somefile VMID@replicatedvm:/home/folder/somefile ### Direct SSH -Transferring files using Direct SSH allows you to use your SSH tool of choice, and pass any client-supported flags. - - -:::note -Requires Replicated CLI v0.104.0 or later. -::: +Transferring files using Direct SSH allows you to use your SSH tool of choice, and pass any client-supported flags. Requires Replicated CLI v0.104.0 or later. 1. Get the SSH endpoint for the VM: @@ -199,9 +191,7 @@ Requires Replicated CLI v0.104.0 or later. - **Example** – `ssh://MyName@37.27.52.116:46795` - :::note Make sure the username for SSH matches the GitHub username in Vendor Portal. For more information about overriding the username, see [Override Username](#override-username). - ::: 1. SSH into the VM: @@ -233,9 +223,7 @@ Request the scp endpoint: **Example** – `scp://MyName@37.27.52.116:46795` -:::note Make sure the username for SSH matches the GitHub username in Vendor Portal. For more information about overriding the username, see [Override Username](#override-username). -::: 1. SCP files into the VM: From 1ad3a853ba500ed0f09a92d0db51df4b9c562c35 Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Fri, 1 Aug 2025 13:14:14 -0600 Subject: [PATCH 17/24] edits --- docs/vendor/testing-how-to.md | 33 ++- docs/vendor/testing-vm-create.md | 342 ++++++++++++++++----------- docs/vendor/testing-vm-networking.md | 12 +- 3 files changed, 229 insertions(+), 158 deletions(-) diff --git a/docs/vendor/testing-how-to.md b/docs/vendor/testing-how-to.md index 7b63b31629..855d001472 100644 --- a/docs/vendor/testing-how-to.md +++ b/docs/vendor/testing-how-to.md @@ -2,17 +2,17 @@ import Prerequisites from "../partials/cmx/_prerequisites.mdx" # Create Clusters -This topic describes how to use Replicated Compatibility Matrix to create and manage ephemeral clusters to test your applications across different Kubernetes distributions and versions +This topic describes how to use Replicated Compatibility Matrix to create and manage ephemeral clusters to test your applications across different Kubernetes distributions and versions. +This topic includes information about creating and managing clusters with Compatibility Matrix using the Replicated Vendor Portal or the Replicated CLI. For information about creating and managing clusters with the Vendor API v3, see the [clusters](https://replicated-vendor-api.readme.io/reference/listclusterusage) section in the Vendor API v3 documentation. ## About Compatibility Matrix Clusters Compatibility Matrix supports both VM-based clusters (such as kind, k3s, RKE2, OpenShift, and Embedded Cluster) and cloud-managed clusters (such as EKS, GKE, and AKS). VM-based clusters run on Replicated bare metal servers, while cloud clusters are provisioned in Replicated-managed cloud accounts for faster delivery. -**When to use Clusters vs VMs:** -* **Use Clusters** for testing Kubernetes-based deployments and Helm installations. -* **Use VMs** for testing Embedded Cluster installers, air-gap installations, or when you need full OS control. See [Create VMs](/vendor/testing-vm-create). +You can use Compatibility Matrix clusters for testing and troubleshooting Kubernetes-based deployments and Helm installations for your application. +For information about creating VMs with Compatibility Matrix to test Replicated Embedded Cluster installers, air-gap installations, or when you need full OS control, see [Create VMs](/vendor/testing-vm-create). ## Prerequisites @@ -22,17 +22,11 @@ Before you can use Compatibility Matrix clusters, you must complete the followin * 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. -## Create and Manage Clusters - -This section explains how to use Compatibility Matrix to create and manage clusters with the Replicated CLI or the Vendor Portal. - -For information about creating and managing clusters with the Vendor API v3, see the [clusters](https://replicated-vendor-api.readme.io/reference/listclusterusage) section in the Vendor API v3 documentation. - -### Create Clusters +## Create Clusters You can create clusters with Compatibility Matrix using the Replicated CLI or the Vendor Portal. -#### Replicated CLI +### With the Replicated CLI To create a cluster using the Replicated CLI: @@ -84,7 +78,7 @@ To create a cluster using the Replicated CLI: In the output of the command, you can see that the `STATUS` of the cluster is `assigned`. When the kubeconfig for the cluster is accessible, the cluster's status is changed to `running`. For more information about cluster statuses, see [Cluster Status](testing-about#cluster-status) in _About Compatibility Matrix._ -#### Vendor Portal +### Vendor Portal To create a cluster using the Vendor Portal: @@ -154,7 +148,7 @@ To create a cluster using the Vendor Portal: [View a larger version of this image](/images/cmx-assigned-cluster.png) -### Prepare Clusters +## 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). @@ -213,7 +207,7 @@ The `cluster prepare` command requires either a Helm chart archive or a director For command usage, including additional options, see [cluster prepare](/reference/replicated-cli-cluster-prepare). -### Access Clusters +## Access Clusters Compatibility Matrix provides the kubeconfig for clusters so that you can access clusters with the kubectl command line tool. For more information, see [Command line tool (kubectl)](https://kubernetes.io/docs/reference/kubectl/) in the Kubernetes documentation. @@ -243,7 +237,7 @@ To access a cluster from the command line: 1. Press Ctrl-D or type `exit` when done to end the shell and the connection to the server. -### Upgrade Clusters (kURL Only) +## Upgrade Clusters (kURL Only) For kURL clusters provisioned with Compatibility Matrix, you can use the the `cluster upgrade` command to upgrade the version of the kURL installer specification used to provision the cluster. A recommended use case for the `cluster upgrade` command is for testing your application's compatibility with Kubernetes API resource version migrations after upgrade. @@ -255,11 +249,11 @@ replicated cluster upgrade cabb74d5 --version 9d5a44c For command usage, see [cluster upgrade](/reference/replicated-cli-cluster-upgrade). -### Delete Clusters +## Delete Clusters You can delete clusters using the Replicated CLI or the Vendor Portal. -#### Replicated CLI +### Replicated CLI To delete a cluster using the Replicated CLI: @@ -292,7 +286,8 @@ To delete a cluster using the Replicated CLI: ``` 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 + +### Vendor Portal To delete a cluster using the Vendor Portal: diff --git a/docs/vendor/testing-vm-create.md b/docs/vendor/testing-vm-create.md index 724e2edf1e..4d2c380d64 100644 --- a/docs/vendor/testing-vm-create.md +++ b/docs/vendor/testing-vm-create.md @@ -2,15 +2,33 @@ import Prerequisites from "../partials/cmx/_prerequisites.mdx" # Create VMs (Beta) -This topic describes how to use Replicated Compatibility Matrix to create and manage ephemeral VMs, which allows greater flexibility in testing VM-based installs such as the [Replicated Embedded Cluster](https://docs.replicated.com/intro-replicated#embedded-cluster). +This topic describes how to use Replicated Compatibility Matrix to create and manage ephemeral VMs. ## About Compatibility Matrix VMs -Compatibility Matrix VMs provide isolated Linux environments for testing your applications. Unlike clusters, VMs give you full control over the operating system and allow you to test installation methods that require direct OS access. +Compatibility Matrix 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. -**When to use VMs vs Clusters:** -* **Use VMs** for testing Embedded Cluster installers, air-gap installations, or when you need full OS control. -* **Use Clusters** for testing Kubernetes-based deployments and Helm installations. See [Create Clusters](/vendor/testing-how-to). +You can use Compatibility Matrix 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 Compatibility Matrix to test Kubernetes-based deployments and Helm installations, see [Create Clusters](/vendor/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 | +| almalinux | 8 | r1.small, r1.medium, r1.large, r1.xlarge, r1.2xlarge | + +## Limitations + +Creating VMs with Compatibility Matrix has the following limitations: + +- Creating VMs with Compatibility Matrix is a Beta feature. +- Installing Embedded Cluster on a VM created with Compatibility Matrix is supported for Embedded Cluster versions 1.21.0 or later. +- [GitHub Actions](/vendor/testing-how-to#replicated-github-actions) are not supported for Compatibility Matrix VMs. +- The [cluster prepare](/reference/replicated-cli-cluster-prepare) command is not supported for Compatibility Matrix VMs. ## Prerequisites @@ -20,48 +38,64 @@ Before you can use Compatibility Matrix VMs, you must complete the following pre * 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 -Prerequisites for SSH access to VMs: - -* [Configure your GitHub username or GitHub service account in Replicated Vendor Portal](team-management-github-username#procedure) +In order to access VMs that you create with Compatibility Matrix, you need to set up SSH access. You can do this using your personal GitHub account or a GitHub service account used by your team. -* Make sure you have added your SSH key in your GitHub account. For instructions, see [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. +For setting up SSH access to VMs that you create on your local machine, Replicated recommends that you use your personal GitHub account. For setting up SSH access for VMs created in CI/CD workflows used by your team, use a GitHub service account. For more information, see the sections below. :::note -Your GitHub usernames and SSH keys are synced to the VM when you first create it. If you update your GitHub username or keys after VM creation, you can manually sync by going to [Account Settings](https://vendor.replicated.com/account-settings) > click "Save." +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**. ::: -## Set Up SSH Access +### Use Your GitHub Account -After completing the prerequisites, verify your SSH access is working: +To set up and verify SSH access for Compatibility Matrix VMs using your personal GitHub account: -```bash -ssh -T replicated@replicatedvm.com -``` +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. -If successful, you will see: +1. Run the following command to verify that your public/private SSH key is properly set up with GitHub. -``` -You have successfully authenticated, use [VM_ID]@replicatedvm.com to access your VM. -``` + ```bash + ssh -T git@github.com + ``` -If you do not see this message, check if your public/private key has been properly set up with GitHub. + If successful, you will see: -```bash -ssh -T git@github.com -``` + ``` + Hi ! You've successfully authenticated, but GitHub does not provide shell access. + ``` -If successful, you will see: +1. Log in to the Vendor Portal and go to [**Account Settings**](https://vendor.replicated.com/account-settings/info). -``` -Hi! You've successfully authenticated, but GitHub does not provide shell access. -``` +1. On the **Account Settings > Account Information** page, for **GitHub username**, add your GitHub username. + +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 + ``` +1. For the prompt `Are you sure you want to continue connecting (yes/no/[fingerprint])?`, type `yes` and press Enter. + If successful, you will see a message similar to the following: -### Alternative: Use a Service GitHub Account + ``` + You have successfully authenticated, use @replicatedvm.com to access your VM. + ``` -To automate VMs in your CI, or otherwise avoid using a personal GitHub account, use the flag `--ssh-public-key` when you first create a VM: +### Use a Service Account + +To automate the creation of VMs in your CI/CD workflows, you can use the flag `--ssh-public-key` when you first create a VM, where you provide the SSH public key for a GitHub service account connected to the Vendor Portal. For example: ```bash replicated vm create --distribution ubuntu --version 20.04 --ssh-public-key ~/.ssh/id_rsa.pub @@ -77,7 +111,6 @@ replicated vm create --distribution ubuntu --version 20.04 --ssh-public-key ~/.s To create VMs with Compatibility Matrix: - 1. (Optional) View the available VM distributions, including the supported VM distribution versions and instance types: ```bash @@ -86,8 +119,7 @@ To create VMs with Compatibility Matrix: For command usage, see [vm versions](/reference/replicated-cli-vm-versions). - -2. Run the following command to create a VM: +1. Run the following command to create a VM: ```bash replicated vm create --distribution DISTRIBUTION @@ -118,139 +150,93 @@ To create VMs with Compatibility Matrix: replicated vm create --distribution ubuntu --version 22.04 --disk 50 --instance-type r1.medium ``` - - -### 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 | -| almalinux | 8 | r1.small, r1.medium, r1.large, r1.xlarge, r1.2xlarge | - ## Connect to a VM -There are currently two supported methods to SSH into a VM: - -1. [**Compatibility Matrix Forwarder**](#compatibility-matrix-forwarder) - * **Easier** – You only need to know the VM ID to connect to the machine via SSH. This is more approachable for users less familiar with SSH clients. - * **Example Use Case** – Run an online Embedded Cluster install command - -2. [**Direct SSH**](#direct-ssh) - * **More Flexible** – Leverage your SSH tool of choice and pass any client supported flags, without any added connection lag of being routed through the Compatibility Matrix Forwarder. - * **Example Use Case** – SCP large assets to the VM, such as air gap bundles. - Pass specific SHH flags during testing workflows - -### Compatibility Matrix Forwarder - -Transferring files using Compatibility Matrix Forwarder is slower than Direct SSH. Compatibility Matrix servers run on EKS, so depending on your location going through the forwarder will add latency. If you're transferring large files onto the VM, use [Direct SSH](#direct-ssh) in combination with SCP. - -SSH into the VM: - -```bash -ssh VMID@replicatedvm.com -``` +You can SSH into a VM using one of the following methods: -- Where `VMID` is the ID of the VM. +* [**Compatibility Matrix Forwarder**](#compatibility-matrix-forwarder): To use the Compatibility Matrix 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. One example use case for the Forwarder is to run an online Embedded Cluster install command. -If needed, copy files onto the machine: +* [**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 Compatibility Matrix 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. -```bash -scp somefile VMID@replicatedvm:/home/folder/somefile -``` +* [**Connect to a VM Manually**](#connect-to-a-vm-manually): If the above options are not supported with your preferred SSH client, you can connect to a VM manually. -- Where `VMID` is the ID of the VM. +### Compatibility Matrix Forwarder :::note -**Beta Limitations:** -- `scp` with flag `-O` (legacy scp protocol) is not supported. -- Relative paths is not supported - - Unsupported: `scp somefile VMID@replicatedvm.com:~` - - Supported: `scp somefile VMID@replicatedvm:/home/folder/somefile` -- File permissions are not inherited. +Transferring files using Compatibility Matrix Forwarder is slower than using direct SSH. Compatibility Matrix servers run on EKS, so depending on your location, using the Forwarder adds latency. If you want to transfer large files such as air gap bundles onto the VM, use [Direct SSH](#direct-ssh) in combination with SCP. ::: -### Direct SSH - -Transferring files using Direct SSH allows you to use your SSH tool of choice, and pass any client-supported flags. Requires Replicated CLI v0.104.0 or later. +To connect to a VM using the Forwarder: -1. Get the SSH endpoint for the VM: +* SSH into the VM: ```bash - replicated vm ssh-endpoint VMID_OR_VMNAME + ssh VMID@replicatedvm.com ``` - - Where `VMID_OR_VMNAME` is the ID or name of the VM. Run `replicated vm ls` - - If successful, you'll see: - - ``` - ssh://[github-user-name]@[ssh-endpoint]:[port] - ``` + Where `VMID` is the ID of the VM. - - **Example** – `ssh://MyName@37.27.52.116:46795` +### Direct SSH - Make sure the username for SSH matches the GitHub username in Vendor Portal. For more information about overriding the username, see [Override Username](#override-username). +Transferring files using Direct SSH allows you to use your SSH tool of choice, and pass any client-supported flags. Direct SSH requires Replicated CLI v0.104.0 or later. -1. SSH into the VM: +1. Get the SSH endpoint for the VM: ```bash - ssh $(replicated vm ssh-endpoint VMID_OR_VMNAME) + replicated vm ssh-endpoint VMID_OR_VMNAME [--username GITHUB_USERNAME] ``` - **Example** – `ssh $(replicated vm ssh-endpoint aba1acc2)` - -### Copy Files to the VM (SCP) - -Request the scp endpoint: + 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 -1. Run the following command to get the SCP endpoint: + **Example:** ```bash - replicated vm scp-endpoint VMID_OR_VMNAME + replicated vm ssh-endpoint aba1acc2 ``` - Where `VMID_OR_VMNAME` is the ID or name of the VM. - - **Example** – `replicated vm scp-endpoint aba1acc2` - - If successful, you'll see: + The output of the command displays the SSH endpoint that you can use to connect to the VM: ``` - scp://[github-user-name]@[ssh-endpoint]:[port] + ssh://[github-user-name]@[ssh-endpoint]:[port] ``` + For example, `ssh://yourusername@37.27.52.116:46795`. - **Example** – `scp://MyName@37.27.52.116:46795` +1. Copy the SSH endpoint. -Make sure the username for SSH matches the GitHub username in Vendor Portal. For more information about overriding the username, see [Override Username](#override-username). - -1. SCP files into the VM: +1. SSH into the VM using the SSH endpoint that you copied: ```bash - scp somefile $(replicated vm scp-endpoint VMID_OR_VMNAME)//PATH + 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. - Where `PATH` is the destination path on the VM. - -### Override Username - -You can override the username used for the endpoint with the `--username` flag. This is useful if you want to: + **Example:** -* Use a different GitHub username than what is in Vendor Portal (or no username set) -* 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 + ```bash + ssh ssh://yourusername@37.27.52.116:46795 + ``` -```bash -replicated vm ssh-endpoint VMID_OR_VMNAME --username GITHUB_USER_NAME -``` + 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** – `replicated vm ssh-endpoint aba1acc2 --username MyName` + **Example** + + ``` + ssh $(replicated vm ssh-endpoint aba1acc2) + ``` -## Connect to a VM Manually +### Connect to a VM Manually -You may need an alternate method if the above options don't work with your preferred SSH client. +If the Forwarder or direct SSH do not work with your preferred SSH client, you can connect manually. When a VM is created, a random port is assigned to each machine within each group of the VM. -When a VM is created, a random port is assigned to each machine within each group of the VM. To connect with the machine over SSH: +To connect with the machine over SSH: ```bash replicated vm ls --output json @@ -280,17 +266,107 @@ If successful, you'll see: ] ``` -To connect with them, you can run: +1. Run the following command to connect: -```bash -ssh -p DIRECT_SSH_PORT GITHUB_USERNAME@DIRECT_SSH_ENDPOINT -``` + ```bash + ssh -p DIRECT_SSH_PORT GITHUB_USERNAME@DIRECT_SSH_ENDPOINT + ``` -**Example** – `ssh -p 33655 myName@95.217.47.21` + **Example:** + + ```bash + ssh -p 33655 myName@95.217.47.21 + ``` -## Limitations +## Copy Files to a VM + +You can copy files to a VM either using an SCP endpoint, or by using SCP after connecting to the VM with the Compatibility Matrix Forwarder. + +### 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 + +You can also copy files with SCP after connecting to the VM using the Compatibility Matrix Forwarder. + +:::note +**Beta 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 Compatibility Matrix 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 + ``` + +## Reboot a VM -- Installing Embedded Cluster is for [EC **1.21.x**](https://github.com/replicatedhq/embedded-cluster/releases/tag/1.21.0%2Bk8s-1.30) or later - - To reboot a Compatibility Matrix VM, run the [Embedded Cluster reset command](embedded-using#reset-a-node) -- [GitHub Actions](https://docs.replicated.com/vendor/testing-how-to#replicated-github-actions) do not yet work with Compatibility Matrix VMs. -- [Cluster prepare](https://docs.replicated.com/reference/replicated-cli-cluster-prepare) is not yet supported with Compatibility Matrix VMs. \ No newline at end of file +To reboot a Compatibility Matrix VM, you can run the Embedded Cluster [reset](embedded-using#reset-a-node) command. \ No newline at end of file diff --git a/docs/vendor/testing-vm-networking.md b/docs/vendor/testing-vm-networking.md index 645a7d7b89..530507274a 100644 --- a/docs/vendor/testing-vm-networking.md +++ b/docs/vendor/testing-vm-networking.md @@ -2,11 +2,11 @@ This topic describes advanced networking features for Replicated Compatibility Matrix VMs, including port exposure, VM-to-cluster connections, and shared networks. -## Compatibility Matrix Tunnels +## Limitations + +Creating wildcard DNS entries for VMs is not supported. For feedback, contact Replicated support. -:::note -Creating wildcard DNS entries for VMs is not currently supported. For feedback, contact Replicated support. -::: +## Compatibility Matrix Tunnels You can expose ports on a VM and make them accessible on the public internet. For more information about a similar feature, see [Compatibility Matrix Tunnels for Clusters](testing-ingress#compatibility-matrix-tunnels-beta). @@ -31,9 +31,9 @@ replicated vm port ls VMID_OR_VMNAME replicated vm port rm VMID_OR_VMNAME ``` -## Connect a CMX VM with a CMX Cluster +## Connect a Compatibility Matrix VM with a Compatibility Matrix Cluster -You can make a CMX Cluster available on the same network as a CMX VM. +You can make a Compatibility Matrix Cluster available on the same network as a CMX VM. **Compatible Clusters:** Openshift, K3s, RKE2, EC, kURL **Requirement:** Replicated CLI 0.90.0 or higher From 45a672586df8866437f3fe43894a81ebe362a2c6 Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Fri, 1 Aug 2025 13:24:04 -0600 Subject: [PATCH 18/24] edits --- docs/vendor/testing-vm-create.md | 68 ++++++++++++++++---------------- 1 file changed, 34 insertions(+), 34 deletions(-) diff --git a/docs/vendor/testing-vm-create.md b/docs/vendor/testing-vm-create.md index 4d2c380d64..356642689b 100644 --- a/docs/vendor/testing-vm-create.md +++ b/docs/vendor/testing-vm-create.md @@ -26,7 +26,7 @@ The following VM types are supported: Creating VMs with Compatibility Matrix has the following limitations: - Creating VMs with Compatibility Matrix is a Beta feature. -- Installing Embedded Cluster on a VM created with Compatibility Matrix is supported for Embedded Cluster versions 1.21.0 or later. +- Installing Embedded Cluster on a VM created with Compatibility Matrix is supported for Embedded Cluster versions 1.21.0 or later. To reboot a Compatibility Matrix VM, you can run the Embedded Cluster [reset](embedded-using#reset-a-node) command. - [GitHub Actions](/vendor/testing-how-to#replicated-github-actions) are not supported for Compatibility Matrix VMs. - The [cluster prepare](/reference/replicated-cli-cluster-prepare) command is not supported for Compatibility Matrix VMs. @@ -95,7 +95,7 @@ To set up and verify SSH access for Compatibility Matrix VMs using your personal ### Use a Service Account -To automate the creation of VMs in your CI/CD workflows, you can use the flag `--ssh-public-key` when you first create a VM, where you provide the SSH public key for a GitHub service account connected to the Vendor Portal. For example: +To automate the creation of VMs in your CI/CD workflows, you can use the flag `--ssh-public-key` to provide the SSH public key for a GitHub service account. For example: ```bash replicated vm create --distribution ubuntu --version 20.04 --ssh-public-key ~/.ssh/id_rsa.pub @@ -154,12 +154,14 @@ To create VMs with Compatibility Matrix: You can SSH into a VM using one of the following methods: -* [**Compatibility Matrix Forwarder**](#compatibility-matrix-forwarder): To use the Compatibility Matrix 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. One example use case for the Forwarder is to run an online Embedded Cluster install command. +* [**Compatibility Matrix Forwarder**](#compatibility-matrix-forwarder): To use the Compatibility Matrix 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 Compatibility Matrix 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. * [**Connect to a VM Manually**](#connect-to-a-vm-manually): If the above options are not supported with your preferred SSH client, you can connect to a VM manually. +For information about how to copy files to a VM after connecting, see [Copy Files to a VM](#copy-files-to-a-vm) below. + ### Compatibility Matrix Forwarder :::note @@ -238,33 +240,35 @@ If the Forwarder or direct SSH do not work with your preferred SSH client, you c To connect with the machine over SSH: -```bash -replicated vm ls --output json -``` +1. Run the following command: -If successful, you'll see: - -```json -[ - { - "id": "e32aafa1", - "name": "sad_black", - "distribution": "ubuntu", - "version": "24.04", - "status": "running", - "created_at": "2024-10-24T15:00:37Z", - "expires_at": "2024-10-24T16:01:10Z", - "ttl": "1h", - "credits_per_hour_per_vm": 0, - "flat_fee": 50000, - "total_credits": 0, - "estimated_cost": 0, - "direct_ssh_port": 33655, - "direct_ssh_endpoint": "95.217.47.21", - "tags": [] - } -] -``` + ```bash + replicated vm ls --output json + ``` + + The following shows an example of the output of this command: + + ```json + [ + { + "id": "e32aafa1", + "name": "sad_black", + "distribution": "ubuntu", + "version": "24.04", + "status": "running", + "created_at": "2024-10-24T15:00:37Z", + "expires_at": "2024-10-24T16:01:10Z", + "ttl": "1h", + "credits_per_hour_per_vm": 0, + "flat_fee": 50000, + "total_credits": 0, + "estimated_cost": 0, + "direct_ssh_port": 33655, + "direct_ssh_endpoint": "95.217.47.21", + "tags": [] + } + ] + ``` 1. Run the following command to connect: @@ -365,8 +369,4 @@ To copy files to the VM using SCP after connecting with the Compatibility Matrix ```bash scp somefile 123abc@replicatedvm:/home/folder/somefile - ``` - -## Reboot a VM - -To reboot a Compatibility Matrix VM, you can run the Embedded Cluster [reset](embedded-using#reset-a-node) command. \ No newline at end of file + ``` \ No newline at end of file From 414808bdb317c48ba2e3c2f3f9d524cc8ac31d04 Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Fri, 1 Aug 2025 13:36:34 -0600 Subject: [PATCH 19/24] edits --- docs/vendor/testing-vm-create.md | 15 +++--- docs/vendor/testing-vm-networking.md | 81 +++++++++++++++------------- 2 files changed, 50 insertions(+), 46 deletions(-) diff --git a/docs/vendor/testing-vm-create.md b/docs/vendor/testing-vm-create.md index 356642689b..2b6e440e99 100644 --- a/docs/vendor/testing-vm-create.md +++ b/docs/vendor/testing-vm-create.md @@ -164,10 +164,6 @@ For information about how to copy files to a VM after connecting, see [Copy File ### Compatibility Matrix Forwarder -:::note -Transferring files using Compatibility Matrix Forwarder is slower than using direct SSH. Compatibility Matrix servers run on EKS, so depending on your location, using the Forwarder adds latency. If you want to transfer large files such as air gap bundles onto the VM, use [Direct SSH](#direct-ssh) in combination with SCP. -::: - To connect to a VM using the Forwarder: * SSH into the VM: @@ -178,6 +174,8 @@ To connect to a VM using the Forwarder: Where `VMID` is the ID of the VM. +For information about copying files to the VM after connecting, see [After Connecting to the VM with the Forwarder](#after-connecting-to-the-vm-with-the-forwarder) below. + ### Direct SSH Transferring files using Direct SSH allows you to use your SSH tool of choice, and pass any client-supported flags. Direct SSH requires Replicated CLI v0.104.0 or later. @@ -334,16 +332,17 @@ To copy files to a VM using the scp endpoint: ### After Connecting to the VM with the Forwarder -You can also copy files with SCP after connecting to the VM using the Compatibility Matrix Forwarder. - :::note -**Beta Limitations:** +Transferring files using Compatibility Matrix Forwarder is slower than using direct SSH. Compatibility Matrix servers run on EKS, so depending on your location, using the Forwarder adds 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 Compatibility Matrix 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 Compatibility Matrix Forwarder: diff --git a/docs/vendor/testing-vm-networking.md b/docs/vendor/testing-vm-networking.md index 530507274a..cf3757a616 100644 --- a/docs/vendor/testing-vm-networking.md +++ b/docs/vendor/testing-vm-networking.md @@ -16,8 +16,10 @@ You can expose ports on a VM and make them accessible on the public internet. Fo replicated vm port expose VMID_OR_VMNAME --port PORT --protocol PROTOCOL ``` -**Example** – Expose port 3000 with HTTP protocol -`replicated vm port expose VM_ID --port 30000 --protocol http` +For example, to expose port 3000 with HTTP protocol: +```bash +replicated vm port expose VM_ID --port 30000 --protocol http +``` ### List Tunnels @@ -33,59 +35,62 @@ replicated vm port rm VMID_OR_VMNAME ## Connect a Compatibility Matrix VM with a Compatibility Matrix Cluster -You can make a Compatibility Matrix Cluster available on the same network as a CMX VM. +You can make a Compatibility Matrix cluster available on the same network as a Compatibility Matrix VM. -**Compatible Clusters:** Openshift, K3s, RKE2, EC, kURL -**Requirement:** Replicated CLI 0.90.0 or higher -**Note:** Create the cluster first, then attach the new VM to that existing network. +**Compatible clusters:** Openshift, K3s, RKE2, EC, kURL +**Requirement:** Replicated CLI 0.90.0 or later -### Create a Cluster +To connect a Compatibility Matrix VM with a Compatibility Matrix cluster on the same network: -```bash -replicated cluster create --distribution K8S_DISTRIBUTION -``` +1. Create a cluster: -**Example** – `replicated cluster create --distribution k3s` + ```bash + replicated cluster create --distribution K8S_DISTRIBUTION + ``` -If successful, you'll see: + For example, `replicated cluster create --distribution k3s`. -``` -ID NAME DISTRIBUTION VERSION STATUS CREATED -EXPIRES COST -b09cf035 affect_mend k3s 1.32.0 queued 2025-01-28 16:04 PST - $0.60 -``` + Example output: -### Check the Network + ``` + ID NAME DISTRIBUTION VERSION STATUS CREATED + EXPIRES COST + b09cf035 affect_mend k3s 1.32.0 queued 2025-01-28 16:04 PST - $0.60 + ``` -```bash -replicated network ls -``` +1. Check the network: -If successful, you'll see: + ```bash + replicated network ls + ``` -``` -ID NAME STATUS CREATED EXPIRES -accbd6a7 affect_mend running 2025-01-28 16:04 PST 2025-01-28 17:05 PST -``` + Example output: -### Create CMX VM on Same Network + ``` + ID NAME STATUS CREATED EXPIRES + accbd6a7 affect_mend running 2025-01-28 16:04 PST 2025-01-28 17:05 PST + ``` -```bash -replicated vm create --distribution DISTRIBUTION --network NETWORK_ID -``` +1. Create a VM on the same network: -**Example** – `replicated vm create --distribution ubuntu --network accbd6a7` + ```bash + replicated vm create --distribution DISTRIBUTION --network NETWORK_ID + ``` -If successful, you'll see: + For example, `replicated vm create --distribution ubuntu --network accbd6a7`. -``` -ID NAME DISTRIBUTION VERSION STATUS CREATED EXPIRES COST -760a30b1 laughing_tu ubuntu 24.04 queued 2025-01-28 16:07 PST - $0.60 -``` + Example output: + + ``` + ID NAME DISTRIBUTION VERSION STATUS CREATED EXPIRES COST + 760a30b1 laughing_tu ubuntu 24.04 queued 2025-01-28 16:07 PST - $0.60 + ``` + + In this example, both the cluster `b09cf035` and the VM `760a30b1` are now on the same tailnet. -**Example** – Both the cluster `b09cf035` and the VM `760a30b1` are now on the same tailnet. +## Connect Compatibility Matrix VMs on a Shared Network -## Connect CMX VMs on a Shared Network +### 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. From bf90ee81af4a68f298c969e62bbe7842b34f6c0e Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Mon, 4 Aug 2025 15:05:53 -0600 Subject: [PATCH 20/24] edits --- docs/vendor/testing-vm-create.md | 71 +++++++------------------------- 1 file changed, 14 insertions(+), 57 deletions(-) diff --git a/docs/vendor/testing-vm-create.md b/docs/vendor/testing-vm-create.md index 2b6e440e99..856e556017 100644 --- a/docs/vendor/testing-vm-create.md +++ b/docs/vendor/testing-vm-create.md @@ -84,15 +84,16 @@ To set up and verify SSH access for Compatibility Matrix VMs using your personal ```bash ssh -T replicated@replicatedvm.com ``` - -1. For the prompt `Are you sure you want to continue connecting (yes/no/[fingerprint])?`, type `yes` and press Enter. - If successful, you will see a message similar to the following: ``` - You have successfully authenticated, use @replicatedvm.com to access your VM. + 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 To automate the creation of VMs in your CI/CD workflows, you can use the flag `--ssh-public-key` to provide the SSH public key for a GitHub service account. For example: @@ -158,8 +159,6 @@ You can SSH into a VM using one of the following methods: * [**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 Compatibility Matrix 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. -* [**Connect to a VM Manually**](#connect-to-a-vm-manually): If the above options are not supported with your preferred SSH client, you can connect to a VM manually. - For information about how to copy files to a VM after connecting, see [Copy Files to a VM](#copy-files-to-a-vm) below. ### Compatibility Matrix Forwarder @@ -178,7 +177,9 @@ For information about copying files to the VM after connecting, see [After Conne ### Direct SSH -Transferring files using Direct SSH allows you to use your SSH tool of choice, and pass any client-supported flags. Direct SSH requires Replicated CLI v0.104.0 or later. +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: @@ -205,6 +206,10 @@ Transferring files using Direct SSH allows you to use your SSH tool of choice, a ``` 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: @@ -230,59 +235,11 @@ Transferring files using Direct SSH allows you to use your SSH tool of choice, a ``` ssh $(replicated vm ssh-endpoint aba1acc2) - ``` - -### Connect to a VM Manually - -If the Forwarder or direct SSH do not work with your preferred SSH client, you can connect manually. When a VM is created, a random port is assigned to each machine within each group of the VM. - -To connect with the machine over SSH: - -1. Run the following command: - - ```bash - replicated vm ls --output json - ``` - - The following shows an example of the output of this command: - - ```json - [ - { - "id": "e32aafa1", - "name": "sad_black", - "distribution": "ubuntu", - "version": "24.04", - "status": "running", - "created_at": "2024-10-24T15:00:37Z", - "expires_at": "2024-10-24T16:01:10Z", - "ttl": "1h", - "credits_per_hour_per_vm": 0, - "flat_fee": 50000, - "total_credits": 0, - "estimated_cost": 0, - "direct_ssh_port": 33655, - "direct_ssh_endpoint": "95.217.47.21", - "tags": [] - } - ] - ``` - -1. Run the following command to connect: - - ```bash - ssh -p DIRECT_SSH_PORT GITHUB_USERNAME@DIRECT_SSH_ENDPOINT - ``` - - **Example:** - - ```bash - ssh -p 33655 myName@95.217.47.21 - ``` + ``` ## Copy Files to a VM -You can copy files to a VM either using an SCP endpoint, or by using SCP after connecting to the VM with the Compatibility Matrix Forwarder. +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 Compatibility Matrix 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 From 0d0b080e5b79f217fef5f23b8748c902308a732c Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Tue, 5 Aug 2025 11:45:14 -0600 Subject: [PATCH 21/24] Apply suggestions from code review Co-authored-by: Kyle Squizzato Co-authored-by: Josh De Winne --- docs/vendor/testing-vm-create.md | 8 ++++---- docs/vendor/testing-vm-networking.md | 4 ++-- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/vendor/testing-vm-create.md b/docs/vendor/testing-vm-create.md index 856e556017..c94b07e9a7 100644 --- a/docs/vendor/testing-vm-create.md +++ b/docs/vendor/testing-vm-create.md @@ -99,13 +99,13 @@ To set up and verify SSH access for Compatibility Matrix VMs using your personal To automate the creation of VMs in your CI/CD workflows, you can use the flag `--ssh-public-key` to provide the SSH public key for a GitHub service account. For example: ```bash -replicated vm create --distribution ubuntu --version 20.04 --ssh-public-key ~/.ssh/id_rsa.pub +replicated vm create --distribution ubuntu --version 24.04 --ssh-public-key ~/.ssh/id_rsa.pub ``` Using multiple SSH public keys: ```bash -replicated vm create --distribution ubuntu --version 20.04 --ssh-public-key ~/.ssh/id_rsa.pub --ssh-public-key ~/.ssh/id_ed25519.pub +replicated vm create --distribution ubuntu --version 24.04 --ssh-public-key ~/.ssh/id_rsa.pub --ssh-public-key ~/.ssh/id_ed25519.pub ``` ## Create VMs @@ -134,9 +134,9 @@ To create VMs with Compatibility Matrix: ``` Where: - * `NAME` is any name for the VM. If `--name` is excluded, a name is automatically generated for the cluster. + * `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., 20.04, 22.04 for Ubuntu). + * `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. diff --git a/docs/vendor/testing-vm-networking.md b/docs/vendor/testing-vm-networking.md index cf3757a616..46f2198301 100644 --- a/docs/vendor/testing-vm-networking.md +++ b/docs/vendor/testing-vm-networking.md @@ -37,7 +37,7 @@ replicated vm port rm VMID_OR_VMNAME You can make a Compatibility Matrix cluster available on the same network as a Compatibility Matrix VM. -**Compatible clusters:** Openshift, K3s, RKE2, EC, kURL +**Compatible clusters:** Openshift, K3s, RKE2, EC, kURL, kind **Requirement:** Replicated CLI 0.90.0 or later To connect a Compatibility Matrix VM with a Compatibility Matrix cluster on the same network: @@ -86,7 +86,7 @@ To connect a Compatibility Matrix VM with a Compatibility Matrix cluster on the 760a30b1 laughing_tu ubuntu 24.04 queued 2025-01-28 16:07 PST - $0.60 ``` - In this example, both the cluster `b09cf035` and the VM `760a30b1` are now on the same tailnet. + In this example, both the cluster `b09cf035` and the VM `760a30b1` are now on the same network. ## Connect Compatibility Matrix VMs on a Shared Network From 7bad328667898b22d4417330eed5c32e117baca1 Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Tue, 5 Aug 2025 12:04:32 -0600 Subject: [PATCH 22/24] correction based on feedback --- docs/vendor/testing-how-to.md | 2 +- docs/vendor/testing-vm-create.md | 4 ++-- docs/vendor/testing-vm-networking.md | 23 +++++++---------------- 3 files changed, 10 insertions(+), 19 deletions(-) diff --git a/docs/vendor/testing-how-to.md b/docs/vendor/testing-how-to.md index 855d001472..b6d4ac2f18 100644 --- a/docs/vendor/testing-how-to.md +++ b/docs/vendor/testing-how-to.md @@ -12,7 +12,7 @@ Compatibility Matrix supports both VM-based clusters (such as kind, k3s, RKE2, O You can use Compatibility Matrix clusters for testing and troubleshooting Kubernetes-based deployments and Helm installations for your application. -For information about creating VMs with Compatibility Matrix to test Replicated Embedded Cluster installers, air-gap installations, or when you need full OS control, see [Create VMs](/vendor/testing-vm-create). +For information about creating VMs with Compatibility Matrix to test Replicated Embedded Cluster installers or when you need full OS control, see [Create VMs](/vendor/testing-vm-create). ## Prerequisites diff --git a/docs/vendor/testing-vm-create.md b/docs/vendor/testing-vm-create.md index c94b07e9a7..cfb7ab4808 100644 --- a/docs/vendor/testing-vm-create.md +++ b/docs/vendor/testing-vm-create.md @@ -26,7 +26,7 @@ The following VM types are supported: Creating VMs with Compatibility Matrix has the following limitations: - Creating VMs with Compatibility Matrix is a Beta feature. -- Installing Embedded Cluster on a VM created with Compatibility Matrix is supported for Embedded Cluster versions 1.21.0 or later. To reboot a Compatibility Matrix VM, you can run the Embedded Cluster [reset](embedded-using#reset-a-node) command. +- Installing Embedded Cluster on a VM created with Compatibility Matrix is supported for Embedded Cluster versions 1.21.0 or later. - [GitHub Actions](/vendor/testing-how-to#replicated-github-actions) are not supported for Compatibility Matrix VMs. - The [cluster prepare](/reference/replicated-cli-cluster-prepare) command is not supported for Compatibility Matrix VMs. @@ -290,7 +290,7 @@ To copy files to a VM using the scp endpoint: ### After Connecting to the VM with the Forwarder :::note -Transferring files using Compatibility Matrix Forwarder is slower than using direct SSH. Compatibility Matrix servers run on EKS, so depending on your location, using the Forwarder adds 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. +Transferring files using Compatibility Matrix 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 diff --git a/docs/vendor/testing-vm-networking.md b/docs/vendor/testing-vm-networking.md index 46f2198301..bc4c35c0a3 100644 --- a/docs/vendor/testing-vm-networking.md +++ b/docs/vendor/testing-vm-networking.md @@ -50,15 +50,7 @@ To connect a Compatibility Matrix VM with a Compatibility Matrix cluster on the For example, `replicated cluster create --distribution k3s`. - Example output: - - ``` - ID NAME DISTRIBUTION VERSION STATUS CREATED - EXPIRES COST - b09cf035 affect_mend k3s 1.32.0 queued 2025-01-28 16:04 PST - $0.60 - ``` - -1. Check the network: +1. Get the network ID: ```bash replicated network ls @@ -66,9 +58,9 @@ To connect a Compatibility Matrix VM with a Compatibility Matrix cluster on the Example output: - ``` - ID NAME STATUS CREATED EXPIRES - accbd6a7 affect_mend running 2025-01-28 16:04 PST 2025-01-28 17:05 PST + ```bash + ID NAME STATUS CREATED EXPIRES POLICY REPORTING + accbd6a7 suspicious_paitras preparing 2025-08-04 13:24 PDT - Open Off ``` 1. Create a VM on the same network: @@ -76,18 +68,17 @@ To connect a Compatibility Matrix VM with a Compatibility Matrix cluster on the ```bash replicated vm create --distribution DISTRIBUTION --network NETWORK_ID ``` + Where `NETWORK_ID` is the ID of the network from the output of the `replicated network ls` command. For example, `replicated vm create --distribution ubuntu --network accbd6a7`. Example output: ``` - ID NAME DISTRIBUTION VERSION STATUS CREATED EXPIRES COST - 760a30b1 laughing_tu ubuntu 24.04 queued 2025-01-28 16:07 PST - $0.60 + 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 ``` - In this example, both the cluster `b09cf035` and the VM `760a30b1` are now on the same network. - ## Connect Compatibility Matrix VMs on a Shared Network ### Create VMs on the Same Network From 3cb736fbb7c7f983102377fcd259923aa119c05f Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Tue, 5 Aug 2025 12:17:38 -0600 Subject: [PATCH 23/24] edit steps --- docs/vendor/testing-vm-networking.md | 16 ++++++---------- 1 file changed, 6 insertions(+), 10 deletions(-) diff --git a/docs/vendor/testing-vm-networking.md b/docs/vendor/testing-vm-networking.md index bc4c35c0a3..3b0e7bcec9 100644 --- a/docs/vendor/testing-vm-networking.md +++ b/docs/vendor/testing-vm-networking.md @@ -50,17 +50,13 @@ To connect a Compatibility Matrix VM with a Compatibility Matrix cluster on the For example, `replicated cluster create --distribution k3s`. -1. Get the network ID: +1. In the output of the `cluster create` command, under `NETWORK`, copy the network ID. - ```bash - replicated network ls - ``` - - Example output: + Example: - ```bash - ID NAME STATUS CREATED EXPIRES POLICY REPORTING - accbd6a7 suspicious_paitras preparing 2025-08-04 13:24 PDT - Open Off + ``` + 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 ``` 1. Create a VM on the same network: @@ -68,7 +64,7 @@ To connect a Compatibility Matrix VM with a Compatibility Matrix cluster on the ```bash replicated vm create --distribution DISTRIBUTION --network NETWORK_ID ``` - Where `NETWORK_ID` is the ID of the network from the output of the `replicated network ls` command. + Where `NETWORK_ID` is the network ID that you copied in the previous step. For example, `replicated vm create --distribution ubuntu --network accbd6a7`. From 8d2e6181a190af51531c0cd48e93089167b5278b Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Tue, 5 Aug 2025 12:24:39 -0600 Subject: [PATCH 24/24] edits --- docs/vendor/testing-vm-networking.md | 28 ++++++++++++++++------------ 1 file changed, 16 insertions(+), 12 deletions(-) diff --git a/docs/vendor/testing-vm-networking.md b/docs/vendor/testing-vm-networking.md index 3b0e7bcec9..55db1b8fee 100644 --- a/docs/vendor/testing-vm-networking.md +++ b/docs/vendor/testing-vm-networking.md @@ -58,6 +58,7 @@ To connect a Compatibility Matrix VM with a Compatibility Matrix cluster on the 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: @@ -87,20 +88,23 @@ replicated vm create --distribution ubuntu --count 3 ### Join VMs to an Existing VM Network -First, get the ID of an existing VM network: +1. Run one of the following commands to get the ID of an existing VM network: -```bash -replicated vm ls -``` + * List VMs: + ```bash + replicated vm ls + ``` -Or + * List networks: + ```bash + replicated network ls + ``` -```bash -replicated network ls -``` +1. In the output of the command, copy the network ID. -Use the `--network` flag to create new VMs on the same network: +1. Use the `--network` flag to create a new VM on the same network: -```bash -replicated vm create --distribution ubuntu --network NETWORK_ID -``` \ No newline at end of file + ```bash + replicated vm create --distribution ubuntu --network NETWORK_ID + ``` + Where `NETWORK_ID` is the network ID that you copied in the previous step. \ No newline at end of file