Skip to content

Latest commit

 

History

History
182 lines (146 loc) · 5.5 KB

README.md

File metadata and controls

182 lines (146 loc) · 5.5 KB
Raw

Development Guide

This document is intended to be the canonical source of truth for things like supported toolchain versions for building Voyager. If you find a requirement that this doc does not capture, please submit an issue on github.

This document is intended to be relative to the branch in which it is found. It is guaranteed that requirements will change over time for the development branch, but release branches of Voyager should not change.

Build Voyager

Some of the Voyager development helper scripts rely on a fairly up-to-date GNU tools environment, so most recent Linux distros should work just fine out-of-the-box.

Setup GO

Voyager is written in Google's GO programming language. Currently, Voyager is developed and tested on go 1.8.3. If you haven't set up a GO development environment, please follow these instructions to install GO.

Download Source

$ go get -u -v github.com/appscode/voyager
$ cd $(go env GOPATH)/src/github.com/appscode/voyager

Install Dev tools

To install various dev tools for Voyager, run the following command:

$ ./hack/builddeps.sh

Build Binary

$ ./hack/make.py
$ voyager version

Dependency management

Voyager uses Glide to manage dependencies. Dependencies are already checked in the vendor folder. If you want to update/add dependencies, run:

$ glide slow

Build Docker images

To build and push your custom Docker image, follow the steps below. To release a new version of Voyager, please follow the release guide.

# Build Docker image
$ ./hack/docker/voyager/setup.sh

# Add docker tag for your repository
$ docker tag appscode/voyager:<tag> <image>:<tag>

# Push Image
$ docker push <image>:<tag>

Build HAProxy

We package HAProxy and Kloader into a Ubuntu 16.04 based Docker image.

$ ./hack/docker/haproxy/<version>/setup.sh
$ ./hack/docker/haproxy/<version>/setup.sh push

Generate CLI Reference Docs

$ ./hack/gendocs/make.sh

Run Test

Run Short Unit Test by running

go test ./pkg/...

Run Full Test

To Run Full unit test You need to provide some secret in hack/configs/.env file. Or You may add them as environment variables.

TEST_GCE_SERVICE_ACCOUNT_DATA
TEST_GCE_PROJECT
TEST_ACME_USER_EMAIL
TEST_DNS_DOMAINS

Then run

$ ./hack/make.py test unit

Run e2e Test

$ ./hack/make.py test minikube # Run Test against minikube, this requires minikube to be set up and started.

$ ./hack/make.py test e2e -cloud-provider=gce # Test e2e against gce cluster

$ ./hack/make.py test integration -cloud-provider=gce # Run Integration test against gce
                                                      # This requires voyager to be deployed in the cluster.


- Run only matching tests e2e test
$ ./hack/make.py test e2e -cloud-provider=gce -ginkgo.focus=<regexp>


- Run tests but do not delete resource that are created
$ ./hack/make.py test minikube -cloud-provider=gce -cleanup=false


- Run Service IP Persist test with provided IP
$ ./hack/make.py test e2e -cloud-provider=gce -lb-ip=35.184.104.215

Tests are run only in namespaces prefixed with test-. So, to run tests in your desired namespace, follow these steps:

# create a Kubernetes namespace in minikube with
kubectl create ns test-<any-name-you-want>

# run tests
./hack/make.py test minikube -namespace test-<any-name-you-want>

e2e tests are powered by ginkgo. All the configs and flags of ginkgo are also available.


## Architecture Voyager works by implementing third party resource data watcher for kubernetes. It connects with k8s apiserver for specific events as ADD, UPDATE and DELETE. and perform required operations.

Ingress watcher generates the configuration for HAProxy and stores it as a ConfigMaps and creates a RC with specified HAProxy - that is configured with auto reload while any changes happens to ConfigMap data. This is handled via kloader. Voyager keeps the ingress resource and the configuration in sync by performing processing on the resources.

Certificate watcher watch and process certificates third party data and obtain a ACME certificates.

Third Party Resources

voyager depends on two Custom Resource Definition Object ingress.voyager.appscode.com and certificate.voyager.appscode.com. Those two objects can be created using following data.

apiVersion: apiextensions.k8s.io/v1beta1
kind: CustomResourceDefinition
metadata:
  name: certificates.voyager.appscode.com
  labels:
    app: voyager
spec:
  group: voyager.appscode.com
  names:
    kind: Certificate
    listKind: CertificateList
    plural: certificates
    shortNames:
    - cert
    singular: certificate
  scope: Namespaced
  version: v1beta1
---
apiVersion: apiextensions.k8s.io/v1beta1
kind: CustomResourceDefinition
metadata:
  name: ingresses.voyager.appscode.com
  labels:
    app: voyager
spec:
  group: voyager.appscode.com
  names:
    kind: Ingress
    listKind: IngressList
    plural: ingresses
    shortNames:
    - ing
    singular: ingress
  scope: Namespaced
  version: v1beta1
# Create Third Party Resources
$ kubectl apply -f https://raw.githubusercontent.com/appscode/voyager/4.0.0-rc.9/apis/voyager/v1beta1/crds.yaml