controller_configuration.md

Controller Configuration

Usage:

• agent-stack-k8s [flags]
• agent-stack-k8s [command]

Available Commands:

Command	Description
completion	Generate the autocompletion script for the specified shell
help	Help about any command
lint	A tool for linting Buildkite pipelines
version	Prints the version

Flags:

Flag	Description
--agent-token-secret string	name of the Buildkite agent token secret (default "buildkite-agent-token")
--buildkite-token string	Buildkite API token with GraphQL scopes
--cluster-uuid string	UUID of the Buildkite Cluster. The agent token must be for the Buildkite Cluster.
-f, --config string	config file path
--debug	debug logs
--default-image-check-pull-policy string	Sets a default PullPolicy for image-check init containers, used if an image pull policy is not set for the corresponding container in a podSpec or podSpecPatch
--default-image-pull-policy string	Configures a default image pull policy for containers that do not specify a pull policy and non-init containers created by the stack itself (default "IfNotPresent")
--empty-job-grace-period duration	Duration after starting a Kubernetes job that the controller will wait before considering failing the job due to a missing pod (e.g., when the podSpec specifies a missing service account) (default 30s)
--graphql-endpoint string	Buildkite GraphQL endpoint URL
--graphql-results-limit int	Sets the amount of results returned by GraphQL queries when retrieving Jobs to be Scheduled (default 100)
-h, --help	help for agent-stack-k8s
--image string	The image to use for the Buildkite agent (default "ghcr.io/buildkite/agent:3.91.0")
--image-pull-backoff-grace-period duration	Duration after starting a pod that the controller will wait before considering cancelling a job due to ImagePullBackOff (e.g., when the podSpec specifies container images that cannot be pulled) (default 30s)
--job-cancel-checker-poll-interval duration	Controls the interval between job state queries while a pod is still Pending (default 5s)
--job-creation-concurrency int	Number of concurrent goroutines to run for converting Buildkite jobs into Kubernetes jobs (default 5)
--job-ttl duration	time to retain kubernetes jobs after completion (default 10m0s)
--job-active-deadline-seconds int	maximum number of seconds a kubernetes job is allowed to run before terminating all pods and failing (default 21600)
--k8s-client-rate-limiter-burst int	The burst value of the K8s client rate limiter. (default 20)
--k8s-client-rate-limiter-qps int	The QPS value of the K8s client rate limiter. (default 10)
--max-in-flight int	max jobs in flight, 0 means no max (default 25)
--namespace string	kubernetes namespace to create resources in (default "default")
--org string	Buildkite organization name to watch
--pagination-depth-limit int	Sets the maximum depth of pagination when retrieving Buildkite Jobs to be Scheduled. Increasing this value will increase the number of requests made to the Buildkite GraphQL API and number of Jobs to be scheduled on the Kubernetes Cluster. (default 1)
--poll-interval duration	time to wait between polling for new jobs (minimum 1s); note that increasing this causes jobs to be slower to start (default 1s)
--profiler-address string	Bind address to expose the pprof profiler (e.g., localhost:6060)
--prohibit-kubernetes-plugin	Causes the controller to prohibit the kubernetes plugin specified within jobs (pipeline YAML) - enabling this causes jobs with a kubernetes plugin to fail, preventing the pipeline YAML from having any influence over the podSpec
--prometheus-port uint16	Bind port to expose Prometheus /metrics; 0 disables it
--tags strings	A comma-separated list of agent tags. The "queue" tag must be unique (e.g., "queue=kubernetes,os=linux") (default [queue=kubernetes])
--enable-queue-pause bool	Allow the controller to pause processing the jobs when the queue is paused on Buildkite. (default false)

Use agent-stack-k8s [command] --help for more information about a command.

With release v0.24.0 of agent-stack-k8s, we can enable --enable-queue-pause in the config, allowing the controller to pause processing the jobs when queue is paused on Buildkite.