diff --git a/docs/vendor/compatibility-matrix-usage.md b/docs/vendor/compatibility-matrix-usage.md index a9b52461bc..5e7e6d9cfc 100644 --- a/docs/vendor/compatibility-matrix-usage.md +++ b/docs/vendor/compatibility-matrix-usage.md @@ -1,4 +1,4 @@ -# View Compatibility Matrix Usage History +# Compatibility Matrix Usage History This topic describes using the Replicated Vendor Portal to understand Compatibility Matrix usage across your team. diff --git a/docs/vendor/environment-setup.mdx b/docs/vendor/environment-setup.mdx index 93739662e1..673b66ddc4 100644 --- a/docs/vendor/environment-setup.mdx +++ b/docs/vendor/environment-setup.mdx @@ -283,6 +283,6 @@ You need access to a VM to test installations and updates with the [Replicated E To test installations with Helm, you need kubectl access to a cluster. -* **Option 1: Use Compatibility Matrix.** You can use Replicated Compatibility Matrix to create clusters. For more information, see [Create Clusters](/vendor/testing-how-to). +* **Option 1: Use Compatibility Matrix.** You can use Replicated Compatibility Matrix to create clusters. For more information, see [Create and Manage Clusters](/vendor/testing-how-to). * **Option 2: Use another cloud provider or tool.** You can use any cloud provider or tool that you prefer to create a cluster, such as Google Kubernetes Engine (GKE) or minikube. diff --git a/docs/vendor/support-inspecting-support-bundles.md b/docs/vendor/support-inspecting-support-bundles.md index b5ad4ee6d4..a9afa60342 100644 --- a/docs/vendor/support-inspecting-support-bundles.md +++ b/docs/vendor/support-inspecting-support-bundles.md @@ -26,7 +26,7 @@ To inspect a support bundle: 1. (Optional) Click **Download bundle** to download the bundle. This can be helpful if you want to access the bundle from another system or if other team members want to access the bundle and use other tools to examine the files. -1. (Optional) Navigate back to the [**Troubleshoot**](https://vendor.replicated.com/troubleshoot) page and click **Create cluster** to provision a cluster with Replicated Compatibility Matrix. This can be helpful for creating customer-representative environments for troubleshooting. For more information about creating clusters with Compatibility Matrix, see [Use Compatibility Matrix](testing-how-to). +1. (Optional) Navigate back to the [**Troubleshoot**](https://vendor.replicated.com/troubleshoot) page and click **Create cluster** to provision a cluster with Replicated Compatibility Matrix. This can be helpful for creating customer-representative environments for troubleshooting. For more information about creating clusters with Compatibility Matrix, see [Create and Manage Clusters](testing-how-to). Cluster configuration dialog diff --git a/docs/vendor/testing-about.md b/docs/vendor/testing-about.md index acb62c8c47..145e7bf31f 100644 --- a/docs/vendor/testing-about.md +++ b/docs/vendor/testing-about.md @@ -11,7 +11,7 @@ Example use cases for Compatibility Matrix include: * Get access to a cluster or VM to develop on and quickly test changes * Reproduce a reported issue on a customer-representative environment for troubleshooting -You can use Compatibility Matrix with the Replicated CLI or the Replicated Vendor Portal. For more information about how to use Compatibility Matrix, see [Create Clusters](testing-how-to) and [Create VMs](testing-vm-create). +You can use Compatibility Matrix with the Replicated CLI or the Replicated Vendor Portal. For more information about how to use Compatibility Matrix, see [Create and Manage Clusters](testing-how-to) and [Create VMs](testing-vm-create). ## Supported Clusters and VMs diff --git a/docs/vendor/testing-ci-cd.md b/docs/vendor/testing-ci-cd.md index 1749e06b5e..bc0cb479a7 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" -# Use Compatibility Matrix with CI/CD +# Test in 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-how-to.md b/docs/vendor/testing-how-to.md index d1f26c2c99..2ff1cd3818 100644 --- a/docs/vendor/testing-how-to.md +++ b/docs/vendor/testing-how-to.md @@ -1,6 +1,6 @@ import Prerequisites from "../partials/cmx/_prerequisites.mdx" -# Create Clusters +# Use Compatibility Matrix 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. @@ -25,7 +25,6 @@ Compatibility Matrix has the following limitations: - ARM instance types are only supported on Cloud Clusters. For distribution-specific details, see [Supported Compatibility Matrix Cluster Types](/vendor/testing-supported-clusters). - GPU instance types are only supported on Cloud Clusters. For distribution-specific details, see [Supported Compatibility Matrix Cluster Types](/vendor/testing-supported-clusters). - There is no support for IPv6 as a single stack. Dual stack support is available on kind clusters. -- There is no support for air gap testing. - The `cluster upgrade` feature is available only for kURL distributions. See [cluster upgrade](/reference/replicated-cli-cluster-upgrade). - Cloud clusters do not allow for the configuration of CNI, CSI, CRI, Ingress, or other plugins, add-ons, services, and interfaces. - The node operating systems for clusters created with Compatibility Matrix cannot be configured nor replaced with different operating systems. @@ -171,6 +170,28 @@ To create a cluster using the Vendor Portal: [View a larger version of this image](/images/cmx-assigned-cluster.png) +## Create Air Gap Clusters (Beta) + +For any VM-based cluster distributions, you can create a cluster that uses an air-gapped network by setting the network policy to `airgap`. + +For more information, see [Use Air Gap Networks (Beta)](testing-network-policy). + +To set the network policy of a VM-based cluster to `airgap`: + +1. Create a cluster: + + ```bash + replicated cluster create --distribution VM_BASED_DISTRIBUTION + ``` + Where `VM_BASED_DISTRIBUTION` is the target VM-based cluster distribution. For a list of supported distributions, see [VM Clusters](/vendor/testing-supported-clusters#vm-clusters). + +1. Change the network policy to `airgap`: + + ```bash + replicated network update NETWORK_ID --policy airgap + ``` + Where `NETWORK_ID` is the ID of the network from the output of the `cluster ls` command. + ## 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). diff --git a/docs/vendor/testing-ingress.md b/docs/vendor/testing-ingress.md index 8317bbaeed..a2b45cc8ed 100644 --- a/docs/vendor/testing-ingress.md +++ b/docs/vendor/testing-ingress.md @@ -1,4 +1,4 @@ -# Cluster Networking +# Compatibility Matrix Cluster Networking This topic describes the networking options for accessing applications deployed on clusters created with Replicated Compatibility Matrix. It also describes how to use and manage Compatibility Matrix tunnels. @@ -32,83 +32,4 @@ Compatibility matrix supports ingress controllers that are running as a `NodePor ### Compatibility Matrix Tunnels All VM-based Compatibility Matrix clusters support tunneling traffic into a `NodePort` service. When this option is used, Replicated is responsible for creating the DNS record and TLS certs. -Replicated will route traffic from `:443` and/or `:80` into the `NodePort` service you defined. For more information about using tunnels, see [Managing Compatibility Matrix Tunnels](#manage-nodes) below. - -The following diagram shows how the traffic is routed into the service using Compatibility Matrix tunnels: - -Compatibility Matrix ingress - -[View a larger version of this image](/images/compatibility-matrix-ingress.png) - -## Managing Compatibility Matrix Tunnels {#manage-nodes} - -Tunnels are viewed, created, and removed using the Compatibility Matrix UI within Vendor Portal, the Replicated CLI, GitHub Actions, or directly with the Vendor API v3. There is no limit to the number of tunnels you can create for a cluster and multiple tunnels can connect to a single service, if desired. - -### Limitations - -Compatibility Matrix tunnels have the following limitations: -* One tunnel can only connect to one service. If you need fanout routing into different services, consider installing the nginx ingress controller as a `NodePort` service and exposing it. -* Tunnels are not supported for cloud distributions (EKS, GKE, AKS). - -### Supported Protocols - -A tunnel can support one or more protocols. -The supported protocols are HTTP, HTTPS, WS and WSS. -GRPC and other protocols are not routed into the cluster. - -### Exposing Ports -Once you have a node port available on the cluster, you can use the Replicated CLI to expose the node port to the public internet. -This can be used multiple times on a single cluster. - -Optionally, you can specify the `--wildcard` flag to expose this port with wildcard DNS and TLS certificate. -This feature adds extra time to provision the port, so it should only be used if necessary. - -```bash -replicated cluster port expose \ - [cluster id] \ - --port [node port] \ - --protocol [protocol] \ - --wildcard -``` - -For example, if you have the nginx ingress controller installed and the node port is 32456: - -```bash -% replicated cluster ls -ID NAME DISTRIBUTION VERSION STATUS -1e616c55 tender_ishizaka k3s 1.29.2 running - -% replicated cluster port expose \ - 1e616c55 \ - --port 32456 \ - --protocol http \ - --protocol https \ - --wildcard -``` - -:::note -You can expose a node port that does not yet exist in the cluster. -This is useful if you have a deterministic node port, but need the DNS name as a value in your Helm chart. -::: - -### Viewing Ports -To view all exposed ports, use the Replicated CLI `port ls` subcommand with the cluster ID: - -```bash -% replicated cluster port ls 1e616c55 -ID CLUSTER PORT PROTOCOL EXPOSED PORT WILDCARD STATUS -d079b2fc 32456 http http://happy-germain.ingress.replicatedcluster.com true ready - -d079b2fc 32456 https https://happy-germain.ingress.replicatedcluster.com true ready -``` - -### Removing Ports -Exposed ports are automatically deleted when a cluster terminates. -If you want to remove a port (and the associated DNS records and TLS certs) prior to cluster termination, run the `port rm` subcommand with the cluster ID: - -```bash -% replicated cluster port rm 1e616c55 --id d079b2fc -``` - -You can remove just one protocol, or all. -Removing all protocols also removes the DNS record and TLS cert. +Replicated will route traffic from `:443` and/or `:80` into the `NodePort` service you defined. For more information about using tunnels, see [Expose Ports Using Tunnels](testing-vm-networking). \ No newline at end of file diff --git a/docs/vendor/testing-network-policy.md b/docs/vendor/testing-network-policy.md index 7ea4ff2d60..f7a01f750b 100644 --- a/docs/vendor/testing-network-policy.md +++ b/docs/vendor/testing-network-policy.md @@ -1,6 +1,6 @@ -# Set Network Policies (Beta) +# Test in Air Gap Environments (Beta) -This topic describes how to change the network policy of a virtual machine (VM) or a VM-based cluster with Replicated Compatibility Matrix. +This topic describes how to change the network policy of a virtual machine (VM) or a VM-based cluster with Replicated Compatibility Matrix, and how to collect and analyze network events to understand your application's behavior in an air gap environment. ## About Network Policies @@ -15,18 +15,29 @@ By default, all VMs and clusters are created with an `open` network policy. You The `airgap` network policy is particularly useful for testing air gap installations for your application. For information about installing with Embedded Cluster in an air-gapped environment, see [Air Gap Installation with Embedded Cluster](/enterprise/installing-embedded-air-gap). For information about installing with the Helm CLI in an air-gapped environment, see [Install and Update with Helm in Air Gap Environments](/vendor/helm-install-airgap). + ## Requirements -* Replicated CLI 0.109.0 or later -* The user must have the Admin or Developer role. Read Only users cannot change network settings. +- **VM-Based Only**: Network policies are supported only for VMs and VM-based clusters (K3s, RKE2, Embedded Cluster, kURL, Kind, OpenShift). Network policies are not supported for cloud-based clusters (EKS, GKE, AKE, OKE). +- **Replicated CLI 0.109.0 or later** +- **User Role**: The user must have the Admin or Developer role. Read Only users cannot change network settings. ## Limitations -* Network policies are a beta feature. For feedback on this feature, including requests for additional types of network policies, contact Replicated support. -* Setting network policies is only supported through the Replicated CLI. You cannot make changes to the network policy through the Compatibility Matrix UI in the Vendor Portal. -* Network policies are supported only for VMs and VM-based clusters (K3s, RKE2, Embedded Cluster, kURL, Kind, OpenShift). Network policies are not supported for cloud-based clusters (EKS, GKE, AKE, OKE). +- **Network Status**: Reporting can only be enabled on running networks +- **Policy Changes**: Changing policies creates a new report (historical data remains) +- **Real-time**: Events may have a 1-2 second delay before appearing in reports + +## Network Policy Overview + +### Basic Network Policies (for traffic control) + +| Policy Name | Description | Use Case | +|-------------|-------------|----------| +| `open` | No restrictions on network traffic | Standard development and testing | +| `airgap` | Restrict all network traffic | Air gap installation testing | -## Set the Network Policy to `airgap` +## Set Network Policy to `airgap` ### For VM-Based Clusters @@ -103,7 +114,7 @@ To set the network policy of a VM-based cluster: ### For VMs -To set the network policy of a VM-based cluster: +To set the network policy of a VM: 1. Create a VM: @@ -158,4 +169,65 @@ To set the network policy of a VM-based cluster: curl: (28) Failed to connect to www.google.com port 80 after 129976 ms: Couldn't connect to server ``` -1. (Optional) Test an air gap installation of your application on the VM. See [Air Gap Installation with Embedded Cluster](/enterprise/installing-embedded-air-gap). \ No newline at end of file + +## Collect and View Network Reports + +### Enable Network Reporting + +#### Via Vendor Portal + +1. Navigate to **Compatibility Matrix** > **Network Policy** +2. In the **Reporting** column, toggle switch from "off" to "on" + +#### Via CLI + +```bash +replicated network update NETWORK_ID --collect-report +``` + +### View Network Reports + +#### Via Vendor Portal + +1. Navigate to **Compatibility Matrix** > **Network Policy** +2. Click on a network name in the Active Resources table +3. The Network Policy Report will appear below the table +4. Use the table to browse and filter network events + +#### Via CLI + +**View detailed network report as JSON:** + +```bash +replicated network report NETWORK_ID +``` + +**View network summary as JSON:** + +```bash +replicated network report NETWORK_ID --summary +``` + + +**List all networks and their reporting status:** + +```bash +replicated network ls +``` + +**Example output:** + +``` +ID NAME STATUS CREATED EXPIRES POLICY REPORTING +a1b2c3d4 example_network_1 running 2025-01-28 16:04 PST 2025-01-28 18:06 PST open off +e5f6g7h8 example_network_2 running 2025-01-28 12:10 PST 2025-01-28 20:11 PST airgap on +``` + + +### Policy Configuration + +Policies are configured at the network level and apply to all VMs and clusters within that network. You can change the policy at any time, but note that: + +- Policy changes terminate the current report and start a new one +- Historical data from the previous policy remains available +- The new policy takes effect immediately for new events diff --git a/docs/vendor/testing-shared-networks.md b/docs/vendor/testing-shared-networks.md new file mode 100644 index 0000000000..aa22b7f925 --- /dev/null +++ b/docs/vendor/testing-shared-networks.md @@ -0,0 +1,84 @@ +# Use Shared Networks + +This topic explains how to create VMs and clusters with Replicated Compatibility Matrix on the same network. + +## Connect a VM with a Cluster on the Same Network + +You can make a Compatibility Matrix cluster available on the same network as a Compatibility Matrix VM. + +#### Supported Cluster Distributions + +Openshift, K3s, RKE2, EC, kURL, kind + +#### Requirement + +Replicated CLI 0.90.0 or later + +To connect a VM with a cluster on the same network: + +1. Create a cluster: + + ```bash + replicated cluster create --distribution K8S_DISTRIBUTION + ``` + + For example, `replicated cluster create --distribution k3s`. + +1. In the output of the `cluster create` command, under `NETWORK`, copy the network ID. + + Example: + + ``` + ID NAME DISTRIBUTION VERSION STATUS NETWORK CREATED EXPIRES COST + 6b14376c ecstatic_raman k3s 1.33.2 queued accbd6a7 2025-08-04 13:20 PDT - $0.60 + ``` + In the example above, the network ID is `accbd6a7`. + +1. Create a VM on the same network: + + ```bash + replicated vm create --distribution DISTRIBUTION --network NETWORK_ID + ``` + Where `NETWORK_ID` is the network ID that you copied in the previous step. + + For example, `replicated vm create --distribution ubuntu --network accbd6a7`. + + Example output: + + ``` + ID NAME DISTRIBUTION VERSION STATUS NETWORK CREATED EXPIRES COST + 760a30b1 suspicious_poitras ubuntu 24.04 assigned accbd6a7 2025-08-04 13:24 PDT - $0.60 + ``` + +## Create VMs on the Same Network + +Use the `--count` flag to create multiple VMs with the same name, all running on the same Network ID. + +```bash +replicated vm create --distribution ubuntu --count 3 +``` + +## Join VMs to an Existing Network + +To join one or more new VMs to the network of an existing VM: + +1. Run one of the following commands to get the ID of an existing VM network: + + * List VMs: + ```bash + replicated vm ls + ``` + + * List networks: + ```bash + replicated network ls + ``` + +1. In the output of the command, copy the network ID. + +1. Use the `--network` flag to create a new VM on the same network: + + ```bash + replicated vm create --distribution ubuntu --network NETWORK_ID + ``` + Where `NETWORK_ID` is the network ID that you copied in the previous step. \ No newline at end of file diff --git a/docs/vendor/testing-supported-clusters.md b/docs/vendor/testing-supported-clusters.md index ed860c11ac..817428a3ce 100644 --- a/docs/vendor/testing-supported-clusters.md +++ b/docs/vendor/testing-supported-clusters.md @@ -1,7 +1,7 @@ import Pool from "../partials/cmx/_openshift-pool.mdx" import InstanceTypes from "../partials/cmx/_instance-types.mdx" -# Supported Compatibility Matrix Cluster Types +# Compatibility Matrix Cluster Types This topic describes the supported Kubernetes distributions, Kubernetes versions, instance types, nodes, limitations, and common use cases for clusters created with Replicated Compatibility Matrix. @@ -11,6 +11,10 @@ Compatibility Matrix provisions cloud-based or virtual machine (VM) clusters. This section lists the supported VM cluster distributions for clusters created with Compatibility Matrix. +VM-based clusters refers to clusters that run on Hetzner servers with the Compatibility Matrix cluster provisioner. This allows for greater flexibility than with Cloud Clusters like AWS, EKS, etc. For example, with VM-based distributions, Compatibility Matrix offers warm pools to make Openshift startup times very fast. + +For information about provisioning VMs, which come without pre-installed clusters and allow for more access to the OS, see [Create VMs](testing-vm-create). + ### kind Compatibility Matrix supports creating [kind](https://kind.sigs.k8s.io/) clusters. diff --git a/docs/vendor/testing-vm-about.md b/docs/vendor/testing-vm-about.md new file mode 100644 index 0000000000..d27d459d51 --- /dev/null +++ b/docs/vendor/testing-vm-about.md @@ -0,0 +1,46 @@ +import Prerequisites from "../partials/cmx/_prerequisites.mdx" +import InstanceTypes from "../partials/cmx/_instance-types.mdx" + +# About Compatibility Matrix VMs (Beta) + +This topic describes Compatibility Matrix VMs and their capabilities for testing your applications. + +## 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 (OS) and allow you to test installation methods that require direct OS access. + +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 and Manage 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. See [Replicated Instance Types](#replicated-instance-types).| +| almalinux | 8, 9, 10 | r1.small, r1.medium, r1.large, r1.xlarge, r1.2xlarge. See [Replicated Instance Types](#replicated-instance-types). | + +## Replicated Instance Types + +The following describes the Replicated instance types for VMs: + + + +## Limitations + +Creating VMs with 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-ci-cd#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 + +Before you can use Compatibility Matrix VMs, you must complete the following prerequisites: + + + +* Existing accounts must accept the TOS for the trial on the [**Compatibility Matrix**](https://vendor.replicated.com/compatibility-matrix) page in the Replicated Vendor Portal. diff --git a/docs/vendor/testing-vm-create.md b/docs/vendor/testing-vm-create.md index a855d0285a..0a63aa44c2 100644 --- a/docs/vendor/testing-vm-create.md +++ b/docs/vendor/testing-vm-create.md @@ -1,50 +1,7 @@ -import Prerequisites from "../partials/cmx/_prerequisites.mdx" -import InstanceTypes from "../partials/cmx/_instance-types.mdx" - -# Create VMs (Beta) +# Use Compatibility Matrix VMs (Beta) 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 (OS) and allow you to test installation methods that require direct OS access. - -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. See [Replicated Instance Types](#replicated-instance-types).| -| almalinux | 8, 9, 10 | r1.small, r1.medium, r1.large, r1.xlarge, r1.2xlarge. See [Replicated Instance Types](#replicated-instance-types). | - -## Replicated Instance Types - -The following describes the Replicated instance types for VMs: - - - -## Limitations - -Creating VMs with 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-ci-cd#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 - -Before you can use Compatibility Matrix VMs, you must complete the following prerequisites: - - - -* Existing accounts must accept the TOS for the trial on the [**Compatibility Matrix**](https://vendor.replicated.com/compatibility-matrix) page in the Replicated Vendor Portal. - ## Set Up SSH Access 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. @@ -228,7 +185,7 @@ 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. -For information about how to copy files to a VM after connecting, see [Copy Files to a VM](#copy-files-to-a-vm) below. +For information about how to copy files to a VM after connecting, see [Copy Files to a VM](testing-vm-transfer-files). ### Compatibility Matrix Forwarder @@ -242,7 +199,7 @@ 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. +For information about copying files to the VM after connecting, see [Copy Files to a VM](testing-vm-transfer-files). ### Direct SSH @@ -306,113 +263,32 @@ To connect to a VM using direct SSH: ssh $(replicated vm ssh-endpoint aba1acc2) ``` -## Expose Ports on Running VMs - -After creating a VM, you can create update the ingress and ports settings to add DNS records. This allows you to connect to ports on the VM. - -To update the ingress and ports settings for a running VM: - -1. In the Vendor Portal, go to [**Compatibility Matrix**](https://vendor.replicated.com/compatibility-matrix). - -1. Open the dot menu for the target VM and click **Edit VM**. - - ![Edit VM in the dot menu](/images/compatibility-matrix-edit-vm.png) - - [View a larger version of this image](/images/compatibility-matrix-edit-vm.png) - -1. Under **Ingress & Ports**, for **Add DNS record**, edit the fields as desired and click **Add** to create a DNS record. - - ![DNS record for a VM](/images/compatibility-matrix-ingress-ports.png) - [View a larger version of this image](/images/compatibility-matrix-ingress-ports.png) - - A DNS record and valid TLS cert are created and connected to the specified port. - -## Copy Files to a VM - -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 - -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 - ``` +## Create Air Gap VMs (Beta) - The output of the command lists the SCP endpoint for the VM: +You can create a VM that uses an air-gapped network by setting the network policy to `airgap`. - ``` - scp://GITHUB_USERNAME@SSH_ENDPOINT:PORT - ``` +For more information, see [Test in Use Air Gap Networks (Beta)](testing-network-policy). - For example, `scp://yourusername@37.27.52.116:46795`. +To set the network policy of a VM to `airgap`: -1. Copy the SCP endpoint. +1. Create a VM: -1. SCP files into the VM: - - ```bash - scp somefile scp://GITHUB_USERNAME@SSH_ENDPOINT:PORT//PATH - ``` - Where: - * `GITHUB_USERNAME`, `SSH_ENDPOINT`, and `PORT` are all copied from the SCP endpoint that you retrieved. - * `PATH` is the destination path on the VM. - - Alternatively, run the following command to SCP files into the VM without needing to copy the endpoint: - - ```bash - scp somefile $(replicated vm scp-endpoint VMID_OR_VMNAME)//PATH - ``` - -### After Connecting to the VM with the Forwarder - -:::note -Transferring files using 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 -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: - -1. SSH into the VM using the Forwarder: - - ```bash - ssh VMID@replicatedvm.com - ``` + ```bash + replicated vm create --distribution VM_DISTRIBUTION + ``` - Where `VMID` is the ID of the VM. +1. After the VM is running, SSH onto the VM: -1. Copy files onto the machine: ```bash - scp FILENAME VMID@replicatedvm:PATH - ``` + ssh VM_ID@replicatedvm.com + ``` + Where `VM_ID` is the ID of the VM from the output of the `vm ls` command. - 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. + For more information and additional options, see [Connect to a VM](/vendor/testing-vm-create#connect-to-a-vm). - **Example:** +1. Set the network policy to `airgap`: - ```bash - scp somefile 123abc@replicatedvm:/home/folder/somefile - ``` + ```bash + replicated network update NETWORK_ID --policy airgap + ``` + Where `NETWORK_ID` is the ID of the network from the output of the `vm ls` command. \ No newline at end of file diff --git a/docs/vendor/testing-vm-networking.md b/docs/vendor/testing-vm-networking.md index 18eec08950..28c0ff4b69 100644 --- a/docs/vendor/testing-vm-networking.md +++ b/docs/vendor/testing-vm-networking.md @@ -1,16 +1,16 @@ -# VM Networking (Beta) +# Compatibility Matrix VM Networking -This topic describes advanced networking features for Replicated Compatibility Matrix VMs, including port exposure, VM-to-cluster connections, and shared networks. +This topic explains how to expose ports on VMs and VM-based clusters created with Compatibility Matrix. -## Limitations +## Expose Ports on VMs -Creating wildcard DNS entries for VMs is not supported. For feedback, contact Replicated support. +You can expose ports on a VM and make them accessible on the public internet. -## Compatibility Matrix Tunnels +### Limitation -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). +Creating wildcard DNS entries for VMs is not supported. For feedback, contact Replicated support. -### Create a Tunnel +### CLI ```bash replicated vm port expose VMID_OR_VMNAME --port PORT --protocol PROTOCOL @@ -21,90 +21,112 @@ For example, to expose port 3000 with HTTP protocol: replicated vm port expose VM_ID --port 30000 --protocol http ``` -### List Tunnels +### Vendor Portal -```bash -replicated vm port ls VMID_OR_VMNAME -``` +To update the ingress and ports settings for a VM: -### Remove a Tunnel +1. In the Vendor Portal, go to [**Compatibility Matrix**](https://vendor.replicated.com/compatibility-matrix). -```bash -replicated vm port rm VMID_OR_VMNAME -``` +1. Create a VM. + +1. Open the dot menu for the VM and click **Edit VM**. + + ![Edit VM in the dot menu](/images/compatibility-matrix-edit-vm.png) + + [View a larger version of this image](/images/compatibility-matrix-edit-vm.png) + +1. Under **Ingress & Ports**, for **Add DNS record**, edit the fields as desired and click **Add** to create a DNS record. + + ![DNS record for a VM](/images/compatibility-matrix-ingress-ports.png) + [View a larger version of this image](/images/compatibility-matrix-ingress-ports.png) + + A DNS record and valid TLS cert are created and connected to the specified port. -## Connect a Compatibility Matrix VM with a Compatibility Matrix Cluster +## Expose Ports on VM-Based Clusters -You can make a Compatibility Matrix cluster available on the same network as a Compatibility Matrix VM. +After you have a node port available on the cluster, you can expose the node port to the public internet using the Replicated CLI. +There is no limit to the number of tunnels you can create for a cluster and multiple tunnels can connect to a single service. -**Compatible clusters:** Openshift, K3s, RKE2, EC, kURL, kind -**Requirement:** Replicated CLI 0.90.0 or later +:::note +You can expose a node port that does not yet exist in the cluster. +This is useful if you have a deterministic node port, but need the DNS name as a value in your Helm chart. +::: -To connect a Compatibility Matrix VM with a Compatibility Matrix cluster on the same network: +The following diagram shows how the traffic is routed into the service using Compatibility Matrix tunnels: -1. Create a cluster: +Compatibility Matrix ingress - ```bash - replicated cluster create --distribution K8S_DISTRIBUTION - ``` +[View a larger version of this image](/images/compatibility-matrix-ingress.png) - For example, `replicated cluster create --distribution k3s`. +### Limitations -1. In the output of the `cluster create` command, under `NETWORK`, copy the network ID. +* A tunnel can only connect to one service. If you need fanout routing into different services, consider installing the nginx ingress controller as a `NodePort` service and exposing it. +* Tunnels are not supported for cloud distributions (EKS, GKE, AKS). - Example: +### Supported Protocols - ``` - 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`. +A tunnel can support one or more protocols. +The supported protocols are HTTP, HTTPS, WS and WSS. +GRPC and other protocols are not routed into the cluster. -1. Create a VM on the same network: +### Expose Ports with the CLI - ```bash - replicated vm create --distribution DISTRIBUTION --network NETWORK_ID - ``` - Where `NETWORK_ID` is the network ID that you copied in the previous step. +To expose a port on a cluster using the Replicated CLI: - For example, `replicated vm create --distribution ubuntu --network accbd6a7`. +```bash +replicated cluster port expose \ + [cluster id] \ + --port [node port] \ + --protocol [protocol] +``` - Example output: +See [cluster port](/reference/replicated-cli-cluster-port). - ``` - 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 - ``` +### Use Wildcard DNS -## Connect Compatibility Matrix VMs on a Shared Network +Optionally, you can specify the `--wildcard` flag to expose this port with wildcard DNS and TLS certificate. +This feature adds extra time to provision the port, so it should only be used if necessary. -### Create VMs on the Same Network +For example, if you have the nginx ingress controller installed and the node port is 32456: -Use the `--count` flag to create multiple VMs with the same name, all running on the same Network ID. +```bash +% replicated cluster ls +ID NAME DISTRIBUTION VERSION STATUS +1e616c55 tender_ishizaka k3s 1.29.2 running + +% replicated cluster port expose \ + 1e616c55 \ + --port 32456 \ + --protocol http \ + --protocol https \ + --wildcard +``` + +## View Exposed Ports + +To view all exposed ports, use the `replicated port ls` subcommand with the cluster or VM ID: ```bash -replicated vm create --distribution ubuntu --count 3 +replicated cluster port ls CLUSTER_ID ``` -### Join VMs to an Existing VM Network +```bash +replicated vm port ls VMID_OR_VMNAME +``` -1. Run one of the following commands to get the ID of an existing VM network: +## Remove Ports - * List VMs: - ```bash - replicated vm ls - ``` +Exposed ports are automatically deleted when the cluster or VM terminates. - * List networks: - ```bash - replicated network ls - ``` +If you want to remove a port (and the associated DNS records and TLS certs) prior to termination, run the `port rm` subcommand with the cluster or VM ID: -1. In the output of the command, copy the network ID. +```bash +replicated cluster port rm PORT_ID --id CLUSTER_ID +``` -1. Use the `--network` flag to create a new VM on the same network: +```bash +replicated vm port rm VMID_OR_VMNAME +``` - ```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 +You can remove just one protocol, or all. +Removing all protocols also removes the DNS record and TLS cert. \ No newline at end of file diff --git a/docs/vendor/testing-vm-transfer-files.md b/docs/vendor/testing-vm-transfer-files.md new file mode 100644 index 0000000000..2a16dd9f5d --- /dev/null +++ b/docs/vendor/testing-vm-transfer-files.md @@ -0,0 +1,91 @@ +# Copy Files to a VM + +This topic describes how to transfer files to a VM created with Replicated Compatibility Matrix. + +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 + +To copy files to a VM using the scp endpoint: + +1. Run the following command to get the SCP endpoint: + + ```bash + replicated vm scp-endpoint VMID_OR_VMNAME [--username GITHUB_USERNAME] + ``` + + Where + * `VMID_OR_VMNAME` is the ID or name of the VM. + * (Optional) `GITHUB_USERNAME` is a GitHub username used to connect to the SCP endpoint. This is an optional flag that overrides the GitHub username listed in your Vendor Portal account. The `--username` flag is required if you want to: + * Use a different GitHub username than what is in Vendor Portal (or if there is no username set in the Vendor Portal) + * When creating a VM, you used the `--ssh-public-key` flag to associate the VM with a GitHub service account, and this doesn't match the GitHub username set in Vendor Portal + + **Example** + ```bash + replicated vm scp-endpoint aba1acc2 + ``` + + The output of the command lists the SCP endpoint for the VM: + + ``` + scp://GITHUB_USERNAME@SSH_ENDPOINT:PORT + ``` + + For example, `scp://yourusername@37.27.52.116:46795`. + +1. Copy the SCP endpoint. + +1. SCP files into the VM: + + ```bash + scp somefile scp://GITHUB_USERNAME@SSH_ENDPOINT:PORT//PATH + ``` + Where: + * `GITHUB_USERNAME`, `SSH_ENDPOINT`, and `PORT` are all copied from the SCP endpoint that you retrieved. + * `PATH` is the destination path on the VM. + + Alternatively, run the following command to SCP files into the VM without needing to copy the endpoint: + + ```bash + scp somefile $(replicated vm scp-endpoint VMID_OR_VMNAME)//PATH + ``` + +## After Connecting to the VM with the Forwarder + +:::note +Transferring files using 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 +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: + +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 + ``` diff --git a/sidebars.js b/sidebars.js index 750672e064..fbf96d15b5 100644 --- a/sidebars.js +++ b/sidebars.js @@ -189,29 +189,23 @@ const sidebars = { label: 'Compatibility Matrix', items: [ 'vendor/testing-about', - 'vendor/testing-pricing', + 'vendor/testing-supported-clusters', + 'vendor/testing-how-to', + 'vendor/testing-ingress', + 'vendor/testing-cluster-addons', + 'vendor/testing-vm-about', + 'vendor/testing-vm-create', + 'vendor/testing-vm-networking', + 'vendor/testing-network-policy', + 'vendor/testing-ci-cd', { type: 'category', - label: 'Use Compatibility Matrix', + label: 'Managing Cost with CMX', items: [ - 'vendor/testing-how-to', - 'vendor/testing-supported-clusters', - 'vendor/testing-cluster-addons', - 'vendor/testing-vm-create', - 'vendor/testing-ci-cd', - { - type: 'category', - label: 'Networking', - items: [ - 'vendor/testing-ingress', - 'vendor/testing-vm-networking', - 'vendor/testing-network-policy', - ] - } - ], + 'vendor/testing-pricing', + 'vendor/compatibility-matrix-usage', + ] }, - - 'vendor/compatibility-matrix-usage', ], }, {