Skip to content

Commit ca7cc53

Browse files
author
Kent Rancourt
committed
doc(routing/ingress): improve docs
1 parent 5ca102d commit ca7cc53

1 file changed

Lines changed: 119 additions & 42 deletions

File tree

‎docs/src/installing-deis/installing-the-deis-platform.md‎

Lines changed: 119 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -35,23 +35,119 @@ $ kubectl get pods --namespace=deis
3535

3636
Once you see all of the pods ready, your Deis platform is running on a cluster!
3737

38-
## Mapping a Default Domain
38+
## Routing Traffic
3939

40-
Deis will route traffic from Kubernetes nodes to Deis components, but to
41-
do so it needs a domain. By default, Deis is configured to use the
42-
domain `example.com`. For basic Deis testing, simply add an entry to
43-
your host machine's `/etc/hosts` file.
40+
The Deis router component will use an incoming request's HTTP `Host`
41+
header to direct traffic to Deis components and to applications deployed
42+
via Deis. It is therefore important that the router be configured
43+
properly and that DNS and/or your local `/etc/hosts` file are as well.
44+
45+
### Configuring the Platform Domain
46+
47+
The Deis router requires a "platform domain" be set. Deis components
48+
that respond to HTTP requests and applications deployed via Deis will
49+
all live on subdomains of the platform domain. When installing Deis
50+
via helm, the platform domain is set to `example.com` by default. This
51+
can be changed by editing Deis' helm chart prior to installation.
52+
Alternatively, the change can be made after Deis has been installed
53+
by editing the router's replication controller like so:
54+
55+
```
56+
$ kubectl edit rc deis-router --namespace=deis
57+
```
58+
59+
Find `example.com` in the manifest, change it to a domain of your
60+
choosing, and save changes. Kubernetes will apply the changes and
61+
the router will dynamically reconfigure itself accordingly.
62+
63+
### Getting Traffic to the Cluster
64+
65+
With the platform domain configured, the only remaining concern
66+
is to ensure traffic for that domain reaches the cluster. There
67+
are a few ways of doing this, and which you use may depend on the
68+
capabilities of your infrastructure and your Kubernetes cluster.
69+
70+
In general, the goal is to connect traffic bound for
71+
`*.the-domain-you.picked` to your Kubernetes cluster.
72+
73+
#### Using an Automatically Provisioned Load Balancer
74+
75+
If your Kubernetes cluster and the underlying infrastructure
76+
support it, the Deis router's service (which is of `type:
77+
LoadBalancer`) will automatically provision an "external"
78+
(external to the Kubernetes cluster) load balancer. On AWS,
79+
for instance, this takes the form of an ELB, while on Google
80+
Container Engine, it takes the form of a routing rule.
81+
82+
If it is supported, you will be able to find the DNS name or
83+
IP(s) of the external load balancer like so:
84+
85+
```
86+
$ kubectl describe service deis-router --namespace=deis
87+
```
88+
89+
Examine the `LoadBalancer Ingress` field to find the DNS
90+
name or IP(s). The former can be added to DNS as a CNAME,
91+
while the latter can be added as an A record.
92+
93+
#### Creating Your Own Load Balancer
94+
95+
On Kubernetes clusters and underlying infrastructure that
96+
do not support the automated provisioning of an external
97+
load balancer for the Deis router, you may provision your
98+
own and add _all_ minion nodes of the Kubernetes cluster to
99+
the pool.
100+
101+
The load balancer must pass incoming traffic on the
102+
following ports to the _same_ ports on the Kubernetes
103+
worker nodes:
104+
105+
* 80
106+
* 443
107+
* 2222
108+
* 9090
109+
110+
The Deis router component listens to those ports on any
111+
host it runs on. Since not _all_ nodes are likely to
112+
be running the router, a health check should be used to
113+
determine which node(s) can serve requests. The router's
114+
healthcheck should use the HTTP protocol, port `9090`, and
115+
the request path `/healthz`.
116+
117+
Load balancer idle timeouts should be set to at least `1200`
118+
seconds so connections do not close prematurely during longer
119+
running requests such as application deployments.
120+
121+
#### Without a Load Balancer
122+
123+
On some platforms (Vagrant, for instance) a load balancer is
124+
not an easy or practical thing to provision. In these cases,
125+
one can directly identify the public IP of a Kubernetes node
126+
that is hosting a router pod and use that information to
127+
configure DNS or the local `/etc/hosts` file.
44128

45129
You can find the IP address of a node using `kubectl`:
46130

47131
```
48-
$ kubectl get nodes
49-
NAME LABELS STATUS AGE
50-
10.245.1.3 kubernetes.io/hostname=10.245.1.3 Ready 19h
132+
$ kubectl get pods --namespace=deis | grep deis-router
133+
deis-router-ih25q 1/1 Running 0 2h
134+
```
135+
136+
Using the pod name determined through the above, one can
137+
use `kubectl` to determine what node the pod is running on:
138+
139+
```
140+
$ kubectl describe pod describe pod deis-router-ih25q --namespace=deis
141+
```
142+
143+
The `Node` field of the response should provide an IP:
144+
145+
```
146+
Node: 10.245.1.3/
51147
```
52148

53-
You may have numerous entries. All entries should be able to route to
54-
Deis, though.
149+
If the IP is public, this can be used to configure DNS or the
150+
local `/etc/hosts` file.
55151

56152
In your `/etc/hosts` file, add an entry like this:
57153

@@ -62,51 +158,32 @@ In your `/etc/hosts` file, add an entry like this:
62158
This route will get you started, though you may find that you have to
63159
manually maintain this file.
64160

65-
### Using a DNS Service
161+
#### Using a DNS Service
66162

67-
Rather than hard-coding a hostfile entry, you may prefer to [configure a DNS][]
68-
record. `xip.io` is a particularly easy way to do this.
163+
With any of the avenues described above, some hassle may be spared by
164+
leveraging a service such as `xip.io`, which will not require any
165+
editing of DNS records or local `/etc/hosts` files.
69166

70-
Edit `$(helm home)/workspace/charts/deis/manifests/deis-router-rc.yaml`
71-
and change the `domain` annotation to point to your DNS entry:
167+
Simply determine the correct IP to route your traffic to (as described
168+
above), then configure the router's platform domain to be `<ip>.xip.io`
72169

73-
```yaml
74-
apiVersion: v1
75-
kind: ReplicationController
76-
metadata:
77-
name: deis-router
78-
namespace: deis
79-
labels:
80-
heritage: deis
81-
annotations:
82-
deis.io/routerConfig: |
83-
{
84-
"domain": "10.245.1.3.xip.io",
85-
"useProxyProtocol": false
86-
}
87-
spec:
88-
replicas: 1
89-
selector:
90-
app: deis-router
91-
#...
92-
```
170+
### Testing
93171

94-
Once you have changed and saved the file, run `kubectl apply`:
172+
To test that traffic reaches its intended destination, a request can be
173+
sent to the Deis controller like so:
95174

96175
```
97-
$ kubectl --namespace=deis apply -f $(helm home)/workspace/charts/deis/manifests/deis-router-rc.yaml
176+
curl http://deis.<platform domain>/v2/
98177
```
99178

100-
After a moment or two, you should be able to test with a brief curl
101-
command:
179+
Since such requests require authentication, a response such as
180+
the following is an indicator of success:
102181

103182
```
104-
curl http://deis.10.245.1.3.xip.io/v2/
105183
{"detail":"Authentication credentials were not provided."}
106184
```
107185

108-
This message indicates that the message has been routed all the way to
109-
the Deis controller.
186+
## Next Steps
110187

111188
Now that you've finished provisioning a cluster, start [Using Deis][] to deploy your first
112189
application on Deis.

0 commit comments

Comments
 (0)