Skip to main content
Version: 0.6.x

Pod Annotations Reference

This document provides a comprehensive reference for all pod annotations available in interLink. These annotations allow you to customize pod behavior, configure networking, and control various aspects of pod execution.

Overview​

InterLink supports several categories of annotations:

VPN & Networking​

interlink.eu/pod-vpn​

Enables VPN connectivity for the pod, allowing it to access the cluster's internal network.

Usage:

apiVersion: v1
kind: Pod
metadata:
  name: my-pod
  annotations:
    interlink.eu/pod-vpn: "true"
spec:
  containers:
  - name: app
    image: nginx:latest

Behavior:

  • When present, the pod will be assigned an IP from the virtual node's CIDR range
  • Enables connectivity to Kubernetes services and other pods
  • Requires proper VPN configuration on the interLink deployment
  • Takes precedence over wstunnel networking features

Default: Not set (VPN disabled)

interlink.eu/pod-ip​

Specifies or retrieves the assigned IP address for the pod.

Usage:

apiVersion: v1
kind: Pod
metadata:
  name: my-pod
  annotations:
    interlink.eu/pod-ip: "10.244.1.100"
spec:
  containers:
  - name: app
    image: nginx:latest

Behavior:

  • Can be manually set to request a specific IP (subject to availability)
  • Automatically populated by interLink when VPN is enabled
  • Used internally for IP allocation and tracking
  • IP must be within the configured CIDR range

Default: Automatically assigned when VPN is enabled

Mesh Networking​

interlink.eu/mesh-network​

Disables mesh networking for a specific offloaded pod when set to "disabled".

Usage:

apiVersion: v1
kind: Pod
metadata:
  name: my-pod
  annotations:
    interlink.eu/mesh-network: "disabled"
spec:
  containers:
  - name: app
    image: nginx:latest

Behavior:

  • When set to "disabled", the pod is offloaded without mesh networking even if the global FullMesh configuration is enabled
  • Disables the WireGuard/wstunnel bidirectional communication setup for this pod
  • All other pods without this annotation continue to use mesh networking as configured
  • Value matching is case-insensitive (e.g., "Disabled", "DISABLED" also work)

Default: Not set (mesh networking follows global FullMesh configuration)

Wstunnel Integration​

interlink.virtual-kubelet.io/wstunnel-timeout​

Configures the timeout for wstunnel infrastructure creation and IP assignment.

Usage:

apiVersion: v1
kind: Pod
metadata:
  name: my-pod
  annotations:
    interlink.virtual-kubelet.io/wstunnel-timeout: "60s"
spec:
  containers:
  - name: web-server
    image: nginx:latest
    ports:
    - containerPort: 80
      name: http

Behavior:

  • Only effective when wstunnel feature is enabled (Network.EnableTunnel: true)
  • Applies to pods with exposed ports and no VPN annotation
  • Controls how long to wait for the wstunnel pod to get an IP address
  • If timeout is exceeded, pod creation fails and resources are cleaned up

Valid Values:

  • Duration strings: 30s, 1m, 2m30s, 10m
  • Must be parseable by Go's time.ParseDuration()

Default: 30s

interlink.eu/wstunnel-client-commands​

Contains the complete wstunnel client command to connect to exposed ports from a remote location.

Usage:

apiVersion: v1
kind: Pod
metadata:
  name: my-pod
  annotations:
    interlink.eu/wstunnel-client-commands: |
      curl -L https://github.com/erebe/wstunnel/releases/latest/download/wstunnel-linux-x64 -o wstunnel && chmod +x wstunnel
      
      ./wstunnel client --http-upgrade-path-prefix a1b2c3d4 -R tcp://[::]:8080:localhost:8080 -R tcp://[::]:9090:localhost:9090 ws://my-pod-wstunnel.example.com:80
spec:
  containers:
  - name: web-server
    image: nginx:latest
    ports:
    - containerPort: 8080
      name: http
    - containerPort: 9090
      name: metrics

Behavior:

  • Automatically generated by interLink when wstunnel feature is enabled
  • Only added to pods with exposed ports and no VPN annotation
  • Contains the complete command with download instructions and client connection
  • Includes unique random password for secure tunnel authentication
  • Multiple ports are handled with multiple -R options in a single command
  • Uses the configured wildcard DNS or service name for ingress endpoint

Command Structure:

  1. Download: Downloads the latest wstunnel binary for Linux x64
  2. Connect: Establishes websocket tunnel with:
    • --http-upgrade-path-prefix: Unique password for authentication
    • -R tcp://[::]:PORT:localhost:PORT: Port forwarding rules (one per exposed port)
    • ws://ENDPOINT:80: Websocket endpoint (ingress URL)

Default: Set automatically by interLink when wstunnel is enabled

interlink.eu/wstunnel-extra-ports​

Specifies additional ports to forward through the wstunnel beyond those defined in the pod specification.

Usage:

apiVersion: v1
kind: Pod
metadata:
  name: my-pod
  annotations:
    interlink.eu/wstunnel-extra-ports: "8080,9090:metrics:UDP,3000:api"
spec:
  containers:
  - name: web-server
    image: nginx:latest
    ports:
    - containerPort: 80
      name: http

Format:

  • Simple port: 8080 - Forward port 8080 with TCP protocol
  • Named port: 9090:metrics - Forward port 9090 with name "metrics" and TCP protocol
  • Full specification: 3000:api:UDP - Forward port 3000 with name "api" and UDP protocol
  • Multiple ports: 8080,9090:metrics:UDP,3000:api - Comma-separated list

Behavior:

  • Only effective when wstunnel feature is enabled (Network.EnableTunnel: true)
  • Allows forwarding ports not explicitly defined in container specs
  • Useful for internal services, debug ports, or dynamic port allocation
  • Ports are added to the generated wstunnel client command
  • Invalid port specifications are silently ignored

Protocol Support:

  • TCP (default if not specified)
  • UDP
  • Case-insensitive protocol names

Default: Not set (no additional ports forwarded)

Job Management​

JobID​

Tracks the remote job identifier for pods executed through interLink.

Usage:

apiVersion: v1
kind: Pod
metadata:
  name: my-pod
  annotations:
    JobID: "slurm-12345"
spec:
  containers:
  - name: compute
    image: ubuntu:latest
    command: ["sleep", "3600"]

Behavior:

  • Automatically set by interLink when a pod is successfully submitted to a remote system
  • Used to correlate Kubernetes pods with remote jobs (e.g., SLURM, PBS, Docker)
  • Required for pod status tracking and lifecycle management
  • Used during cluster restart to reassign pods to the virtual kubelet

Default: Set automatically by interLink

System Annotations​

interlink.virtual-kubelet.io/ping-response​

Stores the response from interLink API health checks.

Usage: This annotation is set automatically by the virtual kubelet.

Behavior:

  • Updated during periodic health checks to the interLink API
  • Contains the response body from successful ping operations
  • Used for monitoring and debugging connectivity issues
  • Visible in node annotations, not pod annotations

Default: Set automatically by virtual kubelet

Configuration Examples​

Basic Pod with VPN​

apiVersion: v1
kind: Pod
metadata:
  name: vpn-enabled-pod
  annotations:
    interlink.eu/pod-vpn: "true"
spec:
  containers:
  - name: app
    image: nginx:latest
    ports:
    - containerPort: 80
  restartPolicy: Never

Pod with Wstunnel (No VPN)​

apiVersion: v1
kind: Pod
metadata:
  name: wstunnel-pod
  annotations:
    interlink.virtual-kubelet.io/wstunnel-timeout: "2m"
spec:
  containers:
  - name: web-server
    image: nginx:latest
    ports:
    - containerPort: 80
      name: http
    - containerPort: 443
      name: https
  restartPolicy: Never

Pod with Custom IP​

apiVersion: v1
kind: Pod
metadata:
  name: custom-ip-pod
  annotations:
    interlink.eu/pod-vpn: "true"
    interlink.eu/pod-ip: "10.244.1.50"
spec:
  containers:
  - name: app
    image: alpine:latest
    command: ["sleep", "3600"]
  restartPolicy: Never

Best Practices​

VPN Configuration​

  • Use VPN annotations when pods need to access Kubernetes services
  • Ensure CIDR ranges are properly configured in the virtual kubelet config
  • Monitor IP allocation to avoid conflicts

Wstunnel Usage​

  • Enable wstunnel only when needed for external port access
  • Use appropriate timeouts based on your infrastructure
  • Remember that wstunnel and VPN are mutually exclusive

Job Management​

  • Never manually set JobID annotations
  • Use JobID for debugging and monitoring remote job execution
  • Check JobID presence to verify successful job submission

Networking Considerations​

  • VPN takes precedence over wstunnel networking
  • Pods with exposed ports automatically trigger wstunnel creation (if enabled)
  • Use interlink.eu/pod-vpn for internal cluster communication
  • Use wstunnel for external port exposure without VPN overhead

Troubleshooting​

Common Issues​

  1. Pod IP not assigned

    • Check VPN configuration and CIDR settings
    • Verify interlink.eu/pod-vpn annotation syntax
    • Review virtual kubelet logs for IP allocation errors

  2. Wstunnel timeout errors

    • Increase timeout with interlink.virtual-kubelet.io/wstunnel-timeout
    • Check network connectivity and DNS resolution
    • Verify wstunnel template and configuration

  3. Job not tracked

    • Verify JobID annotation is set after pod creation
    • Check interLink API connectivity
    • Review plugin logs for job submission errors

Debug Commands​

# Check pod annotations
kubectl get pod <pod-name> -o yaml | grep -A 10 annotations

# Check virtual kubelet node annotations
kubectl get node <vk-node-name> -o yaml | grep -A 5 annotations

# Check wstunnel resources (if applicable)
kubectl get deployment,service,ingress -l interlink.virtual-kubelet.io/type=wstunnel

Version Compatibility​

AnnotationVersionNotes
interlink.eu/pod-vpnv0.1.0+Core VPN functionality
interlink.eu/pod-ipv0.1.0+IP allocation and tracking
JobIDv0.1.0+Remote job management
interlink.virtual-kubelet.io/wstunnel-timeoutv0.6.0+Wstunnel integration
interlink.virtual-kubelet.io/ping-responsev0.2.0+Health check responses
interlink.eu/mesh-networkv0.6.x+Per-pod mesh networking opt-out