@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`).

# 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`).

# 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`).

# 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).

# 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`).

# 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`).

# 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`).
`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`).

# 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`).

# 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`).

# 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`).

# 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`.

# 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`).

# 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`).

# 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.

# 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.

# PatchType type

type PatchType = strategic | merge | json

A patch strategy accepted by kubectl patch --type.

# RolloutAction type

type RolloutAction = status | restart | undo | history

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