Revise ingress docs (#755)

voyagermesh · Dec 14, 2017 · caa0b0a · caa0b0a
1 parent 19e704b
commit caa0b0a
Show file tree

Hide file tree

Showing 90 changed files with 1,273 additions and 518 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -15,7 +15,7 @@ contribution. See the [DCO](DCO) file for details.
 
 ## Developer Guide
 
-We have a [Developer Guide](/docs/developer-guide/README.md) that outlines everything you need to know from setting up your
+We have a [Developer Guide](/docs/setup/developer-guide/README.md) that outlines everything you need to know from setting up your
 dev environment to how to build and test Voyager. If you find something undocumented or incorrect along the way,
 please feel free to send a Pull Request.
 

diff --git a/README.md b/README.md
@@ -2,67 +2,17 @@
 
 [Website](https://appscode.com) • [Slack](https://slack.appscode.com) • [Twitter](https://twitter.com/AppsCodeHQ)
 
-# voyager
+# Voyager
 Voyager is a [HAProxy](http://www.haproxy.org/) backed [secure](#certificate) L7 and L4 [ingress](#ingress) controller for Kubernetes developed by
 [AppsCode](https://appscode.com). This can be used with any Kubernetes cloud providers including aws, gce, gke, azure, acs. This can also be used with bare metal Kubernetes clusters.
 
 
 ## Ingress
-Voyager provides L7 and L4 loadbalancing using a custom Kubernetes [Ingress](/docs/tutorials/ingress) resource. This is built on top of the [HAProxy](http://www.haproxy.org/) to support high availability, sticky sessions, name and path-based virtual hosting.
-This also support configurable application ports with all the options available in a standard Kubernetes [Ingress](https://kubernetes.io/docs/tutorials/ingress/). Here 
-is a [complex ingress example](hack/example/ingress.yaml) that shows how various features can be used.
-You can find the generated HAProxy Configuration [here](hack/example/haproxy_generated.cfg).
-
-**Features**
-  - [HTTP](/docs/tutorials/ingress/single-service.md) and [TCP](/docs/tutorials/ingress/tcp.md) loadbalancing,
-  - [TLS Termination](/docs/tutorials/ingress/tls.md),
-  - Multi-cloud support,
-  - [Name and Path based virtual hosting](/docs/tutorials/ingress/named-virtual-hosting.md),
-  - [Cross namespace routing support](/docs/tutorials/ingress/named-virtual-hosting.md#cross-namespace-traffic-routing),
-  - [URL and Request Header Re-writing](/docs/tutorials/ingress/header-rewrite.md),
-  - [Wildcard Name based virtual hosting](/docs/tutorials/ingress/named-virtual-hosting.md),
-  - Persistent sessions, Loadbalancer stats.
-  - [Route Traffic to StatefulSet Pods Based on Host Name](/docs/tutorials/ingress/statefulset-pod.md)
-  - [Weighted Loadbalancing for Canary Deployment](/docs/tutorials/ingress/weighted.md)
-  - [Customize generated HAProxy config via BackendRule](/docs/tutorials/ingress/backend-rule.md) (can be used for [http rewriting](https://www.haproxy.com/doc/aloha/7.0/haproxy/http_rewriting.html), add [health checks](https://www.haproxy.com/doc/aloha/7.0/haproxy/healthchecks.html), etc.)
-  - [Add Custom Annotation to LoadBalancer Service and Pods](/docs/tutorials/ingress/annotations.md)
-  - [Supports Loadbalancer Source Range](/docs/tutorials/ingress/source-range.md)
-  - [Supports redirects/DNS resolution for `ExternalName` type service](/docs/tutorials/ingress/external-svc.md)
-  - [Expose HAProxy stats for Prometheus](/docs/tutorials/ingress/stats-and-prometheus.md)
-  - [Supports AWS certificate manager](/docs/tutorials/ingress/aws-cert-manager.md)
-  - [Scale load balancer using HorizontalPodAutoscaling](/docs/tutorials/ingress/replicas-and-autoscaling.md)
-  - [Configure Custom Timeouts for HAProxy](/docs/tutorials/ingress/configure-timeouts.md)
-  - [Custom port for HTTP](/docs/tutorials/ingress/custom-http-port.md)
-  - [Specify NodePort](/docs/tutorials/ingress/node-port.md)
-  - [Backend TLS](/docs/tutorials/ingress/backend-tls.md)
-  - [Configure Options](/docs/tutorials/ingress/configure-options.md)
-  - [Using Custom HAProxy Templates](/docs/tutorials/ingress/custom-templates.md)
-  - [Configure Basic Auth for HTTP Backends](/docs/tutorials/ingress/basic-auth.md)
-  - [Configure Sticky session to Backends](/docs/tutorials/ingress/sticky-session.md)
-  - [Apply Frontend Rules](/docs/tutorials/ingress/frontend-rule.md)
-  - [Supported Annotations](/docs/tutorials/ingress/ingress-annotations.md)
-
-
-### Comparison with Kubernetes
-| Feauture | [Kube Ingress](https://kubernetes.io/docs/concepts/services-networking/ingress/) | AppsCode Ingress |
-|----------|--------------|------------------|
-| HTTP Loadbalancing| :white_check_mark: | :white_check_mark: |
-| TCP Loadbalancing | :x: | :white_check_mark: |
-| TLS Termination | :white_check_mark: | :white_check_mark: |
-| Name and Path based virtual hosting | :x: | :white_check_mark: |
-| Cross Namespace service support | :x: | :white_check_mark: |
-| URL and Header rewriting | :x: | :white_check_mark: |
-| Wildcard name virtual hosting | :x: | :white_check_mark: |
-| Loadbalancer statistics | :x: | :white_check_mark: |
-| Route Traffic to StatefulSet Pods Based on Host Name | :x: | :white_check_mark: |
-| Weighted Loadbalancing for Canary Deployment| :x: | :white_check_mark: |
-| Supports Loadbalancer Source Range | :x: | :white_check_mark: |
-| Supports redirects/DNS resolve for `ExternalName` type service | :x: | :white_check_mark: |
-| Expose HAProxy stats for Prometheus | :x: | :white_check_mark: |
-| Supports AWS certificate manager | :x: | :white_check_mark: |
+Voyager provides L7 and L4 loadbalancing using a custom Kubernetes [Ingress](/docs/tasks/ingress) resource. This is built on top of the [HAProxy](http://www.haproxy.org/) to support high availability, sticky sessions, name and path-based virtual hosting.
+This also support configurable application ports with all the options available in a standard Kubernetes [Ingress](https://kubernetes.io/docs/tasks/ingress/).
 
 ## Certificate
-Voyager can automaticallty provision and refresh SSL certificates issued from Let's Encrypt using a custom Kubernetes [Certificate](/docs/tutorials/certificate) resource.
+Voyager can automaticallty provision and refresh SSL certificates issued from Let's Encrypt using a custom Kubernetes [Certificate](/docs/tasks/certificate) resource.
 
 **Features**
 - Provision free TLS certificates from Let's Encrypt,
@@ -81,32 +31,14 @@ Please pick a version of Voyager that matches your Kubernetes installation.
 | [3.2.2](https://github.com/appscode/voyager/releases/tag/3.2.2) (uses TPR)             | [User Guide](https://github.com/appscode/voyager/tree/3.2.2/docs)       | 1.5.x - 1.7.x      | < 0.12.0                    |
 
 
-## User Guide
-To deploy voyager in Kubernetes follow this [guide](/docs/install.md). In short this contains those two steps
-
-1. Create `ingress.voyager.appscode.com` and `certificate.voyager.appscode.com` Third Party Resource
-2. Deploy voyager to kubernetes.
-
-## Running voyager alongside with other ingress controller
-Voyager can be configured to handle default kubernetes ingress or only ingress.appscode.com. voyager can also be run
-along side with other controllers.
-
-```console
-  --ingress-class
-  // this flag can be set to 'voyager' to handle only ingress
-  // with annotation kubernetes.io/ingress.class=voyager.
-
-  // If unset, voyager will also handle ingress without ingress-class annotation.
-```
-
-## Developer Guide
-Want to learn whats happening under the hood, read [the developer guide](/docs/developer-guide/README.md).
+## Installation
+To install Voyager, please follow the guide [here](/docs/setup/install.md).
 
-## Contribution
-If you're interested in being a contributor, read [the contribution guide](CONTRIBUTING.md).
+## Using Voyager
+Want to learn how to use Voyager? Please start [here](/docs/README.md).
 
-## Building voyager
-Read [Build Instructions](/docs/developer-guide/build.md) to build voyager.
+## Contribution guidelines
+Want to help improve Voyager? Please start [here](/CONTRIBUTING.md).
 
 ## Versioning Policy
 There are 2 parts to versioning policy:

diff --git a/apis/voyager/ingress.go b/apis/voyager/ingress.go
@@ -249,7 +249,7 @@ type IngressBackend struct {
 	// This is an handy way to send traffic to Specific
 	// StatefulSet pod.
 	// IE. Setting [web-0] will send traffic to only web-0 host
-	// for this StatefulSet, https://kubernetes.io/docs/tutorials/stateful-application/basic-stateful-set/#creating-a-statefulset
+	// for this StatefulSet, https://kubernetes.io/docs/tasks/stateful-application/basic-stateful-set/#creating-a-statefulset
 	HostNames []string `json:"hostNames,omitempty"`
 
 	// Specifies the name of the referenced service.

diff --git a/apis/voyager/v1beta1/annotations.go b/apis/voyager/v1beta1/annotations.go
@@ -63,7 +63,7 @@ const (
 	//
 	//  - gce, gke, azure: Adds annotation service.beta.kubernetes.io/external-traffic: OnlyLocal
 	// to services used to expose HAProxy.
-	// ref: https://kubernetes.io/docs/tutorials/services/source-ip/#source-ip-for-services-with-typeloadbalancer
+	// ref: https://kubernetes.io/docs/tasks/services/source-ip/#source-ip-for-services-with-typeloadbalancer
 	//
 	// - aws: Enforces the use of the PROXY protocol over any connection accepted by any of
 	// the sockets declared on the same line. Versions 1 and 2 of the PROXY protocol

diff --git a/apis/voyager/v1beta1/certificate.go b/apis/voyager/v1beta1/certificate.go
@@ -75,7 +75,7 @@ type HTTPChallengeProvider struct {
 }
 
 type DNSChallengeProvider struct {
-	// DNS Provider from the list https://github.com/appscode/voyager/blob/master/docs/tutorials/certificate/providers.md
+	// DNS Provider from the list https://github.com/appscode/voyager/blob/master/docs/tasks/certificate/providers.md
 	Provider             string `json:"provider,omitempty"`
 	CredentialSecretName string `json:"credentialSecretName,omitempty"`
 }

diff --git a/apis/voyager/v1beta1/ingress.go b/apis/voyager/v1beta1/ingress.go
@@ -250,7 +250,7 @@ type IngressBackend struct {
 	// This is an handy way to send traffic to Specific
 	// StatefulSet pod.
 	// IE. Setting [web-0] will send traffic to only web-0 host
-	// for this StatefulSet, https://kubernetes.io/docs/tutorials/stateful-application/basic-stateful-set/#creating-a-statefulset
+	// for this StatefulSet, https://kubernetes.io/docs/tasks/stateful-application/basic-stateful-set/#creating-a-statefulset
 	HostNames []string `json:"hostNames,omitempty"`
 
 	// Specifies the name of the referenced service.

diff --git a/apis/voyager/v1beta1/openapi_generated.go b/apis/voyager/v1beta1/openapi_generated.go
@@ -448,7 +448,7 @@ func GetOpenAPIDefinitions(ref common.ReferenceCallback) map[string]common.OpenA
 					Properties: map[string]spec.Schema{
 						"provider": {
 							SchemaProps: spec.SchemaProps{
-								Description: "DNS Provider from the list https://github.com/appscode/voyager/blob/master/docs/tutorials/certificate/providers.md",
+								Description: "DNS Provider from the list https://github.com/appscode/voyager/blob/master/docs/tasks/certificate/providers.md",
 								Type:        []string{"string"},
 								Format:      "",
 							},
@@ -587,7 +587,7 @@ func GetOpenAPIDefinitions(ref common.ReferenceCallback) map[string]common.OpenA
 					Properties: map[string]spec.Schema{
 						"hostNames": {
 							SchemaProps: spec.SchemaProps{
-								Description: "Host names to forward traffic to. If empty traffic will be forwarded to all subsets instance. If set only matched hosts will get the traffic. This is an handy way to send traffic to Specific StatefulSet pod. IE. Setting [web-0] will send traffic to only web-0 host for this StatefulSet, https://kubernetes.io/docs/tutorials/stateful-application/basic-stateful-set/#creating-a-statefulset",
+								Description: "Host names to forward traffic to. If empty traffic will be forwarded to all subsets instance. If set only matched hosts will get the traffic. This is an handy way to send traffic to Specific StatefulSet pod. IE. Setting [web-0] will send traffic to only web-0 host for this StatefulSet, https://kubernetes.io/docs/tasks/stateful-application/basic-stateful-set/#creating-a-statefulset",
 								Type:        []string{"array"},
 								Items: &spec.SchemaOrArray{
 									Schema: &spec.Schema{
@@ -785,7 +785,7 @@ func GetOpenAPIDefinitions(ref common.ReferenceCallback) map[string]common.OpenA
 					Properties: map[string]spec.Schema{
 						"hostNames": {
 							SchemaProps: spec.SchemaProps{
-								Description: "Host names to forward traffic to. If empty traffic will be forwarded to all subsets instance. If set only matched hosts will get the traffic. This is an handy way to send traffic to Specific StatefulSet pod. IE. Setting [web-0] will send traffic to only web-0 host for this StatefulSet, https://kubernetes.io/docs/tutorials/stateful-application/basic-stateful-set/#creating-a-statefulset",
+								Description: "Host names to forward traffic to. If empty traffic will be forwarded to all subsets instance. If set only matched hosts will get the traffic. This is an handy way to send traffic to Specific StatefulSet pod. IE. Setting [web-0] will send traffic to only web-0 host for this StatefulSet, https://kubernetes.io/docs/tasks/stateful-application/basic-stateful-set/#creating-a-statefulset",
 								Type:        []string{"array"},
 								Items: &spec.SchemaOrArray{
 									Schema: &spec.Schema{

diff --git a/chart/stable/voyager/values.yaml b/chart/stable/voyager/values.yaml
@@ -19,10 +19,10 @@ exporter:
 # imagePullSecrets:
 #   - name: myRegistryKeySecretName
 ## Specify a imagePullPolicy
-## ref: http://kubernetes.io/docs/tutorials/images/#pre-pulling-images
+## ref: http://kubernetes.io/docs/tasks/images/#pre-pulling-images
 ##
 imagePullPolicy: IfNotPresent
-## Use cloud provider here. Read details https://github.com/appscode/voyager/blob/master/docs/tutorials/README.md
+## Use cloud provider here. Read details https://github.com/appscode/voyager/blob/master/docs/tasks/README.md
 cloudProvider:
 ## The path to the cloud provider configuration file. Empty string for no configuration file.
 ## ie. for azure use /etc/kubernetes/azure.json
@@ -37,7 +37,7 @@ persistence:
   hostPath: /etc/kubernetes
 
 ## Node labels for pod assignment
-## Ref: https://kubernetes.io/docs/tutorials/node-selection/
+## Ref: https://kubernetes.io/docs/tasks/node-selection/
 ##
 nodeSelector: {}
 

diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md
@@ -0,0 +1,44 @@
+# Contribution Guidelines
+Want to hack on Voyager?
+
+AppsCode projects are [Apache 2.0 licensed](LICENSE) and accept contributions via
+GitHub pull requests.  This document outlines some of the conventions on
+development workflow, commit message formatting, contact points and other
+resources to make it easier to get your contribution accepted.
+
+## Certificate of Origin
+
+By contributing to this project you agree to the Developer Certificate of
+Origin (DCO). This document was created by the Linux Kernel community and is a
+simple statement that you, as a contributor, have the legal right to make the
+contribution. See the [DCO](DCO) file for details.
+
+## Developer Guide
+
+We have a [Developer Guide](/docs/setup/developer-guide/README.md) that outlines everything you need to know from setting up your
+dev environment to how to build and test Voyager. If you find something undocumented or incorrect along the way,
+please feel free to send a Pull Request.
+
+## Getting Help
+
+If you have a question about Voyager or having problem using it, you can contact us on our public Slack channel. Follow [this link](https://slack.appscode.com) to get invitation to our Slack channel.
+
+## Bugs/Feature request
+
+If you have found a bug with Voyager or want to request for new features, please [file an issue](https://github.com/appscode/Voyager/issues/new).
+
+## Submit PR
+
+If you fix a bug or developed a new feature, feel free to submit a PR. In either case, please file a [Github issue]((https://github.com/appscode/Voyager/issues/new)) first, so that we can have a discussion on it. This is a rough outline of what a contributor's workflow looks like:
+
+- Create a topic branch from where you want to base your work (usually master).
+- Make commits of logical units.
+- Push your changes to a topic branch in your fork of the repository.
+- Make sure the tests pass, and add any new tests as appropriate.
+- Submit a pull request to the original repository.
+
+Thanks for your contributions!
+
+## Spread the word
+
+If you have written blog post or tutorial on Voyager, please share it with us on [Twitter](https://twitter.com/AppsCodeHQ) or [Slack](https://slack.appscode.com).