​
Overview

The cpln port-forward command securely connects your local machine with workloads running inside a Global Virtual Cloud (GVC), enabling private and secure interaction without the need for public exposure. This allows users to access applications, such as databases or internal services, that are deployed as workloads.

This functionality is directly analogous to Kubernetes’ kubectl port-forward, providing users with a familiar way to debug, manage, and interact with workloads running inside a GVC environment from their local machine.

Addresses specified can include local or LAN-accessible IP addresses. You can also specify ports using either the format :<port> or <port> alone, allowing the system to assign a local ephemeral port automatically.

You can port-forward to any port in a workload, even if that port isn’t exposed by any running container.

​
Prerequisites

​
Options

​
Optional

  • --address
    • Local addresses to listen on, separated by commas if specifying multiple addresses. Defaults to localhost.
  • --location
    • The location associated with the workload deployment (e.g., aws-us-west-1). Defaults to the first location fetched from the specified GVC. When specifying, make sure that the specified location is part of the specified GVC.
  • --replica
    • The specific replica within the workload. If not specified, a different replica is chosen for every connection that is made.

​
Usage

​
Basic Port Forward

To forward a single local port to a port on a workload, use the following format:

cpln port-forward <workload-name> <local-port>:<container-port> --location <location> --org <org> --gvc <gvc>

Example:

Forward local port 5432 to workload container port 5432 of a database workload named db-workload:

cpln port-forward db-workload 5432:5432 --location aws-us-west-1 --org demo-org --gvc demo-gvc

​
Assigning Local Ephemeral Port

To allow the system to automatically assign a local ephemeral port, use either of these formats:

cpln port-forward db-workload :80 --location aws-us-west-1 --org demo-org --gvc demo-gvc

​
Assigning the Same Local and Remote Port

To forward a local port that matches the remote workload port, specify the port number without :. This ensures direct port mapping, which can be useful for applications requiring a fixed port assignment.

cpln port-forward db-workload 80 --location aws-us-west-1 --org demo-org --gvc demo-gvc

​
Forwarding to Multiple Addresses

You can forward to multiple addresses by specifying them as a comma-separated list in the --address option:

cpln port-forward db-workload 5432:5432 --address 127.0.0.1,192.168.0.10 --location aws-us-west-1 --org demo-org --gvc demo-gvc

​
Forwarding Multiple Ports

To forward multiple ports simultaneously, specify each pair separated by spaces:

cpln port-forward db-workload 8080:80 8443:443 --location aws-us-west-1 --org demo-org --gvc demo-gvc

​
Combining Multiple Ports and Addresses

You can combine multiple ports and multiple addresses:

cpln port-forward db-workload 8080:80 8443:443 --address 127.0.0.1,192.168.0.10 --location aws-us-west-1 --org demo-org --gvc demo-gvc

This will forward ports 80 and 443 from the workload to local ports 8080 and 8443 on both specified local addresses.