Editorial pass over environment state docs - #3386
Conversation
|
Pull request environment is available at https://stoctodocspr3386.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. |
| Environment state lets a deployment or [runbook](/docs/runbooks) run store important values generated during the process for later use. Future deployments and runbook runs for the same project, environment, and tenant get access to these state values as variables. | ||
|
|
||
| Environment state is useful in scenarios where a value produced during one run needs to be reused later. A common example is provisioning and deprovisioning [ephemeral environments](/docs/infrastructure/ephemeral-environments). A provisioning runbook might create a Kubernetes namespace or an application URL that later deployments and the deprovisioning runbook depend on. Recording each value as environment state means Octopus stores it once, so every later run reads it directly instead of re-deriving the value. | ||
| A primary use case for environment state is provisioning and deprovisioning [ephemeral environments](/docs/infrastructure/ephemeral-environments). For example, a provisioning runbook creates a Kubernetes namespace, Azure resource group, or similar to deploy the application to for testing. The identifiers for these resources are stored as environment state values. When it comes time to deprovision the ephemeral environment the deprovisioning runbook can tear down these resources using the identifiers provided as variables. |
There was a problem hiding this comment.
More clarity, less repetition.
There was a problem hiding this comment.
Looks good but this sentence might need tweaking:
For example, if a provisioning runbook creates a Kubernetes namespace, Azure resource group, or similar to deploy the application to an ephemeral environment for testing.
Wondering if you might have accidentally control X'd 🤷♀️
There was a problem hiding this comment.
Nah, just bad writing. I like your suggestion.
There was a problem hiding this comment.
Actually, we don't need multiple examples of resources types. I'll slim it down a bit and hopefully it'll read better.
| --- | ||
|
|
||
| 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 lets a deployment or [runbook](/docs/runbooks) run store important values generated during the process for later use. Future deployments and runbook runs for the same project, environment, and tenant get access to these state values as variables. |
There was a problem hiding this comment.
Strip out some of the specifics to give an impactful introduction to the feature.
| A primary use case for environment state is provisioning and deprovisioning [ephemeral environments](/docs/infrastructure/ephemeral-environments). For example, a provisioning runbook creates a Kubernetes namespace, Azure resource group, or similar to deploy the application to for testing. The identifiers for these resources are stored as environment state values. When it comes time to deprovision the ephemeral environment the deprovisioning runbook can tear down these resources using the identifiers provided as variables. | ||
|
|
||
| Each state entry is scoped to project, environment, and optionally a tenant, so state isn't shared with other projects, environments, or tenants. Setting an entry with a key that already exists for the same project, environment, and tenant overwrites the previous value. Keys are case insensitive. | ||
| Each state entry is scoped to project, environment, and optionally a tenant, keeping them isolated. Setting an entry with a key that already exists for the same project, environment, and tenant overwrites the previous value. Keys are case insensitive. |
| ### Sensitive values | ||
|
|
||
| Mark a value as sensitive to store it encrypted at rest and mask it in task logs. Add the `-Sensitive` switch in PowerShell, or `-sensitive` as the third argument in Bash. | ||
| Mark a value as sensitive to encrypt it at rest and mask it in task logs. Add the `-Sensitive` switch in PowerShell, or `-sensitive` as the third argument in Bash. |
| ## Using environment state | ||
|
|
||
| Octopus makes each state entry available as a [variable](/docs/projects/variables) named `Octopus.Environment.State[key]` in later deployment or runbook run, where `key` is the name you set. | ||
| Octopus makes each state entry available as a [variable](/docs/projects/variables) named `Octopus.Environment.State[key]`, where `key` is the key you set. |
There was a problem hiding this comment.
Remove repetition.
| Octopus makes each state entry available as a [variable](/docs/projects/variables) named `Octopus.Environment.State[key]`, where `key` is the key you set. | ||
|
|
||
| Read it from a script: | ||
| To read environment state in a script: |
There was a problem hiding this comment.
Make it a sentence.
| </details> | ||
|
|
||
| URLs set this way show as clickable links on the [Ephemeral Environments](/docs/projects/ephemeral-environments#environment-urls) in the project, so anyone reviewing the environment can open the running app. | ||
| URLs set this way show as clickable links on the [Ephemeral Environments](/docs/projects/ephemeral-environments#environment-urls) in the project, providing convenient access to the deployed application. |
There was a problem hiding this comment.
Clarity (what does "reviewing the environment" mean?)
|
|
||
| :::div{.hint} | ||
| A URL is a special kind of environment state, the key used must be unique across all state entries (including other URLs) for the same project, environment, and tenant. Reusing a key overwrites the value stored under it. | ||
| The key used for a URL entry must be unique across all state entries (including non-URLs) for the same project, environment, and tenant. With all state entries reusing a key will overwrite its value. |
There was a problem hiding this comment.
Make the point more succinctly.
There was a problem hiding this comment.
A comma might make this easier to follow:
With all state entries, reusing a key will overwrite its value.
| ## Limits on environment state | ||
|
|
||
| Up to 10 environment state entries can be created for each combination of project, environment and optional tenant. | ||
| Environment state has the following limits: |
There was a problem hiding this comment.
Put this in the list for consistency.
| ## Setting an environment URL | ||
|
|
||
| An environment URL is a type of environment state, but gets first-class support in Octopus. It is stored like any other environment state, and surfaced as a clickable link in the Octopus Web Portal and available from the API. | ||
| An environment URL is a special type of environment state that gets first-class support in Octopus. It is stored like any other environment state and surfaced as a clickable link in the Octopus Web Portal and available from the API. |
There was a problem hiding this comment.
I'm nitpicking here, but there is something confusing to me about leading a sentence with a point of similarity and ending it with two points of difference. Maybe you could separate that sentence into two parts or something?
An environment URL is a special type of environment state that gets first-class support in Octopus. It is stored like any other environment state.
An environment URL is surfaced as a clickable link in the Octopus Web Portal and available from the API.
3 participants
No description provided.