A guide to

  * Developing source code changes.
  * Setting up a Kubernetes environment on your laptop

# Development of source code

Locally install tool dependencies using [retool](https://github.com/twitchtv/retool). just `retool` will be globally installed.

    make setup

Run lints and tests

    make && make check && make test

This and e2e tests are automatically ran on our Jenkins CI server.
Additionally, you can run some slower, more extensive linters.

    make lint-slow


# Environment

## GO

To build tidb-operator, Golang compiler version >= 1.9 is required.

## Kubernetes

First we need to run a Kubernetes cluster. `minikube` is the popular option for that. However, minikube only creates one Kubernetes node. To run TiDB, we need multiple Kubernetes nodes. There are a few options for this, but we have found a way to make DinD (Docker in Docker) work.

DinD (Docker in Docker) allows running the docker daemon inside a top-level docker container. This means the top-level container to simulate a Kubernetes node and have containers launched inside it. The kubeadm-dind-cluster project starts multiple docker containers as a k8s nodes on a standalone machine through DinD, and then start a k8s cluster by using docker to start k8s components on these nodes.


### Installing

First install `kubectl`. This has been tested with [version 1.10.0](https://storage.googleapis.com/kubernetes-release/release/v1.10.0/bin/darwin/amd64/kubectl), but newer versions may work.

Configure kubectl auto completion for bash:

    echo "source <(kubectl completion bash)" >> $HOME/.bash_profile && source $HOME/.bash_profile

or zsh:

    echo "source <(kubectl completion zsh)" >> $HOME/.zshrc && source $HOME/.zshrc

Next, bring up the DinD K8s.

    git clone https://github.com/pingcap/kubeadm-dind-cluster.git
    cd kubeadm-dind-cluster
    NUM_NODES=4 ../kubeadm-dind-cluster/tools/multi_k8s_dind_cluster_manager.sh rebuild e2e-v1.10

Ensure the DinD cluster works:

    kubectl get node,componentstatus
    kubectl get pod -n kube-system
    # view http://localhost:8080/ui in your browser

The local persistent volume provisioner doesn't work right in DinD, so we need to provision them manually ourselves.

    cd ..
    git clone https://github.com/pingcap/tidb-operator
    cd tidb-operator/new-operator
    ./manifests/local-dind/pv-hosts.sh

You also need to install helm

    curl https://raw.githubusercontent.com/kubernetes/helm/master/scripts/get > helm.sh
    bash helm.sh
    helm init


### Operating

Other operations for DinD:

    * Stop DinD: ./tools/multi_k8s_dind_cluster_manager.sh down e2e-v1.10
    * Start DinD: ./tools/multi_k8s_dind_cluster_manager.sh up e2e-v1.10
    * Remove DinD: ./tools/multi_k8s_dind_cluster_manager.sh clean e2e-v1.10


# Running TiDB Operator

You can now run tidb operator as per the [README](../README.md) against your local k8s cluster.


# Local Deploy of source code changes

## Setup

As per the README, edit `./charts/tidb-operator/values.yaml`.

## Lifecycle

Make a change to code. Write tests and test it with `make test`. To deploy to your laptop run:

    make dind-reload

If you haven't already, install the cluster chart.

Now connect to the tidb cluster

    make dind-mysql

## Debugging

If the cluster fails to startup, you will likely want to View the scheduler logs. e.g.

    kubectl logs -c tidb-scheduler -n pingcap -l name=tidb-scheduler


# Source code

## Generation

Code under `pkg/client` is generated by `./hack/codegen.sh'.