sidecar.proto

Package: istio.networking.v1alpha3

Copyright 2018 Istio Authors

Licensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at

  http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Types:
Enums:
- [ConfigScope](#ConfigScope)
- [CaptureMode](#CaptureMode)
Source File: github.com/solo-io/supergloo/api/external/istio/networking/v1alpha3/sidecar.proto

Sidecar

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

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.

NOTE: Each namespace can have only one Sidecar resource without any workload selector. 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.

The example below delcares a Sidecar resource in the prod-us1 namespace that configures the sidecar to allow egress traffic to public services in the prod-us1, prod-apis, and the istio-system namespaces.

apiVersion: networking.istio.io/v1alpha3
kind: Sidecar
metadata:
  name: default
  namespace: prod-us1
spec:
  egress:
  - hosts:
    - "prod-us1/*"
    - "prod-apis/*"
    - "istio-system/*"
"workloadSelector": .istio.networking.v1alpha3.WorkloadSelector
"ingress": []istio.networking.v1alpha3.IstioIngressListener
"egress": []istio.networking.v1alpha3.IstioEgressListener

Field Type Description Default
workloadSelector .istio.networking.v1alpha3.WorkloadSelector $hide_from_docs 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 current config namespace.
ingress []istio.networking.v1alpha3.IstioIngressListener $hide_from_docs Ingress specifies the configuration of the sidecar for processing inbound traffic to the attached workload. If omitted, Istio will autoconfigure the sidecar based on the information about the workload obtained from the orchestration platform (e.g., exposed ports, services, etc.).
egress []istio.networking.v1alpha3.IstioEgressListener 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 autoconfigure the sidecar to be able to reach every service in the mesh that is visible to this namespace.

IstioIngressListener

$hide_from_docs IstioIngressListener specifies the properties of an inbound traffic listener on the sidecar proxy attached to a workload.

"port": .istio.networking.v1alpha3.Port
"bind": string
"captureMode": .istio.networking.v1alpha3.CaptureMode
"defaultEndpoint": string

Field Type Description Default
port .istio.networking.v1alpha3.Port REQUIRED. The port associated with the listener. If using unix domain socket, use 0 as the port number, with a valid protocol.
bind string The ip or the unix domain socket to which the listener should be bound to. Format: x.x.x.x or unix:///path/to/uds or unix://@foobar (Linux abstract namespace). If omitted, Istio will autoconfigure the defaults based on imported services and the workload to which this configuration is applied to.
captureMode .istio.networking.v1alpha3.CaptureMode When the bind address is an IP, the captureMode option dictates how traffic to the listener is expected to be captured (or not).
defaultEndpoint string The loopback IP endpoint or unix domain socket to which traffic should be forwarded to by default. 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 unix:///path/to/socket

IstioEgressListener

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

"port": .istio.networking.v1alpha3.Port
"bind": string
"captureMode": .istio.networking.v1alpha3.CaptureMode
"hosts": []string

Field Type Description Default
port .istio.networking.v1alpha3.Port $hide_from_docs 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.
bind string $hide_from_docs 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: x.x.x.x or unix:///path/to/uds or unix://@foobar (Linux abstract namespace). If omitted, Istio will autoconfigure the defaults based on imported services and the workload to which this configuration is applied to.
captureMode .istio.networking.v1alpha3.CaptureMode When the bind address is an IP, the captureMode option dictates how traffic to the listener is expected to be captured (or not).
hosts []string One or more services/virtualServices exposed by the listener in namespace/dnsName format. Publicly scoped services and VirtualServices from remote namespaces corresponding to the specified hosts will be imported. The service in a namespace can be a service in the service registry (e.g., a kubernetes or cloud foundry service) or a service specified via ServiceEntry configuration. In addition, any publicly scoped DestinationRule associated with the imported services will also be imported. Set the namespace to * to import a particular service from any available namespace (e.g., “*/foo.example.com”). Set the dnsName field to * to import all services from the specified namespace (e.g., “prod/*“). The services should be specified using FQDN format. NOTE: Only exported services and configuration artifacts from a namespace can be imported. Private services/configuration will not be imported. Refer to the scope setting associated with VirtualService, DestinationRule, ServiceEntry, etc. for details.

WorkloadSelector

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.

"labels": map<string, string>

Field Type Description Default
labels map<string, string> 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.

ConfigScope

Description: ConfigScope defines the visibility of an Istio configuration artifact in a namespace when the namespace is imported. By default all configuration artifacts are public. Configurations with private scope will not be imported when the namespace containing the configuration is imported in a Sidecar.

Name Description
PUBLIC Config with this scope are visible to all workloads in the mesh
PRIVATE Configs with this scope are visible to only workloads in the same namespace as the configuration resource.

CaptureMode

Description: $hide_from_docs CaptureMode describes how traffic to a listener is expected to be captured. 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 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.