diff --git a/website/docs/feature-flag-tutorials/ios/implementing-feature-flags-ios.md b/website/docs/feature-flag-tutorials/ios/implementing-feature-flags-ios.md index e5a8466eab1a..50853721244a 100644 --- a/website/docs/feature-flag-tutorials/ios/implementing-feature-flags-ios.md +++ b/website/docs/feature-flag-tutorials/ios/implementing-feature-flags-ios.md @@ -39,7 +39,7 @@ a. Limit PII (personally identifiable information) leakage from the end-user dev b. Avoid leakage of configuration information from the central feature flag control service to end-user devices. -Solving both means you need to avoid evaluating feature flags on the user's machine due to security risks like exposing API keys and flag data. Instead, send application context (e.g. username, location, etc) to your feature flag evaluation service to evaluate the results. These results (and only these results) should be stored in the client-side application memory. By keeping the evaluated results for a specific context in memory, you avoid network roundtrips every time your application needs to check the status of a feature flag. This method prevents unauthorized access and data breaches by [keeping configurations and PII secure](/topics/feature-flags/feature-flag-best-practices#2-protect-pii-by-evaluating-flags-server-side). +Solving both means you need to avoid evaluating feature flags on the user's machine due to security risks like exposing API keys and flag data. Instead, send application context (e.g. username, location, etc) to your feature flag evaluation service to evaluate the results. These results (and only these results) should be stored in the client-side application memory. By keeping the evaluated results for a specific context in memory, you avoid network roundtrips every time your application needs to check the status of a feature flag. This method prevents unauthorized access and data breaches by [keeping configurations and PII secure](/topics/feature-flags/feature-flag-best-practices#6-protect-pii-by-evaluating-flags-server-side). ![Keep configurations and PII secure image](/img/react-tutorial-pii-diagram.png) diff --git a/website/docs/feature-flag-tutorials/react/implementing-feature-flags.mdx b/website/docs/feature-flag-tutorials/react/implementing-feature-flags.mdx index 5e1adf687a3c..57cacfbaa0f8 100644 --- a/website/docs/feature-flag-tutorials/react/implementing-feature-flags.mdx +++ b/website/docs/feature-flag-tutorials/react/implementing-feature-flags.mdx @@ -50,7 +50,7 @@ a. Limit PII (personally identifiable information) leakage from the end-user dev b. Avoid leakage of configuration information from the central feature flag control service to end-user devices. -Solving both means you need to avoid evaluating feature flags on the user's machine due to security risks like exposing API keys and flag data. Instead, send application context (e.g. username, location, etc) to your feature flag evaluation service to evaluate the results. These results (and only these results) should be stored in the client-side application memory. By keeping the evaluated results for a specific context in memory, you avoid network roundtrips every time your application needs to check the status of a feature flag. This method prevents unauthorized access and data breaches by [keeping configurations and PII secure](/topics/feature-flags/feature-flag-best-practices#2-protect-pii-by-evaluating-flags-server-side). +Solving both means you need to avoid evaluating feature flags on the user's machine due to security risks like exposing API keys and flag data. Instead, send application context (e.g. username, location, etc) to your feature flag evaluation service to evaluate the results. These results (and only these results) should be stored in the client-side application memory. By keeping the evaluated results for a specific context in memory, you avoid network roundtrips every time your application needs to check the status of a feature flag. This method prevents unauthorized access and data breaches by [keeping configurations and PII secure](/topics/feature-flags/feature-flag-best-practices#6-protect-pii-by-evaluating-flags-server-side). ![Keep configurations and PII secure image](/img/react-tutorial-pii-diagram.png) diff --git a/website/docs/reference/terraform.mdx b/website/docs/reference/terraform.mdx index 8f2411565898..efe6e4007ec9 100644 --- a/website/docs/reference/terraform.mdx +++ b/website/docs/reference/terraform.mdx @@ -14,7 +14,7 @@ description: "Set up and configure your Unleash instance using infastructure as The [Unleash Terraform provider](https://github.com/Unleash/terraform-provider-unleash) enables you to manage and configure Unleash programmatically, leveraging infrastructure as code (IaC) for automated and scalable configuration. -This provider is designed to help you with the **initial setup and configuration** of an instance. The provider does not support managing feature flags through Terraform. Since most [feature flags are short-lived](/topics/feature-flags/feature-flag-best-practices#7-make-flags-short-lived), we recommend managing them through the Unleash Admin UI. +This provider is designed to help you with the **initial setup and configuration** of an instance. The provider does not support managing feature flags through Terraform. Since most [feature flags are short-lived](/topics/feature-flags/feature-flag-best-practices#3-make-flags-short-lived), we recommend managing them through the Unleash Admin UI. For a detailed video tutorial, check out [Managing Unleash through Terraform](https://www.youtube.com/watch?v=B4OIBC1u1ns). For more examples of specific resources and data sources, visit the [Terraform registry](https://registry.terraform.io/providers/Unleash/unleash/latest/docs/data-sources/permission). diff --git a/website/docs/topics/feature-flags/best-practices-using-feature-flags-at-scale.mdx b/website/docs/topics/feature-flags/best-practices-using-feature-flags-at-scale.mdx index 29c766fc13f0..2aa6eed13049 100644 --- a/website/docs/topics/feature-flags/best-practices-using-feature-flags-at-scale.mdx +++ b/website/docs/topics/feature-flags/best-practices-using-feature-flags-at-scale.mdx @@ -69,7 +69,7 @@ Modern applications are composed of multiple services with many complex dependen Just because a user might need to interact with a flag does not mean you should display it by default when it is outside your main organizational parameters. However, all flags should be easily searchable. When a user finds one, they should be able to inspect its configuration and ownership so that they might request additional permissions or [submit change requests for approval](#6-implement-flag-approval-workflows-early). -This is why feature flag systems should be [open by default](./feature-flag-best-practices#9-choose-open-by-default). There are valid use cases for excluding flags from global search. For example, a public company in the middle of an acquisition where exposing flags related to the website or app changes might breach regulatory guidelines. Your feature flag system should accommodate these private projects; however, they should be the exception, not the rule. +This is why feature flag systems should be [open by default](./feature-flag-best-practices#5-choose-open-by-default). There are valid use cases for excluding flags from global search. For example, a public company in the middle of an acquisition where exposing flags related to the website or app changes might breach regulatory guidelines. Your feature flag system should accommodate these private projects; however, they should be the exception, not the rule. ### 3. Design for flag permissions to change over time. @@ -193,7 +193,7 @@ Here are a few examples of functionality managed by feature flags and where you When building new (often complex) features for users, systems require changes across multiple parts – modules within an application or services in a microservices architecture. While it's tempting to use a single feature flag to control all these changes and evaluate it locally in each module, we recommend against it for a few reasons: - Unpredictable Timing: User requests flow through the system and touch different parts as they progress. Between each invocation, time passes. Even with perfectly synchronized feature flags, requests will hit different system parts at slightly different times. This means the flag state could change between evaluations, leading to inconsistent behavior for the user. -- Laws of distributed computing: Particularly in distributed systems, we cannot assume all parts of the system are perfectly synchronized, as networks are unreliable and can experience transient errors at any time. Feature flag systems generally [prefer availability over consistency](./feature-flag-best-practices#6-prioritize-availability-over-consistency). By only evaluating a feature flag once, we guarantee a consistent experience for our users. +- Laws of distributed computing: Particularly in distributed systems, we cannot assume all parts of the system are perfectly synchronized, as networks are unreliable and can experience transient errors at any time. Feature flag systems generally [prefer availability over consistency](./feature-flag-best-practices#2-prioritize-availability-over-consistency). By only evaluating a feature flag once, we guarantee a consistent experience for our users. - Violates Single Responsibility: Using the same flag in multiple locations spreads feature control logic throughout your codebase, violating the single-responsibility principle. We find that companies are usually more successful when using feature flags when they can protect new complex features with a single flag evaluated only once per user request. This approach ensures consistent behavior and simplifies long-term code maintainability. @@ -246,7 +246,7 @@ To keep complexity down, we generally advise not to have complex targeting rules Both feature flags and configuration settings control an application’s behavior. However, it's crucial to distinguish between feature flagging systems and configuration management systems and use each for its intended purpose. Otherwise, you risk management nightmares and security vulnerabilities -Feature flags are intended for dynamic and temporary use, giving you [runtime control](./feature-flag-best-practices#1-enable-runtime-control) to enable or disable functionality in a live environment. This flexibility supports [short-lived experiments](./feature-flag-best-practices#7-make-flags-short-lived), such as A/B testing or gradual rollouts, instead of relying on configuration settings that require an application redeploy to take effect. Despite the ease of turning off and on features or functionality with feature flags, they should not be repurposed for managing configuration. +Feature flags are intended for dynamic and temporary use, giving you [runtime control](./feature-flag-best-practices#1-enable-runtime-control) to enable or disable functionality in a live environment. This flexibility supports [short-lived experiments](./feature-flag-best-practices#3-make-flags-short-lived), such as A/B testing or gradual rollouts, instead of relying on configuration settings that require an application redeploy to take effect. Despite the ease of turning off and on features or functionality with feature flags, they should not be repurposed for managing configuration. A dedicated config management system should manage long-term configuration settings. These systems are designed to handle sensitive information such as API keys and access credentials securely, unlike feature flag systems, which typically do not encrypt flag states. Misusing feature flags for configuration can lead to security risks and management complexities. diff --git a/website/docs/topics/feature-flags/feature-flag-best-practices.mdx b/website/docs/topics/feature-flags/feature-flag-best-practices.mdx index 6201dcd0359b..f46885b88723 100644 --- a/website/docs/topics/feature-flags/feature-flag-best-practices.mdx +++ b/website/docs/topics/feature-flags/feature-flag-best-practices.mdx @@ -1,27 +1,27 @@ --- -title: "11 Principles for building and scaling feature flag systems" +title: "11 principles for building and scaling feature flag systems" toc_max_heading_level: 2 --- -import Figure from '@site/src/components/Figure/Figure.tsx' +import VideoContent from '@site/src/components/VideoContent.jsx'; Feature flags, sometimes called feature toggles or feature switches, are a powerful software development technique that allows engineering teams to decouple the release of new functionality from software deployments. -With feature flags, developers can turn specific features or code segments on or off at runtime without needing a code deployment or rollback. Organizations that adopt feature flags see improvements in key DevOps metrics like lead time to changes, mean time to recovery, deployment frequency, and change failure rate. +With feature flags, developers can turn specific features or code segments on or off at runtime without needing a code deployment or rollback. Organizations that adopt feature flags see improvements in key [DevOps metrics](https://www.getunleash.io/blog/dora-metrics-in-2023-5-ways-to-measure-devops-performance) like lead time to changes, mean time to recovery, deployment frequency, and change failure rate. At Unleash, we've defined 11 principles for building a large-scale feature flag system. These principles have their roots in distributed systems design and focus on security, privacy, and scalability—critical needs for enterprise systems. By following these principles, you can create a feature flag system that's reliable, easy to maintain, and capable of handling heavy loads. These principles are: 1. [Enable runtime control](#1-enable-runtime-control) -2. [Protect PII by evaluating flags server-side](#2-protect-pii-by-evaluating-flags-server-side) -3. [Evaluate flags as close to the user as possible](#3-evaluate-flags-as-close-to-the-user-as-possible) -4. [Scale horizontally by decoupling reads and writes](#4-scale-horizontally-by-decoupling-reads-and-writes) -5. [Limit feature flag payload](#5-limit-feature-flag-payload) -6. [Prioritize availability over consistency](#6-prioritize-availability-over-consistency) -7. [Make flags short-lived](#7-make-flags-short-lived) -8. [Ensure unique flag names](#8-ensure-unique-flag-names) -9. [Choose open by default](#9-choose-open-by-default) +2. [Prioritize availability over consistency](#2-prioritize-availability-over-consistency) +3. [Make flags short-lived](#3-make-flags-short-lived) +4. [Ensure unique flag names](#4-ensure-unique-flag-names) +5. [Choose open by default](#5-choose-open-by-default) +6. [Protect PII by evaluating flags server-side](#6-protect-pii-by-evaluating-flags-server-side) +7. [Evaluate flags as close to the user as possible](#7-evaluate-flags-as-close-to-the-user-as-possible) +8. [Scale horizontally by decoupling reads and writes](#8-scale-horizontally-by-decoupling-reads-and-writes) +9. [Limit feature flag payload](#9-limit-feature-flag-payload) 10. [Prioritize consistent user experience](#10-prioritize-consistent-user-experience) 11. [Optimize for developer experience](#11-optimize-for-developer-experience) @@ -31,7 +31,7 @@ Let's dive deeper into each principle. 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, that's configuration, not a feature flag. -A large-scale feature flag system that enables runtime control should have, at minimum, the following components: a service to manage feature flags, a database or data store, an API layer, a feature flag SDK, and a continuous update mechanism. +A large-scale feature flag system that enables [runtime control](https://www.getunleash.io/blog/so-what-exactly-is-runtime-control) should have, at minimum, the following components: a service to manage feature flags, a database or data store, an API layer, a feature flag SDK, and a continuous update mechanism. Let's break down these components. @@ -41,9 +41,99 @@ Let's break down these components. - **Feature flag SDK**: An easy-to-use interface for fetching flag configurations and evaluating feature flags at runtime. When considering 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. - **Continuous update mechanism**: An update mechanism that enables dynamic updates to feature flag configurations without requiring application restarts or redeployments. The SDK should handle subscriptions or polling to the _Feature Flag Control Service_ for updates. -
+![The SDK holds an in-memory feature flag configuration cache which is continuously synced with the Feature Flag Control Service. You can then use the SDK to check the state of feature flags in your application.](/img/feature-flag-scalable-architecture.png) -## 2. Protect PII by evaluating flags server-side +## 2. Prioritize availability over consistency + +Your application shouldn't have any dependency on the availability of your feature flag system. Robust feature flag systems avoid relying on real-time flag evaluations because the unavailability of the feature flag system will cause application downtime, outages, degraded performance, or even a complete failure of your application. + +If the feature flag system fails, your application should continue running smoothly. Feature flagging should degrade gracefully, preventing any unexpected behavior or disruptions for users. + +You can implement the following strategies to achieve a resilient architecture: + +- **Bootstrap SDKs with data**: Feature flagging SDKs should work with locally cached data, even when the network connection to the _Feature Flag Control Service_ is unavailable, using the last known configuration or defaults to ensure uninterrupted functionality. +- **Use local cache**: Maintaining a local cache of feature flag configurations helps reduce network round trips and dependency on external services. The local cache can periodically synchronize with the central _Feature Flag Control Service_ when it's available. +- **Evaluate feature flags locally**: Whenever possible, the SDKs or application components should evaluate feature flags locally without relying on external services, ensuring uninterrupted feature flag evaluations even if the feature flagging service is down. +- **Prioritize availability over consistency**: In line with the [CAP theorem](https://www.ibm.com/topics/cap-theorem), design for availability over strict consistency. In the face of network partitions or downtime of external services, your application should favor maintaining its availability rather than enforcing perfectly consistent feature flag configuration caches. Eventually consistent systems can tolerate temporary inconsistencies in flag evaluations without compromising availability. + +## 3. Make flags short-lived + +The most common use case for feature flags is to manage the [rollout](https://www.getunleash.io/feature-flag-use-cases-progressive-or-gradual-rollouts) of new functionality. Once a rollout is complete, you should remove the feature flag from your code and archive it. Remove any old code paths that the new functionality replaces. + +Avoid using feature flags for static application configuration. Application configuration should be consistent, long-lived, and loaded during application startup. In contrast, feature flags should be short-lived, dynamic, and updated at runtime. They prioritize availability over consistency and can be modified frequently. + + + + + + + + + + + + + + + + + + + + + +
Configuration systemFeature flag system
Lifetime and runtime behaviorLong-lived, static during runtimeShort-lived, changes during runtime
Example use cases +
    +
  • Database or server credentials
    • +
  • Server port
    • +
  • CORS headers
    • +
  • API base URL
    • +
+ 		+
    +
  • A/B or multivariate testing
    • +
  • Gradual rollout
    • +
  • Permission flags (i.e., beta testing programs)
    • +
  • Operational testing in production
    • +
+
+ +To succeed with feature flags in a large organization, [follow these strategies](https://docs.getunleash.io/topics/feature-flags/best-practices-using-feature-flags-at-scale): + +- **Set flag expiration dates**: Assign expiration dates to feature flags to track which flags are no longer needed. A good feature flag management tool will alert you to expired flags, making it easier to maintain your codebase. +- **Treat feature flags like technical debt**: Incorporate tasks to remove outdated feature flags into your sprint or project planning, just as you would with technical debt. Feature flags add complexity to your code by introducing multiple code paths that need context and maintenance. If you don't clean up feature flags in a timely manner, you risk losing the context as time passes or personnel changes, making them harder to manage or remove. +- **Archive old flags**: When feature flags are no longer in use, archive them after removing them from the codebase. This archive serves as an important audit log of feature flags and allows you to revive flags if you need to restore an older version of your application. + +While most feature flags should be short-lived, there are valid exceptions for long-lived flags, including: +- **Kill switches**: [Kill switches](https://www.getunleash.io/blog/kill-switches-best-practice) act as inverted feature flags, allowing you to gracefully disable parts of a system with known weak spots. +- **Internal flags**: Internal flags to enable additional debugging, tracing, and metrics at runtime, which are too costly to run continuously. Engineers can enable these flags while debugging issues. + +## 4. Ensure unique flag names + +Ensure that all flags within the same _Feature Flag Control Service_ have unique names across your entire system. [Unique naming](https://docs.getunleash.io/topics/feature-flags/best-practices-using-feature-flags-at-scale#13-never-reuse-feature-flag-names) prevents the reuse of old flag names, reducing the risk of accidentally re-enabling outdated features with the same name. + +![Creating a feature flag with a unique name referencing the project and related jira ticket.](/img/feature-flag-unique-name.png) + +Unique naming has the following advantages: +- **Flexibility over time**: Large enterprise systems are not static. Monoliths may split into microservices, microservices may merge, and applications change responsibility. Unique flag naming across your organization means that you can reorganize your flags to match the changing needs of your organization. +- **Fewer conflicts**: If two applications use the same feature flag name, it can become difficult to identify which flag controls which application. Even with separate namespaces, you risk toggling the wrong flag, leading to unexpected consequences. +- **Easier flag management**: Unique names make it simpler to track and identify feature flags. Searching across codebases becomes more straightforward, and it's easier to understand a flag's purpose and usage. +- **Improved collaboration**: A feature flag with a unique name in the organization simplifies collaboration across teams, products, and applications, ensuring that everyone refers to the same feature. + +## 5. Choose open by default + +Making feature flag systems open by default enables engineers, product owners, and support teams to collaborate effectively and make informed decisions. Open access encourages productive discussions about feature releases, experiments, and their impact on the user experience. + +Access control and visibility are also key considerations for security and compliance. Tracking and auditing feature flag changes help maintain data integrity and meet regulatory requirements. While open access is key, it's equally important to integrate with corporate access controls, such as SSO, to ensure security. In some cases, additional controls like feature flag approvals using the [four-eyes principle](/reference/change-requests) are necessary for critical changes. + +![Preview of a change request to enable gradual rollout in production.](/img/feature-flag-change-requests-preview.png) + +For open collaboration, consider providing the following: +- **Access to the codebase**: Engineers need direct access to the codebase that contains the feature flags. This allows them to quickly diagnose and fix issues, minimizing downtime and performance problems. +- **Access to configuration**: Engineers, product owners, and even technical support should be able to view feature flag configuration. This transparency provides insights into which features are currently active, what conditions trigger them, and how they impact the application's behavior. Product owners can also make real-time decisions on feature rollouts or adjustments without relying solely on engineering resources. +- **Access to analytics**: Both engineers and product owners should be able to correlate feature flag changes with production metrics. This helps assess how flags impact user behavior, performance, and system health, enabling data-driven decisions for feature rollouts, optimizations, or rollbacks. + +## 6. Protect PII by evaluating flags server-side Feature flags often require contextual data for accurate evaluation, which could include sensitive information such as user IDs, email addresses, or geographical locations. To safeguard this data, follow the data security [principle of least privilege (PoLP)](https://www.cyberark.com/what-is/least-privilege), ensuring that all [Personally Identifiable Information (PII)](https://www.investopedia.com/terms/p/personally-identifiable-information-pii.asp) remains confined to your application. @@ -51,15 +141,13 @@ To implement the principle of least privilege, ensure that your _Feature Flag Co Let's look at an example where feature flag evaluation happens inside the server-side application. This is where all the contextual application data lives. The flag configuration—all the information needed to evaluate the flags—is fetched from the _Feature Flag Control Service_. -
+![Evaluating flags on the server side without exposing sensitive information.](/img/feature-flag-server-side-evaluation.png) Client-side applications where the code resides on the user's machine in browsers or mobile devices, require a different approach. You can't evaluate flags 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 evaluate feature flags 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. -
- -Here's how you can architect your solution to protect PII and flag configuration data: +![In client-side setups, perform the feature flag evaluation on the server side. Connected client-side applications receive only evaluated feature flags to avoid leaking configuration.](/img/feature-flag-architecture-client-side.png) ### Server-side components @@ -71,11 +159,11 @@ In [Principle 1](#1-enable-runtime-control), we proposed a set of architectural For client-side feature flags, SDKs should send the context to an evaluation server and receive the evaluated results. The evaluated results are then cached in memory in the client-side application, allowing quick lookups without additional network overhead. This provides the performance benefits of local evaluation while minimizing the exposure of sensitive data. -This approach enhances privacy by minimizing the amount of sensitive data sent to the _Feature Flag Control Service_, reducing the risk of data exposure and potential security threats. + -## 3. Evaluate flags as close to the user as possible +## 7. Evaluate flags as close to the user as possible -For optimal performance, you should evaluate feature flags as close to your users as possible. Building on the server-side evaluation approach from [Principle 2](#2-protect-pii-by-evaluating-flags-server-side), let's look at how evaluating flags locally can bring key benefits in terms of performance, cost, and reliability: +For optimal performance, you should evaluate feature flags as close to your users as possible. Building on the server-side evaluation approach from [Principle 2](#6-protect-pii-by-evaluating-flags-server-side), let's look at how evaluating flags locally can bring key benefits in terms of performance, cost, and reliability: - **Reduced latency**: Network roundtrips introduce latency, slowing your application's response time. Local evaluation eliminates the need for these roundtrips, resulting in faster feature flag decisions. This makes your application more responsive thereby improving the user experience. - **Offline functionality**: Many applications need to function offline or in low-connectivity environments. Local evaluation ensures feature flags are still functional, even without an active network connection. This is especially important for mobile apps or services in remote locations. @@ -85,11 +173,11 @@ For optimal performance, you should evaluate feature flags as close to your user In summary, this principle emphasizes optimizing performance while protecting end-user privacy by evaluating feature flags as close to the end user as possible. This also leads to a highly available feature flag system that scales with your applications. -## 4. Scale horizontally by decoupling reads and writes +## 8. Scale horizontally by decoupling reads and writes When designing a scalable feature flag system, one of the most effective strategies is to separate read and write operations into distinct APIs. This architectural decision not only allows you to scale each component independently but also provides better performance, reliability, and control. -
+![Separating the reading and writing of the database allows you to horizontally scale out the read APIs without scaling the write APIs.](/img/feature-flag-horizontal-scaling.png) By decoupling read and write operations, you gain the flexibility to scale horizontally based on the unique demands of your application. For example, if read traffic increases, you can add more servers or containers to handle the load without needing to scale the write operations. @@ -100,7 +188,7 @@ The benefits of decoupling read and write operations extend beyond just scalabil - **Flexibility and maintenance**: Updates to one API won't directly impact the other, reducing the risk of unintended consequences. This separation of concerns allows development teams to work on each API separately, facilitating parallel development and deployment cycles. - **Distributed traffic**: You can tailor load-balancing strategies to the specific needs of the read and write APIs. You can distribute traffic and resources accordingly to optimize performance and ensure that neither API becomes a bottleneck under heavy load. -## 5. Limit feature flag payload +## 9. Limit feature flag payload Minimizing the size of feature flag payloads is a critical aspect of maintaining the efficiency and performance of a feature flag system. Payload size can vary based on targeting rule complexity. For example, targeting based on individual user IDs may work with small user bases but becomes inefficient as the user base grows. @@ -118,56 +206,6 @@ Keeping the feature flag payload small results in: For more insights into reducing payload size, visit our [Best practices for using feature flags at scale](/topics/feature-flags/best-practices-using-feature-flags-at-scale#14-avoid-giant-feature-flag-targeting-lists) guide. -## 6. Prioritize availability over consistency - -Your application shouldn't have any dependency on the availability of your feature flag system. Robust feature flag systems avoid relying on real-time flag evaluations because the unavailability of the feature flag system will cause application downtime, outages, degraded performance, or even a complete failure of your application. - -If the feature flag system fails, your application should continue running smoothly. Feature flagging should degrade gracefully, preventing any unexpected behavior or disruptions for users. - -You can implement the following strategies to achieve a resilient architecture: - -- **Bootstrap SDKs with data**: Feature flagging SDKs should work with locally cached data, even when the network connection to the _Feature Flag Control Service_ is unavailable, using the last known configuration or defaults to ensure uninterrupted functionality. -- **Use local cache**: Maintaining a local cache of feature flag configurations helps reduce network round trips and dependency on external services. The local cache can periodically synchronize with the central _Feature Flag Control Service_ when it's available. This approach minimizes the impact of network failures or service downtime on your application. -- **Evaluate feature flags locally**: Whenever possible, the SDKs or application components should evaluate feature flags locally without relying on external services, ensuring uninterrupted feature flag evaluations even if the feature flagging service is down. -- **Prioritize availability over consistency**: In line with the [CAP theorem](https://www.ibm.com/topics/cap-theorem), design for availability over strict consistency. In the face of network partitions or downtime of external services, your application should favor maintaining its availability rather than enforcing perfectly consistent feature flag configuration caches. Eventually consistent systems can tolerate temporary inconsistencies in flag evaluations without compromising availability. - -## 7. Make flags short-lived - -The most common use case for feature flags is to manage the rollout of new functionality. Once a rollout is complete, you should remove the feature flag from your code and archive it. Remove any old code paths that the new functionality replaces. - -Avoid using feature flags for static application configuration. Application configuration should be consistent, long-lived, and loaded during application startup. In contrast, feature flags are intended to be short-lived, dynamic, and updated at runtime. They prioritize availability over consistency and are designed to be modified frequently. - -To succeed with feature flags in a large organization, follow these strategies: - -- **Set flag expiration dates**: Assign expiration dates to feature flags to track which flags are no longer needed. A good feature flag management tool will alert you to expired flags, making it easier to maintain your codebase. -- **Treat feature flags like technical debt**: Incorporate tasks to remove outdated feature flags into your sprint or project planning, just as you would with technical debt. Feature flags add complexity to your code by introducing multiple code paths that need context and maintenance. If you don't clean up feature flags in a timely manner, you risk losing the context as time passes or personnel changes, making them harder to manage or remove. -- **Archive old flags**: When feature flags are no longer in use, archive them after removing them from the codebase. This archive serves as an important audit log of feature flags and allows you to revive flags if you need to restore an older version of your application. - -While most feature flags should be short-lived, there are valid exceptions for long-lived flags, including: -- **Kill switches**: These act as inverted feature flags, allowing you to gracefully disable parts of a system with known weak spots. -- **Internal flags**: Used to enable additional debugging, tracing, and metrics at runtime, which are too costly to run continuously. Engineers can enable these flags while debugging issues. - -## 8. Ensure unique flag names - -Ensure that all flags within the same _Feature Flag Control Service_ have unique names across your entire system. Unique naming prevents the reuse of old flag names, reducing the risk of accidentally re-enabling outdated features with the same name. - -Unique naming has the following advantages: -- **Flexibility over time**: Large enterprise systems are not static. Monoliths may split into microservices, microservices may merge, and applications change responsibility. Unique flag naming across your organization means that you can reorganize your flags to match the changing needs of your organization. -- **Fewer conflicts**: If two applications use the same feature flag name, it can become difficult to identify which flag controls which application. Even with separate namespaces, you risk toggling the wrong flag, leading to unexpected consequences. -- **Easier flag management**: Unique names make it simpler to track and identify feature flags. Searching across codebases becomes more straightforward, and it's easier to understand a flag's purpose and where it's used. -- **Improved collaboration**: A feature flag with a unique name in the organization simplifies collaboration across teams, products, and applications, ensuring that everyone refers to the same feature. - -## 9. Choose open by default - -At Unleash, we believe in democratizing feature flag access. Making feature flag systems open by default enables engineers, product owners, and support teams to collaborate effectively and make informed decisions. Open access encourages productive discussions about feature releases, experiments, and their impact on the user experience. - -Access control and visibility are also key considerations for security and compliance. Tracking and auditing feature flag changes help maintain data integrity and meet regulatory requirements. While open access is key, it's equally important to integrate with corporate access controls, such as SSO, to ensure security. In some cases, additional controls like feature flag approvals using the [four-eyes principle](/reference/change-requests) are necessary for critical changes. - -For open collaboration, consider providing the following: -- **Access to the codebase**: Engineers need direct access to the codebase where feature flags are implemented. This allows them to quickly diagnose and fix issues, minimizing downtime and performance problems. -- **Access to configuration**: Engineers, product owners, and even technical support should be able to view feature flag configuration. This transparency provides insights into which features are currently active, what conditions trigger them, and how they impact the application's behavior. Product owners can also make real-time decisions on feature rollouts or adjustments without relying solely on engineering resources. -- **Access to analytics**: Both engineers and product owners should be able to correlate feature flag changes with production metrics. This helps assess how flags impact user behavior, performance, and system health, enabling data-driven decisions for feature rollouts, optimizations, or rollbacks. - ## 10. Prioritize consistent user experience Feature flagging solutions are indispensable tools in modern software development, enabling teams to manage feature releases and experiment with new functionality. However, one aspect that is absolutely non-negotiable in any feature flag solution is the need to ensure a consistent user experience. Feature flagging solutions must prioritize consistency and guarantee the same user experience every time, especially with percentage-based gradual rollouts. @@ -191,4 +229,20 @@ To ensure a good developer experience, you should provide the following: - **Usage metrics**: Provide aggregated insights into feature flag usage, helping developers confirm that everything is working as expected. - **Documentation and training**: Offer clear, comprehensive documentation for the API, UI, and SDKs, with easy-to-follow examples. This simplifies onboarding for new developers and supports continuous training, ensuring the effective use of the feature flagging system. -Thank you for reading. Our motivation for writing these principles is to share what we've learned building a large-scale feature flag solution with other architects and engineers solving similar challenges. Unleash is open-source, and so are these principles. Have something to contribute? [Open a PR](https://github.com/Unleash/unleash/pulls) or [discussion](https://github.com/orgs/Unleash/discussions) on our GitHub. +--- + +## Additional resources + +Thank you for reading. Our motivation for writing these principles is to share what we've learned building a large-scale feature flag solution with other architects and engineers solving similar challenges. Unleash is open-source, and so are these principles. +Have something to contribute? [Open a PR](https://github.com/Unleash/unleash/pulls) or [discussion](https://github.com/orgs/Unleash/discussions) on our GitHub. + +To learn more about Unleash architecture and implementation basics, check out this webinar: + + + + +### Best practices for deploying Unleash at scale + +An introduction to Unleash Edge product and its scaling capabilities: + + diff --git a/website/static/img/feature-flag-change-requests-preview.png b/website/static/img/feature-flag-change-requests-preview.png new file mode 100644 index 000000000000..4da6a9bd479f Binary files /dev/null and b/website/static/img/feature-flag-change-requests-preview.png differ diff --git a/website/static/img/feature-flag-unique-name.png b/website/static/img/feature-flag-unique-name.png new file mode 100644 index 000000000000..87c12aa63bca Binary files /dev/null and b/website/static/img/feature-flag-unique-name.png differ