From 3f199c28ae8c2b4df5069e8ad3bb178ce8c12f3e Mon Sep 17 00:00:00 2001 From: Dylan Date: Mon, 20 Apr 2026 16:07:36 +1000 Subject: [PATCH 1/4] Restructure feature toggle documentation Feature toggle documentation is now broken into 3 sections: - Overview: Introduction, getting started, and misc (default values). - Targeting: Targeting controls within an environment. - Providers: List of provider libraries. There are minimal content changes in here (other than adding a few icons and moving a few lines around where it made sense after the restructure). I'll be following this up with some other PRs to add content for all of the new features that we have added over the past few months. --- src/pages/docs/feature-toggles/index.md | 84 ++------------------- src/pages/docs/feature-toggles/providers.md | 21 ++++++ src/pages/docs/feature-toggles/targeting.md | 72 ++++++++++++++++++ 3 files changed, 99 insertions(+), 78 deletions(-) create mode 100644 src/pages/docs/feature-toggles/providers.md create mode 100644 src/pages/docs/feature-toggles/targeting.md diff --git a/src/pages/docs/feature-toggles/index.md b/src/pages/docs/feature-toggles/index.md index 367b83297f..355391c7eb 100644 --- a/src/pages/docs/feature-toggles/index.md +++ b/src/pages/docs/feature-toggles/index.md @@ -1,12 +1,13 @@ --- layout: src/layouts/Default.astro pubDate: 2025-05-21 -modDate: 2025-05-21 -title: Feature Toggles -navTitle: Feature Toggles +modDate: 2026-04-20 +title: Feature Toggles +icon: fa-solid fa-toggle-on +navTitle: Overview navSection: Feature Toggles description: Octopus Feature Toggles allow progressive delivery of changes and instant rollback -navOrder: 95 +navOrder: 95 --- Octopus Feature Toggles support toggling features on or off in real-time, without redeploying, and progressively releasing changes to subsets of your users. @@ -34,7 +35,7 @@ Octopus Feature Toggles rely on [OpenFeature](https://openfeature.dev/) as the c 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](#providers). +Configure OpenFeature to use the [Octopus Provider](/docs/feature-toggles/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 Toggle service which set of toggles to evaluate. @@ -105,79 +106,6 @@ Select your environment, and whether you want the toggle on or off. You can additionally target specific [Tenants](#tenants) or [User Segments](#segments). -## Providers {#providers} - -Below are the Octopus OpenFeature provider SDKs currently available: - -### 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) - -Configuring the providers is documented in the README files in the repositories. - -## Segments {#segments} - -Segments allow enabling a toggle for a subset of users. - -Segments are key/value pairs, and are supplied by your applications via the [OpenFeature EvaluationContext](https://openfeature.dev/docs/reference/concepts/evaluation-context). - - -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` - -The Evaluation Context can be supplied at different points in your application, for example: - -- On start-up -- During each web request -- At the evaluation site - -The following example shows adding a key/value to the evaluation context in C#. - -```cs -// The client would be injected by IoC in many cases -var client = OpenFeature.Api.Instance.GetClient(); -// The following is hard-coded, whereas a real-world use would set this dynamically -client.SetContext(EvaluationContext.Builder().Set("license-type", "free").Build()); -``` - -Segments can then be configured for Environments on the Feature Toggle in Octopus. - -![Add Segment](/docs/img/feature-toggles/segment-add.png) - -A Toggle evaluation will match on segments if the evaluation context matches at least one segment for each key. - -Some examples: - -|Segments | Evaluation Context | Result | -|-----------|--------------------|--------| -| `user-id/123456` | `user-id/123456` | `On` | -| `user-id/123456` | `user-id/789383` | `Off` | -| `license-type/free` `region/Asia` `region/EU` | `license-type/free` `region/Asia` | `On` | -| `license-type/free` `region/Asia` `region/EU` | `license-type/free` `region/US` | `Off` | - -## Tenants {#tenants} - -If your Project uses [Tenants](/docs/tenants/), then Toggles may be enabled for subsets of your Tenants. - -The options for configuring a Feature Toggle for Tenants are: - -- All Tenants -- Specific Tenants Included -- % of Tenants -- Specific Tenants Excluded - -For example, the configuration shown below will result in the Toggle evaluating as `On` for 10% of Tenants, always including `Acme` and never including `Cyberdyne Systems`. - -![Tenanted Rollout](/docs/img/feature-toggles/tenant-rollout.png) - ## Default Values {#default-values} Toggle default values are configured both on the Toggle in Octopus, and at the evaluation site in your client application. It's important to understand how these interact. diff --git a/src/pages/docs/feature-toggles/providers.md b/src/pages/docs/feature-toggles/providers.md new file mode 100644 index 0000000000..eac0ef9ef1 --- /dev/null +++ b/src/pages/docs/feature-toggles/providers.md @@ -0,0 +1,21 @@ +--- +layout: src/layouts/Default.astro +pubDate: 2026-04-20 +modDate: 2026-04-20 +title: OpenFeature Providers +icon: fa-solid fa-code +navTitle: OpenFeature Providers +navSection: Feature Toggles +description: OpenFeature providers for Octopus Feature Toggles +navOrder: 97 +--- + +These are the currently avaiable Octopus OpenFeature provider SDKs. Getting started instructions for 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-toggles/targeting.md b/src/pages/docs/feature-toggles/targeting.md new file mode 100644 index 0000000000..61a74dc1a3 --- /dev/null +++ b/src/pages/docs/feature-toggles/targeting.md @@ -0,0 +1,72 @@ +--- +layout: src/layouts/Default.astro +pubDate: 2026-04-20 +modDate: 2026-04-20 +title: Targeting +subtitle: Control rollout within an environment +icon: fa-solid fa-target +navTitle: Targeting +navSection: Feature Toggles +description: Targeting options for Octopus Feature Toggles +navOrder: 96 +--- + +## Tenants {#tenants} + +If your Project uses [Tenants](/docs/tenants/), then Toggles may be enabled for subsets of your Tenants. + +The options for configuring a Feature Toggle for Tenants are: + +- All Tenants +- Specific Tenants Included +- % of Tenants +- Specific Tenants Excluded + +For example, the configuration shown below will result in the Toggle evaluating as `On` for 10% of Tenants, always including `Acme` and never including `Cyberdyne Systems`. + +![Tenanted Rollout](/docs/img/feature-toggles/tenant-rollout.png) + +## Segments {#segments} + +Segments allow enabling a toggle for a subset of users. + +Segments are key/value pairs, and are supplied by your applications via the [OpenFeature EvaluationContext](https://openfeature.dev/docs/reference/concepts/evaluation-context). + + +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` + +The Evaluation Context can be supplied at different points in your application, for example: + +- On start-up +- During each web request +- At the evaluation site + +The following example shows adding a key/value to the evaluation context in C#. + +```cs +// The client would be injected by IoC in many cases +var client = OpenFeature.Api.Instance.GetClient(); +// The following is hard-coded, whereas a real-world use would set this dynamically +client.SetContext(EvaluationContext.Builder().Set("license-type", "free").Build()); +``` + +Segments can then be configured for Environments on the Feature Toggle in Octopus. + +![Add Segment](/docs/img/feature-toggles/segment-add.png) + +A Toggle evaluation will match on segments if the evaluation context matches at least one segment for each key. + +Some examples: + +|Segments | Evaluation Context | Result | +|-----------|--------------------|--------| +| `user-id/123456` | `user-id/123456` | `On` | +| `user-id/123456` | `user-id/789383` | `Off` | +| `license-type/free` `region/Asia` `region/EU` | `license-type/free` `region/Asia` | `On` | +| `license-type/free` `region/Asia` `region/EU` | `license-type/free` `region/US` | `Off` | \ No newline at end of file From e88240fd6929fd4b3cedb916526a406b954d1697 Mon Sep 17 00:00:00 2001 From: Dylan Date: Mon, 20 Apr 2026 16:30:03 +1000 Subject: [PATCH 2/4] Fixups --- src/pages/docs/feature-toggles/index.md | 2 +- src/pages/docs/feature-toggles/providers.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/src/pages/docs/feature-toggles/index.md b/src/pages/docs/feature-toggles/index.md index 355391c7eb..90d53544f8 100644 --- a/src/pages/docs/feature-toggles/index.md +++ b/src/pages/docs/feature-toggles/index.md @@ -104,7 +104,7 @@ Select your environment, and whether you want the toggle on or off. ![Add Environment dialog](/docs/img/feature-toggles/add-environment-dialog.png) -You can additionally target specific [Tenants](#tenants) or [User Segments](#segments). +You can additionally control rollout within an environment. See [Feature Toggle targeting](/docs/feature-toggles/targeting) for more information. ## Default Values {#default-values} diff --git a/src/pages/docs/feature-toggles/providers.md b/src/pages/docs/feature-toggles/providers.md index eac0ef9ef1..d674b30560 100644 --- a/src/pages/docs/feature-toggles/providers.md +++ b/src/pages/docs/feature-toggles/providers.md @@ -10,7 +10,7 @@ description: OpenFeature providers for Octopus Feature Toggles navOrder: 97 --- -These are the currently avaiable Octopus OpenFeature provider SDKs. Getting started instructions for these providers is documented in the README files in the repositories. +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) From 0d17ff24924ea3ddcc9627ebdbd78d94db68edb5 Mon Sep 17 00:00:00 2001 From: Dylan Date: Mon, 20 Apr 2026 16:34:26 +1000 Subject: [PATCH 3/4] Fix targeting icon --- src/pages/docs/feature-toggles/targeting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pages/docs/feature-toggles/targeting.md b/src/pages/docs/feature-toggles/targeting.md index 61a74dc1a3..884378eba3 100644 --- a/src/pages/docs/feature-toggles/targeting.md +++ b/src/pages/docs/feature-toggles/targeting.md @@ -4,7 +4,7 @@ pubDate: 2026-04-20 modDate: 2026-04-20 title: Targeting subtitle: Control rollout within an environment -icon: fa-solid fa-target +icon: fa-solid fa-bullseye navTitle: Targeting navSection: Feature Toggles description: Targeting options for Octopus Feature Toggles From 2848588c23baded94db16affc8b75ed7ce0d82ff Mon Sep 17 00:00:00 2001 From: Dylan Date: Mon, 20 Apr 2026 16:44:27 +1000 Subject: [PATCH 4/4] Fix linting errors that I've now hit --- src/pages/docs/feature-toggles/index.md | 27 ++++++++++--------- src/pages/docs/feature-toggles/providers.md | 3 ++- src/pages/docs/feature-toggles/targeting.md | 29 ++++++++++----------- 3 files changed, 30 insertions(+), 29 deletions(-) diff --git a/src/pages/docs/feature-toggles/index.md b/src/pages/docs/feature-toggles/index.md index 90d53544f8..e0aed2b1d8 100644 --- a/src/pages/docs/feature-toggles/index.md +++ b/src/pages/docs/feature-toggles/index.md @@ -13,16 +13,16 @@ navOrder: 95 Octopus Feature Toggles support toggling features on or off in real-time, without redeploying, and progressively releasing changes to subsets of your users. :::div{.hint} -Octopus Feature Toggles are currently in Alpha, available to a small set of customers. +Octopus Feature Toggles are currently in Alpha, available to a small set of customers. If you are interested in this feature please register your interest on the [roadmap card](https://roadmap.octopus.com/c/121-feature-toggles) and we'll keep you updated. ::: -## Usage +## Usage -### Create a Feature Toggle +### Create a Feature Toggle -Feature Toggles are located within Octopus Projects: +Feature Toggles are located within Octopus Projects: **Project ➜ Feature Toggles** Create a new Toggle and give it name. @@ -33,17 +33,17 @@ Create a new Toggle and give it name. Octopus Feature Toggles 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. +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-toggles/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 Toggle service which set of toggles to evaluate. :::div{.hint} -The Octopus Feature Toggle client identifier is available via the Octopus variable `Octopus.FeatureToggles.ClientIdentifier` or via the Feature Toggle UI (see below). +The Octopus Feature Toggle client identifier is available via the Octopus variable `Octopus.FeatureToggles.ClientIdentifier` or via the Feature Toggle 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 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. @@ -53,7 +53,7 @@ For applications not deployed by Octopus, or cannot have the client identifier s 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: +For example, an ASP.NET application could have an `appsettings.json` file which contained the following: ```json { @@ -81,7 +81,7 @@ await OpenFeature.Api.Instance.SetProviderAsync(octopusProvider); ### Evaluate a Toggle -The [Provider](#providers) for each language documents how to evaluate toggles. +The [Provider](/docs/feature-toggles/providers) for each language documents how to evaluate toggles. You will need the Toggle slug in order to reference the toggle in code. This can be found in the Octopus portal: @@ -95,8 +95,9 @@ var darkModeEnabled = await featureClient.GetBooleanValueAsync("dark-mode", fals The second argument is the default value. Read more about [default values](#default-values) below. -### Rollout -To enable your toggle for an environment, add the environment to the Toggle. +### Rollout + +To enable your toggle for an environment, add the environment to the Toggle. ![Add Environment button](/docs/img/feature-toggles/add-environment-button.png) @@ -108,7 +109,7 @@ You can additionally control rollout within an environment. See [Feature Toggle ## Default Values {#default-values} -Toggle default values are configured both on the Toggle in Octopus, and at the evaluation site in your client application. It's important to understand how these interact. +Toggle default values are configured both on the Toggle in Octopus, and at the evaluation site in your client application. It's important to understand how these interact. The default value on the Toggle in Octopus will be returned if the environment being evaluated has not been configured with an explicit value. @@ -120,4 +121,4 @@ The default value supplied in client code (the `false` argument in the example b ```cs var darkModeEnabled = await featureClient.GetBooleanValueAsync("dark-mode", false); -``` \ No newline at end of file +``` diff --git a/src/pages/docs/feature-toggles/providers.md b/src/pages/docs/feature-toggles/providers.md index d674b30560..dfc32340f9 100644 --- a/src/pages/docs/feature-toggles/providers.md +++ b/src/pages/docs/feature-toggles/providers.md @@ -13,9 +13,10 @@ navOrder: 97 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) +- [TypeScript/JavaScript](https://github.com/OctopusDeploy/openfeature-provider-ts-web) diff --git a/src/pages/docs/feature-toggles/targeting.md b/src/pages/docs/feature-toggles/targeting.md index 884378eba3..68d4d12cd3 100644 --- a/src/pages/docs/feature-toggles/targeting.md +++ b/src/pages/docs/feature-toggles/targeting.md @@ -13,7 +13,7 @@ navOrder: 96 ## Tenants {#tenants} -If your Project uses [Tenants](/docs/tenants/), then Toggles may be enabled for subsets of your Tenants. +If your Project uses [Tenants](/docs/tenants/), then Toggles may be enabled for subsets of your Tenants. The options for configuring a Feature Toggle for Tenants are: @@ -22,23 +22,22 @@ The options for configuring a Feature Toggle for Tenants are: - % of Tenants - Specific Tenants Excluded -For example, the configuration shown below will result in the Toggle evaluating as `On` for 10% of Tenants, always including `Acme` and never including `Cyberdyne Systems`. +For example, the configuration shown below will result in the Toggle evaluating as `On` for 10% of Tenants, always including `Acme` and never including `Cyberdyne Systems`. ![Tenanted Rollout](/docs/img/feature-toggles/tenant-rollout.png) ## Segments {#segments} -Segments allow enabling a toggle for a subset of users. +Segments allow enabling a toggle for a subset of users. Segments are key/value pairs, and are supplied by your applications via the [OpenFeature EvaluationContext](https://openfeature.dev/docs/reference/concepts/evaluation-context). - 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` +- 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` The Evaluation Context can be supplied at different points in your application, for example: @@ -60,13 +59,13 @@ Segments can then be configured for Environments on the Feature Toggle in Octopu ![Add Segment](/docs/img/feature-toggles/segment-add.png) -A Toggle evaluation will match on segments if the evaluation context matches at least one segment for each key. +A Toggle evaluation will match on segments if the evaluation context matches at least one segment for each key. Some examples: -|Segments | Evaluation Context | Result | -|-----------|--------------------|--------| -| `user-id/123456` | `user-id/123456` | `On` | -| `user-id/123456` | `user-id/789383` | `Off` | -| `license-type/free` `region/Asia` `region/EU` | `license-type/free` `region/Asia` | `On` | -| `license-type/free` `region/Asia` `region/EU` | `license-type/free` `region/US` | `Off` | \ No newline at end of file +| Segments | Evaluation Context | Result | +|-----------------------------------------------|-----------------------------------|--------| +| `user-id/123456` | `user-id/123456` | `On` | +| `user-id/123456` | `user-id/789383` | `Off` | +| `license-type/free` `region/Asia` `region/EU` | `license-type/free` `region/Asia` | `On` | +| `license-type/free` `region/Asia` `region/EU` | `license-type/free` `region/US` | `Off` |