Sidecar

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.

apiVersion: networking.istio.io/v1alpha3
kind: Sidecar
metadata:
  name: default
  namespace: istio-config
spec:
  egress:
  - hosts:
    - "./*"
    - "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.

apiVersion: networking.istio.io/v1alpha3
kind: Sidecar
metadata:
  name: default
  namespace: prod-us1
spec:
  egress:
  - hosts:
    - "prod-us1/*"
    - "prod-apis/*"
    - "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.

apiVersion: networking.istio.io/v1alpha3
kind: Sidecar
metadata:
  name: default
  namespace: prod-us1
spec:
  ingress:
  - port:
      number: 9080
      protocol: HTTP
      name: somename
    defaultEndpoint: unix:///var/run/someuds.sock
  egress:
  - port:
      number: 9080
      protocol: HTTP
      name: egresshttp
    hosts:
    - "prod-us1/*"
  - hosts:
    - "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.

apiVersion: networking.istio.io/v1alpha3
kind: Sidecar
metadata:
  name: no-ip-tables
  namespace: prod-us1
spec:
  workloadSelector:
    labels:
      app: productpage
  ingress:
  - port:
      number: 9080 # binds to proxy_instance_ip:9080 (0.0.0.0:9080, if no unicast IP is available for the instance)
      protocol: HTTP
      name: somename
    defaultEndpoint: 127.0.0.1:8080
    captureMode: NONE # not needed if metadata is set for entire proxy
  egress:
  - port:
      number: 3306
      protocol: MYSQL
      name: egressmysql
    captureMode: NONE # not needed if metadata is set for entire proxy
    bind: 127.0.0.1
    hosts:
    - "*/mysql.foo.com"

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

apiVersion: networking.istio.io/v1alpha3
kind: ServiceEntry
metadata:
  name: external-svc-mysql
  namespace: ns1
spec:
  hosts:
  - mysql.foo.com
  ports:
  - number: 3306
    name: mysql
    protocol: MYSQL
  location: MESH_EXTERNAL
  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.

apiVersion: networking.istio.io/v1alpha3
kind: Sidecar
metadata:
  name: partial-ip-tables
  namespace: prod-us1
spec:
  workloadSelector:
    labels:
      app: productpage
  ingress:
  - bind: 172.16.1.32
    port:
      number: 80 # binds to 172.16.1.32:80
      protocol: HTTP
      name: somename
    defaultEndpoint: 127.0.0.1:8080
    captureMode: NONE
  egress:
    # use the system detected defaults
    # sets up configuration to handle outbound traffic to services
    # in 192.168.0.0/16 subnet, based on information provided by the
    # service registry
  - captureMode: IPTABLES
    hosts:
    - "*/*"

CaptureMode

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

Name	Description
`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.

Field	Type	Description	Required
`port`	`Port`	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
`bind`	`string`	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` or`unix:///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
`captureMode`	`CaptureMode`	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
`hosts`	`string[]`	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 host`istio-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 the`istio-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.

Field	Type	Description	Required
`port`	`Port`	The port associated with the listener.	Yes
`bind`	`string`	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
`captureMode`	`CaptureMode`	The captureMode option dictates how traffic to the listener isexpected to be captured (or not).	No
`defaultEndpoint`	`string`	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:port`or 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.

Field	Type	Description	Required
`mode`	`Mode`		No

OutboundTrafficPolicy.Mode

Name	Description
`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.

Field	Type	Description	Required
`workloadSelector`	`WorkloadSelector`	Criteria used to select the specific set of pods/VMs on which this`Sidecar` configuration should be applied. If omitted, the `Sidecar`configuration will be applied to all workload instances in the same namespace.	No
`ingress`	`IstioIngressListener[]`	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
`egress`	`IstioEgressListener[]`	Egress specifies the configuration of the sidecar for processingoutbound traffic from the attached workload instance to other services in themesh.	Yes
`outboundTrafficPolicy`	`OutboundTrafficPolicy`	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_ANY`will 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.

Field	Type	Description	Required
`labels`	`map<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