Skip to main content

Documentation Index

Fetch the complete documentation index at: https://notes.kodekloud.com/llms.txt

Use this file to discover all available pages before exploring further.

This article compares Istio’s ServiceEntry and WorkloadEntry resources, explains when to use each, and shows typical configuration examples. It’s meant for operators and SREs who need to integrate external services or VMs into an Istio service mesh while preserving routing, telemetry, and mTLS behavior.

​
Overview

  • ServiceEntry: informs Istio about services that are external to the Kubernetes cluster (for example, an external database or a managed API). Primarily used for routing and service discovery.
  • WorkloadEntry: registers a non-Kubernetes workload (for example, an EC2 instance or VM) as a member of the Istio mesh so it can participate in mTLS, policy, and telemetry—provided it runs a sidecar or equivalent proxy.
Use these resources together when you want the mesh to route to a DNS/hostname and you also want those endpoints to behave like first-class mesh workloads.

​
When to use which

  • Use a ServiceEntry when you need to allow or route traffic to an external host from inside the mesh.
  • Use a WorkloadEntry when you want the external endpoint to appear as an integrated member of the mesh (so policies, telemetry, and mTLS can apply).
  • In practice: ServiceEntry publishes the host-level routing and WorkloadEntry registers the concrete endpoints.

​
ServiceEntry — routing-only resource

Purpose:
  • Declares external hosts to Istio for routing and service discovery.
  • Adds a host entry to Istio’s internal registry so in-mesh workloads can route to that host.
  • Does not, by itself, make the external endpoint a full mesh participant (no mTLS/telemetry if there’s no sidecar).
Example ServiceEntry (routes app.internal.com to workloads selected by label): 
apiVersion: networking.istio.io/v1
kind: ServiceEntry
metadata:
  name: external-app-se
  namespace: backend
spec:
  hosts:
  - app.internal.com
  ports:
  - number: 80
    name: http
    protocol: TCP
  resolution: STATIC
  workloadSelector:
    labels:
      app: external
Notes on the example:
  • Declares app.internal.com with resolution: STATIC.
  • workloadSelector targets workloads with app: external. This selector can match Kubernetes Pods and/or WorkloadEntry objects.
  • With STATIC resolution, you must provide endpoints (either in the ServiceEntry via endpoints: or by creating one or more WorkloadEntry resources that match the selector).

​
WorkloadEntry — integrate external VMs / non-K8s workloads

Purpose:
  • Registers non-Kubernetes workloads into the mesh so they can participate in mTLS, receive traffic, and appear in telemetry/policy evaluations.
  • Typically used with an Istio sidecar or an Istio-compatible proxy on the external VM.
Example WorkloadEntry (registers a VM endpoint): 
apiVersion: networking.istio.io/v1
kind: WorkloadEntry
metadata:
  name: details-svc
spec:
  # The serviceAccount indicates the workload's proxy identity and is used
  # when a sidecar proxy is present and mTLS is enabled.
  serviceAccount: details-legacy
  # address is typically an IP address, though a resolvable hostname can be used
  # in some setups if the environment resolves it appropriately.
  address: vm1.vpc01.corp.net
  labels:
    app: details-legacy
    instance-id: vm1
Important fields and behavior:
  • serviceAccount: optional, used by the workload’s proxy identity. When present and properly bootstrapped, it enables the workload to participate in Istio mutual TLS and workload identity.
  • address: endpoint IP or hostname for the workload (IP is most common).
  • labels: used to match selectors (e.g., a ServiceEntry workloadSelector or policy selectors); this is how ServiceEntry hostnames map to WorkloadEntry endpoints.
  • You can create multiple WorkloadEntry objects for a single logical service to represent multiple VMs/endpoints. Use optional fields like network, locality, ports, and weight to control routing and grouping.

​
Key differences (at-a-glance)

ResourcePurposeTypical Use CasemTLS SupportService DiscoveryTelemetry & Metrics
ServiceEntryDeclare external hostnames for routingAllow/route outbound traffic to external servicesNo (routing only)Adds a host entry to Istio registryLimited if endpoint has no sidecar
WorkloadEntryRegister non-K8s workloads into meshMake VMs/instances behave like mesh workloadsYes (if sidecar and serviceAccount configured)Registers concrete endpoints (IP/host)Full telemetry if proxy participates

​
Telemetry and mTLS

  • ServiceEntry alone provides routing but limited telemetry because external endpoints typically lack an Istio sidecar.
  • WorkloadEntry enables richer telemetry and mTLS when the target workload runs an Istio sidecar (or an equivalent proxy) that is properly bootstrapped with the indicated serviceAccount and certificates.
  • To get the most observability and policy enforcement for external workloads, combine:
    • a ServiceEntry (for the logical hostname and routing configuration), and
    • one or more WorkloadEntry resources (to register the concrete endpoint addresses with labels and identity).
Remember: labels used by a ServiceEntry’s workloadSelector can match both Pods and WorkloadEntry objects. This makes it straightforward to route to a mix of in-cluster pods and external endpoints using the same logical service name.
A comparison table titled "Service Entry vs Workload Entry" listing categories (Purpose, Use Case, mTLS Support, Service Discovery, Telemetry & Metrics). It summarizes that Service Entry defines external services for routing, while Workload Entry integrates external workloads into the mesh and supports mTLS and metrics.

​
Practical reminders and best practices

  • If you integrate a VM, install and bootstrap an Istio sidecar (or compatible proxy) so it can present the configured serviceAccount identity and participate in mTLS and telemetry.
  • Use ServiceEntry when you only need to allow or route outbound requests to an external host (e.g., to reach a package mirror or third-party API).
  • Use WorkloadEntry when you want the external endpoint to be treated as a first-class mesh member (policy, telemetry, mTLS).
  • When using resolution: STATIC, ensure the host resolves to concrete endpoints via endpoints: in the ServiceEntry or via WorkloadEntry objects that match the ServiceEntry’s selector.
  • Review optional WorkloadEntry fields (ports, network, locality, weight) to fine-tune routing and traffic distribution across external endpoints.

​
References and further reading

Try creating a ServiceEntry + WorkloadEntry pair in a test environment to observe how the mesh routes traffic, how telemetry appears in your observability tools, and how mTLS behaves once the external workload is bootstrapped.

Watch Video