00-developing.adoc

Developing dklb

Table of Contents

• Prerequisites
• Cloning the repository
• Installing dependencies
• Building dklb
• Running dklb
• Testing dklb
  • Running the unit test suite
  • Running the end-to-end test suite

Prerequisites

To build dklb, the following software is required:

• git.

• make.

• Go 1.12.4+.

  • dklb makes use of the Go modules experiment present in Go 1.11+ only.

  • Go 1.11.3 and earlier were found to have issues computing the checksum of certain modules.

• pre-commit installed according to these instructions and configured according to these instructions.

To run dklb, the following additional software is required:

• skaffold

• A DC/OS cluster having EdgeLB installed.

  • DC/OS must be v1.12.0 or later.

  • EdgeLB must be built and installed from the master branch. A stub-universe is available, see here for details.

  • EdgeLB v1.3.0 may be used instead, but some functionality will be missing.

• An MKE v2.2.0-1.13.3 (or later) cluster.

  • The current kubeconfig context must be configured to point at this cluster.

A Docker Hub account with read/write access to the mesosphere/dklb image repository is additionally required.

Cloning the repository

To clone the repository, the following command may be run:

$ git clone git@github.com:mesosphere/dklb.git /some/path

ℹ️	As dklb relies on Go modules, it is NOT necessary to clone to a directory inside $GOPATH.

Installing dependencies

As dklb uses Go modules, build and test dependencies will be automatically downloaded whenever necessary. However, dklb depends on private GitHub repositories such as mesosphere/dcos-edge-lb. To allow for go mod to access these repositories, the following command must be run after cloning the repository:

$ git config --global url."git@github.com:".insteadOf "https://github.com/"

Building dklb

To build the dklb binary, the following command may be run:

$ make build

By default, this will create a build/dklb binary targeting linux-amd64. This binary is suitable to be imported to inside a container image and ran inside a Kubernetes cluster.

ℹ️	Even though it is not recommended or supported, it is possible to build a binary targeting a different platform by running a command similar to the following one: $ make build GOOS=darwin LDFLAGS= This can be useful to perform local testing with the generated binary.

Running dklb

skaffold is used to ease the process of running and testing dklb during day-to-day development. skaffold builds a Docker image containing the dklb binary and pushes it to the mesosphere/dklb image repository. Write access to this repository is granted only to members of the kubernetes team in the Mesosphere organization. Hence, in order to push the image, it is necessary to login to Docker Hub with adequate credentials:

$ docker login

To deploy dklb to the MKE cluster targeted by the current kubeconfig context, the following command may then be run:

$ make skaffold

These command will perform the following tasks:

1. Build the build/dklb binary.

2. Build the mesosphere/dklb Docker image based on said binary.

3. Push the mesosphere/dklb Docker image to Docker Hub.

4. Create or update a dklb service account, cluster role and cluster role binding.

5. Deploy dklb as a single pod that uses the kube-system/mke-cluster-info configmap to configure its environment.

6. Stream logs from the dklb pod until Ctrl+C is hit.

To simply deploy the dklb pod without streaming logs, the following command may be run instead:

$ make skaffold MODE=run

To delete any resources that may have been created by skaffold (and hence uninstall dklb), the following command may be run:

$ make skaffold MODE=delete

Testing dklb

Running the unit test suite

In order to run the unit test suite for dklb, the following command may be run:

$ make test.unit

Running the end-to-end test suite

As of this writing, `dklb’s end-to-end test suite has the following additional requirements:

• The target DC/OS cluster must be running on AWS.

• The end-to-end test suite must run from outside the target DC/OS cluster.

• To test cloud load-balancer provisioning, the ID of a public subnet must be specified using AWS_PUBLIC_SUBNET_ID.

To run the end-to-end test suite against the MKE cluster targeted by $HOME/.kube/config, the following command may be run:

$ make test.e2e [AWS_PUBLIC_SUBNET_ID="<aws-public-subnet-id>"]

The output of a successful run of the end-to-end test suite will be similar to the following:

(...)
Ran 13 of 13 Specs in 1297.623 seconds
SUCCESS! -- 13 Passed | 0 Failed | 0 Pending | 0 Skipped
--- PASS: TestEndToEnd (1297.62s)
PASS
ok  	github.com/mesosphere/dklb/test/e2e	1297.681s