Sidecar CRD reference

Sidecar introduction

The Sidecar CRD defines the configuration for the Sidecar proxy, which mediates inbound and outbound communication for its attached workload instance. By default, Istio programs all Sidecar proxies in the mesh with the necessary configuration to reach every workload instance in the mesh and to accept traffic on all ports associated with the workload. The Sidecar configuration enables fine-tuning of the ports and protocols that the proxy supports for receiving and forwarding traffic to and from the workload. Additionally, a Sidecar can restrict the set of services that the proxy can access when forwarding outbound traffic from the workload.

A service mesh uses namespaces to manage services and configurations. A Sidecar configuration in a namespace is applied to workload instances in the same namespace using the workloadSelector field. If the workloadSelector field is absent, the Sidecar applies to all workload instances in that namespace. A Sidecar resource with a workloadSelector that selects a specific workload instance takes precedence over a Sidecar resource without a workloadSelector. If a more specific Sidecar is selected, the configuration from the namespace-wide Sidecar is completely ignored.

Considerations

• Each namespace can have only one Sidecar configuration without a specified workloadSelector. This configuration specifies the default values for all pods in that namespace. Name the namespace-scoped Sidecar default.

  • If two or more Sidecar configurations without a selector exist in a given namespace, the system behavior is undefined.

  • If two or more Sidecar configurations with a workload selector select the same workload instance, the system behavior is undefined.

• A Sidecar configuration in the MeshConfig root namespace is applied by default to all namespaces that do not have a Sidecar configuration. This global default Sidecar configuration must not include any workload selectors.

• Sidecars do not apply to gateways, even though gateways are Istio proxies.

Configuration examples

Example 1: Global default Sidecar configuration

The following example declares a global default Sidecar configuration in the root namespace istio-config. This configuration configures Sidecars in all namespaces to allow egress traffic only to other workloads in the same namespace or to services in the istio-system namespace.

apiVersion: networking.istio.io/v1beta1
kind: Sidecar
metadata:
  name: default
  namespace: istio-config
spec:
  egress:
  - hosts:
    - "./*"
    - "istio-system/*"

Example 2: Declare a Sidecar configuration in the prod-us1 namespace to overwrite the global default configuration

The following example declares a Sidecar configuration in the prod-us1 namespace. This configuration overwrites the global default configuration defined in Example 1 and configures the Sidecars in its namespace to allow egress traffic to services in the prod-us1, prod-apis, and istio-system namespaces.

apiVersion: networking.istio.io/v1beta1
kind: Sidecar
metadata:
  name: default
  namespace: prod-us1
spec:
  egress:
  - hosts:
    - "prod-us1/*"
    - "prod-apis/*"
    - "istio-system/*"

Example 3: Declare a Sidecar configuration for all pods with the label app: ratings

The following example declares a Sidecar configuration in the prod-us1 namespace for all pods with the label app: ratings. These pods belong to the ratings.prod-us1 service. The workload accepts inbound HTTP traffic on port 9080 and forwards it to the workload instance listening on a Unix domain socket. For egress traffic, in addition to the istio-system namespace, the Sidecar proxy only forwards HTTP traffic destined for port 9080 in the prod-us1 namespace.

apiVersion: networking.istio.io/v1beta1
kind: Sidecar
metadata:
  name: ratings
  namespace: prod-us1
spec:
  workloadSelector:
    labels:
      app: ratings
  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/*"

Example 4: Declare a Sidecar configuration for all pods of the productpage.prod-us1 service that have the app:productpage label

If a workload is deployed without IPTables-based traffic capture, the only way to configure the ports of the workload proxy is through a Sidecar configuration.

The following example declares a Sidecar configuration for all pods of the productpage.prod-us1 service that have the app:productpage label in the prod-us1 namespace. Assume that these pods do not use IPTables rules (that is, they lack an istio-init container) and the proxy metadata ISTIO_META_INTERCEPTION_MODE is set to NONE. This configuration allows the pods to receive HTTP traffic on port 9080 (wrapped in Istio bidirectional TLS) and forward it to the application listening on 127.0.0.1:8080. It also enables the application to communicate with a backend MySQL database at 127.0.0.1:3306, which is then proxied to an external MySQL service hosted at mysql.foo.com:3306.

apiVersion: networking.istio.io/v1beta1
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"

apiVersion: networking.istio.io/v1beta1
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

Field descriptions

Sidecar

A Sidecar describes the configuration of the Sidecar proxy attached to a workload. The proxy modulates inbound and outbound communications for the workload.

IstioIngressListener

IstioIngressListener specifies the properties of an inbound traffic listener on a Sidecar proxy attached to a workload instance.

IstioEgressListener

IstioEgressListener specifies the properties of an outbound traffic listener on a Sidecar proxy attached to a workload instance.

WorkloadSelector

WorkloadSelector specifies the conditions under which a Gateway, Sidecar, EnvoyFilter, ServiceEntry, or DestinationRule configuration can be applied to a proxy. Matching conditions include metadata related to the proxy, workload instance information (such as labels attached to a pod), or any other information provided by the proxy to Istio during the initial handshake. If multiple conditions are specified, all conditions must match for a workload instance to be selected. Only label-based selection is supported.

OutboundTrafficPolicy

OutboundTrafficPolicy sets the default behavior of the Sidecar proxy for handling outbound traffic from an application. If the application uses an unregistered external service, setting the policy to ALLOW_ANY causes the Sidecar to route any unknown traffic from the application to its requested destination. Instead of using ALLOW_ANY, declare external dependencies using a ServiceEntry configuration. This approach enables monitoring of traffic to these services.

CaptureMode

CaptureMode describes how to capture traffic that is incoming to a listener. This applies only when the listener is bound to an IP address.