---
# System prepended metadata

title: Gangplank

---

# Gangplank


## Gangplank
Gangplank uses a yaml file called 'jobspec' as the primary input which defines how coreos-assembler will be run. The jobspec defines stages that can be run across different pods. Here is a sample jobspec:
```job:
  build_name: me
  strict: true
recipe:
  git_ref:
  git_url:
stages:
- id: first
  description: build
  build_artifacts:
  - base
  - aws
- id: second
  description: do stuff
  commands:
  - echo 'hello world'
  - ls
```

Gangplank has syntatic sugar for the jobspec so users do not need to know everything about the coreos-assembler commands.  In the sample jobspec, the `base` `build_artifacts` in the first stage creates an ostree and a qcow2 by running `coreos-assembler fetch` and `coreos-assembler build`. The `aws` `build_artifacts` creates the AWS image by running `coreos-assembler buildextend-aws`.

Users can also run arbitrary commands as shown in the second stage.

There are additional options in the stages such as `concurrent_execution` and `blocking` which control when pods execute the stages.

## Running Gangplank
Gangplank operates in 3 different modes
1. BuildConfig Mode
1. Unbounded Pod Mode
1. Podman Mode

BuildConfig and unbounded pod mode are considered in cluster since they operate inside a kubernetes or OpenShift cluster. Podman mode is out of cluster since it only requires Podman. 

### BuildConfig Mode
BuildConfig mode runs inside a kubernetes or OpenShit cluster. It is supported on OCP 3.x and 4.x. In BuildConfig mode, a kubernetes or OpenShift buildconfig creates additional pods to perform the stages defined in the jobspec.


### Unbounded Pod Mode
Unbounded pod mode runs inside a kubernetes or OpenShit cluster. It is supported on OCP 3.x and 4.x. In unbounded pod mode, a pod with the appropriate serviceaccount creates additional pods to perform the stages defined in the jobspec.

From within a pod in Kubernetes or OpenShift with a serviceaccount that has privileges to create pods, run
```
gangplank pod --spec jobspec.yaml
```

### Podman Mode
Podman uses libpod and the Podman socket to create additional pods to peform the stages defined in the jobspec.

Pre-requisite:
- Clone https://github.com/coreos/coreos-assembler
- From base directory of checkout run `cd tools && make tools && (sudo) make install`
- From base directory of checkout run `cd gangplank && make gangplank && (sudo) make install`

Then run:
```
gangplank pod --spec jobspec.yaml --podman
```






---
## Other Notes
--srvDir is the option for cachedir if you want to use a shared cache

## Common
- requires a directory that is an overlay
- Uses minio to coordinate the movement of files back and forth between pods




## walters feedback

- like to see this deployed in a MVP mode, something like replacing part of the .cci.jenkinsfile in the cosa repo?
- relationship between cosa and gangplank; primary entrypoint
- Working in https://github.com/ostreedev/ostree/blob/master/.cci.jenkinsfile

## How would this look like in Use?

- gangplank is the space between submitting a PR and finishing 
- use cosa remote to create a tarball and gangplank will inject it into the container which will unpack it and build it in the container
- in jenkins file sh_wrap to run `oc start-build bc/bc_name --from-dir="."`