-
Notifications
You must be signed in to change notification settings - Fork 8.2k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Start FAQ docs #66
Merged
Merged
Start FAQ docs #66
Changes from all commits
Commits
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,3 +1,3 @@ | ||
| # Ingress documentation and examples | ||
|
|
||
| This directory contains examples and documentation. | ||
| This directory contains documentation. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,5 @@ | ||
| # Ingress controller catalog | ||
|
|
||
| This is a non-comprehensive list of existing ingress controllers. | ||
|
|
||
|
|
This file was deleted.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,150 @@ | ||
| # 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 | ||
| ================= | ||
|
|
||
| * [How is Ingress different from Services?](#how-is-ingress-different-from-services) | ||
| * [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) | ||
| * [Are Ingress controllers namespaced?](#are-ingress-controllers-namespaced) | ||
| * [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 do I contribute a backend to the generic Ingress controller?](#how-do-i-contribute-a-backend-to-the-generic-ingress-controller) | ||
| * [Is there a catalog of existing Ingress controllers?](#is-there-a-catalog-of-existing-ingress-controllers) | ||
| * [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 is Ingress different from a Service? | ||
|
|
||
| The Kubernetes Service is an abstraction over endpoints (pod-ip:port pairings). | ||
| The Ingress is an abstraction over Services. This doesn't mean all Ingress | ||
| controller must route *through* a Service, but rather, that routing, security | ||
| and auth configuration is represented in the Ingerss resource per Service, and | ||
| not per pod. As long as this configuration is respected, a given Ingress | ||
| controller is free to route to the DNS name of a Service, the VIP, a NodePort, | ||
| or directly to the Service's endpoints. | ||
|
|
||
| ## 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? | ||
|
|
||
| First check the [catalog](#is-there-a-catalog-of-existing-ingress-controllers), to make sure you really need to write one. | ||
|
|
||
| 1. Write a [generic backend](https://github.com/kubernetes/ingress/blob/master/core/pkg/ingress/doc.go) | ||
| 2. Keep it in your own repo, make sure it passes the [conformance suite](https://github.com/kubernetes/kubernetes/blob/master/test/e2e/ingress_utils.go#L112) | ||
| 3. Submit an example(s) in the appropriate subdirectories [here](/examples/README.md) | ||
| 4. Add it to the catalog | ||
|
|
||
| ## Is there a catalog of existing Ingress controllers? | ||
|
|
||
| Yes, a non-comprehensive [catalog](/docs/catalog.md) exists. | ||
|
|
||
| ## How are the Ingress controllers tested? | ||
|
|
||
| Testing for the Ingress controllers is divided between: | ||
| * 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). | ||
| The Ingress E2Es are located [here](https://github.com/kubernetes/kubernetes/blob/master/test/e2e/ingress.go), | ||
| each controller added to that suite must consistently pass the [conformance suite](https://github.com/kubernetes/kubernetes/blob/master/test/e2e/ingress_utils.go#L112). | ||
|
|
||
| ## 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. | ||
|
|
||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
typo: s/Ingerss/Ingress/