Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/alexellis/run-job

Run a Kubernetes Job and get the logs when it's done 🏃‍♂️
https://github.com/alexellis/run-job

Last synced: 21 days ago
JSON representation

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

Host: GitHub
URL: https://github.com/alexellis/run-job
Owner: alexellis
License: mit
Created: 2022-09-05T14:10:29.000Z (over 2 years ago)
Default Branch: master
Last Pushed: 2024-08-13T22:32:56.000Z (4 months ago)
Last Synced: 2024-11-13T01:03:29.818Z (about 1 month ago)
Language: Go
Homepage: https://blog.alexellis.io/fixing-the-ux-for-one-time-tasks-on-kubernetes/
Size: 11.3 MB
Stars: 208
Watchers: 4
Forks: 9
Open Issues: 8
Metadata Files:
- Readme: README.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS

Awesome Lists containing this project

my-awesome - alexellis/run-job - 08 star:0.2k fork:0.0k Run a Kubernetes Job and get the logs when it's done 🏃‍♂️ (Go)
awesome-repositories - alexellis/run-job - Run a Kubernetes Job and get the logs when it's done 🏃‍♂️ (Go)

README

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