Dev-docs are insufficient and confusing

[itamaro]

I was trying to figure out how to build and run a local glbc, and ended up on the release doc (which is already an odd name for a dev-doc).

The first instruction there was to run make controller, but controller is not a name for any target, and controllers is one, but it only builds the nginx-ingress-controller, and the binary ends up under controllers/nginx/rootfs - already a bunch of surprising & unexpected behaviors.

I managed to figure that controllers/gce has its own Makefile, so I can cd into it and make server to build the binary, or make container to build a Docker image.

Two more surprising things here:

1. why "server" for the binary? (and not "glbc" or "controller")
2. why "container" and not "docker-image" or "image"? the artifact is not a running container...

so, next, I managed to build the glbc binary, but it wouldn't run on my host. I'm building on OS X, so I'm guessing it's configured to build for Linux, but it would be nice if it was clear that it was the case, and there was an obvious way to change the target platform (if OS X is supported, that is).

the error I got is -bash: ./glbc: cannot execute binary file: Exec format error

so I opted to run the Docker image resulting from make container, initially using:

docker run -it --rm gcr.io/itamaro/glbc:0.9.1 --running-in-cluster=false

naturally, it wouldn't work with my actual GKE cluster (or even with a local minikube), because it's sandboxed... eventually, I ended up with the following command that seemed to be working, assuming you have a service account credentials file:

docker run -it --rm --net=host -v $HOME/.kube:/root/.kube -v $HOME/svc.json:/svc.json -e GOOGLE_APPLICATION_CREDENTIALS=/svc.json gcr.io/itamaro/glbc:0.9.1 --running-in-cluster=false --verbose

I'd be happy to clean this up and make a nice docs-PR, but I'd like to receive input from core developers / maintainers on how you think it should be laid out, and whether it is needed at all.

[tonglil]

The first instruction there was to run make controller, but controller is not a name for any target, and controllers is one, but it only builds the nginx-ingress-controller, and the binary ends up under controllers/nginx/rootfs - already a bunch of surprising & unexpected behaviors.

☝️ 👍

I was able to get it to work with Minikube:

• minikube addons disable ingress
• Reuse the docker daemon (https://github.com/kubernetes/minikube#reusing-the-docker-daemon)
• make container
• Edit rc.yaml with --running-in-cluster=false
• kubectl apply -f rc.yaml

To get it to run on OS X:

CGO_ENABLED=0 godep go build -a -installsuffix cgo -ldflags '-w' -o  glbc *.go
./glbc --running-in-cluster=false --verbose

However I can't recommend you trying to do Kubernetes development as much of it is optimized for Linux (such as the above scenario), and the main repo cannot be stood up on OS X locally.

I agree with you, making the instructions more clear would be beneficial to all, whether that's to explicitly mark out Linux development, changing the scripts to accept environment variables w/ Linux defaults, or otherwise.

[diazjf]

I went ahead and cleared up some of the development documentation. Let me know what you guys think. I will keep incrementally adding while I continue ingress development.

See #1065