From ea00ea9d56d05f21719baa1ad8fc4a4c65bd055d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Gast=C3=B3n=20Fournier?= Date: Fri, 1 Sep 2023 15:39:23 +0200 Subject: [PATCH] docs: troubleshooting guides (#4592) ## About the changes Adds troubleshooting guides for some common problems under the how-to area (following the [diataxis framework](https://diataxis.fr/)). This is part of Unleash 2023 offsite challenge --------- Co-authored-by: Drew Gorton Co-authored-by: Diego Susa Co-authored-by: Michael Vittiglio Co-authored-by: Thomas Heartman --- website/docs/about-the-docs.md | 1 + .../docs/how-to/how-to-troubleshoot-cors.md | 6 ++++++ .../how-to-troubleshoot-flag-exposure.md | 7 +++++++ .../how-to-troubleshoot-flag-not-returned.md | 18 ++++++++++++++++++ website/sidebars.js | 17 ++++++++++++++++- 5 files changed, 48 insertions(+), 1 deletion(-) create mode 100644 website/docs/how-to/how-to-troubleshoot-cors.md create mode 100644 website/docs/how-to/how-to-troubleshoot-flag-exposure.md create mode 100644 website/docs/how-to/how-to-troubleshoot-flag-not-returned.md diff --git a/website/docs/about-the-docs.md b/website/docs/about-the-docs.md index 56b40a47fd5f..79393e373d7f 100644 --- a/website/docs/about-the-docs.md +++ b/website/docs/about-the-docs.md @@ -37,6 +37,7 @@ The guides are organized into the following categories: - [Feature toggles, strategies, context, and general how-tos](./how-to/misc) - [Users and permissions how-tos](./how-to/users-and-permissions) - [Single Sign-On (SSO) how-tos](./how-to/sso) +- [Troubleshooting how-tos](./how-to/troubleshooting) ### Reference documentation diff --git a/website/docs/how-to/how-to-troubleshoot-cors.md b/website/docs/how-to/how-to-troubleshoot-cors.md new file mode 100644 index 000000000000..72a79caf8ac4 --- /dev/null +++ b/website/docs/how-to/how-to-troubleshoot-cors.md @@ -0,0 +1,6 @@ +--- +title: My requests are being blocked by CORS +--- + +1. Make sure you've configured CORS access in Unleash admin UI settings as defined in the [Unleash CORS Policy docs](../reference/front-end-api#cors). These settings can be changed in the Unleash Dashboard under **Settings -> CORS Origins** or by using the [API](../reference/api/unleash/set-ui-config). Allowing all origins (using a single asterisk) will address this matter and is a great starting point when troubleshooting the behavior. +1. When receiving "**No 'Access-Control-Policy' header is present on the requested resource**", using the command `curl -I https:///` will allow us to verify that the response includes the header `Access-Control-Allow-Origin: *`. \ No newline at end of file diff --git a/website/docs/how-to/how-to-troubleshoot-flag-exposure.md b/website/docs/how-to/how-to-troubleshoot-flag-exposure.md new file mode 100644 index 000000000000..66c17c413419 --- /dev/null +++ b/website/docs/how-to/how-to-troubleshoot-flag-exposure.md @@ -0,0 +1,7 @@ +--- +title: My feature flag is enabled but all/some of our users are not exposed to it +--- + +To confirm how users will have flags resolved, follow these steps: +1. The [Unleash Playground](../reference/playground.mdx) was developed with this particular use case in mind. An access token can be used along with context values (passed in via the UI) to see how a flag will be resolved. +2. When using a **gradual rollout** strategy, be mindful of the **[stickiness](../reference/stickiness)** value. When evaluating a flag, if the provided context does not include the field used in the stickiness configuration, the gradual rollout strategy will be evaluated to `false`. diff --git a/website/docs/how-to/how-to-troubleshoot-flag-not-returned.md b/website/docs/how-to/how-to-troubleshoot-flag-not-returned.md new file mode 100644 index 000000000000..f4f36bd16c9d --- /dev/null +++ b/website/docs/how-to/how-to-troubleshoot-flag-not-returned.md @@ -0,0 +1,18 @@ +--- +title: My feature flag is not returned in the Frontend API/Edge/Proxy +--- + +By default, these endpoints will not return feature flags that are not enabled. This is mainly to save on bandwidth but it makes it a bit difficult to debug when features are not being returned. + +The first thing to look into is to validate that the feature is well configured and then check the token used from the SDK because it determines the set of accessible features. Last, verify that the context you're providing contains all the required data. + +1. Check that the feature is properly enabled: + 1. Verify that the feature has a strategy associated to it that will return true for your context (ref: [add a strategy](/how-to/how-to-create-feature-toggles#step-2)) + 1. Verify that the feature has been enabled in the environment used by the client application (ref: [enabling a feature flag](/how-to/how-to-create-feature-toggles#step-3)) +1. Check that your token is of the right [type](../reference/api-tokens-and-client-keys.mdx). To connect to the Frontend API, Edge or Proxy, you need to use a [Front-end token](/reference/api-tokens-and-client-keys#front-end-tokens) +1. Check that your token has access to the feature flag. The **token access configuration is immutable post-creation** and defines the set of features that the token can access. The different [parts of a token](/reference/api-tokens-and-client-keys#version-2) determine what projects and environment can be accessed: + 1. **Access to all projects (current and future)** - Tokens with a leading asterisk will provide access to all projects in a particular environment. For example, the token `*:production:xyz123etc...` will provide access to flags in the production environment of all projects. + 1. **Access to a discrete list of projects** - Tokens with a leading set of square brackets (empty) will be given access to a subset of projects in a particular environment. The token will look similar to the following: `[]:production:xyz123etc...`. Which projects the token has access to can be found on the API Tokens page in the Unleash admin UI. + 1. **Single project access** - Tokens that lead with a project name are bound to the specified project and environment. For example, `my_fullstack_app:production:xyz123etc...` will only have access to flags in the "my_fullstack_app" project as set in the production environment. +1. When using a **gradual rollout** strategy, be mindful of the **[stickiness](../reference/stickiness)** value. When evaluating a flag, if the provided context does not include the field used in the stickiness configuration, the gradual rollout strategy will be evaluated to `false` and therefore it will not be returned by the API. +1. Feature activation strategies may have constraints, segments, and rules that can be combined in different ways that can lead to complex scenarios. Try using the [Playground](../reference/playground.mdx) to verify that the feature is properly configured and responding as expected. diff --git a/website/sidebars.js b/website/sidebars.js index d903e2d14fa5..da2c0db54b42 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -154,7 +154,22 @@ module.exports = { slug: '/how-to/sso', }, }, - , + { + label: 'Troubleshooting', + items: [ + 'how-to/how-to-troubleshoot-flag-exposure', + 'how-to/how-to-troubleshoot-flag-not-returned', + 'how-to/how-to-troubleshoot-cors', + ], + type: 'category', + link: { + type: 'generated-index', + title: 'How-to: troubleshooting', + description: + 'Troubleshooting common problems. If you want to contribute, please make sure the title is phrased as a concrete user problem', + slug: '/how-to/troubleshooting', + }, + }, ], }, {