Sidecar

Sidecar describes the configuration of the sidecar proxy that mediatesinbound and outbound communication to the workload instance it is attached to. Bydefault, Istio will program all sidecar proxies in the mesh with thenecessary configuration required to reach every workload instance in the mesh, aswell as accept traffic on all the ports associated with theworkload. The Sidecar configuration provides a way to fine tune the set ofports, protocols that the proxy will accept when forwarding traffic toand from the workload. In addition, it is possible to restrict the setof services that the proxy can reach when forwarding outbound trafficfrom workload instances.

Services and configuration in a mesh are organized into one or morenamespaces (e.g., a Kubernetes namespace or a CF org/space). A Sidecarconfiguration in a namespace will apply to one or more workload instances in the samenamespace, selected using the workloadSelector field. In the absence of aworkloadSelector, it will apply to all workload instances in the samenamespace. When determining the Sidecar configuration to be applied to aworkload instance, preference will be given to the resource with aworkloadSelector that selects this workload instance, over a Sidecar configurationwithout any workloadSelector.

NOTE 1: Each namespace can have only one Sidecar configuration without anyworkloadSelector. The behavior of the system is undefined if morethan one selector-less Sidecar configurations exist in a given namespace. Thebehavior of the system is undefined if two or more Sidecar configurationswith a workloadSelector select the same workload instance.

NOTE 2: A Sidecar configuration in the MeshConfigroot namespacewill be applied by default to all namespaces without a Sidecarconfiguration. This global default Sidecar configuration should not haveany workloadSelector.

The example below declares a global default Sidecar configuration in theroot namespace called istio-config, that configures sidecars inall namespaces to allow egress traffic only to other workloads inthe same namespace, and to services in the istio-system namespace.

  1. apiVersion: networking.istio.io/v1alpha3
  2. kind: Sidecar
  3. metadata:
  4.   name: default
  5.   namespace: istio-config
  6. spec:
  7.   egress:
  8.   - hosts:
  9.     - "./*"
  10.     - "istio-system/*"

The example below declares a Sidecar configuration in the prod-us1namespace that overrides the global default defined above, andconfigures the sidecars in the namespace to allow egress traffic topublic services in the prod-us1, prod-apis, and the istio-systemnamespaces.

  1. apiVersion: networking.istio.io/v1alpha3
  2. kind: Sidecar
  3. metadata:
  4.   name: default
  5.   namespace: prod-us1
  6. spec:
  7.   egress:
  8.   - hosts:
  9.     - "prod-us1/*"
  10.     - "prod-apis/*"
  11.     - "istio-system/*"

The example below declares a Sidecar configuration in the prod-us1 namespacethat accepts inbound HTTP traffic on port 9080 and forwardsit to the attached workload instance listening on a Unix domain socket. In theegress direction, in addition to the istio-system namespace, the sidecarproxies only HTTP traffic bound for port 9080 for services in theprod-us1 namespace.

  1. apiVersion: networking.istio.io/v1alpha3
  2. kind: Sidecar
  3. metadata:
  4.   name: default
  5.   namespace: prod-us1
  6. spec:
  7.   ingress:
  8.   - port:
  9.       number: 9080
  10.       protocol: HTTP
  11.       name: somename
  12.     defaultEndpoint: unix:///var/run/someuds.sock
  13.   egress:
  14.   - port:
  15.       number: 9080
  16.       protocol: HTTP
  17.       name: egresshttp
  18.     hosts:
  19.     - "prod-us1/*"
  20.   - hosts:
  21.     - "istio-system/*"

If the workload is deployed without IPTables-based traffic capture, theSidecar configuration is the only way to configure the ports on the proxyattached to the workload instance. The following example declares a Sidecarconfiguration in the prod-us1 namespace for all pods with labelsapp: productpage belonging to the productpage.prod-us1 service. Assumingthat these pods are deployed without IPtable rules (i.e. the istio-initcontainer) and the proxy metadata ISTIO_META_INTERCEPTION_MODE is set toNONE, the specification, below, allows such pods to receive HTTP trafficon port 9080 and forward it to the application listening on127.0.0.1:8080. It also allows the application to communicate with abacking MySQL database on 127.0.0.1:3306, that then gets proxied to theexternally hosted MySQL service at mysql.foo.com:3306.

  1. apiVersion: networking.istio.io/v1alpha3
  2. kind: Sidecar
  3. metadata:
  4.   name: no-ip-tables
  5.   namespace: prod-us1
  6. spec:
  7.   workloadSelector:
  8.     labels:
  9.       app: productpage
  10.   ingress:
  11.   - port:
  12.       number: 9080 # binds to proxy_instance_ip:9080 (0.0.0.0:9080, if no unicast IP is available for the instance)
  13.       protocol: HTTP
  14.       name: somename
  15.     defaultEndpoint: 127.0.0.1:8080
  16.     captureMode: NONE # not needed if metadata is set for entire proxy
  17.   egress:
  18.   - port:
  19.       number: 3306
  20.       protocol: MYSQL
  21.       name: egressmysql
  22.     captureMode: NONE # not needed if metadata is set for entire proxy
  23.     bind: 127.0.0.1
  24.     hosts:
  25.     - "*/mysql.foo.com"

And the associated service entry for routing to mysql.foo.com:3306

  1. apiVersion: networking.istio.io/v1alpha3
  2. kind: ServiceEntry
  3. metadata:
  4.   name: external-svc-mysql
  5.   namespace: ns1
  6. spec:
  7.   hosts:
  8.   - mysql.foo.com
  9.   ports:
  10.   - number: 3306
  11.     name: mysql
  12.     protocol: MYSQL
  13.   location: MESH_EXTERNAL
  14.   resolution: DNS

It is also possible to mix and match traffic capture modes in a singleproxy. For example, consider a setup where internal services are on the192.168.0.0/16 subnet. So, IP tables are setup on the VM to capture alloutbound traffic on 192.168.0.0/16 subnet. Assume that the VM has anadditional network interface on 172.16.0.0/16 subnet for inboundtraffic. The following Sidecar configuration allows the VM to expose alistener on 172.16.1.32:80 (the VM’s IP) for traffic arriving from the172.16.0.0/16 subnet. Note that in this scenario, theISTIO_META_INTERCEPTION_MODE metadata on the proxy in the VM shouldcontain REDIRECT or TPROXY as its value, implying that IP tablesbased traffic capture is active.

  1. apiVersion: networking.istio.io/v1alpha3
  2. kind: Sidecar
  3. metadata:
  4.   name: partial-ip-tables
  5.   namespace: prod-us1
  6. spec:
  7.   workloadSelector:
  8.     labels:
  9.       app: productpage
  10.   ingress:
  11.   - bind: 172.16.1.32
  12.     port:
  13.       number: 80 # binds to 172.16.1.32:80
  14.       protocol: HTTP
  15.       name: somename
  16.     defaultEndpoint: 127.0.0.1:8080
  17.     captureMode: NONE
  18.   egress:
  19.     # use the system detected defaults
  20.     # sets up configuration to handle outbound traffic to services
  21.     # in 192.168.0.0/16 subnet, based on information provided by the
  22.     # service registry
  23.   - captureMode: IPTABLES
  24.     hosts:
  25.     - "*/*"

CaptureMode

CaptureMode describes how traffic to a listener is expected to becaptured. Applicable only when the listener is bound to an IP.

NameDescription
DEFAULT
The default capture mode defined by the environment.
IPTABLES
Capture traffic using IPtables redirection.
NONE
No traffic capture. When used in an egress listener, the application isexpected to explicitly communicate with the listener port or Unixdomain socket. When used in an ingress listener, care needs to be takento ensure that the listener port is not in use by other processes onthe host.

IstioEgressListener

IstioEgressListener specifies the properties of an outbound trafficlistener on the sidecar proxy attached to a workload instance.

FieldTypeDescriptionRequired
portPort
The port associated with the listener. If using Unix domain socket,use 0 as the port number, with a valid protocol. The port ifspecified, will be used as the default destination port associatedwith the imported hosts. If the port is omitted, Istio will infer thelistener ports based on the imported hosts. Note that when multipleegress listeners are specified, where one or more listeners havespecific ports while others have no port, the hosts exposed on alistener port will be based on the listener with the most specificport.
No
bindstring
The IP or the Unix domain socket to which the listener should be boundto. Port MUST be specified if bind is not empty. Format: x.x.x.x orunix:///path/to/uds or unix://@foobar (Linux abstract namespace). Ifomitted, Istio will automatically configure the defaults based on importedservices, the workload instances to which this configuration is applied to andthe captureMode. If captureMode is NONE, bind will default to127.0.0.1.
No
captureModeCaptureMode
When the bind address is an IP, the captureMode option dictateshow traffic to the listener is expected to be captured (or not).captureMode must be DEFAULT or NONE for Unix domain socket binds.
No
hostsstring[]
One or more service hosts exposed by the listenerin namespace/dnsName format. Services in the specified namespacematching dnsName will be exposed.The corresponding service can be a service in the service registry(e.g., a Kubernetes or cloud foundry service) or a service specifiedusing a ServiceEntry or VirtualService configuration. Anyassociated DestinationRule in the same namespace will also be used.

The dnsName should be specified using FQDN format, optionally includinga wildcard character in the left-most component (e.g., prod/.example.com).Set the dnsName to to select all services from the specified namespace(e.g., prod/).

The namespace can be set to , ., or ~, representing any, the current,or no namespace, respectively. For example, /foo.example.com selects theservice from any available namespace while ./foo.example.com only selectsthe service from the namespace of the sidecar. If a host is set to /,Istio will configure the sidecar to be able to reach every service in themesh that is exported to the sidecar’s namespace. The value ~/ can be usedto completely trim the configuration for sidecars that simply receive trafficand respond, but make no outbound connections of their own.

NOTE: Only services and configuration artifacts exported to the sidecar’snamespace (e.g., exportTo value of ) can be referenced.Private configurations (e.g., exportTo set to .) willnot be available. Refer to the exportTo setting in VirtualService,DestinationRule, and ServiceEntry configurations for details.

WARNING: The list of egress hosts in a Sidecar must also includethe Mixer control plane services if they are enabled. Envoy will notbe able to reach them otherwise. For example, add hostistio-system/istio-telemetry.istio-system.svc.cluster.local if telemetryis enabled, istio-system/istio-policy.istio-system.svc.cluster.local ifpolicy is enabled, or add istio-system/ to allow all services in theistio-system namespace. This requirement is temporary and will be removedin a future Istio release.
Yes

IstioIngressListener

IstioIngressListener specifies the properties of an inboundtraffic listener on the sidecar proxy attached to a workload instance.

FieldTypeDescriptionRequired
portPort
The port associated with the listener.
Yes
bindstring
The IP to which the listener should be bound. Must be in theformat x.x.x.x. Unix domain socket addresses are not allowed inthe bind field for ingress listeners. If omitted, Istio willautomatically configure the defaults based on imported servicesand the workload instances to which this configuration is appliedto.
No
captureModeCaptureMode
The captureMode option dictates how traffic to the listener isexpected to be captured (or not).
No
defaultEndpointstring
The loopback IP endpoint or Unix domain socket to whichtraffic should be forwarded to. This configuration can be used toredirect traffic arriving at the bind IP:Port on the sidecar to a localhost:portor Unix domain socket where the application workload instance is listening forconnections. Format should be 127.0.0.1:PORT or unix:///path/to/socket
Yes

OutboundTrafficPolicy

OutboundTrafficPolicy sets the default behavior of the sidecar forhandling outbound traffic from the application.If your application uses one or more externalservices that are not known apriori, setting the policy to ALLOW_ANYwill cause the sidecars to route any unknown traffic originating fromthe application to its requested destination. Users are stronglyencouraged to use ServiceEntry configurations to explicitly declare any externaldependencies, instead of using ALLOW_ANY, so that traffic to theseservices can be monitored.

FieldTypeDescriptionRequired
modeModeNo

OutboundTrafficPolicy.Mode

NameDescription
REGISTRY_ONLY
Outbound traffic will be restricted to services defined in theservice registry as well as those defined through ServiceEntry configurations.
ALLOW_ANY
Outbound traffic to unknown destinations will be allowed, in casethere are no services or ServiceEntry configurations for the destination port.

Sidecar

Sidecar describes the configuration of the sidecar proxy that mediatesinbound and outbound communication of the workload instance to which it isattached.

FieldTypeDescriptionRequired
workloadSelectorWorkloadSelector
Criteria used to select the specific set of pods/VMs on which thisSidecar configuration should be applied. If omitted, the Sidecarconfiguration will be applied to all workload instances in the same namespace.
No
ingressIstioIngressListener[]
Ingress specifies the configuration of the sidecar for processinginbound traffic to the attached workload instance. If omitted, Istio willautomatically configure the sidecar based on the information about the workloadobtained from the orchestration platform (e.g., exposed ports, services,etc.). If specified, inbound ports are configured if and only if theworkload instance is associated with a service.
No
egressIstioEgressListener[]
Egress specifies the configuration of the sidecar for processingoutbound traffic from the attached workload instance to other services in themesh.
Yes
outboundTrafficPolicyOutboundTrafficPolicy
This allows to configure the outbound traffic policy.If your application uses one or more externalservices that are not known apriori, setting the policy to ALLOW_ANYwill cause the sidecars to route any unknown traffic originating fromthe application to its requested destination.
No

WorkloadSelector

WorkloadSelector specifies the criteria used to determine if the Gateway,Sidecar, or EnvoyFilter configuration can be applied to a proxy. The matching criteriaincludes the metadata associated with a proxy, workload instance info such aslabels attached to the pod/VM, or any other info that the proxy providesto Istio during the initial handshake. If multiple conditions arespecified, all conditions need to match in order for the workload instance to beselected. Currently, only label based selection mechanism is supported.

FieldTypeDescriptionRequired
labelsmap<string, string>
One or more labels that indicate a specific set of pods/VMson which this Sidecar configuration should be applied. The scope oflabel search is restricted to the configuration namespace in which thethe resource is present.
Yes