mTLS Deployment Guide

This guide covers how to deploy InterLink using mutual TLS (mTLS) authentication as an alternative to OIDC. mTLS provides strong cryptographic authentication without requiring an external identity provider.

Overview

mTLS (mutual TLS) is a security protocol that provides authentication of both the client and server using digital certificates. In the context of InterLink, mTLS secures communication between the Virtual Kubelet running in your Kubernetes cluster and the InterLink API server running on the edge node.

Prerequisites

Before setting up mTLS, ensure you have:

1. A Certificate Authority (CA) certificate and private key
2. Server certificate and private key for the InterLink API server
3. Client certificate and private key for the Virtual Kubelet
4. Basic understanding of TLS/SSL certificate management

Certificate Generation

Generate Certificates for mTLS

# Generate CA private key
openssl genrsa -out ca-key.pem 4096

# Generate CA certificate
openssl req -new -x509 -days 365 -key ca-key.pem -sha256 -out ca.pem -subj "/C=US/ST=CA/L=San Francisco/O=InterLink/CN=InterLink CA"

# Generate server private key
openssl genrsa -out server-key.pem 4096

# Generate server certificate signing request
openssl req -subj "/C=US/ST=CA/L=San Francisco/O=InterLink/CN=interlink-server" -sha256 -new -key server-key.pem -out server.csr

# Generate server certificate signed by CA
openssl x509 -req -days 365 -sha256 -in server.csr -CA ca.pem -CAkey ca-key.pem -out server-cert.pem -extensions v3_req

# Generate client private key
openssl genrsa -out client-key.pem 4096

# Generate client certificate signing request
openssl req -subj "/C=US/ST=CA/L=San Francisco/O=InterLink/CN=interlink-client" -sha256 -new -key client-key.pem -out client.csr

# Generate client certificate signed by CA
openssl x509 -req -days 365 -sha256 -in client.csr -CA ca.pem -CAkey ca-key.pem -out client-cert.pem -extensions v3_req

# Clean up CSR files
rm server.csr client.csr

Edge Node Setup

Prepare Certificate Files

First, copy your generated certificates to the appropriate locations:

mkdir -p $HOME/.interlink/certs
mkdir -p $HOME/.interlink/config
mkdir -p $HOME/.interlink/logs
mkdir -p $HOME/.interlink/bin

# Copy certificates (assuming you generated them as shown above)
cp ca.pem server-cert.pem server-key.pem $HOME/.interlink/certs/
cp ca.pem client-cert.pem client-key.pem $HOME/.interlink/certs/

Create mTLS Configuration

Create the InterLink configuration file with mTLS settings:

$HOME/.interlink/config/InterLinkConfig.yaml

InterlinkAddress: https://0.0.0.0
InterlinkPort: "3000"
SidecarURL: http://plugin
SidecarPort: "4000"
VerboseLogging: true
ErrorsOnlyLogging: false
DataRootFolder: "/tmp/interlink"

# mTLS Configuration
TLS:
  Enabled: true
  CertFile: "/home/myusername/.interlink/certs/server-cert.pem"
  KeyFile: "/home/myusername/.interlink/certs/server-key.pem"
  CACertFile: "/home/myusername/.interlink/certs/ca.pem"

Download and Configure InterLink Binary

export VERSION=$(curl -s https://api.github.com/repos/interlink-hq/interlink/releases/latest | jq -r .name)
wget -O $HOME/.interlink/bin/interlink https://github.com/interlink-hq/interLink/releases/download/$VERSION/interlink_Linux_x86_64
chmod +x $HOME/.interlink/bin/interlink

Start InterLink API Server

# Start InterLink API server with mTLS
export INTERLINKCONFIGPATH=$HOME/.interlink/config/InterLinkConfig.yaml
$HOME/.interlink/bin/interlink &> $HOME/.interlink/logs/interlink.log &
echo $! > $HOME/.interlink/interlink.pid

Kubernetes Cluster Setup

Create Kubernetes Secrets for Certificates

Before deploying the Helm chart, create the necessary secrets:

# Create namespace
kubectl create namespace interlink

# Create secret with client certificates for Virtual Kubelet
# Note: The secret name must match the pattern: <nodeName>-tls-certs
# where <nodeName> corresponds to the nodeName value in your helm values
kubectl create secret generic my-node-tls-certs \
  --from-file=ca.crt=$HOME/.interlink/certs/ca.pem \
  --from-file=tls.crt=$HOME/.interlink/certs/client-cert.pem \
  --from-file=tls.key=$HOME/.interlink/certs/client-key.pem \
  -n interlink

Deploy with Helm Chart

Create a custom values file for mTLS deployment:

# Create values file for mTLS
cat > $HOME/.interlink/mtls-values.yaml << EOF
nodeName: "my-node"

virtualNode:
  resources:
    CPUs: 8
    memGiB: 49
    pods: 100
  HTTPProxies:
    HTTP: null
    HTTPs: null
  HTTP:
    insecure: true
    CACert: ""
  kubeletHTTP:
    insecure: true
  # Tracing configuration
  tracing:
    enabled: false

interlink:
  enabled: false
  address: https://172.16.213.51
  port: 3000
  tls:
    enabled: true
    certFile: "/etc/vk/certs/tls.crt"
    keyFile: "/etc/vk/certs/tls.key"
    caCertFile: "/etc/vk/certs/ca.crt"
EOF

# Deploy with mTLS configuration
export INTERLINK_CHART_VERSION="X.X.X"
helm upgrade --install \
  --create-namespace \
  -n interlink \
  my-node \
  oci://ghcr.io/interlink-hq/interlink-helm-chart/interlink \
  --version $INTERLINK_CHART_VERSION \
  --values $HOME/.interlink/mtls-values.yaml

warning

Remember to pick the version of the chart and put it into the INTERLINK_CHART_VERSION env var above.

Security Considerations

Certificate Management

• Implement regular certificate rotation for production deployments
• Store private keys securely with restricted file permissions (600)
• Keep CA private key highly secure and consider using a proper PKI solution
• Monitor certificate expiration dates

Network Security

# Example firewall configuration
sudo ufw allow from <kubernetes-cluster-cidr> to any port 3000 comment "InterLink mTLS API"
sudo ufw deny 3000 comment "Block public access to InterLink API"

Certificate Validation

# Verify certificate details and chain
openssl x509 -in server-cert.pem -text -noout
openssl verify -CAfile ca.pem server-cert.pem

# Test mTLS connection
openssl s_client -connect YOUR_EDGE_NODE_IP:3000 -CAfile ca.pem -cert client-cert.pem -key client-key.pem

Troubleshooting

Common Issues

1. Certificate verification errors - Check certificate chain and CA
2. Permission denied - Verify file permissions and paths
3. Handshake failures - Ensure client certificate is signed by the same CA

Debug Commands

# Check certificate chain
openssl verify -CAfile ca.pem client-cert.pem

# Test server connectivity
curl -v --cacert ca.pem --cert client-cert.pem --key client-key.pem https://YOUR_EDGE_NODE_IP:3000/pinglink

# Check InterLink logs for TLS errors
tail -f $HOME/.interlink/logs/interlink.log | grep -i tls

Log Messages to Monitor

• "Loaded CA certificate for TLS client"
• "mTLS enabled - requiring client certificates"
• "Failed to create TLS HTTP client"
• "certificate verification failed"

Testing Your Setup

Test the mTLS connection to ensure everything is working correctly:

# Test the pinglink endpoint
curl -v --cacert $HOME/.interlink/certs/ca.pem \
     --cert $HOME/.interlink/certs/client-cert.pem \
     --key $HOME/.interlink/certs/client-key.pem \
     https://YOUR_EDGE_NODE_IP:3000/pinglink

If successful, you should receive a response indicating the InterLink service is running and accessible via mTLS.

note

You can find a demo pod to test your setup here.