run-job

README

run-job 🏃‍♂️

The easiest way to run a simple one-shot job on Kubernetes.

run-job 🏃‍♂️ does the following with a simple YAML file definition:

• Creates a Kubernetes Job
• Watches until it passes or fails
• Collects its logs (if available)
• Deletes the job

It's primary usecase is for checking OpenFaaS installations for customers where it requires a service account to access various resources in a controlled way.

Examples

The first example is a real-world job for OpenFaaS customers, you probably won't run this example yourself, but read over it to learn the syntax and options. Then feel free to try Example 2 and 3, which anyone should be able to run.

The image: field in the Job YAML is for a container image that can be pulled by the cluster.

Note: the examples in this repo are built with the faas-cli publish command because it can create multi-arch container images that work on PCs and ARM devices. You can build your images however you like, or by manually typing in various buildx commands for multi-arch.

Example 1 - a customer diagnostics tool with a service account

Create a job.yaml file:

name: checker
image: ghcr.io/openfaas/config-checker:latest
namespace: openfaas
sa: openfaas-checker

Download run-job from the releases page, or use arkade:

$ arkade get run-job

Then start the job defined in job.yaml and export the logs to a report.txt file:

$ run-job \
    -f job.yaml \
    -out report.txt

Example 2 - kubectl with RBAC

In order to access the K8s API, an RBAC file is required along with a serviceAccount field in the job YAML.

The command kubectl get nodes -o wide configured in the job's YAML file.

$ kubectl apply -f ./examples/kubectl/rbac.yaml
$ run-job -f ./examples/kubectl/kubectl_get_nodes_job.yaml

Created job get-nodes.default (e99686bf-2064-4659-8160-ec28b5d820f0)
...
Job get-nodes.default (e99686bf-2064-4659-8160-ec28b5d820f0) succeeded 
Deleted job get-nodes

Recorded: 2023-10-20 12:44:37.097486774 +0000 UTC

NAME           STATUS   ROLES                       AGE   VERSION        INTERNAL-IP   EXTERNAL-IP      OS-IMAGE             KERNEL-VERSION
k3s-agent-1    Ready    <none>                      63d   v1.27.4+k3s1   192.168.3.4   101.58.106.152   Ubuntu 22.04.2 LTS   5.15.0-73-generic
k3s-server-1   Ready    control-plane,etcd,master   71d   v1.27.4+k3s1   192.168.3.1   101.58.106.241   Ubuntu 22.04.2 LTS   5.15.0-73-generic
k3s-server-2   Ready    control-plane,etcd,master   62d   v1.27.4+k3s1   192.168.3.2   101.58.106.122   Ubuntu 22.04.2 LTS   5.15.0-73-generic
k3s-server-3   Ready    control-plane,etcd,master   62d   v1.27.4+k3s1   192.168.3.3   101.58.106.98    Ubuntu 22.04.2 LTS   5.15.0-73-generic

Example 3 - light relief with ASCII cows

See also: examples/cows/Dockerfile

cows.yaml:

$ cat <<EOF > cows.yaml
# Multi-arch image for arm64, amd64 and armv7l
image: alexellis2/cows:2022-09-05-1955
name: cows
EOF

Run the job:

$ run-job -f cows.yaml

        ()  ()
         ()()
         (oo)
  /-------UU
 / |     ||
*  ||w---||
   ^^    ^^
Eh, What's up Doc?

Or run from the examples repo:

run-job -f ./examples/cows/cows_job.yaml

Why does this tool exist?

Running a Job in Kubernetes is confusing:

• The spec is very different to what we're used to building (Pods/Deployments)
• The API is harder to use to check if things worked since it uses conditions
• Getting the name of the Pod created by a job is a pain
• Getting the logs from a job is a pain, and needs multiple get/describe/logs commands

Inspired by:

• alexellis/jaas built in 2017, now deprecated for running jobs on Docker Swarm
• stefanprodan/kjob by Stefan Prodan, now unmaintained for 3 years

Can I get a new option / field / feature?

Raise an issue and explain why you need it and whether it's for work or pleasure.

PRs will not be approved prior to an issue being created and agreed upon.

License: MIT