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 [email protected]:${YOUR_GITHUB_USERNAME}/build.git
cd build
git remote add upstream [email protected]: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 1 ko: To build and deploy changes.
3. 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 if required. To be able to push images to the container registry, you need to run this once:

ko login [OPTIONS] [SERVER]

Note: This is roughly equivalent to docker login.

Install Shipwright Build

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

1. Target your Kubernetes cluster and install the Shipwright Build. Run this from the root of the source repo:

   ./hack/install-tekton.sh

2. Set your KO_DOCKER_REPO environment variable. This will be the container image registry you push to, or kind.local if you're using KinD.

3. Build and deploy the operator from source, from within the root of the repo:

   ko apply -P -R -f deploy/

The above 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:

ko apply -P -R -f deploy/

Tear it down

You can clean up everything with:

kubectl delete -R -f deploy/

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)