Sidecar

    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: 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.

    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. spec:
    6.   workloadSelector:
    7.     labels:
    8.       app: productpage
    9.   ingress:
    10.   - port:
    11.       number: 9080 # binds to proxy_instance_ip:9080 (0.0.0.0:9080, if no unicast IP is available for the instance)
    12.       protocol: HTTP
    13.       name: somename
    14.     defaultEndpoint: 127.0.0.1:8080
    16.   egress:
    17.   - port:
    18.       number: 3306
    19.       protocol: MYSQL
    20.       name: egressmysql
    21.     captureMode: NONE # not needed if metadata is set for entire proxy
    22.     bind: 127.0.0.1
    23.     hosts:
    24.     - "*/mysql.foo.com"

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

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

    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
    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
    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 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 specifies the properties of an inboundtraffic listener on the sidecar proxy attached to a workload instance.

    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
    modeNo

    Sidecar

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

    FieldTypeDescriptionRequired
    workloadSelector
    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
    egress
    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