Merge pull request #8 from dnks0/feature/dbx-proxy

* added architecture diagrams
* updated documentation

Author: dnks0

README.md

@@ -6,12 +6,22 @@
 
 Many enterprise resources live in private networks and are not reachable from serverless compute by default. `dbx-proxy` provides a controlled entry point for [private connectivity to resources in your VPC/Vnet](https://docs.databricks.com/aws/en/security/network/serverless-network-security/pl-to-internal-network).
 
+![](resources/img/overview.png)
+
+Connectivity to your custom resources can be configured via a dedicated Private Endpoint that is connected to a Network Load Balancer (AWS) in your network. From there on you can route traffic accordingly to targets. However, this approach comes with certain limiations for routing of network traffic due to limitations of cloud-provider offerings, e.g. a NLB on AWS does only operate on Layer 4 of the TCP/IP stack, allowing traffic to be routed only by IP/Port. `dbx-proxy` solves this problem by introducing an additional component which receives all traffic from your NLB and takes over the routing logic for individual targets based on your configuration. It is able to operate on Layer 4 & 7 providing greater flexibility for reaching your targets from Databricks Serverless compute.
+
+
 ### What you get
 
 - **Forwarding of L4 & L7 network traffic** based on your configuration
   - L4 (TCP): forwarding of plain TCP traffic, e.g. for databases
   - L7 (HTTP) forwarding of HTTP(s) traffic with **SNI-based routing**, e.g. for applications/APIS
 - **Terraform module** ready to use (currently **AWS only**)
+- No TLS termination, only passthrough!
+
+### High availability (overview)
+
+`dbx-proxy` is placed behind an AWS Network Load Balancer, which spreads connections across the instances in the Auto Scaling Group. Availability depends on how many instances you run and whether your subnets span multiple AZs. See the Terraform module details for configuration and behavior: [High availability (AWS)](terraform/README.md#high-availability-aws).
 
 ### Deployment (Terraform) / How to use
 

resources/img/aws-architecture.png

@@ -27,11 +27,7 @@ This repository provides a **Terraform module** for deploying `dbx-proxy` across
   - Optional IGW + public subnet + NAT gateway (internet connectivity needed to pull images, etc.!)
   - Route tables + associations
 
----
-
-### Architecture diagram (AWS)
-
-(to be added)
+![](../resources/img/aws-architecture.png)
 
 ---
 
@@ -77,7 +73,7 @@ These variables define what the proxy should do (listeners, health port, image t
 
 | Variable | Type | Default | Description |
 |---|---:|---:|---|
-| `dbx_proxy_image_version` | `string` | `"0.2.0"` | Docker image tag/version of `dbx-proxy` to deploy. |
+| `dbx_proxy_image_version` | `string` | `"0.1.1"` | Docker image tag/version of `dbx-proxy` to deploy. |
 | `dbx_proxy_health_port` | `number` | `8080` | Health port exposed by `dbx-proxy` (HTTP `GET /status`). Also used for NLB target group health checks. |
 | `dbx_proxy_max_connections` | `number` | `null` | Optional HAProxy `maxconn` override. If unset, the AWS module derives a value from vCPU and memory of the selected instance-type. |
 | `dbx_proxy_listener` | `list(object)` | `[]` | Listener configuration (ports/modes/routes/destinations). See **Listener configuration** below. |
@@ -141,6 +137,27 @@ These variables define what the proxy should do (listeners, health port, image t
 
 ---
 
+### High availability (AWS)
+
+High availability is driven by the **Auto Scaling Group (ASG)** size and the **subnets/AZs** you provide.
+The module **does not pin instances to a single AZ**; AWS spreads instances across the subnets you pass in `subnet_ids`.
+
+Key behaviors:
+- **Multi-instance support**: set `min_capacity` / `max_capacity` to >1 to allow more than one proxy instance.
+- **AZ distribution**: the ASG uses the subnets in `subnet_ids`. If those subnets span multiple AZs, instances are spread across them.
+- **Single-AZ risk**: if `subnet_ids` are all in one AZ, all instances will stay in that AZ.
+- **Bootstrap mode**: when bootstrapping networking, the module creates two private subnets from `subnet_cidrs`; ensure these map to different AZs in your region.
+
+Deployment variables that affect HA:
+- `min_capacity`, `max_capacity` (ASG size)
+- `subnet_ids` (which AZs are eligible)
+- `subnet_cidrs` (in `bootstrap` mode, controls how many subnets are created)
+- `enable_nat_gateway` (bootstrap only; affects outbound access, not AZ spread)
+
+If you need strict multi-AZ placement guarantees, provide **at least one subnet per AZ** you want to cover and run **>= 2 instances**.
+
+---
+
 ### Listener configuration (deep dive)
 
 `dbx_proxy_listener` is a list of listener objects: