Kubernetes – sidecar

Create a service mesh directly with VeilNet by running Conflux as a sidecar in Kubernetes pods—no additional service mesh solution required.

You can create a service mesh directly with VeilNet—without adding another service mesh solution (e.g. Istio or Linkerd). This guide uses Conflux as a sidecar in your Kubernetes pods (K3s, RKE2, or any distribution). Your application containers share the pod's network namespace with veilnet-conflux, giving them direct access to the VeilNet TUN device and enabling direct communication between services using VeilNet IP addresses—no separate mesh required.

Note TUN device created by VeilNet Conflux is a virtual network interface that exists within the pod's network namespace. It is not visible on the host network, unless you enable host network mode in the pod's spec. Therefore, NET_ADMIN capability is required by the sidecar container to create the TUN device.

Example: Deployment with VeilNet Conflux Sidecar

Here's an example manifest that deploys an application with veilnet-conflux as a sidecar:

apiVersion: v1
kind: Secret
metadata:
  name: veilnet-conflux-secret
  namespace: default
type: Opaque
stringData:
  VEILNET_REGISTRATION_TOKEN: <YOUR_REGISTRATION_TOKEN>
  VEILNET_GUARDIAN: <YOUR_GUARDIAN_URL>
  VEILNET_CONFLUX_TAG: <YOUR_CONFLUX_TAG>
  VEILNET_CONFLUX_IP: <YOUR_VEILNET_IP>
  VEILNET_CONFLUX_TAINTS: "<YOUR_TAINTS>"
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
  namespace: default
spec:
  replicas: 1
  selector:
    matchLabels:
      app: my-app
  template:
    metadata:
      labels:
        app: my-app
    spec:
      containers:
      # VeilNet Conflux sidecar - must be first container
      - name: veilnet-conflux
        image: veilnet/conflux:Beta-v1.0.8
        imagePullPolicy: Always
        securityContext:
          capabilities:
            add:
              - NET_ADMIN
        volumeMounts:
          - name: dev-net-tun
            mountPath: /dev/net/tun
        envFrom:
          - secretRef:
              name: veilnet-conflux-secret
        resources:
          requests:
            memory: "64Mi"
            cpu: "50m"
          limits:
            memory: "128Mi"
            cpu: "100m"
      # Your application container
      - name: app
        image: your-app:latest
        ports:
          - containerPort: 8080
            name: http
        # Application shares network namespace with veilnet-conflux
        # Access other services via VeilNet IP addresses
        resources:
          requests:
            memory: "256Mi"
            cpu: "100m"
          limits:
            memory: "512Mi"
            cpu: "500m"
      volumes:
        - name: dev-net-tun
          hostPath:
            path: /dev/net/tun
            type: CharDevice
      # All containers in the pod share the same network namespace
      # This is the default behavior in Kubernetes
---
apiVersion: v1
kind: Service
metadata:
  name: my-app
  namespace: default
spec:
  selector:
    app: my-app
  ports:
    - protocol: TCP
      port: 80
      targetPort: 8080
  type: ClusterIP

VEILNET_CONFLUX_TAINTS (comma-separated) is required so this Conflux can talk to peers with a compatible taint set. For a single-cluster sidecar, you usually do not need VEILNET_CONFLUX_PORTAL—omit it unless you explicitly want portal mode on that instance. Optionally add VEILNET_CONFLUX_RIFT when you need rift mode; see Rift and portal.

Multi-region or multi-cluster Kubernetes: when VeilNet spans clusters or regions, set VEILNET_CONFLUX_PORTAL: "true" on the Conflux instances that must advertise reachability across those boundaries (see below).

Key Points

Shared Network Namespace: All containers in a Kubernetes pod share the same network namespace by default, which achieves the same effect as Docker's network_mode: "container:veilnet-conflux".
Sidecar Container: The veilnet-conflux container runs as a sidecar alongside your application container in the same pod.
TUN Device Access: The sidecar needs access to /dev/net/tun and NET_ADMIN capability to create the VeilNet interface.
Environment Variables: Store VeilNet configuration in a Secret and reference it using envFrom. Use VEILNET_REGISTRATION_TOKEN, VEILNET_GUARDIAN, VEILNET_CONFLUX_TAG, VEILNET_CONFLUX_IP, and VEILNET_CONFLUX_TAINTS (required for connectivity with other nodes). Add VEILNET_CONFLUX_PORTAL and/or VEILNET_CONFLUX_RIFT only when you need those modes; see Rift and portal. Multi-region / multi-cluster: set VEILNET_CONFLUX_PORTAL: "true" where cross-region reachability is required.
Service Access: Your application can access other services using their VeilNet IP addresses, just like in the Docker setup.

Accessing Services

Once deployed, your application can:

Access services on other pods using their VeilNet IP addresses
Use the VeilNet TUN device directly through the shared network namespace
Communicate with services across different Kubernetes nodes via VeilNet

Example: Multi-Container Pod with Database

apiVersion: apps/v1
kind: Deployment
metadata:
  name: web-app-with-db
  namespace: default
spec:
  replicas: 1
  selector:
    matchLabels:
      app: web-app-with-db
  template:
    metadata:
      labels:
        app: web-app-with-db
    spec:
      containers:
      # VeilNet Conflux sidecar
      - name: veilnet-conflux
        image: veilnet/conflux:Beta-v1.0.8
        imagePullPolicy: Always
        securityContext:
          capabilities:
            add:
              - NET_ADMIN
        volumeMounts:
          - name: dev-net-tun
            mountPath: /dev/net/tun
        envFrom:
          - secretRef:
              name: veilnet-conflux-secret
      # Web application
      - name: web-app
        image: nginx:latest
        ports:
          - containerPort: 80
      # Database (shares network namespace)
      - name: database
        image: postgres:15-alpine
        env:
          - name: POSTGRES_DB
            value: mydb
          - name: POSTGRES_USER
            value: user
          - name: POSTGRES_PASSWORD
            value: password
        ports:
          - containerPort: 5432
      volumes:
        - name: dev-net-tun
          hostPath:
            path: /dev/net/tun
            type: CharDevice

In this example, all three containers (veilnet-conflux, web-app, and database) share the same network namespace, allowing them to communicate via localhost while also having access to the VeilNet network.

Docker – namespace sharing

Direct service mesh with VeilNet via Docker namespace sharing. No other solution needed.

Architecture Overview

Master, Guardian, and Conflux—post-quantum, identity-native overlay