diff --git a/dictionary-octopus.txt b/dictionary-octopus.txt index 2f897ab313..ccfb6eb6be 100644 --- a/dictionary-octopus.txt +++ b/dictionary-octopus.txt @@ -401,6 +401,7 @@ oldthumbprint oneshot onlylogs onmicrosoft +openfeature openon operationalize outfile @@ -481,6 +482,7 @@ robocopy roboto rocksville rolename +rollouts ROOTDIR rootelement Rootfs diff --git a/src/pages/docs/feature-flags/getting-started.md b/src/pages/docs/feature-flags/getting-started.md new file mode 100644 index 0000000000..1ef15c26bd --- /dev/null +++ b/src/pages/docs/feature-flags/getting-started.md @@ -0,0 +1,167 @@ +--- +layout: src/layouts/Default.astro +pubDate: 2026-11-05 +modDate: 2026-11-05 +title: Getting started with feature flags +sidebarLabel: Getting started +navTitle: Getting started +navSection: Feature Flags +navOrder: 10 +icon: fa-solid fa-play +description: Create an Octopus feature flag, connect your application with OpenFeature, evaluate the flag in code, and turn it on for an environment. +subject: feature flags, OpenFeature, client identifier, getting started, feature flag slug +type: guide +audience: [app-dev, devops-eng, new-user] +image: +imageAlt: +--- + +This page takes you from no feature flags to a flag your application checks at runtime. You'll create a flag in Octopus, connect your application to the Octopus feature flag service, evaluate the flag in code, and turn it on for an environment. + +## Create a feature flag + +A feature flag lives in an Octopus project. Create one for each feature you want to control independently. + +**Before you begin** + +You'll need: + +- An Octopus project that deploys the application you want to add the flag to. +- [VERIFY: the permission required to create feature flags, for example FeatureToggleEdit — needs: confirmation of the permission name shown in the Octopus UI] + +To create a feature flag: + +1. From your project, select **Feature Flags**. +2. Select **Add Feature Flag**. +3. Enter a **Name** for the flag. +4. [VERIFY: the label of the button that creates the flag — needs: confirmation from the Add Feature Flag dialog] + +The flag appears in the project's feature flag list. Octopus generates a slug from the name, which is how your application refers to the flag. + +## Add the Octopus provider to your application + +Your application evaluates flags through the OpenFeature SDK, using the Octopus provider to fetch flag values from the Octopus feature flag service. Do this once per application. + +To add the Octopus provider: + +1. Install the [OpenFeature SDK](https://openfeature.dev/docs/reference/sdks/) for your language. +2. Install the [Octopus provider](/docs/feature-flags/providers) for your language. +3. In your application's startup code, create the Octopus provider with your client identifier and set it as the OpenFeature provider. + +For example, in an ASP.NET application: + +```cs +// Read the client identifier from configuration +var builder = WebApplication.CreateBuilder(args); +var octopusFeatureFlagsClientId = builder.Configuration["FeatureFlags:ClientId"] ?? ""; + +// Create the Octopus provider +var octopusProvider = new OctopusFeatureProvider(new OctopusFeatureConfiguration(octopusFeatureFlagsClientId)); + +// Set Octopus as the OpenFeature provider +await OpenFeature.Api.Instance.SetProviderAsync(octopusProvider); +``` + +Each provider's README covers setup for that language. + +:::div{.warning} +Projects that use feature flag rules need a minimum provider version. See [OpenFeature providers](/docs/feature-flags/providers) for the versions. +::: + +Next, give your application its client identifier during deployment. + +## Supply the client identifier during deployment + +The client identifier is a [JWT](https://jwt.io/introduction) that names the project, environment, and tenant (if applicable) your application belongs to. Octopus provides it in the `Octopus.FeatureFlags.ClientIdentifier` variable, so you can inject the right value for each environment and tenant as you deploy. + +**Before you begin** + +You'll need: + +- A deployment step that can substitute Octopus variables into your application's configuration, such as [structured configuration variables](/docs/projects/steps/configuration-features/structured-configuration-variables-feature) or [substitute variables in templates](/docs/projects/steps/configuration-features/substitute-variables-in-templates). + +To supply the client identifier during deployment: + +1. In your application's configuration file, add a setting for the client identifier with the value `#{Octopus.FeatureFlags.ClientIdentifier}`. +2. In your deployment process, turn on variable substitution for that configuration file. +3. Deploy a release to the environment. + +For example, an `appsettings.json` file could contain: + +```json +{ + "FeatureFlags": { + "ClientId": "#{Octopus.FeatureFlags.ClientIdentifier}" + } +} +``` + +The deployed configuration file contains a client identifier for the environment, and tenant if applicable, that you deployed to. + +:::div{.hint} +Earlier versions of these docs used the variable `Octopus.FeatureToggles.ClientIdentifier`. It still works as a deprecated alias of `Octopus.FeatureFlags.ClientIdentifier`. +::: + +## Get a client identifier for an application Octopus doesn't deploy + +If Octopus doesn't deploy your application, or you can't inject the client identifier during deployment, you can generate one in the Octopus Web Portal and add it to your configuration yourself. + +To get a client identifier: + +1. From your project, select **Feature Flags**. +2. Open the overflow menu and select **Preview Client Identifiers**. +3. Select the **Environment**, and the **Tenant** if your project uses tenants. +4. Copy the client identifier into your application's configuration. + +![Client identifier preview menu item](/docs/img/feature-flags/client-identifier-preview-menu-item.png) + +:::div{.warning} +A generated client identifier doesn't carry the version of a deployed release, so flags that use a [Version is at least](/docs/feature-flags/rules#rule-conditions) condition won't match for applications that use it. +::: + +## Evaluate a feature flag + +Your application asks OpenFeature for a flag's value by its slug wherever it needs to decide whether to show the feature. + +To evaluate a feature flag: + +1. From your project, select **Feature Flags**, then select the flag. +2. Copy the flag's **Slug**. +3. In your application, call the OpenFeature client with the slug and a default value. + +For example, to evaluate the flag with the slug `dark-mode` in C#: + +```cs +var featureClient = OpenFeature.Api.Instance.GetClient(); +var darkModeEnabled = await featureClient.GetBooleanValueAsync("dark-mode", false); +``` + +The second argument is the default value your code uses if it can't reach the Octopus feature flag service. To learn how it differs from the default value you set in Octopus, see [Default values](/docs/feature-flags/how-evaluation-works#default-values). + +## Turn on a feature flag for an environment + +A new flag returns its default value everywhere until you add an environment to it. Adding an environment gives the flag a switch for that environment, which turns the flag on for everyone there. + +**Before you begin** + +You'll need: + +- An environment in one of your project's lifecycles. + +To turn on a feature flag for an environment: + +1. From your project, select **Feature Flags**, then select the flag. +2. In the **Environments** section, select **Add Environment**. +3. Select the environment. +4. Save the flag. + +The environment appears in the flag's environment list with its switch on, and applications in that environment get `true` for the flag. + +To turn the flag on for only some users in the environment, add rules. See [Targeting users with feature flag rules](/docs/feature-flags/rules). + +## Related links + +- [Feature flags](/docs/feature-flags) +- [How feature flag evaluation works](/docs/feature-flags/how-evaluation-works) +- [Targeting users with feature flag rules](/docs/feature-flags/rules) +- [OpenFeature providers](/docs/feature-flags/providers) diff --git a/src/pages/docs/feature-flags/how-evaluation-works.md b/src/pages/docs/feature-flags/how-evaluation-works.md new file mode 100644 index 0000000000..acbad62520 --- /dev/null +++ b/src/pages/docs/feature-flags/how-evaluation-works.md @@ -0,0 +1,95 @@ +--- +layout: src/layouts/Default.astro +pubDate: 2026-11-05 +modDate: 2026-11-05 +title: How feature flag evaluation works +sidebarLabel: How evaluation works +navTitle: How evaluation works +navSection: Feature Flags +navOrder: 20 +icon: fa-solid fa-diagram-project +description: Learn how Octopus decides whether a feature flag is on, from environment switches and default values to rules, phases, and percentage rollouts. +subject: feature flags, evaluation, default values, percentage rollout, rules, phases +type: concept +audience: [app-dev, devops-eng] +image: +imageAlt: +--- + +When your application asks for a feature flag, Octopus works through the flag's configuration for that application's environment and returns `true` or `false`. This page explains each part of that decision, so you can predict what any user will get before you change a flag. + +## The evaluation sequence + +Every evaluation follows the same sequence, and it stops at the first step that decides the result. Knowing the order tells you which part of a flag's configuration to look at when a user gets a result you didn't expect. + +For the environment named in the application's client identifier: + +1. If the environment hasn't been added to the flag, the result is the flag's default value. +2. If the environment's switch is off, the result is `false`. [VERIFY: that a switched-off environment returns false rather than the flag's default value — needs: confirmation from the feature flags team] +3. If the environment has no rules, the result is `true`, for everyone. +4. If the environment has phases and none of them is on, the result is `false`. +5. If any rule in a phase that's on matches, the result is `true`. Otherwise, it's `false`. + +If the application can't reach the Octopus feature flag service at all, none of this happens, and the application uses the default value in its own code. + + + +## Rules and conditions + +A rule is a set of conditions that together describe a group of users, and the rules on an environment are how a flag reaches some users but not others. Conditions in a rule combine with AND: the rule matches only when every condition matches. Rules combine with OR: the flag is on when at least one rule matches. + +For example, an environment with these 2 rules: + +- **Internal users**: context attribute `email-domain` is one of `octopus.com` +- **Early adopters**: tenant has tag `Ring/Early adopter` AND 50% of targeting keys + +turns the flag on for every internal user, and for half the users of tenants in the early adopter ring. + +Because rules combine with OR, a condition only limits the rule it's in. To keep a flag away from someone no matter which rule they'd otherwise match, such as excluding one tenant, add that condition to every rule. For the full list of conditions, see [Rule conditions](/docs/feature-flags/rules#rule-conditions). + +## Phases + +A phase is a stage in a rollout that holds one or more rules. When a phase is on, its rules join the rules from earlier phases that are already on, so each phase widens the rollout rather than replacing it. When a phase is off, its rules are ignored. + +Phases turn on in order. A phase can't be on while a phase before it is off, which keeps the rollout moving in one direction. Turning a phase off rolls the flag back to the users the earlier phases target. + +An environment with rules but no visible phases holds all its rules in a single phase that's on. For how phases turn on by themselves, see [Rolling out feature flags in phases](/docs/feature-flags/phased-rollouts). + +## Default values {#default-values} + +A flag has 2 default values, and each applies in a different situation. Mixing them up is the most common cause of a flag returning something unexpected. + +The default value on the flag in Octopus is returned for any environment that hasn't been added to the flag. For example, if a flag's default value is off and only `Staging` and `Production` have been added to it, an application in `Development` gets `false`. + +The default value in your code, the second argument to the evaluation call, is used only when the application can't get a value from the Octopus feature flag service, for example during a network outage: + +```cs +var darkModeEnabled = await featureClient.GetBooleanValueAsync("dark-mode", false); +``` + +Set the default value in your code to the result that's safest for your users if Octopus can't be reached. In most cases, that's `false`. + +## Percentage rollouts + +A percentage condition turns a flag on for a share of tenants or users, such as 20% of tenants. Percentages let you limit how many people a change reaches while you watch for problems, then widen it. + +Octopus decides who falls in a percentage by hashing an identifier together with a key that belongs to the flag. For tenants, the identifier is the tenant ID. For users, it's the [targeting key](/docs/feature-flags/rules#evaluation-context) your application supplies. The hash is deterministic, so the same tenant or user always gets the same result for the same flag, and they don't flip between on and off as they use your application. + +Because the flag's key is part of the hash, a 20% rollout of one flag reaches a different 20% than a 20% rollout of another flag. This stops the same users from always being the first to get every new feature. When you want related flags to reach the same users, put them in a [rollout group](/docs/feature-flags/rollout-groups), which gives every flag in the group the same key. + +[VERIFY: that increasing a percentage keeps everyone already included and only adds new tenants or users — needs: confirmation of the bucketing behavior from the feature flags team] + +## Publishing + +Octopus doesn't evaluate flags inside your deployments. When you save a change to a flag, Octopus publishes the project's flag configuration to the Octopus feature flag service, which your applications' providers read from. This is why flag changes reach running applications without a redeployment. + +If a publish fails, the project's **Feature Flags** page shows a callout, and your applications keep the configuration from the last successful publish. To check recent publishes, see [Check a project's publish history](/docs/feature-flags/managing-flags#check-a-projects-publish-history). + +[VERIFY: how long a running application takes to see a published change — needs: the provider refresh interval from the feature flags team] + +## Related links + +- [Targeting users with feature flag rules](/docs/feature-flags/rules) +- [Rolling out feature flags in phases](/docs/feature-flags/phased-rollouts) +- [Previewing feature flag evaluations](/docs/feature-flags/previewing-evaluations) +- [Managing rollout groups](/docs/feature-flags/rollout-groups) diff --git a/src/pages/docs/feature-flags/index.md b/src/pages/docs/feature-flags/index.md index 6773edb899..e472143028 100644 --- a/src/pages/docs/feature-flags/index.md +++ b/src/pages/docs/feature-flags/index.md @@ -1,122 +1,65 @@ --- layout: src/layouts/Default.astro pubDate: 2025-05-21 -modDate: 2026-06-18 -title: Feature Flags -icon: fa-solid fa-toggle-on +modDate: 2026-11-05 +title: Feature flags +sidebarLabel: Overview navTitle: Overview navSection: Feature Flags -description: Octopus Feature Flags allow progressive delivery of changes and instant rollback navOrder: 95 +icon: fa-solid fa-toggle-on +description: Turn features on and off without redeploying, and roll changes out to the right users in stages with Octopus Feature Flags. +subject: feature flags, feature toggles, progressive delivery, OpenFeature, phased rollouts, rules +type: concept +audience: [app-dev, devops-eng, evaluator] +image: +imageAlt: --- -Octopus Feature Flags support toggling features on or off in real-time, without redeploying, and progressively releasing changes to subsets of your users. +This page explains what Octopus Feature Flags are, the parts a flag is built from, and how they connect to the projects, environments, and tenants you already deploy with. :::div{.hint} -Octopus Feature Flags are now available to Octopus Cloud customers as a Private Preview. To get access, [register your interest](https://survey.octopus.com/t/piv3LpVWWmus). +Octopus Feature Flags are available to Octopus Cloud customers as a Private Preview. To get access, [register your interest](https://survey.octopus.com/t/piv3LpVWWmus). ::: -## Usage - -### Create a Feature Flag - -Feature Flags are located within Octopus Projects: -**Project ➜ Feature Flags** - -Create a new flag and give it a name. - -![New flag name](/docs/img/feature-flags/new-flag-name.png) - -### Configure OpenFeature in your client application {#configure-open-feature-client-app} - -Octopus Feature Flags rely on [OpenFeature](https://openfeature.dev/) as the client SDK. - -Follow the [OpenFeature guide for installing the SDK for your language](https://openfeature.dev/ecosystem?instant_search%5BrefinementList%5D%5Btype%5D%5B0%5D=SDK) into your application. - -Configure OpenFeature to use the [Octopus Provider](/docs/feature-flags/providers). - -The Octopus OpenFeature Provider requires a client identifier when instantiated. This is a [JWT](https://jwt.io/introduction) which specifies the Octopus Project, Environment, and Tenant (if applicable). This tells the Octopus Feature Flag service which set of flags to evaluate. - -:::div{.hint} -The Octopus Feature Flag client identifier is available via the Octopus variable `Octopus.FeatureToggles.ClientIdentifier` or via the Feature Flag UI (see below). +:::div{.info} +If your project's **Feature Flags** page shows an **Upgrade to feature flag rules** callout, the project still uses the previous way of configuring flags. See [Legacy feature flags](/docs/feature-flags/legacy) for how those flags work, or [Upgrading to feature flag rules](/docs/feature-flags/upgrading-to-rules) to move the project to rules. ::: -For applications deployed by Octopus, the recommended way is to have Octopus inject the client identifier as part of deployment, for example by injecting it into a configuration file or environment variable. The client identifier is made available via the Octopus variable `Octopus.FeatureToggles.ClientIdentifier`. - -For applications not deployed by Octopus, or cannot have the client identifier supplied during deployment for any reason, the client identifier can be obtained via the portal UI, as shown below. - -![Client identifier preview menu item](/docs/img/feature-flags/client-identifier-preview-menu-item.png) - -![Client identifier preview UI](/docs/img/feature-flags/client-identifier-preview.png) - -The previewed client identifier may then be copied into your application configuration. - -For example, an ASP.NET application could have an `appsettings.json` file which contained the following: - -```json -{ - "FeatureFlags": { - "ClientId": "#{Octopus.FeatureToggles.ClientIdentifier}" - } -} -``` - -This would be transformed during deployment by Octopus to contain the correct client identifier for the current Project and Environment. - -This would then be used during application startup to configure the OpenFeature with the Octopus Provider, similar to: - -```cs -// Retrieve client identifier from config -var builder = WebApplication.CreateBuilder(args); -var octopusFeatureFlagsClientId = builder.Configuration["FeatureFlags:ClientId"] ?? ""; - -// Instantiate the Octopus Provider -var octopusProvider = new OctopusFeatureProvider(new OctopusFeatureConfiguration(octopusFeatureFlagsClientId)); - -// Set Octopus as the OpenFeature provider -await OpenFeature.Api.Instance.SetProviderAsync(octopusProvider); -``` - -### Evaluate a Flag - -The [Provider](/docs/feature-flags/providers) for each language documents how to evaluate flags. - -You will need the flag slug in order to reference the flag in code. This can be found in the Octopus portal: - -![Feature Flag slug](/docs/img/feature-flags/feature-flag-slug.png) +## Feature flags -Below is an example of evaluating the flag with slug `dark-mode` in C#: +A feature flag is a named on/off switch that your application checks at runtime. Flags let you ship code with a feature turned off, then turn it on for some or all of your users without another deployment, and turn it off again as quickly if something goes wrong. -```cs -var darkModeEnabled = await featureClient.GetBooleanValueAsync("dark-mode", false); -``` +Feature flags belong to a project in Octopus. Your application evaluates them with [OpenFeature](https://openfeature.dev/), an open standard for feature flag SDKs, and the [Octopus provider](/docs/feature-flags/providers) for your language. When your application starts, the provider uses a client identifier to tell the Octopus feature flag service which project, environment, and tenant the application belongs to. Octopus injects the client identifier during deployment, so the same build gets the right flags in every environment. -The second argument is the default value. Read more about [default values](#default-values) below. +When you change a flag in Octopus, Octopus publishes the change to the feature flag service, and your applications pick it up without being redeployed. -### Rollout +Use a feature flag when you want to separate releasing a feature from deploying it: to test a change with a small group of users, to roll it out gradually, or to keep a way to turn it off quickly. Feature flags are boolean. They aren't a replacement for configuration values that differ by environment. Use [variables](/docs/projects/variables) for those. -To enable your flag for an environment, add the environment to the flag. +## Environment configuration -![Add Environment button](/docs/img/feature-flags/add-environment-button.png) +A feature flag is configured separately for each environment in your project. Adding an environment to a flag gives that environment its own on/off switch and its own targeting, so a flag can be on for everyone in Development, on for a few internal users in Production, and absent from Staging entirely. -Once your Environment configuration is saved, you can toggle the Flag on or off for that Environment. +An environment that isn't added to a flag returns the flag's default value. An environment that's added and switched on, with no rules, has the flag on for everyone. To narrow down who gets the flag, you add rules. -![Toggle Environment](/docs/img/feature-flags/environment-toggle.png) +## Rules, conditions, and phases -You can additionally control rollout within an environment. See [Feature Flag targeting](/docs/feature-flags/targeting) for more information. +Rules decide who gets a flag in an environment. A rule is made of one or more conditions, such as "the tenant has the tag `Tier/Enterprise`" or "the user falls in 20% of targeting keys". A rule matches when all its conditions match, and the flag is on for a user when any rule matches. -## Default Values {#default-values} +Phases group rules into stages of a rollout. Each phase adds more rules, and turning on a phase adds its rules to the rules that are already on. Phases can turn on by themselves at a set date and time, or a set delay after the phase before them, so a rollout can move from internal users to 10% of users to everyone without anyone having to be online for each step. -Flag default values are configured both on the flag in Octopus, and at the evaluation site in your client application. It's important to understand how these interact. + -The default value on the flag in Octopus will be returned if the environment being evaluated has not been configured with an explicit value. +You don't need phases to use rules. An environment with rules and no phases behaves like a single phase that's always on. To see how these parts combine into a single result, see [How feature flag evaluation works](/docs/feature-flags/how-evaluation-works). -In the example below, the `Production` and `Staging` environments have values configured. The default value for the flag is `Off`. If an evaluation is made by an application running in the `Development` environment, or any other environment not configured, it would receive the default value (`Off`). +## Feature flags and tenants -![Default Values](/docs/img/feature-flags/default-values.png) +In a project that uses [tenants](/docs/tenants), the client identifier also names the tenant an application was deployed for. Rules can target tenants directly, target tenants by their tenant tags, or roll a flag out to a percentage of tenants. This means you can give a feature to one customer, to every customer on a particular tier, or to a growing share of customers, without writing any targeting code in your application. -The default value supplied in client code (the `false` argument in the example below) will only be used if the Octopus Feature Flag service cannot be reached, for example if there are network issues or the service is unavailable. +## Related links -```cs -var darkModeEnabled = await featureClient.GetBooleanValueAsync("dark-mode", false); -``` +- [Getting started with feature flags](/docs/feature-flags/getting-started) +- [How feature flag evaluation works](/docs/feature-flags/how-evaluation-works) +- [Targeting users with feature flag rules](/docs/feature-flags/rules) +- [Rolling out feature flags in phases](/docs/feature-flags/phased-rollouts) +- [OpenFeature providers](/docs/feature-flags/providers) diff --git a/src/pages/docs/feature-flags/legacy/index.md b/src/pages/docs/feature-flags/legacy/index.md new file mode 100644 index 0000000000..17ab599945 --- /dev/null +++ b/src/pages/docs/feature-flags/legacy/index.md @@ -0,0 +1,126 @@ +--- +layout: src/layouts/Default.astro +pubDate: 2025-05-21 +modDate: 2026-11-05 +title: Legacy feature flags +icon: fa-solid fa-toggle-on +navTitle: Overview +navSection: Legacy +description: Feature flags in Octopus projects that haven't been upgraded to feature flag rules. +navOrder: 200 +--- + +:::div{.warning} +This page covers feature flags in projects that haven't been upgraded to feature flag rules. If your project uses rules, see [Feature flags](/docs/feature-flags) instead. To move a project to rules, see [Upgrading to feature flag rules](/docs/feature-flags/upgrading-to-rules). +::: + +Octopus Feature Flags support toggling features on or off in real-time, without redeploying, and progressively releasing changes to subsets of your users. + +:::div{.hint} +Octopus Feature Flags are now available to Octopus Cloud customers as a Private Preview. To get access, [register your interest](https://survey.octopus.com/t/piv3LpVWWmus). +::: + +## Usage + +### Create a Feature Flag + +Feature Flags are located within Octopus Projects: +**Project ➜ Feature Flags** + +Create a new flag and give it a name. + +![New flag name](/docs/img/feature-flags/new-flag-name.png) + +### Configure OpenFeature in your client application {#configure-open-feature-client-app} + +Octopus Feature Flags rely on [OpenFeature](https://openfeature.dev/) as the client SDK. + +Follow the [OpenFeature guide for installing the SDK for your language](https://openfeature.dev/ecosystem?instant_search%5BrefinementList%5D%5Btype%5D%5B0%5D=SDK) into your application. + +Configure OpenFeature to use the [Octopus Provider](/docs/feature-flags/legacy/providers). + +The Octopus OpenFeature Provider requires a client identifier when instantiated. This is a [JWT](https://jwt.io/introduction) which specifies the Octopus Project, Environment, and Tenant (if applicable). This tells the Octopus Feature Flag service which set of flags to evaluate. + +:::div{.hint} +The Octopus Feature Flag client identifier is available via the Octopus variable `Octopus.FeatureToggles.ClientIdentifier` or via the Feature Flag UI (see below). +::: + +For applications deployed by Octopus, the recommended way is to have Octopus inject the client identifier as part of deployment, for example by injecting it into a configuration file or environment variable. The client identifier is made available via the Octopus variable `Octopus.FeatureToggles.ClientIdentifier`. + +For applications not deployed by Octopus, or cannot have the client identifier supplied during deployment for any reason, the client identifier can be obtained via the portal UI, as shown below. + +![Client identifier preview menu item](/docs/img/feature-flags/client-identifier-preview-menu-item.png) + +![Client identifier preview UI](/docs/img/feature-flags/client-identifier-preview.png) + +The previewed client identifier may then be copied into your application configuration. + +For example, an ASP.NET application could have an `appsettings.json` file which contained the following: + +```json +{ + "FeatureFlags": { + "ClientId": "#{Octopus.FeatureToggles.ClientIdentifier}" + } +} +``` + +This would be transformed during deployment by Octopus to contain the correct client identifier for the current Project and Environment. + +This would then be used during application startup to configure the OpenFeature with the Octopus Provider, similar to: + +```cs +// Retrieve client identifier from config +var builder = WebApplication.CreateBuilder(args); +var octopusFeatureFlagsClientId = builder.Configuration["FeatureFlags:ClientId"] ?? ""; + +// Instantiate the Octopus Provider +var octopusProvider = new OctopusFeatureProvider(new OctopusFeatureConfiguration(octopusFeatureFlagsClientId)); + +// Set Octopus as the OpenFeature provider +await OpenFeature.Api.Instance.SetProviderAsync(octopusProvider); +``` + +### Evaluate a Flag + +The [Provider](/docs/feature-flags/legacy/providers) for each language documents how to evaluate flags. + +You will need the flag slug in order to reference the flag in code. This can be found in the Octopus portal: + +![Feature Flag slug](/docs/img/feature-flags/feature-flag-slug.png) + +Below is an example of evaluating the flag with slug `dark-mode` in C#: + +```cs +var darkModeEnabled = await featureClient.GetBooleanValueAsync("dark-mode", false); +``` + +The second argument is the default value. Read more about [default values](#default-values) below. + +### Rollout + +To enable your flag for an environment, add the environment to the flag. + +![Add Environment button](/docs/img/feature-flags/add-environment-button.png) + +Once your Environment configuration is saved, you can toggle the Flag on or off for that Environment. + +![Toggle Environment](/docs/img/feature-flags/environment-toggle.png) + +You can additionally control rollout within an environment. See [Feature Flag targeting](/docs/feature-flags/legacy/targeting) for more information. + +## Default Values {#default-values} + +Flag default values are configured both on the flag in Octopus, and at the evaluation site in your client application. It's important to understand how these interact. + +The default value on the flag in Octopus will be returned if the environment being evaluated has not been configured with an explicit value. + +In the example below, the `Production` and `Staging` environments have values configured. The default value for the flag is `Off`. If an evaluation is made by an application running in the `Development` environment, or any other environment not configured, it would receive the default value (`Off`). + +![Default Values](/docs/img/feature-flags/default-values.png) + +The default value supplied in client code (the `false` argument in the example below) will only be used if the Octopus Feature Flag service cannot be reached, for example if there are network issues or the service is unavailable. + +```cs +var darkModeEnabled = await featureClient.GetBooleanValueAsync("dark-mode", false); +``` diff --git a/src/pages/docs/feature-flags/legacy/providers.md b/src/pages/docs/feature-flags/legacy/providers.md new file mode 100644 index 0000000000..7d4d3c117a --- /dev/null +++ b/src/pages/docs/feature-flags/legacy/providers.md @@ -0,0 +1,26 @@ +--- +layout: src/layouts/Default.astro +pubDate: 2026-04-20 +modDate: 2026-11-05 +title: Legacy OpenFeature providers +icon: fa-solid fa-code +navTitle: OpenFeature providers +navSection: Legacy +description: OpenFeature provider versions for feature flags in projects that haven't been upgraded to feature flag rules. +navOrder: 202 +--- + +:::div{.warning} +This page covers feature flags in projects that haven't been upgraded to feature flag rules. If your project uses rules, see [Feature flags](/docs/feature-flags) instead. To move a project to rules, see [Upgrading to feature flag rules](/docs/feature-flags/upgrading-to-rules). +::: + +These are the available Octopus OpenFeature provider SDKs. Getting started instructions for each of these providers is documented in the README files in the repositories. + +## Server SDKs + +- [.NET](https://github.com/OctopusDeploy/openfeature-provider-dotnet) +- [Java](https://github.com/OctopusDeploy/openfeature-provider-java) + +## Web SDKs + +- [TypeScript/JavaScript](https://github.com/OctopusDeploy/openfeature-provider-ts-web) diff --git a/src/pages/docs/feature-flags/legacy/targeting.md b/src/pages/docs/feature-flags/legacy/targeting.md new file mode 100644 index 0000000000..0c74d6d6f8 --- /dev/null +++ b/src/pages/docs/feature-flags/legacy/targeting.md @@ -0,0 +1,128 @@ +--- +layout: src/layouts/Default.astro +pubDate: 2026-04-20 +modDate: 2026-11-05 +title: Legacy targeting +icon: fa-solid fa-bullseye +navTitle: Targeting +navSection: Legacy +description: Targeting options for feature flags in projects that haven't been upgraded to feature flag rules. +navOrder: 201 +--- + +:::div{.warning} +This page covers feature flags in projects that haven't been upgraded to feature flag rules. If your project uses rules, see [Feature flags](/docs/feature-flags) instead. To move a project to rules, see [Upgrading to feature flag rules](/docs/feature-flags/upgrading-to-rules). +::: + +## Minimum version + +You can configure a feature flag to require a minimum version before being enabled in an environment. The flag will be enabled once that version (or any later version) is deployed to that environment. + +![Screenshot of feature flag environment drawer, minimum version section is expanded, minimum version input has value 12.1.0](/docs/img/feature-flags/minimum-version.png) + +## Tenants {#tenants} + +If your project uses [Tenants](/docs/tenants/), you can configure a feature flag to be enabled for subsets of your tenants within an environment. + +There are many options for configuring a feature flag for tenants. These are all modeled in Octopus and do not require any custom configuration in application code. + +### Excluded tenants + +You can exclude tenants individually or exclude groups of tenants using tenant tags. Excluded tenants will always override any other rollout configuration, even if the rollout percentage is set to 100%. + +![Screenshot of feature flag environment drawer, excluded tenants section expanded, tenants to exclude multi-select has Acme Corporation and Contoso Ltd tenants selected, tenant tags to exclude multi-select has Tier/Enterprise tag selected](/docs/img/feature-flags/excluded-tenants.png) + +Once a feature flag is configured with an excluded tenant tag, any changes to tenant tag assignments apply immediately to feature flags (no update to the feature flag configuration is required). + +### Included tenants + +You can enable feature flags for individual tenants. These tenants will always be included, even if the tenant rollout percentage is set to 0%. + +![Screenshot of feature flag environment drawer, included tenants section expanded, tenants to include multi-select has Acme Corporation selected, tenant rollout percentage and tenant tags to include in rollout inputs are empty](/docs/img/feature-flags/included-tenants.png) + +### Tenant rollout + +Tenant rollout allows you to enable a flag for a pseudorandom percentage of all tenants. + +The included tenants are determined using a MurmurHash of the tenant ID and a flag-specific key. This guarantees deterministic evaluation for any given tenant and flag combination, while ensuring that a different set of tenants is included for each flag. + +![Screenshot of feature flag environment drawer, included tenants section expanded, tenants to include is empty, tenant rollout percentage is set to 50% and tenant tags to include in rollout multi-select has Tier/Free, Region/Australia, and Region/Europe selected](/docs/img/feature-flags/tenant-rollout.png) + +You can further restrict the rollout using tenant tags. For example, if you specify `Region/Australia`, `Region/Europe`, and `Tier/Enterprise`, a 50% rollout will only apply to 50% of Enterprise tenants in either Australia or Europe. If you do not specify any tenant tags, a 50% rollout will apply to 50% of all tenants. + +As with excluded tenants, any changes to tenant tags apply immediately to feature flags. + +## Client rollout + +Client rollout allows you to enable a flag for a random percentage of your application users. The included users are determined using a MurmurHash of the [OpenFeature Targeting Key](https://openfeature.dev/docs/reference/concepts/evaluation-context#targeting-key) and a flag-specific key. This guarantees deterministic evaluation for any given user and flag combination. + +To use client rollout, you must configure a targeting key in your OpenFeature client. Refer to the [OpenFeature SDK](https://openfeature.dev/docs/reference/sdks/) documentation for your development language for details on how to set the targeting key. If you do not set a targeting key, the feature flag will not be enabled for any users unless the rollout is set to 100%. + +You should set the targeting key to a value that uniquely identifies your evaluation subject. For most applications, this will be a user identifier (such as a user ID), but you can use any identifier that suits your needs (for example, team, region, or server instance). + +:::div{.hint} +Support for client rollout percentages was added in the following versions of the [provider libraries](/docs/feature-flags/legacy/providers): + +- [.NET: `2.1.0`](https://github.com/OctopusDeploy/openfeature-provider-dotnet/releases/tag/v2.1.0) +- [Java: `0.3.0`](https://github.com/OctopusDeploy/openfeature-provider-java/releases/tag/0.3.0) +- [TypeScript/JavaScript: `3.0.0`](https://github.com/OctopusDeploy/openfeature-provider-ts-web/releases/tag/v3.0.0) + +If you are not running the required minimum version of these libraries, the rollout percentage will be ignored (and handled as if the value was set to 100%). +::: + +### Segments {#segments} + +Segments allow you to further refine the client rollout for a flag based on data that is not modeled in Octopus. Segments are key/value pairs, and are supplied by your application via the [OpenFeature evaluation context](https://openfeature.dev/docs/reference/concepts/evaluation-context). + +Like tenant targeting, segments are configured per-environment on the feature flag in Octopus. + +![Screenshot of feature flag environment drawer, client rollout section expanded, client rollout percentage is set to 50% with 3 segments region/eu, region/au, and ring/early-adopter](/docs/img/feature-flags/segments.png) + +Refer to the [OpenFeature SDK](https://openfeature.dev/docs/reference/sdks/) documentation for your development language for more details on how to set these values. + +Common segment examples include: + +- Specific users (e.g. `user-id/123456`) +- Specific accounts (e.g. `account-id/123456`) +- License types (e.g. `license-type/free`) +- Geographic regions (e.g. `region/eu`) +- Rollout rings (e.g. `ring/early-adopter`) + +A feature flag evaluation will match on segments if the evaluation context matches at least one segment for each key. If you specify `ring/early-adopter`, `region/eu`, and `region/au`, the rollout will apply only to users in the early-adopter ring who are in either the EU or AU regions. If you do not specify any segments, the rollout will apply to all users. + +Some examples: + +| Segments | Evaluation Context | Result | +|------------------------------------------------|-----------------------------------|--------| +| `user-id/123456` | `user-id/123456` | `On` | +| `user-id/123456` | `user-id/789383` | `Off` | +| `ring/early-adopter`, `region/eu`, `region/au` | `ring/early-adopter`, `region/eu` | `On` | +| `ring/early-adopter`, `region/eu`, `region/au` | `ring/early-adopter`, `region/au` | `On` | +| `ring/early-adopter`, `region/eu`, `region/au` | `license-type/free` | `Off` | +| `ring/early-adopter`, `region/eu`, `region/au` | `region/au` | `Off` | + +## Rollout groups {#rollout-groups} + +By default, a percentage rollout on one feature flag will include a different set of tenants or clients than the same percentage rollout on another flag. This ensures the same tenants or clients are not always the first to receive every new feature. + +Rollout groups let you connect rollout evaluation between multiple feature flags so that the same tenants or clients are included in the rollout across those flags. This can be useful when you have related features that should roll out to the same audience. + +You can assign a rollout group to a feature flag from the feature flag page by selecting a group from the rollout group dropdown. + +![Screenshot of feature flag page showing rollout group selector expanded with new onboarding flow group selected](/docs/img/feature-flags/rollout-group-selector.png) + +:::div{.warning} +If you have a tenant or client rollout configured, adding, changing, or removing a rollout group on a feature flag will change which tenants or clients are included in that rollout. +::: + +### Managing rollout groups + +You can manage rollout groups from the rollout groups page. To access this page, open the overflow menu on the feature flags list page and select **Manage Rollout Groups**. + +![Screenshot of feature flags list page with overflow menu expanded highlighting the manage rollout groups button](/docs/img/feature-flags/manage-rollout-group-overflow.png) + +From the rollout groups page, you can add, rename, and delete rollout groups. + +![Screenshot of rollout group list page with a single rollout group named new onboarding flow, used by the live chat and AI recommendations feature flags, with the overflow menu expanded and showing edit and delete options](/docs/img/feature-flags/rollout-group-page.png) + +You cannot delete a rollout group that is assigned to one or more feature flags. To delete a rollout group, first remove it from all feature flags that use it. diff --git a/src/pages/docs/feature-flags/managing-flags.md b/src/pages/docs/feature-flags/managing-flags.md new file mode 100644 index 0000000000..2038308c3a --- /dev/null +++ b/src/pages/docs/feature-flags/managing-flags.md @@ -0,0 +1,114 @@ +--- +layout: src/layouts/Default.astro +pubDate: 2026-11-05 +modDate: 2026-11-05 +title: Managing feature flags +sidebarLabel: Managing flags +navTitle: Managing flags +navSection: Feature Flags +navOrder: 70 +icon: fa-solid fa-sliders +description: Clone Octopus feature flags, copy rules between flags, change slugs safely, rotate client identifiers, and check publish history. +subject: feature flags, clone, slug, client identifier, publish history, troubleshooting +type: guide +audience: [app-dev, devops-eng] +image: +imageAlt: +--- + +This page covers the everyday upkeep of feature flags in a project: reusing configuration from other flags, renaming a flag's slug without breaking your applications, rotating client identifiers, and checking that your changes reached the Octopus feature flag service. + +## Clone a feature flag + +Clone a flag to start a new one with the same environments, rules, and phases, such as for a feature that rolls out the same way as an earlier one. + +**Before you begin** + +You'll need: + +- Permission to edit the flag and every environment it's configured for. +- No unsaved changes on the flag. + +To clone a feature flag: + +1. From your project, select **Feature Flags**, then select the flag. +2. Open the overflow menu and select **Clone**. +3. Enter a **Name** for the new flag. +4. Select **Clone**. + +The new flag opens with the original flag's environments, rules, and phases. To stop the clone from reaching users before you're ready, the clone differs from the original in these ways: + +- Every environment's switch is off. +- Every phase is off. +- **Specific date/time** triggers are removed. **After a delay** triggers are kept, because they can't fire until you turn on the phase before them. + +## Copy rules and phases from another flag + +Copy configuration into one environment of a flag when another flag, or another environment, already targets the users you need. + +To copy rules and phases from another flag: + +1. From your project, select **Feature Flags**, then select the flag you're copying to. +2. In the **Environments** section, select the environment to copy into. +3. Select **Add**, then select **Existing configuration**. +4. Select the flag and environment to copy from. Select **Only show this environment** to limit the list to the same environment. +5. Select **Clone**. +6. Save the flag. + +The copied rules or phases appear in the environment, and Octopus shows what it added. If the source is a different environment, the preview reminds you that the configuration may need changes, such as tenants that aren't connected to this environment. + +What you get depends on what's already in the environment: + +- **No rules yet**: the environment gets a copy of the source's rules or phases. +- **Rules but no phases**: copied rules are added to the existing rules. Copied phases are added after the existing rules, which become the first phase. +- **Phases**: copied rules are added as a new phase at the end, and copied phases are added after the existing phases. + +Copied rules that aren't in a phase take effect when you save, like any other rule. Copied phases arrive off, and they keep **After a delay** triggers but not **Specific date/time** triggers, so they don't go live until you turn them on. + +## Change a feature flag's slug + +Your applications refer to a flag by its slug, so changing the slug changes what your code must ask for. Plan the change so your applications don't fall back to their code defaults. + +To change a feature flag's slug safely: + +1. Release a version of your application that handles both the old slug and the new slug. +2. From your project, select **Feature Flags**, then select the flag. +3. Change the **Slug**. +4. Save the flag. +5. Release a version of your application that only uses the new slug. + +Applications that still ask for the old slug get the default value in their own code. [VERIFY: that evaluating a slug that no longer exists returns the code default — needs: confirmation of provider behavior for unknown flags] + +## Rotate client identifiers + +Rotate a project's client identifiers if one has been exposed or your security policy requires regular rotation. Rotation is a 2-step process, so applications keep working while you redeploy them with the new identifiers. + +:::div{.warning} +Rotating client identifiers is destructive. After the rotation finishes, applications that still use an old client identifier can't get flag values and fall back to the default values in their own code. +::: + +To rotate client identifiers: + +1. From your project, select **Feature Flags**. +2. Open the overflow menu and select **Rotate Client Identifiers**. +3. [PLACEHOLDER: the remaining steps of the 2-step rotation, including when to redeploy applications — needs: the rotation procedure from the feature flags team] + +## Check a project's publish history + +When you save a flag, Octopus publishes the project's flag configuration to the Octopus feature flag service. Check the publish history when your applications don't seem to have a change you saved. + +To check a project's publish history: + +1. From your project, select **Feature Flags**. +2. Select **View publish history**. If the latest publish failed, this link also appears in the callout at the top of the page. + +The history lists recent publish attempts and whether each one succeeded. To retry a failed publish, select **Publish now**. + +If publishes keep failing on Octopus Server, check that any firewall or proxy lets Octopus Server reach the feature flag service at `features.octopus.com`. + +## Related links + +- [Feature flags](/docs/feature-flags) +- [Rolling out feature flags in phases](/docs/feature-flags/phased-rollouts) +- [Managing rollout groups](/docs/feature-flags/rollout-groups) +- [Getting started with feature flags](/docs/feature-flags/getting-started) diff --git a/src/pages/docs/feature-flags/phased-rollouts.md b/src/pages/docs/feature-flags/phased-rollouts.md new file mode 100644 index 0000000000..c650514185 --- /dev/null +++ b/src/pages/docs/feature-flags/phased-rollouts.md @@ -0,0 +1,117 @@ +--- +layout: src/layouts/Default.astro +pubDate: 2026-11-05 +modDate: 2026-11-05 +title: Rolling out feature flags in phases +sidebarLabel: Phased rollouts +navTitle: Phased rollouts +navSection: Feature Flags +navOrder: 40 +icon: fa-solid fa-stairs +description: Roll an Octopus feature flag out in stages with phases, and use date and delay triggers to move between stages automatically. +subject: feature flags, phases, phased rollout, triggers, progressive delivery, rollback +type: guide +audience: [app-dev, devops-eng] +image: +imageAlt: +--- + +Phases let you plan a feature flag's whole rollout in an environment up front, from the first internal users to everyone, and move through it one stage at a time. This page covers adding phases, setting triggers so phases turn on by themselves, and turning phases on and off by hand to move a rollout forward or roll it back. + +## Phases and triggers + +A phase is a stage in a flag's rollout in one environment, such as "Internal", "10% of users", or "Everyone". Each phase holds one or more [rules](/docs/feature-flags/rules). When a phase is on, its rules join the rules from the phases before it, so every phase you turn on widens the rollout. + +Phases are ordered, and they turn on in that order. A phase can't be on while a phase before it is off. Turning a phase off removes its rules from the rollout and rolls the flag back to the users that earlier phases still target. + +A trigger turns a phase on without anyone having to do it. Each phase can have one trigger. A phase can turn on at a specific date and time, or a set delay after the phase before it turns on. A phase without a trigger waits for someone to turn it on. + +Triggers chain. If phase 2 starts 1 day after phase 1, and phase 3 starts 2 days after phase 2, turning on phase 1 sets the whole rollout in motion. Each delay counts from when the phase before it actually turned on, so if you hold phase 2 back by turning it on by hand later, phase 3 moves back too. + + + +Use phases when you want a planned, staged rollout in an environment. If you only need to target a fixed group of users, rules on their own are enough. + +## Add a phase + +Add a phase for each stage of the rollout. The first time you add a phase to an environment that already has rules, those rules become the first phase. + +**Before you begin** + +You'll need: + +- A feature flag with the environment added to it. See [Turn on a feature flag for an environment](/docs/feature-flags/getting-started#turn-on-a-feature-flag-for-an-environment). + +To add a phase: + +1. From your project, select **Feature Flags**, then select the flag. +2. In the **Environments** section, select the environment. +3. Select **Add**, then select **Phase**. +4. Enter a **Phase Name** that describes the stage. +5. Add one or more rules to the phase. See [Add a rule](/docs/feature-flags/rules#add-a-rule). +6. Save the flag. + +The new phase appears at the end of the environment's phase list. It's off until you turn it on or its trigger fires. + +:::div{.hint} +A phase can't be empty. Removing a phase's last rule removes the phase, including its trigger. To start a new phase from an existing one, open the phase's menu and select **Clone phase**. +::: + +## Phase triggers + +A phase's trigger decides when the phase turns on. This table lists the trigger types you can choose in the phase's trigger settings. + +| Trigger | Settings | Turns the phase on | +| --- | --- | --- | +| **Manual** | None | Only when someone turns it on. | +| **After a delay** | **Delay** and **Unit** (hours or days) | The given time after the phase before it turns on. Not available on the first phase. | +| **Specific date/time** | **Date**, **Time**, and **Timezone** | At the given date and time in the given timezone. | + +Delays are exact durations, so a 24-hour delay that crosses a daylight saving change is still 24 hours. A **Specific date/time** trigger still waits for the phases before it: if an earlier phase is off when the date passes, the phase turns on after the earlier phases do. + +For example, a Production rollout might start an "Internal" phase manually, start "10% of users" **After a delay** of 1 day, and start "Everyone" at a **Specific date/time** of Monday at 9:00am in the team's timezone. + +## Set a phase trigger + +Set a trigger to turn a phase on automatically, so the rollout keeps moving outside working hours or without someone watching. + +To set a phase trigger: + +1. From your project, select **Feature Flags**, then select the flag. +2. In the **Environments** section, select the environment. +3. Select the phase's trigger. [VERIFY: the name or position of the control that opens a phase's trigger settings — needs: confirmation from the phase list UI] +4. Select the trigger type. +5. Enter the trigger's settings. +6. Save the flag. + +The phase shows when it's due to turn on, such as "Triggers in 2 days". Octopus checks for due triggers with a scheduled server task [VERIFY: how often the task runs and whether it appears in the Tasks list — needs: confirmation from the feature flags team], so a phase can turn on a short time after its due time. + +If a trigger's time has already passed when you save, for example because you set a date in the past, Octopus asks you to confirm in a **Save and Trigger Phases** dialog. Saving turns those phases on straight away, along with any later phases whose triggers also become due. + +## Turn a phase on or off + +Turn a phase on by hand to start a rollout or move it forward early. Turn a phase off to roll the flag back to the users that earlier phases target. + +To turn a phase on or off: + +1. From your project, select **Feature Flags**, then select the flag. +2. In the **Environments** section, select the environment. +3. Select **Turn this phase on** or **Turn this phase off** on the phase. +4. Save the flag. + +The phase shows as on or off in the environment's phase list, and applications in the environment get the new result after Octopus publishes the change. + +Because phases turn on in order, a phase can only be turned off while every phase after it is off. [VERIFY: whether turning a phase off in the UI also turns off the later phases, or blocks the change until they're off — needs: confirmation from the phase list UI] + +:::div{.warning} +Turning a phase off also clears the time it turned on. If the next phase has an **After a delay** trigger, its delay starts again from when you turn the earlier phase back on. +::: + +To stop a flag for everyone in the environment straight away, turn off the environment's switch instead. + +## Related links + +- [How feature flag evaluation works](/docs/feature-flags/how-evaluation-works) +- [Targeting users with feature flag rules](/docs/feature-flags/rules) +- [Previewing feature flag evaluations](/docs/feature-flags/previewing-evaluations) +- [Managing feature flags](/docs/feature-flags/managing-flags) diff --git a/src/pages/docs/feature-flags/previewing-evaluations.md b/src/pages/docs/feature-flags/previewing-evaluations.md new file mode 100644 index 0000000000..5ea915f282 --- /dev/null +++ b/src/pages/docs/feature-flags/previewing-evaluations.md @@ -0,0 +1,66 @@ +--- +layout: src/layouts/Default.astro +pubDate: 2026-11-05 +modDate: 2026-11-05 +title: Previewing feature flag evaluations +sidebarLabel: Previewing evaluations +navTitle: Previewing evaluations +navSection: Feature Flags +navOrder: 60 +icon: fa-solid fa-magnifying-glass +description: Check what an Octopus feature flag returns in each environment and for each tenant, including unsaved changes, before your users see it. +subject: feature flags, evaluation preview, tenants, environments, rules, testing +type: guide +audience: [app-dev, devops-eng] +image: +imageAlt: +--- + +Evaluation previews show what a feature flag returns for each environment and tenant, based on the flag's rules and what's deployed. This page covers previewing one flag across your environments and tenants, and previewing every flag for one tenant. + +## Evaluation previews + +An evaluation preview runs a flag's configuration the same way the Octopus feature flag service does, for each environment or tenant in your project, and shows the result with the reason for it. Previews take the version of the release deployed to each environment into account, so **Minimum version** conditions show the result your applications get now. + +Previews also include changes you haven't saved yet. While you edit a flag, the preview shows both the saved value and the unsaved value, so you can check a change before it reaches anyone. + +A preview covers what Octopus knows: environments, tenants, and deployed versions. It can't know your application's evaluation context, so the result for rules that use **Context attribute** or **Percentage** by targeting keys conditions depends on the users in your application. [VERIFY: how previews show results for rules that depend on evaluation context — needs: confirmation from the Evaluate tab UI] + +## Preview a feature flag + +Preview a flag to check its result in every environment, or for every tenant in one environment, after a change or while you plan one. + +To preview a feature flag: + +1. From your project, select **Feature Flags**, then select the flag. +2. Select the **Evaluate** tab. +3. In **Display by**, select **Environments** or **Tenants**. +4. Select the **Tenant** or **Environment** to preview for, and the **Channel** if your project uses more than one. + +The table lists each environment or tenant with the flag's **Value**, the **Reason** for it, and the deployed **Version**. Projects that use tenants also show an **Untenanted** row for applications deployed without a tenant. + + + +## Preview every feature flag for a tenant + +Preview a tenant's flags to answer "what does this customer see?" for every flag in a project at once, such as before a support call or a tenant's upgrade. + +**Before you begin** + +You'll need: + +- A tenant connected to at least one environment in the project. + +To preview every feature flag for a tenant: + +1. Select **Tenants**, then select the tenant. +2. Select **Feature Flags**. [VERIFY: the navigation to a tenant's feature flags page — needs: confirmation from the tenant UI] +3. Select the **Project** and **Environment**. + +The page lists each of the project's feature flags with its value for that tenant in the environment. + +## Related links + +- [How feature flag evaluation works](/docs/feature-flags/how-evaluation-works) +- [Targeting users with feature flag rules](/docs/feature-flags/rules) +- [Rolling out feature flags in phases](/docs/feature-flags/phased-rollouts) diff --git a/src/pages/docs/feature-flags/providers.md b/src/pages/docs/feature-flags/providers.md index 35ca6eeb86..1227e54d52 100644 --- a/src/pages/docs/feature-flags/providers.md +++ b/src/pages/docs/feature-flags/providers.md @@ -1,22 +1,39 @@ --- layout: src/layouts/Default.astro pubDate: 2026-04-20 -modDate: 2026-06-18 -title: OpenFeature Providers -icon: fa-solid fa-code -navTitle: OpenFeature Providers +modDate: 2026-11-05 +title: OpenFeature providers +sidebarLabel: OpenFeature providers +navTitle: OpenFeature providers navSection: Feature Flags -description: OpenFeature providers for Octopus Feature Flags -navOrder: 97 +navOrder: 80 +icon: fa-solid fa-code +description: The Octopus OpenFeature providers for each language, and the minimum versions projects that use feature flag rules need. +subject: feature flags, OpenFeature, providers, SDK, .NET, Java, TypeScript +type: reference +audience: [app-dev] +image: +imageAlt: --- -These are the available Octopus OpenFeature provider SDKs. Getting started instructions for each of these providers is documented in the README files in the repositories. +Your application connects to Octopus Feature Flags through an Octopus provider for the [OpenFeature](https://openfeature.dev/) SDK in its language. This page lists the available providers and the versions you need. + +## Octopus providers + +This table lists every Octopus OpenFeature provider. The minimum versions apply to projects that use feature flag rules. Projects that haven't been upgraded to rules can use earlier versions, listed in [Legacy OpenFeature providers](/docs/feature-flags/legacy/providers). + +| Language | Type | Repository | Minimum version for rules | +| --- | --- | --- | --- | +| .NET | Server | [openfeature-provider-dotnet](https://github.com/OctopusDeploy/openfeature-provider-dotnet) | [VERIFY: `4.0.0` — needs: the released version with rule support; the Octopus UI marks this as provisional] | +| Java | Server | [openfeature-provider-java](https://github.com/OctopusDeploy/openfeature-provider-java) | [VERIFY: `2.0.0` — needs: the released version with rule support; the Octopus UI marks this as provisional] | +| TypeScript/JavaScript | Web | [openfeature-provider-ts-web](https://github.com/OctopusDeploy/openfeature-provider-ts-web) | [VERIFY: `5.0.0` — needs: the released version with rule support; the Octopus UI marks this as provisional] | -## Server SDKs +Each repository's README covers installing the provider and configuring it with your client identifier. -- [.NET](https://github.com/OctopusDeploy/openfeature-provider-dotnet) -- [Java](https://github.com/OctopusDeploy/openfeature-provider-java) +An application on an earlier provider version keeps the flag values it had when its project was upgraded to rules, and doesn't see any changes made after that. See [Upgrading to feature flag rules](/docs/feature-flags/upgrading-to-rules). -## Web SDKs +## Related links -- [TypeScript/JavaScript](https://github.com/OctopusDeploy/openfeature-provider-ts-web) +- [Getting started with feature flags](/docs/feature-flags/getting-started) +- [Targeting users with feature flag rules](/docs/feature-flags/rules) +- [Upgrading to feature flag rules](/docs/feature-flags/upgrading-to-rules) diff --git a/src/pages/docs/feature-flags/rollout-groups.md b/src/pages/docs/feature-flags/rollout-groups.md new file mode 100644 index 0000000000..5363ccdf03 --- /dev/null +++ b/src/pages/docs/feature-flags/rollout-groups.md @@ -0,0 +1,85 @@ +--- +layout: src/layouts/Default.astro +pubDate: 2026-11-05 +modDate: 2026-11-05 +title: Managing rollout groups +sidebarLabel: Rollout groups +navTitle: Rollout groups +navSection: Feature Flags +navOrder: 50 +icon: fa-solid fa-layer-group +description: Group related Octopus feature flags so their percentage rollouts reach the same tenants and users. +subject: feature flags, rollout groups, percentage rollout, tenants, targeting key +type: guide +audience: [app-dev, devops-eng] +image: +imageAlt: +--- + +Rollout groups keep percentage rollouts in step across related feature flags. This page covers adding a flag to a rollout group, and creating, renaming, and deleting groups. + +## Rollout groups + +By default, a percentage condition on one flag reaches a different set of tenants or users than the same percentage on another flag. This spreads the risk of new features, so the same tenants or users aren't always first in line. + +A rollout group connects the percentage rollouts of several flags so they reach the same tenants and users. If 2 flags in a group each roll out to 20% of tenants, they reach the same 20%. Use a rollout group for features that only make sense together, such as a new onboarding flow split across several flags. + +A rollout group affects **Percentage** conditions only. Other conditions, such as tenant tags or context attributes, match the same way whether or not a flag is in a group. For how percentages are calculated, see [Percentage rollouts](/docs/feature-flags/how-evaluation-works#percentage-rollouts). + +## Create a rollout group + +Create a rollout group before you add flags to it. Rollout groups belong to a project. + +To create a rollout group: + +1. From your project, select **Feature Flags**. +2. Open the overflow menu and select **Manage Rollout Groups**. +3. Select **Add Rollout Group**. +4. Enter a name for the group. +5. [VERIFY: the label of the button that saves a new rollout group — needs: confirmation from the Add Rollout Group dialog] + +![Feature flags list page with the overflow menu open and Manage Rollout Groups highlighted](/docs/img/feature-flags/manage-rollout-group-overflow.png) + +The group appears in the project's rollout group list, ready to assign to flags. + +## Add a feature flag to a rollout group + +Adding a flag to a rollout group changes which tenants and users its percentage conditions reach, so check the flag's current rollout first. + +To add a feature flag to a rollout group: + +1. From your project, select **Feature Flags**, then select the flag. +2. Select the group in the **Rollout group** field. +3. Save the flag. + +:::div{.warning} +If the flag has percentage conditions, adding it to a group, changing its group, or removing it from a group changes which tenants and users get the flag. Octopus warns you and lists the affected environments before you save. +::: + +The rollout group list shows the flag under the group's feature flags. + +## Rename or delete a rollout group + +Rename a group to keep its purpose clear, or delete it when no flags need it. Renaming a group doesn't change which tenants or users its flags reach. + +**Before you begin** + +You'll need: + +- To delete a group: no flags assigned to it. Remove the group from each flag that uses it first. + +To rename or delete a rollout group: + +1. From your project, select **Feature Flags**. +2. Open the overflow menu and select **Manage Rollout Groups**. +3. Open the group's overflow menu and select **Edit** or **Delete**. + +![Rollout group list with one group named new onboarding flow, its overflow menu open showing Edit and Delete](/docs/img/feature-flags/rollout-group-page.png) + +The group shows its new name, or no longer appears in the list. + +## Related links + +- [How feature flag evaluation works](/docs/feature-flags/how-evaluation-works) +- [Targeting users with feature flag rules](/docs/feature-flags/rules) +- [Managing feature flags](/docs/feature-flags/managing-flags) diff --git a/src/pages/docs/feature-flags/rules.md b/src/pages/docs/feature-flags/rules.md new file mode 100644 index 0000000000..34014c4b8a --- /dev/null +++ b/src/pages/docs/feature-flags/rules.md @@ -0,0 +1,127 @@ +--- +layout: src/layouts/Default.astro +pubDate: 2026-11-05 +modDate: 2026-11-05 +title: Targeting users with feature flag rules +sidebarLabel: Rules +navTitle: Rules +navSection: Feature Flags +navOrder: 30 +icon: fa-solid fa-bullseye +description: Use rules and conditions to turn Octopus feature flags on for specific tenants, users, versions, and percentages, and pass evaluation context from your app. +subject: feature flags, rules, conditions, targeting, evaluation context, targeting key, tenants +type: guide +audience: [app-dev, devops-eng] +image: +imageAlt: +--- + +Rules let you turn a feature flag on for some users in an environment and not others. This page covers adding rules to an environment, the conditions a rule can use, and passing the evaluation context those conditions need from your application. + +## Rules and conditions + +A rule describes a group of users who should get a flag, such as "enterprise tenants in Europe" or "10% of users on version 3.2 or later". Each rule is made of one or more conditions. Conditions in a rule combine with AND, so a rule matches only when all its conditions match. Rules combine with OR, so the flag is on for a user when any rule matches. + +Rules belong to an environment on a flag, and each environment has its own rules. An environment without rules has the flag on for everyone, so adding the first rule is what narrows the flag down to a group. + +Some conditions use information Octopus already knows, such as the tenant in the client identifier or the version of the release deployed to the environment. Others use information your application passes in when it evaluates the flag, called the evaluation context. If a condition needs evaluation context and your application doesn't pass it, the condition doesn't match. + +Because rules combine with OR, a condition in one rule has no effect on another rule. To exclude a tenant or a user from a flag entirely, add the exclusion to every rule on the environment. + +## Add a rule + +Add a rule to narrow a flag down to a group of users in one environment. Add more rules to reach more groups. + +**Before you begin** + +You'll need: + +- A feature flag with the environment added to it. See [Turn on a feature flag for an environment](/docs/feature-flags/getting-started#turn-on-a-feature-flag-for-an-environment). + +To add a rule: + +1. From your project, select **Feature Flags**, then select the flag. +2. In the **Environments** section, select the environment. [VERIFY: that selecting the environment in the list opens its rules and phases editor — needs: confirmation from the feature flag page UI] +3. Select **Add**, then select **Rule**. +4. Enter a **Rule name** that describes the group the rule targets. +5. Select **Add Condition**, then select the condition type. +6. Enter the condition's values. +7. Select **Done**. +8. Save the flag. + + + +The rule appears in the environment's rule list, with its conditions joined by **And** and separated from any other rules by **Or**. To check who the rule reaches before or after you save, see [Previewing feature flag evaluations](/docs/feature-flags/previewing-evaluations). + +:::div{.hint} +Adding a rule to an environment that's switched on applies it straight away when you save. To stage a rule so it applies later, add it to a phase. See [Rolling out feature flags in phases](/docs/feature-flags/phased-rollouts). +::: + +## Rule conditions {#rule-conditions} + +This table lists every condition a rule can use, in the order they appear when you select **Add Condition**. The **Tenants** and **Tenant tags** conditions, and percentages by tenants, appear only in projects that use tenants. + +| Condition | Match | Matches when | Values come from | +| --- | --- | --- | --- | +| **Percentage** | By tenants, by targeting keys | The tenant, or the targeting key in the evaluation context, falls in the given percentage. Percentages go up in steps of 10%. | Octopus (tenant) or your application (targeting key) | +| **Tenants** | One of, not one of | The tenant in the client identifier is, or isn't, one of the selected tenants. | Octopus (client identifier) | +| **Tenant tags** | One of, not one of | The tenant has, or doesn't have, any of the selected tags. All the tags in one condition come from the same tag set. | Octopus (tenant tags) | +| **Minimum version** | Version is at least | The latest release deployed to the environment is the given version or later. The version must be a valid semantic version. [VERIFY: whether a tenanted application is matched on the latest release deployed to its tenant — needs: confirmation from the feature flags team] | Octopus (deployed release) | +| **Context attribute** | One of, not one of | The named attribute in the evaluation context is, or isn't, one of the listed values. | Your application (evaluation context) | + +To reach several tag sets, such as a region and a tier, add a **Tenant tags** condition for each tag set. A rule with `Region` is one of `Australia`, `Europe` AND `Tier` is one of `Enterprise` matches enterprise tenants in either Australia or Europe. + +## Rule limits + +Each environment on a flag has limits on how many rules and conditions it can hold. These limits apply to every project that uses feature flag rules. + +| Item | Limit | +| --- | --- | +| Conditions in a rule | 100 | +| Rules in an environment, counted across all its phases | 100 | +| Phases in an environment | 50 | + +A rule needs at least one condition. An environment that needs more than 100 rules usually needs fewer, broader rules, such as a tenant tag in place of a list of individual tenants. + +## Pass evaluation context from your application {#evaluation-context} + +The evaluation context is the information about the current user that your application passes to OpenFeature when it evaluates a flag. **Context attribute** conditions and **Percentage** conditions by targeting keys only work when your application supplies it. + +The evaluation context has 2 parts: + +- The **targeting key**: one value that uniquely identifies whoever you're evaluating the flag for. Percentage conditions by targeting keys use it to decide who's in the percentage. For most applications, this is a user ID, but it can be any stable identifier, such as an account, a team, or a server instance. +- **Attributes**: key/value pairs that **Context attribute** conditions match against, such as `region: eu`, `license-type: free`, or `ring: early-adopter`. + +To pass evaluation context: + +1. Choose a targeting key that stays the same for a user across sessions. +2. Build an OpenFeature evaluation context with the targeting key and any attributes your rules use. +3. Pass the evaluation context when you evaluate the flag, or set it on the OpenFeature client so every evaluation uses it. + +For example, in C#: + +```cs +var context = EvaluationContext.Builder() + .SetTargetingKey(user.Id) + .Set("region", user.Region) + .Set("license-type", user.LicenseType) + .Build(); + +var darkModeEnabled = await featureClient.GetBooleanValueAsync("dark-mode", false, context); +``` + +For other languages, and for setting context once for every evaluation, see the [OpenFeature evaluation context documentation](https://openfeature.dev/docs/reference/concepts/evaluation-context). + +:::div{.warning} +If your application doesn't set a targeting key, a **Percentage** condition by targeting keys doesn't match unless the percentage is 100%. [VERIFY: that a missing targeting key still fails to match for rule-based flags, as it did for client rollout percentages — needs: confirmation from the feature flags team] +::: + +Attribute keys and values are case-sensitive, so `Region` and `region` are different attributes. [VERIFY: that context attribute matching is case-sensitive for both keys and values — needs: confirmation of OctoToggle condition matching] + +## Related links + +- [How feature flag evaluation works](/docs/feature-flags/how-evaluation-works) +- [Rolling out feature flags in phases](/docs/feature-flags/phased-rollouts) +- [Previewing feature flag evaluations](/docs/feature-flags/previewing-evaluations) +- [Managing rollout groups](/docs/feature-flags/rollout-groups) +- [OpenFeature providers](/docs/feature-flags/providers) diff --git a/src/pages/docs/feature-flags/targeting.md b/src/pages/docs/feature-flags/targeting.md index ccc0fda23a..f20db173ff 100644 --- a/src/pages/docs/feature-flags/targeting.md +++ b/src/pages/docs/feature-flags/targeting.md @@ -1,125 +1,9 @@ --- -layout: src/layouts/Default.astro -pubDate: 2026-04-20 -modDate: 2026-06-18 -title: Targeting -subtitle: Configure rollout within an environment -icon: fa-solid fa-bullseye -navTitle: Targeting -navSection: Feature Flags -description: Targeting options for Octopus Feature Flags -navOrder: 96 +layout: src/layouts/Redirect.astro +title: Redirect +redirect: https://octopus.com/docs/feature-flags/legacy/targeting +pubDate: 2026-11-05 +navSearch: false +navSitemap: false +navMenu: false --- - -## Minimum version - -You can configure a feature flag to require a minimum version before being enabled in an environment. The flag will be enabled once that version (or any later version) is deployed to that environment. - -![Screenshot of feature flag environment drawer, minimum version section is expanded, minimum version input has value 12.1.0](/docs/img/feature-flags/minimum-version.png) - -## Tenants {#tenants} - -If your project uses [Tenants](/docs/tenants/), you can configure a feature flag to be enabled for subsets of your tenants within an environment. - -There are many options for configuring a feature flag for tenants. These are all modeled in Octopus and do not require any custom configuration in application code. - -### Excluded tenants - -You can exclude tenants individually or exclude groups of tenants using tenant tags. Excluded tenants will always override any other rollout configuration, even if the rollout percentage is set to 100%. - -![Screenshot of feature flag environment drawer, excluded tenants section expanded, tenants to exclude multi-select has Acme Corporation and Contoso Ltd tenants selected, tenant tags to exclude multi-select has Tier/Enterprise tag selected](/docs/img/feature-flags/excluded-tenants.png) - -Once a feature flag is configured with an excluded tenant tag, any changes to tenant tag assignments apply immediately to feature flags (no update to the feature flag configuration is required). - -### Included tenants - -You can enable feature flags for individual tenants. These tenants will always be included, even if the tenant rollout percentage is set to 0%. - -![Screenshot of feature flag environment drawer, included tenants section expanded, tenants to include multi-select has Acme Corporation selected, tenant rollout percentage and tenant tags to include in rollout inputs are empty](/docs/img/feature-flags/included-tenants.png) - -### Tenant rollout - -Tenant rollout allows you to enable a flag for a pseudorandom percentage of all tenants. - -The included tenants are determined using a MurmurHash of the tenant ID and a flag-specific key. This guarantees deterministic evaluation for any given tenant and flag combination, while ensuring that a different set of tenants is included for each flag. - -![Screenshot of feature flag environment drawer, included tenants section expanded, tenants to include is empty, tenant rollout percentage is set to 50% and tenant tags to include in rollout multi-select has Tier/Free, Region/Australia, and Region/Europe selected](/docs/img/feature-flags/tenant-rollout.png) - -You can further restrict the rollout using tenant tags. For example, if you specify `Region/Australia`, `Region/Europe`, and `Tier/Enterprise`, a 50% rollout will only apply to 50% of Enterprise tenants in either Australia or Europe. If you do not specify any tenant tags, a 50% rollout will apply to 50% of all tenants. - -As with excluded tenants, any changes to tenant tags apply immediately to feature flags. - -## Client rollout - -Client rollout allows you to enable a flag for a random percentage of your application users. The included users are determined using a MurmurHash of the [OpenFeature Targeting Key](https://openfeature.dev/docs/reference/concepts/evaluation-context#targeting-key) and a flag-specific key. This guarantees deterministic evaluation for any given user and flag combination. - -To use client rollout, you must configure a targeting key in your OpenFeature client. Refer to the [OpenFeature SDK](https://openfeature.dev/docs/reference/sdks/) documentation for your development language for details on how to set the targeting key. If you do not set a targeting key, the feature flag will not be enabled for any users unless the rollout is set to 100%. - -You should set the targeting key to a value that uniquely identifies your evaluation subject. For most applications, this will be a user identifier (such as a user ID), but you can use any identifier that suits your needs (for example, team, region, or server instance). - -:::div{.hint} -Support for client rollout percentages was added in the following versions of the [provider libraries](/docs/feature-flags/providers): - -- [.NET: `2.1.0`](https://github.com/OctopusDeploy/openfeature-provider-dotnet/releases/tag/v2.1.0) -- [Java: `0.3.0`](https://github.com/OctopusDeploy/openfeature-provider-java/releases/tag/0.3.0) -- [TypeScript/JavaScript: `3.0.0`](https://github.com/OctopusDeploy/openfeature-provider-ts-web/releases/tag/v3.0.0) - -If you are not running the required minimum version of these libraries, the rollout percentage will be ignored (and handled as if the value was set to 100%). -::: - -### Segments {#segments} - -Segments allow you to further refine the client rollout for a flag based on data that is not modeled in Octopus. Segments are key/value pairs, and are supplied by your application via the [OpenFeature evaluation context](https://openfeature.dev/docs/reference/concepts/evaluation-context). - -Like tenant targeting, segments are configured per-environment on the feature flag in Octopus. - -![Screenshot of feature flag environment drawer, client rollout section expanded, client rollout percentage is set to 50% with 3 segments region/eu, region/au, and ring/early-adopter](/docs/img/feature-flags/segments.png) - -Refer to the [OpenFeature SDK](https://openfeature.dev/docs/reference/sdks/) documentation for your development language for more details on how to set these values. - -Common segment examples include: - -- Specific users (e.g. `user-id/123456`) -- Specific accounts (e.g. `account-id/123456`) -- License types (e.g. `license-type/free`) -- Geographic regions (e.g. `region/eu`) -- Rollout rings (e.g. `ring/early-adopter`) - -A feature flag evaluation will match on segments if the evaluation context matches at least one segment for each key. If you specify `ring/early-adopter`, `region/eu`, and `region/au`, the rollout will apply only to users in the early-adopter ring who are in either the EU or AU regions. If you do not specify any segments, the rollout will apply to all users. - -Some examples: - -| Segments | Evaluation Context | Result | -|------------------------------------------------|-----------------------------------|--------| -| `user-id/123456` | `user-id/123456` | `On` | -| `user-id/123456` | `user-id/789383` | `Off` | -| `ring/early-adopter`, `region/eu`, `region/au` | `ring/early-adopter`, `region/eu` | `On` | -| `ring/early-adopter`, `region/eu`, `region/au` | `ring/early-adopter`, `region/au` | `On` | -| `ring/early-adopter`, `region/eu`, `region/au` | `license-type/free` | `Off` | -| `ring/early-adopter`, `region/eu`, `region/au` | `region/au` | `Off` | - -## Rollout groups {#rollout-groups} - -By default, a percentage rollout on one feature flag will include a different set of tenants or clients than the same percentage rollout on another flag. This ensures the same tenants or clients are not always the first to receive every new feature. - -Rollout groups let you connect rollout evaluation between multiple feature flags so that the same tenants or clients are included in the rollout across those flags. This can be useful when you have related features that should roll out to the same audience. - -You can assign a rollout group to a feature flag from the feature flag page by selecting a group from the rollout group dropdown. - -![Screenshot of feature flag page showing rollout group selector expanded with new onboarding flow group selected](/docs/img/feature-flags/rollout-group-selector.png) - -:::div{.warning} -If you have a tenant or client rollout configured, adding, changing, or removing a rollout group on a feature flag will change which tenants or clients are included in that rollout. -::: - -### Managing rollout groups - -You can manage rollout groups from the rollout groups page. To access this page, open the overflow menu on the feature flags list page and select **Manage Rollout Groups**. - -![Screenshot of feature flags list page with overflow menu expanded highlighting the manage rollout groups button](/docs/img/feature-flags/manage-rollout-group-overflow.png) - -From the rollout groups page, you can add, rename, and delete rollout groups. - -![Screenshot of rollout group list page with a single rollout group named new onboarding flow, used by the live chat and AI recommendations feature flags, with the overflow menu expanded and showing edit and delete options](/docs/img/feature-flags/rollout-group-page.png) - -You cannot delete a rollout group that is assigned to one or more feature flags. To delete a rollout group, first remove it from all feature flags that use it. diff --git a/src/pages/docs/feature-flags/upgrading-to-rules.md b/src/pages/docs/feature-flags/upgrading-to-rules.md new file mode 100644 index 0000000000..89cf624552 --- /dev/null +++ b/src/pages/docs/feature-flags/upgrading-to-rules.md @@ -0,0 +1,76 @@ +--- +layout: src/layouts/Default.astro +pubDate: 2026-11-05 +modDate: 2026-11-05 +title: Upgrading to feature flag rules +sidebarLabel: Upgrading to rules +navTitle: Upgrading to rules +navSection: Feature Flags +navOrder: 90 +icon: fa-solid fa-circle-up +description: Move an Octopus project's feature flags to rules and phases, and learn how existing targeting converts so your flags keep behaving the same. +subject: feature flags, rules, upgrade, migration, legacy feature flags, targeting +type: guide +audience: [app-dev, devops-eng] +image: +imageAlt: +--- + +Projects that had feature flags before feature flag rules were introduced keep using the legacy way of configuring flags until you upgrade them. This page explains what the upgrade changes, how your existing targeting converts to rules, and how to upgrade a project. + +## The upgrade to feature flag rules + +The upgrade moves a project's feature flags from the legacy targeting settings to [rules](/docs/feature-flags/rules) and [phases](/docs/feature-flags/phased-rollouts). Octopus converts every flag in the project, so each flag targets the same tenants and users after the upgrade as it did before. You don't need to set up any flags again. + +You upgrade one project at a time, and an upgrade can't be undone. New projects, and existing projects that don't have any feature flags yet, already use rules and don't need upgrading. + +The upgrade changes what Octopus publishes to the feature flag service. Applications on a provider version that supports rules get every change you make after the upgrade. Applications on an earlier provider version keep the flag values they had at the upgrade, but don't see any changes after it. Upgrade the provider in every application that uses the project's flags before you upgrade the project. See [OpenFeature providers](/docs/feature-flags/providers) for the minimum versions. + +## How legacy settings convert to rules + +This table lists each legacy targeting setting on an environment and the rule condition it becomes. Each environment with targeting gets one phase, named `Phase 1`, that's on. An environment with no targeting, or with a 100% tenant rollout and no other settings, gets no rules and stays on for everyone. + +| Legacy setting | Becomes | +| --- | --- | +| **Minimum version** | **Minimum version**: Version is at least, in every rule | +| **Tenants to exclude** | **Tenants**: not one of, in every rule | +| **Tenant tags to exclude** | **Tenant tags**: not one of, one condition for each tag set, in every rule | +| **Tenants to include** | **Tenants**: one of, in a rule of its own when the environment also has a tenant rollout | +| **Tenant rollout percentage** | **Percentage** by tenants, when it's less than 100% | +| **Tenant tags to include in rollout** | **Tenant tags**: one of, one condition for each tag set | +| **Client rollout percentage** | **Percentage** by targeting keys, in every rule, when it's less than 100% | +| Segments | **Context attribute**: one of, one condition for each segment key, in every rule | + +Because rules combine with OR, the legacy "included tenants OR tenant rollout" becomes 2 rules, and every other setting is repeated in both. For example, an environment with a minimum version of `2.0.0`, the included tenant `Acme Corporation`, and a 50% tenant rollout converts to: + +- **Rule 1**: Version is at least `2.0.0` AND tenant is one of `Acme Corporation` +- **Rule 2**: Version is at least `2.0.0` AND 50% of tenants + +## Upgrade a project to feature flag rules + +Upgrade a project when you're ready to use rules and phases for its feature flags. After the upgrade, the project's flags open in the rules editor. + +**Before you begin** + +You'll need: + +- Every application that uses the project's feature flags on a provider version that supports rules. See [OpenFeature providers](/docs/feature-flags/providers). +- [VERIFY: the permission required to upgrade a project — needs: confirmation from the feature flags team] + +To upgrade a project to feature flag rules: + +1. From your project, select **Feature Flags**. +2. In the **Upgrade to feature flag rules** callout, select **Upgrade project**. +3. Check the minimum provider versions listed in the dialog against your applications. +4. Type `Upgrade` to confirm. +5. Select **Upgrade**. + +The callout no longer appears on the **Feature Flags** page, and each environment with targeting shows its converted rules. To check that every flag still targets the same users, see [Previewing feature flag evaluations](/docs/feature-flags/previewing-evaluations). + +## Related links + +- [Feature flags](/docs/feature-flags) +- [Targeting users with feature flag rules](/docs/feature-flags/rules) +- [Rolling out feature flags in phases](/docs/feature-flags/phased-rollouts) +- [OpenFeature providers](/docs/feature-flags/providers) +- [Legacy feature flags](/docs/feature-flags/legacy) diff --git a/src/pages/docs/feature-toggles/targeting.md b/src/pages/docs/feature-toggles/targeting.md index f5441e03f3..5aaaf4af58 100644 --- a/src/pages/docs/feature-toggles/targeting.md +++ b/src/pages/docs/feature-toggles/targeting.md @@ -1,7 +1,7 @@ --- layout: src/layouts/Redirect.astro title: Redirect -redirect: https://octopus.com/docs/feature-flags/targeting +redirect: https://octopus.com/docs/feature-flags/legacy/targeting pubDate: 2026-06-18 navSearch: false navSitemap: false