diff --git a/_includes/doc-nav.html b/_includes/doc-nav.html index 16d8c4d126..ff6a95aecb 100644 --- a/_includes/doc-nav.html +++ b/_includes/doc-nav.html @@ -9,7 +9,7 @@
  • Quick Start
  • Guides
  • Tutorials
    • -
  • Reference API
    • +
  • Reference
  • Samples
    • {% include contribute-links.html %} diff --git a/_includes/doc-side-guides-nav.html b/_includes/doc-side-guides-nav.html index 2c5ec23837..893834efb9 100644 --- a/_includes/doc-side-guides-nav.html +++ b/_includes/doc-side-guides-nav.html @@ -2,8 +2,7 @@ {% assign current = page.url | downcase | split: '/' %}
  • Guides
  • What is Istio?
    • -
  • Istio Concepts
    • -
  • Istio Proxy
    • -
  • Istio Configuration Manager
    • -
  • Istio Mixer
    • +
  • Architecture
    • +
  • Service Model
    • +
  • Mixer
    • diff --git a/_includes/footer.html b/_includes/footer.html index 54547e3d12..8d92740c53 100644 --- a/_includes/footer.html +++ b/_includes/footer.html @@ -12,7 +12,7 @@

  • Quick Start

  • Guides

  • Tutorials

    • -

  • Reference APIs

    • +

  • Reference

  • Samples

    • diff --git a/_includes/nav.html b/_includes/nav.html index cbcbee34c8..a33fa1cd13 100644 --- a/_includes/nav.html +++ b/_includes/nav.html @@ -41,7 +41,7 @@
  • Quick Start
    •
  • Guides
    •
  • Tutorials
    •  -
  • Reference API
    •  +
  • Reference
    •
  • Samples
    •  diff --git a/_includes/sticky-nav.html b/_includes/sticky-nav.html index 8aa149c5d2..2452bf3f43 100644 --- a/_includes/sticky-nav.html +++ b/_includes/sticky-nav.html @@ -41,7 +41,7 @@
  • Quick Start
    •
  • Guides
    •
  • Tutorials
    •  -
  • Reference API
    •  +
  • Reference
    •
  • Samples
    •  diff --git a/docs/guides/architecture.md b/docs/guides/architecture.md new file mode 100644 index 0000000000..c48ae6ecea --- /dev/null +++ b/docs/guides/architecture.md @@ -0,0 +1,48 @@ +--- +bodyclass: docs +headline: Architecture +layout: docs +sidenav: doc-side-guides-nav.html +title: Architecture +type: markdown +--- + +The Istio service mesh consists of three major components: + +## Proxy + +The Istio proxy is designed to mediate inbound and outbound +traffic for all Istio-managed services. The Istio proxy is based on +[Envoy](https://lyft.github.io/envoy/). Istio leverages Envoy's features +such as dynamic service discovery, load balancing, TLS termination, HTTP/2 & gRPC +proxying, circuit breakers, health checks, staged rollouts with %-based +traffic split, fault injection, and a rich set of metrics. In addition, +Istio extends the proxy to interact with the mixer to enforce various +access control policies rate limiting, ACLs, as well as telemetry +reporting. + +## Mixer + +The Istio mixer is responsible for enforcing access control +and usage policies across the service mesh and collects telemetry data from +proxies and istio-managed services alike. The Istio proxy extracts request +level attributes that are then evaluated by the mixer. More info on the +attribute extraction and policy evaluation can be found +[here](../reference/attributes.md). The mixer includes a flexible plugin model enabling +it to interface to a variety of host environments and configured backends, +abstracting the proxy and Istio-managed services from these details. + +## Manager + +The Istio manager serves as an interface between the user +and Istio, collecting configuration, validating it and propagating it to +various components. It abstracts platform-specific implementation details +from the mixer and proxies, providing them with an +[abstract representation](model.md) of user's services that is independent +of the underlying platform. In addition, [traffic management rules](../reference/rule-dsl.md) +(i.e. generic layer-4 rules and layer-7 HTTP/gRPC routing rules) +can be programmed at runtime via the Istio Manager. + +The overall architecture of an Istio-based service. + +
    diff --git a/docs/guides/index.md b/docs/guides/index.md index 375646ace2..cdfe37de09 100644 --- a/docs/guides/index.md +++ b/docs/guides/index.md @@ -7,6 +7,22 @@ title: Guides type: markdown --- -This document introduces you to ... +As enterprises migrate from traditional VM infrastructures to more agile +microservice-based deployments on container platforms, there is a need for +a simplifying technology that can take care of common cross-cutting +capabilities around service communication and management such as secure +interconnect, service discovery & load balancing, staged rollouts, A/B +testing, intelligent rate limiting, authentication, access control, +monitoring, logging, etc. + +Towards this goal, we are designing Istio, an _open +platform-independent service mesh_ that takes care of traffic management, +policy enforcement, rate limiting, and telemetry collection. +It allows application developers to focus on the +business logic and iterate quickly on new features by managing how traffic +flows across their services. And it simplifies the operators' job of enforcing +various policies and monitor the mesh from a central control point, +independent of the evolution of the application ensuring continuous +compliance with policies of the organization/business unit.
    diff --git a/docs/guides/mixer.md b/docs/guides/mixer.md new file mode 100644 index 0000000000..d06c1d4be6 --- /dev/null +++ b/docs/guides/mixer.md @@ -0,0 +1,39 @@ +--- +bodyclass: docs +headline: Istio Mixer +layout: docs +sidenav: doc-side-guides-nav.html +title: Istio Mixer +type: markdown +--- + +The mixer provides the control-plane abstractions necessary for most real-world multi-tenant services. +The proxy delegates policy decisions to the mixer and dispatches its telemetry data to the mixer, which +proceeds to repackage and redirect the data towards configured backends. + +Services within the Istio mesh can also directly integrate with the mixer. For example, services may wish to provide rich telemetry for particular operations +beyond what the proxy automatically collects. Or services may use the mixer for resource-oriented quota management. Services that leverage the mixer in this +way are abstracted from environment-specific control plane details, greatly easing the process of hosting the code in +different environments (different clouds & on-prem) + +The mixer provides three core features: + +**Precondition Checking**. Enables callers to verify a number of preconditions before responding to an incoming request from a service consumer. +Preconditions can include whether the service consumer is properly authenticated, is on the service's whitelist, passes ACL checks, and more. + +**Telemetry Reporting**. Enables services to produce logging, monitoring, tracing and billing streams intended for the service producer itself as well as +for its consumers. + +**Quota Management**. Enables services to allocate and free quota on a number of dimensions, Quotas are used as a relatively simple resource management +tool to provide some fairness between service consumers when contending for limited resources. + +## Mixer Adapters + +Adapters are binary-level plugins to the mixer which make it possible to customize the mixer’s behavior. Adapters allow the mixer to interface +to different backend systems that deliver core control-plane functionality, such as logging, monitoring, quotas, ACL checking, and more. Adapters +enable the mixer to expose a single consistent control API, independent of the backends in use. The exact set of adapters +used at runtime is determined through configuration. + +Mixer and its adapters. + +
    diff --git a/docs/guides/model.md b/docs/guides/model.md new file mode 100644 index 0000000000..e7c19cc2c9 --- /dev/null +++ b/docs/guides/model.md @@ -0,0 +1,82 @@ +--- +bodyclass: docs +headline: Istio Service Model +layout: docs +sidenav: doc-side-guides-nav.html +title: Istio Service Model +type: markdown +--- + +The Istio manager serves as an interface between the user and Istio, +collecting configuration, validating it and propagating it to various +components. It abstracts platform-specific implementation details from the +mixer and proxies, providing them with an abstract representation of user's +services that is independent of the underlying platform. The model +described below assumes a microservice-based application owned by a single +tenant. + +**Istio-managed service:** Modern cloud applications are created by +composing together independent sets of services. Individual services are +referenced by their fully-qualified domain name (FQDN) and one or more +ports where the service is listening for connections. + +**Platform-agnostic internal representation:** The Istio model of a +microservice is independent of how it is represented in the underlying +platform (Kubernetes, Mesos, CloudFoundry, etc.). Platform-specific +adapters are responsible for populating the internal model representation +with various fields, from the metadata found in the platform. + +## Multiple versions of a service + +Istio introduces the concept of a service version, which is a finer-grained +way to subdivide service instances by versions (`v1`, `v2`) or environment +(`staging`, `prod`). These variants are not necessarily different API +versions: they could be iterative changes to the same service, deployed in +different environments (prod, staging, dev, etc.). Common scenarios where +this occurs include A/B testing, canary rollouts, etc. Istio +[routing rules](../reference/rule-dsl.md) can refer to the service versions, to provide +additional control over traffic between services. + +**Tags** Each version of a service can be differentiated by a unique set of +tags associated with the version. Tags are simple key value pairs +assigned to the instances of a particular service version, i.e., all +instances of the same version must have the same tags. + +## Populating the abstract service model + +Where possible, Istio leverages the service registration and discovery +mechanism provided by the underlying platform to populate its abstract +service model. Most container platforms come built-in with a service +registry (e.g., kubernetes, mesos) where a pod specification can contain +all the version related tags. Upon launching the pod, the platform +automatically registers the pod with the registry along with the tags. In +other platforms, a dedicated service registration agent might be needed to +automatically register the service with a service registration/discovery +solution like Consul, etc. + +At the moment, Istio integrates readily with the Kubernetes service registry +and automatically discovers various services, their pods etc., and +groups the pods into unique sets -- each set representing a service +version. In future, Istio will add support for pulling in similar +information from Mesos registry and *potentially* other registries. + +## Communication between services + +Clients of a service have no knowledge of different versions of the +service. They can continue to access the services using the hostname/IP +address of the service. The Istio Proxy intercepts and forwards all +requests/responses between the client and the service. + +The actual choice of the service version is determined dynamically by the +Istio Proxy based on the routing rules set forth by the operator. This +model enables the application code to decouple itself from the +evolution of its dependent services, while providing other benefits as well +(see [mixer](mixer.md)). Routing rules allow the proxy to select a version based on +criterion such as (headers, url, etc.), tags associated with +source/destination and/or by weights assigned to each version. + +Note that Istio does not provide a DNS. Applications can try to resolve the +FQDN using the DNS service present in the underlying platform (kube-dns, +mesos-dns, etc.). + +
    diff --git a/docs/reference/attributes.md b/docs/reference/attributes.md new file mode 100644 index 0000000000..9ccb0422f7 --- /dev/null +++ b/docs/reference/attributes.md @@ -0,0 +1,119 @@ +--- +bodyclass: docs +headline: 'Mixer Attributes' +layout: docs +title: Mixer Attributes +type: markdown +--- + +Istio uses *attributes* to describe runtime behavior of services running in the mesh. Attributes are named and typed pieces of metadata +describing ingress and egress traffic and the environment this traffic occurs in. An Istio attribute carries a specific piece +of information such as the error code of an API request, the latency of an API request, or the +original IP address of a TCP connection. + +Istio's policy evaluation model operates on attributes. For example, access control is configured by +specifying policies against particular attribute values. + +A given Istio deployment has a fixed vocabulary of attributes that it understands. The specific vocabulary is +determined by the set of attribute producers being used in the deployment. The primary attribute producer in Istio +is the proxy, although the mixer and services can also introduce attributes. + +Attribute producers declare the set of attributes they produce using the [`AttributeDescriptor`](https://raw.githubusercontent.com/istio/api/master/mixer/v1/config/descriptor/attribute_descriptor.proto) +message: + + message AttributeDescriptor { + // The name of this descriptor, referenced from individual attribute instances and other + // descriptors. + string name = 1; + + // An optional human-readable description of the attribute's purpose. + string description = 2; + + // The type of data carried by attributes + ValueType value_type = 3; + } + + enum ValueType { + // Invalid, default value. + VALUE_TYPE_UNSPECIFIED = 0; + + // An undiscriminated variable-length string. + STRING = 1; + + // An undiscriminated 64-bit signed integer. + INT64 = 2; + + // An undiscriminated 64-bit floating-point value. + DOUBLE = 3; + + // An undiscriminated boolean value. + BOOL = 4; + + // A point in time. + TIMESTAMP = 5; + + // An IP address. + IP_ADDRESS = 6; + + // An email address. + EMAIL_ADDRESS = 7; + + // A URI. + URI = 8; + + // A DNS name. + DNS_NAME = 9; + + // A span between two points in time. + DURATION = 10; + + // A map string -> string, typically used by headers. + STRING_MAP = 11; + } + +When an attribute is used in Istio, its name is given along with a value. The value must be of the type declared by the corresponding descriptor. This +type checking makes it possible for the Istio system to statically detect or prevent many configuration errors. + +# Standard Istio Attribute Vocabulary + +In a standard Istio deployment (using the Istio proxy), the system will produce the following set of attributes. This is considered the canonical attribute set for Istio. + +| Name | Type | Description | Kubernetes Example | +|------|------|-------------|--------------------| +| source.ip | ip_address | The IP address of the client that sent the request. | 10.0.0.117 | +| source.port | int64 | The port on the client that sent the request. | 9284 | +| source.name | string | The fully qualified name of the application that sent the request. | redis-master.namespace.deps.cluster.local | +| source.uid | string | A unique identifier for the particular instance of the application that sent the request. | redis-master-2353460263-1ecey.namespace.pods.cluster.local | +| source.namespace | string | The namespace of the sender of the request. | namespace.cluster.local | +| source.labels | map | A map of key-value pairs attached to the source. | | +| source.user | string | The user running the target application. | service-account@namespace.cluster.local | +| target.ip | ip_address | The IP address the request was sent to. | 10.0.0.104 | +| target.port | int64 | The port the request was sent to. | 8080 | +| target.service | dns_name | The hostname that was the target of the request. | my-svc.my-namespace.svc.cluster.local | +| target.name | string | The fully qualified name of the application that was the target of the request. | | +| target.uid | string | A unique identifier for the particular instance of the application that received the request. | | +| target.namespace | string | The namespace of the receiver of the request. | | +| target.labels | map | A map of key-value pairs attached to the target. | | +| target.user | string | The user running the target application. | service-account@namespace.cluster.local | +| origin.ip | ip_address | The IP address of the originating application | | +| origin.name | string | The fully qualified name of the originating application | | +| origin.uid | string | A unique identifier for the particular instance of the application that originated the request. This must be unique within the cluster. | for in cluster pod-id gives sufficient to ascertain all other attributes needed by the policy. | +| origin.namespace | string | The namespace of the originator of the request. | | +| origin.labels | map | A map of key-value pairs attached to the origin. | | +| origin.user | string | The user running the originating application. | | +| request.headers | map | A map of HTTP headers attached to the request. | | +| request.id | string | A unique ID for the request, which can be propagated to downstream systems. This should be a guid or a psuedo-guid with a low probability of collision in a temporal window measured in days or weeks. | | +| request.path | string | The HTTP URL path including query string | | +| request.host | string | The HTTP Host header. | | +| request.method | string | The HTTP method. | | +| request.reason | string | The system parameter for auditing reason. It is required for cloud audit logging and GIN logging | | +| request.referer | string | The HTTP referer header. | | +| request.scheme | string | URI Scheme of the request | | +| request.size | int64 | Size of the request in bytes. For HTTP requests this is equivalent to the Content-Length header. | | +| request.time | timestamp | The timestamp when the target receives the request. This should be equivalent to Firebase "now". | | +| request.user-agent | string | The HTTP User-Agent header. | | +| response.headers | map | A map of HTTP headers attached to the response. | | +| response.size | int64 | Size of the response body in bytes | | +| response.time | timestamp | The timestamp when the target produced the response. | | +| response.duration | duration | The amount of time the response took to generate. | | +| response.code | int64 | The response's HTTP status code | | diff --git a/docs/reference/index.html b/docs/reference/index.md similarity index 52% rename from docs/reference/index.html rename to docs/reference/index.md index d6a01519f9..c7bf77ec59 100644 --- a/docs/reference/index.html +++ b/docs/reference/index.md @@ -1,7 +1,7 @@ --- bodyclass: docs -headline: 'API Reference' +headline: 'Reference' layout: docs -title: Reference API +title: Reference type: markdown --- diff --git a/docs/reference/istioctl.md b/docs/reference/istioctl.md new file mode 100644 index 0000000000..d12097a1ed --- /dev/null +++ b/docs/reference/istioctl.md @@ -0,0 +1,100 @@ +--- +bodyclass: docs +headline: 'Istioctl CLI' +layout: docs +title: Istioctl CLI +type: markdown +--- + +`istioctl` is a command line interface for managing an Istio service mesh. This overview covers +synax, describes command operations, and provides examples. + +# Syntax + +Istioctl commands follow the syntax: + +``` +istioctl [targets] [flags] +``` + +where `command`, `targets` and `flags` are: + +* **command**: the operation to perform, such as `create`, `delete`, `replace`, or `list`. +* **targets**: targets for commands such as delete +* **flags**: Optional flags. For example specify `--file ` to specify a configuration file to create from. + +# Operations + +* **create**: Create policies and rules +* **delete**: Delete policies or rules +* **get**: Retrieve policy/policies or rules +* **replace**: Replace policies and rules +* **version**: Display CLI version information + +_kubernetes specific_ +* **kube-inject**: Inject istio runtime proxy into kubernetes + resources. This command has been added to aid in `istiofying` + services for kubernetes and should eventually go away once a proper + istio admission controller for kubernetes is available. + +# Policy and Rule types + +* **route-rule** Describes a rule for routing network traffic. See [Route Rules](rule-dsl.md#route-rules) for details on routing rules. +* **destination-policy** Describes a policy for traffic destinations. See [Destination Policies](rule-dsl.md#destination-policies) for details on destination policies. + +# Examples of common operations + +`istioctl create` - Create policies or rules from a file or stdin. + +``` +// Create a rule using the definition in example-routing.yaml. +$ istioctl create -f example-routing.yaml +``` + +`istioctl delete` - Create policies or rules from a file or stdin. + +``` +// Delete a rule using the definition in example-routing.yaml. +$ istioctl delete -f example-routing.yaml +``` + +`istioctl get` - List policies or rules in YAML format + +``` +// List route rules +istioctl get route-rules + +// List destination policies +istioctl get destination-policies +``` + +# kube-inject + +A short term workaround for the lack of a proper istio admision +controller is client-side injection. Use `istioctl kube-inject` to add the +necessary configurations to a kubernetes resource files. + + istioctl kube-inject -f deployment.yaml -o deployment-with-istio.yaml + +Or update the resource on the fly before applying. + + kubectl create -f <(istioctl kube-inject -f depoyment.yaml) + +Or update an existing deployment. + + kubectl get deployment -o yaml | istioctl kube-inject -f - | kubectl apply -f - + +`istioctl kube-inject` will update +the [PodTemplateSpec](https://kubernetes.io/docs/api-reference/v1/definitions/#_v1_podtemplatespec) in +kubernetes Job, DaemonSet, ReplicaSet, and Deployment YAML resource +documents. Support for additional pod-based resource types can be +added as necessary. + +Unsupported resources are left unmodified so, for example, it is safe +to run `istioctl kube-inject` over a single file that contains multiple +Service, ConfigMap, and Deployment definitions for a complex +application. + +The Istio project is continually evolving so the low-level proxy +configuration may change unannounced. When in doubt re-run `istioctl kube-inject` +on your original deployments. diff --git a/docs/reference/rule-dsl.md b/docs/reference/rule-dsl.md new file mode 100644 index 0000000000..2bb50605f9 --- /dev/null +++ b/docs/reference/rule-dsl.md @@ -0,0 +1,518 @@ +--- +bodyclass: docs +headline: 'Routing & Traffic Management' +layout: docs +title: Routing & Traffic Management +type: markdown +--- + +* [Overview](#overview) +* [Route Rules](#route-rules) + * [destination](#destination) + * [precedence](#precendence) + * [match](#match) + * [match.source](#match-source) + * [match.sourceTags](#match-sourceTags) + * [match.httpHeaders](#match-httpHeaders) + * [match.tcp](#match-tcp) + * [match.udp](#match-udp) + * [route](#route) + * [route.destination](#route-destination) + * [route.tags](#route-tags) + * [route.weight](#route-weight) + * [httpReqTimeout](#httpReqTimeout) + * [httpReqRetries](#httpReqRetries) + * [httpFault](#httpFault) + * [httpFault.delay](#httpFault-delay) + * [httpFault.abort](#httpFault-abort) +* [Route Rule Evaluation](#route-rule-evaluation) +* [Destination Policies](#destination-policies) + * [destination](#pdestination) + * [tags](#tags) + * [loadBalancing](#loadBalancing) + * [circuitBreaker](#circuitBreaker) +* [Destination Policy Evaluation](#destination-policy-evaluation) + +## Overview + +Istio provides a simple Domain-specific language (DSL) based on the proto3 +schema (documented +[here](https://github.com/istio/api/blob/master/proxy/v1/config/cfg.md)) to +control how API calls and layer-4 traffic flows across various +microservices in the application deployment. The DSL allows the operator to +configure service level properties such as circuit breakers, timeouts, +retries, as well as set up common continuous deployment tasks such as +canary rollouts, A/B testing, staged rollouts with %-based traffic splits, +etc.. + +For example, a simple rule to send 100% of incoming traffic for a "reviews" microservice +to version "v1" can be described using the Rules DSL as follows: + +```yaml +destination: reviews.default.svc.cluster.local +route: +- tags: + version: v1 + weight: 100 +``` + +The destination is the name of the service (specified as a fully qualified +domain name (FQDN)) to which the traffic is being routed. In a Kubernetes +deployment of Istio, the route *tag* +"version: v1" corresponds to a Kubernetes *label* "version: v1". The rule +ensures that only Kubernetes pods containing the label "version: v1" +will receive traffic. + +There are two types of rules in Istio, **Route Rules**, +which control request routing, and **Destination Policies**, +which specify policies, for example, circuit breakers, that control requests for a destination service. + +Istio rules can be set and displayed using the [istioctl CLI](istioctl.md). +For example, the above rule can be set using the following command: +```bash +$ cat < + +The following subsections provide a overview of the basic fields of a route rule. +A complete and detailed description of a route rule structure can be found +[here](https://github.com/istio/api/blob/master/proxy/v1/config/cfg.md#route-rules). + +#### Property: destination + +Every rule corresponds to some destination microservice identified by a *destination* field in the +rule. For example, all rules that apply to calls to the "reviews" microservice will include the following field. + +```yaml +destination: reviews.default.svc.cluster.local +``` + +The *destination* value SHOULD be a fully qualified domain name (FQDN). It +is used by the Istio runtime for matching rules to services. For example, +in Kubernetes, a fully qualified domain name for a service can be +constructed using the following format: *serviceName.namespace.dnsSuffix*. + +#### Property: precedence + +The order of evaluation of rules corresponding to a given destination, when there is more than one, can be specified +by setting the *precedence* field of the rule. + +```yaml +destination: reviews.default.svc.cluster.local +precedence: 1 +``` + +The precedence field is an optional integer value, 0 by default. +Rules with higher precedence values are evaluated first. +If there is more than one rule with the same precedence value the order of evaluation is undefined. + +For further details, see [Route Rule Evaluation](#route-rule-evaluation). + +#### Property: match + +Rules can optionally be qualified to only apply to requests that match some specific criteria such +as a specific request source and/or headers. An optional *match* field is used for this purpose. + +The *match* field is an object with the following nested fields: + +* **source** fully qualified domain name (FQDN) +* **sourceTags** optional match qualifications +* **httpHeaders** HTTP header qualifications +* **tcp** +* **udp** + +#### Property: match.source + +The *source* field qualifies a rule to only apply to requests from a specific caller. +For example, +the following *match* clause qualifies the rule to only apply to calls from the "reviews" microservice. + +```yaml +destination: ratings.default.svc.cluster.local +match: + source: reviews.default.svc.cluster.local +``` + +The *source* value, just like *destination*, is an FQDN of a service. + +#### Property: match.sourceTags + +The *sourceTags* field can be used to further qualify a rule to only apply to specific instances of a +calling service. +For example, +the following *match* clause refines the previous example to qualify the rule to only +apply to calls from version "v2" of the "reviews" microservice. + +```yaml +destination: ratings.default.svc.cluster.local +match: + source: reviews.default.svc.cluster.local + sourceTags: + version: v2 +``` + +#### Property: match.httpHeaders + +The *httpHeaders* field is a set of one or more property-value pairs where each property is an HTTP header name +and the corresponding value is one of the following: + +1. `exact: "value"`, where the header value must match *value* exactly +2. `prefix: "value"`, where *value* must be a prefix of the header value +3. `regex: "value"`, where *value* is a regular expression that matches the header value + +For example, the following rule will only apply +to an incoming request if it includes a "Cookie" header that contains the substring "user=jason". + +```yaml +destination: reviews.default.svc.cluster.local +match: + httpHeaders: + Cookie: + regex: "^(.*?;)?(user=jason)(;.*)?$" +``` + +If more than one property-value pair is provided, then all of the corresponding headers +must match for the rule to apply. + +The *source* and *httpHeaders* fields can both be set in the *match* object in which case both criteria must pass. +For example, the following rule only applies if the source of the request is "reviews:v2" +AND the "Cookie" header containing "user=jason" is present. + +```yaml +destination: ratings.default.svc.cluster.local +match: + source: reviews.default.svc.cluster.local + sourceTags: + version: v2 + httpHeaders: + Cookie: + regex: "^(.*?;)?(user=jason)(;.*)?$" +``` + +#### Property: match.tcp + +TBD + +#### Property: match.udp + +TBD + +#### Property: route + +The *route* field identifies a set of one or more weighted backends to call when the rule is activated. +Each *route* backend is an object with the following fields: + +* **tags** +* **weight** +* **destination** + +Of these fields, *tags* is the only required one, the others are optional. + +#### Property: route.tags + +The *tags* field is a list of instance tags to identify the target instances (e.g., version) to route requests to. +If there are multiple registered instances with the specified tag(s), +they will be routed to based on the [load balancing policy](#loadBalancing) configured for the service, +or round-robin by default. + +#### Property: route.weight + +The *weight* field is an optional value between 0 and 100 that represents the percentage of requests to route +to instances associated with the corresponding backend. If not set, the *weight* is assumed to be 100. + +The sum of all route weights in a rule SHOULD equal 100. +For example, the following rule will route 25% of traffic for the "reviews" service to instances with +the "v2" tag and the remaining traffic (i.e., 75%) to "v1". + +```yaml +destination: reviews.default.svc.cluster.local +route: +- tags: + version: v2 + weight: 25 +- tags: + version: v1 + weight: 75 +``` + +#### Property: route.destination + +The *destination* field is optional and specifies the service name of the target instances. +If not specified, it defaults to the value of the rule's *destination* field. + +#### Property: httpReqTimeout + +A timeout for http requests can be specified using the *httpReqTimeout* field. +By default, the timeout is 15 seconds, but this can be overridden as follows: + +```yaml +destination: "ratings.default.svc.cluster.local" +route: +- tags: + version: v1 +httpReqTimeout: + simpleTimeout: + timeoutSeconds: 10 +``` + +#### Property: httpReqRetries + +The *httpReqRetries* field can be used to control the number retries for a given http request. +The maximum number of attempts, or as many as possible within the time period +specified by *httpReqTimeout*, can be set as follows: + +```yaml +destination: "ratings.default.svc.cluster.local" +route: +- tags: + version: v1 +httpReqRetries: + simpleRetry: + attempts: 3 +``` + +#### Property: httpFault + +The *httpFault* field is used to specify one or more faults to inject +while forwarding http requests to the rule's corresponding request destination. +The faults injected depend on the following nested fields: + +* **delay** +* **abort** + +#### Property: httpFault.delay + +The *delay* field is used to delay a request by a specified amount of time. Nested fields +*percent* and one of either *fixedDelaySeconds* or *exponentialDelaySeconds* are used to specify the delay. + +The *fixedDelaySeconds* field is used to indicate the amount of delay in seconds. + +Alternatively, the *exponentialDelaySeconds* field can be used to specify the mean delay +for values derived according to an exponential function. + +An optional *percent* field, a value between 0 and 100, can be used to only delay a certain percentage of requests. +All request are delayed by default. + +The following example will introduce a 5 second delay in 10% of the requests to the "v1" version of the "reviews" microservice. + +```yaml +destination: reviews.default.svc.cluster.local +route: +- tags: + version: v1 +httpFault: + delay: + percent: 10 + fixedDelaySeconds: 5 +``` + +#### Property: httpFault.abort + +An *abort* field is used to prematurely abort a request, usually to simulate a failure. Nested fields +*percent* and one of *httpStatus*, *http2Error*, or *grpcStatus*, are used to specify the abort. + +The optional *percent* field, a value between 0 and 100, is used to only abort a certain percentage of requests. +All requests are aborted by default. + +The *httpStatus* field is used to indicate a value to return from an HTTP request, instead of forwarding the request to the destination. +Its value is an integer HTTP 2xx, 3xx, 4xx, or 5xx status code. + +Similarly, to abort HTTP/2 or gRPC, the value to return +can be specified using the *http2Error* or *grpcStatus*, respectively. + +The following example will return an HTTP 400 error code for 10% of the requests to the "ratings" service "v1". + +```yaml +destination: "ratings.default.svc.cluster.local" +route: +- tags: + version: v1 +httpFault: + abort: + percent: 10 + httpStatus: 400 +``` + +Sometimes delays and abort faults are used together. For example, the following rule will delay +by 5 seconds all requests from the "reviews" service "v2" to the "ratings" service "v1" and +then abort 10 percent of them: + +```yaml +destination: ratings.default.svc.cluster.local +match: + source: reviews.default.svc.cluster.local + sourceTags: + version: v2 +route: +- tags: + version: v1 +httpFault: + delay: + fixedDelaySeconds: 5 + abort: + percent: 10 + httpStatus: 400 +``` + +## Route Rule Evaluation + +Whenever the routing story for a particular microservice is purely weight based, +it can be specified in a single rule, as shown in the [route.weight](#route-weight) example. +When, on the other hand, other crieria (e.g., requests from a specific user) are being used to route traffic, +more than one rule will be needed to specify the routing. +This is where the rule *precedence* field must be set to make sure that the rules are evaluated in the right order. + +A common pattern for generalized route specification is to provide one or more higher priority rules +that use the *match* field (see [match](#match)) to provide specific rules, +and then provide a single weight-based rule with no match criteria at the lowest priority to provide the +weighted distribution of traffic for all other cases. + +The following 2 rules, together, specify that all requests for the "reviews" service +that includes a header named "Foo" with the value "bar" will be sent to the "v2" instances. +All remaining requests will be sent to "v1". + +```yaml +destination: reviews.default.svc.cluster.local +precedence: 2 +match: + httpHeaders: + Foo: + exact: bar +route: +- tags: + version: v2 +--- +destination: reviews.default.svc.cluster.local +precedence: 1 +route: +- tags: + version: v1 + weight: 100 +``` + +Notice that the header-based rule has the higher precedence (2 vs. 1). If it was lower, these rules wouldn't work as expected since the +weight-based rule, with no specific match criteria, would be evaluated first which would then simply route all traffic +to "v1", even requests that include the matching "Foo" header. Once a rule is found that applies to the incoming +request, it will be executed and the rule-evaluation process will terminate. That's why it's very important to +carefully consider the priorities of each rule when there is more than one. + +## Destination Policies + +The following subsections provide a overview of the basic fields of a destination policy. +A complete and detailed description of a destination policy structure can be found +[here](https://github.com/istio/api/blob/master/proxy/v1/config/cfg.md#destination-policies). + +#### Property: destination + +Exactly the same as in a [route rule](#route-rules), +every destination policy includes a *destination* field +which identifies the destination microservice for the rule. +For example, a destination policy for calls to the "reviews" microservice will include the following field. + +```yaml +destination: reviews.default.svc.cluster.local +``` + +#### Property: tags + +An optional field, *tags*, is a list of destination tags that can be used to only apply the policy +to requests that are routed to backends with the specified tags. + +The following policy will only apply to requests targetting the "v1" version of the "reviews" microserivice. + +```yaml +destination: reviews.default.svc.cluster.local +tags: + version: v1 +``` + +#### Property: loadBalancing + +The *loadBalancing* field can be used to specify the load balancing policy for a destination service. +The value can be one of `LEAST_CONN`, `RANDOM`, or `ROUND_ROBIN` (default). + +The following destination policy specifies that RANDOM load balancing be used for balancing across +instances of any version of the "reviews" microservice: + +```yaml +destination: reviews.default.svc.cluster.local +loadBalancing: RANDOM +``` + +#### Property: circuitBreaker + +The *circuitBreaker* field can be used to set a circuit breaker for a particular microservice. +A simple circuit breaker can be set based on a number of criteria such as connection and request limits. + +For example, the following destination policy +sets a limit of 100 connections to "reviews" service version "v1" backends. + +```yaml +destination: reviews.default.svc.cluster.local +tags: + version: v1 +circuitBreaker: + simpleCb: + maxConnections: 100 +``` + +The complete set of simple circuit breaker fields can be found +[here](https://github.com/rshriram/api/blob/master/proxy/v1/config/cfg.md#circuitbreakersimplecircuitbreakerpolicy). + +## Destination Policy Evaluation + +Similar to route rules, destination policies are associated with a particular *destination* however +if they also include *tags* their activation depends on route rule evaluation results. + +The first step in the rule evaluation process evaluates the route rules for a *destination*, +if any are defined, to determine the tags (i.e., specific version) of the destination service +that the current request will be routed to. Next, the set of destination policies, if any, are evaluated +to determine if they apply. + +One subtlety of the algorithm to keep in mind is that policies that are defined for specific +tagged destinations will only be applied if the corresponding tagged instances are explicity +routed to. For example, consider the following rule, as the one and only rule defined for +the "reviews" microservice. + +```yaml +destination: reviews.default.svc.cluster.local +tags: + version: v1 +circuitBreaker: + simpleCb: + maxConnections: 100 +``` + +Since there is no specific route rule defined for the "reviews" microservice, default +round-robin routing behavior will apply, which will persumably call "v1" instances on occasion, +maybe even always if "v1" is the only running version. Nevertheless, the above policy will never +be invoked since the default routing is done at a lower level. The rule evaluation engine will be +unaware of the final destination and therefore unable to match the destination policy to the request. + +You can fix the above example in one of two ways. You can either remove the `tags:` +from the rule, if "v1" is the only instance anyway, or, better yet, define proper route rules +for the service. For example, you can add a simple route rule for "reviews:v1". + +```yaml +destination: reviews.default.svc.cluster.local +route: +- tags: + version: v1 +``` + +Although the default Istio behavior conveniently sends traffic from all versions of a source service +to all versions of a destination service without any rules being set, +as soon as version discrimination is desired rules are going to be needed. + +Therefore, setting a default rule for every microservice, right from the start, +is generally considered a best practice in Istio. diff --git a/img/adapters.png b/img/adapters.png new file mode 100644 index 0000000000..f646d27f0c Binary files /dev/null and b/img/adapters.png differ diff --git a/img/adapters.svg b/img/adapters.svg new file mode 100644 index 0000000000..b349f4b0d5 --- /dev/null +++ b/img/adapters.svg @@ -0,0 +1,4 @@ + + + + diff --git a/img/arch.png b/img/arch.png new file mode 100644 index 0000000000..7a2fbc87fc Binary files /dev/null and b/img/arch.png differ diff --git a/img/arch.svg b/img/arch.svg new file mode 100644 index 0000000000..b24492fe40 --- /dev/null +++ b/img/arch.svg @@ -0,0 +1,4 @@ + + + + diff --git a/img/control-data-flow.png b/img/control-data-flow.png new file mode 100644 index 0000000000..4ebadd4860 Binary files /dev/null and b/img/control-data-flow.png differ diff --git a/img/control-data-flow.svg b/img/control-data-flow.svg new file mode 100644 index 0000000000..a2a8a9a855 --- /dev/null +++ b/img/control-data-flow.svg @@ -0,0 +1,4 @@ + + + +