istio.io/content/docs/reference/config/networking/v1alpha3/sidecar/index.html

---
WARNING: THIS IS AN AUTO-GENERATED FILE, DO NOT EDIT. PLEASE MODIFY THE ORIGINAL SOURCE IN THE https://github.com/istio/api REPO
source_repo: https://github.com/istio/api
title: Sidecar
description: Configuration affecting network reachability of a sidecar.
location: https://istio.io/docs/reference/config/networking/v1alpha3/sidecar.html
layout: protoc-gen-docs
generator: protoc-gen-docs
number_of_entries: 5
---
<p><code>Sidecar</code> describes the configuration of the sidecar proxy that mediates
inbound and outbound communication to the workload it is attached to. By
default, Istio will program all sidecar proxies in the mesh with the
necessary configuration required to reach every workload in the mesh, as
well as accept traffic on all the ports associated with the
workload. The Sidecar resource provides a way to fine tune the set of
ports, protocols that the proxy will accept when forwarding traffic to
and from the workload. In addition, it is possible to restrict the set
of services that the proxy can reach when forwarding outbound traffic
from the workload.</p>

<p>Services and configuration in a mesh are organized into one or more
namespaces (e.g., a Kubernetes namespace or a CF org/space). A Sidecar
resource in a namespace will apply to one or more workloads in the same
namespace, selected using the workloadSelector. In the absence of a
workloadSelector, it will apply to all workloads in the same
namespace. When determining the Sidecar resource to be applied to a
workload, preference will be given to the resource with a
workloadSelector that selects this workload, over a Sidecar resource
without any workloadSelector.</p>

<p>NOTE: <em><em>Each namespace can have only one Sidecar resource without any
workload selector</em></em>. The behavior of the system is undefined if more
than one selector-less Sidecar resources exist in a given namespace. The
behavior of the system is undefined if two or more Sidecar resources
with a workload selector select the same workload.</p>

<p>The example below declares a Sidecar resource in the prod-us1 namespace
that configures the sidecars in the namespace to allow egress traffic to
public services in the prod-us1, prod-apis, and the istio-system
namespaces.</p>

<pre><code class="language-yaml">apiVersion: networking.istio.io/v1alpha3
kind: Sidecar
metadata:
  name: default
  namespace: prod-us1
spec:
  egress:
  - hosts:
    - &quot;prod-us1/*&quot;
    - &quot;prod-apis/*&quot;
    - &quot;istio-system/*&quot;
</code></pre>

<p>The example below declares a Sidecar resource in the prod-us1 namespace
that accepts inbound HTTP traffic on port 9080 and forwards
it to the attached workload listening on a Unix domain socket. In the
egress direction, in addition to the istio-system namespace, the sidecar
proxies only HTTP traffic bound for port 9080 for services in the
prod-us1 namespace.</p>

<pre><code class="language-yaml">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:
  - hosts:
    - &quot;istio-system/*&quot;
  - port:
      number: 9080
      protocol: HTTP
      name: egresshttp
    hosts:
    - &quot;prod-us1/*&quot;
</code></pre>

<p>If the workload is deployed without IP tables based traffic capture, the
Sidecar resource is the only way to configure the ports on the proxy
attached to the workload. The following example declares a Sidecar
resource in the prod-us1 namespace for all pods with labels &ldquo;app:
productpage&rdquo; belonging to the productpage.prod-us1 service. Assuming
that these pods are deployed without IPtable rules (i.e. the Istio init
container) and the proxy metadata <code>ISTIO_META_INTERCEPTION_MODE</code> is set to
NONE, the specification below allows such pods to receive HTTP traffic
on port 9080 and forward it to the application listening on
127.0.0.1:8080. It also allows the application to communicate with a
backing MySQL database on 127.0.0.1:3306, that then gets proxied to the
externally hosted MySQL service at mysql.foo.com:3306.</p>

<pre><code class="language-yaml">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 0.0.0.0:9080
      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:
    - &quot;*/mysql.foo.com&quot;
</code></pre>

<p>And the associated service entry for routing to mysql.foo.com:3306</p>

<pre><code class="language-yaml">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
</code></pre>

<p>It is also possible to mix and match traffic capture modes in a single
proxy. For example, consider a setup where internal services are on the
192.168.0.0/16 subnet. So, IP tables are setup on the VM to capture all
outbound traffic on 192.168.0.0/16 subnet. Assume that the VM has an
additional network interface on 172.16.0.0/16 subnet for inbound
traffic. The following Sidecar configuration allows the VM to expose a
listener on 172.16.1.32:80 (the VM&rsquo;s IP) for traffic arriving from the
172.16.0.0/16 subnet. Note that in this scenario, the
<code>ISTIO_META_INTERCEPTION_MODE</code> metadata on the proxy in the VM should
contain &ldquo;REDIRECT&rdquo; or &ldquo;TPROXY&rdquo; as its value, implying that IP tables
based traffic capture is active.</p>

<pre><code class="language-yaml">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:
    - &quot;*/*&quot;
</code></pre>

<h2 id="CaptureMode">CaptureMode</h2>
<section>
<p>CaptureMode describes how traffic to a listener is expected to be
captured. Applicable only when the listener is bound to an IP.</p>

<table class="enum-values">
<thead>
<tr>
<th>Name</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr id="CaptureMode-DEFAULT">
<td><code>DEFAULT</code></td>
<td>
<p>The default capture mode defined by the environment</p>

</td>
</tr>
<tr id="CaptureMode-IPTABLES">
<td><code>IPTABLES</code></td>
<td>
<p>Capture traffic using IPtables redirection</p>

</td>
</tr>
<tr id="CaptureMode-NONE">
<td><code>NONE</code></td>
<td>
<p>No traffic capture. When used in egress listener, the application is
expected to explicitly communicate with the listener port/unix
domain socket. When used in ingress listener, care needs to be taken
to ensure that the listener port is not in use by other processes on
the host.</p>

</td>
</tr>
</tbody>
</table>
</section>
<h2 id="IstioEgressListener">IstioEgressListener</h2>
<section>
<p>IstioEgressListener specifies the properties of an outbound traffic
listener on the sidecar proxy attached to a workload.</p>

<table class="message-fields">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr id="IstioEgressListener-port">
<td><code>port</code></td>
<td><code><a href="/docs/reference/config/networking/v1alpha3/gateway.html#Port">Port</a></code></td>
<td>
<p>The port associated with the listener. If using Unix domain socket,
use 0 as the port number, with a valid protocol. The port if
specified, will be used as the default destination port associated
with the imported hosts. If the port is omitted, Istio will infer the
listener ports based on the imported hosts. Note that when multiple
egress listeners are specified, where one or more listeners have
specific ports while others have no port, the hosts exposed on a
listener port will be based on the listener with the most specific
port.</p>

</td>
</tr>
<tr id="IstioEgressListener-bind">
<td><code>bind</code></td>
<td><code>string</code></td>
<td>
<p>The ip or the Unix domain socket to which the listener should be bound
to. Port MUST be specified if bind is not empty. Format: <code>x.x.x.x</code> or
<code>unix:///path/to/uds</code> or <code>unix://@foobar</code> (Linux abstract namespace). If
omitted, Istio will automatically configure the defaults based on imported
services, the workload to which this configuration is applied to and
the captureMode. If captureMode is NONE, bind will default to
127.0.0.1.</p>

</td>
</tr>
<tr id="IstioEgressListener-capture_mode">
<td><code>captureMode</code></td>
<td><code><a href="#CaptureMode">CaptureMode</a></code></td>
<td>
<p>When the bind address is an IP, the captureMode option dictates
how traffic to the listener is expected to be captured (or not).
captureMode must be DEFAULT or NONE for Unix domain socket binds.</p>

</td>
</tr>
<tr id="IstioEgressListener-hosts">
<td><code>hosts</code></td>
<td><code>string[]</code></td>
<td>
<p>REQUIRED: One or more service hosts exposed by the listener
in <code>namespace/dnsName</code> format. Services in the specified namespace
matching <code>dnsName</code> 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 specified
using a <code>ServiceEntry</code> or <code>VirtualService</code> configuration. Any
associated <code>DestinationRule</code> in the same namespace will also be used.</p>

<p>The <code>dnsName</code> should be specified using FQDN format, optionally including
a wildcard character in the left-most component (e.g., <code>prod/*.example.com</code>).
Set the <code>dnsName</code> to <code>*</code> to select all services from the specified namespace
(e.g.,<code>prod/*</code>). The <code>namespace</code> can also be set to <code>*</code> to select a particular
service from any available namespace (e.g., &ldquo;*/foo.example.com&rdquo;).</p>

<p>NOTE: Only services and configuration artifacts exported to the sidecar&rsquo;s
namespace (e.g., <code>exportTo</code> value of <code>*</code>) can be referenced.
Private configurations (e.g., <code>exportTo</code> set to <code>.</code>) will
not be available. Refer to the <code>exportTo</code> setting in <code>VirtualService</code>,
<code>DestinationRule</code>, and <code>ServiceEntry</code> configurations for details.</p>

</td>
</tr>
</tbody>
</table>
</section>
<h2 id="IstioIngressListener">IstioIngressListener</h2>
<section>
<p>IstioIngressListener specifies the properties of an inbound
traffic listener on the sidecar proxy attached to a workload.</p>

<table class="message-fields">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr id="IstioIngressListener-port">
<td><code>port</code></td>
<td><code><a href="/docs/reference/config/networking/v1alpha3/gateway.html#Port">Port</a></code></td>
<td>
<p>REQUIRED. The port associated with the listener. If using
Unix domain socket, use 0 as the port number, with a valid
protocol.</p>

</td>
</tr>
<tr id="IstioIngressListener-bind">
<td><code>bind</code></td>
<td><code>string</code></td>
<td>
<p>The ip or the Unix domain socket to which the listener should be bound
to. Format: <code>x.x.x.x</code> or <code>unix:///path/to/uds</code> or <code>unix://@foobar</code> (Linux
abstract namespace). If omitted, Istio will automatically configure the defaults
based on imported services and the workload to which this
configuration is applied to.</p>

</td>
</tr>
<tr id="IstioIngressListener-capture_mode">
<td><code>captureMode</code></td>
<td><code><a href="#CaptureMode">CaptureMode</a></code></td>
<td>
<p>When the bind address is an IP, the captureMode option dictates
how traffic to the listener is expected to be captured (or not).
captureMode must be DEFAULT or NONE for Unix domain socket binds.</p>

</td>
</tr>
<tr id="IstioIngressListener-default_endpoint">
<td><code>defaultEndpoint</code></td>
<td><code>string</code></td>
<td>
<p>REQUIRED: The loopback IP endpoint or Unix domain socket to which
traffic should be forwarded to. This configuration can be used to
redirect traffic arriving at the bind point on the sidecar to a port
or Unix domain socket where the application workload is listening for
connections. Format should be 127.0.0.1:PORT or <code>unix:///path/to/socket</code></p>

</td>
</tr>
</tbody>
</table>
</section>
<h2 id="Sidecar">Sidecar</h2>
<section>
<table class="message-fields">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr id="Sidecar-workload_selector">
<td><code>workloadSelector</code></td>
<td><code><a href="#WorkloadSelector">WorkloadSelector</a></code></td>
<td>
<p>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 workloads in the same config
namespace.</p>

</td>
</tr>
<tr id="Sidecar-ingress">
<td><code>ingress</code></td>
<td><code><a href="#IstioIngressListener">IstioIngressListener[]</a></code></td>
<td>
<p>Ingress specifies the configuration of the sidecar for processing
inbound traffic to the attached workload. If omitted, Istio will
automatically configure the sidecar based on the information about the workload
obtained from the orchestration platform (e.g., exposed ports, services,
etc.). If specified, inbound ports are configured if and only if the
workload is associated with a service.</p>

</td>
</tr>
<tr id="Sidecar-egress">
<td><code>egress</code></td>
<td><code><a href="#IstioEgressListener">IstioEgressListener[]</a></code></td>
<td>
<p>Egress specifies the configuration of the sidecar for processing
outbound traffic from the attached workload to other services in the
mesh. If omitted, Istio will automatically configure the sidecar to be able to
reach every service in the mesh that is visible to this namespace.</p>

</td>
</tr>
</tbody>
</table>
</section>
<h2 id="WorkloadSelector">WorkloadSelector</h2>
<section>
<p>WorkloadSelector specifies the criteria used to determine if the Gateway
or Sidecar resource can be applied to a proxy. The matching criteria
includes the metadata associated with a proxy, workload info such as
labels attached to the pod/VM, or any other info that the proxy provides
to Istio during the initial handshake. If multiple conditions are
specified, all conditions need to match in order for the workload to be
selected. Currently, only label based selection mechanism is supported.</p>

<table class="message-fields">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr id="WorkloadSelector-labels">
<td><code>labels</code></td>
<td><code>map&lt;string,&nbsp;string&gt;</code></td>
<td>
<p>REQUIRED: One or more labels that indicate a specific set of pods/VMs
on which this sidecar configuration should be applied. The scope of
label search is restricted to the configuration namespace in which the
the resource is present.</p>

</td>
</tr>
</tbody>
</table>
</section>