From 7add6dfe8085b8f03fc9a88f1b7e39f4d1a69b1b Mon Sep 17 00:00:00 2001 From: Ross Kukulinski Date: Thu, 12 Jul 2018 06:53:38 -0700 Subject: [PATCH 1/5] Docs refresh for Contour 0.6-beta.1. Fixes #171 Signed-off-by: Ross Kukulinski --- README.md | 5 ----- docs/README.md | 2 +- docs/route.md | 46 +++++++++++++++++++++++++++++++++------------- docs/teams.md | 8 +++++++- 4 files changed, 41 insertions(+), 20 deletions(-) diff --git a/README.md b/README.md index f9aa4718..47c96932 100644 --- a/README.md +++ b/README.md @@ -37,11 +37,6 @@ Documentation for all the Gimbal components can be found in the [docs directory] * Upstream Kubernetes Pods and OpenStack VMs must be routable from the Gimbal load balancing cluster. * Support is not available for Kubernetes clusters with overlay networks. * We are looking for community feedback on design requirements for a solution. A possible option is one GRE tunnel per upstream cluster. [Feedback welcome here](https://github.com/heptio/gimbal/issues/39)! -* The Kubernetes Ingress API is limited and insecure. - * Provides only one backend per route. - * Anyone can modify route rules for a domain. - * More complex load balancing features like weighting and strategy are not supported. - * Gimbal & Contour will provide a solution with a [new IngressRoute CRD](https://github.com/heptio/contour/blob/master/design/ingressroute-design.md). ## Troubleshooting diff --git a/docs/README.md b/docs/README.md index 5059e671..5e1bfde5 100644 --- a/docs/README.md +++ b/docs/README.md @@ -21,7 +21,7 @@ These guides describe how the components of Gimbal function and how they interac ## User Topics -- [Route Specification](route.md) +- [IngressRoute Management](route.md) - [Dashboards / Monitoring / Alerting](monitoring.md) ## Data Flow diff --git a/docs/route.md b/docs/route.md index 8e6635d9..90a71fbc 100644 --- a/docs/route.md +++ b/docs/route.md @@ -1,30 +1,50 @@ # Route Specification -The core of Gimbal is Routes, which allow traffic into one or more applications. This section will discuss how to utilize Kubernetes `Ingress` objects to create these routes. +The core of Gimbal is Ingressroutes, which allow traffic to be routed into one or more applications. This section will discuss how to utilize [Contour IngressRoute](https://github.com/heptio/contour/blob/master/docs/ingressroute.md) objects to create these definitions. Before beginning it is important to understand how service discovery functions within Gimbal. The Discoverer components should be deployed per upstream cluster. Once synchronized, services will show up in your team namespace with the cluster name appended. -For example, if a Kubernetes cluster is being discovered and there was a service named `s1` which existed in the namespace `team1`, in the cluster `node02`, once synchronized the service in the Gimbal cluster would be named `s1-node02`. +For example, if a Kubernetes cluster is being discovered and there was a service named `s1` which existed in the namespace `team1`, in the cluster `node02`, once synchronized the service in the Gimbal cluster would be named `s1-node02`. ## Basic Route -Following is a basic route which routes any request to `foo.bar.com` and proxies to a service named `s1` on the remote cluster `node02` over port `80`. +Following is a basic IngressRoute which routes any request to `foo.bar.com` and proxies to a service named `s1` on the remote cluster `node02` over port `80`. ```sh -apiVersion: extensions/v1beta1 -kind: Ingress +apiVersion: contour.heptio.com/v1beta1 +kind: IngressRoute metadata: name: test spec: - rules: - - host: foo.bar.com - http: - paths: - - backend: - serviceName: s1-node02 - servicePort: 80 + virtualhost: + fqdn: foo.bar.com + routes: + - match: / + services: + - name: cluster1-service1 + port: 80 ``` +## IngressRoute Features + +The IngressRoute API provides a number of [enhancements](https://github.com/heptio/contour/blob/master/docs/ingressroute.md#key-ingressroute-benefits) over Kubernetes Ingress: + +* Weight shifting +* Multiple services per route +* Load balancing strategies +* Multi-team support + +## IngressRoute Delegation + +Gimbal's multi-team support is enabled through Contour's [IngressRoute Delegation](https://github.com/heptio/contour/blob/master/docs/ingressroute.md#ingressroute-delegation). + +### Restricted root namespaces + +Contour has an [enforcing mode](https://github.com/heptio/contour/blob/master/docs/ingressroute.md#restricted-root-namespaces) which accepts a list of namespaces where root IngressRoutes are valid. +Only users permitted to operate in those namespaces can therefore create IngressRoutes with the `virtualhost` field. + +This restricted mode is enabled in Contour by specifying a command line flag, `--ingressroute-root-namespaces`, which will restrict Contour to only searching the defined namespaces for root IngressRoutes. + ## Additional Information -More information regarding Ingress can be found here: [https://kubernetes.io/docs/concepts/services-networking/ingress/](https://kubernetes.io/docs/concepts/services-networking/ingress/) \ No newline at end of file +More information regarding IngressRoutes can be found in the [Contour Documentation](https://github.com/heptio/contour/blob/master/docs/ingressroute.md) \ No newline at end of file diff --git a/docs/teams.md b/docs/teams.md index ba8a8458..6c4ce954 100644 --- a/docs/teams.md +++ b/docs/teams.md @@ -1,6 +1,6 @@ # Teams with Gimbal -A key feature of Gimbal is team management. Teams should be able to configure and define their own Ingress resources within the Gimbal cluster without requiring an administrator to assist. To enable this, users should be allowed access only to specified namespaces in the Gimbal cluster. Within their respective namespaces, team members should be granted specific authorization to create Ingress routes and to view Services and Endpoints. +A key feature of Gimbal is team management. Teams should be able to configure and define their own IngressRoute resources within the Gimbal cluster without requiring an administrator to assist. To enable this, users should be allowed access only to specified namespaces in the Gimbal cluster. Within their respective namespaces, team members should be granted specific authorization to create IngressRoutes and to view Services and Endpoints. ## RBAC rules @@ -29,4 +29,10 @@ rules: - ingresses verbs: - "*" +- apiGroups: + - contour.heptio.com + resources: + - ingressroutes + verbs: + - "*" ``` \ No newline at end of file From 84d4ece7ce9fb50949e1e35fe5227ef36caacfd0 Mon Sep 17 00:00:00 2001 From: Ross Kukulinski Date: Thu, 12 Jul 2018 07:04:50 -0700 Subject: [PATCH 2/5] Nit Ingressroutes to IngressRoutes Signed-off-by: Ross Kukulinski --- docs/route.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/route.md b/docs/route.md index 90a71fbc..6a8ce26e 100644 --- a/docs/route.md +++ b/docs/route.md @@ -1,6 +1,6 @@ # Route Specification -The core of Gimbal is Ingressroutes, which allow traffic to be routed into one or more applications. This section will discuss how to utilize [Contour IngressRoute](https://github.com/heptio/contour/blob/master/docs/ingressroute.md) objects to create these definitions. +The core of Gimbal is IngressRoutes, which allow traffic to be routed into one or more applications. This section will discuss how to utilize [Contour IngressRoute](https://github.com/heptio/contour/blob/master/docs/ingressroute.md) objects to create these definitions. Before beginning it is important to understand how service discovery functions within Gimbal. The Discoverer components should be deployed per upstream cluster. Once synchronized, services will show up in your team namespace with the cluster name appended. From 24a9c3f783493257729f170aba2a8abfd208c48c Mon Sep 17 00:00:00 2001 From: Ross Kukulinski Date: Thu, 12 Jul 2018 07:14:47 -0700 Subject: [PATCH 3/5] More fixes Signed-off-by: Ross Kukulinski --- docs/route.md | 4 ++-- docs/teams.md | 2 ++ 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/route.md b/docs/route.md index 6a8ce26e..1471a1d8 100644 --- a/docs/route.md +++ b/docs/route.md @@ -4,9 +4,9 @@ The core of Gimbal is IngressRoutes, which allow traffic to be routed into one o Before beginning it is important to understand how service discovery functions within Gimbal. The Discoverer components should be deployed per upstream cluster. Once synchronized, services will show up in your team namespace with the cluster name appended. -For example, if a Kubernetes cluster is being discovered and there was a service named `s1` which existed in the namespace `team1`, in the cluster `node02`, once synchronized the service in the Gimbal cluster would be named `s1-node02`. +For example, if a Kubernetes cluster is being discovered and there was a service named `s1` which existed in the namespace `team1`, in the cluster `cluster1`, once synchronized, the service in the Gimbal cluster would be named `cluster1-s1` and it would be in the `team` namespace. -## Basic Route +## Basic Routex Following is a basic IngressRoute which routes any request to `foo.bar.com` and proxies to a service named `s1` on the remote cluster `node02` over port `80`. diff --git a/docs/teams.md b/docs/teams.md index 6c4ce954..9da36737 100644 --- a/docs/teams.md +++ b/docs/teams.md @@ -2,6 +2,8 @@ A key feature of Gimbal is team management. Teams should be able to configure and define their own IngressRoute resources within the Gimbal cluster without requiring an administrator to assist. To enable this, users should be allowed access only to specified namespaces in the Gimbal cluster. Within their respective namespaces, team members should be granted specific authorization to create IngressRoutes and to view Services and Endpoints. +Cluster administrators can [delegate](route.md) specific VirtualHosts (and/or paths) to team namespaces. Paired with a locked-dwn RBAC policy, Gimbal provides a secure multi-team ingress solution. + ## RBAC rules A key component of any secure Kubernetes cluster are permissions implemented with Role Based Access Control (RBAC). From d266ae3320c434fada2fd74d2c46f8f457e4aa5c Mon Sep 17 00:00:00 2001 From: Ross Kukulinski Date: Thu, 12 Jul 2018 07:18:39 -0700 Subject: [PATCH 4/5] nit team1 not team Signed-off-by: Ross Kukulinski --- docs/route.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/route.md b/docs/route.md index 1471a1d8..7c848e1c 100644 --- a/docs/route.md +++ b/docs/route.md @@ -4,7 +4,7 @@ The core of Gimbal is IngressRoutes, which allow traffic to be routed into one o Before beginning it is important to understand how service discovery functions within Gimbal. The Discoverer components should be deployed per upstream cluster. Once synchronized, services will show up in your team namespace with the cluster name appended. -For example, if a Kubernetes cluster is being discovered and there was a service named `s1` which existed in the namespace `team1`, in the cluster `cluster1`, once synchronized, the service in the Gimbal cluster would be named `cluster1-s1` and it would be in the `team` namespace. +For example, if a Kubernetes cluster is being discovered and there was a service named `s1` which existed in the namespace `team1`, in the cluster `cluster1`, once synchronized, the service in the Gimbal cluster would be named `cluster1-s1` and it would be in the `team1` namespace. ## Basic Routex From 98311a0d7eaeb910fbf94fe889acde9eca98a3e9 Mon Sep 17 00:00:00 2001 From: Ross Kukulinski Date: Thu, 12 Jul 2018 07:43:20 -0700 Subject: [PATCH 5/5] Routex be gone Signed-off-by: Ross Kukulinski --- docs/route.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/route.md b/docs/route.md index 7c848e1c..0ea70b24 100644 --- a/docs/route.md +++ b/docs/route.md @@ -6,7 +6,7 @@ Before beginning it is important to understand how service discovery functions w For example, if a Kubernetes cluster is being discovered and there was a service named `s1` which existed in the namespace `team1`, in the cluster `cluster1`, once synchronized, the service in the Gimbal cluster would be named `cluster1-s1` and it would be in the `team1` namespace. -## Basic Routex +## Basic Route Following is a basic IngressRoute which routes any request to `foo.bar.com` and proxies to a service named `s1` on the remote cluster `node02` over port `80`.