HOLD FOR RELEASE: Add CMX VMs beta docs #3407
Conversation
✅ Deploy Preview for replicated-docs ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
replicated-ci
added
type::docs
✅ Deploy Preview for replicated-docs-upgrade ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
docs/vendor/testing-vm-networking.md
Outdated
| replicated vm port rm VMID_OR_VMNAME | ||
| ``` | ||
|
|
||
| ## Connect a CMX VM with a CMX Cluster |
There was a problem hiding this comment.
Oo fancy.
Makes me wonder if we might want to consider how this content fits with or overlaps with https://docs.replicated.com/vendor/testing-ingress.
As in, do we want separate VMs and cluster networking pages?, where would this info live that touches on both?, do we want the headlines framed around "networking", "accessing your app in the cluster/VM", or maybe something else? etc
I don't really think this needs to be addressed as part of this PR, but something we can talk through
There was a problem hiding this comment.
Yes, let's discuss this! Very good questions.
docs/vendor/testing-vm-create.md
Outdated
| ssh -T [email protected] | ||
| ``` | ||
|
|
||
| 1. For the prompt `Are you sure you want to continue connecting (yes/no/[fingerprint])?`, type `yes` and press Enter. |
There was a problem hiding this comment.
- For the prompt
Are you sure you want to continue connecting (yes/no/[fingerprint])?, typeyesand press Enter.
I got this output when I was testing. I assume you are just supposed to say Yes?
There was a problem hiding this comment.
Note from 8/4: we should clarify that you may or may not see this prompt.
|
|
||
| ```bash | ||
| replicated vm create --distribution ubuntu --version 20.04 --ssh-public-key ~/.ssh/id_rsa.pub --ssh-public-key ~/.ssh/id_ed25519.pub | ||
| ``` |
There was a problem hiding this comment.
To automate the creation of VMs in your CI/CD workflows, you can use the flag
--ssh-public-keyto provide the SSH public key for a GitHub service account.
This section doesn't have any info about how to set up the service account/use it in your CI/CD workflows. I think that's fine for the first iteration of these docs, but one thing that might be important is how would the Vendor Portal be made aware of this service account?
Would we like to recommend that someone on the team needs to add the name of the service account in their Vendor Portal account? Or would be prefer the username override method?
| replicated vm create --distribution ubuntu --version 22.04 --disk 50 --instance-type r1.medium | ||
| ``` | ||
|
|
||
| ## Connect to a VM |
There was a problem hiding this comment.
Note: I did some reorg here so that you have three methods listed for how to connect to a VM (previously, the steps on connecting manually were elsewhere).
I also moved the steps on how to transfer files to their own h2 section. My assumption was that it would be worthwhile to include steps just for how to connect, without also telling people how to transfer. If that's not a valid use case though, we can combine the "connect" and "copy files" sections into one. LMK.
docs/vendor/testing-vm-create.md
Outdated
|
|
||
| * [**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. |
There was a problem hiding this comment.
^ this "connect manually" doesn't need to be a totally different option. instead, just add it as an alternative to the vm ssh-endpoint command
| :::note | ||
| You can also get the SSH endpoint and port in JSON format by running `replicated vm ls --output json`. | ||
| ::: |
There was a problem hiding this comment.
^ new note that replaces the "connect manually" steps
There was a problem hiding this comment.
@hyu updated based on our convo today and approved! marking as "hold for release", and I'll leave it to you to merge when you all are ready :)
paigecalvert
changed the title
| 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. |
There was a problem hiding this comment.
We support rebooting, sudo reboot works fine and is supported. I don't think we need to mention the reboot portion at all
| 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 |
There was a problem hiding this comment.
Might make more sense for the version to be one we support in the example:
| 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 |
There was a problem hiding this comment.
| 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 |
| ``` | ||
| Where: | ||
| * `NAME` is any name for the VM. If `--name` is excluded, a name is automatically generated for the cluster. |
There was a problem hiding this comment.
| * `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. |
|
|
||
| ``` | ||
| ID NAME DISTRIBUTION VERSION STATUS CREATED EXPIRES COST | ||
| 760a30b1 laughing_tu ubuntu 24.04 queued 2025-01-28 16:07 PST - $0.60 |
There was a problem hiding this comment.
This output is inaccruate and is missing the NETWORK column, for example:
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
|
|
||
| ``` | ||
| ID NAME STATUS CREATED EXPIRES | ||
| accbd6a7 affect_mend running 2025-01-28 16:04 PST 2025-01-28 17:05 PST |
There was a problem hiding this comment.
This table output is not lined up, and the output is an old version of network ls, here's what it should look like:
ID NAME STATUS CREATED EXPIRES POLICY REPORTING
accbd6a7 suspicious_poitras preparing 2025-08-04 13:24 PDT - open off
|
|
||
| ## Create and Manage Clusters | ||
| 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). |
There was a problem hiding this comment.
Airgap is referenced here but we never talk about it in the Create VMs page.
There was a problem hiding this comment.
Ah yeah I had noticed that too and forgot to remove it. Good catch!
| 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). |
There was a problem hiding this comment.
| * `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). |
| ### 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. |
There was a problem hiding this comment.
I don't think we should expose here that this runs on EKS.
|
|
||
| You can make a Compatibility Matrix cluster available on the same network as a Compatibility Matrix VM. | ||
|
|
||
| **Compatible clusters:** Openshift, K3s, RKE2, EC, kURL |
There was a problem hiding this comment.
| **Compatible clusters:** Openshift, K3s, RKE2, EC, kURL | |
| **Compatible clusters:** Openshift, K3s, RKE2, EC, kURL, kind |
| 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 |
There was a problem hiding this comment.
This should already show the network id?
| 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. |
There was a problem hiding this comment.
| 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. |
No description provided.