diff --git a/frontend/src/component/environments/EnvironmentTable/EnvironmentActionCell/EnvironmentCloneModal/EnvironmentCloneModal.tsx b/frontend/src/component/environments/EnvironmentTable/EnvironmentActionCell/EnvironmentCloneModal/EnvironmentCloneModal.tsx
index ffca6514a1..8076b46809 100644
--- a/frontend/src/component/environments/EnvironmentTable/EnvironmentActionCell/EnvironmentCloneModal/EnvironmentCloneModal.tsx
+++ b/frontend/src/component/environments/EnvironmentTable/EnvironmentActionCell/EnvironmentCloneModal/EnvironmentCloneModal.tsx
@@ -238,7 +238,7 @@ export const EnvironmentCloneModal = ({
modal
title={`Clone ${environment.name} environment`}
description='Cloning an environment will clone all feature flags and their configuration (activation strategies, segments, status, etc) into a new environment.'
- documentationLink='https://docs.getunleash.io/reference/environments#cloning-environments'
+ documentationLink='https://docs.getunleash.io/reference/environments#clone-an-environment'
documentationLinkLabel='Cloning environments documentation'
formatApiCode={formatApiCode}
>
diff --git a/src/lib/routes/admin-api/environments.ts b/src/lib/routes/admin-api/environments.ts
index 9232c3bf5c..3780f2ed53 100644
--- a/src/lib/routes/admin-api/environments.ts
+++ b/src/lib/routes/admin-api/environments.ts
@@ -104,7 +104,7 @@ export class EnvironmentsController extends Controller {
operationId: 'getProjectEnvironments',
summary: 'Get the environments available to a project',
description:
- 'Gets the environments that are available for this project. An environment is available for a project if enabled in the [project configuration](https://docs.getunleash.io/reference/environments#step-1-enable-new-environments-for-your-project)',
+ 'Gets the environments that are available for this project. An environment is available for a project if enabled in the [project configuration](https://docs.getunleash.io/reference/environments#enable-an-environment)',
responses: {
200: createResponseSchema('environmentsProjectSchema'),
...getStandardResponses(401, 403, 404),
diff --git a/website/docs/how-to/how-to-clone-environments.mdx b/website/docs/how-to/how-to-clone-environments.mdx
deleted file mode 100644
index 61ddf33dde..0000000000
--- a/website/docs/how-to/how-to-clone-environments.mdx
+++ /dev/null
@@ -1,39 +0,0 @@
----
-title: How to clone environments
----
-
-:::note Availability
-
-**Plan**: [Enterprise](https://www.getunleash.io/plans/enterprise) | **Version**: `4.19+`
-
-:::
-
-[Environment cloning](../reference/environments.md#cloning-environments) enables Unleash admins to duplicate existing environments, including all feature flags strategies and their state.
-
-## Step 1: Navigate to the environments page {#step-1}
-
-Navigate to the _Environments_ page in the admin UI (available at the URL `/environments`). Use the navigation menu item "Configure" and select "Environments".
-
-
-
-## Step 2: Select an environment to clone {#step-2}
-
-Select an environment to clone. On the right side, open the actions submenu and select "Clone".
-
-
-
-## Step 3: Fill in the clone environment form {#step-3}
-
-Give your new environment a name. The name must be unique and cannot be the same as the original environment. The name is pre-filled with a suggestion, but you can change it to whatever you like.
-
-Select an environment type, which projects should have their environment configuration cloned, and whether to keep the existing user permissions for the new environment.
-
-
-
-You can optionally generate an API token for the new environment right away. Select which projects the token should have access to, and the token will be generated when you submit the form.
-
-
-
-
-
-You can always create API tokens for the new environment by following the [_Generating an API token_](../how-to/how-to-create-api-tokens.mdx) guide.
diff --git a/website/docs/reference/environments.md b/website/docs/reference/environments.md
index 7ca73e8715..0c0a5599fc 100644
--- a/website/docs/reference/environments.md
+++ b/website/docs/reference/environments.md
@@ -8,58 +8,54 @@ title: Environments
**Version**: `4.3+`
:::
+## Overview
-
-
-
+Environments represent different stages in your development lifecycle. They allow you to manage your product releases from local development to production. [Projects](/reference/projects) and [feature flags](/reference/feature-toggles) are accessible in all environments, but each environment has different feature flag configurations. This allows you to enable a flag in development or test without enabling it in production.
-Environments are a way to organize activation strategy configurations for feature flags. A feature exists in all environments, as the goal is to release it as soon as possible, but it makes sense to configure activation differently depending on the environment. [Open Source](https://www.getunleash.io/pricing) and [Pro](https://www.getunleash.io/pricing) customers have two preconfigured environments, **development** and **production**. [Enterprise](https://www.getunleash.io/pricing) customers can have unlimited environments.
+The default environments are **development** and **production**. Unleash instances created before version `4.3` also have an environment called **default**. [Enterprise](https://www.getunleash.io/pricing) customers can create, clone, deprecate, and delete environments.
-Connected applications use environment-scoped API keys to ensure they download only the relevant feature flag configurations for the environment they are running in. Unleash tracks usage metrics per environment.
-
-
+The set of all available environments is defined at the instance level. Additionally, each project can choose which of the environments are visible on the project level. The set of environments available to any given project is always a subset of the environments at the instance level. Each project must always have at least one active environment.
## Environment types
-All environments in Unleash have a **type**. When you create a new environment, you must also assign it a type.
-
-The built-in environment types are:
+Each environment has a name and one of the following types:
- Development
- Test
- Pre-production
- Production
-The **production** environment type is special: Unleash will show additional confirmation prompts when you change something that could impact users in environments of this type. The built-in "production" environment is a production-type environment.
+Meeting specific conditions in a given environment type affects a feature's [lifecycle stage](/reference/feature-toggles#feature-flag-lifecycle). For example, a feature that is receiving metrics and is exposed to users in a production environment moves to the [live](/reference/feature-toggles#live) stage. Production environments also display additional confirmation prompts for changes that may impact users. The default **production** environment is of type production.
-The other environment types do not currently have any functionality associated with them. This may change in the future.
+## Activation strategies
-## Global and project-level environments
+[Activation strategies](/reference/activation-strategies) are the component of feature flags that define who should get a feature. An activation strategy is assigned to one feature flag in one environment. For example, you can use activation strategies to show a feature only to select users in development, but roll it out to 25% of users in production.
-Environments exist on a global level, so they are available to all projects within Unleash. However, every [project](./projects) might not need to use every environment. That's why you can also choose which of the global environments should be available within a project.
+
-## How to start using environments
+## Connected applications and usage metrics
-To enable an environment for a feature flag, you must first add activation strategies for that environment. You cannot enable an environment without activation strategies.
+When connecting an SDK to Unleash, the API key determines which environment to fetch feature flag configurations for. Therefore, connected applications must use environment-scoped [API tokens](/reference/api-tokens-and-client-keys).
-### Step 1: Enable new environments for your Project
+:::caution deprecation
-Navigate to the project and choose the “environments” tab.
+The `environment` context field in SDKs is a legacy implementation and does not affect environment access.
-
+:::
-### Step 2: Configure activation strategies for the new environment
+Unleash tracks usage metrics per environment.
-From the “feature flag view” you will now be able to configure activation strategies per environment. You can also enable and disable environments here. Remember that an environment must have activation strategies before you can enable it.
+## Enable an environment
-
+To enable an environment for a feature flag, you must first add [activation strategies](#activation-strategies) for that environment. If you don't define an activation strategy, the default is a gradual rollout to 100% of users.
-### Step 3: Create environment specific API keys
+To enable a feature flag in a specific environment, do the following:
+1. In the Admin UI, navigate to the feature flag you'd like to enable in an environment.
+2. In the list of environments, click **Add strategy** for the environment you want to enable.
+3. Enter a strategy name and define the rollout percentage. Optionally, you can configure segments, constraints, and variants.
+4. Click **Save strategy**.
+5. In the **Enabled in environments** section, toggle the environment you want to enable.
-In order for the SDK to download the feature flag configuration for the correct environment you will need to create an API token for a defined environment.
-
-
-
-## Cloning environments
+## Clone an environment
:::note Availability
@@ -67,53 +63,8 @@ In order for the SDK to download the feature flag configuration for the correct
:::
-Unleash environments can be cloned. Cloning an environment creates a **new** environment based on the selected source environment. When cloning an environment, you select any number of projects whose feature flag configurations will also be cloned. These projects will have identical configurations for the source and target environments. However, the environments can then be configured independently and will not stay in sync with each other.
+Cloning an environment allows you to duplicate environments, including all feature flag strategies and their states. To clone an environment in the Admin UI, go to **Configure > Environments**. Under **Actions**, select **Clone** for the environment you want to clone.
-When cloning an environment, you must give the new environment
-- a name
-- an environment type
-- a list of projects to clone feature configurations in
-
-You can also clone user permissions into the new environment. When you do that, permissions in the new environment will be the same as in the environment you cloned from. If you don't clone permissions, only admins and project editors can make changes in the new environment. You can change permissions after creation by using [custom project roles](../reference/rbac#custom-project-roles).
-
-In order to clone an environment, you can follow the [how to clone environments](../how-to/how-to-clone-environments.mdx) guide.
-
-Once created, the new environment works just as any other environment.
-
-## Migration
-
-To ease migration we have created a special environment called **default**. All existing activation strategies have been added to this environment. All existing Client API keys have also been scoped to work against the default environment to ensure zero disruption as part of the upgrade.
-
-If you're currently using strategy constraints together with the “environment” field on the Unleash Context, you should be aware that the new environment support works slightly differently. With environments, the SDK API will use the client's API key to determine which environment the client is configured for. The API then sends _only_ strategies belonging to the client's environment. This means that you might not need the "environment" property of the Unleash Context anymore.
-
-
-
-### Integrations
-
-We have made some slight changes to events related to feature flags: there's one deprecation and several new event types. Most of the new events contain _project_ and _environment_ data.
-
-To avoid missing important updates, you will also need to update your integration configuration to subscribe to the new events.
-
-**Deprecated events:**
-
-- **FEATURE_UPDATE** - _not used after switching to environments_
-
-**New Events**
-
-- **FEATURE-METADATA-UPDATED** - The feature flag metadata was updated (across all environments).
-- **FEATURE-STRATEGY-ADD**¹ - An activation strategy was added to a feature flag in an environment. The _data_ will contain the updated strategy configuration.
-- **FEATURE-STRATEGY-UPDATE**¹ - An activation strategy was updated for a feature flag. The _data_ will contain the updated strategy configuration.
-- **FEATURE-STRATEGY-REMOVE**¹ - An activation strategy was removed for a feature flag.
-- **FEATURE-ENVIRONMENT-ENABLED**¹ - Signals that a feature flag has been _enabled_ in a defined environment.
-- **FEATURE-ENVIRONMENT-DISABLED**¹ - Signals that a feature flag has been _disabled_ in a defined environment.
-- **FEATURE-PROJECT-CHANGE**¹ - The feature flag was moved to a new project.
-
-> 1. These feature events will contain _project_ and _environment_ as part of the event metadata.
-
-### API
-
-In order to support configuration per environment we had to rebuild our feature flag admin API to account for environments as well. This means that we're making the following changes to the API:
-
-- **/api/admin/features** - _deprecated (scheduled for removal in Unleash v5.0). The [old feature flags admin API](/reference/api/legacy/unleash/admin/features.md) still works, but strategy configuration will be assumed to target the “default” environment._
-- **/api/admin/projects/:projectId/features** - New feature API to be used for feature flags which also adds support for environments. See [the documentation](/reference/api/legacy/unleash/admin/features.md) to learn more.
+Cloning an environment creates a copy of the selected source environment. You can select which projects to clone the environment configuration in. This means that the default visibility of the source environment, as well as any feature flag configurations, are cloned in the new environment. For example, if a feature flag had a gradual rollout to 67% in the source environment, then your new environment will have the same feature enabled with the same activation strategy in the new environment. After cloning, the environments are independent and do not stay in sync.
+You can also clone the [user permissions](/reference/rbac) of the source environment. If you don't clone permissions, only Admins and Editors can make changes in the new environment.
\ No newline at end of file
diff --git a/website/docs/reference/feature-toggles.mdx b/website/docs/reference/feature-toggles.mdx
index 578464dfb9..5f0784b744 100644
--- a/website/docs/reference/feature-toggles.mdx
+++ b/website/docs/reference/feature-toggles.mdx
@@ -95,23 +95,23 @@ These insights can help you improve the efficiency of your software development
#### Initial
-The feature flag is created, but Unleash hasn't detected any metrics in any environments. Once Unleash receives metrics from a non-production environment, the flag moves to the [pre-live](#pre-live) stage.
+The feature flag is created, but Unleash hasn't detected any metrics in any environments. Once Unleash receives metrics from a [non-production environment](/reference/environments#environment-types), the flag moves to the [pre-live](#pre-live) stage.
A feature stuck in an initial stage can indicate integration issues in pre-production setups.
#### Pre-live
-The feature flag has received metrics in a non-production environment or a production environment that is disabled. Too much time in the pre-live stage can suggest challenges in achieving production readiness.
+The feature flag has received metrics in a non-production environment or a [production environment](/reference/environments#environment-types) that is disabled. Too much time in the pre-live stage can suggest challenges in achieving production readiness.
#### Live
-The first users have been exposed to the feature in a production environment. Once you have enough production usage data, you can mark the feature as completed. Marking the feature flag as complete does not affect any configuration; you decide whether to keep the feature, keep just one variant of it, or archive it entirely.
+The first users have been exposed to the feature in a [production environment](/reference/environments#environment-types). Once you have enough production usage data, you can mark the feature as completed. Marking the feature flag as complete does not affect any configuration; you decide whether to keep the feature, keep just one variant of it, or archive it entirely.
This stage serves as a reminder to start cleaning up the feature toggle and removing it from the code. A feature flag stuck in the live stage can indicate difficulties in data gathering or decision-making.
#### Completed
-The feature has been completed but Unleash still receives usage metrics in production. This is an indication that you should clean up the feature flag from your code before archiving it.
+The feature has been completed but Unleash still receives usage metrics in [production](/reference/environments#environment-types). This is an indication that you should clean up the feature flag from your code before archiving it.
If you've accidentally marked the feature as completed, you can revert it to the [live](#live) stage.
Too much time in the completed stage can indicate delays in decommissioning the feature and cleaning up resources.
diff --git a/website/sidebars.js b/website/sidebars.js
index 8ba009dda3..7305dc5db8 100644
--- a/website/sidebars.js
+++ b/website/sidebars.js
@@ -539,7 +539,6 @@ module.exports = {
slug: '/how-to/env',
},
items: [
- 'how-to/how-to-clone-environments',
'how-to/how-to-import-export',
'how-to/how-to-environment-import-export',
],
diff --git a/website/static/img/clone-environment-1.png b/website/static/img/clone-environment-1.png
deleted file mode 100644
index 78cc19791a..0000000000
Binary files a/website/static/img/clone-environment-1.png and /dev/null differ
diff --git a/website/static/img/clone-environment-2.png b/website/static/img/clone-environment-2.png
deleted file mode 100644
index 9aff739f3f..0000000000
Binary files a/website/static/img/clone-environment-2.png and /dev/null differ
diff --git a/website/static/img/clone-environment-3.png b/website/static/img/clone-environment-3.png
deleted file mode 100644
index d69534bcbf..0000000000
Binary files a/website/static/img/clone-environment-3.png and /dev/null differ
diff --git a/website/static/img/clone-environment-4.png b/website/static/img/clone-environment-4.png
deleted file mode 100644
index 8ab2d68863..0000000000
Binary files a/website/static/img/clone-environment-4.png and /dev/null differ
diff --git a/website/static/img/clone-environment-5.png b/website/static/img/clone-environment-5.png
deleted file mode 100644
index 5798d5ca82..0000000000
Binary files a/website/static/img/clone-environment-5.png and /dev/null differ
diff --git a/website/static/img/environments-activation-strategy.png b/website/static/img/environments-activation-strategy.png
new file mode 100644
index 0000000000..6d959ca083
Binary files /dev/null and b/website/static/img/environments-activation-strategy.png differ
diff --git a/website/static/img/environments_api_keys.png b/website/static/img/environments_api_keys.png
deleted file mode 100644
index 4400d3f18f..0000000000
Binary files a/website/static/img/environments_api_keys.png and /dev/null differ
diff --git a/website/static/img/environments_configure.png b/website/static/img/environments_configure.png
deleted file mode 100644
index 7fa4d7741b..0000000000
Binary files a/website/static/img/environments_configure.png and /dev/null differ
diff --git a/website/static/img/environments_overview.svg b/website/static/img/environments_overview.svg
deleted file mode 100644
index ee6eafb4e5..0000000000
--- a/website/static/img/environments_overview.svg
+++ /dev/null
@@ -1 +0,0 @@
-
\ No newline at end of file
diff --git a/website/static/img/environments_strategies.png b/website/static/img/environments_strategies.png
deleted file mode 100644
index 60c2c93f81..0000000000
Binary files a/website/static/img/environments_strategies.png and /dev/null differ
diff --git a/website/static/img/environments_strategy_constraints.png b/website/static/img/environments_strategy_constraints.png
deleted file mode 100644
index bea78f04be..0000000000
Binary files a/website/static/img/environments_strategy_constraints.png and /dev/null differ
diff --git a/website/vercel.json b/website/vercel.json
index 7f1fa77a90..157b34ef2b 100644
--- a/website/vercel.json
+++ b/website/vercel.json
@@ -111,6 +111,11 @@
"destination": "/reference/feature-toggles#set-a-naming-pattern",
"permanent": true
},
+ {
+ "source": "/how-to/how-to-clone-environments",
+ "destination": "/reference/environments#clone-an-environment",
+ "permanent": true
+ },
{
"source": "/toggle_variants",
"destination": "/reference/feature-toggle-variants",