Demo Workload Entry

This tutorial demonstrates how to install Istio with a locked-down outbound traffic policy (REGISTRY_ONLY) and register an external workload so in-cluster pods can reach it. We’ll use a host-run nginx as the external workload and show how WorkloadEntry and ServiceEntry allow pods to access it when the mesh denies unregistered outbound destinations.

Prerequisites

A Kubernetes cluster with kubectl access.
curl and apt (for the control-plane host demo steps).
istioctl (we’ll download it as part of the demo).

Verify Kubernetes is running

List all pods across namespaces to confirm your cluster is healthy:

kubectl get pods -A

Example (truncated):

NAMESPACE     NAME                                      READY   STATUS    RESTARTS   AGE
kube-system   coredns-76f75df574-9pksc                   1/1     Running   0          45m
kube-system   etcd-controlplane                           1/1     Running   1 (45m ago) 45m
kube-system   kube-apiserver-controlplane                 1/1     Running   0          45m
weave-net-zs761                             2/2     Running   1 (45m ago) 45m

Download and install Istio (demo: v1.18.2)

Download Istio and make istioctl available:

curl -L https://istio.io/downloadIstio | ISTIO_VERSION=1.18.2 sh -
export PATH="$PATH:/root/istio-1.18.2/bin"

Create a local copy of the demo profile so we can modify mesh settings:

istioctl profile dump demo -o yaml > demo.yaml

Edit demo.yaml to set the mesh outbound traffic policy to REGISTRY_ONLY. Add or update the following under meshConfig:

meshConfig:
  outboundTrafficPolicy:
    mode: REGISTRY_ONLY
  accessLogFile: /dev/stdout
  defaultConfig:
    proxyMetadata: {}
  enablePrometheusMerge: true

For context, the file should include the hub and the modified meshConfig:

hub: docker.io/istio
meshConfig:
  outboundTrafficPolicy:
    mode: REGISTRY_ONLY
  accessLogFile: /dev/stdout
  defaultConfig:
    proxyMetadata: {}
  enablePrometheusMerge: true

Validate and install the modified profile:

istioctl validate -f demo.yaml
istioctl install -f demo.yaml -y
# Output will indicate Istio core, Istiod, ingress/egress gateways installed, etc.

Verify Istio system pods are running:

kubectl get pods -n istio-system

Setting outboundTrafficPolicy.mode to REGISTRY_ONLY blocks traffic to any destination not registered in the mesh registry. Apply this carefully in production; it can break external integrations unless those endpoints are explicitly added via ServiceEntry/WorkloadEntry.

Simulate an external application (nginx on the host)

For this demo we simulate an external workload by running nginx on the control plane host. (In production, this would typically be a VM or cloud instance.) Install nginx on the host:

apt update -y && apt install nginx -y

Verify nginx serves locally:

curl localhost

Identify the host network interface used by your CNI (weave in this demo) and note its IP (example: 10.50.0.1):

ip a

You should see the weave interface with an IP like:

4: weave: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1376 ...
    inet 10.50.0.1/16 brd 10.50.255.255 scope global weave

Confirm the host’s nginx is reachable via that IP:

curl http://10.50.0.1
# returns the nginx HTML

Create a test pod inside the cluster (with sidecar injection enabled)

Enable Istio sidecar injection for the namespace (we use default here):

kubectl label namespace default istio-injection=enabled --overwrite

Run a test pod with an injected sidecar:

kubectl run test --image=nginx
kubectl get pods
# NAME   READY   STATUS    RESTARTS   AGE
# test   2/2     Running   0          10s

Attempt to curl the host IP from inside the pod. With REGISTRY_ONLY the sidecar blocks traffic to unregistered IPs and typically returns a 502:

kubectl exec -ti test -- curl --head http://10.50.0.1

Example response:

HTTP/1.1 502 Bad Gateway
date: ...
server: envoy
transfer-encoding: chunked

Setting meshConfig.outboundTrafficPolicy.mode to REGISTRY_ONLY requires that any external service you want pods to access must be registered with Istio (via ServiceEntry and/or WorkloadEntry). Otherwise the sidecar will reject the outbound traffic.

Register the external workload with WorkloadEntry

Create a WorkloadEntry that represents the host-run nginx. Save the following as workload-entry.yaml:

apiVersion: networking.istio.io/v1beta1
kind: WorkloadEntry
metadata:
  name: external-app-we
  namespace: default
spec:
  address: 10.50.0.1
  labels:
    app: external

Apply it and confirm:

kubectl apply -f workload-entry.yaml
kubectl get we
# NAME               AGE   ADDRESS
# external-app-we    10s   10.50.0.1

Create a ServiceEntry that maps a hostname to the WorkloadEntry

Create service-entry.yaml to define a logical hostname and connect it to the WorkloadEntry via a selector:

apiVersion: networking.istio.io/v1beta1
kind: ServiceEntry
metadata:
  name: external-app-se
  namespace: default
spec:
  hosts:
  - app.internal.com
  ports:
  - number: 80
    name: http
    protocol: HTTP
  resolution: STATIC
  workloadSelector:
    labels:
      app: external

Notes:

hosts is the logical hostname clients will use, e.g. app.internal.com.
resolution: STATIC is required when the ServiceEntry is paired with WorkloadEntry(s).
workloadSelector.labels picks the WorkloadEntry(s) (or pods) with matching labels.

Apply the ServiceEntry:

kubectl apply -f service-entry.yaml
kubectl get serviceentry
# NAME                HOSTS                 LOCATION   RESOLUTION   AGE
# external-app-se     ["app.internal.com"]             STATIC       3s

Test access from the test pod via the registered hostname

From inside the test pod, curl the logical hostname:

kubectl exec -ti test -- curl http://app.internal.com

You should receive the nginx HTML from the host because Istio now recognizes app.internal.com via the ServiceEntry/WorkloadEntry registration.

Add an in-cluster pod to the same workload (WorkloadEntry label)

To show that a WorkloadEntry can represent multiple endpoints, create an in-cluster pod with the same label as the WorkloadEntry:

kubectl run nginx --image=nginx --labels="app=external"
kubectl get pods
# pod/nginx created

Edit the pod’s index page to distinguish it from the host nginx:

kubectl exec -ti nginx -- /bin/bash
# inside the pod:
echo "This is an Nginx Pod" > /usr/share/nginx/html/index.html
curl localhost
# Output: This is an Nginx Pod
exit

Now requests to app.internal.com from the test pod may be served by either the external host (WorkloadEntry IP) or the in-cluster nginx pod, since they share the label and are part of the same logical service:

kubectl exec -ti test -- curl http://app.internal.com
# This is an Nginx Pod
kubectl exec -ti test -- curl http://app.internal.com
# This is an Nginx Pod

Istio may load-balance traffic across the registered endpoints.

Quick reference: WorkloadEntry vs ServiceEntry

Resource	Purpose	Key fields / notes	Example snippet
WorkloadEntry	Represent an external or non-Kubernetes workload (VM, bare metal, other cloud VM, or IP)	`address`, `labels`, `serviceAccount` (for mTLS), `network`, `ports`	`apiVersion: networking.istio.io/v1beta1` `kind: WorkloadEntry`
ServiceEntry	Register a service hostname into Istio and describe how to reach it	`hosts`, `ports`, `resolution` (`STATIC` with WorkloadEntry), `workloadSelector`	`apiVersion: networking.istio.io/v1beta1` `kind: ServiceEntry`

Practical notes and reference

WorkloadEntry lets Istio manage non-Kubernetes endpoints. Use it for VMs, bare metal, and external IPs.
ServiceEntry maps DNS names into the mesh and describes ports/protocols and resolution. Use workloadSelector to attach WorkloadEntry(s).
Common WorkloadEntry fields: address (IP or DNS), serviceAccount (if mTLS is required), network, labels, and ports.
If location is not set in a ServiceEntry, the default is MESH_EXTERNAL. Use location: MESH_INTERNAL when the service should be considered internal to the mesh.
When using REGISTRY_ONLY, ensure every external dependency is added to the registry; otherwise application traffic will be blocked.

Introduction

Installation & Configuration

Traffic Management

Securing Workloads

Troubleshooting

Conclusion

Demo Workload Entry

Prerequisites

Verify Kubernetes is running

Download and install Istio (demo: v1.18.2)

Simulate an external application (nginx on the host)

Create a test pod inside the cluster (with sidecar injection enabled)

Register the external workload with WorkloadEntry

Create a ServiceEntry that maps a hostname to the WorkloadEntry

Test access from the test pod via the registered hostname

Add an in-cluster pod to the same workload (WorkloadEntry label)

Quick reference: WorkloadEntry vs ServiceEntry

Practical notes and reference

Watch Video

Practice Lab

​Prerequisites

​Verify Kubernetes is running

​Download and install Istio (demo: v1.18.2)

​Simulate an external application (nginx on the host)

​Create a test pod inside the cluster (with sidecar injection enabled)

​Register the external workload with WorkloadEntry

​Create a ServiceEntry that maps a hostname to the WorkloadEntry

​Test access from the test pod via the registered hostname

​Add an in-cluster pod to the same workload (WorkloadEntry label)

​Quick reference: WorkloadEntry vs ServiceEntry

​Practical notes and reference

Watch Video

Practice Lab

Prerequisites

Verify Kubernetes is running

Download and install Istio (demo: v1.18.2)

Simulate an external application (nginx on the host)

Create a test pod inside the cluster (with sidecar injection enabled)

Register the external workload with WorkloadEntry

Create a ServiceEntry that maps a hostname to the WorkloadEntry

Test access from the test pod via the registered hostname

Add an in-cluster pod to the same workload (WorkloadEntry label)

Quick reference: WorkloadEntry vs ServiceEntry

Practical notes and reference