overview docs

_includes/doc-side-guides-nav.html

@@ -2,8 +2,7 @@
 	{% assign current = page.url | downcase | split: '/' %}
 	<li><h5 class="doc-side-nav-title">Guides</h5></li>
 	<li class="doc-side-nav-list-item"><a href="{{ site.baseurl }}/docs/guides/index.html" {% if current[3] == 'index.html' %}class='current'{% endif %}>What is Istio?</a></li>
-	<li class="doc-side-nav-list-item"><a href="{{ site.baseurl }}/docs/guides/concepts.html" {% if current[3] == 'concepts.html' %}class='current'{% endif %}>Istio Concepts</a></li>
-	<li class="doc-side-nav-list-item"><a href="{{ site.baseurl }}/docs/guides/proxy.html" {% if current[3] == 'proxy.html' %}class='current'{% endif %}>Istio Proxy</a></li>
-	<li class="doc-side-nav-list-item"><a href="{{ site.baseurl }}/docs/guides/manager.html" {% if current[3] == 'manager.html' %}class='current'{% endif %}>Istio Configuration Manager</a></li>
-	<li class="doc-side-nav-list-item"><a href="{{ site.baseurl }}/docs/guides/mixer.html" {% if current[3] == 'mixer.html' %}class='current'{% endif %}>Istio Mixer</a></li>
+	<li class="doc-side-nav-list-item"><a href="{{ site.baseurl }}/docs/guides/concepts.html" {% if current[3] == 'architecture.html' %}class='current'{% endif %}>Architecture</a></li>
+	<li class="doc-side-nav-list-item"><a href="{{ site.baseurl }}/docs/guides/model.html" {% if current[3] == 'model.html' %}class='current'{% endif %}>Service Model</a></li>
+	<li class="doc-side-nav-list-item"><a href="{{ site.baseurl }}/docs/guides/mixer.html" {% if current[3] == 'mixer.html' %}class='current'{% endif %}>Mixer</a></li>
  </ul>

docs/guides/architecture.md

@@ -0,0 +1,42 @@
+---
+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](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](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.
+
+<img src="/img/arch.svg" alt="The overall architecture of an Istio-based service.">
+
+<div id="toc" class="toc mobile-toc"></div>

docs/guides/concepts.md

@@ -0,0 +1,42 @@
+---
+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](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](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.
+
+<img src="/img/arch.svg" alt="The overall architecture of an Istio-based service.">
+
+<div id="toc" class="toc mobile-toc"></div>

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.
 
 <div id="toc" class="toc mobile-toc"></div>

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.
+
+<img src="/img/adapters.svg" alt="Mixer and its adapters.">
+
+<div id="toc" class="toc mobile-toc"></div>

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](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.).
+
+<div id="toc" class="toc mobile-toc"></div>