Mirrors/unleash.unleash
1
0
Fork 0
mirror of https://github.com/Unleash/unleash.git synced 2024-10-18 20:09:08 +02:00
Code Issues Projects Releases Wiki Activity
7f907eb44c
unleash.unleash/website/docs/topics/proxy-hosting.mdx

111 lines
7.6 KiB
Plaintext
Raw Normal View History

docs: add proxy deployment diagrams (#1743) * docs: remove empty table row * docs: add placeholder proxy hosting article * docs: add images, describe first one * docs: describe the customer-hosted proxy solution * docs: describe the self-hosted single-region setup. * docs: describe enterprise multi-region setup. * docs: minor changes * docs: update lists; restructure * docs: more minor changes * docs: add alt text to diagrams * docs: update proxy hosting doc * docs: some prettier formatting * docs: add link to proxy hosting doc * docs: format proxy config table * docs: prettier formatting
2022-06-23 08:28:01 +02:00
---
title: Proxy hosting strategies
---
Source proxy and Edge docs from GitHub (#3122) ## What The main purpose of this PR is to 1. Delete the proxy docs in this repo and replace them with the proxy's GitHub readme. 2. Add the docs for Unleash Edge. ### Detailed change description This PR contains a lot of small changes in a large number of files. To make it easier to get an overview, here's a detailed description of what happens where: #### In the `website/docs`directory Except for the deletion of the proxy doc, all changes in this directory are rewriting internal links, so that they point to the newly generated document instead. #### `package.json` and `yarn.lock` When including the documentation for Edge, we also want to render the mermaid diagrams it uses. Docusaurus supports this via a plugin. All changes in these files are related to installing that plugin. #### `docusaurus.config.js` There's two types of changes in this file: 1. Mermaid-related changes: we ask docusaurus to render mermaid in markdown files and add the plugin 2. Document generation. There's some rewrites to the sdk doc generation plus an entirely new section that generates docs for Edge and the proxy #### `sidebars.js` Two things: 1. Add the edge docs 2. Move both the Edge and the proxy docs up a level, so that they're directly under "reference docs" instead of nested inside "unleash concepts". #### In the `website/remote-content` directory These are the remote content files. Previously, all of this lived only in a `readme-fns.js` file, but with the introduction of Edge and proxy docs, this has been moved into its own directory and refactored into three files (`shared`, `sdks`, `edge-proxy`). #### `custom.css` Style updates to center mermaid diagrams and provide more space around them. #### In `static/img` The image files that were included in the proxy doc and that have been deleted. ## Why For two reasons: 1. Reduce duplication for the proxy. Have one source of truth. 2. Add docs for edge. ## Discussion points and review wishes This is a big PR, and I don't expect anyone to do a line-by-line review of it, nor do I think that is particularly useful. Instead, I'd like to ask reviewers to: 1. Visit the [documentation preview](https://unleash-docs-git-docs-source-proxy-gh-unleash-team.vercel.app/reference/unleash-proxy) and have a look at both the proxy docs and the Edge docs. Potentially have a look at the SDK docs too to verify that everything still works. 2. Consider whether they think moving the proxy and edge docs up a level (in the sidebar) makes sense. 3. Let me know what slug they'd prefer for the Edge docs. I've gone with `unleash-edge` for now (so that it's `docs.getunleash.io/reference/unleash-edge`), but we could potentially also just use `edge`. WDYT? 4. Read through the detailed changes section. 5. Let me know if they have any other concerns or questions. ## Screenies The new proxy doc: ![image](https://user-images.githubusercontent.com/17786332/219043145-1c75c83e-4191-45a3-acb5-775d05d13862.png) The new edge doc: ![image](https://user-images.githubusercontent.com/17786332/219043220-1f5daf13-972e-4d56-8aaf-70ff1812863e.png)
2023-02-16 13:36:28 +01:00
Because the [Unleash proxy](../generated/unleash-proxy.md) is a separate piece of the Unleash architecture and because it should sit close to your application, there are numerous ways of hosting it. Another important distinction is whether you're hosting Unleash yourself or you have a managed solution.
docs: add proxy deployment diagrams (#1743) * docs: remove empty table row * docs: add placeholder proxy hosting article * docs: add images, describe first one * docs: describe the customer-hosted proxy solution * docs: describe the self-hosted single-region setup. * docs: describe enterprise multi-region setup. * docs: minor changes * docs: update lists; restructure * docs: more minor changes * docs: add alt text to diagrams * docs: update proxy hosting doc * docs: some prettier formatting * docs: add link to proxy hosting doc * docs: format proxy config table * docs: prettier formatting
2022-06-23 08:28:01 +02:00
This document describes the three main ways of hosting the proxy alongside the Unleash API and the tradeoffs between hosting the proxy yourself and having Unleash host it for you.
## Unleash-hosted proxy vs self-hosted proxy {#unleash-hosted-or-self-hosted}
Which way is right for you will depend on your setup and your needs. In general, we recommend that you host the proxy yourself, but we do recognize that self-hosting requires some extra work on your part and that not all our customers need it.
If you want Unleash to host the proxy for you, you should be aware of the following limitations:
- This is only available to Pro and Enterprise customers who have signed up for a managed Unleash instance.
fix: adjust the proxy docs
2022-08-29 23:07:48 +02:00
- Pro customers will get a total of two (2) proxies: One for the "development" environment and one for the "production" environment.
refactor: move docs into new structure / fix links for SEO (#2416) ## What This (admittedly massive) PR updates the "physical" documentation structure and fixes url inconsistencies and SEO problems reported by marketing. The main points are: - remove or move directories : advanced, user_guide, deploy, api - move the files contained within to the appropriate one of topics, how-to, tutorials, or reference - update internal doc links and product links to the content - create client-side redirects for all the urls that have changed. A number of the files have been renamed in small ways to better match their url and to make them easier to find. Additionally, the top-level api directory has been moved to /reference/api/legacy/unleash (see the discussion points section for more on this). ## Why When moving our doc structure to diataxis a while back, we left the "physical' files lying where they were, because it didn't matter much to the new structure. However, that did introduce some inconsistencies with where you place docs and how we organize them. There's also the discrepancies in whether urls us underscores or hyphens (which isn't necessarily the same as their file name), which has been annoying me for a while, but now has also been raised by marketing as an issue in terms of SEO. ## Discussion points The old, hand-written API docs have been moved from /api to /reference/api/legacy/unleash. There _is_ a /reference/api/unleash directory, but this is being populated by the OpenAPI plugin, and mixing those could only cause trouble. However, I'm unsure about putting /legacy/ in the title, because the API isn't legacy, the docs are. Maybe we could use another path? Like /old-docs/ or something? I'd appreciate some input on this.
2022-11-22 10:05:30 +01:00
- We do allow short spikes in traffic and our adaptive infrastructure will automatically scale your needs.
Source proxy and Edge docs from GitHub (#3122) ## What The main purpose of this PR is to 1. Delete the proxy docs in this repo and replace them with the proxy's GitHub readme. 2. Add the docs for Unleash Edge. ### Detailed change description This PR contains a lot of small changes in a large number of files. To make it easier to get an overview, here's a detailed description of what happens where: #### In the `website/docs`directory Except for the deletion of the proxy doc, all changes in this directory are rewriting internal links, so that they point to the newly generated document instead. #### `package.json` and `yarn.lock` When including the documentation for Edge, we also want to render the mermaid diagrams it uses. Docusaurus supports this via a plugin. All changes in these files are related to installing that plugin. #### `docusaurus.config.js` There's two types of changes in this file: 1. Mermaid-related changes: we ask docusaurus to render mermaid in markdown files and add the plugin 2. Document generation. There's some rewrites to the sdk doc generation plus an entirely new section that generates docs for Edge and the proxy #### `sidebars.js` Two things: 1. Add the edge docs 2. Move both the Edge and the proxy docs up a level, so that they're directly under "reference docs" instead of nested inside "unleash concepts". #### In the `website/remote-content` directory These are the remote content files. Previously, all of this lived only in a `readme-fns.js` file, but with the introduction of Edge and proxy docs, this has been moved into its own directory and refactored into three files (`shared`, `sdks`, `edge-proxy`). #### `custom.css` Style updates to center mermaid diagrams and provide more space around them. #### In `static/img` The image files that were included in the proxy doc and that have been deleted. ## Why For two reasons: 1. Reduce duplication for the proxy. Have one source of truth. 2. Add docs for edge. ## Discussion points and review wishes This is a big PR, and I don't expect anyone to do a line-by-line review of it, nor do I think that is particularly useful. Instead, I'd like to ask reviewers to: 1. Visit the [documentation preview](https://unleash-docs-git-docs-source-proxy-gh-unleash-team.vercel.app/reference/unleash-proxy) and have a look at both the proxy docs and the Edge docs. Potentially have a look at the SDK docs too to verify that everything still works. 2. Consider whether they think moving the proxy and edge docs up a level (in the sidebar) makes sense. 3. Let me know what slug they'd prefer for the Edge docs. I've gone with `unleash-edge` for now (so that it's `docs.getunleash.io/reference/unleash-edge`), but we could potentially also just use `edge`. WDYT? 4. Read through the detailed changes section. 5. Let me know if they have any other concerns or questions. ## Screenies The new proxy doc: ![image](https://user-images.githubusercontent.com/17786332/219043145-1c75c83e-4191-45a3-acb5-775d05d13862.png) The new edge doc: ![image](https://user-images.githubusercontent.com/17786332/219043220-1f5daf13-972e-4d56-8aaf-70ff1812863e.png)
2023-02-16 13:36:28 +01:00
- Please check the [Fair Use Policy](https://www.getunleash.io/fair-use-policy) to see the limits of the Unleash-hosted proxy.
docs: add proxy deployment diagrams (#1743) * docs: remove empty table row * docs: add placeholder proxy hosting article * docs: add images, describe first one * docs: describe the customer-hosted proxy solution * docs: describe the self-hosted single-region setup. * docs: describe enterprise multi-region setup. * docs: minor changes * docs: update lists; restructure * docs: more minor changes * docs: add alt text to diagrams * docs: update proxy hosting doc * docs: some prettier formatting * docs: add link to proxy hosting doc * docs: format proxy config table * docs: prettier formatting
2022-06-23 08:28:01 +02:00
- There's no guarantee that it'll be close to your applications. This means you'll get higher response times.
refactor: move docs into new structure / fix links for SEO (#2416) ## What This (admittedly massive) PR updates the "physical" documentation structure and fixes url inconsistencies and SEO problems reported by marketing. The main points are: - remove or move directories : advanced, user_guide, deploy, api - move the files contained within to the appropriate one of topics, how-to, tutorials, or reference - update internal doc links and product links to the content - create client-side redirects for all the urls that have changed. A number of the files have been renamed in small ways to better match their url and to make them easier to find. Additionally, the top-level api directory has been moved to /reference/api/legacy/unleash (see the discussion points section for more on this). ## Why When moving our doc structure to diataxis a while back, we left the "physical' files lying where they were, because it didn't matter much to the new structure. However, that did introduce some inconsistencies with where you place docs and how we organize them. There's also the discrepancies in whether urls us underscores or hyphens (which isn't necessarily the same as their file name), which has been annoying me for a while, but now has also been raised by marketing as an issue in terms of SEO. ## Discussion points The old, hand-written API docs have been moved from /api to /reference/api/legacy/unleash. There _is_ a /reference/api/unleash directory, but this is being populated by the OpenAPI plugin, and mixing those could only cause trouble. However, I'm unsure about putting /legacy/ in the title, because the API isn't legacy, the docs are. Maybe we could use another path? Like /old-docs/ or something? I'd appreciate some input on this.
2022-11-22 10:05:30 +01:00
- When we host the proxy, we will also receive whatever end user data you put in the [Unleash context](../reference/unleash-context.md). This may or may not be an issue depending on your business requirements.
docs: add proxy deployment diagrams (#1743) * docs: remove empty table row * docs: add placeholder proxy hosting article * docs: add images, describe first one * docs: describe the customer-hosted proxy solution * docs: describe the self-hosted single-region setup. * docs: describe enterprise multi-region setup. * docs: minor changes * docs: update lists; restructure * docs: more minor changes * docs: add alt text to diagrams * docs: update proxy hosting doc * docs: some prettier formatting * docs: add link to proxy hosting doc * docs: format proxy config table * docs: prettier formatting
2022-06-23 08:28:01 +02:00
Hosting the proxy yourself requires a little more setup on your part than the Unleash-hosted proxy does, but it offers a number of benefits:
- You can scale the proxy horizontally and automatically.
- There's no request cap or extra charges.
- You can host as many proxies as you want for as many different environments as you want.
- You can arrange for the proxy to be close to your applications, minimizing response times.
- You have full control of all your user data. None of the data that the proxy receives is ever sent to the Unleash API. This keeps _your_ data in _your_ hands.
- You can easily add more proxies in different regions, as described in the [multi-region](#multi-region) section.
## Unleash hosts everything
:::info Availability
This setup is only available to Pro and Enterprise customers.
:::
![An architecture diagram of using the proxy in a setup where Unleash hosts both the API and the proxy.](/img/proxy-hosting-all-unleash.svg)
When Unleash hosts the proxy, it'll run alongside the Unleash API and the admin UI within Unleash's Kubernetes setup in AWS. The API is backed by an Amazon RDS database. Your applications can connect to the proxy from your own cloud or other hosting solution. You'll need to configure your proxy SDKs with the following details:
- One of the [proxy's client keys](../reference/api-tokens-and-client-keys.mdx#proxy-client-keys). Unleash will provide you with the actual keys.
- The proxy's endpoint. This will be the your Unleash instance's URL followed by "/api/proxy/development" or "/api/proxy/production" (depending on which environment you want to use).
This is the simplest, but also most limited (by far) way to host the proxy. In this setup, Unleash hosts both the Unleash API and the Unleash proxy. With Unleash hosting the proxy, you'll only need to worry about the client keys and the URL the proxy is hosted at.
While this is easy to get started with, it comes with the limitations described in the [section on tradeoffs between self-hosted and Unleash-hosted setups](#unleash-hosted-or-self-hosted).
## Unleash hosts the API, you host the proxy
:::info Availability
This setup is only available to Pro and Enterprise customers.
:::
![An architecture diagram of using the proxy in a setup where Unleash hosts the API and you host the proxy.](/img/proxy-hosting-unleash-api-customer-proxy.svg)
You host the proxy yourself. It runs in a standalone container alongside your other applications in your cloud or hosting setup. Unleash manages the Unleash API, the admin UI, and the backing database in our AWS setup: the API and the UI run together in a Kubernetes deployment and connect to an Amazon RDS database.
You'll need to configure the proxy and the proxy client SDKs.
For the proxy, configure:
- The Unleash API url. This is your Unleash instance URL followed by "/api".
refactor: move docs into new structure / fix links for SEO (#2416) ## What This (admittedly massive) PR updates the "physical" documentation structure and fixes url inconsistencies and SEO problems reported by marketing. The main points are: - remove or move directories : advanced, user_guide, deploy, api - move the files contained within to the appropriate one of topics, how-to, tutorials, or reference - update internal doc links and product links to the content - create client-side redirects for all the urls that have changed. A number of the files have been renamed in small ways to better match their url and to make them easier to find. Additionally, the top-level api directory has been moved to /reference/api/legacy/unleash (see the discussion points section for more on this). ## Why When moving our doc structure to diataxis a while back, we left the "physical' files lying where they were, because it didn't matter much to the new structure. However, that did introduce some inconsistencies with where you place docs and how we organize them. There's also the discrepancies in whether urls us underscores or hyphens (which isn't necessarily the same as their file name), which has been annoying me for a while, but now has also been raised by marketing as an issue in terms of SEO. ## Discussion points The old, hand-written API docs have been moved from /api to /reference/api/legacy/unleash. There _is_ a /reference/api/unleash directory, but this is being populated by the OpenAPI plugin, and mixing those could only cause trouble. However, I'm unsure about putting /legacy/ in the title, because the API isn't legacy, the docs are. Maybe we could use another path? Like /old-docs/ or something? I'd appreciate some input on this.
2022-11-22 10:05:30 +01:00
- A [client API token](../reference/api-tokens-and-client-keys.mdx#client-tokens). (Refer to [how to create API tokens](../how-to/how-to-create-api-tokens.mdx) for the steps to create one.)
- One or more [proxy client keys](../reference/api-tokens-and-client-keys.mdx#proxy-client-keys). Refer to the [configuration section of the proxy document](../reference/unleash-proxy#configuration) for more details.
docs: add proxy deployment diagrams (#1743) * docs: remove empty table row * docs: add placeholder proxy hosting article * docs: add images, describe first one * docs: describe the customer-hosted proxy solution * docs: describe the self-hosted single-region setup. * docs: describe enterprise multi-region setup. * docs: minor changes * docs: update lists; restructure * docs: more minor changes * docs: add alt text to diagrams * docs: update proxy hosting doc * docs: some prettier formatting * docs: add link to proxy hosting doc * docs: format proxy config table * docs: prettier formatting
2022-06-23 08:28:01 +02:00
For the proxy client SDK, configure:
- One of the proxy client keys that you configured for the proxy.
- The proxy's endpoint. This will depend on where and how you're hosting the proxy, but will typically end in "/proxy"
This setup requires a little more setup on your part than the Unleash-hosted proxy does, but it offers all the benefits described in the [section on tradeoffs between self-hosted and Unleash-hosted setups](#unleash-hosted-or-self-hosted).
## You host everything
:::info Availability
This setup is only available open-source and Enterprise customers.
:::
![An architecture diagram of using the proxy in a single-region, self-hosted setup.](/img/proxy-hosting-customer-single.svg)
You host everything yourself. Everything runs where and how you configure it to.
You'll need to configure the proxy and the proxy client SDKs.
For the proxy, configure:
- The Unleash API url. This is your Unleash instance URL followed by "/api".
refactor: move docs into new structure / fix links for SEO (#2416) ## What This (admittedly massive) PR updates the "physical" documentation structure and fixes url inconsistencies and SEO problems reported by marketing. The main points are: - remove or move directories : advanced, user_guide, deploy, api - move the files contained within to the appropriate one of topics, how-to, tutorials, or reference - update internal doc links and product links to the content - create client-side redirects for all the urls that have changed. A number of the files have been renamed in small ways to better match their url and to make them easier to find. Additionally, the top-level api directory has been moved to /reference/api/legacy/unleash (see the discussion points section for more on this). ## Why When moving our doc structure to diataxis a while back, we left the "physical' files lying where they were, because it didn't matter much to the new structure. However, that did introduce some inconsistencies with where you place docs and how we organize them. There's also the discrepancies in whether urls us underscores or hyphens (which isn't necessarily the same as their file name), which has been annoying me for a while, but now has also been raised by marketing as an issue in terms of SEO. ## Discussion points The old, hand-written API docs have been moved from /api to /reference/api/legacy/unleash. There _is_ a /reference/api/unleash directory, but this is being populated by the OpenAPI plugin, and mixing those could only cause trouble. However, I'm unsure about putting /legacy/ in the title, because the API isn't legacy, the docs are. Maybe we could use another path? Like /old-docs/ or something? I'd appreciate some input on this.
2022-11-22 10:05:30 +01:00
- A [client API token](../reference/api-tokens-and-client-keys.mdx#client-tokens). (Refer to [how to create API tokens](../how-to/how-to-create-api-tokens.mdx) for the steps to create one.)
- One or more [proxy client keys](../reference/api-tokens-and-client-keys.mdx#proxy-client-keys). Refer to the [configuration section of the proxy document](../reference/unleash-proxy#configuration) for more details.
docs: add proxy deployment diagrams (#1743) * docs: remove empty table row * docs: add placeholder proxy hosting article * docs: add images, describe first one * docs: describe the customer-hosted proxy solution * docs: describe the self-hosted single-region setup. * docs: describe enterprise multi-region setup. * docs: minor changes * docs: update lists; restructure * docs: more minor changes * docs: add alt text to diagrams * docs: update proxy hosting doc * docs: some prettier formatting * docs: add link to proxy hosting doc * docs: format proxy config table * docs: prettier formatting
2022-06-23 08:28:01 +02:00
For the proxy client SDK, configure:
- One of the proxy client keys that you configured for the proxy.
- The proxy's endpoint. This will depend on where and how you're hosting the proxy, but will typically end in "/proxy"
As you might expect, doing everything yourself _is_ going to give you the most flexibility, but it's also going to be the most work. If you're already hosting Unleash yourself, though, this shouldn't be any more difficult than the previous section.
As described in the [section on tradeoffs between self-hosted and Unleash-hosted setups](#unleash-hosted-or-self-hosted), running the proxy yourself gives you a number of benefits.
## Multi-region
![An architecture diagram of using the proxy in a multi-region, self-hosted setup.](/img/proxy-hosting-customer-multi.svg)
You can also use the proxy for a multi-region setup. You can run a proxy in a different region to the API and still connect to the API. Because the proxy runs closer to your applications it still provides you benefits in terms of quicker response times. Everything should be configured as described in the [you host everything section](#you-host-everything) or the [Unleash hosts the API, you host the proxy section](#unleash-hosts-the-api-you-host-the-proxy). You can add as many extra proxies in as many extra regions as you want.
Reference in New Issue Copy Permalink