Labels are metadata on any object in Prodvana that allow them to be queried. Labels can be a great way to manage a large number of objects, for example, to manage a large number of Runtimes and Release Channels.

Defining Labels

📘

Only supported on Runtimes and Release channels

Currently, labels are only supported on Runtimes and Release Channels. Support for other objects is coming soon.

Labels are defined via config files or Terraform. Both labels and their values must follow the regex ^[a-zA-Z0-9.\-_@+]$.

On Runtimes

Here is a way to define a cloudProvider label on a runtime:

runtime:
  name: my-aws-runtime
  labels:
  - label: cloudProvider
    value: aws

On Release Channels

Release Channel labels are defined in the Release Channel config (part of Application config when using config file, standalone when using Terraform).

application:
  name: my-app
  releaseChannels:
  - name: staging-1
    labels:
    - label: env
      value: staging
  - name: staging-2
    labels:
    - label: env
      value: staging

Auto-Generated Labels

For convenience, Prodvana automatically generates certain labels for all objects. Auto-generated labels begin with @.

All Objects

The following labels exist on all objects:

Release Channels

The following labels are specific to release channels:

Querying Labels

The query language is set-based, with operators for unions, intersection, and diffs.

@type=runtime  # all runtimes  
@type=runtime env=staging  # all staging runtimes  
@type=runtime env=staging -region=us-west-1  # all staging runtimes not in us-west  
@type=runtime env=staging -region=us-west-1 +(@type=runtime environment=prod)  # all staging runtimes not in us-west and all prod runtimes

Objects can be queried using pvnctl labels query, for example, pvnctl labels query "@type=runtime env=staging".

To get all labels associated with an object, run pvnctl labels get-labels <type> <name-or-id>, for example, pvnctl labels get-labels runtime my-runtime.

Uses of Labels

Defining Release Channels Using Runtime Labels

A common operation when managing a large number of Runtimes is to define an app(s) that have Release Channels deploying to all Runtimes, in certain order. Labels can help define such Application without having to individually enumerate all Runtimes.

For example, say you have the following Runtimes with the following labels:

To define an Application that deploys first to staging Runtimes and production Runtimes, you can use labels the following way:

application:
  name: my-app
  releaseChannelGroups:
  - name: staging
    runtimeSelector: env=staging  # @type=runtime is implied
  - name: prod
    runtimeSelector: env=prod

This will get translated under the hood to:

application:
  name: my-app
  releaseChannels:
  - name: staging-staging-us-1
    group: staging
    runtimes:
    - runtime: staging-us-1
  - name: staging-staging-eu-1
    group: staging
    runtimes:
    - runtime: staging-eu-1
  - name: prod-prod-us-1
    group: prod
    runtimes:
    - runtime: prod-us-1
  - name: prod-prod-us-2
    group: prod
    runtimes:
    - runtime: prod-us-2
  - name: prod-prod-eu-1
    group: prod
    runtimes:
    - runtime: prod-eu-1

To customize how Release Channel configs are generated, releaseChannelGroup takes a template that looks like a releaseChannel object. For example, to have production Release Channels wait on staging Release Channels:

application:
  name: my-app
  releaseChannelGroups:
  - name: staging
    runtimeSelector: env=staging
  - name: prod
    runtimeSelector: env=prod
    template:
      preconditions:
      - releaseChannelStable:
          selector: '@group=staging'  # @type=release-channel @application=my-app is implied

Within template, the following template variables are available to be used:

template gets merged with the following object automatically, with user-provided values taking precedence:

name: '{{.Builtins.Group}}-{{.Builtins.Runtime.Name}}'
group: '{{.Builtins.Group}}'
runtimes:
- runtime: '{{.Builtins.Runtime.Name}}'

The above configuration gets translated to:

application:
  name: my-app
  releaseChannels:
  - name: staging-staging-us-1
    group: staging
    runtimes:
    - runtime: staging-us-1
  - name: staging-staging-eu-1
    group: staging
    runtimes:
    - runtime: staging-eu-1
  - name: prod-prod-us-1
    group: prod
    runtimes:
    - runtime: prod-us-1
    preconditions:
    - releaseChannelStable:
        releaseChannel: staging-staging-us-1
    - releaseChannelStable:
        releaseChannel: staging-staging-eu-1
  - name: prod-prod-us-2
    group: prod
    runtimes:
    - runtime: prod-us-2
    preconditions:
    - releaseChannelStable:
        releaseChannel: staging-staging-us-1
    - releaseChannelStable:
        releaseChannel: staging-staging-eu-1
  - name: prod-prod-eu-1
    group: prod
    runtimes:
    - runtime: prod-eu-1
    preconditions:
    - releaseChannelStable:
        releaseChannel: staging-staging-us-1
    - releaseChannelStable:
        releaseChannel: staging-staging-eu-1

For more information about what can be configured in a Release Channel, see Configuring Applications.