Manual QHx Proxy Sidecar Configuration

This guide shows how to add QHx Proxy to a Kubernetes workload manually to support Quantum Helix.

Objectives

• Support post-quantum-secure, mutually authenticated communications for a workload based on a cryptographic workload identity.
• Avoid the need for application modification.

Example Server Application

Suppose an existing workload is defined as the following Kubernetes pod (or deployment, stateful set, etc.):

---
apiVersion: v1
kind: Pod
metadata:
  name: app-server
  namespace: example
spec:
  serviceAccountName: app-server
  containers:
    - name: app-server
      image: "my-app-server:latest"

The following modified configuration demonstrates the addition of QHx Proxy as a sidecar container:

---
apiVersion: v1
kind: Pod
metadata:
  name: app-server
  namespace: example
spec:
  serviceAccountName: app-server

  containers:
    - name: app-server
      image: "my-app-server:latest"

    ### --- Add proxy sidecar ---
    - name: qhx-proxy
      image: "oci.messier42.com/qhx/proxy:v${RELEASE_VERSION}"
      imagePullPolicy: Always
      ports:
        - name: http
          containerPort: 8081
      volumeMounts:
        - name: spiffe-workload-api
          mountPath: /spiffe-workload-api
          readOnly: true
      securityContext:
        runAsNonRoot: true
        runAsUser: 1001
        runAsGroup: 1001
        allowPrivilegeEscalation: false
        capabilities:
          drop: [ALL]
      env:
        - name: QHX_PROXY_CONFIG
          value: |
            spiffe:
              workload_socket_path: unix:///spiffe-workload-api/agent.sock
            listeners:
              - name: server
                address: "0.0.0.0:8081"
                protocol: http
                mode: server
                target:
                  # Configure local application server endpoint to forward
                  # requests to.
                  url: http://localhost:11434
                source:
                  # Configure permitted source workload identities
                  # (e.g. namespace 'example', service account 'app-client').
                  spiffe_ids:
                    - '^spiffe://qhx.dev/ns/example/sa/app-client/.*$'
                middlewares: []
                timeouts:
                  read: 600s
                  write: 600s
                  idle: 600s
  volumes:

    ### --- Add workload API volume ---
    - name: spiffe-workload-api
      csi:
        driver: csi.spiffe.io
        readOnly: true

Example Client Application

Suppose an existing workload is defined as the following Kubernetes pod (or deployment, stateful set, etc.):

---
apiVersion: v1
kind: Pod
metadata:
  name: app-client
  namespace: example
spec:
  serviceAccountName: app-client
  containers:
    - name: app-client
      image: "my-app-client:latest"

The following modified configuration demonstrates the addition of QHx Proxy as a sidecar container:

---
apiVersion: v1
kind: Pod
metadata:
  name: app-client
  namespace: example
spec:
  serviceAccountName: app-client

  containers:
    - name: app-client
      image: "my-app-client:latest"

    ### --- Add proxy sidecar ---
    - name: qhx-proxy
      image: "oci.messier42.com/qhx/proxy:v${RELEASE_VERSION}"
      imagePullPolicy: Always
      ports:
        - name: http
          containerPort: 8081
      volumeMounts:
        - name: spiffe-workload-api
          mountPath: /spiffe-workload-api
          readOnly: true
      securityContext:
        runAsNonRoot: true
        runAsUser: 1001
        runAsGroup: 1001
        allowPrivilegeEscalation: false
        capabilities:
          drop: [ALL]
      env:
        - name: QHX_PROXY_CONFIG
          value: |
            spiffe:
              workload_socket_path: unix:///spiffe-workload-api/agent.sock
            listeners:
              - name: client
                address: "0.0.0.0:8081"
                protocol: http
                mode: client
                target:
                  # Configure local application server endpoint to forward
                  # requests to.
                  url: http://app-server.example.svc.cluster.local:8081
                  spiffe_ids:
                    - '^spiffe://qhx.dev/ns/example/sa/app-server/.*$'
                middlewares: []
                timeouts:
                  read: 600s
                  write: 600s
                  idle: 600s

  volumes:

    ### --- Add workload API volume ---
    - name: spiffe-workload-api
      csi:
        driver: csi.spiffe.io
        readOnly: true