Proto: virtual_destination.proto

Package: networking.gloo.solo.io

Set up intelligent multicluster routing for active-active and active-passive workloads in your environment by using VirtualDestinations. VirtualDestinations allow you to define unique internal hostnames for apps that are spread across multiple clusters, and route to these apps via these hostnames.

For more information, see the Routing overview concept docs.

Examples

East-west: This resource creates a VirtualDestination for a backing destination that receives requests from an initiator app. This VirtualDestination is configured to listen for incoming traffic on the internal-only, arbitrary hostname destination-app.mesh.internal.com:8080. Incoming requests can then be routed to any service instances with the label app: destination-app on port 9080. Note that because VirtualDestinations are dynamic, the east-west gateway that handles the request routes it to the closest healthy app instance.

  apiVersion: networking.gloo.solo.io/v2
kind: VirtualDestination
metadata:
  name: destination-app-vd
  namespace: global
spec:
  hosts:
  # Arbitrary, internal-only hostname assigned to the endpoint
  - destination-app.mesh.internal.com
  ports:
  - number: 8080
    protocol: HTTP
    targetPort:
      number: 9080
  services:
    - labels:
        app: destination-app

North-south: This resource creates a VirtualDestination that defines a unique hostname that the virtual gateway serves traffic on. This VirtualDestination is configured to listen for incoming traffic on the hostname my.app.com:8080. Incoming requests can then be routed to any service instances with the label app: global-app on port 9080. Note that because VirtualDestinations are dynamic, the ingress gateway load balances the request across healthy app instances.

  apiVersion: networking.gloo.solo.io/v2
kind: VirtualDestination
metadata:
  name: global-app-vd
  namespace: global
spec:
  hosts:
  # Hostname assigned to the endpoint
  - my.app.com
  ports:
  - number: 8080
    protocol: HTTP
    targetPort:
      number: 9080
  services:
    - labels:
        app: global-app

VirtualDestinationReport

The resources that the VirtualDestination selects after it is successfully applied.

FieldDescription
workspaces(repeated VirtualDestinationReport.WorkspacesEntry)

A list of workspaces in which the virtal destination can be applied.
appliedDestinationPolicies(repeated VirtualDestinationReport.AppliedDestinationPoliciesEntry)

A map of policy GVK to policy references for all policies that are applied on this resource.
selectedBackingServices(repeated common.gloo.solo.io.DestinationReference)

A list of destinations that back this VirtualDestination.
ownerWorkspace(string)

The name of the workspace that owns the VirtualDestination.

VirtualDestinationReport.AppliedDestinationPoliciesEntry

FieldDescription
key(string)

value(common.gloo.solo.io.AppliedDestinationPortPolicies)

VirtualDestinationReport.WorkspacesEntry

FieldDescription
key(string)

value(common.gloo.solo.io.Report)

VirtualDestinationSpec

Specifications for the VirtualDestination resource.


Note: If services, externalServices, and externalWorkloads are all empty, then you must also create a RouteTable resource to accompany this VirtualDestination.


Configuration constraints: At least one of hosts, services, externalServices, or externalWorkloads must be set.

FieldDescription
hosts(repeated string)

Optional: The set of custom hosts for which this VirtualDestination will serve traffic.

Configuration constraints:
  • The hostname(s) must be unique to other hosts in this resource. However, it is recommended that you also make hosts unique globally in your Gloo environment to avoid collisions.
  • The hostname cannot equal the wildcard host or contain the wildcard character "*".
  • Each hostname must follow these requirements:
    • Hostnames must be 1 - 255 characters in length.
    • The hostname cannot be an empty string.
    • Supported characters are a-z, A-Z, 0-9, -, and ..
    • Each segment separated by a period (.) must be 1 - 63 characters in length and cannot start with the - character.
    • Each segment must meet the regex ^[a-zA-Z0-9](?:[-a-zA-Z0-9]*[a-zA-Z0-9])?$.
    • The top-level domain (last segment), such as com in www.example.com, cannot be all numeric characters.
    • The top-level domain (last segment) can be empty, such as "istio.io.".
services(repeated common.gloo.solo.io.ObjectSelector)

Selectors for the backing Kubernetes services that comprise this VirtualDestination. A service is selected when it matches any of the provided selectors. Currently only one Kubernetes service can be selected per cluster. If more than one service is selected within a cluster, the VirtualDestination reports a warning, and the oldest created service is selected. When a request is routed through the VirtualDestination, it is forwarded to one of the backing services, selected at random. To forward traffic to the service on the local cluster first, create a FailoverPolicy and an OutlierDetectionPolicy. If a deployment is unavailable, requests are not forwarded to that deployment.
externalServices(repeated common.gloo.solo.io.ObjectSelector)

Selectors for the backing External services that comprise this VirtualDestination. An external service is selected when it matches any of the provided selectors. Multiple External Services can be selected.
externalWorkloads(repeated common.gloo.solo.io.ObjectSelector)

Selectors for the backing ExternalWorkloads that comprise this VirtualDestination. Currently only one ExternalWorkload can be selected per cluster. If more than one external workload is selected within a cluster, the VirtualDestination reports a warning, and the oldest created external workload is selected. When a request is routed through the VirtualDestination, it is forwarded to one of the backing external workloads, selected at random. To forward traffic to the service on the local cluster first, create a FailoverPolicy and an OutlierDetectionPolicy.
ports(repeated VirtualDestinationSpec.PortMapping)

Required: The port(s) on which the VirtualDestination serves traffic.

Configuration constraints: At least one port is required.
clientMode(common.gloo.solo.io.ClientMode)

Optional: The way in which the VirtualDestination is translated. If nil, the mode is inherited from the WorkspaceSettings resource for the workspace.

VirtualDestinationSpec.PortMapping

A new port that is exposed on a VirtualDestination.

FieldDescription
number(uint32)

The port number.

Configuration constraints:
  • This field is required.
  • The port number must be in the range 1 - 65535, inclusive.
protocol(string)

The protocol used in communication with this destination. Note that the VirtualDestination protocol may not match the protocol of the backing Kubernetes service(s). For example, VirtualDestinations pointing to gRPC services require the protocol to equal GRPC. The prefix of the Kubernetes service port’s name typically matches the required protocol.

Configuration constraints:
  • This field is required.
  • The value must equal one of the following: HTTP, HTTPS, GRPC, HTTP2, MONGO, TCP, TLS.
targetPort(common.gloo.solo.io.PortSelector)

Optional: The port number or name used to match the corresponding port on the VirtualDestination’s backing services and external services. All of the backing services for this VirtualDestination must contain this port, matching by name or number. If unspecified, this field defaults to the value of the port number.

Configuration constraints: If services, externalServices, and externalWorkloads are all empty, this field must be empty.

VirtualDestinationStatus

The status of the resource after it is applied to your Gloo environment.

FieldDescription
common(common.gloo.solo.io.Status)

The state and workspace conditions of the applied resource.
numAppliedDestinationPolicies(repeated VirtualDestinationStatus.NumAppliedDestinationPoliciesEntry)

A map of policy GVK to policy references for all policies that are applied on this resource.
numSelectedBackingServices(uint32)

The number of destinations (across all clusters) that back this VirtualDestination.
ownedByWorkspace(string)

The name of the workspace that owns the VirtualDestination.

VirtualDestinationStatus.NumAppliedDestinationPoliciesEntry

FieldDescription
key(string)

value(uint32)