Add doc for environment state - #3319
Conversation
yangguoif
changed the title
|
Pull request environment is available at https://stoctodocspr3319.z22.web.core.windows.net. You can view the ephemeral environment status in Octopus Deploy. This environment will be automatically deprovisioned when the pull request is closed, or after 7 days of inactivity. |
75be84c to
746257b
Compare
|
|
||
| ## Availability | ||
|
|
||
| Environment state is available to all cloud and self-hosted customers from version `2026.3.10863`. |
There was a problem hiding this comment.
TODO: Double check the rollout plan and the version number here.
| ## How environment state works | ||
|
|
||
| - A step in a deployment or runbook run sets a state entry with a key and a value. | ||
| - Octopus captures the entry when the step completes successfully, and stores it based on the project, environment, and tenant that the deployment or runbook run is executing against. | ||
| - Later deployment or runbook run for the same project, environment, and tenant, can read the value from a variable named `Octopus.Environment.State[key]`. |
There was a problem hiding this comment.
🤔 yeah I think we prob don't really need it, customers prob don't really care about how it works from the Octopus side, just how they use it
geofflamrock
left a comment
geofflamrock
left a comment
There was a problem hiding this comment.
This looks pretty good, I've left a few small suggestions and questions, happy to pair on working through anything here.
| ## How environment state works | ||
|
|
||
| - A step in a deployment or runbook run sets a state entry with a key and a value. | ||
| - Octopus captures the entry when the step completes successfully, and stores it based on the project, environment, and tenant that the deployment or runbook run is executing against. | ||
| - Later deployment or runbook run for the same project, environment, and tenant, can read the value from a variable named `Octopus.Environment.State[key]`. |
There was a problem hiding this comment.
🤔 yeah I think we prob don't really need it, customers prob don't really care about how it works from the Octopus side, just how they use it
|
|
||
| Environment state lets a deployment or [runbook](/docs/runbooks) run save key/value pairs scoped to the combination of project, environment, and optionally a tenant. Later deployments and runbook runs for the same project and environment can then read those values back. | ||
|
|
||
| Environment state addresses a common problem with [ephemeral environments](/docs/infrastructure/ephemeral-environments). A provisioning runbook often creates infrastructures that later steps depend on, such as a Kubernetes namespace or an application URL. Without environment state, each step must re-derive these values, which is error-prone. Environment state records each value once, so every later deployment, runbook run, and deprovisioning runbook reads it directly from Octopus. It works with any environment, not just ephemeral ones. |
There was a problem hiding this comment.
I wonder if we could reframe this section to be about scenarios where environment state is useful, the way this currently reads is that there is a problem with ephemeral environments in Octopus, it gives it a bit of a negative spin.
Maybe something more like "Environment state can be used for a variety of scenarios such as dynamically generated data during provisioning and deprovisioning of ephemeral environments, ..." (this isn't phrased very well though), we'd need to come up with some other areas of use cases as well. Might be easiest to workshop through this one together.
|
|
||
| ## Environment URLs | ||
|
|
||
| An environment URL is a type of [environment state](/docs/infrastructure/environments/environment-state) that Octopus gives first-class support. When a deployment or runbook run of the ephemeral environment sets an environment URL, Octopus shows it as a clickable link in the table on the Ephemeral Environments page, so anyone reviewing the environment can open the running app without digging through task logs. To set an environment URL from a deployment or runbook step, see [Setting an environment URL](/docs/infrastructure/environments/environment-state#setting-an-environment-url). |
There was a problem hiding this comment.
Some small potential tweaks to make this a bit more specific to ephemeral environments and to reduce some of the "developery" language like "digging into" which I'm not sure we use in our customer facing docs. I'm also not entirely sure on the "first-class support" language and whether we use want to use that in docs?
| An environment URL is a type of [environment state](/docs/infrastructure/environments/environment-state) that Octopus gives first-class support. When a deployment or runbook run of the ephemeral environment sets an environment URL, Octopus shows it as a clickable link in the table on the Ephemeral Environments page, so anyone reviewing the environment can open the running app without digging through task logs. To set an environment URL from a deployment or runbook step, see [Setting an environment URL](/docs/infrastructure/environments/environment-state#setting-an-environment-url). | |
| An environment URL is a type of [environment state](/docs/infrastructure/environments/environment-state) that Octopus gives first-class support. When an environment URL is set during a provisioning runbook or deployment, Octopus shows it as a clickable link in the table on the Ephemeral Environments page, making it easy to open the running application without needing to look through task logs. To set an environment URL from a deployment or runbook step, see [Setting an environment URL](/docs/infrastructure/environments/environment-state#setting-an-environment-url). |
|
|
||
| Octopus then shows the `App` URL as a clickable link on the Ephemeral Environments page: | ||
|
|
||
|  |
There was a problem hiding this comment.
From memory we have some conventions we use for screenshots when it comes to project names etc. we probably don't want to adjust the screenshot to use those.
Co-authored-by: Geoff Lamrock <geoff.lamrock@gmail.com>
3 participants
Background
BMBB-661 : Support for Environment State is added into Octopus, we should update related doc in Environment and Ephemeral Environment.
What's changed
This PR
How to review
Proof reading is highly appreciated. Please checkout the preview built by CI (after CI shows green tick), recommend starting from
docs/projects/ephemeral-environments#environment-urls, clicking the link to check the doc related to Environment State.