Start FAQ docs

README.md

@@ -15,12 +15,12 @@ It is currently in a state of flux as project maintainers port code over from [i
      * See our user documentation on [k8s.io](http://kubernetes.io/docs/user-guide/ingress/)
      * Follow through to the respective platform specific [examples](docs/examples/README.md)
 * Write your own Ingress controller
-    * See our [developer documentation](docs/developer.md)
+    * See our [developer documentation](docs/dev/README.md)
 * Deploy existing Ingress controllers
     * See our [admin documentation](docs/admin.md)
 * Contribute
     * See the [contributor guidelines](CONTRIBUTING.md)
 * Debug
-    * Peruse the [FAQ section](docs/faq.md)
+    * Peruse the [FAQ section](docs/faq/README.md)
     * Ask on one of the [user-support channels](CONTRIBUTING.md#support-channels)
 

docs/README.md

@@ -1,3 +1,3 @@
 # Ingress documentation and examples
 
-This directory contains examples and documentation.
+This directory contains documentation.

docs/faq/README.md

@@ -0,0 +1,129 @@
+# Ingress FAQ
+
+This page contains general FAQ for Ingress, there is also a per-backend FAQ
+in this directory with site specific information.
+
+Table of Contents
+=================
+
+   * [Ingress FAQ](#ingress-faq)
+      * [I created an ingress and nothing happens, what now?](#i-created-an-ingress-and-nothing-happens-what-now)
+      * [How do I deploy an ingress controller?](#how-do-i-deploy-an-ingress-controller)
+      * [How do I disable an ingress controller?](#how-do-i-disable-an-ingress-controller)
+      * [How do I run multiple ingress controllers in the same cluster?](#how-do-i-run-multiple-ingress-controllers-in-the-same-cluster)
+      * [How are the ingress controllers tested?](#how-are-the-ingress-controllers-tested)
+      * [An ingress controller E2E is failing, what should I do?](#an-ingress-controller-e2e-is-failing-what-should-i-do)
+      * [Is there a roadmap for ingress features?](#is-there-a-roadmap-for-ingress-features)
+      * [How do I contribute a backend to the generic ingress controller?](#how-do-i-contribute-a-backend-to-the-generic-ingress-controller)
+
+## I created an ingress and nothing happens, what now?
+
+Run `describe` on the Ingress. If you see create/add events, you have an ingress
+controller running in the cluster, otherwise, you either need to deploy or
+restart your ingress controller. If the events associaged with an ingress are
+insufficient to debug, consult the controller specific FAQ.
+
+## How do I deploy an ingress controller?
+
+The following platforms currently deploy an ingress controller addon: GCE, GKE,
+minikube. If you're running on any other platform, you can deploy an ingress
+controller by following [this](examples/deployment) example.
+
+## Are ingress controllers namespaced?
+
+Ingress is namespaced, this means 2 Ingress objects can have the same name in 2
+namespaces, and must only point to Services in its own namespace. An admin can
+deploy an ingress controller such that it only satisfies ingress from a given
+namespace, but by default, controllers will watch the entire kubernetes cluster
+for unsatisfied Ingress.
+
+## How do I disable an ingress controller?
+
+Either shutdown the controller satisfying the ingress, or use the
+`ingress-class` annotation, as follows:
+
+```yaml
+apiVersion: extensions/v1beta1
+kind: Ingress
+metadata:
+  name: test
+  annotations:
+    kubernetes.io/ingress.class: "nginx"
+spec:
+  tls:
+  - secretName: tls-secret
+  backend:
+    serviceName: echoheaders-https
+    servicePort: 80
+```
+
+Setting the annotation to any value other than "gce" or the empty string, will
+force the GCE controller to ignore your ingress. The same applies for the nginx
+controller.
+
+To completely stop the Ingress controller on GCE/GKE, please see [this](gce.md#host-do-i-disable-the-ingress-controller) faq.
+
+## How do I run multiple ingress controllers in the same cluster?
+
+Multiple ingress controllers can co-exist and key off the `ingress-class`
+annotation, as shown in this [faq](#how-do-i-run-multiple-ingress-controllers-in-the-same-cluster),
+as well as in [this](examples/pipeline) example.
+
+## How do I contribute a backend to the generic ingress controller?
+
+1. Write a [generic backend](https://github.com/kubernetes/ingress/blob/master/core/pkg/ingress/doc.go)
+2. Keep it in your own repo
+3. Submit an example(s) in the appropriate subdirectories [here](examples/README.md)
+
+## How are the ingress controllers tested?
+
+Testing for the ingress controllers is divided into:
+* Ingress repo: unittests and pre-submit integration tests run via travis
+* Kubernetes repo: [pre-submit e2e](https://k8s-testgrid.appspot.com/google-gce#gce&include-filter-by-regex=Loadbalancing),
+  [post-merge e2e](https://k8s-testgrid.appspot.com/google-gce#gci-gce-ingress),
+  [per release-branch e2e](https://k8s-testgrid.appspot.com/google-gce#gci-gce-ingress-release-1.5)
+
+The configuration for jenkins e2e tests are located [here](https://github.com/kubernetes/test-infra).
+
+## An ingress controller E2E is failing, what should I do?
+
+First, identify the reason for failure.
+
+* Look at the build log, if there's nothing obvious, search for quota issues.
+  * Find events logged by the controller in the build log
+  * Ctrl+f "quota" in the build log
+* If the failure is in the GCE controller:
+  * Navigate to the test artifacts for that run and look at glbc.log, [eg](http://gcsweb.k8s.io/gcs/kubernetes-jenkins/logs/ci-kubernetes-e2e-gci-gce-ingress-release-1.5/1234/artifacts/bootstrap-e2e-master/)
+  * Look up the `PROJECT=` line in the build log, and navigate to that project
+    looking for quota issues (`gcloud compute project-info describe project-name`
+    or navigate to the cloud console > compute > quotas)
+* If the failure is for a non-cloud controller (eg: nginx)
+  * Make sure the firewall rules required by the controller are opened on the
+    right ports (80/443), since the jenkins builders run *outside* the
+    Kubernetes cluster.
+
+Note that you currently need help from a test-infra maintainer to access the GCE
+test project. If you think the failures are related to project quota, cleanup
+leaked resources and bump up quota before debugging the leak.
+
+If the preceding identification process fails, it's likely that the ingress api
+is broked upstream. Try to setup a [dev environment](docs/dev/setup.md) from
+HEAD and create an Ingress. You should be deploying the [latest](https://github.com/kubernetes/ingress/releases)
+release image to the local cluster.
+
+If neither of these 2 strategies produces anything useful, you can either start
+reverting images, or digging into the underlying infrastructure the e2es are
+running on for more nefarious issues (like permission and scope changes for
+some set of nodes on which an ingress controller is running).
+
+## Is there a roadmap for ingress features?
+
+The community is working on it. There are currently too many efforts in flight
+to serialize into a flat roadmap. You might be interested in the following issues:
+* Loadbalancing [umbrella issue](https://github.com/kubernetes/kubernetes/issues/24145)
+* Service proxy [proposal](https://groups.google.com/forum/#!topic/kubernetes-sig-network/weni52UMrI8)
+* Better [routing rules](https://github.com/kubernetes/kubernetes/issues/28443)
+* Ingress [classes](https://github.com/kubernetes/kubernetes/issues/30151)
+
+As well as the issues in this repo.
+

docs/faq/gce.md

@@ -0,0 +1 @@
+# GCE Ingress controller FAQ

docs/faq/nginx.md

@@ -0,0 +1 @@
+# Nginx Ingress controller FAQ