Merge pull request #697 from rramkumar1/docs-fix

Update docs for contributing

README.md

@@ -13,8 +13,6 @@ Please read the [beta limitations](BETA_LIMITATIONS.md) doc to before using this
 - It relies on a beta Kubernetes resource.
 - The loadbalancer controller pod is not aware of your GCE quota.
 
-**If you are running a cluster on GKE and interested in trying out alpha releases of the GLBC before they are officially released please visit the deploy/glbc/ directory.**
-
 ## Overview
 
 See [here](https://kubernetes.io/docs/concepts/services-networking/ingress/) for high-level concepts on Ingress in Kubernetes.
@@ -25,9 +23,13 @@ For GCP-specific documentation, please visit [here](https://cloud.google.com/kub
 
 Please visit the [changelog](CHANGELOG.md) for both high-level release notes and a detailed changelog.
 
+## Documentation
+
+Please visit our [docs](docs/) for more information on how to run, contribute, troubleshoot and much more!
+
 ## GKE Version Mapping
 
-The table below describes what version of Ingress-GCE is running on GKE. Note that these versions are simply the defaults. Users still have the power to change the version manually if they want to (see deploy/).
+The table below describes what version of Ingress-GCE is running on GKE. Note that these versions are simply the defaults. 
 
    *Format: k8s version -> glbc version* ('+' indicates that version or above)
 

cmd/echo/README.md

@@ -0,0 +1,11 @@
+# echoserver
+
+The echoserver binary is a simple webserver that responds to HTTP GET calls on
+the following two paths:
+
+        * "/healthcheck" - Responds with a 200.
+
+        * "/" - Responds w/ information from the request such as host, headers, etc.
+
+This server is suitable for use as a backend for an Ingress. See [here](echo.yaml)
+for an example usage.

deploy/echo/yaml/deployment.yaml → cmd/echo/echo.yaml

@@ -40,3 +40,25 @@ spec:
             path: /healthcheck
             scheme: HTTP
             port: http
+---
+apiVersion: v1
+kind: Service
+metadata:
+  annotations:
+    service.alpha.kubernetes.io/app-protocols: '{"https":"HTTPS","http":"HTTP"}'
+  name: echo
+  labels:
+    app: echo
+spec:
+  type: NodePort
+  ports:
+  - port: 80
+    protocol: TCP
+    name: http
+    targetPort: http
+  - port: 443
+    protocol: TCP
+    name: https
+    targetPort: https
+  selector:
+    app: echo

docs/contrib/README.md

@@ -1,4 +1,10 @@
 # Contribute
 
-This directory will soon contain up-to-date information on how to contribute to
-ingress-gce
+This directory contains information on how to contribute to the ingress-gce project.
+If you find a requirement that this doc does not capture, please submit an issue on GitHub.
+
+1. Read the [setup guide](dev-setup.md) for information on how to get your
+   development environment setup, run unit tests and how to build binaries.
+2. Read the [cluster setup guide](cluster-setup.md) for information on how to create a cluster
+   that can be used to test your changes.
+3. Read the [testing guide](testing.md) for how to test your changes end-to-end.

docs/contrib/cluster-setup.md

@@ -0,0 +1,22 @@
+# Overview
+
+This doc outlines the steps needed to setup a dev cluster for testing changes
+made to the Ingress-GCE controller. Typically we test out controller changes
+by running the binary locally but this still means we need a working cluster
+to test against.
+
+## Create the cluster
+
+We recommend to create a k8s cluster in GCE. For instructions on how to do
+that, go [here](../deploy/gce/README.md)
+
+## Remove the default controller
+
+Once the cluster is created, we need to delete the existing Ingress-GCE controller
+that comes by default:
+
+```console
+kubectl delete pod l7-lb-controller
+```
+
+This ensures we can run our own copy of the controller locally.

docs/contrib/dev-setup.md

@@ -0,0 +1,51 @@
+# Overview
+
+This document explains how to get started with developing for Ingress-GCE.
+The below guide assumes you have installed the necessary binaries to run Golang.
+
+## Get the code
+
+It is suggested to create your own fork of the repository on Github. Once that
+is done, go ahead and download the repo.
+
+```console
+cd $GOPATH/src
+git clone https://github.com/[YOUR GITHUB_USER]/ingress-gce.git
+```
+
+## Unit tests
+
+To execute the unit tests, run:
+
+```console
+make test
+```
+
+## Building
+
+This assumes you have properly setup docker.
+
+All ingress-gce binaries are built through a Makefile. Depending on your
+requirements you can build a raw binary, a local container image,
+or push an image to a remote repository. To build all binaries, run:
+
+```console
+make build
+```
+
+The resulting binaries can be found in bin/amd64/. To push an image up to a
+repository, run the following:
+
+```console
+export REGISTRY=[MY CONTAINER REGISTRY]
+make push
+```
+We suggest using [Google Container Registry](https://cloud.google.com/container-registry/docs/quickstart)
+to store your images.
+
+## Other considerations
+
+The build uses dependencies in the `ingress/vendor` directory, which
+must be installed before building a binary/image. Occasionally, you
+might need to update the dependencies. In that case, you will need to install
+the [dep](https://github.com/golang/dep) tool.

docs/dev/testing.md → docs/contrib/testing.md

@@ -1,9 +1,9 @@
-# GLBC E2E Testing
+# Overview
 
 This document briefly goes over how the e2e testing is setup for this repository. It will also go into
 some detail on how you can run tests against your own cluster.
 
-## Kubernetes CI Overview
+## CI 
 
 There are two groups of e2e tests that run in Kubernetes CI.
 The first group uses a currently released image of GLBC when the test cluster is brought up.
@@ -21,26 +21,10 @@ a job that pushes a new image of GLBC for e2e testing. The ingress-gce-* jobs th
 this image when the test cluster is brought up. You can see the results of this job
 at https://k8s-testgrid.appspot.com/sig-network-gce#ingress-gce-image-push.
 
-## Manual Testing
+## Running E2E tests
 
 If you are fixing a bug or writing a new feature and want to test your changes before they
-are run through CI, then you will most likely want to test your changes end-to-end before submitting:
-
-1. ingress-gce-e2e:
-
-  * `VERSION=mytag REGISTRY=gcr.io/my-test-project make push-e2e`
-  * `export GCE_GLBC_IMAGE=gcr.io/my-test-project/ingress-gce-e2e-glbc-amd64:mytag`
-  * `go run hack/e2e.go --up --test --down --test_args="--ginkgo.focus=\[Feature:Ingress\]"`
-
-2. ingress-gce-upgrade-e2e
-
-  * `VERSION=mytag REGISTRY=gcr.io/my-test-project make push-e2e`
-  * `go run hack/e2e.go --up --test --down --test_args="--ginkgo.focus=\[Feature:IngressUpgrade\] --ingress-upgrade-image=gcr.io/my-test-project/ingress-gce-e2e-glbc-amd64:mytag"`
-
-
-
-**Disclaimer:**
-
-Note that the cluster you create should have permission to pull images from the registry
-you are using to push the image to. You can either make your registry publicly readable or give explicit permission
-to your cluster's project service account.
+are run through CI, then you will most likely want to test your changes end-to-end before submitting.
+The instructions for running the e2e tests are [here](../../cmd/e2e-test/readme.md).
+Before following those instructions, ensure that you are running the controller
+by following the instructions [here](../deploy/local/README.md)

docs/deploy/README.md

@@ -1,5 +1,9 @@
 # How To Run
 
-This directory will soon contain up-to-date information on how to run your own
-self-managed instance of the ingress-gce controller.
+This directory contains information for how to run the Ingress-GCE controller.
 
+## Navigation
+
+* [Running on GCE](gce/README.md)
+* [Run a self-managed instance on GKE](gke/README.md)
+* [Run locally](local/README.md)

docs/deploy/gce/README.md

@@ -0,0 +1,37 @@
+# Overview
+
+This guide walks you through how to create a k8s cluster on GCE with the
+Ingress-GCE controller. The steps below assume that you already have a project
+in GCP setup and that you have a working `gcloud` binary.
+
+## Deploy on GCE
+
+Verify the project you want to create the cluster in is the same as the one
+displayed by the following command:
+
+```console
+gcloud config list
+```
+
+Then, clone the kubernetes repo and test-infra repo:
+
+```console
+$ cd $GOPATH/src/
+$ git clone https://github.com/kubernetes/kubernetes.git
+$ git clone https://github.com/kubernetes/test-infra.git
+```
+
+Change into kubernetes/kubernetes and build the release tars:
+
+```console
+make quick-release
+```
+
+Finally, create the cluster:
+
+```console
+go run hack/e2e.go --up
+```
+
+Note that the above command automatically destroys any existing cluster that
+was previously created with --up.

deploy/glbc/README.md → docs/deploy/gke/README.md

@@ -1,16 +1,10 @@
 # Overview
 
-Welcome, you are reading this because you are interested in running a version of the
-GCP Ingress Controller (GLBC) before it is officially released on GKE! The purpose of this is to
-allow users to find bugs and report them, while also getting early access to improvements and
-new features. You will notice that the following things are sitting in this directory:
+Welcome, you are reading this because you are interested in running a **self-managed** version of the
+Ingress-GCE Controller on GKE!
 
-1. script.sh
-2. gce.conf
-3. yaml/
-
-We will explain what each of these things mean in a bit. However, you will only be interacting
-with one file (script.sh).
+Note that on GKE, Ingress-GCE runs by default but it is managed for you by GKE. This document
+will teach you how to release GKE from managing GLBC and put that power in your hands.
 
 **Disclaimer: Running this script could potentially be disruptive to traffic
 so if you want to run this on a production cluster, do so at your own risk.
@@ -29,14 +23,14 @@ under [core]/project is the one that contains your cluster. Second, ensure that
 the current logged-in account listed under [core]/account is the owner of the project.
 In other words, this account should have full project ownership permissions and be listed as
 having the "Owner" role on the IAM page of your GCP project. You might ask why this
-is needed? Well, the reason is that the script invokes a kubectl command which
+is needed? Well, the reason is that our [script](../resources/gke-self-managed.sh) invokes a kubectl command which
 creates a new k8s RBAC role (see below for explanation why). In order to do this, the
 current user must be the project owner. The "Owner" role also gives the account
 permission to do basically anything so all commands the script runs should
 theoretically work. If not, the script will do its best to fail gracefully
 and let you know what might have went wrong.
 
-The second step is to make sure you populate the gce.conf file. The instructions
+The second step is to make sure you populate the [gce.conf](../resources/gce.conf) file. The instructions
 for populating the file are in the file itself. You just have to fill it in.
 
 # Important Details
@@ -72,22 +66,22 @@ with what we described above.
 
 ## Dependencies
 
-As promised, here is an explanation of each script dependency.
+Here is an explanation of each script dependency.
 
-1. gce.conf
+1. [gce.conf](../resources/gce.conf)
     * This file normally sits on the GKE master and provides important config for
       the GCP Compute API client within the GLBC. The GLBC is configured to know
       where to look for this file. In this case, we simply mount the file as a
       volume and tell GLBC to look for it there.
-2. yaml/default-http-backend.yaml
+2. [default-http-backend.yaml](../resources/default-http-backend.yaml)
     * This file contains the specifications for both the default-http-backend
       deployment and service. This is no different than what you are used to
       seeing in your cluster. In this case, we need to recreate the default
       backend since turning off the GLBC on the master removes it.
-3. yaml/rbac.yaml
+3. [rbac.yaml](../resources/rbac.yaml)
     * This file contains specification for an RBAC role which gives the GLBC
       access to the resources it needs from the k8s API server.
-4. yaml/glbc.yaml
+4. [glbc.yaml](../resources/glbc.yaml)
     * This file contains the specification for the GLBC deployment. Notice that in
       this case, we need a deployment because we want to preserve the controller
       in case of node restarts.
@@ -98,7 +92,7 @@ Take a look at the script to understand where each file is used.
 
 Run the command below to see the usage:
 
-`./script.sh --help`
+`./gke-self-managed.sh --help`
 
 After that, it should be self-explanatory!