From 4581bdc94711e0caff292548c156dd9a062ec0ab Mon Sep 17 00:00:00 2001 From: chronark Date: Mon, 27 Jan 2025 08:14:52 +0100 Subject: [PATCH 1/5] docs: create rfc 008 Dataplane --- .../content/rfcs/0008-dataplane.mdx | 111 ++++++++++++++++++ 1 file changed, 111 insertions(+) create mode 100644 apps/engineering/content/rfcs/0008-dataplane.mdx diff --git a/apps/engineering/content/rfcs/0008-dataplane.mdx b/apps/engineering/content/rfcs/0008-dataplane.mdx new file mode 100644 index 000000000..54018f748 --- /dev/null +++ b/apps/engineering/content/rfcs/0008-dataplane.mdx @@ -0,0 +1,111 @@ +--- +title: 0008 Dataplane +description: Global Unkey Deployment Architecture +date: 2025-01-26 +authors: + - Andreas Thomas +--- + + +We need to design a globally distributed architecture for Unkey where the dataplane can operate independently from the primary database for improved availability. The main challenge is ensuring gateway nodes have access to dynamic data (gateway configs, API keys, etc.) while maintaining global eventual consistency and performance. + +## Goals + +- Achieve 100% dataplane availability independent of primary database +- Provide fast access to dynamic data across global regions +- Propagate data across the system quickly +- Minimize load on expensive storage +- Enable efficient cache invalidation +- Can run on any cloud or on premise + +## Options + +### 1. Direct S3 + In-Memory Cache with SWR + +```ascii +┌─────────────────────┐ ┌─────────┐ +│ Gateway │ │ │ +│ ┌───────────────┐ │────►│ S3 │ +│ │ Memory Cache │ │ │ │ +│ └───────────────┘ │ │ │ +└─────────────────────┘ └─────────┘ +``` + +#### Pros +- Simple, straightforward design +- Low architectural complexity + +#### Cons +- Cache invalidation requires communication with all machines or really low TTLs (\<10s) +- Inefficient cache refresh patterns +- High load on S3 due to concurrent SWR requests from multiple machines + +### 2. S3 + In-Memory Cache with Gossip Protocol + +```ascii +┌─────────────────────┐ +│ Gateway │ +│ ┌───────────────┐ │──┐ +│ │ Memory Cache │ │ │ +│ └───────────────┘ │ │ +└─────────────────────┘ │ + ▲ │ + │ Gossip │ ┌─────────┐ + ▼ ├───►│ │ +┌─────────────────────┐ │ │ S3 │ +│ Gateway │ │ │ │ +│ ┌───────────────┐ │──┘ └─────────┘ +│ │ Memory Cache │ │ +│ └───────────────┘ │ +└─────────────────────┘ +``` + +If we had global fast and efficient eviction, we could set much higher TTLs. + +#### Pros +- Efficient cache invalidation through gossip allowing higher TTLs. +- Reduced load on primary storage +- Only need to notify one node for changes + +#### Cons +- Need to implement ordering mechanism (timestamps/Lamport clocks) +- More complex system architecture +- Global gossip cluster management overhead + +### 3. S3 + Dedicated Cache Layer + +```ascii +┌─────────────────┐ +│ Gateway 1 │───┐ +└─────────────────┘ │ + │ +┌─────────────────┐ │ ┌────────────┐ +│ Gateway 2 │───┼───►│ Load │ ┌────────────┐ +└─────────────────┘ │ │ Balancer │───►│ Cache │──┐ + │ │ │ │ Node 1 │ │ +┌─────────────────┐ │ │ │ └────────────┘ │ +│ Gateway 3 │───┤ │ │ │ ┌─────────┐ +└─────────────────┘ │ │ │ ├───►│ S3 │ + ├───►│ │ ┌────────────┐ │ └─────────┘ +┌─────────────────┐ │ │ │───►│ Cache │──┘ +│ Gateway 4 │───┤ │ │ │ Node 2 │ +└─────────────────┘ │ └────────────┘ └────────────┘ + │ +┌─────────────────┐ │ +│ Gateway n │───┘ +└─────────────────┘ +``` + +Gateways still use an in-memory SWR cache. The cache nodes help reduce the cost +and latency of S3, but will likely have the same freshness/staleness as the +gateways. TBD.. + +Everything here, except the s3 bucket, would be duplicated per region. + +#### Pros +- Better cache retention due to less frequent reboots +- Optional global eviction via gossip/kafka later +- Maybe we only need 1 S3 region now instead of replicating it + +#### Cons +- Additional infrastructure to manage From f162826377600b0ff9fd114ab941f606c87d463e Mon Sep 17 00:00:00 2001 From: "autofix-ci[bot]" <114827586+autofix-ci[bot]@users.noreply.github.com> Date: Mon, 27 Jan 2025 07:19:29 +0000 Subject: [PATCH 2/5] [autofix.ci] apply automated fixes --- apps/dashboard/lib/trpc/routers/key/delete.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/apps/dashboard/lib/trpc/routers/key/delete.ts b/apps/dashboard/lib/trpc/routers/key/delete.ts index c36360fad..33e38ac13 100644 --- a/apps/dashboard/lib/trpc/routers/key/delete.ts +++ b/apps/dashboard/lib/trpc/routers/key/delete.ts @@ -76,7 +76,7 @@ export const deleteKeys = t.procedure ); }) .catch((err) => { - console.error(err) + console.error(err); throw new TRPCError({ code: "INTERNAL_SERVER_ERROR", message: "We are unable to delete the key. Please try again or contact support@unkey.dev", From a6d4b816c9feadb706c37e467a4a3deb4c26494a Mon Sep 17 00:00:00 2001 From: chronark Date: Mon, 27 Jan 2025 08:25:13 +0100 Subject: [PATCH 3/5] chore: spelling --- apps/engineering/content/rfcs/0008-dataplane.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/apps/engineering/content/rfcs/0008-dataplane.mdx b/apps/engineering/content/rfcs/0008-dataplane.mdx index 54018f748..c62d060ff 100644 --- a/apps/engineering/content/rfcs/0008-dataplane.mdx +++ b/apps/engineering/content/rfcs/0008-dataplane.mdx @@ -7,7 +7,7 @@ authors: --- -We need to design a globally distributed architecture for Unkey where the dataplane can operate independently from the primary database for improved availability. The main challenge is ensuring gateway nodes have access to dynamic data (gateway configs, API keys, etc.) while maintaining global eventual consistency and performance. +We need to design a globally distributed architecture for Unkey where the dataplane can operate independently of the primary database for improved availability. ## Goals @@ -63,7 +63,7 @@ We need to design a globally distributed architecture for Unkey where the datapl If we had global fast and efficient eviction, we could set much higher TTLs. #### Pros -- Efficient cache invalidation through gossip allowing higher TTLs. +- Efficient cache invalidation through gossip, allowing higher TTLs - Reduced load on primary storage - Only need to notify one node for changes @@ -100,7 +100,7 @@ Gateways still use an in-memory SWR cache. The cache nodes help reduce the cost and latency of S3, but will likely have the same freshness/staleness as the gateways. TBD.. -Everything here, except the s3 bucket, would be duplicated per region. +Everything here, except the S3 bucket, would be duplicated per region. #### Pros - Better cache retention due to less frequent reboots From 33641ae53ed1dbee0fe2a613962c454f3ac38c9e Mon Sep 17 00:00:00 2001 From: chronark Date: Fri, 31 Jan 2025 09:14:17 +0100 Subject: [PATCH 4/5] docs: add dynamodb --- .../content/rfcs/0008-dataplane.mdx | 65 +++++++++++++++++++ 1 file changed, 65 insertions(+) diff --git a/apps/engineering/content/rfcs/0008-dataplane.mdx b/apps/engineering/content/rfcs/0008-dataplane.mdx index c62d060ff..cac95dda1 100644 --- a/apps/engineering/content/rfcs/0008-dataplane.mdx +++ b/apps/engineering/content/rfcs/0008-dataplane.mdx @@ -109,3 +109,68 @@ Everything here, except the S3 bucket, would be duplicated per region. #### Cons - Additional infrastructure to manage + +### 4. DynamoDB Global Tables + Caching + + +Option 4A: Direct DynamoDB + Gateway Memory Cache +- Each gateway maintains a local memory SWR cache with a TTL of 10s +- DynamoDB serves as source of truth +- Automatic multi-region replication handled by AWS + +```ascii +┌─────────────────────┐ ┌──────────────────┐ +│ Gateway (US) │ │ DynamoDB │ +│ ┌───────────────┐ │────►│ (US-WEST-1) │ +│ │ Memory Cache │ │ │ │ +│ └───────────────┘ │ └──────────────────┘ +└─────────────────────┘ ▲ + │ + │ Replication + │ +┌─────────────────────┐ ▼ +│ Gateway (EU) │ ┌──────────────────┐ +│ ┌───────────────┐ │────►│ DynamoDB │ +│ │ Memory Cache │ │ │ (EU-WEST-1) │ +│ └───────────────┘ │ │ │ +└─────────────────────┘ └──────────────────┘ +``` + + +Option 4B: With Dedicated Cache Layer + +A dedicated cache layer could be added to reduce the load on DynamoDB and improve read performance as well as cost. +Whether this actually saves money is debatable, we'll have to try. +These cache nodes would be dumb, they only cache reads for 10s and don't have any manual eviction possibilities. + +```ascii +┌─────────────────┐ +│ Gateway 1 │───┐ +└─────────────────┘ │ + │ ┌────────────┐ +┌─────────────────┐ │ │ Load │ ┌────────────┐ +│ Gateway 2 │───┼───►│ Balancer │───►│ Cache │──┐ +└─────────────────┘ │ │ │ │ Node 1 │ │ ┌──────────────┐ + │ │ │ └────────────┘ ├───►│ DynamoDB │ + │ │ │ │ │ Global │ + │ │ │ ┌────────────┐ │ │ Tables │ +┌─────────────────┐ │ │ │───►│ Cache │──┘ └──────────────┘ +│ Gateway n │───┘ └────────────┘ │ Node 2 │ +└─────────────────┘ └────────────┘ +``` + +#### Pros +- Built-in multi-region replication with strong consistency +- No need to manage complex replication logic +- Lower latency reads from local region +- Automatic conflict resolution +- Serverless and fully managed by AWS +- Cheaper per read operation than S3 +- 99.999% availability (s3 only has 99.99%) + + +#### Cons +- Vendor lock-in to AWS -> we need to have an abstraction +- Higher storage cost compared to S3 due to replication +- Cost of replication +- Replication lag is controlled by AWS, not us From b8fc2e84d7c6ea25ed942bc148f09be3f533d57b Mon Sep 17 00:00:00 2001 From: chronark Date: Fri, 31 Jan 2025 09:59:31 +0100 Subject: [PATCH 5/5] docs: pricing --- apps/engineering/content/rfcs/0008-dataplane.mdx | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/apps/engineering/content/rfcs/0008-dataplane.mdx b/apps/engineering/content/rfcs/0008-dataplane.mdx index cac95dda1..761ad939a 100644 --- a/apps/engineering/content/rfcs/0008-dataplane.mdx +++ b/apps/engineering/content/rfcs/0008-dataplane.mdx @@ -165,7 +165,7 @@ These cache nodes would be dumb, they only cache reads for 10s and don't have an - Lower latency reads from local region - Automatic conflict resolution - Serverless and fully managed by AWS -- Cheaper per read operation than S3 +- Cheaper for small reads than S3 - 99.999% availability (s3 only has 99.99%) @@ -174,3 +174,4 @@ These cache nodes would be dumb, they only cache reads for 10s and don't have an - Higher storage cost compared to S3 due to replication - Cost of replication - Replication lag is controlled by AWS, not us +- More expensive for large \>13kb reads than S3