From 947932e722a31b473483c9034eeab2925b87c1e5 Mon Sep 17 00:00:00 2001 From: George MacRorie Date: Fri, 10 May 2024 16:21:28 +0100 Subject: [PATCH 1/8] feat(cloud/architecture): add initial outline around cloud archiecture --- cloud/architecture/overview.mdx | 56 ++++++ .../architecture-overview-dark.svg | 190 ++++++++++++++++++ .../architecture-overview-light.svg | 118 +++++++++++ .../architecture/architecture-overview.d2 | 82 ++++++++ 4 files changed, 446 insertions(+) create mode 100644 images/cloud/architecture/architecture-overview-dark.svg create mode 100644 images/cloud/architecture/architecture-overview-light.svg create mode 100644 images/cloud/architecture/architecture-overview.d2 diff --git a/cloud/architecture/overview.mdx b/cloud/architecture/overview.mdx index 355aabc..6be1dd1 100644 --- a/cloud/architecture/overview.mdx +++ b/cloud/architecture/overview.mdx @@ -2,3 +2,59 @@ title: Technical Details description: Learn the technical details of how Flipt Hybrid Cloud works --- + +This page details how Flipt Cloud is architected to provide a simple and scalable solution for accessing and securing your internal, self-hosted deployments of Flipt. + +Much like other great self-hosted, open-source developer tools with built-in user interfaces, Flipt itself comes baked with lots of critical features for scale and security. + +- Horizontal scalability +- HTTPS/TLS support +- Configurable authentication mechanisms (Static Token, OIDC, GitHub, JWT and Kubernetes) +- API and UI with session management and termination + +These capabilites are super important for being able to deploy Flipt onto your own infrastructure and make it secure for your users. +However, enabling and integrating these features is not free of its own complexities, infrastructure and time investment. +In order to take advantage of these, you're likely going to have to perform one or many of the following: + +- Enable networking and routing to your Flipt instance +- Issue and assign an (internal or external) DNS name for your Flipt +- Add a load-balancer to distribute load across your instances of Flipt +- Issue TLS certificates and manage their rotation over time +- Manually configure OAuth client credentials for your SSO provider for OIDC authentication +- Deploy and manage a database for Flipt to store session credentials in + +![Common Deployed Components Diagram]() + +Flipt Cloud replaces all these steps with a few clicks and some API credentials. + +## Flipt the problem on its head + +Flipt Cloud reverses the ingress problem so that your deployments of Flipt dial out to us instead. +This approaches is commonly referred to as _reverse tunnelling_. +Tunnelling in this way has some advantages for applications, as they can be deployed in environments without a stable IP address (e.g. behind restrictive NATs). +For Flipt, this means you can safely expose Flipt from inside a major cloud provider, a modern hyperscaler or simply from your own laptop on your home network. + + + + +When you register your instance in this way with Flipt Cloud, we issue you with a stable subdomain under flipt.cloud (e.g. production-megacorp.flipt.cloud). +Using this DNS name, requests for your instances will flow though our API gateways, load-balancers and then only reach your instances once fully authenticated. +This entire process is performed over secure TLS connections from your end users back to your instances. +All of which is done without you having to provide TLS certificates, and without having to manage rotation. + +## Tunnel Registration + +Your connections are made using an API key credential obtained from our Flipt Cloud UI, or via the `flipt cloud login` subcommand of the Flipt CLI. +This credential is used in an initial handshake to identify your Flipt Cloud organization and the logical instance your Flipt is joining. + +![Tunnel Registration Handshake]() + +Once registered and associated with Flipt Cloud, your Flipt instance is added to our remote load balancer pool for your logical instance. +Now when you visit your new Flipt Cloud instance subdomain, your requests are routed to the instance(s) deployed on your infrastructure. + +The majority of the tunneling functionality we perform is now open-source in our project [Reverst](https://github.com/flipt-io/reverst). +Reverst is unique in that it leverages HTTP/3 and the QUIC protocol to establish secure, reliable and performant connections for tunnels. +Keep your eyes peeled for our upcoming blog on how and why we choose to build our reverse tunnels in this way. + +We deploy and scale multiple instances of Reverst on our infrastructure for establishing and managing these tunnels for you. +All while tightly integrating them with the Flipt Cloud user interface, authentication and instance management system. diff --git a/images/cloud/architecture/architecture-overview-dark.svg b/images/cloud/architecture/architecture-overview-dark.svg new file mode 100644 index 0000000..e1573d6 --- /dev/null +++ b/images/cloud/architecture/architecture-overview-dark.svg @@ -0,0 +1,190 @@ +internetYour InfrastructureQUICGatewayFlipt CloudReverst flipt.cloudinstance-org.flipt.cloudflipt.cloudinstance-org.flipt.cloud + + + + + + + + + + + + diff --git a/images/cloud/architecture/architecture-overview-light.svg b/images/cloud/architecture/architecture-overview-light.svg new file mode 100644 index 0000000..40b1973 --- /dev/null +++ b/images/cloud/architecture/architecture-overview-light.svg @@ -0,0 +1,118 @@ +internetYour InfrastructureQUICGatewayFlipt CloudReverst flipt.cloudinstance-org.flipt.cloudflipt.cloudinstance-org.flipt.cloud + + + + + + + + + + + + diff --git a/images/cloud/architecture/architecture-overview.d2 b/images/cloud/architecture/architecture-overview.d2 new file mode 100644 index 0000000..f232e70 --- /dev/null +++ b/images/cloud/architecture/architecture-overview.d2 @@ -0,0 +1,82 @@ +vars: { + d2-config: { + layout-engine: elk + } +} + +style: { + fill: transparent +} + +direction: right + +internet: { + shape: image + icon: https://icons.terrastruct.com/essentials%2F140-internet.svg +} + +internet -> cloud.gateway: flipt.cloud { + style.font-size: 32 +} +internet -> cloud.gateway: instance-org.flipt.cloud { + style.font-size: 32 +} + +cloud: "" { + style: { + fill: transparent + } + + gateway: Gateway { + shape: image + icon: https://icons.terrastruct.com/infra%2F033-protection.svg + style.font-size: 32 + } + + cloudInstance: Flipt Cloud { + shape: image + icon: https://flipt.cloud/icon.svg?3c7bba14eb804cba + style.font-size: 32 + } + gateway -> cloudInstance: flipt.cloud { + style.font-size: 32 + } + + reverst: Reverst { + shape: image + icon: https://icons.terrastruct.com/infra%2F012-data.svg + style.font-size: 32 + } + gateway -> reverst: instance-org.flipt.cloud { + style.font-size: 32 + } +} + +yours: Your Infrastructure { + style.fill: transparent + fapi: "" { + icon: https://assets-global.website-files.com/659480aa07716c37f0fd8dee/6597f2baa456ff33c9f13a07_logo%201.svg + } + + ftwo: "" { + icon: https://assets-global.website-files.com/659480aa07716c37f0fd8dee/6597f2baa456ff33c9f13a07_logo%201.svg + } + + fthree: "" { + icon: https://assets-global.website-files.com/659480aa07716c37f0fd8dee/6597f2baa456ff33c9f13a07_logo%201.svg + } +} + +cloud.reverst <-> quic +cloud.reverst <-> quic +cloud.reverst <-> quic + +quic: "QUIC" { + shape: image + icon: https://raw.githubusercontent.com/quicwg/wg-materials/main/badge/transparent/QUIC-Badge-Dark-RGB.svg + style.font-size: 32 +} + +quic <-> yours.fapi +quic <-> yours.ftwo +quic <-> yours.fthree From fb5c7b1d93fc542fa3565b5cabf821c37886315b Mon Sep 17 00:00:00 2001 From: GeorgeMac Date: Fri, 10 May 2024 15:22:33 +0000 Subject: [PATCH 2/8] chore: format code --- cloud/architecture/overview.mdx | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/cloud/architecture/overview.mdx b/cloud/architecture/overview.mdx index 6be1dd1..bad364d 100644 --- a/cloud/architecture/overview.mdx +++ b/cloud/architecture/overview.mdx @@ -34,8 +34,14 @@ This approaches is commonly referred to as _reverse tunnelling_. Tunnelling in this way has some advantages for applications, as they can be deployed in environments without a stable IP address (e.g. behind restrictive NATs). For Flipt, this means you can safely expose Flipt from inside a major cloud provider, a modern hyperscaler or simply from your own laptop on your home network. - - + + When you register your instance in this way with Flipt Cloud, we issue you with a stable subdomain under flipt.cloud (e.g. production-megacorp.flipt.cloud). Using this DNS name, requests for your instances will flow though our API gateways, load-balancers and then only reach your instances once fully authenticated. From 027b1ef4c6a3f0f13c7beb1aed16085fcf6c98df Mon Sep 17 00:00:00 2001 From: George MacRorie Date: Fri, 10 May 2024 16:48:08 +0100 Subject: [PATCH 3/8] feat(cloud/architecture): add common infrastructure images --- cloud/architecture/overview.mdx | 3 +- .../common-infrastructure-dark.svg | 179 ++++++++++++++++++ .../common-infrastructure-light.svg | 107 +++++++++++ .../architecture/common-infrastructure.d2 | 68 +++++++ 4 files changed, 356 insertions(+), 1 deletion(-) create mode 100644 images/cloud/architecture/common-infrastructure-dark.svg create mode 100644 images/cloud/architecture/common-infrastructure-light.svg create mode 100644 images/cloud/architecture/common-infrastructure.d2 diff --git a/cloud/architecture/overview.mdx b/cloud/architecture/overview.mdx index 6be1dd1..e77a6ed 100644 --- a/cloud/architecture/overview.mdx +++ b/cloud/architecture/overview.mdx @@ -23,7 +23,8 @@ In order to take advantage of these, you're likely going to have to perform one - Manually configure OAuth client credentials for your SSO provider for OIDC authentication - Deploy and manage a database for Flipt to store session credentials in -![Common Deployed Components Diagram]() + + Flipt Cloud replaces all these steps with a few clicks and some API credentials. diff --git a/images/cloud/architecture/common-infrastructure-dark.svg b/images/cloud/architecture/common-infrastructure-dark.svg new file mode 100644 index 0000000..954adaf --- /dev/null +++ b/images/cloud/architecture/common-infrastructure-dark.svg @@ -0,0 +1,179 @@ +internetYour InfrastructureDNS ZoneLoad BalancerTLS CredentialsDatabase + + + + + + + + diff --git a/images/cloud/architecture/common-infrastructure-light.svg b/images/cloud/architecture/common-infrastructure-light.svg new file mode 100644 index 0000000..b10b5f2 --- /dev/null +++ b/images/cloud/architecture/common-infrastructure-light.svg @@ -0,0 +1,107 @@ +internetYour InfrastructureDNS ZoneLoad BalancerTLS CredentialsDatabase + + + + + + + + diff --git a/images/cloud/architecture/common-infrastructure.d2 b/images/cloud/architecture/common-infrastructure.d2 new file mode 100644 index 0000000..adaede9 --- /dev/null +++ b/images/cloud/architecture/common-infrastructure.d2 @@ -0,0 +1,68 @@ +vars: { + d2-config: { + layout-engine: elk + } +} + +direction: right + +style.fill: transparent + +internet: { + shape: image + icon: https://icons.terrastruct.com/essentials%2F140-internet.svg +} + +internet -> user.zone.elb + +user: Your Infrastructure { + style: { + stroke: transparent + fill: transparent + } + + zone: DNS Zone { + icon: https://icons.terrastruct.com/aws%2FNetworking%20&%20Content%20Delivery%2FAmazon-Route-53_Hosted-Zone_light-bg.svg + + style: { + fill: transparent + } + + elb: Load Balancer { + shape: image + icon: https://icons.terrastruct.com/aws%2FNetworking%20&%20Content%20Delivery%2FElastic-Load-Balancing-ELB_Network-load-balancer_light-bg.svg + } + + keys: TLS Credentials { + shape: image + icon: https://icons.terrastruct.com/essentials%2F216-key.svg + } + + elb -> keys + + fapi: "" { + icon: https://assets-global.website-files.com/659480aa07716c37f0fd8dee/6597f2baa456ff33c9f13a07_logo%201.svg + } + + ftwo: "" { + icon: https://assets-global.website-files.com/659480aa07716c37f0fd8dee/6597f2baa456ff33c9f13a07_logo%201.svg + } + + fthree: "" { + icon: https://assets-global.website-files.com/659480aa07716c37f0fd8dee/6597f2baa456ff33c9f13a07_logo%201.svg + } + + elb -> fapi + elb -> ftwo + elb -> fthree + + db: Database { + shape: image + icon: https://icons.terrastruct.com/essentials%2F117-database.svg + } + + fapi -> db + ftwo -> db + fthree -> db + } +} From 6c61958bc525c15dd2cad8743f98218edb1204d2 Mon Sep 17 00:00:00 2001 From: GeorgeMac Date: Fri, 10 May 2024 15:51:51 +0000 Subject: [PATCH 4/8] chore: format code --- cloud/architecture/overview.mdx | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/cloud/architecture/overview.mdx b/cloud/architecture/overview.mdx index 79fb72c..8885920 100644 --- a/cloud/architecture/overview.mdx +++ b/cloud/architecture/overview.mdx @@ -23,8 +23,14 @@ In order to take advantage of these, you're likely going to have to perform one - Manually configure OAuth client credentials for your SSO provider for OIDC authentication - Deploy and manage a database for Flipt to store session credentials in - - + + Flipt Cloud replaces all these steps with a few clicks and some API credentials. From fd29c3e30f4def72ff22fcc9525de65115708602 Mon Sep 17 00:00:00 2001 From: George MacRorie Date: Fri, 10 May 2024 17:08:19 +0100 Subject: [PATCH 5/8] feat(cloud/architecture): add tunnel handshake images --- cloud/architecture/overview.mdx | 3 +- images/cloud/architecture/handshake-dark.svg | 185 ++++++++++++++++++ images/cloud/architecture/handshake-light.svg | 113 +++++++++++ images/cloud/architecture/handshake.d2 | 22 +++ 4 files changed, 322 insertions(+), 1 deletion(-) create mode 100644 images/cloud/architecture/handshake-dark.svg create mode 100644 images/cloud/architecture/handshake-light.svg create mode 100644 images/cloud/architecture/handshake.d2 diff --git a/cloud/architecture/overview.mdx b/cloud/architecture/overview.mdx index 79fb72c..8f9f7bc 100644 --- a/cloud/architecture/overview.mdx +++ b/cloud/architecture/overview.mdx @@ -54,7 +54,8 @@ All of which is done without you having to provide TLS certificates, and without Your connections are made using an API key credential obtained from our Flipt Cloud UI, or via the `flipt cloud login` subcommand of the Flipt CLI. This credential is used in an initial handshake to identify your Flipt Cloud organization and the logical instance your Flipt is joining. -![Tunnel Registration Handshake]() + + Once registered and associated with Flipt Cloud, your Flipt instance is added to our remote load balancer pool for your logical instance. Now when you visit your new Flipt Cloud instance subdomain, your requests are routed to the instance(s) deployed on your infrastructure. diff --git a/images/cloud/architecture/handshake-dark.svg b/images/cloud/architecture/handshake-dark.svg new file mode 100644 index 0000000..54bf5ac --- /dev/null +++ b/images/cloud/architecture/handshake-dark.svg @@ -0,0 +1,185 @@ +FliptFlipt CloudFlipt UserFlipt registers on flipt.cloudInstance served on flipt.cloudtunnelled request Register TunnelRegisteredinstance-org.flipt.cloudRequestResponseResponse + + + + + + + + + + + + + + diff --git a/images/cloud/architecture/handshake-light.svg b/images/cloud/architecture/handshake-light.svg new file mode 100644 index 0000000..219cf9e --- /dev/null +++ b/images/cloud/architecture/handshake-light.svg @@ -0,0 +1,113 @@ +FliptFlipt CloudFlipt UserFlipt registers on flipt.cloudInstance served on flipt.cloudtunnelled request Register TunnelRegisteredinstance-org.flipt.cloudRequestResponseResponse + + + + + + + + + + + + + + diff --git a/images/cloud/architecture/handshake.d2 b/images/cloud/architecture/handshake.d2 new file mode 100644 index 0000000..318762c --- /dev/null +++ b/images/cloud/architecture/handshake.d2 @@ -0,0 +1,22 @@ +shape: sequence_diagram + +style.fill: transparent + +client_one: Flipt +tunnel: Flipt Cloud + +register: Flipt registers on flipt.cloud { + client_one -> tunnel.handshake: Register Tunnel + tunnel.handshake -> client_one: Registered +} + +user: Flipt User + +instance: Instance served on flipt.cloud { + user -> tunnel.req: instance-org.flipt.cloud + tunnelled request: { + tunnel -> client_one.req: Request + client_one.req -> tunnel: Response + } + tunnel.req -> user: Response +} From 35816d2586dc731ae54b02bf880d31a214908955 Mon Sep 17 00:00:00 2001 From: GeorgeMac Date: Fri, 10 May 2024 16:09:12 +0000 Subject: [PATCH 6/8] chore: format code --- cloud/architecture/overview.mdx | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/cloud/architecture/overview.mdx b/cloud/architecture/overview.mdx index 212a943..bbd349d 100644 --- a/cloud/architecture/overview.mdx +++ b/cloud/architecture/overview.mdx @@ -60,8 +60,14 @@ All of which is done without you having to provide TLS certificates, and without Your connections are made using an API key credential obtained from our Flipt Cloud UI, or via the `flipt cloud login` subcommand of the Flipt CLI. This credential is used in an initial handshake to identify your Flipt Cloud organization and the logical instance your Flipt is joining. - - + + Once registered and associated with Flipt Cloud, your Flipt instance is added to our remote load balancer pool for your logical instance. Now when you visit your new Flipt Cloud instance subdomain, your requests are routed to the instance(s) deployed on your infrastructure. From 5654f361fe4065e79bdf97477705d36d20a9c2f4 Mon Sep 17 00:00:00 2001 From: George Date: Fri, 10 May 2024 17:31:26 +0100 Subject: [PATCH 7/8] chore: apply suggestions from code review Co-authored-by: Mark Phelps <209477+markphelps@users.noreply.github.com> --- cloud/architecture/overview.mdx | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/cloud/architecture/overview.mdx b/cloud/architecture/overview.mdx index bbd349d..4a6003b 100644 --- a/cloud/architecture/overview.mdx +++ b/cloud/architecture/overview.mdx @@ -5,15 +5,15 @@ description: Learn the technical details of how Flipt Hybrid Cloud works This page details how Flipt Cloud is architected to provide a simple and scalable solution for accessing and securing your internal, self-hosted deployments of Flipt. -Much like other great self-hosted, open-source developer tools with built-in user interfaces, Flipt itself comes baked with lots of critical features for scale and security. +Flipt comes baked with lots of critical features for scale and security, including: -- Horizontal scalability +- Ability to scale hoizontally - HTTPS/TLS support - Configurable authentication mechanisms (Static Token, OIDC, GitHub, JWT and Kubernetes) - API and UI with session management and termination -These capabilites are super important for being able to deploy Flipt onto your own infrastructure and make it secure for your users. -However, enabling and integrating these features is not free of its own complexities, infrastructure and time investment. +These capabilities are super important for deploying Flipt into your infrastructure and making it secure for your users. +However, enabling and integrating these features is not free of complexities, infrastructure, and time investment. In order to take advantage of these, you're likely going to have to perform one or many of the following: - Enable networking and routing to your Flipt instance @@ -34,11 +34,11 @@ In order to take advantage of these, you're likely going to have to perform one Flipt Cloud replaces all these steps with a few clicks and some API credentials. -## Flipt the problem on its head +## Flipt the Problem on its Head Flipt Cloud reverses the ingress problem so that your deployments of Flipt dial out to us instead. -This approaches is commonly referred to as _reverse tunnelling_. -Tunnelling in this way has some advantages for applications, as they can be deployed in environments without a stable IP address (e.g. behind restrictive NATs). +This approach is commonly referred to as _reverse tunneling_. +Tunneling in this way has some advantages for applications, as they can be deployed in environments without a stable IP address (e.g. behind restrictive NATs). For Flipt, this means you can safely expose Flipt from inside a major cloud provider, a modern hyperscaler or simply from your own laptop on your home network. Date: Fri, 10 May 2024 17:39:35 +0100 Subject: [PATCH 8/8] chore(cloud/architecture): appease the vale linting gods --- .vale/styles/Flipt/spelling-exceptions.txt | 5 ++++- cloud/architecture/overview.mdx | 10 +++++----- 2 files changed, 9 insertions(+), 6 deletions(-) diff --git a/.vale/styles/Flipt/spelling-exceptions.txt b/.vale/styles/Flipt/spelling-exceptions.txt index 87b0ba1..e666e7b 100644 --- a/.vale/styles/Flipt/spelling-exceptions.txt +++ b/.vale/styles/Flipt/spelling-exceptions.txt @@ -67,4 +67,7 @@ uncomment uncompromised URIs yaml -zipkin \ No newline at end of file +zipkin +NATs +hyperscaler +Reverst diff --git a/cloud/architecture/overview.mdx b/cloud/architecture/overview.mdx index 4a6003b..7da040f 100644 --- a/cloud/architecture/overview.mdx +++ b/cloud/architecture/overview.mdx @@ -3,17 +3,17 @@ title: Technical Details description: Learn the technical details of how Flipt Hybrid Cloud works --- -This page details how Flipt Cloud is architected to provide a simple and scalable solution for accessing and securing your internal, self-hosted deployments of Flipt. +This page details how Flipt Cloud is built to provide a simple and scalable solution for accessing and securing your internal, self-hosted deployments of Flipt. Flipt comes baked with lots of critical features for scale and security, including: -- Ability to scale hoizontally +- Ability to scale horizontally - HTTPS/TLS support - Configurable authentication mechanisms (Static Token, OIDC, GitHub, JWT and Kubernetes) - API and UI with session management and termination These capabilities are super important for deploying Flipt into your infrastructure and making it secure for your users. -However, enabling and integrating these features is not free of complexities, infrastructure, and time investment. +However, enabling and integrating these features isn't free of complexities, infrastructure, and time investment. In order to take advantage of these, you're likely going to have to perform one or many of the following: - Enable networking and routing to your Flipt instance @@ -57,7 +57,7 @@ All of which is done without you having to provide TLS certificates, and without ## Tunnel Registration -Your connections are made using an API key credential obtained from our Flipt Cloud UI, or via the `flipt cloud login` subcommand of the Flipt CLI. +Your connections are made using an API key credential obtained from our Flipt Cloud UI, or via the `flipt cloud login` sub-command of the Flipt CLI. This credential is used in an initial handshake to identify your Flipt Cloud organization and the logical instance your Flipt is joining. Once registered and associated with Flipt Cloud, your Flipt instance is added to our remote load balancer pool for your logical instance. -Now when you visit your new Flipt Cloud instance subdomain, your requests are routed to the instance(s) deployed on your infrastructure. +Now when you visit your new Flipt Cloud instance subdomain, your requests are routed to the instances deployed on your infrastructure. The majority of the tunneling functionality we perform is now open-source in our project [Reverst](https://github.com/flipt-io/reverst). Reverst is unique in that it leverages HTTP/3 and the QUIC protocol to establish secure, reliable, and performant connections for tunnels.