You are browsing unreleased documentation. See the latest documentation here.

MeshPassthrough

This policy uses new policy matching algorithm.

This policy enables Kong Mesh to configure traffic to external destinations that is allowed to pass outside the mesh. When using this policy, the passthrough mode flag is ignored.

TargetRef support matrix

To learn more about the information in this table, see the matching docs.

Configuration

This policy doesn’t work with sidecars without transparent-proxy.

The following describes the default configuration settings of the MeshPassthrough policy:

• passthroughMode: (Optional) Defines behaviour for handling traffic. Allowed values: All, None and Matched. Default: None
  • All enables all traffic to pass through.
  • Matched allows only the traffic defined in appendMatch.
  • None disallows all traffic.
• appendMatch: List of destinations that are allowed to pass through. When passthroughMode is All or None this list is not used. It only takes effect when passthroughMode is Matched.
  • type: Defines what type of destination is allowed. Either Domain, IP or CIDR.
  • value: Destination address based on the defined type.
  • port: Port at which external destination is available. When not defined it caches all traffic to the address.
  • protocol: Defines protocol of the external destination.
    • tcp: Can’t be used when type is Domain (at TCP level we are not able to distinguish domain, in this case it is going to hijack whole traffic on this port).
    • tls: Should be used when TLS traffic is originated by the client application.
    • http
    • http2
    • grpc
    • mysql

Wildcard DNS matching

MeshPassthrough policy allows you to create a match for a wildcard subdomain.

Currently, support for partial subdomain matching is not implemented. For example, a match for *w.example.com will be rejected.

apiVersion: kuma.io/v1alpha1
kind: MeshPassthrough
metadata:
  name: wildcard-passthrough
  namespace: kong-mesh-system
  labels:
    kuma.io/mesh: default
spec:
  targetRef:
    kind: Dataplane
  default:
    passthroughMode: Matched
    appendMatch:
    - type: Domain
      value: "*.cluster-1.kafka.aws.us-east-2.com"
      protocol: tls
      port: 443

type: MeshPassthrough
name: wildcard-passthrough
mesh: default
spec:
  targetRef:
    kind: Dataplane
  default:
    passthroughMode: Matched
    appendMatch:
    - type: Domain
      value: "*.cluster-1.kafka.aws.us-east-2.com"
      protocol: tls
      port: 443

resource "konnect_mesh_passthrough" "wildcard_passthrough" {
  provider = konnect-beta
  type = "MeshPassthrough"
  name = "wildcard-passthrough"
  spec = {
    target_ref = {
      kind = "Dataplane"
    }
    default = {
      passthrough_mode = "Matched"
      append_match = [
        {
          type = "Domain"
          value = "*.cluster-1.kafka.aws.us-east-2.com"
          protocol = "tls"
          port = "443"
        }
      ]
    }
  }
  labels   = {
    "kuma.io/mesh" = konnect_mesh.my_mesh.name
  }
  cp_id    = konnect_mesh_control_plane.my_meshcontrolplane.id
  mesh     = konnect_mesh.my_mesh.name
}

Security

It is advised that the Mesh Operator is responsible for managing the MeshPassthrough policy. This policy can introduce traffic outside of the mesh or even the cluster, and the Mesh Operator should be aware of this. If you want to restrict access to MeshPassthrough to specific services, you must choose them manually. If you rely on tags in the top-level targetRef you might consider securing them by using one of the following techniques:

• Make sure that service owners can’t freely modify them (using something like kyverno, OPA or similar)
• Accept the risk of being able to “impersonate” a passthrough label and rely on auditing to figure out any violations.

Limitations

• Due to the nature of some traffic, it is not possible to combine certain protocols on the same port. You can create a MeshPassthrough policy that handles tcp, tls, and one of http, http2, or grpc traffic on the same port. Layer 7 protocols cannot be distinguished, which could introduce unexpected behavior.
• It isn’t possible to route passthrough traffic through the zone egress.
• Wildcard domains with L7 protocol and all ports is not supported.
• Builtin gateway is not supported.
• Envoy prioritizes matches in the following order: first by Port, second by Address IP, and third by SNI. For example, if you have an HTTP domain match configured for a specific port (e.g., 80) and a CIDR match also configured for port 80, a request to this domain may match the CIDR configuration if the domain’s address falls within the CIDR range. However, if the domain’s address does not match the CIDR, the request might fail to match entirely due to the absence of an appropriate matcher for that IP. This behavior is a limitation and could potentially be addressed in the future with the adoption of the Matcher API.

Examples

Disable passthrough for all sidecars

apiVersion: kuma.io/v1alpha1
kind: MeshPassthrough
metadata:
  name: disable-passthrough
  namespace: kong-mesh-system
  labels:
    kuma.io/mesh: default
spec:
  targetRef:
    kind: Dataplane
  default:
    passthroughMode: None

type: MeshPassthrough
name: disable-passthrough
mesh: default
spec:
  targetRef:
    kind: Dataplane
  default:
    passthroughMode: None

resource "konnect_mesh_passthrough" "disable_passthrough" {
  provider = konnect-beta
  type = "MeshPassthrough"
  name = "disable-passthrough"
  spec = {
    target_ref = {
      kind = "Dataplane"
    }
    default = {
      passthrough_mode = "None"
    }
  }
  labels   = {
    "kuma.io/mesh" = konnect_mesh.my_mesh.name
  }
  cp_id    = konnect_mesh_control_plane.my_meshcontrolplane.id
  mesh     = konnect_mesh.my_mesh.name
}

Enable passthrough for a subset of sidecars

apiVersion: kuma.io/v1alpha1
kind: MeshPassthrough
metadata:
  name: enable-passthrough
  namespace: kong-mesh-system
  labels:
    kuma.io/mesh: default
spec:
  targetRef:
    kind: Dataplane
    labels:
      app: demo-app
  default:
    passthroughMode: All

type: MeshPassthrough
name: enable-passthrough
mesh: default
spec:
  targetRef:
    kind: Dataplane
    labels:
      app: demo-app
  default:
    passthroughMode: All

resource "konnect_mesh_passthrough" "enable_passthrough" {
  provider = konnect-beta
  type = "MeshPassthrough"
  name = "enable-passthrough"
  spec = {
    target_ref = {
      kind = "Dataplane"
      labels = {
        app = "demo-app"
      }
    }
    default = {
      passthrough_mode = "All"
    }
  }
  labels   = {
    "kuma.io/mesh" = konnect_mesh.my_mesh.name
  }
  cp_id    = konnect_mesh_control_plane.my_meshcontrolplane.id
  mesh     = konnect_mesh.my_mesh.name
}

Allow a subset of services to communicate with specific external endpoints

apiVersion: kuma.io/v1alpha1
kind: MeshPassthrough
metadata:
  name: allow-some-passthrough
  namespace: kong-mesh-system
  labels:
    kuma.io/mesh: default
spec:
  targetRef:
    kind: Dataplane
    labels:
      app: demo-app
  default:
    passthroughMode: Matched
    appendMatch:
    - type: Domain
      value: httpbin.org
      protocol: tls
      port: 443
    - type: IP
      value: 10.240.15.39
      protocol: tcp
      port: 8888
    - type: CIDR
      value: 10.250.0.0/16
      protocol: tcp
      port: 10000
    - type: Domain
      value: "*.wikipedia.org"
      protocol: tls
      port: 443
    - type: Domain
      value: httpbin.dev
      protocol: http
      port: 80

type: MeshPassthrough
name: allow-some-passthrough
mesh: default
spec:
  targetRef:
    kind: Dataplane
    labels:
      app: demo-app
  default:
    passthroughMode: Matched
    appendMatch:
    - type: Domain
      value: httpbin.org
      protocol: tls
      port: 443
    - type: IP
      value: 10.240.15.39
      protocol: tcp
      port: 8888
    - type: CIDR
      value: 10.250.0.0/16
      protocol: tcp
      port: 10000
    - type: Domain
      value: "*.wikipedia.org"
      protocol: tls
      port: 443
    - type: Domain
      value: httpbin.dev
      protocol: http
      port: 80

resource "konnect_mesh_passthrough" "allow_some_passthrough" {
  provider = konnect-beta
  type = "MeshPassthrough"
  name = "allow-some-passthrough"
  spec = {
    target_ref = {
      kind = "Dataplane"
      labels = {
        app = "demo-app"
      }
    }
    default = {
      passthrough_mode = "Matched"
      append_match = [
        {
          type = "Domain"
          value = "httpbin.org"
          protocol = "tls"
          port = "443"
        },
        {
          type = "IP"
          value = "10.240.15.39"
          protocol = "tcp"
          port = "8888"
        },
        {
          type = "CIDR"
          value = "10.250.0.0/16"
          protocol = "tcp"
          port = "10000"
        },
        {
          type = "Domain"
          value = "*.wikipedia.org"
          protocol = "tls"
          port = "443"
        },
        {
          type = "Domain"
          value = "httpbin.dev"
          protocol = "http"
          port = "80"
        }
      ]
    }
  }
  labels   = {
    "kuma.io/mesh" = konnect_mesh.my_mesh.name
  }
  cp_id    = konnect_mesh_control_plane.my_meshcontrolplane.id
  mesh     = konnect_mesh.my_mesh.name
}

Allow a service to communicate with MySQL

The mysql protocol does not support type: Domain due to the nature of the handshake and an Envoy limitation that disrupts the connection to MySQL when using inspector.

apiVersion: kuma.io/v1alpha1
kind: MeshPassthrough
metadata:
  name: allow-mysql-connection
  namespace: kong-mesh-system
  labels:
    kuma.io/mesh: default
spec:
  targetRef:
    kind: Dataplane
    labels:
      app: demo-app
  default:
    passthroughMode: Matched
    appendMatch:
    - type: CIDR
      value: 10.250.0.0/16
      protocol: mysql
      port: 3306

type: MeshPassthrough
name: allow-mysql-connection
mesh: default
spec:
  targetRef:
    kind: Dataplane
    labels:
      app: demo-app
  default:
    passthroughMode: Matched
    appendMatch:
    - type: CIDR
      value: 10.250.0.0/16
      protocol: mysql
      port: 3306

resource "konnect_mesh_passthrough" "allow_mysql_connection" {
  provider = konnect-beta
  type = "MeshPassthrough"
  name = "allow-mysql-connection"
  spec = {
    target_ref = {
      kind = "Dataplane"
      labels = {
        app = "demo-app"
      }
    }
    default = {
      passthrough_mode = "Matched"
      append_match = [
        {
          type = "CIDR"
          value = "10.250.0.0/16"
          protocol = "mysql"
          port = "3306"
        }
      ]
    }
  }
  labels   = {
    "kuma.io/mesh" = konnect_mesh.my_mesh.name
  }
  cp_id    = konnect_mesh_control_plane.my_meshcontrolplane.id
  mesh     = konnect_mesh.my_mesh.name
}

All policy options