RunR v0.6.0

Documentation

runr_environment (Resource)

An environment of a project (dev, staging, …): a workload of its own, <slug>-<name>, that runs the project's versions with the project's configuration, its overrides on top, its own secret variables (runr_environment_secret), bindings (runr_binding_attachment.environment), custom domains (runr_domain.environment), private database connections (runr_private_connection.environment) and, optionally, another region (environments). Nothing runs in it until a version is deployed or promoted to it: promotions, approvals and deploys are actions, not managed here.

The primary environment production is the project's own workload and exists with every project: name = "production" adopts it to manage its requires_approval and position only (its configuration is the project's); destroying the resource sets them back to production's defaults (approval required, last in the pipeline). Destroying another environment deletes it with its workload, deployments and secrets; its bindings are detached, its custom domains, gateway route and private connections removed.

Needs environments.manage on the project (overrides with env_vars also env.edit, deploy_strategy projects.update). Import with <project name or id>/<environment name>.

Example Usage#

# staging: pushes to develop deploy it, with its own overrides of the project's configuration.
resource "runr_environment" "staging" {
  project_id = runr_project.api.id
  name       = "staging"
  git_branch = "develop"

  # The complete set of overrides (what is left out follows the project's configuration)
  overrides = {
    env_vars        = { LOG_LEVEL = "debug" }
    remove_env_vars = ["ANALYTICS_KEY"] # the project's variable does not reach staging
    min_scale       = 0
    max_scale       = 2
  }

  # No containers warm in staging; the project's timed warmer stays production's
  scale_schedule = []

  # Canary deploys in staging, whatever the project's strategy
  deploy_strategy = {
    strategy = "canary"
    canary   = { steps = [50, 100], interval_minutes = 2 }
  }
}

# qa in another region, without the project's secret variables.
resource "runr_environment" "qa" {
  project_id      = runr_project.api.id
  name            = "qa"
  region_id       = data.runr_region.us.id
  inherit_secrets = false
  position        = 0 # first in the pipeline
}

# production is the project's own workload: adopted to manage its approval only.
resource "runr_environment" "production" {
  project_id        = runr_project.api.id
  name              = "production"
  requires_approval = true
}

output "staging_url" {
  value = runr_environment.staging.url
}

Schema#

Required#

  • name (String) Lowercase DNS label of at most 20 characters (staging, qa-eu), unique in the project; its workload is <slug>-<name>. Not a name the project's resources use (trigger, qc, bindings, pr-<n>, v<n>, …). production adopts the project's own workload. Changing it creates a new environment.
  • project_id (String) Project id. Changing it creates a new environment.

Optional#

  • auto_deploy (Boolean) Whether a push to git_branch deploys (default true). Left out, the setting stays.
  • deploy_strategy (Attributes) How the environment's deploys and the promotions into it roll out, over the project's deploy strategy. The configured values become the environment's own and stay when the project's settings change; the others follow the project's. Reads back the settings the environment deploys with. Left out, the environment keeps its settings. (see below for nested schema)
  • deploy_strategy_inherited (Boolean) Whether the environment sets nothing of its own deploy strategy and follows the project's. Set it to true to drop what it sets and follow the project's again; false only together with deploy_strategy.
  • git_branch (String) Branch whose pushes deploy the environment (develop); one environment per branch, never the project's deploy branch. "" maps no branch (the default). Left out, the branch stays.
  • inherit_secrets (Boolean) Whether the project's secret variables reach the environment (default true); off, it has only its own (runr_environment_secret). Left out, the setting stays.
  • overrides (Attributes) Configuration over the project's. RunR saves the overrides as a whole: a configured block is the complete set (a field left out of it follows the project's value; {} overrides nothing). Left out, the overrides stay as they are. A change reaches the workload with the environment's next deploy. (see below for nested schema)
  • position (Number) Place in the pipeline (0-2000): environments run by position, production's is 1000. Default: after the environments added before it, before production. Left out, the position stays.
  • region_id (String) Region it runs in (data.runr_region); default the project's, which it then follows. The organization's data residency must allow the region. RunR changes it only while nothing runs in the environment and it has no gateway route or private connection. Left out, the region stays.
  • requires_approval (Boolean) Whether promotions into the environment wait for an approver with environments.approve (default false; true for production). Left out, the setting stays.
  • scale_schedule (Attributes List) The environment's own timed warmer: each row keeps at least min_scale containers warm from the moment its five-field cron expression fires until the next row fires, in the organization's time zone. The rows replace the project's schedule in the environment (at most 10, each at most its max_scale, else the project's); [] keeps no containers warm there. A change reaches the running workload within a minute, without a deploy. Reads back the schedule the environment runs, the project's while scale_schedule_inherited. Left out, the environment keeps what it has. (see below for nested schema)
  • scale_schedule_inherited (Boolean) Whether the environment runs the project's timed warmer (it has no schedule of its own). Set it to true to drop the environment's own schedule and follow the project's again; false only together with scale_schedule.

Read-Only#

  • default_url (String) Its own URL on the function domain of its region, https://<workload>.<domain>.
  • id (String) Environment id.
  • own_region (Boolean) Whether the environment has a region of its own (false: it follows the project's).
  • url (String) URL of the environment: its gateway URL while it has a gateway route, else default_url.
  • workload_name (String) Name of its workload (Knative Service) in the region: <slug>-<name>; the slug for production.

Nested Schema for deploy_strategy#

Optional:

  • blue_green (Attributes) Options of the blue-green strategy. Left out, the options stay as they are. (see below for nested schema)
  • canary (Attributes) Options of the canary strategy. Left out, the options stay as they are. (see below for nested schema)
  • strategy (String) direct (the new revision replaces the live one once it is ready), blue_green or canary. A strategy other than direct needs an http or workflow trigger.

Nested Schema for deploy_strategy.blue_green#

Optional:

  • auto_promote (Boolean) Promote once the health checks passed; false waits for runr rollout promote.
  • health_checks (Number) Consecutive 2xx answers auto promotion needs (1-20, one every 10 s).
  • health_path (String) Path the health checks call, e.g. /healthz. Not set in a configured blue_green block: the new revision's readiness alone decides.
  • keep_previous_minutes (Number) Minutes the previous revision stays warm after promotion for an instant rollback (0-1440).

Nested Schema for deploy_strategy.canary#

Optional:

  • error_rate_threshold (Number) Roll back above this error rate of the new revision in percent (0-100). Not set in a configured canary block: not checked.
  • interval_minutes (Number) How long each step lasts (1-1440 minutes).
  • p95_threshold_ms (Number) Roll back above this 95th percentile latency in milliseconds (1-600000). Not set in a configured canary block: not checked.
  • steps (List of Number) Traffic percentages of the new revision, strictly increasing (1-10 steps, 1-100); reaching 100 promotes it.

Nested Schema for overrides#

Optional:

  • cpu (String) Kubernetes CPU quantity of the container (250m, 0.5); also what the environment reserves.
  • env_vars (Map of String, Sensitive) Plain variables merged over the project's by name. A token without env.view cannot read them back: the configured values are kept (with a warning).
  • max_scale (Number) Maximum instances (1-1000).
  • memory_mb (Number) Memory in MB (at least 64); also what the environment reserves.
  • min_scale (Number) Minimum instances (0-10).
  • queue_stream (String) Stream a queue trigger reads. Without one the environment reads <stream>-<name>, never production's stream.
  • remove_env_vars (Set of String) Names of the project's plain variables the environment does not get (RunR's null override). A name is in env_vars or here, not both.
  • scale_to_zero (Boolean) Scale to zero instances when idle.
  • schedule (String) Cron schedule of a schedule trigger.
  • timeout_seconds (Number) Request timeout in seconds (within the region's limit).

Nested Schema for scale_schedule#

Required:

  • cron (String) Five-field cron expression (minute hour day-of-month month day-of-week), fields separated by one space, e.g. 0 9 * * 1-5.
  • min_scale (Number) Containers kept warm from this moment on (0-10).

Import#

Import is supported using the following syntax:

The terraform import command can be used, for example:

# <project name or id>/<environment name>
terraform import runr_environment.staging orders-api/staging

# production (the project's own workload) is imported like any other environment.
terraform import runr_environment.production orders-api/production

RunR v0.6.0 · MIT License