diff --git a/public/docs/projects/ephemeral-environments/confirm-ephemeral-environments-configuration.png b/public/docs/projects/ephemeral-environments/confirm-ephemeral-environments-configuration.png index 59e54e2ace..be9903c5f3 100644 Binary files a/public/docs/projects/ephemeral-environments/confirm-ephemeral-environments-configuration.png and b/public/docs/projects/ephemeral-environments/confirm-ephemeral-environments-configuration.png differ diff --git a/public/docs/projects/ephemeral-environments/deprovision-ephemeral-environment.png b/public/docs/projects/ephemeral-environments/deprovision-ephemeral-environment.png index f4889b129d..fc0b4e29d2 100644 Binary files a/public/docs/projects/ephemeral-environments/deprovision-ephemeral-environment.png and b/public/docs/projects/ephemeral-environments/deprovision-ephemeral-environment.png differ diff --git a/public/docs/projects/ephemeral-environments/ephemeral-environment-settings.png b/public/docs/projects/ephemeral-environments/ephemeral-environment-settings.png index f3c77d6a8b..d1e05b83e2 100644 Binary files a/public/docs/projects/ephemeral-environments/ephemeral-environment-settings.png and b/public/docs/projects/ephemeral-environments/ephemeral-environment-settings.png differ diff --git a/public/docs/projects/ephemeral-environments/ephemeral-environments-configured.png b/public/docs/projects/ephemeral-environments/ephemeral-environments-configured.png index c60f006dce..a49b746702 100644 Binary files a/public/docs/projects/ephemeral-environments/ephemeral-environments-configured.png and b/public/docs/projects/ephemeral-environments/ephemeral-environments-configured.png differ diff --git a/public/docs/projects/ephemeral-environments/getting-started.png b/public/docs/projects/ephemeral-environments/getting-started.png index a138cb7096..543653caff 100644 Binary files a/public/docs/projects/ephemeral-environments/getting-started.png and b/public/docs/projects/ephemeral-environments/getting-started.png differ diff --git a/public/docs/projects/ephemeral-environments/viewing-ephemeral-environments.png b/public/docs/projects/ephemeral-environments/viewing-ephemeral-environments.png index 6f40dd7f52..08bf3f636d 100644 Binary files a/public/docs/projects/ephemeral-environments/viewing-ephemeral-environments.png and b/public/docs/projects/ephemeral-environments/viewing-ephemeral-environments.png differ diff --git a/src/pages/docs/projects/ephemeral-environments/index.md b/src/pages/docs/projects/ephemeral-environments/index.md index c0d24b2456..6d1bfde352 100644 --- a/src/pages/docs/projects/ephemeral-environments/index.md +++ b/src/pages/docs/projects/ephemeral-environments/index.md @@ -1,7 +1,7 @@ --- layout: src/layouts/Default.astro -pubDate: 2025-09-08 -modDate: 2025-09-08 +pubDate: 2025-10-17 +modDate: 2025-10-17 title: Ephemeral Environments navTitle: Ephemeral Environments navSection: Ephemeral Environments @@ -17,7 +17,7 @@ Support for Ephemeral Environments is rolling out as an Early Access Preview to Ephemeral environments integrate smoothly into your existing development workflows by building on existing Octopus features such as [Releases](/docs/releases), [Channels](/docs/releases/channels) and [Runbooks](/docs/runbooks). -Octopus will automatically create and deploy to an ephemeral environment from releases created within a specifically configured channel in a project, and supports provisioning and deprovisioning of associated infrastructure using Runbooks. +Octopus can automatically create and deploy to an ephemeral environment from releases created within a specifically configured channel in a project, and supports provisioning and deprovisioning of associated infrastructure using Runbooks. ## Getting started @@ -41,11 +41,19 @@ Enter the name for a new parent environment or select an existing parent environ Give your parent environment a recognizable name that describes what you intend to use ephemeral environments for. Examples might include "Pull request environments" or "Test environments". ::: -### Naming +### Auto Deploy -Octopus will automatically provision a new ephemeral environment for you from releases in your project. The name of each environment can be configured using an Environment Name Template. Templates support the same powerful syntax as Variables. Any [system variable for a release](/docs/projects/variables/system-variables#release) can be used as part of the template. +You can choose to automatically deploy releases to ephemeral environments when they created. This can help to streamline your workflows by reducing the number of manual steps required to get your changes deployed. -Enter a template and click Next. +When auto deployment is configured, Octopus will automatically create a new ephemeral environment for you from releases in your project. The name of each environment can be configured using an Environment Name Template. Templates support the same powerful syntax as Variables. Any [system variable for a release](/docs/projects/variables/system-variables#release) can be used as part of the template. + +When auto deployment is not configured, you need to manually create ephemeral environments and deploy releases to them. You can do this using the Octopus Portal, API and CLI. +You can also select to manually create and deploy to an environment. + +Select whether to automatically deploy releases to ephemeral environments. +If you select to automatically deploy, you will also have to provide an environment name template that will be used to name the environment. + +#### Environment Name Template :::div{.hint} **Tips:** @@ -56,7 +64,7 @@ Enter a template and click Next. ::: -#### Custom Fields +##### Custom Fields Releases support Custom Fields which can be used to configure the name of an ephemeral environment. See [Using custom fields in releases](/docs/releases/creating-a-release#custom-fields) for more information. @@ -90,7 +98,7 @@ Review the selected configuration and click Confirm. You can go back and adjust ![Confirming the configuration of ephemeral environments for a project](/docs/projects/ephemeral-environments/confirm-ephemeral-environments-configuration.png) -Ephemeral environments are now configured for your project. A new channel has been created in the project which will automatically create and deploy to a new environment for each release. +Ephemeral environments are now configured for your project. A new channel has been created in the project to manage the creation and deployment of ephemeral environments. Click **Got it** to continue to creating a new environment from a release. @@ -98,7 +106,11 @@ Click **Got it** to continue to creating a new environment from a release. ## Creating an ephemeral environment -To create an ephemeral environment, create a release in the new channel configured within the project. Octopus will automatically create a new environment and deploy the release to it. +### Automatically + +Octopus can automatically create an ephemeral environment when a release is created in the channel configured for ephemeral environments if automatic deployments is selected. + +To create an ephemeral environment, create a release in the new channel configured within the project. Octopus will create a new environment and deploy the release to it. A release can be created using the: @@ -116,6 +128,16 @@ Remember to provide any custom fields with the release that are used in the envi Support for providing custom fields is not yet available in the Octopus CLI. ::: +### Manually + +If automatic deployments is not selected, ephemeral environments can be created from the Ephemeral Environments page within the project. + +To create an ephemeral environment manually: +- Select **Add Ephemeral Environment** from the Ephemeral Environments page. +- Enter a name for the environment. + +The environment will now be created in the Not Provisioned state, ready for a release to be deployed to it. Provisioning will be performed automatically by the configured runbook when a release is deployed to the environment. + ## Provisioning infrastructure Infrastructure required for an ephemeral environment can be provisioned using a runbook. Octopus will automatically run this runbook before the first deployment to the environment. @@ -136,7 +158,13 @@ Environments can be filtered by name and by the current state of the environment ## Updating an existing environment -To update an existing ephemeral environment, create another release that results in the same environment name based on the template. The release will be automatically deployed into the environment. +### Automatic Deployments + +Create another release that results in the same environment name based on the environment name template. The release will be automatically deployed into the environment. + +### Manual Deployments + +Create a new release, then deploy it and select the existing environment in the Deploy to step. Octopus deploys the release to that environment without creating a new one. ## Deprovisioning an environment @@ -157,7 +185,7 @@ To deprovision an environment: ### Automatic deprovisioning of environments -Ephemeral environments can be automatically deprovisioned if they are inactive after after a configurable time period. Deploying a release to an environment or running a runbook against an environment marks the environment as still being active. +Ephemeral environments can be automatically deprovisioned if they are inactive after a configurable time period. Deploying a release to an environment or running a runbook against an environment marks the environment as still being active. :::div{.hint} By default, ephemeral environments are removed after 7 days of inactivity. @@ -206,4 +234,3 @@ The following limitations currently apply to the use of the Ephemeral Environmen - Ephemeral environments cannot be deployed to tenants. - Parent environments cannot be connected to tenants. - Ephemeral environments and parent environments cannot be used within lifecycles, deployment freezes and insights reports. -- Ephemeral environments cannot be manually created outside of releases.