diff --git a/website/docs/topics/feature-flags/never-expose-pii.md b/website/docs/topics/feature-flags/never-expose-pii.md index d16e5791aa..5b3782d81e 100644 --- a/website/docs/topics/feature-flags/never-expose-pii.md +++ b/website/docs/topics/feature-flags/never-expose-pii.md @@ -2,19 +2,21 @@ title: 2. Never expose PII. Follow the principle of least privilege. --- -To keep things simple, you may be tempted to evaluate the feature flags in your Feature Flag Control Service. Don’t. Your Feature Flag Control Service should only handle the configuration for your feature flags and pass this configuration down to SDKs connecting from your applications. +import Figure from '@site/src/components/Figure/Figure.tsx' + +To keep things simple, you may be tempted to evaluate the feature flags in your Feature Flag Control Service. Don’t. Your Feature Flag Control Service should only handle the configuration for your feature flags and pass this configuration down to SDKs connecting from your applications. The primary rationale behind this practice is that feature flags often require contextual data for accurate evaluation. This may include user IDs, email addresses, or geographical locations that influence whether a flag should be toggled on or off. Safeguarding this sensitive information from external exposure is paramount. This information may include Personally Identifiable Information (PII), which must remain confined within the boundaries of your application, following the data security principle of least privilege (PoLP). -![feature-flag-server-side-evaluation](https://github.com/Unleash/unleash/assets/87366358/6ca24aea-26fb-481d-92ff-a9af2729cb83) +
For client-side applications where the code resides on the user's machine, such as in the browser or on mobile devices, you’ll want to take a different approach. You can’t evaluate on the client side because it raises significant security concerns by exposing potentially sensitive information such as API keys, flag data, and flag configurations. Placing these critical elements on the client side increases the risk of unauthorized access, tampering, or data breaches. -Instead of performing client-side evaluation, a more secure and maintainable approach is to conduct feature flag evaluation within a self-hosted environment. Doing so can safeguard sensitive elements like API keys and flag configurations from potential client-side exposure. This strategy involves a server-side evaluation of feature flags, where the server makes decisions based on user and application parameters and then securely passes down the evaluated results to the frontend without any configuration leaking. +Instead of performing client-side evaluation, a more secure and maintainable approach is to conduct feature flag evaluation within a self-hosted environment. Doing so can safeguard sensitive elements like API keys and flag configurations from potential client-side exposure. This strategy involves a server-side evaluation of feature flags, where the server makes decisions based on user and application parameters and then securely passes down the evaluated results to the frontend without any configuration leaking. -![feature-flag-architecture-client-side](https://github.com/Unleash/unleash/assets/87366358/28240019-ea3c-4ae6-a6da-60ad9079dc54) +
-Here’s how you can architect your solution to minimize PII or configuration leakage: +Here’s how you can architect your solution to minimize PII or configuration leakage: 1. **Server-Side Components**: diff --git a/website/docs/topics/feature-flags/runtime-control.md b/website/docs/topics/feature-flags/runtime-control.md index e95747a81c..ce9d1b73a4 100644 --- a/website/docs/topics/feature-flags/runtime-control.md +++ b/website/docs/topics/feature-flags/runtime-control.md @@ -2,11 +2,13 @@ title: 1. Enable run-time control. Control flags dynamically, not using config files. --- +import Figure from '@site/src/components/Figure/Figure.tsx' + A scalable feature management system evaluates flags at runtime. Flags are dynamic, not static. If you need to restart your application to turn on a flag, you are using configuration, not feature flags. A large-scale feature flag system that enables runtime control should have at minimum the following components: -**1. Feature Flag Control Service**: Use a centralized feature flag service that acts as the control plane for your feature flags. This service will handle flag configuration. The scope of this service should reflect the boundaries of your organization. +**1. Feature Flag Control Service**: Use a centralized feature flag service that acts as the control plane for your feature flags. This service will handle flag configuration. The scope of this service should reflect the boundaries of your organization. Independent business units or product lines should potentially have their own instances, while business units or product lines that work closely together should most likely use the same instance in order to facilitate collaboration. This will always be a contextual decision based on your organization and how you organize the work, but keep in mind that you’d like to keep the management of the flags as simple as possible to avoid the complexity of cross-instance synchronization of feature flag configuration. @@ -14,10 +16,10 @@ Independent business units or product lines should potentially have their own in **3. API Layer**: Develop an API layer that exposes endpoints for your application to interact with the Feature Flag Control Service. This API should allow your application to request feature flag configurations. -**4. Feature Flag SDK**: Build or integrate a feature flag SDK into your application. This SDK should provide an easy-to-use interface for fetching flag configurations and evaluating feature flags at runtime. When evaluating feature flags in your application, the call to the SDK should query the local cache, and the SDK should ask the central service for updates in the background. +**4. Feature Flag SDK**: Build or integrate a feature flag SDK into your application. This SDK should provide an easy-to-use interface for fetching flag configurations and evaluating feature flags at runtime. When evaluating feature flags in your application, the call to the SDK should query the local cache, and the SDK should ask the central service for updates in the background. Build SDK bindings for each relevant language in your organization. Make sure that the SDKs uphold a standard contract governed by a set of feature flag client specifications that documents what functionality each SDK should support. -![feature-flag-scalable-architecture](https://github.com/Unleash/unleash/assets/87366358/e0ac76e0-992c-49ef-80be-70d2971ed937) +
**5. Continuously Updated**: Implement update mechanisms in your application so that changes to feature flag configurations are reflected without requiring application restarts or redeployments. The SDK should handle subscriptions or polling to the feature flag service for updates. diff --git a/website/docs/topics/feature-flags/scale-horizontally.md b/website/docs/topics/feature-flags/scale-horizontally.md index 7262f2dde8..87ee74efd1 100644 --- a/website/docs/topics/feature-flags/scale-horizontally.md +++ b/website/docs/topics/feature-flags/scale-horizontally.md @@ -2,9 +2,11 @@ title: 4. Scale Horizontally. Decouple reading and writing flags. --- +import Figure from '@site/src/components/Figure/Figure.tsx' + Separating the reading and writing of feature flags into distinct APIs is a critical architectural decision for building a scalable and efficient feature flag system, particularly when considering horizontal scaling. This separation provides several benefits: -![feature-flag-horizontal-scaling](https://github.com/Unleash/unleash/assets/87366358/92135dea-917a-45c8-87e4-515b2a48daa9) +
1. **Horizontal Scaling**: diff --git a/website/static/img/feature-flag-architecture-client-side.png b/website/static/img/feature-flag-architecture-client-side.png new file mode 100644 index 0000000000..d9743ef1e4 Binary files /dev/null and b/website/static/img/feature-flag-architecture-client-side.png differ diff --git a/website/static/img/feature-flag-horizontal-scaling.png b/website/static/img/feature-flag-horizontal-scaling.png new file mode 100644 index 0000000000..5329e42137 Binary files /dev/null and b/website/static/img/feature-flag-horizontal-scaling.png differ diff --git a/website/static/img/feature-flag-scalable-architecture.png b/website/static/img/feature-flag-scalable-architecture.png new file mode 100644 index 0000000000..1b99def651 Binary files /dev/null and b/website/static/img/feature-flag-scalable-architecture.png differ diff --git a/website/static/img/feature-flag-server-side-evaluation.png b/website/static/img/feature-flag-server-side-evaluation.png new file mode 100644 index 0000000000..2b28571d58 Binary files /dev/null and b/website/static/img/feature-flag-server-side-evaluation.png differ