From 0afab18de7a764e050cc43b85e2f29284acfd37a Mon Sep 17 00:00:00 2001 From: Tamal Saha Date: Wed, 3 Jan 2018 18:42:45 -0800 Subject: [PATCH] Reorganize docs for hosting on product site (#798) --- docs/CONTRIBUTING.md | 24 +- docs/README.md | 17 +- docs/_index.md | 4 +- docs/acknowledgement.md | 10 +- docs/concepts/README.md | 5 +- docs/concepts/ingress-class.md | 14 -- docs/concepts/overview.md | 49 ++--- docs/guides/_index.md | 3 +- docs/guides/certificate/README.md | 19 +- docs/guides/certificate/_index.md | 2 +- docs/guides/certificate/delete.md | 11 +- docs/guides/certificate/dns/_index.md | 11 + .../certificate/{ => dns}/google-cloud.md | 10 +- .../guides/certificate/{ => dns}/providers.md | 19 +- docs/guides/certificate/{ => dns}/route53.md | 10 +- docs/guides/certificate/faq.md | 14 +- docs/guides/certificate/http/_index.md | 11 + .../certificate/{http.md => http/overview.md} | 10 +- docs/guides/ingress/README.md | 207 +++--------------- docs/guides/ingress/_index.md | 2 +- docs/guides/ingress/configuration/_index.md | 6 +- .../ingress/configuration/annotations.md | 38 ++-- .../ingress/configuration/backend-rule.md | 10 +- .../ingress/configuration/custom-templates.md | 8 +- ...onfigure-options.md => default-options.md} | 23 +- ...figure-timeouts.md => default-timeouts.md} | 7 +- .../ingress/configuration/frontend-rule.md | 12 +- .../guides/ingress/configuration/node-port.md | 23 +- docs/guides/ingress/http/_index.md | 6 +- .../{weighted.md => blue-green-deployment.md} | 16 +- docs/guides/ingress/http/cors.md | 10 +- docs/guides/ingress/http/custom-http-port.md | 9 +- docs/guides/ingress/http/external-svc.md | 7 +- docs/guides/ingress/http/hsts.md | 13 +- .../{header-rewrite.md => rewrite-rules.md} | 18 +- docs/guides/ingress/http/simple-fanout.md | 81 ------- docs/guides/ingress/http/single-service.md | 11 +- docs/guides/ingress/http/source-range.md | 10 +- docs/guides/ingress/http/statefulset-pod.md | 21 +- docs/guides/ingress/http/sticky-session.md | 11 +- ...-virtual-hosting.md => virtual-hosting.md} | 51 ++++- docs/guides/ingress/monitoring/_index.md | 6 +- .../monitoring/coreos-prometheus-operator.md | 21 +- .../{stats-and-prometheus.md => stats.md} | 9 +- docs/guides/ingress/pod-placement.md | 17 +- ...replicas-and-autoscaling.md => scaling.md} | 12 +- docs/guides/ingress/security/_index.md | 6 +- docs/guides/ingress/security/basic-auth.md | 7 +- docs/guides/ingress/security/tls-auth.md | 26 ++- docs/guides/ingress/tcp/_index.md | 6 +- .../ingress/tcp/{tcp.md => overview.md} | 14 +- docs/guides/ingress/tls/_index.md | 6 +- docs/guides/ingress/tls/aws-cert-manager.md | 13 +- docs/guides/ingress/tls/backend-tls.md | 14 +- .../ingress/tls/{tls.md => overview.md} | 19 +- docs/roadmap.md | 15 +- docs/setup/README.md | 25 +++ docs/setup/_index.md | 3 +- docs/setup/developer-guide/_index.md | 2 +- .../{README.md => overview.md} | 5 +- docs/setup/developer-guide/release.md | 5 +- docs/setup/install.md | 17 +- docs/setup/uninstall.md | 27 ++- docs/support.md | 16 +- 64 files changed, 523 insertions(+), 611 deletions(-) create mode 100644 docs/guides/certificate/dns/_index.md rename docs/guides/certificate/{ => dns}/google-cloud.md (97%) rename docs/guides/certificate/{ => dns}/providers.md (93%) rename docs/guides/certificate/{ => dns}/route53.md (98%) create mode 100644 docs/guides/certificate/http/_index.md rename docs/guides/certificate/{http.md => http/overview.md} (96%) rename docs/guides/ingress/configuration/{configure-options.md => default-options.md} (58%) rename docs/guides/ingress/configuration/{configure-timeouts.md => default-timeouts.md} (93%) rename docs/guides/ingress/http/{weighted.md => blue-green-deployment.md} (87%) rename docs/guides/ingress/http/{header-rewrite.md => rewrite-rules.md} (84%) delete mode 100644 docs/guides/ingress/http/simple-fanout.md rename docs/guides/ingress/http/{named-virtual-hosting.md => virtual-hosting.md} (61%) rename docs/guides/ingress/monitoring/{stats-and-prometheus.md => stats.md} (96%) rename docs/guides/ingress/{replicas-and-autoscaling.md => scaling.md} (93%) rename docs/guides/ingress/tcp/{tcp.md => overview.md} (91%) rename docs/guides/ingress/tls/{tls.md => overview.md} (96%) create mode 100644 docs/setup/README.md rename docs/setup/developer-guide/{README.md => overview.md} (97%) diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 62c87881c..026f9ef13 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -5,17 +5,20 @@ menu: product_voyager_5.0.0-rc.10: identifier: contributing-voyager name: Contributing - parent: getting-started - weight: 35 + parent: welcome + weight: 10 product_name: voyager menu_name: product_voyager_5.0.0-rc.10 -section_menu_id: getting-started -url: /products/voyager/5.0.0-rc.10/getting-started/contributing/ +section_menu_id: welcome +url: /products/voyager/5.0.0-rc.10/welcome/contributing/ +aliases: + - /products/voyager/5.0.0-rc.10/CONTRIBUTING/ --- + # Contribution Guidelines Want to hack on Voyager? -AppsCode projects are [Apache 2.0 licensed](LICENSE) and accept contributions via +AppsCode projects are [Apache 2.0 licensed](https://github.com/appscode/voyager/blob/master/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. @@ -25,25 +28,26 @@ resources to make it easier to get your contribution accepted. 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. +contribution. See the [DCO](https://github.com/appscode/voyager/blob/master/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 +We have a [Developer Guide](/docs/setup/developer-guide/overview.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. +If you have a question about Voyager or having problem using it, you can contact us on the [AppsCode Slack team](https://appscode.slack.com/messages/C0XQFLGRM/details/) channel `#general`. 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). +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: +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. diff --git a/docs/README.md b/docs/README.md index d81482a76..d6f7c7352 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,22 +1,23 @@ --- -title: Overview | Voyager -description: Overview of Voyager +title: Weclome | Voyager +description: Welcome to Voyager menu: product_voyager_5.0.0-rc.10: - identifier: overview-voyager - name: Overview - parent: getting-started - weight: 20 + identifier: readme-voyager + name: Readme + parent: welcome + weight: -1 product_name: voyager menu_name: product_voyager_5.0.0-rc.10 -section_menu_id: getting-started -url: /products/voyager/5.0.0-rc.10/getting-started/ +section_menu_id: welcome +url: /products/voyager/5.0.0-rc.10/welcome/ aliases: - /products/voyager/5.0.0-rc.10/ - /products/voyager/5.0.0-rc.10/README/ --- # Voyager + Voyager is a [HAProxy](http://www.haproxy.org/) backed secure L7 and L4 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. From here you can learn all about Voyager's architecture and how to deploy and use Voyager. diff --git a/docs/_index.md b/docs/_index.md index 4c6ed5879..8b7c4d221 100644 --- a/docs/_index.md +++ b/docs/_index.md @@ -3,8 +3,8 @@ title: Docs | Voyager description: Voyager Docs menu: product_voyager_5.0.0-rc.10: - identifier: getting-started - name: Getting Started + identifier: welcome + name: Welcome weight: 10 menu_name: product_voyager_5.0.0-rc.10 --- diff --git a/docs/acknowledgement.md b/docs/acknowledgement.md index eb235105d..4e6412e20 100644 --- a/docs/acknowledgement.md +++ b/docs/acknowledgement.md @@ -5,12 +5,14 @@ menu: product_voyager_5.0.0-rc.10: identifier: acknowledgement-voyager name: Acknowledgement - parent: getting-started - weight: 40 + parent: welcome + weight: 20 product_name: voyager menu_name: product_voyager_5.0.0-rc.10 -section_menu_id: getting-started -url: /products/voyager/5.0.0-rc.10/getting-started/acknowledgement/ +section_menu_id: welcome +url: /products/voyager/5.0.0-rc.10/welcome/acknowledgement/ +aliases: + - /products/voyager/5.0.0-rc.10/acknowledgement/ --- # Acknowledgement diff --git a/docs/concepts/README.md b/docs/concepts/README.md index 9b9ab5aed..0fc262997 100644 --- a/docs/concepts/README.md +++ b/docs/concepts/README.md @@ -13,7 +13,8 @@ url: /products/voyager/5.0.0-rc.10/concepts/ aliases: - /products/voyager/5.0.0-rc.10/concepts/README/ --- - # Concepts -Concepts help you learn about the different parts of the Voyager system and the abstractions it uses. +Concepts help you learn about the different parts of the Voyager and the abstractions it uses. + +- [Overview](/docs/concepts/overview.md). Provides a conceptual introduction to Voyager, including the problems it solves and its high-level architecture. diff --git a/docs/concepts/ingress-class.md b/docs/concepts/ingress-class.md index 84966e18a..37e26baa6 100644 --- a/docs/concepts/ingress-class.md +++ b/docs/concepts/ingress-class.md @@ -1,17 +1,3 @@ ---- -title: Ingress Class | Voyager -description: Ingress Class -menu: - product_voyager_5.0.0-rc.10: - identifier: ingress-class - name: Ingress Class - parent: concepts - weight: 40 -product_name: voyager -menu_name: product_voyager_5.0.0-rc.10 -section_menu_id: concepts ---- - # 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 diff --git a/docs/concepts/overview.md b/docs/concepts/overview.md index 477d82085..43f79461a 100644 --- a/docs/concepts/overview.md +++ b/docs/concepts/overview.md @@ -1,19 +1,14 @@ --- title: Overview | Voyager -description: Overview of Voyager menu: product_voyager_5.0.0-rc.10: - identifier: overview-voyager + identifier: overview-concepts name: Overview - parent: getting-started - weight: 20 + parent: concepts + weight: 10 product_name: voyager menu_name: product_voyager_5.0.0-rc.10 -section_menu_id: getting-started -url: /products/voyager/5.0.0-rc.10/getting-started/ -aliases: - - /products/voyager/5.0.0-rc.10/ - - /products/voyager/5.0.0-rc.10/README/ +section_menu_id: concepts --- # Voyager @@ -23,22 +18,20 @@ Voyager is a [HAProxy](http://www.haproxy.org/) backed [secure](#certificate) L7 ## Ingress Voyager provides L7 and L4 loadbalancing using a custom Kubernetes [Ingress](/docs/guides/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/guides/ingress/). +This also support configurable application ports with all the options available in a standard Kubernetes [Ingress](https://kubernetes.io/docs/concepts/services-networking/ingress/). -**Features** - HTTP - - [Single Service Ingress](/docs/guides/ingress/http/single-service.md) - - [Name and Path based virtual hosting](/docs/guides/ingress/http/named-virtual-hosting.md) + - [Exposing Service via Ingress](/docs/guides/ingress/http/single-service.md) + - [Virtual Hosting](/docs/guides/ingress/http/virtual-hosting.md) - [Supports Loadbalancer Source Range](/docs/guides/ingress/http/source-range.md) - - [URL and Request Header Re-writing](/docs/guides/ingress/http/header-rewrite.md) + - [URL and Request Header Re-writing](/docs/guides/ingress/http/rewrite-rules.md) - [Enable CORS](/docs/guides/ingress/http/cors.md) - [Custom HTTP Port](/docs/guides/ingress/http/custom-http-port.md) - - [Supports redirects/DNS resolution for `ExternalName` type service](/docs/guides/ingress/http/external-svc.md) + - [Using External Service as Ingress Backend](/docs/guides/ingress/http/external-svc.md) - [HSTS](/docs/guides/ingress/http/hsts.md) - - [Simple Fanout](/docs/guides/ingress/http/simple-fanout.md) - - [Route Traffic to StatefulSet Pods Based on Host Name](/docs/guides/ingress/http/statefulset-pod.md) + - [Forward Traffic to StatefulSet Pods](/docs/guides/ingress/http/statefulset-pod.md) - [Configure Sticky session to Backends](/docs/guides/ingress/http/sticky-session.md) - - [Weighted Loadbalancing for Canary Deployment](/docs/guides/ingress/http/weighted.md) + - [Blue Green Deployments using weighted Loadbalancing](/docs/guides/ingress/http/weighted.md) - TLS/SSL - [TLS Termination](/docs/guides/ingress/tls/tls.md) - [Backend TLS](/docs/guides/ingress/tls/backend-tls.md) @@ -49,29 +42,23 @@ This also support configurable application ports with all the options available - [Customize generated HAProxy config via BackendRule](/docs/guides/ingress/configuration/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.) - [Apply Frontend Rules](/docs/guides/ingress/configuration/frontend-rule.md) - [Supported Annotations](/docs/guides/ingress/configuration/annotations.md) - - [Bind to address](/docs/guides/ingress/configuration/bind-address.md) - [Specify NodePort](/docs/guides/ingress/configuration/node-port.md) - - [Configure global options](/docs/guides/ingress/configuration/configure-options.md) - - [Configure Custom Timeouts for HAProxy](/docs/guides/ingress/configuration/configure-timeouts.md) + - [Configure global options](/docs/guides/ingress/configuration/default-options.md) + - [Configure Custom Timeouts for HAProxy](/docs/guides/ingress/configuration/default-timeouts.md) - [Using Custom HAProxy Templates](/docs/guides/ingress/configuration/custom-templates.md) -- External DNS - - [Configuring DNS](/docs/guides/ingress/dns/external-dns.md) - Security - [Configure Basic Auth for HTTP Backends](/docs/guides/ingress/security/basic-auth.md) - [TLS Authentication](/docs/guides/ingress/security/tls-auth.md) - - [Configuring RBAC](/docs/guides/ingress/security/rbac.md) - - [Running Voyager per Namespace](/docs/guides/ingress/security/restrict-namespace.md) - Monitoring - - [Exposing HAProxy Stats](/docs/guides/ingress/monitoring/stats-and-prometheus.md) -- [Replicas and Horizontal Pod Autoscaling](/docs/guides/ingress/replicas-and-autoscaling.md) -- [Placement of HAProxy Pods](/docs/guides/ingress/pod-placement.md) -- [Debugging Ingress](/docs/guides/ingress/debugging.md) + - [Exposing HAProxy Stats](/docs/guides/ingress/monitoring/stats.md) +- [Scaling Ingress](/docs/guides/ingress/scaling.md) +- [Placement of Ingress Pods](/docs/guides/ingress/pod-placement.md) ## Certificate -Voyager can automaticallty provision and refresh SSL certificates issued from Let's Encrypt using a custom Kubernetes [Certificate](/docs/guides/certificate) resource. -**Features** +Voyager can automagically provision and refresh SSL certificates issued from Let's Encrypt using a custom Kubernetes [Certificate](/docs/guides/certificate) resource. + - Provision free TLS certificates from Let's Encrypt, - Manage issued certificates using a Kubernetes Third Party Resource, - Domain validation using ACME dns-01 challenges, diff --git a/docs/guides/_index.md b/docs/guides/_index.md index 481911f4e..42d9199f3 100644 --- a/docs/guides/_index.md +++ b/docs/guides/_index.md @@ -1,6 +1,5 @@ --- -title: Guides -description: Voyager Guides +title: Guides | Voyager menu: product_voyager_5.0.0-rc.10: identifier: guides diff --git a/docs/guides/certificate/README.md b/docs/guides/certificate/README.md index 29a129416..7151d5aab 100644 --- a/docs/guides/certificate/README.md +++ b/docs/guides/certificate/README.md @@ -1,9 +1,10 @@ --- +title: Certificate | Voyager menu: product_voyager_5.0.0-rc.10: - identifier: certificate-readme + identifier: readme-certificate name: Readme - parent: certificate + parent: certificate-guides weight: -1 product_name: voyager menu_name: product_voyager_5.0.0-rc.10 @@ -13,23 +14,23 @@ aliases: - /products/voyager/5.0.0-rc.10/guides/certificate/README/ --- -# Certificate +# Guides -Voyager comes with a built-in certificate manager that can issue free TLS/SSL certificates from Let's Encrypt. Voyager uses a Custom Resource Definition called `Certificate` to declaratively manage and issue certificates from Let's Encrypt. +Guides show you how to use Voyager's built-in certificate manager to issue free TLS/SSL certificates from Let's Encrypt. ## Features - Provision free TLS certificates from Let's Encrypt. - Manage certificates declaratively using a Kubernetes Custom Resource Definition (CRD). - Domain validation using ACME http-01 and dns-01 challenges. -- Support for many popular [DNS providers](/docs/guides/certificate/providers.md). +- Support for many popular [DNS providers](/docs/guides/certificate/dns/providers.md). - Auto Renew certificates. - Use issued certificates with Ingress to secure communications. ## Next Steps -- [Issue Let's Encrypt certificate using HTTP-01 challenge](/docs/guides/certificate/http.md) +- [Issue Let's Encrypt certificate using HTTP-01 challenge](/docs/guides/certificate/http/overview.md) - DNS-01 chanllege providers - - [Issue Let's Encrypt certificate using AWS Route53](/docs/guides/certificate/route53.md) - - [Issue Let's Encrypt certificate using Google Cloud DNS](/docs/guides/certificate/google-cloud.md) - - [Supported DNS Challenge Providers](/docs/guides/certificate/providers.md) + - [Issue Let's Encrypt certificate using AWS Route53](/docs/guides/certificate/dns/route53.md) + - [Issue Let's Encrypt certificate using Google Cloud DNS](/docs/guides/certificate/dns/google-cloud.md) + - [Supported DNS Challenge Providers](/docs/guides/certificate/dns/providers.md) - [Deleting Certificate](/docs/guides/certificate/delete.md) - [Frequently Asked Questions](/docs/guides/certificate/faq.md) diff --git a/docs/guides/certificate/_index.md b/docs/guides/certificate/_index.md index 7cd3af965..85cbd60f3 100644 --- a/docs/guides/certificate/_index.md +++ b/docs/guides/certificate/_index.md @@ -2,7 +2,7 @@ title: Certificate menu: product_voyager_5.0.0-rc.10: - identifier: certificate + identifier: certificate-guides name: Certificate parent: guides weight: 80 diff --git a/docs/guides/certificate/delete.md b/docs/guides/certificate/delete.md index bbc21af18..b3463eddf 100644 --- a/docs/guides/certificate/delete.md +++ b/docs/guides/certificate/delete.md @@ -1,30 +1,35 @@ --- +title: Delete Certificate | Voyager menu: product_voyager_5.0.0-rc.10: - identifier: certificate-delete + identifier: delete-certificate name: Delete - parent: certificate - weight: 60 + parent: certificate-guides + weight: 20 product_name: voyager menu_name: product_voyager_5.0.0-rc.10 section_menu_id: guides --- + # Deleting Certificate Deleting a Kubernetes `Certificate` object will only delete the certificate CRD from Kubernetes. It will not delete the obtained certificate and user account secret from Kubernetes. User have to manually delete these secrets for complete cleanup. - Delete Certificate crd. + ```console kubectl delete certificate.voyager.appscode.com test-cert ``` - Delete Obtained Let's Encrypt tls certificate + ```console kubectl delete secret tls-test-cert ``` - Delete Let's Encrypt user account `Secret` + ```console kubectl delete secret test-user-secret ``` diff --git a/docs/guides/certificate/dns/_index.md b/docs/guides/certificate/dns/_index.md new file mode 100644 index 000000000..09d9bfef8 --- /dev/null +++ b/docs/guides/certificate/dns/_index.md @@ -0,0 +1,11 @@ +--- +title: DNS Challenger +description: DNS Challenger +menu: + product_voyager_5.0.0-rc.10: + identifier: dns-certificate + parent: certificate-guides + name: DNS Challenger + weight: 15 +menu_name: product_voyager_5.0.0-rc.10 +--- diff --git a/docs/guides/certificate/google-cloud.md b/docs/guides/certificate/dns/google-cloud.md similarity index 97% rename from docs/guides/certificate/google-cloud.md rename to docs/guides/certificate/dns/google-cloud.md index 96fb62569..c71da438c 100644 --- a/docs/guides/certificate/google-cloud.md +++ b/docs/guides/certificate/dns/google-cloud.md @@ -1,10 +1,12 @@ --- +title: Issue Let's Encrypt certificate using Google Cloud DNS +description: Issue Let's Encrypt certificate using Google Cloud DNS in Kubernetes menu: product_voyager_5.0.0-rc.10: - identifier: certificate-google-cloud + identifier: googlecloud-dns name: Google Cloud - parent: certificate - weight: 30 + parent: dns-certificate + weight: 15 product_name: voyager menu_name: product_voyager_5.0.0-rc.10 section_menu_id: guides @@ -24,7 +26,7 @@ Server Version: v1.8.4-gke.0 ## Deploy Voyager operator -Deploy Voyager operator following instructions [here](/docs/install.md). +Deploy Voyager operator following instructions [here](/docs/setup/install.md). ```console # install without RBAC diff --git a/docs/guides/certificate/providers.md b/docs/guides/certificate/dns/providers.md similarity index 93% rename from docs/guides/certificate/providers.md rename to docs/guides/certificate/dns/providers.md index ad355a111..f6c23a319 100644 --- a/docs/guides/certificate/providers.md +++ b/docs/guides/certificate/dns/providers.md @@ -1,10 +1,12 @@ --- +title: Supported DNS Challenge Providers +description: Supported DNS Challenge Providers menu: product_voyager_5.0.0-rc.10: - identifier: certificate-provider - name: Providers - parent: certificate - weight: 40 + identifier: providers-dns + name: Supported Providers + parent: dns-certificate + weight: 20 product_name: voyager menu_name: product_voyager_5.0.0-rc.10 section_menu_id: guides @@ -24,7 +26,7 @@ Please see the list of supported providers and the keys expected in credential p - `AWS_SECRET_ACCESS_KEY`: The secret corresponding to the access key - `AWS_HOSTED_ZONE_ID`: `Optional`. If AWS_HOSTED_ZONE_ID is not set, Voyager tries to determine the correct public hosted zone via the FQDN. -To learn about necessary IAM permissions, please see [here](/docs/guides/certificate/route53.md#configure-iam-permissions). +To learn about necessary IAM permissions, please see [here](/docs/guides/certificate/dns/route53.md). ### Microsoft Azure - Provider: `azure` or `acs` @@ -83,7 +85,7 @@ To learn about necessary IAM permissions, please see [here](/docs/guides/certifi - `GCE_PROJECT`: The name of the Google Cloud project to use - `GOOGLE_SERVICE_ACCOUNT_JSON_KEY`: Service account json downloaded from Google Cloud console. This service account requires scope `https://www.googleapis.com/auth/ndev.clouddns.readwrite` to view and manage your DNS records hosted by Google Cloud DNS. -If you are running your cluster on Google Cloud (GKE or GCE), Voyager can use default service account associated with a VM. Please see [here](/docs/guides/certificate/google-cloud.md#configure-service-account-permissions) for detailed instructions. +If you are running your cluster on Google Cloud (GKE or GCE), Voyager can use default service account associated with a VM. Please see [here](/docs/guides/certificate/dns/google-cloud.md) for detailed instructions. ### Linode - Provider: `linode` @@ -167,5 +169,6 @@ spec: ``` For detailed guides on how to issue SSL certificates using Voyager, please see below: -- [Issue Let's Encrypt certificate using AWS Route53](/docs/guides/certificate/route53.md) -- [Issue Let's Encrypt certificate using Google Cloud DNS](/docs/guides/certificate/google-cloud.md) + +- [Issue Let's Encrypt certificate using AWS Route53](/docs/guides/certificate/dns/route53.md) +- [Issue Let's Encrypt certificate using Google Cloud DNS](/docs/guides/certificate/dns/google-cloud.md) diff --git a/docs/guides/certificate/route53.md b/docs/guides/certificate/dns/route53.md similarity index 98% rename from docs/guides/certificate/route53.md rename to docs/guides/certificate/dns/route53.md index 9158542e7..586a3153e 100644 --- a/docs/guides/certificate/route53.md +++ b/docs/guides/certificate/dns/route53.md @@ -1,10 +1,12 @@ --- +title: Issue Let's Encrypt certificate using AWS Route53 +description: Issue Let's Encrypt certificate using AWS Route53 in Kubernetes menu: product_voyager_5.0.0-rc.10: - identifier: certificate-route53 - name: Route53 - parent: certificate - weight: 50 + identifier: route53-dns + name: AWS Route53 + parent: dns-certificate + weight: 10 product_name: voyager menu_name: product_voyager_5.0.0-rc.10 section_menu_id: guides diff --git a/docs/guides/certificate/faq.md b/docs/guides/certificate/faq.md index f7efd6d85..a21c226a5 100644 --- a/docs/guides/certificate/faq.md +++ b/docs/guides/certificate/faq.md @@ -1,10 +1,11 @@ --- +title: Certificate FAQ | Voyager menu: product_voyager_5.0.0-rc.10: - identifier: certificate-faq + identifier: faq-certificate name: FAQ - parent: certificate - weight: 70 + parent: certificate-guides + weight: 25 product_name: voyager menu_name: product_voyager_5.0.0-rc.10 section_menu_id: guides @@ -25,6 +26,7 @@ kubectl describe certificate --namespace ``` You can also check the logs for voyager operator pod and look for anything suspicious. + ```console kubectl logs -f -n kube-system ``` @@ -34,6 +36,7 @@ Please consult the official document on this matter: https://letsencrypt.org/doc ### How to use Let's Encrypt staging servers? If you are just testing Voyager and want to avoid hitting the rate limits in LE productoion environment, you have 2 options: + - Buy a cheap domain for testing. There are lot of $0.99/yr domains available these days. - You can tell voyager to use the LE staging servers for issuing the certificate. The issued certificate is not trusted, hence should not be used in production websites. But this works great for testing purposes. To use the staging environment, set the key `ACME_SERVER_URL` in your acme secret in addition to your email address. @@ -67,8 +70,9 @@ type: Opaque ### How can I distribute the issued ssl certificates? There are several options: -- If you are trying to distribute the same ssl certificate across different namespaces of a cluster, you can use a tool like [kubed](https://github.com/appscode/kubed/blob/master/docs/guides/config-syncer.md). -- If you want to distribute the issued certificates across different clusters, you can setup Voyager to issue certificates independently on each cluster. Please read the rate limiting restrictions for LE. The other option is to use [Kubernetes cluster federation](https://kubernetes.io/docs/guides/administer-federation/secret/) but it might not be worth the trouble if this is your only usecase for cluster federation. + +- If you are trying to distribute the same ssl certificate across different namespaces of a cluster, you can use a tool like [kubed](https://appscode.com/products/kubed). +- If you want to distribute the issued certificates across different clusters, you can setup Voyager to issue certificates independently on each cluster. Please read the rate limiting restrictions for LE. The other option is to use [kubed](https://appscode.com/products/kubed). - Just manually copy paste the `tls-***` secret to your destination cluster or namespace. diff --git a/docs/guides/certificate/http/_index.md b/docs/guides/certificate/http/_index.md new file mode 100644 index 000000000..f18a5c8df --- /dev/null +++ b/docs/guides/certificate/http/_index.md @@ -0,0 +1,11 @@ +--- +title: HTTP Challenger +description: HTTP Challenger +menu: + product_voyager_5.0.0-rc.10: + identifier: http-certificate + parent: certificate-guides + name: HTTP Challenger + weight: 10 +menu_name: product_voyager_5.0.0-rc.10 +--- diff --git a/docs/guides/certificate/http.md b/docs/guides/certificate/http/overview.md similarity index 96% rename from docs/guides/certificate/http.md rename to docs/guides/certificate/http/overview.md index df80188da..9910532cd 100644 --- a/docs/guides/certificate/http.md +++ b/docs/guides/certificate/http/overview.md @@ -1,10 +1,12 @@ --- +title: Issue Let's Encrypt certificate using HTTP-01 challenge +description: Issue Let's Encrypt certificate using HTTP-01 challenge in Kubernetes menu: product_voyager_5.0.0-rc.10: - identifier: certificate-http - name: HTTP - parent: certificate - weight: 20 + identifier: overview-http + name: Overview + parent: http-certificate + weight: 10 product_name: voyager menu_name: product_voyager_5.0.0-rc.10 section_menu_id: guides diff --git a/docs/guides/ingress/README.md b/docs/guides/ingress/README.md index b80fbc097..1aecee18f 100644 --- a/docs/guides/ingress/README.md +++ b/docs/guides/ingress/README.md @@ -1,9 +1,11 @@ --- +title: Ingress | Voyager menu: product_voyager_5.0.0-rc.10: - name: Overview - parent: ingress - weight: 8 + identifier: readme-ingress + name: Readme + parent: ingress-guides + weight: -1 product_name: voyager menu_name: product_voyager_5.0.0-rc.10 section_menu_id: guides @@ -12,179 +14,40 @@ aliases: - /products/voyager/5.0.0-rc.10/guides/ingress/README/ --- -### Ingress -An Ingress is a collection of rules which allow inbound connections to reach the cluster services. -It can be configured to give services externally-reachable urls, load balance traffic, terminate SSL, -offer name-based virtual hosting, etc. Users can request ingress by POSTing the Ingress resource to API server. [Read More](http://kubernetes.io/docs/guides/ingress/) +# Guides -### Appscode Ingress -An extended plugin of Kubernetes Ingress by AppsCode, to support both L7 and L4 load balancing via a single ingress. -This is built on top of the HAProxy, to support high availability, sticky sessions, name and path-based virtual -hosting. This plugin also support configurable application ports with all the features available in Kubernetes Ingress. [Read More](#what-is-appscode-ingress) +Guides show you how to use Voyager as a Kubernetes Ingress controller. -**Features** - - [HTTP](/docs/guides/ingress/http/single-service.md) and [TCP](/docs/guides/ingress/tcp/tcp.md) loadbalancing, - - [TLS Termination](/docs/guides/ingress/tls/tls.md), - - Multi-cloud support, - - [Name and Path based virtual hosting](/docs/guides/ingress/http/named-virtual-hosting.md), - - [Cross namespace routing support](/docs/guides/ingress/http/named-virtual-hosting.md#cross-namespace-traffic-routing), - - [URL and Request Header Re-writing](/docs/guides/ingress/http/header-rewrite.md), - - [Wildcard Name based virtual hosting](/docs/guides/ingress/http/named-virtual-hosting.md), - - Persistent sessions, Loadbalancer stats. - - [Route Traffic to StatefulSet Pods Based on Host Name](/docs/guides/ingress/http/statefulset-pod.md) - - [Weighted Loadbalancing for Canary Deployment](/docs/guides/ingress/http/weighted.md) - - [Customize generated HAProxy config via BackendRule](/docs/guides/ingress/configuration/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/guides/ingress/configuration/annotations.md) +- HTTP + - [Exposing Service via Ingress](/docs/guides/ingress/http/single-service.md) + - [Virtual Hosting](/docs/guides/ingress/http/virtual-hosting.md) - [Supports Loadbalancer Source Range](/docs/guides/ingress/http/source-range.md) - - [Supports redirects/DNS resolution for `ExternalName` type service](/docs/guides/ingress/http/external-svc.md) - - [Expose HAProxy stats for Prometheus](/docs/guides/ingress/monitoring/stats-and-prometheus.md) + - [URL and Request Header Re-writing](/docs/guides/ingress/http/rewrite-rules.md) + - [Enable CORS](/docs/guides/ingress/http/cors.md) + - [Custom HTTP Port](/docs/guides/ingress/http/custom-http-port.md) + - [Using External Service as Ingress Backend](/docs/guides/ingress/http/external-svc.md) + - [HSTS](/docs/guides/ingress/http/hsts.md) + - [Forward Traffic to StatefulSet Pods](/docs/guides/ingress/http/statefulset-pod.md) + - [Configure Sticky session to Backends](/docs/guides/ingress/http/sticky-session.md) + - [Blue Green Deployments using weighted Loadbalancing](/docs/guides/ingress/http/weighted.md) +- TLS/SSL + - [TLS Termination](/docs/guides/ingress/tls/tls.md) + - [Backend TLS](/docs/guides/ingress/tls/backend-tls.md) - [Supports AWS certificate manager](/docs/guides/ingress/tls/aws-cert-manager.md) - - [Scale load balancer using HorizontalPodAutoscaling](/docs/guides/ingress/replicas-and-autoscaling.md) - - [Configure Custom Timeouts for HAProxy](/docs/guides/ingress/configuration/configure-timeouts.md) - - [Custom port for HTTP](/docs/guides/ingress/http/custom-http-port.md) +- TCP + - [TCP LoadBalancing](/docs/guides/ingress/tcp/tcp.md) +- Configuration + - [Customize generated HAProxy config via BackendRule](/docs/guides/ingress/configuration/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.) + - [Apply Frontend Rules](/docs/guides/ingress/configuration/frontend-rule.md) + - [Supported Annotations](/docs/guides/ingress/configuration/annotations.md) - [Specify NodePort](/docs/guides/ingress/configuration/node-port.md) - - [Backend TLS](/docs/guides/ingress/tls/backend-tls.md) - - [Configure Options](/docs/guides/ingress/configuration/configure-options.md) + - [Configure global options](/docs/guides/ingress/configuration/default-options.md) + - [Configure Custom Timeouts for HAProxy](/docs/guides/ingress/configuration/default-timeouts.md) - [Using Custom HAProxy Templates](/docs/guides/ingress/configuration/custom-templates.md) +- Security - [Configure Basic Auth for HTTP Backends](/docs/guides/ingress/security/basic-auth.md) - - [Configure Sticky session to Backends](/docs/guides/ingress/http/sticky-session.md) - - [Apply Frontend Rules](/docs/guides/ingress/configuration/frontend-rule.md) - - [Supported Annotations](/docs/guides/ingress/configuration/annotations.md#ingress-annotations) - -### Comparison with Kubernetes -| Feauture | Kube 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 on Canary Deployment| :x: | :white_check_mark: | -| Supports full Spectrum of HAProxy backend rules | :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: | - -## AppsCode Ingress Flow -Typically, services and pods have IPs only routable by the cluster network. All traffic that ends up at an -edge router is either dropped or forwarded elsewhere. An AppsCode Ingress is a collection of rules that allow -inbound connections to reach the app running in the cluster, and of course though it the applications are recongnized -via service the traffic will bypass service and go directly to pod. -AppsCode Ingress can also be configured to give services externally-reachable urls, load balance traffic, -terminate SSL, offer name based virtual hosting etc. - -This resource Type is backed by an controller called Voyager which monitors and manages the resources of AppsCode Ingress Kind. -Which is used for maintain and HAProxy backed loadbalancer to the cluster for open communications inside cluster -from internet via the loadbalancer.
-Even when a resource for AppsCode Ingress type is created, the controller will treat it as a new loadbalancer -request and will create a new loadbalancer, based on the configurations. - - -## Dive Into AppsCode Ingress -Multiple scenario can happen with loadbalancer. AppsCode Ingress intends to resolve all these scenario -for a high-availability loadbalancer, inside a kubernetes cluster. - -### The Endpoints are like: - -| VERB | ENDPOINT | ACTION | BODY -|---------|-------------------------------------------------------------|--------|------- -| GET | /apis/voyager.appscode.com/v1beta1/namespace/`ns`/ingresss | LIST | nil -| GET | /apis/voyager.appscode.com/v1beta1/namespace/`ns`/ingresss/`name` | GET | nil -| POST | /apis/voyager.appscode.com/v1beta1/namespace/`ns`/ingresss | CREATE | JSON -| PUT | /apis/voyager.appscode.com/v1beta1/namespace/`ns`/ingresss/`name` | UPDATE | JSON -| DELETE | /apis/voyager.appscode.com/v1beta1/namespace/`ns`/ingresss/`name` | DELETE | nil - -## Ingress Status -If an ingress is created as `ingress.appscode.com/type: LoadBalancer` the ingress status field will contain -the ip/host name for that LoadBalancer. For `HostPort` mode the ingress will open ports on the nodes selected to run HAProxy. - -### Configuration Options -Voyager operator allows customization of Ingress resource using annotation keys with `ingress.appscode.com/` prefix. -The ingress annotaiton keys are always string. Annotation values might have the following data types: - -| Value Type | Description | Example YAML | -|----------- |-------------|--------------| -| string | any valid string | 'v1'; "v2" | -| integer | any valid integer | '1'; "2" | -| bool | 1, t, T, TRUE, true, True considered _true_; everything else is considered _false_ | 'true' | -| array | json formatted array of string | '["v1", "v2"]' | -| map | json formatted string to string map | '{ "k1" : "v1", "k2": "v2" }' | -| enum | string which has a predefined set of valid values | 'E1'; "E2" | - -If you are using YAML to write your Ingress, you can use any valid YAML syntax, including multi-line string. Here is an example: -```yaml -annotations: - ingress.appscode.com/type: LoadBalancer - ingress.appscode.com/replicas: '2' - ingress.appscode.com/load-balancer-ip: '100.101.102.103' - ingress.appscode.com/stats: 'true' - ingress.appscode.com/stats-port: '2017' - ingress.appscode.com/stats-secret-name: my-secret - ingress.appscode.com/annotations-service: | - { - "service.beta.kubernetes.io/aws-load-balancer-backend-protocol": "http", - "service.beta.kubernetes.io/aws-load-balancer-proxy-protocol": "*", - "service.beta.kubernetes.io/aws-load-balancer-ssl-cert": "arn:aws:acm:..." - } -``` - -Below is the full list of supported annotation keys, [voyager also support standard ingress annotations](./configuration/annotations.md#ingress-annotations): - -| Keys | Value | Default | Description | -|--------|-----------|----------|--------------| -| ingress.appscode.com/type | LoadBalancer, HostPort, NodePort, Internal | LoadBalancer | `Required`. Indicates type of service used to expose HAProxy to the internet | -| ingress.appscode.com/replicas | integer | 1 | `Optional`. Indicates number of replicas of HAProxy pods | -| ingress.appscode.com/load-balancer-ip | string | x | `Optional`. For "gce", "gke", "azure", "acs" cloud provider, if this value is set to a valid IPv4 address, it will be assigned to loadbalancer used to expose HAProxy. The IP should be pre-allocated in cloud provider account but not assigned to the load-balancer. Usually this is set to a static IP to preserve DNS configuration | -| ingress.appscode.com/node-selector | map | x | Indicates which hosts are selected to run HAProxy pods. This is a recommended annotation for `HostPort` type ingress. | -| ingress.appscode.com/sticky-session | bool | false | `Optional`. Indicates the session affinity for the traffic. If set, session affinity will apply to all the rulses. | -| ingress.appscode.com/annotations-service | map | x | `Optional`. Annotaiotns applied to service used to expose HAProxy | -| ingress.appscode.com/annotations-pod | map | x | `Optional`. Annotations applied to pods used to run HAProxy | -| ingress.appscode.com/keep-source-ip | bool | false | `Optional`. If set, preserves source IP for `LoadBalancer` type ingresses. The actual configuration generated depends on the underlying cloud provider. For gce, gke, azure: Adds annotation `service.beta.kubernetes.io/external-traffic: OnlyLocal` to services used to expose HAProxy. For aws, enforces the use of the PROXY protocol. | -| ingress.appscode.com/accept-proxy | bool | false | `Optional`. If set, enforces the use of the PROXY protocol. | -| ingress.appscode.com/stats | bool | false | `Optional`. If set, HAProxy stats will be exposed | -| ingress.appscode.com/stats-port | integer | 56789 | `Optional`. Port used to expose HAProxy stats | -| ingress.appscode.com/stats-secret-name | string | x | `Optional`. Secret used to provide username & password to secure HAProxy stats endpoint. Secret must contain keys `username` and `password` | -| ingress.appscode.com/stats-service-name | string | `voyager--stats` | ClusterIP type service used to expose HAproxy stats. This allows to avoid exposing stats to internet. | -| ingress.appscode.com/ip | | | Removed since 1.5.6. Use `ingress.appscode.com/load-balancer-ip` | -| ingress.appscode.com/persist | | | Removed since 1.5.6. | -| ingress.appscode.com/daemon.nodeSelector | | | Removed since 1.5.6. Use `ingress.appscode.com/node-selector` | -| ingress.appscode.com/stickySession | | | Removed since 1.5.6. Use `ingress.appscode.com/sticky-session` | -| ingress.appscode.com/annotationsService | | | Removed since 1.5.6. Use `ingress.appscode.com/annotations-service` | -| ingress.appscode.com/annotationsPod | | | Removed since 1.5.6. Use `ingress.appscode.com/annotations-pod` | -| ingress.appscode.com/statsSecretName | | | Removed since 1.5.6. Use `ingress.appscode.com/stats-secret-name` | - -**Following annotations for ingress are not modifiable. The configuration is applied only when an Ingress object is created. -If you need to update these annotations, then first delete the Ingress and then recreate.** -``` -ingress.appscode.com/type -ingress.appscode.com/node-selector -ingress.appscode.com/load-balaner-ip -``` -The issue is being [tracked here.](https://github.com/appscode/voyager/issues/143) - -## Next Reading -- [Single Service example](./http/single-service.md) -- [Simple Fanout](./http/simple-fanout.md) -- [Virtual Hosting](./http/named-virtual-hosting.md) -- [URL and Header Rewriting](./http/header-rewrite.md) -- [TCP Loadbalancing](./tcp/tcp.md) -- [TLS Termination](./tls/tls.md) -- [Route Traffic to StatefulSet Pods Based on Host Name](./http/statefulset-pod.md) -- [Weighted Loadbalancing on Canary Deployment](./http/weighted.md) -- [Supports full HAProxy Spectrum via BackendRule](./configuration/backend-rule.md) -- [Add Custom Annotation to LoadBalancer Service and Pods](./configuration/annotations.md) -- [Supports Loadbalancer Source Range](./http/source-range.md) -- [Supports redirects/DNS resolve for `ServiceTypeExternalName`](./http/external-svc.md) -- [Expose HAProxy stats and metrics, use prometheus with metrics](./monitoring/stats-and-prometheus.md) - -## Example -Check out examples for [complex ingress configurations](../../../hack/example/ingress.yaml). -This example generates to a HAProxy Configuration like [this](../../../hack/example/haproxy_generated.cfg). - -## Other CURD Operations -Applying other operation like update, delete to AppsCode Ingress is regular kubernetes resource operation. + - [TLS Authentication](/docs/guides/ingress/security/tls-auth.md) +- Monitoring + - [Exposing HAProxy Stats](/docs/guides/ingress/monitoring/stats.md) +- [Scaling Ingress](/docs/guides/ingress/scaling.md) +- [Placement of Ingress Pods](/docs/guides/ingress/pod-placement.md) diff --git a/docs/guides/ingress/_index.md b/docs/guides/ingress/_index.md index c0cdc1dad..f985c1b45 100644 --- a/docs/guides/ingress/_index.md +++ b/docs/guides/ingress/_index.md @@ -2,7 +2,7 @@ title: Ingress menu: product_voyager_5.0.0-rc.10: - identifier: ingress + identifier: ingress-guides name: Ingress parent: guides weight: 100 diff --git a/docs/guides/ingress/configuration/_index.md b/docs/guides/ingress/configuration/_index.md index efe03afa5..eb7a0bad3 100644 --- a/docs/guides/ingress/configuration/_index.md +++ b/docs/guides/ingress/configuration/_index.md @@ -2,9 +2,9 @@ title: Configuration menu: product_voyager_5.0.0-rc.10: - identifier: configuration + identifier: config-ingress name: Configuration - parent: ingress - weight: 20 + parent: ingress-guides + weight: 25 menu_name: product_voyager_5.0.0-rc.10 --- diff --git a/docs/guides/ingress/configuration/annotations.md b/docs/guides/ingress/configuration/annotations.md index 2a3713ecb..f9654f304 100644 --- a/docs/guides/ingress/configuration/annotations.md +++ b/docs/guides/ingress/configuration/annotations.md @@ -1,18 +1,18 @@ --- -title: Annotations +title: Supported Annotations | Kubernetes Ingress menu: product_voyager_5.0.0-rc.10: + identifier: annotation-config name: Annotations - parent: configuration - weight: 10 + parent: config-ingress + weight: 20 product_name: voyager menu_name: product_voyager_5.0.0-rc.10 section_menu_id: guides -aliases: - - /products/voyager/5.0.0-rc.10/guides/ingress/configuration/ --- -# Configuration Options +# Supported Annotations + Voyager operator allows customization of Ingress resource using annotation keys with `ingress.appscode.com/` prefix. The ingress annotaiton keys are always string. Annotation values might have the following data types: @@ -26,6 +26,7 @@ The ingress annotaiton keys are always string. Annotation values might have the | enum | string which has a predefined set of valid values | 'E1'; "E2" | If you are using YAML to write your Ingress, you can use any valid YAML syntax, including multi-line string. Here is an example: + ```yaml annotations: ingress.appscode.com/type: LoadBalancer @@ -69,6 +70,7 @@ Below is the full list of supported annotation keys, [voyager also support stand **Following annotations for ingress are not modifiable. The configuration is applied only when an Ingress object is created. If you need to update these annotations, then first delete the Ingress and then recreate.** + ``` ingress.appscode.com/type ingress.appscode.com/node-selector @@ -85,6 +87,7 @@ set via two ingress options. Json encoded annotations map that will be applied to LoadBalancer service. ie. + ``` ingress.appscode.com/annotations-service = {"foo": "bar", "service-annotation": "set"} ``` @@ -95,6 +98,7 @@ This will add the `foo:bar` and `service-annotation:set` to the Service annotati Json encoded annotations map that will be applied to LoadBalancer pods. ie. + ``` ingress.appscode.com/annotations-pod = {"foo": "bar", "pod-annotation": "set"} ``` @@ -144,8 +148,8 @@ can be applied on ingress or backends. | annotations-service | [Add Custom Annotation to LoadBalancer Service](annotations.md)| ingress | | annotations-pod | [Add Custom Annotation to LoadBalancer Pods](annotations.md) | ingress | | accept-proxy | Accept proxy protocol | ingress | -| default-timeout | [Configure Custom Timeouts for HAProxy](configure-timeouts.md) | ingress | -| default-option | [Configure Options for HAProxy](configure-options.md) | ingress | +| default-timeout | [Configure Custom Timeouts for HAProxy](default-timeouts.md) | ingress | +| default-option | [Configure Options for HAProxy](default-options.md) | ingress | | backend-tls | [TLS enabled Backend](backend-tls.md) | service, ingress | | sticky-session (deprecated) | [Configure Sticky session to Backends](sticky-session.md) | service, ingress | | use-dns-resolver | [Supports redirects/DNS resolution for `ExternalName` type service](external-svc.md) | ingress | @@ -154,15 +158,15 @@ can be applied on ingress or backends. | dns-resolver-retries | [Supports redirects/DNS resolution for `ExternalName` type service](external-svc.md) | ingress| | dns-resolver-timeout | [Supports redirects/DNS resolution for `ExternalName` type service](external-svc.md) |ingress| | dns-resolver-hold | [Supports redirects/DNS resolution for `ExternalName` type service](external-svc.md)|ingress| -| stats | [Expose HAProxy stats](stats-and-prometheus.md) | ingress | -| stats-port | [Expose HAProxy stats](stats-and-prometheus.md) | ingress | -| stats-secret-name | [Expose HAProxy stats](stats-and-prometheus.md) | ingress | -| stats-service-name | [Expose HAProxy stats](stats-and-prometheus.md) | ingress | -| monitoring-agent | [Expose HAProxy stats using prometheus](stats-and-prometheus.md#using-prometheus) | ingress | -| service-monitor-labels |[Expose HAProxy stats using prometheus](stats-and-prometheus.md#using-prometheus) | ingress | -| service-monitor-namespace|[Expose HAProxy stats using prometheus](stats-and-prometheus.md#using-prometheus) | ingress | -| service-monitor-endpoint-port|[Expose HAProxy stats using prometheus](stats-and-prometheus.md#using-prometheus) | ingress | -| service-monitor-endpoint-scrape-interval |[Expose HAProxy stats using prometheus](stats-and-prometheus.md#using-prometheus) | ingress | +| stats | [Expose HAProxy stats](stats.md) | ingress | +| stats-port | [Expose HAProxy stats](stats.md) | ingress | +| stats-secret-name | [Expose HAProxy stats](stats.md) | ingress | +| stats-service-name | [Expose HAProxy stats](stats.md) | ingress | +| monitoring-agent | [Expose HAProxy stats using prometheus](stats.md#using-prometheus) | ingress | +| service-monitor-labels |[Expose HAProxy stats using prometheus](stats.md#using-prometheus) | ingress | +| service-monitor-namespace|[Expose HAProxy stats using prometheus](stats.md#using-prometheus) | ingress | +| service-monitor-endpoint-port|[Expose HAProxy stats using prometheus](stats.md#using-prometheus) | ingress | +| service-monitor-endpoint-scrape-interval |[Expose HAProxy stats using prometheus](stats.md#using-prometheus) | ingress | ## Acknowledgements diff --git a/docs/guides/ingress/configuration/backend-rule.md b/docs/guides/ingress/configuration/backend-rule.md index 69f924204..a99d6fef7 100644 --- a/docs/guides/ingress/configuration/backend-rule.md +++ b/docs/guides/ingress/configuration/backend-rule.md @@ -1,16 +1,18 @@ --- -title: Backend Rule +title: Backend Rules | Kubernetes Ingress menu: product_voyager_5.0.0-rc.10: + identifier: backend-config name: Backend Rule - parent: configuration - weight: 20 + parent: config-ingress + weight: 10 product_name: voyager menu_name: product_voyager_5.0.0-rc.10 section_menu_id: guides --- -### BackendRule +# Backend Rules + Voyager supports full spectrum of HAProxy backend rules via `backendRule`. Read [more](https://cbonte.github.io/haproxy-dconv/1.7/configuration.html) about HAProxy backend rules. diff --git a/docs/guides/ingress/configuration/custom-templates.md b/docs/guides/ingress/configuration/custom-templates.md index 6e29591ef..f6c778511 100644 --- a/docs/guides/ingress/configuration/custom-templates.md +++ b/docs/guides/ingress/configuration/custom-templates.md @@ -1,15 +1,16 @@ --- +title: Using Custom HAProxy Templates | Kubernetes Ingress menu: product_voyager_5.0.0-rc.10: + identifier: custom-tpl-config name: Custom Templates - parent: configuration - weight: 55 + parent: config-ingress + weight: 40 product_name: voyager menu_name: product_voyager_5.0.0-rc.10 section_menu_id: guides --- - # Using Custom HAProxy Templates Since 3.2.0, Voyager can use custom templates provided by users to render HAProxy configuration. Voyager comes with a set of GO [text/templates](https://golang.org/pkg/text/template/) found [here](/hack/docker/voyager/templates). These templates are mounted at `/srv/voyager/templates`. You can mount a ConfigMap with matching template names when installing Voyager operator to a different location and pass that to Voyager operator using `--custom-templates` flag. Voyager will [load](https://github.com/appscode/voyager/blob/3ae30cd023ff8fa6301d2656bf9fbc5765529691/pkg/haproxy/template.go#L40) the built-in templates first and then load any custom templates if provided. As long as the custom templates have [same name](https://golang.org/pkg/text/template/#Template.ParseGlob) as the built-in templates, custom templates will be used render HAProxy config. You can overwrite any number of templates as you wish. Also note that templates are loaded when Voyager operator starts. So, if you want to reload custom templates, you need to restart the running Voyager operator pod (not HAProxy pods). @@ -42,6 +43,7 @@ defaults ``` Now create a ConfigMap using the defaults.cfg as key and the file content as the value. + ```console $ kubectl create configmap -n kube-system voyager-templates --from-file=/tmp/defaults.cfg ``` diff --git a/docs/guides/ingress/configuration/configure-options.md b/docs/guides/ingress/configuration/default-options.md similarity index 58% rename from docs/guides/ingress/configuration/configure-options.md rename to docs/guides/ingress/configuration/default-options.md index bf1fed29e..7aa86e6bc 100644 --- a/docs/guides/ingress/configuration/configure-options.md +++ b/docs/guides/ingress/configuration/default-options.md @@ -1,22 +1,24 @@ --- -title: Configure Options +title: Default HAProxy Options | Kubernetes Ingress menu: product_voyager_5.0.0-rc.10: - name: Configure Options - parent: configuration - weight: 35 + identifier: options-config + name: HAProxy Options + parent: config-ingress + weight: 30 product_name: voyager menu_name: product_voyager_5.0.0-rc.10 section_menu_id: guides --- +# Default HAProxy Options + +Voyager Supports all valid options for [defaults section of HAProxy config](https://cbonte.github.io/haproxy-dconv/1.7/configuration.html#4.2-option%20abortonclose). You can provide these options using a json encoded map in Ingress annotaiotns liek below: + +`ingress.appscode.com/default-option: '{"http-keep-alive": "true", "dontlognull": "true", "clitcpka": "false"}'` + +This will be appended in the defaults section of HAProxy as: -Voyager Supports all valid options for defaults section of HAProxy config -https://cbonte.github.io/haproxy-dconv/1.7/configuration.html#4.2-option%20abortonclose -from the list from here -expects a json encoded map -ie: "ingress.appscode.com/default-option": {"http-keep-alive": "true", "dontlognull": "true", "clitcpka": "false"} -This will be appended in the defaults section of HAProxy as ``` option http-keep-alive option dontlognull @@ -24,6 +26,7 @@ no option clitcpka ``` Ingress Example: + ```yaml apiVersion: voyager.appscode.com/v1beta1 kind: Ingress diff --git a/docs/guides/ingress/configuration/configure-timeouts.md b/docs/guides/ingress/configuration/default-timeouts.md similarity index 93% rename from docs/guides/ingress/configuration/configure-timeouts.md rename to docs/guides/ingress/configuration/default-timeouts.md index 0ebf69006..4d6cfc488 100644 --- a/docs/guides/ingress/configuration/configure-timeouts.md +++ b/docs/guides/ingress/configuration/default-timeouts.md @@ -1,14 +1,17 @@ --- +title: Customize Ingress Timeouts | Kubernetes Ingress menu: product_voyager_5.0.0-rc.10: + identifier: custom-timeouts-config name: Configure Timeouts - parent: configuration - weight: 40 + parent: config-ingress + weight: 35 product_name: voyager menu_name: product_voyager_5.0.0-rc.10 section_menu_id: guides --- +# Customize Timeouts Custom timeouts can be configured for HAProxy via annotations. Supports all valid timeout option for defaults section of HAProxy. [Read More](https://cbonte.github.io/haproxy-dconv/1.7/configuration.html#4.2-timeout%20check) diff --git a/docs/guides/ingress/configuration/frontend-rule.md b/docs/guides/ingress/configuration/frontend-rule.md index deee4b756..f7cb66970 100644 --- a/docs/guides/ingress/configuration/frontend-rule.md +++ b/docs/guides/ingress/configuration/frontend-rule.md @@ -1,21 +1,22 @@ --- +title: Frontend Ingress Rules| Voyager menu: product_voyager_5.0.0-rc.10: + identifier: frontend-rule-config name: Frontend Rule - parent: configuration - weight: 65 + parent: config-ingress + weight: 15 product_name: voyager menu_name: product_voyager_5.0.0-rc.10 section_menu_id: guides --- +# Frontend Rules -## Frontend Rules Frontend rules specify a set of rules that are applied to HAProxy frontend configuration. The set of keywords are from here https://cbonte.github.io/haproxy-dconv/1.7/configuration.html#4.1. Only frontend sections can be applied here. **It is up to user to provide valid sets of rules**. -This allows acls or other options in frontend sections in HAProxy config. -Frontend rules will be mapped to `spec.rules` according to HAProxy port. +This allows acls or other options in frontend sections in HAProxy config. Frontend rules will be mapped to `spec.rules` according to HAProxy port. ```yaml @@ -99,6 +100,7 @@ spec: ### Why does not IP whitelisting work in LoadBalancer type Ingress in AWS? From [HAProxy official documentation](https://cbonte.github.io/haproxy-dconv/1.7/configuration.html#5.1-accept-proxy): + ``` The PROXY protocol dictates the layer 3/4 addresses of the incoming connection to be used everywhere an address is used, with the only exception of diff --git a/docs/guides/ingress/configuration/node-port.md b/docs/guides/ingress/configuration/node-port.md index 7096cf18d..15ee408db 100644 --- a/docs/guides/ingress/configuration/node-port.md +++ b/docs/guides/ingress/configuration/node-port.md @@ -1,16 +1,17 @@ --- +title: Specify Ingress NodePort | Kubernetes Ingress menu: product_voyager_5.0.0-rc.10: - name: Node Port - parent: configuration - weight: 90 + identifier: nodeport-config + name: Specify NodePort + parent: config-ingress + weight: 25 product_name: voyager menu_name: product_voyager_5.0.0-rc.10 section_menu_id: guides --- - -## Specify NodePort +# Specify NodePort If you are using a `NodePort` or `LoadBalancer` type Ingress, a `NodePort` or `LoadBalancer` type Service is used to expose HAProxy pods respectively. If no node port is specified for each HAProxy Service port, Kubernetes will randomly assign one for you. @@ -108,23 +109,23 @@ $ kubectl get configmap voyager-test-ingress -o yaml # Generated HAProxy config snippet frontend http-8989 - bind *:8989 + bind *:8989 mode http option httplog option forwardfor - + acl host_acl_test-server.default:80-t3bu6y hdr(host) -i one.example.com:32666 acl url_acl_test-server.default:80-t3bu6y path_beg /t1 use_backend test-server.default:80-t3bu6y if host_acl_test-server.default:80-t3bu6y url_acl_test-server.default:80-t3bu6y - + acl host_acl_test-server.default:80-s46phe hdr(host) -i one.example.com:32666 acl url_acl_test-server.default:80-s46phe path_beg /t2 use_backend test-server.default:80-s46phe if host_acl_test-server.default:80-s46phe url_acl_test-server.default:80-s46phe - + acl host_acl_test-server.default:80-iv3d2y hdr(host) -i other.example.com:32666 - + use_backend test-server.default:80-iv3d2y if host_acl_test-server.default:80-iv3d2y - + backend test-server.default:80-t3bu6y server pod-172.17.0.5 172.17.0.5:8080 diff --git a/docs/guides/ingress/http/_index.md b/docs/guides/ingress/http/_index.md index c56c22f51..62bf86d6f 100644 --- a/docs/guides/ingress/http/_index.md +++ b/docs/guides/ingress/http/_index.md @@ -2,9 +2,9 @@ title: HTTP menu: product_voyager_5.0.0-rc.10: - identifier: http + identifier: http-ingress name: HTTP - parent: ingress - weight: 40 + parent: ingress-guides + weight: 10 menu_name: product_voyager_5.0.0-rc.10 --- diff --git a/docs/guides/ingress/http/weighted.md b/docs/guides/ingress/http/blue-green-deployment.md similarity index 87% rename from docs/guides/ingress/http/weighted.md rename to docs/guides/ingress/http/blue-green-deployment.md index ebad442c4..b90b0c8c9 100644 --- a/docs/guides/ingress/http/weighted.md +++ b/docs/guides/ingress/http/blue-green-deployment.md @@ -1,19 +1,19 @@ --- +title: Blue Green Deployments | Kubernetes Ingress menu: product_voyager_5.0.0-rc.10: - name: Weighted - parent: http - weight: 140 + identifier: blue-green-http + name: Blue Green Deployment + parent: http-ingress + weight: 60 product_name: voyager menu_name: product_voyager_5.0.0-rc.10 section_menu_id: guides --- +# Blue Green Deployments -## Weighted Loadbalancing -`Voayger` supports weighted loadbalancing on canary deployments. - -Following example illustrates an weighted loadbalance scenario. +Voayger supports Blue Green deployments using weighted loadbalancing for backend pods. Following example illustrates a weighted loadbalance scenario. ```yaml apiVersion: extensions/v1beta1 @@ -89,7 +89,6 @@ spec: - containerPort: 8080 name: http-1 protocol: TCP - ``` Two different workload with the annotation `ingress.appscode.com/backend-weight` and one single service pointing to them @@ -111,6 +110,7 @@ spec: ``` The following ingress will forward 90% traffic to `deployment-1` and 10% to `deployment-2` + ```yml apiVersion: voyager.appscode.com/v1beta1 kind: Ingress diff --git a/docs/guides/ingress/http/cors.md b/docs/guides/ingress/http/cors.md index 2567f5c18..1c4ec86a9 100644 --- a/docs/guides/ingress/http/cors.md +++ b/docs/guides/ingress/http/cors.md @@ -1,17 +1,18 @@ --- +title: CORS | Kubernetes Ingress menu: product_voyager_5.0.0-rc.10: + identifier: cors-http name: CORS - parent: http - weight: 45 + parent: http-ingress + weight: 30 product_name: voyager menu_name: product_voyager_5.0.0-rc.10 section_menu_id: guides - - /products/voyager/5.0.0-rc.10/guides/ingress/http/ --- +# CORS -## Enable CORS Applying `ingress.kubenretes.io/enable-cors` annotation in ingress enables CORS for all HTTP Frontend. ```yaml @@ -39,6 +40,7 @@ spec: ``` Applying the annotation in ingress will have the following effects, will add the CORS Header in the response. + ``` $ curl -v -X 'GET' -k -H 'Origin: foo.bar.com' 'http://foo.bar.com' HTTP/1.1 200 OK diff --git a/docs/guides/ingress/http/custom-http-port.md b/docs/guides/ingress/http/custom-http-port.md index 2041ec594..6bce76222 100644 --- a/docs/guides/ingress/http/custom-http-port.md +++ b/docs/guides/ingress/http/custom-http-port.md @@ -1,17 +1,18 @@ --- +title: Custom HTTP Port | Kubernetes Ingress menu: product_voyager_5.0.0-rc.10: + identifier: custom-port-http name: Custom HTTP Port - parent: http - weight: 50 + parent: http-ingress + weight: 35 product_name: voyager menu_name: product_voyager_5.0.0-rc.10 section_menu_id: guides --- +# Custom HTTP Port - -## Custom HTTP Port Voyager 3.2+ supports using any non-standard port (beyond 80 and 443) for L7 traffic. If no port is specified, port 80 or 443 will be used depending on whether TLS is used or not. ```yaml diff --git a/docs/guides/ingress/http/external-svc.md b/docs/guides/ingress/http/external-svc.md index 86a844178..049d5a818 100644 --- a/docs/guides/ingress/http/external-svc.md +++ b/docs/guides/ingress/http/external-svc.md @@ -1,9 +1,11 @@ --- +title: Using External Service as Ingress Backend | Kubernetes Ingress menu: product_voyager_5.0.0-rc.10: + identifier: external-svc-backend-http name: External SVC - parent: http - weight: 60 + parent: http-ingress + weight: 40 product_name: voyager menu_name: product_voyager_5.0.0-rc.10 section_menu_id: guides @@ -128,6 +130,7 @@ backend: ``` The generated redirect line in HAProxy config: + ``` http-request redirect location http[s]://{{e.ExternalName}}:{{ e.Port }} code 301 ``` diff --git a/docs/guides/ingress/http/hsts.md b/docs/guides/ingress/http/hsts.md index 7f1530a11..1b62bc246 100644 --- a/docs/guides/ingress/http/hsts.md +++ b/docs/guides/ingress/http/hsts.md @@ -1,19 +1,19 @@ --- +title: HSTS | Kubernetes Ingress menu: product_voyager_5.0.0-rc.10: + identifier: hsts-http name: HSTS - parent: http - weight: 75 + parent: http-ingress + weight: 45 product_name: voyager menu_name: product_voyager_5.0.0-rc.10 section_menu_id: guides --- +# HSTS -## HSTS -HTTP Strict Transport Security (HSTS) is a web security policy mechanism which helps to protect -websites against protocol downgrade attacks and cookie hijacking. It allows web servers to -declare that web browsers (or other complying user agents) should only interact with it using secure +HTTP Strict Transport Security (HSTS) is a web security policy mechanism which helps to protect websites against protocol downgrade attacks and cookie hijacking. It allows web servers to declare that web browsers (or other complying user agents) should only interact with it using secure HTTPS connections, and never via the insecure HTTP protocol. HSTS is an IETF standards track protocol and is specified in RFC 6797. The HSTS Policy is communicated by the server to the user agent via an HTTPS response header field named "Strict-Transport-Security". @@ -47,6 +47,7 @@ spec: ``` Applying the annotation in ingress will have the following effects, will add the HSTS Header in the response. + ```console $ curl -v -X 'GET' -k 'http://foo.bar.com' Strict-Transport-Security: max-age=100; includeSubDomains; preload diff --git a/docs/guides/ingress/http/header-rewrite.md b/docs/guides/ingress/http/rewrite-rules.md similarity index 84% rename from docs/guides/ingress/http/header-rewrite.md rename to docs/guides/ingress/http/rewrite-rules.md index 1bdce060b..e1f971203 100644 --- a/docs/guides/ingress/http/header-rewrite.md +++ b/docs/guides/ingress/http/rewrite-rules.md @@ -1,19 +1,21 @@ --- +title: Header and URL Rewriting | Voayger menu: product_voyager_5.0.0-rc.10: - name: Header Rewrite - parent: http - weight: 70 + identifier: rewrite-http + name: Rewrite Support + parent: http-ingress + weight: 25 product_name: voyager menu_name: product_voyager_5.0.0-rc.10 section_menu_id: guides --- +# Header and URL Rewriting -### Header and URL Rewriting AppsCode Ingress support header and URL modification at the loadbalancer level. To ensure simplicity, -the header and rewrite rules follow the HAProxy syntax as it is. -To add some rewrite rules in a http rule, the syntax is: +the header and rewrite rules follow the HAProxy syntax as it is. To add some rewrite rules for a HTTP path, follow the example below: + ```yaml apiVersion: voyager.appscode.com/v1beta1 kind: Ingress @@ -40,7 +42,3 @@ the base URL the load balancer received the requests. The rules specified in `rewriteRule` are used to modify the request url including the host. Current example will add an `/testings` prefix in every request URI before forwarding it to backend. - -## Next Reading -- [TCP Loadbalancing](../tcp/tcp.md) -- [TLS Termination](../tls/tls.md) diff --git a/docs/guides/ingress/http/simple-fanout.md b/docs/guides/ingress/http/simple-fanout.md deleted file mode 100644 index 816f17495..000000000 --- a/docs/guides/ingress/http/simple-fanout.md +++ /dev/null @@ -1,81 +0,0 @@ ---- -menu: - product_voyager_5.0.0-rc.10: - name: Simple Fanout - parent: http - weight: 100 -product_name: voyager -menu_name: product_voyager_5.0.0-rc.10 -section_menu_id: guides ---- - -### Simple Fanout -As described previously, pods within kubernetes have ips only visible on the cluster network. So, we need -something at the edge accepting ingress traffic and proxy-ing it to right endpoints. This component -is usually a highly available loadbalancer(s). An Ingress allows you to keep number of loadbalancers -down to a minimum, for example, a setup can be like: - - -``` -foo.bar.com -> load balancer -> / foo s1:80 - / bar s2:80 -``` - -would require an Ingress such as: -```yaml -apiVersion: voyager.appscode.com/v1beta1 -kind: Ingress -metadata: - name: test-ingress - namespace: default -spec: - rules: - - host: appscode.example.com - http: - paths: - - path: "/foo" - backend: - serviceName: s1 - servicePort: '80' - - path: "/bar" - backend: - serviceName: s2 - servicePort: '80' -``` -The Ingress controller will provision an implementation specific loadbalancer that satisfies the Ingress, -as long as the services (s1, s2) exist. When it has done so, you will see the address of the loadbalancer under -the Status of Ingress. - -In Voyager, **the order of rules and paths is important** as Voyager will use them in the order provided by user, instead of automatically reordering them. So, to add a catch-all service for all other paths, you can add a `/` path to the end. -```yaml -apiVersion: voyager.appscode.com/v1beta1 -kind: Ingress -metadata: - name: test-ingress - namespace: default -spec: - rules: - - host: appscode.example.com - http: - paths: - - path: "/foo" - backend: - serviceName: s1 - servicePort: '80' - - path: "/bar" - backend: - serviceName: s2 - servicePort: '80' - - path: "/" - backend: - serviceName: catch-all - servicePort: '80' -``` - - -## Next Reading -- [Virtual Hosting](named-virtual-hosting.md) -- [URL and Header Rewriting](header-rewrite.md) -- [TCP Loadbalancing](../tcp/tcp.md) -- [TLS Termination](../tls/tls.md) -- [Configure Custom Timeouts for HAProxy](../configuration/configure-timeouts.md) diff --git a/docs/guides/ingress/http/single-service.md b/docs/guides/ingress/http/single-service.md index 0c2a29207..61ad6d889 100644 --- a/docs/guides/ingress/http/single-service.md +++ b/docs/guides/ingress/http/single-service.md @@ -1,16 +1,18 @@ --- +title: Exposing Service | Kubernetes Ingress menu: product_voyager_5.0.0-rc.10: + identifier: single-svc-http name: Single Service - parent: http - weight: 105 + parent: http-ingress + weight: 10 product_name: voyager menu_name: product_voyager_5.0.0-rc.10 section_menu_id: guides --- +# Exposing Service via Ingress -### Single Service Ingress There are existing Kubernetes concepts which allows you to expose a single service. However, you can do so through an AppsCode Ingress as well, simply by specifying a default backend with no rules. @@ -62,6 +64,3 @@ This Ingress will forward traffic to `test-service` if request comes from the ho Other requests will be forwarded to default backend. Default Backend also supports `headerRule` and `rewriteRule`. - -## Next Reading -- [Simple Fanout](simple-fanout.md) \ No newline at end of file diff --git a/docs/guides/ingress/http/source-range.md b/docs/guides/ingress/http/source-range.md index c24cb2f42..94f912bd8 100644 --- a/docs/guides/ingress/http/source-range.md +++ b/docs/guides/ingress/http/source-range.md @@ -1,16 +1,17 @@ --- +title: Loadbalancer Source Range | Kubernetes Ingress menu: product_voyager_5.0.0-rc.10: name: Source Range - parent: http - weight: 110 + parent: http-ingress + weight: 20 product_name: voyager menu_name: product_voyager_5.0.0-rc.10 section_menu_id: guides --- +# Loadbalancer Source Range -## Loadbalancer Source Range When using an Ingress with `ingress.appscode.com/type: LoadBalancer` annotation, you can specify the IP ranges that are allowed to access the load balancer by using `spec.loadBalancerSourceRanges`. This field takes a list of IP CIDR ranges, which will be forwarded to Kubernetes, that will use to @@ -41,7 +42,8 @@ spec: In the following example, a load balancer will be created that is only accessible to clients with IP addresses from 130.211.204.1 and 130.211.204.2. -``` + +```yaml apiVersion: voyager.appscode.com/v1beta1 kind: Ingress metadata: diff --git a/docs/guides/ingress/http/statefulset-pod.md b/docs/guides/ingress/http/statefulset-pod.md index 0b666cab5..cf3b6f52a 100644 --- a/docs/guides/ingress/http/statefulset-pod.md +++ b/docs/guides/ingress/http/statefulset-pod.md @@ -1,18 +1,22 @@ --- +title: Forward Traffic to StatefulSet Pods | Kubernetes Ingress menu: product_voyager_5.0.0-rc.10: + identifier: statefulset-http name: Statefulset Pod - parent: http - weight: 115 + parent: http-ingress + weight: 50 product_name: voyager menu_name: product_voyager_5.0.0-rc.10 section_menu_id: guides --- +# Forward Traffic to StatefulSet -### Forward Traffic to StatefulSet -There is the regular way to forward traffic to StatefulSet. Create a service with the pods label selector as -selector, and use the service name as Backend ServiceName. By following: +## Forward Traffic to all Pods of a StatefulSet + +There is the usual way of forwarding traffic to a Service matching a StatefulSet. Create a Service with the pods label selector as +selector, and use the service name as Backend ServiceName. ```yaml apiVersion: apps/v1beta1 @@ -50,6 +54,7 @@ spec: ``` Create another service for StatefulSets pods with selector. + ```yaml apiVersion: v1 kind: Service @@ -67,6 +72,7 @@ spec: ``` And Use the service in the ingress Backend service name, as: + ```yaml backend: serviceName: nginx-service @@ -76,9 +82,8 @@ backend: That will forward traffic to your StatefulSets Pods. -#### Forward Traffic to specific Pods of a StatefulSet -There is a way to send traffic to all or specific pod of a StatefulSet using voyager. You can set -`hostNames` field in `Backend`, traffic will only forwarded to those pods. +## Forward Traffic to specific Pods of a StatefulSet +There is a way to send traffic to all or specific pod of a StatefulSet using voyager. You can set `hostNames` field in `Backend`, traffic will only forwarded to those pods. For Example the above StatefulSet will create two pod. ``` diff --git a/docs/guides/ingress/http/sticky-session.md b/docs/guides/ingress/http/sticky-session.md index 29b9d2c53..8d71cfb30 100644 --- a/docs/guides/ingress/http/sticky-session.md +++ b/docs/guides/ingress/http/sticky-session.md @@ -1,23 +1,26 @@ --- +title: Sticky Session | Kubernetes Ingress menu: product_voyager_5.0.0-rc.10: + identifier: sticky-http name: Sticky Session - parent: http - weight: 125 + parent: http-ingress + weight: 55 product_name: voyager menu_name: product_voyager_5.0.0-rc.10 section_menu_id: guides --- # Sticky Session + Voyager 3.2.0+ can configure [sticky connections](https://www.haproxy.com/blog/load-balancing-affinity-persistence-sticky-sessions-what-you-need-to-know/) in 2 modes. By applying annotation to an Ingress resource, you can configure all backends in that ingress to use sticky session. Or you can apply annotation to a service and configure backends using that service to use sticky session. `ingress.appscode.com/sticky-session` annotations is deprecated in voyager 4.0.0+. Use `ingress.kubernetes.io/affinity` instead. ### Sticky Ingress -Applying annotation `ingress.kubernetes.io/affinity` to Ingress will configure all backends to -support sticky session. +Applying annotation `ingress.kubernetes.io/affinity` to Ingress will configure all backends to support sticky session. + ```yaml apiVersion: voyager.appscode.com/v1beta1 kind: Ingress diff --git a/docs/guides/ingress/http/named-virtual-hosting.md b/docs/guides/ingress/http/virtual-hosting.md similarity index 61% rename from docs/guides/ingress/http/named-virtual-hosting.md rename to docs/guides/ingress/http/virtual-hosting.md index b6aadb04f..52ef364a7 100644 --- a/docs/guides/ingress/http/named-virtual-hosting.md +++ b/docs/guides/ingress/http/virtual-hosting.md @@ -1,16 +1,20 @@ --- +title: Virtual Hosting | Kubernetes Ingress menu: product_voyager_5.0.0-rc.10: - name: Named Virtual Hosting - parent: http - weight: 85 + identifier: virtual-hosting-http + name: Virtual Hosting + parent: http-ingress + weight: 15 product_name: voyager menu_name: product_voyager_5.0.0-rc.10 section_menu_id: guides --- +# Virtual Hosting + +## Hostname based Routing -### Name based virtual hosting Name-based virtual hosts use multiple host names for the same IP address. ``` @@ -46,7 +50,7 @@ spec: If the `host` field is set to `*.bar.com`, Ingress will forward traffic for any subdomain of `bar.com`. so `foo.bar.com` or `test.bar.com` will forward traffic to the desired backends. -### Cross Namespace traffic routing +## Cross Namespace traffic routing If your ingress in namespace `foo` and your application is in namespace `bar` you can still forward traffic. ```yaml @@ -65,8 +69,37 @@ spec: servicePort: '80' ``` +## Path based Routing + +A setup can be like: + +``` +foo.bar.com -> load balancer -> / foo s1:80 + / bar s2:80 +``` + +would require an Ingress such as: + +```yaml +apiVersion: voyager.appscode.com/v1beta1 +kind: Ingress +metadata: + name: test-ingress + namespace: default +spec: + rules: + - host: appscode.example.com + http: + paths: + - path: "/foo" + backend: + serviceName: s1 + servicePort: '80' + - path: "/bar" + backend: + serviceName: s2 + servicePort: '80' +``` -## Next Reading -- [URL and Header Rewriting](header-rewrite.md) -- [TCP Loadbalancing](../tcp/tcp.md) -- [TLS Termination](../tls/tls.md) +The Ingress controller will provision an implementation specific loadbalancer that satisfies the Ingress, +as long as the services (s1, s2) exist. diff --git a/docs/guides/ingress/monitoring/_index.md b/docs/guides/ingress/monitoring/_index.md index f04f213ef..657f6135d 100644 --- a/docs/guides/ingress/monitoring/_index.md +++ b/docs/guides/ingress/monitoring/_index.md @@ -2,9 +2,9 @@ title: Monitoring menu: product_voyager_5.0.0-rc.10: - identifier: monitoring + identifier: monitoring-ingress name: Monitoring - parent: ingress - weight: 50 + parent: ingress-guides + weight: 40 menu_name: product_voyager_5.0.0-rc.10 --- diff --git a/docs/guides/ingress/monitoring/coreos-prometheus-operator.md b/docs/guides/ingress/monitoring/coreos-prometheus-operator.md index 15dda3d12..643ad2ba3 100644 --- a/docs/guides/ingress/monitoring/coreos-prometheus-operator.md +++ b/docs/guides/ingress/monitoring/coreos-prometheus-operator.md @@ -1,16 +1,3 @@ ---- -menu: - product_voyager_5.0.0-rc.10: - name: CoreOS Prometheus - parent: monitoring - weight: 10 -product_name: voyager -menu_name: product_voyager_5.0.0-rc.10 -section_menu_id: guides -aliases: - - /products/voyager/5.0.0-rc.10/guides/ingress/monitoring/ ---- - ```console $ kubectl create -f ./docs/examples/monitoring/demo-0.yaml @@ -70,15 +57,15 @@ prometheus-operated None 9090/TCP 37 test-server 10.0.0.28 80/TCP 9m voyager-test-ingress 10.0.0.81 80:30446/TCP 9m voyager-test-ingress-stats 10.0.0.36 56789/TCP,56790/TCP 6s -~/g/s/g/a/v/h/deploy (d2) $ +~/g/s/g/a/v/h/deploy (d2) $ ~/g/s/g/a/v/h/deploy (d2) $ kubectl get servicemonitor -n demo NAME KIND voyager-demo-test-ingress ServiceMonitor.v1alpha1.monitoring.coreos.com ~/g/s/g/a/v/h/deploy (d2) $ kubectl get servicemonitor -n demo NAME KIND voyager-demo-test-ingress ServiceMonitor.v1alpha1.monitoring.coreos.com -~/g/s/g/a/v/h/deploy (d2) $ -~/g/s/g/a/v/h/deploy (d2) $ +~/g/s/g/a/v/h/deploy (d2) $ +~/g/s/g/a/v/h/deploy (d2) $ ~/g/s/g/a/v/h/deploy (d2) $ kubectl get servicemonitor -n demo -o yaml apiVersion: v1 items: @@ -151,7 +138,7 @@ spec: type: ClusterIP status: loadBalancer: {} -~/g/s/g/a/v/h/deploy (d2) $ +~/g/s/g/a/v/h/deploy (d2) $ ``` diff --git a/docs/guides/ingress/monitoring/stats-and-prometheus.md b/docs/guides/ingress/monitoring/stats.md similarity index 96% rename from docs/guides/ingress/monitoring/stats-and-prometheus.md rename to docs/guides/ingress/monitoring/stats.md index bdbd4a3ca..f4de2bfb0 100644 --- a/docs/guides/ingress/monitoring/stats-and-prometheus.md +++ b/docs/guides/ingress/monitoring/stats.md @@ -1,17 +1,18 @@ --- +title: Exposing HAProxy Stats menu: product_voyager_5.0.0-rc.10: + identifier: stats-monitoring name: Stats and Prometheus - parent: ingress - weight: 120 + parent: monitoring-ingress + weight: 10 product_name: voyager menu_name: product_voyager_5.0.0-rc.10 section_menu_id: guides --- +# Exposing HAProxy Stats - -## Exposing HAProxy Stats To expose HAProxy stats, please use the following annotations: ### Stats annotations diff --git a/docs/guides/ingress/pod-placement.md b/docs/guides/ingress/pod-placement.md index 2f518aef8..064be9f02 100644 --- a/docs/guides/ingress/pod-placement.md +++ b/docs/guides/ingress/pod-placement.md @@ -1,4 +1,17 @@ -# Placement of HAProxy Pods +--- +title: Placement of Ingress Pods | Voyager +menu: + product_voyager_5.0.0-rc.10: + identifier: pod-placement-ingress + name: Pod Placement + parent: ingress-guides + weight: 50 +product_name: voyager +menu_name: product_voyager_5.0.0-rc.10 +section_menu_id: guides +--- + +# Placement of Ingress Pods Voyager has rich support for how HAProxy pods are placed on cluster nodes. Please check [here](https://kubernetes.io/docs/concepts/configuration/assign-pod-node/) to understand Kubernetes' support for pod placement. @@ -6,7 +19,7 @@ Voyager has rich support for how HAProxy pods are placed on cluster nodes. Pleas At first, you need to have a Kubernetes cluster, and the kubectl command-line tool must be configured to communicate with your cluster. If you do not already have a cluster, you can create one by using [Minikube](https://github.com/kubernetes/minikube). -Now, install Voyager operator in your `minikube` cluster following the steps [here](/docs/install.md). +Now, install Voyager operator in your `minikube` cluster following the steps [here](/docs/setup/install.md). ```console minikube start diff --git a/docs/guides/ingress/replicas-and-autoscaling.md b/docs/guides/ingress/scaling.md similarity index 93% rename from docs/guides/ingress/replicas-and-autoscaling.md rename to docs/guides/ingress/scaling.md index bb96458d8..182e47c9a 100644 --- a/docs/guides/ingress/replicas-and-autoscaling.md +++ b/docs/guides/ingress/scaling.md @@ -1,15 +1,19 @@ --- +title: Scaling Ingress | Voyager menu: product_voyager_5.0.0-rc.10: - name: Replicas And Autoscaling - parent: ingress - weight: 95 + identifier: scaling-ingress + name: Scaling Ingress + parent: ingress-guides + weight: 45 product_name: voyager menu_name: product_voyager_5.0.0-rc.10 section_menu_id: guides --- -# Replicas +# Scaling Ingress + +## Replicas For each Ingress resource, Voyager deploys HAProxy in a Deployment prefixed by `voyager-` and the name of the Ingress. diff --git a/docs/guides/ingress/security/_index.md b/docs/guides/ingress/security/_index.md index 5897a1c4a..c452ee981 100644 --- a/docs/guides/ingress/security/_index.md +++ b/docs/guides/ingress/security/_index.md @@ -2,9 +2,9 @@ title: Security menu: product_voyager_5.0.0-rc.10: - identifier: security + identifier: security-ingress name: Security - parent: ingress - weight: 55 + parent: ingress-guides + weight: 35 menu_name: product_voyager_5.0.0-rc.10 --- diff --git a/docs/guides/ingress/security/basic-auth.md b/docs/guides/ingress/security/basic-auth.md index bcd4480c6..3cce28cd8 100644 --- a/docs/guides/ingress/security/basic-auth.md +++ b/docs/guides/ingress/security/basic-auth.md @@ -1,8 +1,10 @@ --- +title: Basic Authentication | Kubernetes Ingress menu: product_voyager_5.0.0-rc.10: + identifier: basic-auth-security name: Basic Auth - parent: security + parent: security-ingress weight: 10 product_name: voyager menu_name: product_voyager_5.0.0-rc.10 @@ -59,6 +61,7 @@ $ rm -fv auth ``` Create an Ingress with Basic Auth annotations + ```yaml apiVersion: voyager.appscode.com/v1beta1 kind: Ingress @@ -184,6 +187,7 @@ Content-Type: text/plain; charset=utf-8 ``` No auth enabled Backend + ```console $ curl -i ip:port/no-auth HTTP/1.1 200 OK @@ -195,6 +199,7 @@ Content-Type: text/plain; charset=utf-8 ## Using Basic Auth In Frontend Basic Auth can also be configured per frontend in voyager ingress via FrontendRules. + ```yaml apiVersion: voyager.appscode.com/v1beta1 kind: Ingress diff --git a/docs/guides/ingress/security/tls-auth.md b/docs/guides/ingress/security/tls-auth.md index 8f42bb8a0..f18303f69 100644 --- a/docs/guides/ingress/security/tls-auth.md +++ b/docs/guides/ingress/security/tls-auth.md @@ -1,9 +1,11 @@ --- +title: TLS Authentication | Kubernetes Ingress menu: product_voyager_5.0.0-rc.10: + identifier: tls-auth-security name: TLS Auth - parent: security - weight: 40 + parent: security-ingress + weight: 15 product_name: voyager menu_name: product_voyager_5.0.0-rc.10 section_menu_id: guides @@ -11,14 +13,11 @@ section_menu_id: guides # TLS Authentication -This example demonstrates how to configure -[TLS Authentication](https://tools.ietf.org/html/rfc2617) on -Voyager Ingress controller. +This example demonstrates how to configure [TLS Authentication](https://tools.ietf.org/html/rfc2617) on Voyager Ingress controller. - [Using tls auth in Ingress](#using-tls-authentication) - [Using tls auth in Frontend](#using-tls-auth-in-frontend) - Before diving into the deep learn about TLS Auth with HAproxy. - [SSL Client certificate management at application level](https://www.haproxy.com/blog/ssl-client-certificate-management-at-application-level/) - [Clinet side ssl certificates](https://raymii.org/s/tutorials/haproxy_client_side_ssl_certificates.html) @@ -34,16 +33,19 @@ Voyager Ingress read ca certificates from files stored on secrets with `ca.crt` ### Configure Create tls secret for enable ssl termination: + ```console $ kubectl create secret tls server --cert=/path/to/cert/file --key=/path/to/key/file ``` Create ca cert secret: + ```console $ kubectl create secret generic ca --from-file=/path/to/ca.crt ``` Create an Ingress with TLS Auth annotations + ```yaml apiVersion: voyager.appscode.com/v1beta1 kind: Ingress @@ -72,6 +74,7 @@ spec: ``` Test without certificates: + ```console $ curl -i -vvv 'https://auth.example.com' * Hostname was NOT found in DNS cache @@ -97,6 +100,7 @@ curl: (35) error:14094410:SSL routines:SSL3_READ_BYTES:sslv3 alert handshake fai ``` Send a valid clinet certificate: + ```console $ curl -v -s --key client.key --cert client.crt https://auth.example.com HTTP/1.1 200 OK @@ -107,6 +111,7 @@ Content-Type: text/plain; charset=utf-8 ``` Send a invalid clinet certificate, that will redirect to error page if provided: + ```console $ curl -v -s --key invalidclient.key --cert invalidclient.crt https://auth.example.com HTTP/1.1 302 @@ -115,6 +120,7 @@ Location: https://auth.example.com/errors.html ## Using TLS Auth In Frontend Basic Auth can also be configured per frontend in voyager ingress via FrontendRules. + ```yaml apiVersion: voyager.appscode.com/v1beta1 kind: Ingress @@ -158,6 +164,7 @@ spec: ``` Request in non tls port: + ```console $ curl -v -s https://auth.example.com HTTP/1.1 200 OK @@ -167,8 +174,8 @@ Content-Type: text/plain; charset=utf-8 ``` - Test without certificates: + ```console $ curl -i -vvv 'https://auth.example.com:8080' * Hostname was NOT found in DNS cache @@ -194,6 +201,7 @@ curl: (35) error:14094410:SSL routines:SSL3_READ_BYTES:sslv3 alert handshake fai ``` Send a valid clinet certificate: + ```console $ curl -v -s --key client.key --cert client.crt https://auth.example.com:8080 HTTP/1.1 200 OK @@ -205,11 +213,9 @@ Content-Type: text/plain; charset=utf-8 backend server will receive Headers `X-SSL` and `X-SSL-Client-CN`. Send a invalid clinet certificate, that will redirect to error page if provided: + ```console $ curl -v -s --key invalidclient.key --cert invalidclient.crt https://auth.example.com:8080 HTTP/1.1 302 Location: https://auth.example.com/errors.html ``` - -## Acknowledgement - - This document has been adapted from [kubernetes/ingress](https://github.com/kubernetes/ingress/tree/master/examples/auth/basic/haproxy) project. diff --git a/docs/guides/ingress/tcp/_index.md b/docs/guides/ingress/tcp/_index.md index a8db43799..69cee4214 100644 --- a/docs/guides/ingress/tcp/_index.md +++ b/docs/guides/ingress/tcp/_index.md @@ -2,9 +2,9 @@ title: TCP menu: product_voyager_5.0.0-rc.10: - identifier: tcp + identifier: tcp-ingress name: TCP - parent: ingress - weight: 60 + parent: ingress-guides + weight: 20 menu_name: product_voyager_5.0.0-rc.10 --- diff --git a/docs/guides/ingress/tcp/tcp.md b/docs/guides/ingress/tcp/overview.md similarity index 91% rename from docs/guides/ingress/tcp/tcp.md rename to docs/guides/ingress/tcp/overview.md index 5f20cd0f8..340043c21 100644 --- a/docs/guides/ingress/tcp/tcp.md +++ b/docs/guides/ingress/tcp/overview.md @@ -1,18 +1,18 @@ --- +title: TCP LoadBalancing | Kubernetes Ingress menu: product_voyager_5.0.0-rc.10: - name: TCP - parent: tcp + identifier: overview-tcp + name: Overview + parent: tcp-ingress weight: 10 product_name: voyager menu_name: product_voyager_5.0.0-rc.10 section_menu_id: guides -aliases: - - /products/voyager/5.0.0-rc.10/guides/ingress/tcp/ --- - # TCP LoadBalancing + TCP load balancing is one of the core features of Voyager Ingress. Voyager can handle TCP Load balancing with or without TLS. One Voyager Ingress can also be used to load balance both HTTP and TCP. One Simple TCP Rule Would be: @@ -59,7 +59,3 @@ For this Ingress, HAProxy will open up 3 separate ports: ### Restrictions - For one Ingress, you cannot have multiple `tcp` rules listening to same port, even if they do not have same `host`. - - -## Next Reading -- [TLS Termination](../tls/tls.md) diff --git a/docs/guides/ingress/tls/_index.md b/docs/guides/ingress/tls/_index.md index bbeaacb5c..9b38ba972 100644 --- a/docs/guides/ingress/tls/_index.md +++ b/docs/guides/ingress/tls/_index.md @@ -2,9 +2,9 @@ title: TLS menu: product_voyager_5.0.0-rc.10: - identifier: tls + identifier: tls-ingress name: TLS - parent: ingress - weight: 70 + parent: ingress-guides + weight: 15 menu_name: product_voyager_5.0.0-rc.10 --- diff --git a/docs/guides/ingress/tls/aws-cert-manager.md b/docs/guides/ingress/tls/aws-cert-manager.md index b6426e83b..4b7f6bf0a 100644 --- a/docs/guides/ingress/tls/aws-cert-manager.md +++ b/docs/guides/ingress/tls/aws-cert-manager.md @@ -1,15 +1,19 @@ --- +title: Using AWS Certificate Manager | Kubernetes Ingress menu: product_voyager_5.0.0-rc.10: + identifier: aws-cm-tls name: AWS Cert Manager - parent: tls - weight: 20 + parent: tls-ingress + weight: 15 product_name: voyager menu_name: product_voyager_5.0.0-rc.10 section_menu_id: guides --- -Voyager can use AWS certificate manager to terminate SSL connections for `LoadBalancer` type ingress in "aws" provider. To use this feature, +# Using AWS Certificate Manager + +Voyager can use AWS certificate manager to terminate SSL connections for `LoadBalancer` type ingress in `aws` provider. To use this feature, add the following annotations to Ingress; ```yaml @@ -25,7 +29,7 @@ Voyager operator will apply these annotation on `LoadBalancer` service used to e This service will (logically) listen on port 443, terminate SSL and forward to port 80 on HAProxy pods. Also, ELB will listen on port 80 and forward cleartext traffic to port 80. -``` +```yaml apiVersion: v1 kind: Service metadata: @@ -50,7 +54,6 @@ like to redirect cleartext client traffic on port 80 to port 443, please add red when `X-Forwarded-Proto` header value is `HTTPS`. Please see the following ingress example and [example rules](https://www.exratione.com/2014/10/managing-haproxy-configuration-when-your-server-may-or-may-not-be-behind-an-ssl-terminating-proxy/). - ```yaml apiVersion: voyager.appscode.com/v1beta1 kind: Ingress diff --git a/docs/guides/ingress/tls/backend-tls.md b/docs/guides/ingress/tls/backend-tls.md index 4b38a58ed..c4809acd5 100644 --- a/docs/guides/ingress/tls/backend-tls.md +++ b/docs/guides/ingress/tls/backend-tls.md @@ -1,18 +1,20 @@ --- +title: Backend TLS Support | Kubernetes Ingress menu: product_voyager_5.0.0-rc.10: + identifier: backend-tls name: Backend TLS - parent: tls - weight: 30 + parent: tls-ingress + weight: 20 product_name: voyager menu_name: product_voyager_5.0.0-rc.10 section_menu_id: guides --- +# Backend TLS Support Voyager can connect to a tls enabled backend server with or without ssl verification. -Available Options ssl: Creates a TLS/SSL socket when connecting to this server in order to cipher/decipher the traffic @@ -39,8 +41,8 @@ Available Options If this annotation is not set HAProxy will connect to backend as http, This value should not be set if the backend do not support https resolution. -Example -``` +Example: +```yaml kind: Service apiVersion: v1 metadata: @@ -57,7 +59,7 @@ spec: ``` -``` +```yaml apiVersion: voyager.appscode.com/v1beta1 kind: Ingress metadata: diff --git a/docs/guides/ingress/tls/tls.md b/docs/guides/ingress/tls/overview.md similarity index 96% rename from docs/guides/ingress/tls/tls.md rename to docs/guides/ingress/tls/overview.md index 577283a8d..a68315c25 100644 --- a/docs/guides/ingress/tls/tls.md +++ b/docs/guides/ingress/tls/overview.md @@ -1,21 +1,22 @@ --- +title: TLS | Kubernetes Ingress menu: product_voyager_5.0.0-rc.10: - name: TLS - parent: ingress - weight: 135 + identifier: overview-tls + name: Overview + parent: tls-ingress + weight: 10 product_name: voyager menu_name: product_voyager_5.0.0-rc.10 section_menu_id: guides --- + > New to Voyager? Please start [here](/docs). -## TLS +# TLS You can secure an Ingress by specifying a secret containing TLS pem or by referring a `certificate.voyager.appscode.com` resource. `certificate.voyager.appscode.com` can manage an certificate resource and use that certificate to encrypt communication. -# TLS - This tutorial will show you how to secure an Ingress using TLS/SSL certificates. ## Before You Begin @@ -71,15 +72,16 @@ To issue a free TLS/SSL certificate from Let's Encrypt, create a `Certificate` o ## Secure HTTP Service -To terminate a HTTP service, +To terminate a HTTP service, Caveats: - You can't terminate default backend For HTTP, If the `spec.TLS` section in an Ingress specifies different hosts, they will be multiplexed -on the same port according to hostname specified through SNI TLS extension (Voyager supports SNI). +on the same port according to hostname specified through SNI TLS extension (Voyager supports SNI). Referencing this secret in an Ingress will tell the Voyager to secure the channel from client to the loadbalancer using TLS: + ```yaml apiVersion: voyager.appscode.com/v1beta1 kind: Ingress @@ -107,6 +109,7 @@ terminate TLS at load balancer with the secret retried via SNI and forward unenc Adding a TCP TLS termination at Voyager Ingress is slightly different than HTTP, as TCP mode does not have SNI support. A TCP endpoint with TLS termination, will look like this in Voyager Ingress: + ```yaml apiVersion: voyager.appscode.com/v1beta1 kind: Ingress diff --git a/docs/roadmap.md b/docs/roadmap.md index 336759025..758482a43 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -1,25 +1,28 @@ --- title: Roadmap | Voyager -description: Roadmap of Voyager +description: Roadmap of voyager menu: product_voyager_5.0.0-rc.10: identifier: roadmap-voyager name: Roadmap - parent: getting-started - weight: 30 + parent: welcome + weight: 15 product_name: voyager menu_name: product_voyager_5.0.0-rc.10 -section_menu_id: getting-started -url: /products/voyager/5.0.0-rc.10/getting-started/roadmap/ +section_menu_id: welcome +url: /products/voyager/5.0.0-rc.10/welcome/roadmap/ +aliases: + - /products/voyager/5.0.0-rc.10/roadmap/ --- # Versioning Policy There are 2 parts to versioning policy: + - Operator version: Voyager __does not follow semver__, rather the _major_ version of operator points to the Kubernetes [client-go](https://github.com/kubernetes/client-go#branches-and-tags) version. You can verify this from the `glide.yaml` file. This means there might be breaking changes between point releases of the operator. This generally manifests as changed annotation keys or their meaning. Please always check the release notes for upgrade instructions. - - TPR version: appscode.com/v1beta1 is considered in beta. This means any changes to the YAML format will be backward + - CRD version: appscode.com/v1beta1 is considered in beta. This means any changes to the YAML format will be backward compatible among different versions of the operator. diff --git a/docs/setup/README.md b/docs/setup/README.md new file mode 100644 index 000000000..c3e73404b --- /dev/null +++ b/docs/setup/README.md @@ -0,0 +1,25 @@ +--- +title: Table of Contents | Setup +description: Table of Contents | Setup +menu: + product_voyager_5.0.0-rc.10: + identifier: setup-readme + name: Readme + parent: setup + weight: -1 +product_name: voyager +menu_name: product_voyager_5.0.0-rc.10 +section_menu_id: setup +url: /products/voyager/5.0.0-rc.10/setup/ +aliases: + - /products/voyager/5.0.0-rc.10/setup/README/ +--- +# Setup + +Setup contains instructions for installing the Voyager and its various components in Kubernetes. + +- [Install Voyager](/docs/setup/install.md). Installation instructions for Voyager. +- [Uninstall Voyager](/docs/setup/uninstall.md). Instructions for uninstallating Voyager. +- Developer Guide + - [Overview](/docs/setup/developer-guide/overview.md). Outlines everything you need to know from setting up your dev environment to how to build and test Voyager. + - [Release process](/docs/setup/developer-guide/release.md). Steps for releasing a new version of Voyager. diff --git a/docs/setup/_index.md b/docs/setup/_index.md index 011aa40e2..9eb0e1300 100644 --- a/docs/setup/_index.md +++ b/docs/setup/_index.md @@ -1,6 +1,5 @@ --- -title: Setup -description: Voyager Setup +title: Setup | Voyager menu: product_voyager_5.0.0-rc.10: identifier: setup diff --git a/docs/setup/developer-guide/_index.md b/docs/setup/developer-guide/_index.md index 568a91d94..5a37aa669 100644 --- a/docs/setup/developer-guide/_index.md +++ b/docs/setup/developer-guide/_index.md @@ -8,4 +8,4 @@ menu: parent: setup weight: 40 menu_name: product_voyager_5.0.0-rc.10 ---- \ No newline at end of file +--- diff --git a/docs/setup/developer-guide/README.md b/docs/setup/developer-guide/overview.md similarity index 97% rename from docs/setup/developer-guide/README.md rename to docs/setup/developer-guide/overview.md index 9e9941222..05a69a528 100644 --- a/docs/setup/developer-guide/README.md +++ b/docs/setup/developer-guide/overview.md @@ -9,10 +9,7 @@ menu: weight: 15 product_name: voyager menu_name: product_voyager_5.0.0-rc.10 -section_menu_id: developer-guide -url: /products/voyager/5.0.0-rc.10/developer-guide/ -aliases: - - /products/voyager/5.0.0-rc.10/developer-guide/README/ +section_menu_id: setup --- ## Development Guide diff --git a/docs/setup/developer-guide/release.md b/docs/setup/developer-guide/release.md index 3f521d384..3b46261db 100644 --- a/docs/setup/developer-guide/release.md +++ b/docs/setup/developer-guide/release.md @@ -3,15 +3,14 @@ title: Release | Voyager description: Voyager Release menu: product_voyager_5.0.0-rc.10: - identifier: release + identifier: release name: Release parent: developer-guide weight: 15 product_name: voyager menu_name: product_voyager_5.0.0-rc.10 -section_menu_id: developer-guide +section_menu_id: setup --- - # Release Process The following steps must be done from a Linux x64 bit machine. diff --git a/docs/setup/install.md b/docs/setup/install.md index eb83faaf1..c9269aa69 100644 --- a/docs/setup/install.md +++ b/docs/setup/install.md @@ -1,24 +1,21 @@ --- -title: Install | Voyager +title: Install Voyager description: Voyager Install menu: product_voyager_5.0.0-rc.10: identifier: install-voyager name: Install - parent: getting-started - weight: 35 + parent: setup + weight: 10 product_name: voyager menu_name: product_voyager_5.0.0-rc.10 -section_menu_id: getting-started -url: /products/voyager/5.0.0-rc.10/getting-started/install/ -aliases: - - /products/voyager/5.0.0-rc.10/install/ +section_menu_id: setup --- # Installation Guide ## Using YAML -Voyager can be installed via installer script included in the [/hack/deploy](https://github.com/appscode/voyager/tree/5.0.0-rc.10/hack) folder. +Voyager can be installed via installer script included in the [/hack/deploy](https://github.com/appscode/voyager/tree/5.0.0-rc.10/hack/deploy) folder. ```console # provider=acs @@ -78,12 +75,12 @@ $ curl -fsSL https://raw.githubusercontent.com/appscode/voyager/5.0.0-rc.10/hack ## Using Helm -Voyager can be installed via [Helm](https://helm.sh/) using the [chart](/chart/stable/voyager) included in this repository or from official charts repository. To install the chart with the release name `my-release`: +Voyager can be installed via [Helm](https://helm.sh/) using the [chart](https://github.com/appscode/voyager/tree/5.0.0-rc.10/chart/stable/voyager) included in this repository or from official charts repository. To install the chart with the release name `my-release`: ```console $ helm repo update $ helm install stable/voyager --name my-release ``` -To see the detailed configuration options, visit [here](/chart/stable/voyager/README.md). +To see the detailed configuration options, visit [here](https://github.com/appscode/voyager/tree/5.0.0-rc.10/chart/stable/voyager). ## Verify installation diff --git a/docs/setup/uninstall.md b/docs/setup/uninstall.md index 814c53d20..f213e1957 100644 --- a/docs/setup/uninstall.md +++ b/docs/setup/uninstall.md @@ -1,24 +1,23 @@ --- -title: Uninstall | Voyager +title: Uninstall Voyager description: Voyager Uninstall menu: product_voyager_5.0.0-rc.10: identifier: uninstall-voyager name: Uninstall - parent: getting-started - weight: 50 + parent: setup + weight: 20 product_name: voyager menu_name: product_voyager_5.0.0-rc.10 -section_menu_id: getting-started -url: /products/voyager/5.0.0-rc.10/getting-started/uninstall/ -aliases: - - /products/voyager/5.0.0-rc.10/uninstall/ +section_menu_id: setup --- # Uninstall Voyager + Please follow the steps below to uninstall Voyager: -1. Delete the deployment and service used for Voyager operator. +- Delete the deployment and service used for Voyager operator. + ```console $ curl -fsSL https://raw.githubusercontent.com/appscode/voyager/5.0.0-rc.10/hack/deploy/uninstall.sh | bash @@ -34,24 +33,28 @@ No resources found No resources found ``` -2. Now, wait several seconds for Voyager to stop running. To confirm that Voyager operator pod(s) have stopped running, run: +- Now, wait several seconds for Voyager to stop running. To confirm that Voyager operator pod(s) have stopped running, run: + ```console $ kubectl get pods --all-namespaces -l app=voyager ``` -3. To keep a copy of your existing Voyager objects, run: +- To keep a copy of your existing Voyager objects, run: + ```console $ kubectl get ingress.voyager.appscode.com --all-namespaces -o yaml > ingress.yaml $ kubectl get certificate.voyager.appscode.com --all-namespaces -o yaml > certificate.yaml ``` -4. To delete existing Voyager objects from all namespaces, run the following command in each namespace one by one. +- To delete existing Voyager objects from all namespaces, run the following command in each namespace one by one. + ```console $ kubectl delete ingress.voyager.appscode.com --all --cascade=false $ kubectl delete certificate.voyager.appscode.com --all --cascade=false ``` -5. Delete the old CRD-registration. +- Delete the old CRD-registration. + ```console kubectl delete crd -l app=voyager ``` diff --git a/docs/support.md b/docs/support.md index 4f07a8601..930646f6c 100644 --- a/docs/support.md +++ b/docs/support.md @@ -5,16 +5,18 @@ menu: product_voyager_5.0.0-rc.10: identifier: support-voyager name: Support - parent: getting-started - weight: 45 + parent: welcome + weight: 25 product_name: voyager menu_name: product_voyager_5.0.0-rc.10 -section_menu_id: getting-started -url: /products/voyager/5.0.0-rc.10/getting-started/support/ +section_menu_id: welcome +url: /products/voyager/5.0.0-rc.10/welcome/support/ +aliases: + - /products/voyager/5.0.0-rc.10/support/ --- # Support -If you have any questions, you can reach out to us. -* [Slack](https://slack.appscode.com) -* [Twitter](https://twitter.com/AppsCodeHQ) +We use Slack for public discussions. To chit chat with us or the rest of the community, join us in the [AppsCode Slack team](https://appscode.slack.com/messages/C0XQFLGRM/details/) channel `#general`. To sign up, use our [Slack inviter](https://slack.appscode.com/). + +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).