KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#developer-tools #claude-code #codex #typescript #ai-agents #dsh #dsh-plugin #deepseek-harness #ai-agent #mcp #agent-skills #macos

run-job

★ 210 Open GitHub ↗

Run a Kubernetes Job and get the logs when it's done 🏃‍♂️

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

## run-job 🏃‍♂️

[![Sponsor this](https://img.shields.io/static/v1?label=Sponsor&message=%E2%9D%A4&logo=GitHub&link=https://github.com/sponsors/alexellis)](https://github.com/sponsors/alexellis)
[![Github All Releases](https://img.shields.io/github/downloads/alexellis/run-job/total.svg)]()
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![build](https://github.com/alexellis/run-job/actions/workflows/build.yml/badge.svg)](https://github.com/alexellis/run-job/actions/workflows/build.yml)

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](https://github.com/openfaas/config-checker) 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:

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

Download run-job from [the releases page](https://github.com/alexellis/run-job/releases), or use arkade:

```bash
$ arkade get run-job
```

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

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

### Example 2 - kubectl with RBAC

In order to access the K8s API, [an RBAC file](/examples/kubectl/rbac.yaml) 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](/examples/kubectl/kubectl_get_nodes_job.yaml).

```bash
$ 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](/examples/cows/Dockerfile)

cows.yaml:

```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:

```bash
$ run-job -f cows.yaml

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

Or run from the examples repo:

```bash
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](https://github.com/alexellis/jaas) built in 2017, now deprecated for running jobs on Docker Swarm
* [stefanprodan/kjob](https://github.com/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

run-job

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README