@zuke/kubectl

`@zuke/kubectl` — typed `kubectl` CLI task wrappers for Zuke builds, for

Symbols

DryRunMode

type

type DryRunMode = none | client | server

The --dry-run strategies kubectl accepts.

KubectlAnnotateSettings

class

class KubectlAnnotateSettings extends KubectlSettings

Settings for kubectl annotate.

Member	Signature	Doc
`resource`	`resource(...tokens: string[]): this`	Resource tokens, e.g. `("deploy", "api")` or `("pods", "-l", "app=web")`; repeatable.
`annotation`	`annotation(key: string, value: string): this`	Set an annotation as a `key=value` token; repeatable.
`remove`	`remove(key: string): this`	Remove an annotation, rendered as kubectl's `key-` syntax; repeatable.
`overwrite`	`overwrite(): this`	Overwrite existing annotations (`--overwrite`).
`all`	`all(): this`	Apply to all resources of the given type (`--all`).
`selector`	`selector(query: string): this`	Restrict to resources matching a label selector (`-l`).

KubectlApiResourcesSettings

class

class KubectlApiResourcesSettings extends KubectlSettings

Settings for kubectl api-resources.

Member	Signature	Doc
`apiGroup`	`apiGroup(name: string): this`	Only resources in this API group (`--api-group`).
`namespaced`	`namespaced(value?: boolean): this`	Whether to list namespaced resources (`--namespaced`); kubectl's default is `true`, so pass `false` for the cluster-scoped ones.
`verbs`	`verbs(...names: string[]): this`	Only resources supporting these verbs (`--verbs`).
`categories`	`categories(...names: string[]): this`	Only resources in these categories (`--categories`).
`sortBy`	`sortBy(field: name \| kind): this`	Sort by `name` or `kind` (`--sort-by`).
`output`	`output(format: string): this`	The output format (`-o`), e.g. `name` or `wide`.
`noHeaders`	`noHeaders(): this`	Leave the header row out (`--no-headers`).
`cached`	`cached(): this`	Use the discovery cache rather than asking the server (`--cached`).

KubectlApiVersionsSettings

class

class KubectlApiVersionsSettings extends KubectlSettings

Settings for kubectl api-versions.

KubectlApplySettings

class

class KubectlApplySettings extends KubectlSettings

Settings for kubectl apply.

Member	Signature	Doc
`file`	`file(path: PathLike): this`	Apply a manifest file, directory, or URL (`-f`); repeatable.
`kustomize`	`kustomize(dir: PathLike): this`	Apply a kustomization directory (`-k`).
`recursive`	`recursive(): this`	Recurse into directories given to `-f` (`-R`).
`prune`	`prune(): this`	Prune resources not present in the applied set (`--prune`).
`serverSide`	`serverSide(): this`	Apply server-side (`--server-side`).
`dryRun`	`dryRun(mode?: DryRunMode): this`	Preview without persisting (`--dry-run=`; defaults to `client`).
`selector`	`selector(query: string): this`	Restrict to resources matching a label selector (`-l`).
`force`	`force(): this`	Force apply by delete-and-recreate when needed (`--force`).

KubectlAuthCanISettings

class

class KubectlAuthCanISettings extends KubectlSettings

Settings for kubectl auth can-i.

The command answers through its exit status — 0 when the action is allowed and non-zero when it is not — so "./kubectl.ts".KubectlTasksApi.canI reads the code into a boolean rather than failing the build on a routine "no".

Member	Signature	Doc
`verb`	`verb(name: string): this`	The API verb to check, e.g. `create` (required unless `list`).
`resource`	`resource(name: string): this`	The resource, e.g. `deployments` or `deployments/api`.
`subresource`	`subresource(name: string): this`	A subresource, e.g. `log` or `scale` (`--subresource`).
`allNamespaces`	`allNamespaces(): this`	Check across every namespace (`--all-namespaces`).
`list`	`list(): this`	Print every allowed action instead of checking one (`--list`).
`quietAnswer`	`quietAnswer(): this`	Print nothing and answer only through the exit code (kubectl's `--quiet`). Named apart from the inherited `.quiet()`, which suppresses Zuke's own echo of the command rather than kubectl's output.

kubectlCanary

function

function kubectlCanary(configure: Configure<KubectlCanarySettings>): KubectlCanary

Two Kubernetes Deployments behind one Service as a canary platform, for @zuke/canary:

c.platform(kubectlCanary((k) =>
  k.stable("api").canary("api-canary").container("api")
    .image(this.image.value).replicas(10).namespace("prod")
    .kubectl((s) => s.context("prod"))
))

The lambda runs on every call, so it may read resolved parameters.

- stage — reads the stable image, both Deployments' .spec.paused and the canary's .spec.replicas (get -o jsonpath=…), refusing a paused Deployment or a canary that is not at 0, then set image deployment/<canary> <container>=<image>. - expose — scale the canary up, rollout status it, then scale the stable Deployment down. - promote — set image the candidate on the stable Deployment, scale it to the total, rollout status it, then scale the canary to 0. - abort — the same with the stable image: the one stage read, or, run by hand, the one set with .stableImage(...). A rollback with nothing recorded runs nothing: nothing was staged.

stage records the Deployments, container and namespace it changed, and the later calls refuse a lambda that names others. Keep them — and the kube context or kubeconfig in .kubectl(...), which cannot be recorded — unchanged until the rollout is finished or cancelled.

KubectlCanary

class

class KubectlCanary

Two Kubernetes Deployments behind one Service as a canary platform. Create one with kubectlCanary; hand it to @zuke/canary's c.platform(...).

Exposure is a share of replicas, so it is quantised: expose returns the share it actually reached.

Member	Signature	Doc
`describe`	`describe(): string`	`"Kubernetes deployment api (canary api-canary)"`, for the summary.
`stage`	`stage(ctx: KubectlCanaryContext): Promise<void>`	Read the image the stable Deployment runs, so a rollback can put it back; check that neither Deployment is paused and that the canary has no replicas; then set the candidate image on the canary. With no replicas, nothing runs the candidate yet.
`expose`	`expose(percent: number, ctx: KubectlCanaryContext): Promise<number>`	Move replicas so the canary Deployment holds about `percent` of the total. The canary grows first and is waited for with `rollout status`; only then does the stable Deployment shrink, so capacity never dips. A step between 0 and 100 always leaves at least one replica on each side, and a step that asks for less than half a replica is refused rather than rounded up to a far larger share. The total is the one `stage` recorded, so a resumed process sizes the step the same way. It refuses a rollout `stage` did not record, and one whose lambda now names other Deployments than `stage` changed. Returns the share reached, `canary / total × 100`.
`promote`	`promote(ctx: KubectlCanaryContext): Promise<void>`	Set the staged candidate image on the stable Deployment, scale it to the total and wait for it, then empty the canary Deployment — only once the wait succeeded. It promotes the image `stage` recorded — the one analysed — whatever the lambda says now, and refuses when the lambda names other Deployments than `stage` changed. Idempotent.
`abort`	`abort(ctx: KubectlCanaryContext): Promise<void>`	Return every replica to the stable Deployment, running the stable image. Idempotent. What it does depends on what this rollout recorded: - Staged (a rollback mid-rollout): the image `stage` read off the stable Deployment goes back on it — a no-op unless a promote got part of the way — the stable Deployment is scaled to the total `stage` recorded and waited for, and the canary is emptied, even when that wait fails. What `stage` recorded wins over the lambda's `stableImage` and `replicas`; a lambda naming other Deployments, container or namespace than `stage` recorded is refused. - `stage` failed before the candidate was on record: the canary had no replicas and the stable Deployment was not touched, so nothing runs. - Nothing recorded, on a rollback (`ctx.reason` is `"rollback"`): nothing was staged, so nothing runs — the stable image is not even read. A marker `stage` never writes is a damaged record, and a rollback refuses it. - Nothing recorded, run by hand (`rollout.abort` on its own, a fresh run, or an engine that names no reason): the same as staged, with the image set by `KubectlCanarySettings.stableImage`. Without one this refuses: after a promote the stable Deployment runs the candidate, and moving replicas alone would report a rollback that changed nothing.
`exposure`	`exposure: replicas`	Traffic follows ready pods, so exposure is a share of replicas.

KubectlCanaryContext

interface

interface KubectlCanaryContext

The part of the canary engine's context the Kubernetes platform uses: the rollout's durable state, where stage records what a rollback needs, and the build summary. The engine hands a richer context; this is the narrow view.

Member	Signature	Doc
`reportSummary`	`reportSummary(pairs: SummaryPairs): void`	Add key/value pairs to the calling target's row in the build summary.
`state`	`state: TargetStateHandle`	The rollout's durable platform state, shared by every call.
`reason?`	`reason?: rollback \| hand-run`	Why `abort` runs: `"rollback"` when the engine undoes a rollout, `"hand-run"` for `rollout.abort` run on its own. An engine older than this field leaves it out, which is treated as a hand run — the behaviour from before the field existed.

KubectlCanarySettings

class

class KubectlCanarySettings

How kubectlCanary reaches the two Deployments, configured through its lambda.

Member	Signature	Doc
`stable`	`stable(deployment: string): this`	The Deployment serving the current release. It must already exist, and its pods and the canary's must be selected by the same Service.
`canary`	`canary(deployment: string): this`	The Deployment the candidate runs in — a second Deployment with the same pod labels the Service selects (plus one of its own, so its selector does not match the stable pods). It must already exist; at rest it has 0 replicas.
`container`	`container(name: string): this`	The container, in both Deployments, whose image is rolled out.
`image`	`image(reference: string): this`	The candidate's container image, set on the canary Deployment by `stage`. Prefer a digest (`repo@sha256:…`) — a mutable tag can point at something else by the time `promote` sets it on the stable Deployment.
`stableImage`	`stableImage(reference: string): this`	The image a `rollout.abort` run by hand puts back on the stable Deployment. Such a run is fresh, with no record of a rollout, and the release it undoes has usually been promoted — so the stable Deployment already runs the candidate, and moving replicas alone would change nothing. A rollback the engine runs mid-rollout does not use it: that one restores the image `stage` read off the stable Deployment.
`replicas`	`replicas(total: number): this`	The replicas the two Deployments run between them — the stable Deployment's size at rest. A whole number from 1 to 2147483647; a step needs enough that it asks for at least half a replica, and at least 2, so it can leave a replica on each side. `stage` records it, so a resumed or rolled-back rollout restores the size it started from.
`namespace`	`namespace(name: string): this`	The namespace both Deployments live in (`--namespace`).
`timeout`	`timeout(duration: string): this`	How long each `kubectl rollout status` waits for a Deployment to become ready, as a Go duration from `1ms` to `24h` (default `5m`). kubectl reads 0 as "wait forever", so it is refused.
`kubectl`	`kubectl(configure: Configure<KubectlSettings>): this`	Global flags for every kubectl command the platform runs — `(s) => s.context("prod").kubeconfig("~/.kube/prod")`, or a `.toolPath(...)` to a specific kubectl.
`runner`	`runner(run: KubectlSettingsRunner): this`	Replace how each prepared command is run. The default runs it; this is for a test, or for a build that executes kubectl through something else.
`stable_?`	`stable_?: string`	The Deployment that serves the current release (set by `stable`).
`canary_?`	`canary_?: string`	The Deployment that runs the candidate (set by `canary`).
`container_?`	`container_?: string`	The container whose image is rolled out (set by `container`).
`image_?`	`image_?: string`	The candidate's container image (set by `image`).
`stableImage_?`	`stableImage_?: string`	The image a hand-run rollback restores (set by `stableImage`).
`replicas_?`	`replicas_?: number`	Replicas across both Deployments (set by `replicas`).
`namespace_?`	`namespace_?: string`	The namespace of both Deployments (set by `namespace`).
`timeout_`	`timeout_: string`	How long each `rollout status` waits (set by `timeout`).
`kubectl_?`	`kubectl_?: Configure<KubectlSettings>`	Global kubectl flags for every command (set by `kubectl`).
`runner_`	`runner_: KubectlSettingsRunner`	How each command is run (set by `runner`).

KubectlClusterInfoSettings

class

class KubectlClusterInfoSettings extends KubectlSettings

Settings for kubectl cluster-info.

KubectlConfigCurrentContextSettings

class

class KubectlConfigCurrentContextSettings extends KubectlSettings

Settings for kubectl config current-context.

KubectlConfigGetContextsSettings

class

class KubectlConfigGetContextsSettings extends KubectlSettings

Settings for kubectl config get-contexts.

Member	Signature	Doc
`namesOnly`	`namesOnly(): this`	Print only the names (`-o name`), the one output format gh accepts here.
`noHeaders`	`noHeaders(): this`	Leave the header row out (`--no-headers`).

KubectlConfigSetContextSettings

class

class KubectlConfigSetContextSettings extends KubectlSettings

Settings for kubectl config set-context.

Note that set-context has its own --namespace, which sets the namespace recorded in the context entry rather than scoping one command. The inherited .namespace(...) renders that same flag, which is what a caller of this command wants.

Member	Signature	Doc
`contextName`	`contextName(name: string): this`	The context to write (required unless `current` is set).
`current`	`current(): this`	Modify the current context rather than a named one (`--current`).
`cluster`	`cluster(name: string): this`	The cluster the context points at (`--cluster`).
`user`	`user(name: string): this`	The user the context authenticates as (`--user`).

KubectlConfigUseContextSettings

class

class KubectlConfigUseContextSettings extends KubectlSettings

Settings for kubectl config use-context.

Member	Signature	Doc
`contextName`	`contextName(name: string): this`	The context to switch to (required).

KubectlConfigViewSettings

class

class KubectlConfigViewSettings extends KubectlSettings

Settings for kubectl config view.

Member	Signature	Doc
`minify`	`minify(): this`	Keep only what the current context uses (`--minify`).
`flatten`	`flatten(): this`	Inline the referenced files, for a portable kubeconfig (`--flatten`).
`raw`	`raw(): this`	Print the credentials in the clear (`--raw`). kubectl redacts them by default; anything this prints belongs in a `parameter().secret()`, not in a build's log.
`output`	`output(format: string): this`	The output format (`-o`), e.g. `json`; kubectl's default is `yaml`.

KubectlCordonSettings

class

class KubectlCordonSettings extends KubectlSettings

Settings for kubectl cordon and kubectl uncordon — marking a node unschedulable, and letting it take pods again.

Member	Signature	Doc
`node`	`node(name: string): this`	The node to act on; required unless a `selector` picks them.
`uncordon`	`uncordon(): this`	Make the node schedulable again instead — `kubectl uncordon`.
`selector`	`selector(query: string): this`	Act on every node matching a label selector (`-l`).
`dryRun`	`dryRun(mode?: DryRunMode): this`	Preview without persisting (`--dry-run=`; defaults to `client`).

KubectlCpSettings

class

class KubectlCpSettings extends KubectlSettings

Settings for kubectl cp — copying files into and out of a container.

This is how a build gets a report out of a pod that produced it. Each side is either a local path or a [namespace/]pod:path spec, and kubectl takes exactly one of each.

Member	Signature	Doc
`from`	`from(spec: string): this`	Where to copy from: a local path, or `pod:path` / `namespace/pod:path`.
`to`	`to(spec: string): this`	Where to copy to, in the same two forms.
`container`	`container(name: string): this`	Which container of the pod (`-c`).
`noPreserve`	`noPreserve(): this`	Do not carry ownership and permissions across (`--no-preserve`).
`retries`	`retries(count: number): this`	Retry a copy out of a container this many times (`--retries`).

KubectlCreateSettings

class

class KubectlCreateSettings extends KubectlSettings

Settings for kubectl create.

Member	Signature	Doc
`file`	`file(path: PathLike): this`	Create from a manifest file, directory, or URL (`-f`); repeatable. For resource-form creation (`create secret …`), use the base `.args(...)`.
`recursive`	`recursive(): this`	Recurse into directories given to `-f` (`-R`).
`dryRun`	`dryRun(mode?: DryRunMode): this`	Preview without persisting (`--dry-run=`; defaults to `client`).
`output`	`output(format: string): this`	Output format, e.g. `yaml` or `json` (`-o`).
`saveConfig`	`saveConfig(): this`	Record the current resource in its annotation (`--save-config`).

KubectlDeleteSettings

class

class KubectlDeleteSettings extends KubectlSettings

Settings for kubectl delete.

Member	Signature	Doc
`file`	`file(path: PathLike): this`	Delete from a manifest file or directory (`-f`); repeatable.
`resource`	`resource(...tokens: string[]): this`	Resource tokens, e.g. `("pod", "web")` or `("deployment/api")`; repeatable.
`selector`	`selector(query: string): this`	Restrict to resources matching a label selector (`-l`).
`all`	`all(): this`	Delete all resources of the given type (`--all`).
`ignoreNotFound`	`ignoreNotFound(): this`	Treat "not found" as a success (`--ignore-not-found`).
`force`	`force(): this`	Force immediate deletion (`--force`).
`gracePeriod`	`gracePeriod(seconds: number): this`	Seconds to wait before forceful termination (`--grace-period`).
`recursive`	`recursive(): this`	Recurse into directories given to `-f` (`-R`).

KubectlDescribeSettings

class

class KubectlDescribeSettings extends KubectlSettings

Settings for kubectl describe.

Member	Signature	Doc
`resource`	`resource(...tokens: string[]): this`	Resource tokens, e.g. `("pod", "web")` or `("deployment/api")`; repeatable.
`selector`	`selector(query: string): this`	Restrict to resources matching a label selector (`-l`).

KubectlDiffSettings

class

class KubectlDiffSettings extends KubectlSettings

Settings for kubectl diff — what an apply would change, without changing it.

diff reports its answer through the exit status: 0 when there is no difference and 1 when there is, with anything above 1 meaning kubectl or the differ failed. "./kubectl.ts".KubectlTasksApi.diff keeps the ordinary contract, so a build that wants the printed diff and a failed target on drift gets both; "./kubectl.ts".KubectlTasksApi.diffHasChanges is the reader that turns the code into a boolean.

Member	Signature	Doc
`file`	`file(path: PathLike): this`	Diff a manifest file, directory, or URL (`-f`); repeatable.
`kustomize`	`kustomize(dir: PathLike): this`	Diff a kustomization directory (`-k`).
`recursive`	`recursive(): this`	Recurse into directories given to `-f` (`-R`).
`serverSide`	`serverSide(): this`	Diff the server-side apply (`--server-side`).
`forceConflicts`	`forceConflicts(): this`	Take ownership of conflicting fields (`--force-conflicts`).
`prune`	`prune(): this`	Include what a prune would delete (`--prune`).
`selector`	`selector(query: string): this`	Restrict to resources matching a label selector (`-l`).
`showManagedFields`	`showManagedFields(): this`	Include the managed fields, which are otherwise hidden (`--show-managed-fields`).
`concurrency`	`concurrency(count: number): this`	How many objects to diff in parallel (`--concurrency`).

KubectlDrainSettings

class

class KubectlDrainSettings extends KubectlSettings

Settings for kubectl drain.

kubectl refuses to drain a node whose pods it cannot safely move, and the two flags that override that refusal are exactly the ones worth being deliberate about: --ignore-daemonsets and --delete-emptydir-data, the second of which destroys local data. Neither is defaulted here.

Member	Signature	Doc
`node`	`node(name: string): this`	The node to drain; required unless a `selector` picks them.
`force`	`force(): this`	Evict pods no controller manages, which nothing will recreate (`--force`).
`ignoreDaemonSets`	`ignoreDaemonSets(): this`	Proceed past DaemonSet-managed pods, which drain never deletes (`--ignore-daemonsets`).
`deleteEmptyDirData`	`deleteEmptyDirData(): this`	Proceed past pods using emptyDir, destroying that data (`--delete-emptydir-data`).
`disableEviction`	`disableEviction(): this`	Delete rather than evict (`--disable-eviction`), which bypasses every PodDisruptionBudget — the guardrail an operator wrote down on purpose.
`gracePeriod`	`gracePeriod(seconds: number): this`	Seconds each pod gets to terminate (`--grace-period`).
`timeout`	`timeout(duration: string): this`	How long to wait for the drain overall, e.g. `5m` (`--timeout`).
`podSelector`	`podSelector(query: string): this`	Only drain pods matching this label selector (`--pod-selector`).
`selector`	`selector(query: string): this`	Drain every node matching this label selector (`-l`).
`skipWaitForDeleteTimeout`	`skipWaitForDeleteTimeout(seconds: number): this`	Stop waiting on pods already deleting this long (`--skip-wait-for-delete-timeout`).
`dryRun`	`dryRun(mode?: DryRunMode): this`	Preview without persisting (`--dry-run=`; defaults to `client`).

KubectlEventsSettings

class

class KubectlEventsSettings extends KubectlSettings

Settings for kubectl events — the first thing to read when a rollout stalls and rollout status will not say why.

Member	Signature	Doc
`forResource`	`forResource(reference: string): this`	Only events about this resource, as `TYPE/NAME` (`--for`).
`types`	`types(...names: string[]): this`	Only events of these types, e.g. `Warning` (`--types`).
`allNamespaces`	`allNamespaces(): this`	Across every namespace (`-A`).
`watch`	`watch(): this`	Keep watching after the listing (`--watch`). A target that watches blocks until something stops it, so pair it with `.killAfter(...)` unless the wait is the point.
`noHeaders`	`noHeaders(): this`	Leave the header row out (`--no-headers`).
`output`	`output(format: string): this`	The output format (`-o`), e.g. `json`.

KubectlExecSettings

class

class KubectlExecSettings extends KubectlSettings

Settings for kubectl exec.

Member	Signature	Doc
`resource`	`resource(name: string): this`	The pod (or `type/name`) to exec into (required).
`container`	`container(name: string): this`	Target a specific container (`-c`).
`stdin`	`stdin(): this`	Keep STDIN open (`-i`).
`tty`	`tty(): this`	Allocate a TTY (`-t`).
`command`	`command(...args: Array<string \| number>): this`	The command and arguments to run in the container (required).

KubectlExplainSettings

class

class KubectlExplainSettings extends KubectlSettings

Settings for kubectl explain — the schema of a resource type.

Member	Signature	Doc
`type`	`type(name: string): this`	The type to explain, e.g. `pods` or `deployments.spec.replicas`.
`recursive`	`recursive(): this`	Print nested fields too (`-R`).
`maxDepth`	`maxDepth(depth: number): this`	Cap how deep `recursive` goes (`--max-depth`).
`apiVersion`	`apiVersion(value: string): this`	Explain a particular API group/version (`--api-version`).
`output`	`output(format: string): this`	How to render the schema (`-o`): `plaintext` or `plaintext-openapiv2`.

KubectlExposeSettings

class

class KubectlExposeSettings extends KubectlSettings

Settings for kubectl expose — a service in front of an existing workload.

Member	Signature	Doc
`resource`	`resource(reference: string): this`	The workload to expose, e.g. `deployment/api`.
`file`	`file(path: PathLike): this`	Expose the workload a manifest identifies instead (`-f`); repeatable.
`port`	`port(value: string \| number): this`	The port the service serves on (`--port`).
`targetPort`	`targetPort(value: string \| number): this`	The container port traffic goes to (`--target-port`).
`type`	`type(value: string): this`	The service type (`--type`), e.g. `LoadBalancer`.
`name`	`name(value: string): this`	The new service's name (`--name`).
`protocol`	`protocol(value: string): this`	The protocol (`--protocol`), e.g. `TCP`.
`selector`	`selector(query: string): this`	The selector the service routes by (`--selector`). kubectl infers it from the exposed resource when it is omitted, and only equality-based requirements are supported here.
`labels`	`labels(value: string): this`	Labels for the created service (`--labels`), comma-separated.
`sessionAffinity`	`sessionAffinity(value: None \| ClientIP): this`	Session affinity (`--session-affinity`): `None` or `ClientIP`.
`dryRun`	`dryRun(mode?: DryRunMode): this`	Preview without persisting (`--dry-run=`; defaults to `client`).

KubectlGetSettings

class

class KubectlGetSettings extends KubectlSettings

Settings for kubectl get.

Member	Signature	Doc
`resource`	`resource(...tokens: string[]): this`	Resource tokens, e.g. `("pods")` or `("pod", "web")`; repeatable.
`output`	`output(format: string): this`	Output format, e.g. `wide`, `yaml`, `json`, `jsonpath=…` (`-o`).
`selector`	`selector(query: string): this`	Restrict to resources matching a label selector (`-l`).
`fieldSelector`	`fieldSelector(query: string): this`	Restrict by field selector (`--field-selector`).
`allNamespaces`	`allNamespaces(): this`	List across all namespaces (`-A`).
`watch`	`watch(on?: boolean): this`	Watch for changes instead of returning once (`-w`); pass `false` to disable.
`showLabels`	`showLabels(): this`	Include resource labels as columns (`--show-labels`).

KubectlKustomizeSettings

class

class KubectlKustomizeSettings extends KubectlSettings

Settings for kubectl kustomize — rendering a kustomization to stdout.

Member	Signature	Doc
`dir`	`dir(path: PathLike): this`	The kustomization directory or repository URL; kubectl assumes `.`.
`output`	`output(path: PathLike): this`	Write the rendered output to a file instead of stdout (`-o`).
`enableHelm`	`enableHelm(): this`	Allow the Helm chart inflator generator (`--enable-helm`).
`loadRestrictor`	`loadRestrictor(value: string): this`	Relax where a kustomization may load files from (`--load-restrictor`).

KubectlLabelSettings

class

class KubectlLabelSettings extends KubectlSettings

Settings for kubectl label.

Member	Signature	Doc
`resource`	`resource(...tokens: string[]): this`	Resource tokens, e.g. `("deploy", "api")` or `("pods", "-l", "app=web")`; repeatable.
`label`	`label(key: string, value: string): this`	Set a label as a `key=value` token; repeatable.
`remove`	`remove(key: string): this`	Remove a label, rendered as kubectl's `key-` syntax; repeatable.
`overwrite`	`overwrite(): this`	Overwrite existing labels (`--overwrite`).
`all`	`all(): this`	Apply to all resources of the given type (`--all`).
`selector`	`selector(query: string): this`	Restrict to resources matching a label selector (`-l`).

KubectlLogsSettings

class

class KubectlLogsSettings extends KubectlSettings

Settings for kubectl logs.

Member	Signature	Doc
`resource`	`resource(name: string): this`	The pod (or `type/name`) to read logs from.
`container`	`container(name: string): this`	Read from a specific container (`-c`).
`selector`	`selector(query: string): this`	Select pods by label instead of naming one (`-l`).
`follow`	`follow(): this`	Stream new log output (`-f`).
`previous`	`previous(): this`	Read the previous container instance's logs (`--previous`).
`tail`	`tail(lines: number): this`	Show only the last N lines (`--tail`).
`since`	`since(duration: string): this`	Only logs newer than a duration, e.g. `5m` (`--since`).
`allContainers`	`allContainers(): this`	Include all containers in the pod (`--all-containers`).
`timestamps`	`timestamps(): this`	Prefix each line with a timestamp (`--timestamps`).

KubectlPatchSettings

class

class KubectlPatchSettings extends KubectlSettings

Settings for kubectl patch.

Member	Signature	Doc
`resource`	`resource(name: string): this`	The resource to patch, e.g. `deployment/api` (required).
`patch`	`patch(content: string): this`	The patch document (`-p`, required).
`type`	`type(strategy: PatchType): this`	The patch strategy (`--type`).

KubectlPortForwardSettings

class

class KubectlPortForwardSettings extends KubectlSettings

Settings for kubectl port-forward.

Member	Signature	Doc
`resource`	`resource(name: string): this`	The pod or service, e.g. `svc/api` (required).
`port`	`port(mapping: string): this`	A port mapping, e.g. `8080:80` or `8080`; repeatable, at least one.
`address`	`address(value: string): this`	The local address(es) to bind (`--address`).

KubectlReplaceSettings

class

class KubectlReplaceSettings extends KubectlSettings

Settings for kubectl replace.

Member	Signature	Doc
`file`	`file(path: PathLike): this`	Replace from a manifest file, directory, or URL (`-f`); repeatable.
`kustomize`	`kustomize(dir: PathLike): this`	Replace from a kustomization directory (`-k`).
`recursive`	`recursive(): this`	Recurse into directories given to `-f` (`-R`).
`force`	`force(): this`	Delete and recreate rather than update (`--force`). This is not a retry knob: the resource genuinely goes away first, so anything depending on it sees it missing.
`gracePeriod`	`gracePeriod(seconds: number): this`	Seconds each object gets to terminate (`--grace-period`).
`timeout`	`timeout(duration: string): this`	How long to wait on the delete half, e.g. `60s` (`--timeout`).
`cascade`	`cascade(strategy: background \| orphan \| foreground): this`	The cascading strategy for dependents (`--cascade`).
`wait`	`wait(): this`	Wait for the resources to be gone before returning (`--wait`).
`dryRun`	`dryRun(mode?: DryRunMode): this`	Preview without persisting (`--dry-run=`; defaults to `client`).

KubectlRolloutSettings

class

class KubectlRolloutSettings extends KubectlSettings

Settings for kubectl rollout.

Member	Signature	Doc
`status`	`status(): this`	Show rollout status (`rollout status`).
`restart`	`restart(): this`	Restart a rollout (`rollout restart`).
`undo`	`undo(): this`	Roll back to the previous revision (`rollout undo`).
`history`	`history(): this`	Show rollout history (`rollout history`).
`pause`	`pause(): this`	Stop the rollout where it is (`rollout pause`) — half of a canary. A paused workload takes no further updates until `resume`.
`resume`	`resume(): this`	Let a paused rollout continue (`rollout resume`).
`resource`	`resource(name: string): this`	The resource, e.g. `deployment/api` (required).
`toRevision`	`toRevision(revision: number): this`	With `undo`, the revision to roll back to (`--to-revision`).
`timeout`	`timeout(duration: string): this`	With `status`, how long to wait, e.g. `60s` (`--timeout`).

KubectlRunSettings

class

class KubectlRunSettings extends KubectlSettings

Settings for kubectl run — one pod, imperatively.

This is for a one-off: a migration job, a debug shell. A workload a build owns belongs in a manifest and goes through "./manifests.ts".KubectlApplySettings, which is declarative and can be diffed.

Member	Signature	Doc
`name`	`name(value: string): this`	The pod's name (required).
`image`	`image(reference: string): this`	The image to run (`--image`, required).
`restart`	`restart(policy: Always \| OnFailure \| Never): this`	The restart policy (`--restart`).
`envVar`	`envVar(key: string, value: string): this`	An environment variable for the container (`--env KEY=VALUE`); repeatable. Named apart from the inherited `.env(...)`, which sets the environment `kubectl` itself runs in.
`labels`	`labels(value: string): this`	Labels for the pod (`--labels`), comma-separated.
`port`	`port(value: string \| number): this`	The port the container exposes (`--port`).
`overrides`	`overrides(json: string): this`	An inline JSON override for the generated pod (`--overrides`).
`expose`	`expose(): this`	Also create a ClusterIP service (`--expose`), which needs `port`.
`command`	`command(first: string, ...rest: string[]): this`	The command and arguments to run, after kubectl's `--` separator. Passing any also sets `--command`, so they replace the image's entrypoint rather than being appended to it.
`dryRun`	`dryRun(mode?: DryRunMode): this`	Preview without persisting (`--dry-run=`; defaults to `client`).

KubectlScaleSettings

class

class KubectlScaleSettings extends KubectlSettings

Settings for kubectl scale.

Member	Signature	Doc
`replicas`	`replicas(count: number): this`	Desired replica count (`--replicas`, required).
`resource`	`resource(name: string): this`	The resource to scale, e.g. `deployment/api`.
`file`	`file(path: PathLike): this`	Scale a resource defined in a file (`-f`).
`currentReplicas`	`currentReplicas(count: number): this`	Only scale if the current replica count matches (`--current-replicas`).
`selector`	`selector(query: string): this`	Restrict to resources matching a label selector (`-l`).
`all`	`all(): this`	Scale all resources of the given type (`--all`).

KubectlSetEnvSettings

class

class KubectlSetEnvSettings extends KubectlSetSettings

Settings for kubectl set env.

Member	Signature	Doc
`set`	`set(key: string, value: string): this`	Set a variable (`-e KEY=VALUE`); repeatable.
`remove`	`remove(key: string): this`	Remove a variable, which kubectl spells `KEY-` (`-e KEY-`); repeatable.
`from`	`from(reference: string): this`	Inject every key of a ConfigMap or Secret (`--from`), e.g. `secret/db`.
`keys`	`keys(...names: string[]): this`	Only these keys of the `from` resource (`--keys`).
`prefix`	`prefix(value: string): this`	Prefix the injected variable names (`--prefix`).
`list`	`list(): this`	Print the environment instead of changing it (`--list`).
`resolve`	`resolve(): this`	Show what the references resolve to when listing (`--resolve`).
`overwrite`	`overwrite(value?: boolean): this`	Whether an existing variable may be replaced (`--overwrite`).

KubectlSetImageSettings

class

class KubectlSetImageSettings extends KubectlSettings

Settings for kubectl set image.

Member	Signature	Doc
`resource`	`resource(name: string): this`	The resource to update, e.g. `deployment/api` (required).
`image`	`image(container: string, reference: string): this`	Set a container's image (`container=image`); repeatable, at least one.
`selector`	`selector(query: string): this`	Restrict to resources matching a label selector (`-l`).
`all`	`all(): this`	Apply to all resources of the given type (`--all`).

KubectlSetResourcesSettings

class

class KubectlSetResourcesSettings extends KubectlSetSettings

Settings for kubectl set resources.

Member	Signature	Doc
`limit`	`limit(resource: string, quantity: string): this`	A resource limit, e.g. `.limit("cpu", "500m")`; repeatable.
`request`	`request(resource: string, quantity: string): this`	A resource request, e.g. `.request("memory", "256Mi")`; repeatable.

KubectlSetSettings

class

class KubectlSetSettings extends KubectlSettings

Base for the kubectl set subcommands that change a pod template in place: they share the target (a resource, a manifest, or everything in the namespace) and the container selection.

Member	Signature	Doc
`resource`	`resource(...names: string[]): this`	The resource to change, e.g. `deployment/api`; repeatable.
`file`	`file(path: PathLike): this`	Change the resource identified by a manifest instead (`-f`); repeatable.
`all`	`all(): this`	Change every resource of the named types in the namespace (`--all`).
`containers`	`containers(pattern: string): this`	Which containers to change (`-c`); kubectl's default is every one.
`selector`	`selector(query: string): this`	Restrict to resources matching a label selector (`-l`).
`local`	`local(): this`	Rewrite the local manifest without contacting the server (`--local`).
`dryRun`	`dryRun(mode?: DryRunMode): this`	Preview without persisting (`--dry-run=`; defaults to `client`).

KubectlSettings

class

class KubectlSettings extends ToolSettings

Base for all kubectl subcommand settings: the binary is kubectl, and the cluster-targeting flags (--namespace, --context, --kubeconfig) are shared by every subcommand.

Member	Signature	Doc
`namespace`	`namespace(name: string): this`	Target a namespace (`--namespace`).
`context`	`context(name: string): this`	Use a named kubeconfig context (`--context`).
`kubeconfig`	`kubeconfig(path: PathLike): this`	Use an explicit kubeconfig file (`--kubeconfig`).

KubectlSettingsRunner

type

type KubectlSettingsRunner = unknown

Runs one prepared kubectl command and returns its output. The default runs it; a test or a build that executes kubectl some other way injects its own with KubectlCanarySettings.runner.

KubectlTaintSettings

class

class KubectlTaintSettings extends KubectlSettings

Settings for kubectl taint.

Member	Signature	Doc
`node`	`node(...names: string[]): this`	A node to taint; repeatable.
`taint`	`taint(key: string, value: string, effect: TaintEffect): this`	Add a taint, as `key=value:effect`; repeatable.
`removeTaint`	`removeTaint(key: string, effect?: TaintEffect): this`	Remove a taint, which kubectl spells with a trailing `-`; repeatable.
`all`	`all(): this`	Taint every node in the cluster (`--all`).
`overwrite`	`overwrite(): this`	Replace a taint of the same key rather than failing (`--overwrite`).
`selector`	`selector(query: string): this`	Taint every node matching a label selector (`-l`).
`dryRun`	`dryRun(mode?: DryRunMode): this`	Preview without persisting (`--dry-run=`; defaults to `client`).

KubectlTasks

const

const KubectlTasks: KubectlTasksApi

Typed task functions for the kubectl CLI.

KubectlTasksApi

interface

interface KubectlTasksApi

The shape of KubectlTasks.

Member	Signature	Doc
`apply`	`apply(configure?: Configure<KubectlApplySettings>): Promise<CommandOutput>`	Apply manifests: `kubectl apply`.
`create`	`create(configure?: Configure<KubectlCreateSettings>): Promise<CommandOutput>`	Create resources: `kubectl create`.
`delete`	`delete(configure?: Configure<KubectlDeleteSettings>): Promise<CommandOutput>`	Delete resources: `kubectl delete`.
`get`	`get(configure?: Configure<KubectlGetSettings>): Promise<CommandOutput>`	List resources: `kubectl get`.
`getNamespaces`	`getNamespaces(configure?: Configure<KubectlGetSettings>): Promise<KubernetesNamespace[]>`	List namespaces as typed `KubernetesNamespace` records: runs `kubectl get namespaces -o json` (forcing JSON output, quietly) and parses the result. Use the lambda for cluster flags or a label `.selector(...)`.
`describe`	`describe(configure?: Configure<KubectlDescribeSettings>): Promise<CommandOutput>`	Describe resources: `kubectl describe`.
`logs`	`logs(configure?: Configure<KubectlLogsSettings>): Promise<CommandOutput>`	Read logs: `kubectl logs`.
`exec`	`exec(configure?: Configure<KubectlExecSettings>): Promise<CommandOutput>`	Exec into a container: `kubectl exec`.
`rollout`	`rollout(configure?: Configure<KubectlRolloutSettings>): Promise<CommandOutput>`	Manage rollouts: `kubectl rollout`.
`scale`	`scale(configure?: Configure<KubectlScaleSettings>): Promise<CommandOutput>`	Scale a workload: `kubectl scale`.
`setImage`	`setImage(configure?: Configure<KubectlSetImageSettings>): Promise<CommandOutput>`	Update a container image: `kubectl set image`.
`annotate`	`annotate(configure?: Configure<KubectlAnnotateSettings>): Promise<CommandOutput>`	Annotate resources: `kubectl annotate`.
`label`	`label(configure?: Configure<KubectlLabelSettings>): Promise<CommandOutput>`	Label resources: `kubectl label`.
`patch`	`patch(configure?: Configure<KubectlPatchSettings>): Promise<CommandOutput>`	Patch a resource: `kubectl patch`.
`portForward`	`portForward(configure?: Configure<KubectlPortForwardSettings>): Promise<CommandOutput>`	Forward local ports: `kubectl port-forward`.
`wait`	`wait(configure?: Configure<KubectlWaitSettings>): Promise<CommandOutput>`	Wait for a condition: `kubectl wait`.
`top`	`top(configure?: Configure<KubectlTopSettings>): Promise<CommandOutput>`	Show resource usage: `kubectl top`.
`diff`	`diff(configure?: Configure<KubectlDiffSettings>): Promise<CommandOutput>`	Show what an apply would change: `kubectl diff`. The command exits 1 when it finds differences, so this task fails the target on drift — which is what a gate wants. Use `KubectlTasksApi.diffHasChanges` to read the answer as a value instead.
`diffHasChanges`	`diffHasChanges(configure?: Configure<KubectlDiffSettings>): Promise<boolean>`	Whether an apply would change anything: `true` when `kubectl diff` reports differences, `false` when it reports none. An exit code above 1 means kubectl or its differ failed and still fails the build.
`replace`	`replace(configure?: Configure<KubectlReplaceSettings>): Promise<CommandOutput>`	Replace a resource wholesale: `kubectl replace`.
`getEntries`	`getEntries(configure?: Configure<KubectlGetSettings>): Promise<KubernetesResource[]>`	Every matching resource as typed `KubernetesResource` records: runs `kubectl get … -o json` and parses the common metadata, whatever the kind.
`explain`	`explain(configure?: Configure<KubectlExplainSettings>): Promise<CommandOutput>`	Show a resource type's schema: `kubectl explain`.
`setEnv`	`setEnv(configure?: Configure<KubectlSetEnvSettings>): Promise<CommandOutput>`	Change environment variables on a pod template: `kubectl set env`.
`setResources`	`setResources(configure?: Configure<KubectlSetResourcesSettings>): Promise<CommandOutput>`	Change requests and limits on a pod template: `kubectl set resources`.
`run`	`run(configure?: Configure<KubectlRunSettings>): Promise<CommandOutput>`	Run one pod imperatively: `kubectl run`.
`expose`	`expose(configure?: Configure<KubectlExposeSettings>): Promise<CommandOutput>`	Put a service in front of a workload: `kubectl expose`.
`cp`	`cp(configure?: Configure<KubectlCpSettings>): Promise<CommandOutput>`	Copy files into or out of a container: `kubectl cp`.
`events`	`events(configure?: Configure<KubectlEventsSettings>): Promise<CommandOutput>`	Report cluster events: `kubectl events`.
`eventEntries`	`eventEntries(configure?: Configure<KubectlEventsSettings>): Promise<KubernetesEvent[]>`	The events as typed `KubernetesEvent` records — what a build reads when a rollout stalls and `rollout status` will not say why.
`currentContext`	`currentContext(configure?: Configure<KubectlConfigCurrentContextSettings>): Promise<string>`	The name of the current kubeconfig context: `kubectl config current-context`.
`contexts`	`contexts(configure?: Configure<KubectlConfigGetContextsSettings>): Promise<string[]>`	The available context names: `kubectl config get-contexts -o name`.
`useContext`	`useContext(configure?: Configure<KubectlConfigUseContextSettings>): Promise<CommandOutput>`	Switch the current context: `kubectl config use-context`.
`setContext`	`setContext(configure?: Configure<KubectlConfigSetContextSettings>): Promise<CommandOutput>`	Write a context entry: `kubectl config set-context`.
`configView`	`configView(configure?: Configure<KubectlConfigViewSettings>): Promise<CommandOutput>`	Show the merged kubeconfig: `kubectl config view`.
`version`	`version(configure?: Configure<KubectlVersionSettings>): Promise<CommandOutput>`	Print the client and server versions: `kubectl version`.
`versionInfo`	`versionInfo(configure?: Configure<KubectlVersionSettings>): Promise<KubernetesVersion>`	The client and server versions, parsed from `kubectl version -o json`.
`clusterInfo`	`clusterInfo(configure?: Configure<KubectlClusterInfoSettings>): Promise<CommandOutput>`	Show where the cluster's services live: `kubectl cluster-info`.
`apiResources`	`apiResources(configure?: Configure<KubectlApiResourcesSettings>): Promise<CommandOutput>`	List the server's API resources: `kubectl api-resources`.
`apiVersions`	`apiVersions(configure?: Configure<KubectlApiVersionsSettings>): Promise<CommandOutput>`	List the server's API versions: `kubectl api-versions`.
`authCanI`	`authCanI(configure?: Configure<KubectlAuthCanISettings>): Promise<CommandOutput>`	Check a permission: `kubectl auth can-i`.
`canI`	`canI(configure?: Configure<KubectlAuthCanISettings>): Promise<boolean>`	Whether the action is allowed. `kubectl auth can-i` answers through its exit status, so this reads the code rather than failing the build on a routine "no".
`kustomize`	`kustomize(configure?: Configure<KubectlKustomizeSettings>): Promise<CommandOutput>`	Render a kustomization to stdout: `kubectl kustomize`.
`cordon`	`cordon(configure?: Configure<KubectlCordonSettings>): Promise<CommandOutput>`	Mark a node unschedulable, or schedulable again: `kubectl cordon`/`uncordon`.
`drain`	`drain(configure?: Configure<KubectlDrainSettings>): Promise<CommandOutput>`	Evict a node's pods before maintenance: `kubectl drain`.
`taint`	`taint(configure?: Configure<KubectlTaintSettings>): Promise<CommandOutput>`	Add or remove node taints: `kubectl taint`.

KubectlTopSettings

class

class KubectlTopSettings extends KubectlSettings

Settings for kubectl top.

Member	Signature	Doc
`pods`	`pods(): this`	Report pod usage (`top pods`).
`nodes`	`nodes(): this`	Report node usage (`top nodes`).
`name`	`name(value: string): this`	Limit to a single named pod or node.
`selector`	`selector(query: string): this`	Restrict to resources matching a label selector (`-l`).
`containers`	`containers(): this`	Break pod usage down by container (`--containers`).
`allNamespaces`	`allNamespaces(): this`	Report across all namespaces (`-A`).

KubectlVersionSettings

class

class KubectlVersionSettings extends KubectlSettings

Settings for kubectl version.

Member	Signature	Doc
`clientOnly`	`clientOnly(): this`	Report the client's version without reaching a cluster (`--client`).
`output`	`output(format: json \| yaml): this`	The output format (`-o`): `json` or `yaml`.

KubectlWaitSettings

class

class KubectlWaitSettings extends KubectlSettings

Settings for kubectl wait.

Member	Signature	Doc
`file`	`file(path: PathLike): this`	Wait on resources defined in a file (`-f`); repeatable.
`resource`	`resource(...tokens: string[]): this`	Resource tokens, e.g. `("pod/web")` or `("pods")`; repeatable.
`forCondition`	`forCondition(condition: string): this`	The condition to wait for, e.g. `condition=Available` or `delete`.
`timeout`	`timeout(duration: string): this`	How long to wait, e.g. `60s` (`--timeout`).
`selector`	`selector(query: string): this`	Restrict to resources matching a label selector (`-l`).
`all`	`all(): this`	Wait on all resources of the given type (`--all`).

KubernetesEvent

interface

interface KubernetesEvent

One event of "./kubectl.ts".KubectlTasksApi.eventEntries — what the cluster reports about a resource, which is the first thing to read when a rollout stalls.

Member	Signature	Doc
`type`	`type: string`	`Normal` or `Warning` (`type`); `""` when the field is absent.
`reason`	`reason: string`	The short machine-readable cause (`reason`).
`message`	`message: string`	The human-readable detail (`message`).
`regarding?`	`regarding?: string`	What the event is about, as `Kind/name` (`regarding`/`involvedObject`).
`count?`	`count?: number`	How many times it has repeated (`series.count` or `count`).
`lastSeen?`	`lastSeen?: string`	When it was last seen, ISO 8601, when the payload carries a time.

KubernetesNamespace

interface

interface KubernetesNamespace

A Kubernetes namespace, parsed from kubectl get namespaces -o json — the typed result of KubectlTasksApi.getNamespaces.

Member	Signature	Doc
`name`	`name: string`	The namespace name (`metadata.name`).
`status`	`status: string`	The lifecycle phase (`status.phase`), e.g. `"Active"` or `"Terminating"`; `""` when the field is absent.
`labels`	`labels: Record<string, string>`	The namespace labels (`metadata.labels`), string-valued; `{}` when none.
`createdAt?`	`createdAt?: string`	When the namespace was created (`metadata.creationTimestamp`), if present.

KubernetesResource

interface

interface KubernetesResource

One resource of "./kubectl.ts".KubectlTasksApi.getEntries — the fields every Kubernetes object carries, whatever its kind.

Member	Signature	Doc
`name`	`name: string`	The object's name (`metadata.name`).
`kind`	`kind: string`	Its kind, e.g. `Pod` (`kind`); `""` when the field is absent.
`namespace?`	`namespace?: string`	Its namespace (`metadata.namespace`), absent for a cluster-scoped object.
`labels`	`labels: Record<string, string>`	Its labels (`metadata.labels`), string-valued; `{}` when none.
`createdAt?`	`createdAt?: string`	When it was created (`metadata.creationTimestamp`), if present.

KubernetesVersion

interface

interface KubernetesVersion

The client and server versions parseVersion reads.

Member	Signature	Doc
`client?`	`client?: string`	The `kubectl` binary's version, e.g. `v1.31.2`.
`server?`	`server?: string`	The API server's version, absent when only the client was asked for.

parseEvents

function

function parseEvents(json: string): KubernetesEvent[]

Parse the JSON text of kubectl events -o json into KubernetesEvent records. Items carrying neither a reason nor a message are skipped; empty input yields []. Throws if the text is non-empty and not valid JSON.

parseNamespaces

function

function parseNamespaces(json: string): KubernetesNamespace[]

Parse the JSON text of kubectl get namespaces -o json — a List, or a single namespace object — into KubernetesNamespace records. Items without a metadata.name are skipped; empty input yields []. Throws if the text is non-empty and not valid JSON.

parseResources

function

function parseResources(json: string): KubernetesResource[]

Parse the JSON text of any kubectl get … -o json — a List, or a single object — into KubernetesResource records. Items without a metadata.name are skipped; empty input yields []. Throws if the text is non-empty and not valid JSON.

parseVersion

function

function parseVersion(json: string): KubernetesVersion

Parse the JSON text of kubectl version -o json into the two version strings. A payload that is not an object, or carries neither version, yields an empty record rather than throwing — the versions are advisory.

PatchType

type

type PatchType = strategic | merge | json

A patch strategy accepted by kubectl patch --type.

RolloutAction

type

type RolloutAction = status | restart | undo | history | pause | resume

A rollout sub-action: kubectl rollout <action>.

TaintEffect

type

type TaintEffect = NoSchedule | PreferNoSchedule | NoExecute

What a taint does to pods that do not tolerate it.