env group

A variable group is a set of variables held once and used by several applications. The group is created and edited with these commands; which applications receive it is a separate assignment.

Nothing here deploys anything. A change reaches an application at its next deployment, and env group get --apps lists the applications that are waiting for one.

env group list

List the team's shared variable groups.

Usage

outplane env group list

Output

Examples

What groups exist

outplane env group list

Find the id to assign

outplane env group list --json --fields name,id,assignments

Read the groups in a pipeline

outplane env group list --json --fields name,variables,assignments

{
  "items": [
    {
      "assignments": 3,
      "name": "shared",
      "variables": 12
    }
  ],
  "total": 1,
  "truncated": false
}

What to Know

• This lists the groups, not what is in them. env group get reports the variables, with values hidden unless asked for.
• A group used neither at build nor at runtime reaches nothing. scope says so in words; useInBuild and useInRuntime are the fields to branch on.

Errors

Beyond 0 for success, this command exits with:

The code on the error object is one of context.no_team. Branch on that, or on the exit status. The message is prose and changes.

env group get

Show what a group holds.

Usage

outplane env group get <GROUP> [flags]

Arguments

Flags

The global flags apply as well.

Output

Examples

What is in a group

outplane env group get shared

Which applications use it, and therefore what to deploy

outplane env group get shared --apps

{
  "items": [
    {
      "app": "checkout",
      "appId": "618ac10a-…"
    },
    {
      "app": "worker",
      "appId": "c0345de8-…"
    }
  ],
  "total": 2,
  "truncated": false
}

Read the keys without the values

outplane env group get shared --json --fields name,entries

See which applications would be affected by a change

outplane env group get shared -o text

What to Know

• The rows are the variables. Which group they belong to, how it is scoped and how many applications use it are in the closing line, because a table of key and value has nowhere to put them.
• Resolving a name costs a list call before the read, since the detail endpoint takes an id.
• --apps answers the question the other commands leave open: a change to a group reaches its applications at their next deployment, and nothing here deploys them, so this is the list to work through.

Errors

Beyond 0 for success, this command exits with:

The code on the error object is one of envgroup.not_found, envgroup.ambiguous, usage.missing_argument. Branch on that, or on the exit status. The message is prose and changes.

env group create

Create a shared variable group.

Usage

outplane env group create <NAME> [flags]

Arguments

Flags

The global flags apply as well.

Output

Examples

A group two services share

outplane env group create shared --var LOG_LEVEL=info --var REGION=eu

Build-time only

outplane env group create buildargs --var NPM_TOKEN=x --build --build-only

Check the request without creating anything

outplane env group create shared --var A=1 --dry-run --json

{
  "changed": false,
  "name": "shared",
  "variables": 1
}

What to Know

• A new group is assigned to nothing and therefore reaches nothing until env group assign runs.
• --build-only without --build is refused. The server would accept a group used neither at build nor at runtime, which is a mistake that looks like working configuration.
• The same reserved keys apply as anywhere else: HOSTNAME, and anything starting with OP_ or KUBERNETES_.

Errors

Beyond 0 for success, this command exits with:

The code on the error object is one of envgroup.name_required, envgroup.name_invalid, envgroup.scope_empty, usage.bad_assignment, env.reserved_key, env.reserved_prefix, env.value_too_long. Branch on that, or on the exit status. The message is prose and changes.

env group set

Change a group's variables or settings.

Usage

outplane env group set <GROUP> [flags]

Arguments

Flags

The global flags apply as well.

Output

Examples

Add a variable

outplane env group set shared --var TIMEOUT=30

Remove one

outplane env group set shared --unset TIMEOUT

See what would change, and what would stay

outplane env group set shared --var A=2 --dry-run --json

{
  "changed": false,
  "name": "shared",
  "variables": 12
}

What to Know

• Every variable is sent back on every call, because the endpoint replaces the group. Concurrent edits overwrite each other and nothing detects it.
• --unset refuses a key the group does not have, rather than reporting success for a removal that removed nothing.
• A change reaches the applications using the group at their next deployment.
• Calling it with nothing to change is an error, not a no-op write.

Errors

Beyond 0 for success, this command exits with:

The code on the error object is one of envgroup.not_found, envgroup.scope_empty, env.not_found, usage.bad_assignment, usage.missing_argument. Branch on that, or on the exit status. The message is prose and changes.

env group assign

Give an application a group's variables.

Usage

outplane env group assign <GROUP> [flags]

Arguments

Flags

The global flags apply as well.

Output

Examples

Check what it would do, without doing it

outplane env group assign shared --app checkout --dry-run --json

{
  "app": "checkout",
  "changed": false,
  "group": "shared"
}

Assign a group

outplane env group assign shared --app checkout

Read the result in a pipeline

outplane env group assign shared --app checkout --json --fields group,app,changed

What to Know

• Idempotent. Assigning something already assigned reports changed false and exits 0, and so does unassigning something that was not assigned.
• The API removes an assignment by the assignment's own id, not by the pair, so the assignment is looked up first. That is one extra request and it is what turns a missing assignment into a sentence rather than a 404.
• The change reaches the application at its next deployment.

Errors

Beyond 0 for success, this command exits with:

The code on the error object is one of envgroup.not_found, app.not_found, context.no_app. Branch on that, or on the exit status. The message is prose and changes.

env group unassign

Stop an application using a group.

Usage

outplane env group unassign <GROUP> [flags]

Arguments

Flags

The global flags apply as well.

Output

Examples

Check what it would do, without doing it

outplane env group unassign shared --app checkout --dry-run --json

{
  "app": "checkout",
  "changed": false,
  "group": "shared"
}

Unassign a group

outplane env group unassign shared --app checkout

Read the result in a pipeline

outplane env group unassign shared --app checkout --json --fields group,app,changed

What to Know

• Idempotent. Assigning something already assigned reports changed false and exits 0, and so does unassigning something that was not assigned.
• The API removes an assignment by the assignment's own id, not by the pair, so the assignment is looked up first. That is one extra request and it is what turns a missing assignment into a sentence rather than a 404.
• The change reaches the application at its next deployment.

Errors

Beyond 0 for success, this command exits with:

The code on the error object is one of envgroup.not_found, app.not_found, context.no_app. Branch on that, or on the exit status. The message is prose and changes.

env group delete

Permanently delete a variable group.

Usage

outplane env group delete <GROUP> [flags]

Arguments

Flags

The global flags apply as well.

Output

Examples

See what would be lost

outplane env group delete shared --dry-run

The confirmed form

outplane env group delete shared --yes --confirm-name shared

Check what the name resolves to, and who uses it

outplane env group delete shared --dry-run --json

{
  "assignments": 0,
  "changed": false,
  "name": "shared"
}

What to Know

• Never prompts. Without confirmation it exits 4 and returns the command to replay in the error's confirm_command field.
• Under a detected agent harness it exits 4 even with both flags.
• A group with assignments cannot be deleted: the server refuses and says so. Unassign it from every application first, which env group get --apps lists.

Errors

Beyond 0 for success, this command exits with:

The code on the error object is one of confirmation.required, envgroup.confirm_name_mismatch, envgroup.not_found, envgroup.in_use. Branch on that, or on the exit status. The message is prose and changes.

Related