docs: update architecture diagrams + descriptions (#1218)

* docs: update architecture diagrams + descriptions

* Update docs/docs/topics/production-deployment.md

Co-authored-by: bobby <1544881+desimone@users.noreply.github.com>

* Update docs/docs/topics/production-deployment.md

Co-authored-by: bobby <1544881+desimone@users.noreply.github.com>

* Update docs/docs/topics/production-deployment.md

Co-authored-by: bobby <1544881+desimone@users.noreply.github.com>

docs/docs/readme.md

@@ -18,35 +18,51 @@ Pomerium can be used to:
 - provide a **single-sign-on gateway** to internal applications.
 - enforce **dynamic access policy** based on **context**, **identity**, and **device state**.
 - aggregate access logs and telemetry data.
-- a **VPN alternative**.
+- perform delegated user authorization for service-based authorization systems:
+  - [Istio](/guides/istio.html)
+  - [Google Cloud](/guides/cloud-run.html)
+- provide unified identity attestation for upstream services:
+  - [Kubernetes](/guides/kubernetes.html)
+  - [Grafana](/guides/istio.html#pomerium-configuration)
+  - [Custom applications](/docs/topics/getting-users-identity.html)
+- provide a **VPN alternative**.
 
 ## Architecture
 
 ### System Level
 
-Pomerium sits between end users and services which require strong authentication. After verifying identity with your identity provider (IdP), Pomerium uses a configurable policy to decide how to route your user's request and if they are authorized to the service.
+Pomerium sits between end users and services requiring strong authentication. After verifying identity with your identity provider (IdP), Pomerium uses a configurable policy to decide how to route your user's request and if they are authorized to access the service.
 
 <img alt="pomerium architecture diagram" src="/pomerium-system-context.svg" width="65%">
 
 ### Component Level
 
-Pomerium is composed of 3 logical components:
+Pomerium is composed of 4 logical components:
 
 - Proxy Service
   - All user traffic flows through the proxy
-  - Initiates authentication flow to Authentication service as needed
   - Verifies all requests with Authentication service
+  - Directs users to Authentication service to establish session identity
   - Processes policy to determine external/internal route mappings
 - Authentication Service
   - Handles authentication flow to your IdP as needed
   - Handles identity verification after initial Authentication
+  - Establishes user session cookie
+  - Stores user OIDC tokens in cache service
 - Authorization Service
   - Processes policy to determine permissions for each service
   - Handles authorization check for all user sessions
+  - Directs Proxy service to initiate Authentication flow as required
+  - Provides additional security releated headers for upstream services to consume
+- Cache Service
+  - Retrieves identity provider related data such as group membership
+  - Stores and refreshes identity provider access and refresh tokens
+  - Provides streaming authoritative session and identity data to Authorize service
+  - Stores session and identity data in persistent storage
 
 In production deployments, it is recommended that you deploy each component separately. This allows you to limit external attack surface, as well as scale and manage the services independently.
 
-In test deployments, all three components may run from a single binary and configuration.
+In test deployments, all four components may run from a single binary and configuration.
 
 <img alt="pomerium architecture diagram" src="/pomerium-container-context.svg" width="65%">
 
@@ -54,7 +70,7 @@ In test deployments, all three components may run from a single binary and confi
 
 Pomerium's internal and external component interactions during full authentication from a fresh user are diagramed below.
 
-After initial authentication to provide a session token, only the authorization interactions occur.
+After initial authentication to provide a session token, only the authorization check interactions occur.
 
 <a href="/pomerium-auth-flow.svg">
 <img alt="pomerium architecture diagram" src="/pomerium-auth-flow.svg">

docs/docs/topics/production-deployment.md

@@ -22,18 +22,13 @@ In smaller deployments or while testing, it may be desirable to run in "all-in-o
 
 In larger footprints, it is recommended to run Pomerium as a collection of discrete service clusters. This limits blast radius in the event of vulnerabilities and allows for per-service [scaling](#scaling) and monitoring.
 
-In more complicated deployments, you may also choose to share aspects of the control plane across multiple logical Proxy clusters. Examples:
-
-1. You want central AuthN and AuthZ but need to support a number of independently configured Proxy clusters
-2. You want central AuthZ but different Proxy clusters need different IDPs
-
-In both configurations, you must ensure the [Shared Secret](../../reference/readme.md#shared-secret) matches across services. You must also ensure Proxy and Authenticate external names sit within the same domain.
-
 ## Scaling
 
 In dedicated service mode, you have the opportunity to scale the components of Pomerium independently.
 
-Pomerium's components are stateless, and may all be scaled horizontally or vertically. In general, horizontal scaling is recommended.
+All of Pomerium's components are designed to be stateless, and may all be scaled horizontally or vertically. In general, horizontal scaling is recommended.  Vertical scaling will lead to diminished returns after ~8 vCPUs.
+
+The Cache service, which is responsible for session and identity related data, must be [configured for external persistence](/docs/topics/data-storage.html) to be fully stateless.
 
 ### Proxy
 
@@ -45,13 +40,23 @@ Proxy will need resources scaled in conjunction with request count and may need
 
 The Authorize service is responsible for policy checks during requests. It is in the hot path for user requests but does not directly handle user traffic.
 
-Authorize will need resources scaled in conjunction with request count. Request size and type should be of a constant complexity.
+Authorize will need resources scaled in conjunction with request count. Request size and type should be of a constant complexity.  In most environments, Authorize and Proxy will scale linearly with request volume.
 
 ### Authenticate
 
-The Authenticate service handles session token renewal, creation, and interaction with your Identity Provider. The Authenticate service between a successful session setup or renewal and session expiration.
+The Authenticate service handles session cookie setup, session storage, and authentication with your Identity Provider. 
 
-Authenticate requires significantly fewer resources than other components due to the only-occasional requirement to establish/renew sessions. Add resources to the Authenticate service if you have a high session churn rate. The requests should be constant time and complexity, but may vary by Identity Provider implementation.
+Authenticate requires significantly fewer resources than other components due to the only-occasional requirement to establish new sessions.  Add resources to the Authenticate service if you have a high session/user churn rate. The requests should be constant time and complexity, but may vary by Identity Provider implementation.
+
+### Cache
+
+The Cache service is responsible for background identity data retrieval and storage.  It is in the hot path for user authentication.  However, it does not directly handle user traffic and is not in-path for authorization decisions.
+
+The Cache service does not require significant resources, as it provides streaming updates of state changes to the Authorize service.  There will be utilization spikes when Authorize services are restarted and perform an initial synchronization.  Add resources if running many Authorize services and performing restarts in large batches.  In many deployments, 2 replicas of Cache is enough to provide resilient service.
+
+::: warning
+In a production configuration, Cache CPU/IO utilization also translates to IO load on the [underlying storage system](/docs/topics/data-storage.html).  Ensure it is scaled accordingly!
+:::
 
 ## Load Balancing
 
@@ -69,11 +74,11 @@ You should provide a TCP or HTTP(s) load balancer between end users and the Auth
 
 Authenticate is compatible with any L4 or L7/HTTP load balancer. Session stickiness should not be required and it is typical to have Authenticate be a named vhost on the same L7 load balancer as the Proxy service.
 
-### Authorize
+### Authorize and Cache
 
-You do **not** need to provide a load balancer between the Proxy and the Authorize services. Authorize utilizes GRPC and thus has special requirements if you should chose to use an external load balancer. GRPC can perform client based load balancing, and in most configurations is the best architecture.
+You do **not** need to provide a load balancer in front of Authorize and Cache services. Both utilize GRPC, and thus has special requirements if you should choose to use an external load balancer. GRPC can perform client based load balancing, and in most configurations is the best architecture.
 
-By default, the Proxy will automatically connect to all IPs returned by a DNS query for the name of the Authorize service. Proxy will then regularly re-query DNS for changes to the Authorize service cluster. Health checks and failover are automatic.
+By default, Pomerium gRPC clients will automatically connect to all IPs returned by a DNS query for the name of an upstream service. They will then regularly re-query DNS for changes to the Authorize or Cache service cluster. Health checks and failover are automatic.
 
 **Many load balancers do not support HTTP2 yet. Please verify with your hardware, software or cloud provider**
 
@@ -93,6 +98,10 @@ Regardless of the service mode, it is recommended you run 2+ instances of Pomeri
 
 Ensure that you have enough spare capacity to handle the scope of your failure domains.
 
+::: warning
+Multiple replicas of Cache or all-in-one service are only supported with [external storage](/docs/topics/data-storage.html) configured
+::: 
+
 ## SSL/TLS Certificates
 
 Pomerium utilizes TLS end to end, so the placement, certificate authorities and covered subjects are critical to align correctly.