QHx Proxy TCP

This guide shows how to run QHx Proxy as a neutral carrier for TCP protocols transported over QHx mTLS in a direct client-server topology.

Server Pod

The server application listens on a local TCP port. QHx Proxy terminates mTLS on :19443 and forwards plaintext TCP to the local server.

apiVersion: v1
kind: Pod
metadata:
  name: tcp-server
  namespace: example
  labels:
    app: tcp-server
spec:
  serviceAccountName: tcp-server
  containers:
    - name: app-server
      image: "my-tcp-server:latest"
      ports:
        - containerPort: 5432

    - name: qhx-proxy
      image: "oci.messier42.com/qhx/proxy:v${RELEASE_VERSION}"
      imagePullPolicy: Always
      ports:
        - name: mtls
          containerPort: 19443
      volumeMounts:
        - name: spiffe-workload-api
          mountPath: /spiffe-workload-api
          readOnly: true
      env:
        - name: QHX_PROXY_CONFIG
          value: |
            spiffe:
              workload_socket_path: unix:///spiffe-workload-api/agent.sock
            listeners:
              - name: tcp-server
                address: "0.0.0.0:19443"
                protocol: tcp
                mode: server
                target:
                  url: tcp://127.0.0.1:5432
                source:
                  spiffe_ids:
                    - '^spiffe://qhx.dev/ns/example/sa/tcp-client/.*$'
  volumes:
    - name: spiffe-workload-api
      csi:
        driver: csi.spiffe.io
        readOnly: true

Expose the server proxy port with a ClusterIP service:

apiVersion: v1
kind: Service
metadata:
  name: tcp-server-proxy
  namespace: example
spec:
  selector:
    app: tcp-server
  ports:
    - name: mtls
      port: 19443
      targetPort: 19443

Client Pod

The client application connects to a local TCP port (e.g., 127.0.0.1:19081). QHx Proxy encapsulates that TCP stream over mTLS to the server proxy service.

apiVersion: v1
kind: Pod
metadata:
  name: tcp-client
  namespace: example
  labels:
    app: tcp-client
spec:
  serviceAccountName: tcp-client
  containers:
    - name: app-client
      image: "my-tcp-client:latest"
      env:
        - name: TCP_TARGET
          value: "127.0.0.1:19081"

    - name: qhx-proxy
      image: "oci.messier42.com/qhx/proxy:v${RELEASE_VERSION}"
      imagePullPolicy: Always
      volumeMounts:
        - name: spiffe-workload-api
          mountPath: /spiffe-workload-api
          readOnly: true
      env:
        - name: QHX_PROXY_CONFIG
          value: |
            spiffe:
              workload_socket_path: unix:///spiffe-workload-api/agent.sock
            listeners:
              - name: tcp-client
                address: "127.0.0.1:19081"
                protocol: tcp
                mode: client
                target:
                  url: "tls://tcp-server-proxy.example.svc.cluster.local:19443"
                  spiffe_ids:
                    - '^spiffe://qhx.dev/ns/example/sa/tcp-server/.*$'
  volumes:
    - name: spiffe-workload-api
      csi:
        driver: csi.spiffe.io
        readOnly: true