WorkloadEntry
Supported Version: Istio 1.28+ Last Updated: February 19, 2026
WorkloadEntry is a resource for registering Virtual Machines (VMs) or bare-metal servers into the Istio service mesh. This enables workloads outside of Kubernetes to utilize the mesh's traffic management, security, and observability features.
Table of Contents
- Overview
- WorkloadEntry vs Kubernetes Pod
- Architecture
- Basic Usage
- ServiceEntry Integration
- VM Registration Practical Guide
- Security Settings (mTLS)
- Health Checks and Monitoring
- Advanced Configuration
- Troubleshooting
- Best Practices
Overview
What is WorkloadEntry?
WorkloadEntry is an Istio Custom Resource Definition (CRD) that registers workloads (VMs, bare-metal) outside the mesh into the Istio service mesh.
Use Scenarios
Primary Use Cases:
- Gradual Migration: Incrementally migrate legacy applications to Kubernetes
- Hybrid Architecture: Operate VMs and containers simultaneously
- Database Integration: Include external databases in the mesh
- High-Performance Workloads: Utilize specialized hardware like GPU servers
WorkloadEntry vs Kubernetes Pod
Comparison Table
| Characteristic | Kubernetes Pod | WorkloadEntry (VM) |
|---|---|---|
| Deployment Location | Inside cluster | Outside cluster |
| Envoy Injection | Automatic (sidecar) | Manual installation |
| Service Discovery | Automatic (Service) | Manual (WorkloadEntry) |
| IP Management | Kubernetes CNI | Manual specification |
| mTLS | Automatic | Automatic (certificate deployment required) |
| Health Checks | Automatic (Liveness/Readiness) | Manual configuration |
| Scaling | HPA | Manual |
| Operational Complexity | Low | High |
| Use Scenario | Cloud-native apps | Legacy apps, specialized hardware |
Traffic Flow Comparison
Architecture
VM Workload Architecture
Key Components
- WorkloadEntry: VM information registration (IP, ports, labels)
- ServiceEntry: Service definition and WorkloadEntry reference
- Envoy Proxy: Manually installed sidecar on VM
- istiod: Configuration deployment and certificate management
- Service Account: VM identity authentication
Basic Usage
WorkloadEntry Resource Definition
apiVersion: networking.istio.io/v1
kind: WorkloadEntry
metadata:
name: legacy-api-vm-1
namespace: production
spec:
# VM's IP address
address: 192.168.1.100
# Labels for service selection
labels:
app: legacy-api
version: v1.0
tier: backend
# Service account for mTLS authentication
serviceAccount: legacy-api-sa
# Ports to expose
ports:
http: 8080
https: 8443
metrics: 9090
# Locality information (optional)
locality: us-west-2/us-west-2a
# Weight (for load balancing, optional)
weight: 100
# Network (multi-network environment, optional)
network: vm-networkRequired Field Descriptions
| Field | Description | Example |
|---|---|---|
| address | VM's IP address (required) | 192.168.1.100 |
| labels | Labels for ServiceEntry matching | app: legacy-api |
| serviceAccount | SA for mTLS authentication | legacy-api-sa |
| ports | Port map to expose | http: 8080 |
Registering Multiple VMs
# VM 1
apiVersion: networking.istio.io/v1
kind: WorkloadEntry
metadata:
name: api-vm-1
namespace: production
spec:
address: 192.168.1.101
labels:
app: api-service
version: v1
serviceAccount: api-sa
ports:
http: 8080
---
# VM 2
apiVersion: networking.istio.io/v1
kind: WorkloadEntry
metadata:
name: api-vm-2
namespace: production
spec:
address: 192.168.1.102
labels:
app: api-service
version: v1
serviceAccount: api-sa
ports:
http: 8080
---
# VM 3 (different version)
apiVersion: networking.istio.io/v1
kind: WorkloadEntry
metadata:
name: api-vm-3
namespace: production
spec:
address: 192.168.1.103
labels:
app: api-service
version: v2 # New version
serviceAccount: api-sa
ports:
http: 8080ServiceEntry Integration
WorkloadEntry is always used together with ServiceEntry.
Basic Integration Pattern
# 1. Define service with ServiceEntry
apiVersion: networking.istio.io/v1
kind: ServiceEntry
metadata:
name: legacy-api
namespace: production
spec:
hosts:
- api.legacy.internal
addresses:
- 240.240.1.1 # Virtual IP
ports:
- number: 8080
name: http
protocol: HTTP
location: MESH_INTERNAL
resolution: STATIC
workloadSelector:
labels:
app: legacy-api # Match with WorkloadEntry labels
---
# 2. Register VM with WorkloadEntry
apiVersion: networking.istio.io/v1
kind: WorkloadEntry
metadata:
name: legacy-api-vm-1
namespace: production
spec:
address: 192.168.1.100
labels:
app: legacy-api # Match with ServiceEntry
version: v1
serviceAccount: legacy-api-sa
ports:
http: 8080Operation Flow
Load Balancing
Automatic load balancing when multiple WorkloadEntries exist:
apiVersion: networking.istio.io/v1
kind: ServiceEntry
metadata:
name: database-cluster
spec:
hosts:
- db.cluster.internal
ports:
- number: 5432
name: postgresql
protocol: TCP
location: MESH_INTERNAL
resolution: STATIC
workloadSelector:
labels:
app: postgres
tier: database
---
# Primary DB
apiVersion: networking.istio.io/v1
kind: WorkloadEntry
metadata:
name: postgres-primary
spec:
address: 10.0.1.100
labels:
app: postgres
tier: database
role: primary
weight: 100 # Weight
---
# Replica DB 1
apiVersion: networking.istio.io/v1
kind: WorkloadEntry
metadata:
name: postgres-replica-1
spec:
address: 10.0.1.101
labels:
app: postgres
tier: database
role: replica
weight: 50
---
# Replica DB 2
apiVersion: networking.istio.io/v1
kind: WorkloadEntry
metadata:
name: postgres-replica-2
spec:
address: 10.0.1.102
labels:
app: postgres
tier: database
role: replica
weight: 50VM Registration Practical Guide
Prerequisites
VM Requirements:
- Network: Can communicate with Kubernetes cluster
- OS: Linux (Ubuntu 20.04+ recommended)
- Ports: Envoy ports open (15012, 15017, etc.)
Kubernetes Preparation:
- Istio installation complete
- Create namespace for VM usage
- Create ServiceAccount
Step 1: Create ServiceAccount
# Create namespace
kubectl create namespace vm-workloads
# Create ServiceAccount
kubectl create serviceaccount vm-postgres-sa -n vm-workloads
# (Optional) RBAC setup
kubectl create role vm-postgres-role \
--verb=get,list,watch \
--resource=configmaps,secrets \
-n vm-workloads
kubectl create rolebinding vm-postgres-binding \
--role=vm-postgres-role \
--serviceaccount=vm-workloads:vm-postgres-sa \
-n vm-workloadsStep 2: Create WorkloadGroup (Optional)
WorkloadGroup serves as a template for multiple WorkloadEntries:
apiVersion: networking.istio.io/v1
kind: WorkloadGroup
metadata:
name: postgres-vms
namespace: vm-workloads
spec:
metadata:
labels:
app: postgres
version: v14
template:
serviceAccount: vm-postgres-sa
network: vm-network
ports:
postgresql: 5432Step 3: Install Envoy on VM
Generate Automatic Installation Script
# Generate VM registration files with istioctl
istioctl x workload entry configure \
-f workloadgroup.yaml \
-o vm-postgres-1 \
--clusterID Kubernetes \
--autoregister
# Generated files:
# - cluster.env: Cluster information
# - istio-token: Authentication token
# - mesh.yaml: Mesh configuration
# - root-cert.pem: Root certificate
# - hosts: /etc/hosts entriesExecute Installation on VM
# Connect to VM
ssh user@192.168.1.100
# Copy files (using SCP)
scp -r vm-postgres-1/* user@192.168.1.100:/tmp/
# Install Envoy on VM
sudo apt-get update
sudo apt-get install -y curl
# Install Istio sidecar
curl -LO https://storage.googleapis.com/istio-release/releases/1.28.0/deb/istio-sidecar.deb
sudo dpkg -i istio-sidecar.deb
# Place configuration files
sudo mkdir -p /etc/certs
sudo cp /tmp/root-cert.pem /etc/certs/
sudo cp /tmp/istio-token /var/run/secrets/tokens/
sudo cp /tmp/cluster.env /var/lib/istio/envoy/
sudo cp /tmp/mesh.yaml /etc/istio/config/mesh
# Start Envoy
sudo systemctl start istio
sudo systemctl enable istio
# Check status
sudo systemctl status istioStep 4: Register WorkloadEntry
If auto-registration is enabled, it's automatically created when Envoy starts. Manual registration:
apiVersion: networking.istio.io/v1
kind: WorkloadEntry
metadata:
name: postgres-vm-1
namespace: vm-workloads
spec:
address: 192.168.1.100
labels:
app: postgres
version: v14
serviceAccount: vm-postgres-sa
ports:
postgresql: 5432kubectl apply -f workloadentry.yamlStep 5: Create ServiceEntry
apiVersion: networking.istio.io/v1
kind: ServiceEntry
metadata:
name: postgres-service
namespace: vm-workloads
spec:
hosts:
- postgres.vm.internal
addresses:
- 240.240.2.1
ports:
- number: 5432
name: postgresql
protocol: TCP
location: MESH_INTERNAL
resolution: STATIC
workloadSelector:
labels:
app: postgreskubectl apply -f serviceentry.yamlStep 6: Test Connection
# Create test pod
kubectl run -it --rm debug \
--image=postgres:14 \
--restart=Never \
--namespace=vm-workloads \
-- psql -h postgres.vm.internal -U dbuser -d mydb
# On successful connection:
# Password for user dbuser:
# psql (14.x)
# Type "help" for help.
# mydb=#Security Settings (mTLS)
Automatic mTLS Enablement
WorkloadEntry automatically supports mTLS:
# Force mTLS with PeerAuthentication
apiVersion: security.istio.io/v1
kind: PeerAuthentication
metadata:
name: default
namespace: vm-workloads
spec:
mtls:
mode: STRICT # mTLS required for both VM and podVM Identity Verification
# Check certificates on VM
sudo ls -la /etc/certs/
# cert-chain.pem: Certificate chain
# key.pem: Private key
# root-cert.pem: Root CA
# Check certificate contents
sudo openssl x509 -in /etc/certs/cert-chain.pem -text -noout
# Check Subject Alternative Name (SAN):
# spiffe://cluster.local/ns/vm-workloads/sa/vm-postgres-saAccess Control (AuthorizationPolicy)
# PostgreSQL access control
apiVersion: security.istio.io/v1
kind: AuthorizationPolicy
metadata:
name: postgres-access
namespace: vm-workloads
spec:
selector:
matchLabels:
app: postgres # WorkloadEntry labels
action: ALLOW
rules:
# Allow only API service access
- from:
- source:
principals:
- cluster.local/ns/production/sa/api-service-sa
to:
- operation:
ports: ["5432"]
methods: ["*"]
# Allow monitoring service access
- from:
- source:
principals:
- cluster.local/ns/istio-system/sa/prometheus
to:
- operation:
ports: ["9187"] # postgres_exportermTLS Verification
# Test connection from pod to VM
kubectl exec -it <pod-name> -n production -- \
curl -v --cacert /etc/certs/root-cert.pem \
--cert /etc/certs/cert-chain.pem \
--key /etc/certs/key.pem \
https://postgres.vm.internal:5432
# Verify mTLS with Envoy stats
kubectl exec -it <pod-name> -c istio-proxy -- \
curl localhost:15000/stats | grep ssl
# Example output:
# listener.0.0.0.0_15006.ssl.connection_error: 0
# listener.0.0.0.0_15006.ssl.handshake: 1234Health Checks and Monitoring
Health Check Configuration
WorkloadEntry does not support automatic health checks, so manual configuration is required:
apiVersion: networking.istio.io/v1
kind: DestinationRule
metadata:
name: postgres-healthcheck
namespace: vm-workloads
spec:
host: postgres.vm.internal
trafficPolicy:
connectionPool:
tcp:
maxConnections: 100
http:
http1MaxPendingRequests: 50
outlierDetection:
consecutiveErrors: 5 # Exclude after 5 consecutive failures
interval: 30s # Check every 30 seconds
baseEjectionTime: 30s # Exclude for 30 seconds
maxEjectionPercent: 50 # Exclude up to 50%
minHealthPercent: 50 # Maintain at least 50%VM Health Check Endpoint
Add a health check endpoint to your VM application:
# Python Flask example
from flask import Flask, jsonify
import psycopg2
app = Flask(__name__)
@app.route('/health', methods=['GET'])
def health():
try:
# Verify database connection
conn = psycopg2.connect("dbname=mydb user=dbuser")
conn.close()
return jsonify({"status": "healthy"}), 200
except Exception as e:
return jsonify({"status": "unhealthy", "error": str(e)}), 503
if __name__ == '__main__':
app.run(host='0.0.0.0', port=8080)Prometheus Metrics Collection
# Collect VM metrics with ServiceMonitor
apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
name: postgres-vm-metrics
namespace: vm-workloads
spec:
selector:
matchLabels:
app: postgres
endpoints:
- port: metrics
interval: 30s
path: /metricsGrafana Dashboard Queries
# VM workload request count
sum(rate(istio_requests_total{destination_workload="postgres-vm-1"}[5m]))
# VM workload error rate
sum(rate(istio_requests_total{destination_workload="postgres-vm-1",response_code="500"}[5m]))
/
sum(rate(istio_requests_total{destination_workload="postgres-vm-1"}[5m]))
* 100
# VM workload latency (P99)
histogram_quantile(0.99,
sum(rate(istio_request_duration_milliseconds_bucket{destination_workload="postgres-vm-1"}[5m])) by (le)
)Advanced Configuration
Multi-Network Environment
Register VMs in different networks:
# VM in Network A
apiVersion: networking.istio.io/v1
kind: WorkloadEntry
metadata:
name: api-vm-network-a
spec:
address: 192.168.1.100
labels:
app: api-service
serviceAccount: api-sa
network: network-a
ports:
http: 8080
---
# VM in Network B
apiVersion: networking.istio.io/v1
kind: WorkloadEntry
metadata:
name: api-vm-network-b
spec:
address: 10.0.1.100
labels:
app: api-service
serviceAccount: api-sa
network: network-b
ports:
http: 8080Locality-aware Load Balancing
apiVersion: networking.istio.io/v1
kind: WorkloadEntry
metadata:
name: api-vm-us-west
spec:
address: 192.168.1.100
labels:
app: api-service
locality: us-west/us-west-2/us-west-2a
weight: 100
---
apiVersion: networking.istio.io/v1
kind: WorkloadEntry
metadata:
name: api-vm-us-east
spec:
address: 10.0.1.100
labels:
app: api-service
locality: us-east/us-east-1/us-east-1a
weight: 100
---
# Locality-aware routing with DestinationRule
apiVersion: networking.istio.io/v1
kind: DestinationRule
metadata:
name: api-locality-lb
spec:
host: api.service.internal
trafficPolicy:
loadBalancer:
localityLbSetting:
enabled: true
distribute:
- from: us-west/*
to:
"us-west/*": 80
"us-east/*": 20
- from: us-east/*
to:
"us-east/*": 80
"us-west/*": 20Canary Deployment
Canary deployment can also be applied to WorkloadEntry:
# v1 version VM
apiVersion: networking.istio.io/v1
kind: WorkloadEntry
metadata:
name: api-vm-v1
spec:
address: 192.168.1.100
labels:
app: api-service
version: v1
serviceAccount: api-sa
---
# v2 version VM (Canary)
apiVersion: networking.istio.io/v1
kind: WorkloadEntry
metadata:
name: api-vm-v2
spec:
address: 192.168.1.101
labels:
app: api-service
version: v2
serviceAccount: api-sa
---
# Traffic splitting with VirtualService
apiVersion: networking.istio.io/v1
kind: VirtualService
metadata:
name: api-service-canary
spec:
hosts:
- api.service.internal
http:
- route:
- destination:
host: api.service.internal
subset: v1
weight: 90
- destination:
host: api.service.internal
subset: v2
weight: 10
---
# Define subsets with DestinationRule
apiVersion: networking.istio.io/v1
kind: DestinationRule
metadata:
name: api-service-subsets
spec:
host: api.service.internal
subsets:
- name: v1
labels:
version: v1
- name: v2
labels:
version: v2Troubleshooting
WorkloadEntry Not Registered
Symptom: Resource visible in kubectl get workloadentry but traffic not routing
Verification:
# 1. Check WorkloadEntry status
kubectl get workloadentry -n vm-workloads -o yaml
# 2. Check ServiceEntry's workloadSelector
kubectl get serviceentry -n vm-workloads -o yaml | grep -A 5 workloadSelector
# 3. Verify label matching
# WorkloadEntry labels:
# app: postgres
# ServiceEntry workloadSelector:
# labels:
# app: postgres # Must match
# 4. Check Envoy configuration
istioctl proxy-config endpoints <pod-name> -n production
# Output should include WorkloadEntry's IP:
# ENDPOINT STATUS CLUSTER
# 192.168.1.100:5432 HEALTHY outbound|5432||postgres.vm.internalResolution:
# Modify labels to match exactly
apiVersion: networking.istio.io/v1
kind: WorkloadEntry
metadata:
name: postgres-vm-1
spec:
labels:
app: postgres # Must be identical to ServiceEntry
version: v14mTLS Connection Failure on VM
Symptom: connection refused or TLS handshake failed
Verification:
# Check Envoy logs on VM
sudo journalctl -u istio -f | grep -i tls
# Check certificates
sudo ls -la /etc/certs/
sudo openssl x509 -in /etc/certs/cert-chain.pem -text -noout
# Check certificate expiration
sudo openssl x509 -in /etc/certs/cert-chain.pem -noout -dates
# Check ServiceAccount token
sudo ls -la /var/run/secrets/tokens/
sudo cat /var/run/secrets/tokens/istio-tokenResolution:
# Reissue certificates
istioctl x workload entry configure \
-f workloadgroup.yaml \
-o vm-postgres-1 \
--clusterID Kubernetes \
--autoregister
# Copy to VM and restart Envoy
scp -r vm-postgres-1/* user@192.168.1.100:/tmp/
ssh user@192.168.1.100 "sudo cp /tmp/root-cert.pem /etc/certs/ && sudo systemctl restart istio"Traffic Not Reaching Due to Health Check Failure
Symptom: Envoy marks WorkloadEntry as UNHEALTHY
Verification:
# Check Envoy endpoint status
istioctl proxy-config endpoints <pod-name> -n production | grep postgres
# Output:
# 192.168.1.100:5432 UNHEALTHY outbound|5432||postgres.vm.internal
# Check DestinationRule's outlierDetection
kubectl get destinationrule -n vm-workloads -o yamlResolution:
# Adjust OutlierDetection settings
apiVersion: networking.istio.io/v1
kind: DestinationRule
metadata:
name: postgres-healthcheck
spec:
host: postgres.vm.internal
trafficPolicy:
outlierDetection:
consecutiveErrors: 10 # More lenient
interval: 60s # Increase check interval
baseEjectionTime: 60s
maxEjectionPercent: 100 # Prevent all from being excludedDNS Lookup Failure
Symptom: postgres.vm.internal lookup fails from pod
Verification:
# Check ServiceEntry
kubectl get serviceentry -n vm-workloads
# DNS lookup test
kubectl run -it --rm debug --image=busybox --restart=Never -- \
nslookup postgres.vm.internal
# Check Istio DNS Proxy enablement
kubectl get pod <pod-name> -o yaml | grep ISTIO_META_DNS_CAPTUREResolution:
# Add addresses to ServiceEntry
apiVersion: networking.istio.io/v1
kind: ServiceEntry
metadata:
name: postgres-service
spec:
hosts:
- postgres.vm.internal
addresses:
- 240.240.2.1 # Specify virtual IP
ports:
- number: 5432
name: postgresql
protocol: TCP
location: MESH_INTERNAL
resolution: STATIC
workloadSelector:
labels:
app: postgresBest Practices
1. Naming Conventions
# WorkloadEntry name: <app>-<role>-<id>
name: postgres-primary-1
name: postgres-replica-2
name: api-backend-vm-3
# ServiceEntry name: <app>-service
name: postgres-service
name: api-service
# ServiceAccount name: <app>-sa
name: postgres-sa
name: api-sa2. Label Strategy
spec:
labels:
# Required labels
app: postgres # Application name
version: v14 # Version
# Optional labels
tier: database # Tier (frontend, backend, database)
role: primary # Role (primary, replica, canary)
environment: production # Environment
team: platform # Team3. ServiceAccount Management
# Separate ServiceAccount by namespace
kubectl create sa db-sa -n databases
kubectl create sa api-sa -n applications
kubectl create sa cache-sa -n middleware
# Principle of least privilege
kubectl create role db-limited \
--verb=get \
--resource=configmaps \
-n databases4. Monitoring and Alerting
# Alert setup with PrometheusRule
apiVersion: monitoring.coreos.com/v1
kind: PrometheusRule
metadata:
name: workloadentry-alerts
spec:
groups:
- name: workloadentry
rules:
- alert: WorkloadEntryDown
expr: up{job="workloadentry-postgres"} == 0
for: 5m
labels:
severity: critical
annotations:
summary: "WorkloadEntry {{ $labels.instance }} is down"
- alert: WorkloadEntryHighErrorRate
expr: |
rate(istio_requests_total{
destination_workload=~".*-vm-.*",
response_code="500"
}[5m]) > 0.05
for: 10m
labels:
severity: warning5. Documentation
Maintain documentation for each WorkloadEntry:
apiVersion: networking.istio.io/v1
kind: WorkloadEntry
metadata:
name: postgres-primary-1
annotations:
description: "Primary PostgreSQL database for production"
owner: "platform-team@example.com"
provisioned-date: "2025-11-26"
os: "Ubuntu 22.04 LTS"
location: "us-west-2a"
runbook: "https://wiki.example.com/postgres-vm-runbook"
spec:
address: 192.168.1.100
labels:
app: postgres
version: v146. Backup and Disaster Recovery
# Backup WorkloadEntry
kubectl get workloadentry -n vm-workloads -o yaml > workloadentries-backup.yaml
# Backup ServiceEntry
kubectl get serviceentry -n vm-workloads -o yaml > serviceentries-backup.yaml
# Restore
kubectl apply -f workloadentries-backup.yaml
kubectl apply -f serviceentries-backup.yaml7. Gradual Migration Strategy
Phase 1: VM Mesh Registration
# Register WorkloadEntry
apiVersion: networking.istio.io/v1
kind: WorkloadEntry
metadata:
name: legacy-api-vm
spec:
address: 192.168.1.100
labels:
app: api
version: legacyPhase 2: Traffic Splitting (100% VM)
apiVersion: networking.istio.io/v1
kind: VirtualService
metadata:
name: api-migration
spec:
hosts:
- api.internal
http:
- route:
- destination:
host: api.internal
subset: legacy
weight: 100Phase 3: Kubernetes Deployment
kubectl apply -f kubernetes-deployment.yamlPhase 4: Gradual Traffic Transition
# 10% Kubernetes
apiVersion: networking.istio.io/v1
kind: VirtualService
metadata:
name: api-migration
spec:
http:
- route:
- destination:
subset: legacy # VM
weight: 90
- destination:
subset: k8s # Kubernetes
weight: 10Phase 5: VM Removal
# After transitioning 100% traffic to Kubernetes
kubectl delete workloadentry legacy-api-vm -n vm-workloads