DEVELOPMENT.md

Developing

Getting started

1. Ramp up on kubernetes and CRDs
2. Create a GitHub account
3. Setup GitHub access via SSH
4. Create and checkout a repo fork
5. Install requirements
6. Set up a Kubernetes cluster
7. Set up your shell environment
8. Configure kubectl to use your cluster
9. Install Shipwright Build in your cluster

Ramp up

Welcome to the project!! You may find these resources helpful to ramp up on some of the technology this project is built on. This project extends Kubernetes (aka k8s) with Custom Resource Definitions (CRDs). To find out more:

• The Kubernetes docs on Custom Resources - These will orient you on what words like "Resource" and "Controller" concretely mean
• Understanding Kubernetes objects - This will further solidify k8s nomenclature
• API conventions - Types(kinds) - Another useful set of words describing words. "Objects" and "Lists" in k8s land
• Extend the Kubernetes API with CustomResourceDefinitions- A tutorial demonstrating how a Custom Resource Definition can be added to Kubernetes without anything actually "happening" beyond being able to list Objects of that kind

At this point, you may find it useful to return to these Shipwright Build docs:

• Shipwright Build - Some of the terms here may make more sense!
• Install via getting started for development
• Shipwright Build overview and tutorial - Define BuildStrategies, Builds, and BuildRuns, see what happens when they are run

Checkout your fork

The Go tools require that you clone the repository to the src/github.com/shipwright-io/build directory in your GOPATH.

To check out this repository:

1. Create your own fork of this repo
2. Clone it to your machine:

mkdir -p ${GOPATH}/src/github.com/shipwright-io
cd ${GOPATH}/src/github.com/shipwright-io
git clone git@github.com:${YOUR_GITHUB_USERNAME}/build.git
cd build
git remote add upstream git@github.com:shipwright-io/build.git
git remote set-url --push upstream no_push

Adding the upstream remote sets you up nicely for regularly syncing your fork.

Requirements

You must install these tools:

1. go: The language Shipwright Build is built in
2. git: For source control
3. A container runtime to build the operator image, such as docker or podman
4. kubectl: For interacting with your kube cluster

Create a cluster and a repo

1. Follow the instructions in the Kubernetes doc to Set up a kubernetes cluster
2. Set up a container image repository for pushing images. Any container image registry that is accessible to your cluster can be used for your repository. This can be a public registry like Docker Hub, quay.io, or a container registry runs by your cloud provider

Note: We support Kubernetes version 1.17 and 1.18, 1 cluster worker node for basic usage, 2+ cluster worker nodes for HA

Environment Setup

To run your operator, you'll need to set these environment variables (we recommend adding them to your .bashrc):

1. GOPATH: If you don't have one, simply pick a directory and add export GOPATH=...
2. $GOPATH/bin on PATH: This is so that tooling installed via go get will work properly.

.bashrc example:

export GOPATH="$HOME/go"
export PATH="${PATH}:${GOPATH}/bin"

Make sure to configure authentication for your docker if required. To be able to push images to the container registry, you need to run this once:

docker login [OPTIONS] [SERVER]

Install Shipwright Build

The following set of steps highlight how to deploy a Build operator pod into an existing Kubernetes cluster.

1. Build a custom docker image from this repository. This can be done with Docker, for example:

   pushd $GOPATH/src/github.com/shipwright-io/build
   docker build -t eeeoo/build-operator:master .
   docker push eeeoo/build-operator:master
   popd

   You can also find the official versioned operator image in our quay.io

2. Reference the generated image name in the operator.yaml. The spec.template.containers[0].image value should be modified.

3. Target your Kubernetes cluster and install the Shipwright Build:

   pushd $GOPATH/src/github.com/shipwright-io/build
   ./hack/install-tekton.sh
   popd

4. Install the Build operator pod and all related resources.

   pushd $GOPATH/src/github.com/shipwright-io/build
   ./hack/shipwright-build.sh install
   popd

The above four steps give you a running Build operator that executes the code from your current branch.

Redeploy operator

As you make changes to the code, you can redeploy your operator with:

pushd $GOPATH/src/github.com/shipwright-io/build
./hack/shipwright-build.sh install
popd

Tear it down

You can clean up everything with:

pushd $GOPATH/src/github.com/shipwright-io/build
./hack/shipwright-build.sh uninstall
popd

Accessing logs

To look at the operator logs, run:

kubectl -n build-operator logs $(kubectl -n build-operator get pods -l name=build-operator -o name)