Skip to content

Commit

Permalink
cloud-docs/run-environment: Don't overload the term "run"
Browse files Browse the repository at this point in the history
The "run environment" page belongs to a collection of pages that describe
the capital-R concept of "Run" in HCP Terraform, which refers to the
combination of a plan phase and an optional apply phase. "Normal" runs
form a per-workspace queue where each run must be resolved (its plan either
approved or declined) before proceeding with the next.

This particular section, however, was using "run" both in its usual meaning
_and_ with a new meaning of "job that can be picked up by a worker", which
made this section hard to follow when considered in the broader context
where it's placed.

The prior text was already using the word "job" to describe what was being
taken from queues, and so here I've revised the text to consistently use
that noun to refer to the kind of thing that is constrained by our
concurrency limits. I think that explains the situation a little more
clearly while avoiding getting _too_ deep into the implementation details.

I also made the separate editorial decision that jobs take actions and so
what they do should be described as active agents, e.g. using the gerund
"applying" instead of the nouned-verb "applies" (which is ambiguous with
the present-tense verb as in "the agent _applies_ the plan".

Otherwise I attempted to keep the message largely the same as it was
before, but just using hopefully-clearer terminology.
  • Loading branch information
apparentlymart committed May 16, 2024
1 parent 53e0c33 commit 4a2c020
Showing 1 changed file with 9 additions and 7 deletions.
16 changes: 9 additions & 7 deletions website/docs/cloud-docs/run/run-environment.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -29,17 +29,19 @@ If you are using the SaaS version of HCP Terraform, this means your VCS provider

Terraform Enterprise instances must have network connectivity to any connected VCS providers or managed infrastructure providers.

## Concurrency and Run Queuing
<a name="concurrency-and-run-queuing"></a>

HCP Terraform uses multiple concurrent worker VMs, which take jobs from a global queue of runs that are ready for processing. (This includes confirmed applies, and plans that have just become the current run on their workspace.)
## Concurrency and Job Queuing

If the global queue has more runs than the workers can handle at once, some of them must wait until a worker becomes available. When the queue is backed up, HCP Terraform gives different priorities to different kinds of runs:
HCP Terraform uses multiple concurrent worker VMs, which take jobs from a global queue of operations that are ready to execute. (This includes both creating new plans and then applying those plans once they've been approved.)

- Applies that will make changes to infrastructure have the highest priority.
- Normal plans have the next highest priority.
- Speculative plans have the lowest priority.
If the global queue has more jobs than the workers can handle at once, some of them must wait until a worker becomes available. When the queue is backed up, HCP Terraform gives different priorities to different kinds of jobs:

HCP Terraform can also delay some runs in order to make performance more consistent across organizations. If an organization requests a large number of runs at once, HCP Terraform queues some of them immediately, and delays the rest until some of the initial batch have finished; this allows every organization to continue performing runs even during periods of especially heavy load.
- Applying approved plans has the highest priority.
- Creation of normal plans has the next-highest priority.
- Creation of speculative plans has the lowest priority.

HCP Terraform can also delay some jobs to make performance more consistent across organizations. If an organization requests a large number of jobs at once, HCP Terraform queues some of them immediately, and delays the rest until some of the initial batch have finished; this allows every organization to continue executing jobs even during periods of especially heavy load.

## State Access and Authentication

Expand Down

0 comments on commit 4a2c020

Please sign in to comment.