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, 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, 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"]
      }
    ]
  },
}

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 and workload permissions.

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

—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_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

​OpenTelemetry

​Use command-line flags

​Options

​—egress_policy <string>

​—output, -o <plain|json>

​—remove_egress_policy

​—reset

​—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

OpenTelemetry

Use command-line flags

Options

—egress_policy <string>

—output, -o <plain|json>

—remove_egress_policy

—reset

—reset_permissions

—spec_file <string>

—workload_permissions <stringArray> (can be repeated)

Related Topics