nsc buildkite queue update - Namespace Documentation

Update settings for a Namespace-managed Buildkite queue. Use nsc buildkite queue update to configure an egress policy, custom workload permissions, cache volume commit behavior, or OpenTelemetry tracing for a queue. You can set individual options or provide all queue settings in a JSON file.

Usage

To update queue settings, first use nsc buildkite queue list, which lists all Buildkite queues that you have registered with Namespace. Find the ID of the queue you want to configure. With this ID, you can call

nsc buildkite queue update <queue-id> [flags]

in order to apply egress policies, default workload permissions, cache volume commit behavior, and OpenTelemetry settings to your queue. The queue configuration can be defined either in a JSON spec file or via command line flags.

Use a JSON spec file

The CLI supports updating queue configuration from a JSON spec file. To start from your queue’s current settings, export your current spec with nsc buildkite queue describe, edit the file, and apply it:

nsc buildkite queue describe <queue-id> -o spec > spec.json
nsc buildkite queue update <queue-id> --spec_file spec.json

Applying a configuration in this way will replace the entire queue configuration with a configuration matching your spec file. Any fields omitted from the spec file will be cleared in your queue configuration.

Available Settings

Egress Policy

You can configure an egress policy to be used for all jobs in this queue. Either use the --egress-policy command line flag or configure it in a spec file:

spec.json

{
  "egress_policy_tag": "my-egress-policy",
}

The configured egress policy will be enforced for every job in this queue, and it cannot be overridden by individual jobs.

Workload Permissions

Namespace supports custom workload permissions per queue, to enable fine-grained control over which jobs may access certain features. These can be configured using the --workload_permissions flag or with a spec file. The example spec file below allows jobs in the queue to access the HTTP build cache.

spec.json

{
  "permissions": {
    "permissions_type": "CUSTOM",
    "workload_permissions": [
      {
        "resource_type": "cache/httpcache",
        "resource_id": "",
        "actions": ["ensure", "read", "write"]
      }
    ]
  },
}

Cache Volume Commit

Control whether jobs in a queue can commit changes to the user Cache Volume selected by the nsc-cache-tag agent tag.

Value	Behavior
`NEVER`	Jobs can read cached contents and write to their local copy, but their changes are not committed for future jobs.
`DEFAULT`	Jobs follow existing cache commit rules, including branch restrictions and settings that disable cache commits.

Disable cache commits for a queue without changing its other settings:

nsc buildkite queue update <queue-id> --cache_volume_commit NEVER

Neither DEFAULT nor removing the override bypasses existing restrictions on cache commits. This setting applies to the user cache volume, including any caches stored inside it. It does not change commit behavior for separate system cache volumes, such as separate Git mirror or container image caches. You can also configure this setting in a spec file. JSON uses the full enum name, unlike the CLI flag:

spec.json

{
  "cache_volume_settings": {
    "commit": "CACHE_VOLUME_COMMIT_NEVER"
  }
}

Use CACHE_VOLUME_COMMIT_DEFAULT for default commit behavior. Omitting cache_volume_settings or using CACHE_VOLUME_COMMIT_UNSPECIFIED restores existing cache behavior. Applying the example above as a spec file also clears other queue settings; export and edit the current spec to preserve them.

OpenTelemetry

OpenTelemetry tracing in the Buildkite agent can only be configured with a spec file, using the open_telemetry_settings field. The following fields are supported in the OpenTelemetry configuration of a Buildkite queue.

Field	Description
`otlp_endpoint`	Required. URL of the OTLP collector.
`otlp_protocol`	`OTLP_PROTOCOL_GRPC` (default) or `OTLP_PROTOCOL_HTTP_PROTOBUF`.
`headers`	Headers sent with each export request, such as authentication tokens.
`resource_attributes`	Additional key-value pairs for `OTEL_RESOURCE_ATTRIBUTES`.

The following spec file applies OpenTelemetry settings to a queue and removes any configured egress policy, workload permissions, and cache volume commit override.

spec.json

{
  "open_telemetry_settings": {
    "otlp_endpoint": "https://...",
    "headers: [
      {
        "name": "Authorization",
        "value_from": { "from_secret_id": "sec_<secret-id>" }
      }
    ]
  }
}

When using bearer authorization for OpenTelemetry, it is recommended to store your token as a Namespace secret in the form Bearer: <token>, and reference the resulting secret ID in a header as in the example above.

Use command-line flags

Instead of passing a spec file, it is also possible to define queue settings via individual command-line flags. To apply the egress policies and workload permissions matching the spec files above, using command-line flags:

nsc buildkite queue update <queue-id> \
  --egress_policy my-egress-policy \
  --workload_permissions '{
      "resource_type": "cache/httpcache",
      "resource_id": "",
      "actions": ["ensure", "read", "write"]
  }'

Command-line flags allow you to update individual fields without defining the queue’s entire configuration. If you want to leave the workload permissions in place but update only the egress policy:

nsc buildkite queue update <queue-id> --egress_policy my-other-egress-policy

Options

—cache_volume_commit <DEFAULT|NEVER>

Set commit behavior for the user cache volume. Values are case-sensitive. NEVER prevents committing cache changes, not local writes. DEFAULT follows existing cache commit rules. Cannot be combined with --reset_cache_volume_commit or --reset.

—egress_policy <string>

Apply the workspace egress policy with this tag to jobs running for the queue.

—output, -o <plain|json>

Output format for the updated queue. Supported values are plain and json. Defaults to plain.

—remove_egress_policy

Remove the workspace egress policy tag from the queue.

—reset

Reset all queue settings.

—reset_cache_volume_commit

Remove the cache volume commit override without changing other queue settings. Cannot be combined with --cache_volume_commit or --reset.

—reset_permissions

Remove custom workload permissions from the queue.

—spec_file <string>

Read the queue settings from the specified JSON file. When provided, the CLI ignores individual settings flags. See Use a JSON spec file above for an example.

—workload_permissions <stringArray> (can be repeated)

Set a custom workload permission as JSON. Repeat this option to set multiple permissions.

{"resource_type":"...","resource_id":"...","actions":["..."]}

See Permissions for available resource types and actions.

nsc buildkite queue describe - Inspect a queue
nsc buildkite queue list - List registered queues
Egress Policies - Control network access from jobs
Managing Buildkite Queues - Register queues and route Buildkite jobs to Namespace

​Usage

​Use a JSON spec file

​Available Settings

​Egress Policy

​Workload Permissions

​Cache Volume Commit

​OpenTelemetry

​Use command-line flags

​Options

​—cache_volume_commit <DEFAULT|NEVER>

​—egress_policy <string>

​—output, -o <plain|json>

​—remove_egress_policy

​—reset

​—reset_cache_volume_commit

​—reset_permissions

​—spec_file <string>

​—workload_permissions <stringArray> (can be repeated)

​Related Topics

Usage

Use a JSON spec file

Available Settings

Egress Policy

Workload Permissions

Cache Volume Commit

OpenTelemetry

Use command-line flags

Options

—cache_volume_commit <DEFAULT|NEVER>

—egress_policy <string>

—output, -o <plain|json>

—remove_egress_policy

—reset

—reset_cache_volume_commit

—reset_permissions

—spec_file <string>

—workload_permissions <stringArray> (can be repeated)

Related Topics