Skip to content
This repository has been archived by the owner on Mar 11, 2022. It is now read-only.

Latest commit

 

History

History
252 lines (172 loc) · 9.29 KB

DEVELOPMENT.md

File metadata and controls

252 lines (172 loc) · 9.29 KB

Development

Prerequisites

Access to a cluster

First of all, you will need access to a Kubernetes or an OpenShift cluster. The easiest way is to start a local minimal cluster in a virtual machine with the help of Minikube or Minishift.

  • VirtualBox - hypervisor to run a local cluster (minikube/minishift) virtual machine in
  • Minikube - local Kubernetes cluster
  • Minishift - local OpenShift cluster
  • Kind - local Kubernetes cluster in Docker
  • kubectl - command line tool for controlling Kubernetes cluster
  • openshift-cli - command line tool for controlling OpenShift cluster

Installing on a Mac

Every component can be easily installed via Homebrew:

brew cask install virtualbox
brew install minikube
brew install kind
brew install kubectl
brew cask install minishift
brew install openshift-cli

Installing on a Linux

You can install the applications via a distro-specific package manager, or download a binary, or install from source.

Vendor instructions on how to install on Linux:

Tools to build and test Eunomia

Apart from setting up access to a cluster, you will need some tools in order to build and test Eunomia.

Tools to build:

Tools to test:

Installing on a Mac

Again, all the components (except operator-sdk v0.17.1 and golint) can be easily installed via Homebrew:

brew install git
brew install [email protected]
brew install docker
brew install make  # it will be installed as "gmake"; follow the instructions that will appear to use it as "make"
brew install shfmt
brew install shellcheck

Installing on a Linux

The components (except operator-sdk v0.17.1 and golint) can be installed via a distro-specific package manager. You can also download a binary, or install from source.

Here are vendor instructions on how to install the necessary components on Linux:

Installing operator-sdk v0.17.1 from GitHub release

The script scripts/install-operator-sdk.sh will do this for you on Linux and MacOS:

scripts/install-operator-sdk.sh v0.17.1 /your/target/path

Installing golint

To install golint, follow the installation instruction.

Checkout your fork

To check out this repository:

  1. Create a fork of this repo
  2. Create the directories and clone your fork
git clone https://github.com/<YOUR_FORK>/eunomia.git
cd eunomia

Running Locally for Development Purposes

The most efficient way to develop the operator locally is run the code on your local machine. This allows you to test code changes as you make them.

To achieve this, run the helper script (preferably in a separate console window as the script blocks):

./scripts/run-eunomia-locally.sh

If you want Eunomia to watch a particular namespace, just pass its name as an argument to the above script. Running the script without the argument defaults to Eunomia watching all namespaces.

Note on cluster being watched

The above script uses operator-sdk up local command to run Eunomia operator binary locally. It enforces the use of a Kubernetes cluster - Eunomia will be watching namespace(s) in a Kubernetes cluster.

Note on template-processor images

Eunomia binary being run locally still uses template-processor images to manage templates and parameters. If you are tweaking the images (anything in template-processors directory), make sure to deploy them to your local Minikube Docker registry beforehand. The easiest way is to use the helper script:

./scripts/deploy-to-local.sh minikube

By doing this you'll build your tweaked template-processor images and send them to Minikube Docker registry with the tag dev. You must also not forget to use this tag in templateProcessorImage in your GitOpsConfig. If not, the images will be downloaded from Kohl's quay.io.

Building the Operator Image

The Eunomia operator gets packaged as a container image for running on Kubernetes clusters. These instructions will walk you through building and testing the image in a cluster.

Building the image on your local workstation

See https://golang.org/doc/install to install/setup your Go Programming environment if you have not already done this.

GOOS=linux make

From here you can build the eunomia-operator Docker image and manually push it to a registry, or run it in a local cluster (see Using Minikube or Using Minishift).

Building the image and pushing to a remote registry

Run the following to build and push the eunomia-operator image as well as template-processors images:

export REGISTRY=<your_registry>
docker login $REGISTRY
./scripts/build-images.sh

Testing

If you want to play with Eunomia deployed to Minikube or Minishift, here are some preliminary instructions.

Using Minikube

# Start minikube
minikube start --vm-driver virtualbox

# Build eunomia-operator (building eunomia-operator binary included) and template-processors
# images and store them in minikube docker registry
scripts/deploy-to-local.sh minikube

# Deploy the operator, use your locally-built image
helm template deploy/helm/eunomia-operator/ \
  --set eunomia.operator.image.tag=dev \
  --set eunomia.operator.image.pullPolicy=Never | kubectl apply -f -

Using KIND

# Start kind cluster
scripts/kind-create-cluster.sh

# Build eunomia-operator (building eunomia-operator binary included) and template-processors
# images and store load them into the kind node
scripts/deploy-to-local.sh kind

# Deploy the operator, use your locally-built image
helm template deploy/helm/eunomia-operator/ \
  --set eunomia.operator.image.tag=dev \
  --set eunomia.operator.image.pullPolicy=Never | kubectl apply -f -

Using Minishift

# Start minishift
minishift start --vm-driver virtualbox

# Log in to minishift as admin
oc login -u system:admin

# Build eunomia-operator (building eunomia-operator binary included) and template-processors
# images and store them in minishift docker registry
scripts/deploy-to-local.sh minishift

# Deploy the operator, use your locally-built image
helm template deploy/helm/eunomia-operator/ \
  --set eunomia.operator.image.tag=dev \
  --set eunomia.operator.image.pullPolicy=Never \
  --set eunomia.openshift.route.enabled=true | oc apply -f -

After testing configure Docker CLI to use local Docker daemon again

After testing you might want to use your local Docker daemon again. To do it just issue

eval "$(docker-machine env -u)"

Run Tests

For testing and CI purposes, we manage several set of tests. These tests can be run locally by following the below instructions. All test scripts assume that you are already logged into your minikube cluster.

Running Unit Tests

make test-unit

Running End-to-End Tests

# Optional: Set the environment variable $EUNOMIA_URI to point to a specific git url for testing
# Optional: Set the environment variable $EUNOMIA_REF to point to a specific git reference for testing
# Optional: Set the environment variable $EUNOMIA_TEST_ENV to minikube|minishift|kind (default is minikube)
# Optional: Set the environment variable $EUNOMIA_TEST_PAUSE to yes (default is no)
# Optional: Set the environment variable $EUNOMIA_TEST_SKIP_IMAGES to yes to skip building all images
# Optional: Set the environment variable $EUNOMIA_TEST_SKIP_DEPLOYMENT to yes to skip the Eunomia deployment
# Optional: Set the environment variable $EUNOMIA_TEST_GO_RUN to the single test you want to run

make test-e2e

Running All Tests

make test