Full API - k8s-tools

API: k8s.mk

This is the complete list of namespaces & static public targets that are available from k8s.mk, along with their documentation. Documentation is pulled automatically from the latest source.

Dynamic target scaffolding is also generated in a several categories for each of the containers defined in k8s-tools.yml, such as helpers for target-dispatch, debugging shells for that container, etc. For an overview of autogenerated targets, see instead the upstream compose.mk documentation. See also the overview of CLI help.

k8s.mk: (Static Targets)

Targets are usable as an API, either as prereq-targets or as part of the body in your project automation.
Targets are usable interactively from your shell as ./k8s.mk <target> or make <target> if you've include'd the library file.
You'll need to have setup KUBECONFIG before running most of these

Target names are reserved names after declaration, but collisions aren't likely because things are organized into a few namespaces:

Most targets depend on compose.mk. When used in stand-alone mode, k8s.mk will attempt to import compose.mk from the same directory.
Most targets have a soft-requirement k8s-tools.yml. This isn't always a hard-requirement if you have tools like kubectl available already on the docker-host.
Targets are usable interactively from your shell as make <target> or ./k8s.mk <target>. If you use k8s.mk directly here, you need to set vars like KUBECONFIG yourself instead of relying on your project Makefile to set them up.
Targets are usable as an API, either as prereq-targets or as part of the body in your targets.
Target names are reserved names after declaration. Things are organized into a few namespaces, which hopefully avoids collisions with your project targets.
k8s.* targets: Default namespace with general helpers. These targets only use things available in the k8s:base container.
k3d.* targets:: Helpers for working with the k3d tool / container
kubefwd.* targets: Helpers for working with kubefwd tool / container
helm.* targets: Helpers for working with helm tool / container

API: k8s

DOCS: [1] https://robot-wranglers.github.io/k8s-tools/api#api-k8s

For more details, read on into the API, or see the k8s:base container spec in k8s-tools.yml

This documentation is pulled automatically from source.

`k8s.ansible`

Interface for ansible's `kubernetes.core.k8s` module[1].
 This accepts only module args, but there are a few ways to pass them.  
 See the docs in 'ansible.adhoc/<module>' for discussion of examples.

 * `[1]`: https://docs.ansible.com/ansible/latest/collections/kubernetes/core/k8s_module.html

`k8s.cluster.ready`

Checks whether the cluster is available.  
 This just returns the exit status of cluster-info, and not 
 whether pods are all in a ready state. For that, see 'k8s.wait'

 EXAMPLE: 
   ./k8s.mk k8s.cluster.ready

 EXAMPLE: ( in a loop )
   ./k8s.mk flux.loop.until/k8s.cluster.ready

 REFS:
   * `[1]`: https://github.com/alecjacobs5401/kubectl-sick-pods

`k8s.cluster.wait`

Waits until all pods in all namespaces are ready.  (Alias for 'k8s.namespace.wait/all')

`k8s.commander`

TUI layout providing an overview for docker.  
 This has 3 panes by default, where the main pane is lazydocker, plus two utility panes.
 Automation also ensures that lazydocker always starts with the "statistics" tab open.

`k8s.commander/<arg>`

Sends the given target(s) to the main pane.

 USAGE:
   ./k8s.mk k8s.commander/<target1>,<target2>

`k8s.get/<arg>`

`k8s.graph`

Alias for k8s.graph/all/pods.  This returns dot-format data.

`k8s.graph.tui`

Alias for 'k8s.graph.tui/all/pods'.  This prints a visual graph on the terminal.

`k8s.graph.tui/<arg>`

Previews topology for a given kubernetes <namespace>/<kind> in a way that's terminal-friendly.

 This is a human-friendly way to visualize progress or changes, because it supports 
 very large input data from complex deployments with lots of services/pods, either in 
 one namespace or across the whole cluster. To do that, it has to throw away some 
 information compared with raw kubectl output, and node labels on the graph aren't 
 visible.

 This is basically a pipeline from graphs in dot format, generated by kubectl-graph, 
 then passed through some image-magick transformations, and then pushed into 
 the 'chafa' tool for generating ASCII-art from images.

 USAGE: (same as k8s.graph)
   ./k8s.mk k8s.graph.tui/<namespace>/<kind>
   ./k8s.mk k8s.graph.tui/<namespace>/<kind>,<outfile>

`k8s.graph/<arg>`

Graphs resources under the given namespace, for the given kind, in dot-format.
 Pipe Friendly: results are always dot files.  Caller should handle any errors.

 This requires the krew plugin "graph" (installed by default with k8s-tools.yml).

 USAGE: 
     ./k8s.mk k8s.graph/<namespace>/<kind>
     ./k8s.mk k8s.graph/<namespace>/<kind>,<outfile>

 Argument for 'kind' must be provided, but may be "all".

`k8s.help`

Shows targets for just the 'k8s' namespace.

`k8s.kubens.create/<arg>`

Context-manager.  Activates the given namespace, creating it first if necessary.

 NB: This modifies state in the kubeconfig, so that it can effect contexts 
 outside of the current process, therefore this is not thread-safe.

 USAGE: 
    ./k8s.mk k8s.kubens.create/<namespace>

`k8s.kubens/<arg>`

Context-manager.  Activates the given namespace.
 NB: This modifies state in the kubeconfig, so that it can effect contexts 
 outside of the current process, therefore this is not thread-safe.

 USAGE:  
   ./k8s.mk k8s.kubens/<namespace>

`k8s.namespace.fwd/<arg>`

Alias for kubefwd.start/<arg>

`k8s.namespace.label/<arg>`

Appends the given label to the given namespace.

 USAGE: 
   key=<key> val=<val> ./k8s.mk k8s.namespace.label/<namespace>
   ./k8s.mk k8s.namespace.label/<namespace>/<key>/<val>

`k8s.namespace.wait/<arg>`

Waits for every pod in the given namespace to be ready.

 This uses only kubectl/jq to loop on pod-status, but assumes that 
 the krew-plugin 'sick-pods'[1] is available for formatting the 
 user-message.  See `k8s.wait` for an alias that waits on all pods.

 NB: If the parameter is "all" then this uses --all-namespaces

 USAGE: 
   ./k8s.mk k8s.namespace.wait/<namespace>

 REFS:
   * `[1]`: https://github.com/alecjacobs5401/kubectl-sick-pods

`k8s.namespace/<arg>`

Context-manager.  Activates the given namespace.

 NB: This modifies state in the kubeconfig, so that it can effect contexts 
 outside of the current process, therefore this is not thread-safe.

 USAGE:  
     ./k8s.mk k8s.namespace/<namespace>

`k8s.pod.shell/<arg>`

This drops into a debugging shell for the named pod using `kubectl exec`,
 plus a streaming version of the same which allows for working with pipes.

 NB: This target assumes that the named pod actually exists.  If you want
 an idempotent create-operation for such a pod.. see `k8s.test_harness`.

 NB: This target attempts to be "universal", so that it may run from the 
 docker host or inside the `k8s:base` container.  This works by detecting 
 aspects of the caller context.  In general, it tries to use k8s-tools.yml 
 when that makes sense and if it's present, falling back to kubectl.

 USAGE: Interactive shell in pod:
   ./k8s.mk k8s.shell/<namespace>/<pod_name>

`k8s.ready`

Checks whether the cluster is available.  
 This just returns the exit status of cluster-info, and not 
 whether pods are all in a ready state. For that, see 'k8s.wait'

 EXAMPLE: 
   ./k8s.mk k8s.cluster.ready

 EXAMPLE: ( in a loop )
   ./k8s.mk flux.loop.until/k8s.cluster.ready

 REFS:
   * `[1]`: https://github.com/alecjacobs5401/kubectl-sick-pods

`k8s.stat`

Describes status for cluster, cluster auth, and namespaces.
 Not pipe friendly, and not suitable for parsing!  

 This is just for user information, as it's generated from 
 a bunch of tools that are using very different output styles.

 For a shorter, looping version that's suitable as a tmux widget, see 'k8s.stat.widget'

`k8s.stat.ctx`

Output of `kubectx`

`k8s.stat.env`

Shows cluster, kube, and docker environment variables

`k8s.stat.ns`

Shows all namespaces for the current cluster.
 (This is just the output of `kubens` with no arguments)

`k8s.test_harness.random`

Starts a test-pod with a random name in the given namespace, optionally blocking until it's ready.

 USAGE: 
    `k8s.test_harness.random`

`k8s.test_harness/<arg>`

Starts a test-pod in the given namespace, optionally blocking until it's ready.
 When no image is provided, this will use 'IMG_ALPINE_K8S' as default.

 USAGE: 
    `k8s.test_harness/<namespace>/<pod_name>` or 
    `k8s.test_harness/<namespace>/<pod_name>/<image>`

`k8s.wait`

Waits until all pods in all namespaces are ready.  (Alias for 'k8s.namespace.wait/all')

`k8s.wait.quiet`

API: ansible

DOCS: [1] https://robot-wranglers.github.io/k8s-tools/api#api-ansible

These targets use the ansible container, but are generally safe to run from the docker-host.

This documentation is pulled automatically from source.

`ansible.adhoc/<arg>`

An interface into the named ansible module.  Just pass the module-arguments.  
 Like adhoc ansible, this allows you to call a task without a playbook.
 This actually generates a playbook JIT though, which makes things 
 more flexible.

 USAGE:
   echo '<arg_json>' | ./compose.mk ansible.adhoc/<ansible_module_name>

`ansible.blockinfile`

Interface for ansible's block-in-file module[1].
 This accepts only module args, but there are several ways to pass them.  
 See the docs in ansible.adhoc/<module> for discussion of examples.

 USAGE:
   echo <json_data> | ./k8s.mk ansible.blockinfile
   ./k8s.mk jb <key1>=<val1> <keyn>=<valn> | ./k8s.mk ansible.blockinfile
   data="<key1>=<val1> <keyn>=<valn>" ./k8s.mk ansible.blockinfile

 EXAMPLE:
   path=.gitignore block=".flux.stage.*" | ./k8s.mk ansible.blockinfile

 * `[1]`: https://docs.ansible.com/ansible/latest/collections/ansible/builtin/blockinfile_module.html

`ansible.helm`

Interface for ansible's helm module[1].
 This accepts only module args, but there are a few ways to pass them.  
 See the docs in 'ansible.adhoc/<module>' for discussion of examples.

 * `[1]`: https://docs.ansible.com/ansible/latest/collections/kubernetes/core/helm_module.html

`ansible.kubernetes.core.k8s`

Interface for ansible's `kubernetes.core.k8s` module[1].
 This accepts only module args, but there are a few ways to pass them.  
 See the docs in 'ansible.adhoc/<module>' for discussion of examples.

 * `[1]`: https://docs.ansible.com/ansible/latest/collections/kubernetes/core/k8s_module.html

`ansible.run`

Runs the input-stream as an ansible playbook.
 This calls ansible in a way that ensures all output is JSON.

 USAGE:
   cat <playbook> | ./compose.mk ansible.run

`ansible.run/<arg>`

Runs the given playbook file.
 This calls ansible in a way that ensures all output is JSON.

 USAGE: 
   ./k8s.mk ansible.run/<path>

API k3d

The k3d.* targets describe a small interface for working with k3d[2].

Most targets in this namespace will use k3d directly, and so are usually dispatched, and not run from the host. Most targets are small utilities that can help to keep common tasks idempotent, but there's also a TUI that provides a useful overview of what's going on with K3d

DOCS: [1]: https://robot-wranglers.github.io/k8s-tools/api#api-k3d\ [2]:

For more details, read on into the API, or see the k8s:k3d container spec in k8s-tools.yml

This documentation is pulled automatically from source.

`k3d.cluster.create/<arg>`

Creates a k3d cluster with the given name, using the given configuration.
 This supports most of the usual command-line options, but they are passed 
 as variables.

 USAGE:
   k3d_servers=.. k3d_agents=.. 
   k3d_port=.. k3d_api_port=.. 
     ./k8s.mk k3d.cluster.create/<cluster_name>

`k3d.cluster.delete/<arg>`

Idempotent version of k3d cluster delete 

 USAGE:
   ./k8s.mk k3d.cluster.delete/<cluster_name>

`k3d.cluster.exists/<arg>`

Succeeds iff cluster exists.

`k3d.cluster.get_or_create/<arg>`

Create a k3d cluster if it does not already exist.

`k3d.cluster.list`

Returns cluster-names, newline delimited.

 USAGE:  
   ./k8s.mk k3d.cluster.list

`k3d.commander`

Starts a 4-pane TUI dashboard, using the commander layout.  
 This opens 'lazydocker', 'ktop', and other widgets that are convenient for working with k3d.

 USAGE:  
   KUBECONFIG=.. ./k8s.mk k3d.commander/<namespace>

`k3d.has_cluster/<arg>`

Alias for k3d.cluster.exists/<arg>

`k3d.help`

Shows targets for just the 'k3d' namespace.

`k3d.list`

Returns cluster-names, newline delimited.

 USAGE:  
   ./k8s.mk k3d.cluster.list

`k3d.panic`

Non-graceful stop for everything that is k3d related. 

 USAGE:  
   ./k8s.mk k3d.panic

`k3d.stat`

Show status for k3d.

API: kubefwd

These targets use the kubefwd container, but are generally safe to run from the docker-host.

The kubefwd.* targets describe a small interface for working with kubefwd. It aims to cleanly background / foreground kubefwd in an unobtrusive way, with clean setup/teardown and reasonable defaults for usage per-project.

Forwarding is not just for ports but for DNS as well. Note that this takes effect everywhere, including the containers inside k8s-tools.yml via /etc/hosts bind-mount, as it does on the docker-host.

DOCS: [1] https://robot-wranglers.github.io/k8s-tools/api#api-k8smk

This documentation is pulled automatically from source.

`kubefwd.help`

Shows targets for just the 'kubefwd' namespace.

`kubefwd.panic`

Non-graceful stop for everything that is kubefwd related.

 Emergency use only; this can clutter up your /etc/hosts
 file as kubefwd may not get a chance to clean things up.

 USAGE:  
   ./k8s.mk kubefwd.panic

`kubefwd.ps`

`kubefwd.start/<arg>`

Runs kubefwd for the given namespace, finding and forwarding ports/DNS for the given 
 service, or for all services. This is idempotent, and implicitly stops port-forwarding 
 if it is running, then restarts it. 

 NB: This target should only run from the docker host (not from the kubefwd container),  
 and it assumes k8s-tools.yml is present with that filename. Simple port-mapping and 
 filtering by name is supported; other usage with selectors/labels/reservations/etc 
 should just invoke kubefwd directly.

 USAGE: 
   ./k8s.mk kubefwd/<namespace>
   ./k8s.mk kubefwd/<namespace>/<svc_name>
     mapping="8080:80" ./k8s.mk kubefwd/<namespace> 
   mapping="8080:80" ./k8s.mk kubefwd/<namespace>/<svc_name>

`kubefwd.stat`

Display status info for all kubefwd instances that are running

`kubefwd.stop/<arg>`

Stops the named kubefwd instance.
 This is mostly for internal usage, usually you want 'kubefwd.start' or 'kubefwd.panic'

 USAGE:
    ./k8s.mk kubefwd.stop/<namespace>/<svc_name>

API: helm

DOCS: [1] https://robot-wranglers.github.io/k8s-tools/api#api-helm

For more details, read on into the API, or see the k8s:helm container spec in k8s-tools.yml.

This documentation is pulled automatically from source.

`helm.dispatch/.helm.repo.list`

`helm.release.missing/<arg>`

`helm.release.present/<arg>`

`helm.release.stat/<arg>`

Like `helm.status`, but strict and quiet for use with conditionals.
 Result status is an error if the given repo name doesnt exist 

 USAGE:
  ./k8s.mk helm.stat/<release_name>

`helm.release.status/<arg>`

Interface to `helm status`, this returns information for the given release.
 Always returns JSON.  Not strict: no error will be 
 thrown in case the repo doesn't exist.

 USAGE:
  ./k8s.mk helm.status/<release_name>

`helm.repo.list`

Returns JSON for the currently available helm repositories.

`helm.repo.require/<arg>`

Add the named helm repository iff it's missing.

 USAGE:
  url=<repo_url> ./k8s.mk helm.repo.require/<name>