Skip to content

Commit 62d317c

Browse files
author
Matthew Fisher
committed
feat(docs): add digitalocean guide
1 parent bfe8832 commit 62d317c

2 files changed

Lines changed: 234 additions & 0 deletions

File tree

‎docs/installing_deis/configure-dns.rst‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,8 @@ On a multi-node cluster, however, there are probably multiple routers, and the c
1515

1616
Note that the controller will eventually live behind the routers so that all external traffic will flow through the load balancer - configuring a DNS record which points to a service whose IP could change is less than ideal.
1717

18+
.. _dns_records:
19+
1820
Necessary DNS records
1921
---------------------
2022

@@ -26,6 +28,8 @@ Apps can then be accessed by browsers at ``appname.myapps.com``, and the control
2628

2729
This record is necessary for all deployments of Deis (EC2, Rackspace, DigitalOcean, Google Compute Engine, bare metal, etc.). Local clusters can use the domain ``local.deisapp.com``, ``local3.deisapp.com``, or ``local5.deiaspp.com``.
2830

31+
.. _xip_io:
32+
2933
Using xip.io
3034
------------
3135
An alternative to configuring your own DNS records is to use `xip`_ to reference the IP of your load balancer. For example:

‎docs/installing_deis/digitalocean.rst‎

Lines changed: 230 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,230 @@
1+
:title: Installing Deis on DigitalOcean
2+
:description: How to provision a multi-node Deis cluster on DigitalOcean
3+
4+
.. _deis_on_digitalocean:
5+
6+
DigitalOcean
7+
============
8+
9+
In this tutorial, we will show you how to set up your own 3-node cluster on DigitalOcean. This
10+
guide is also available in DigitalOcean's `Community site`_, so check out their guide as well!
11+
12+
Prerequisites
13+
-------------
14+
15+
To complete this guide, you must have the following:
16+
17+
- An SSH key for running operator's commands against the cluster using ``deisctl``
18+
- An SSH key for authorizing yourself against Deis' builder
19+
- A domain to point to the cluster
20+
- The ability to provision at least 3 DigitalOcean Droplets that are 2GB or greater
21+
22+
In order to provision the cluster, we will need to install a couple of administrative tools.
23+
`docl`_ is a convenience tool to help provision DigitalOcean Droplets. We will also require the
24+
`Deis Control Utility`_, which will assist us with installing, configuring and managing the Deis
25+
platform.
26+
27+
Generate a New Discovery URL
28+
----------------------------
29+
30+
To get started with provisioning the Droplets, we will need to generate a new Discovery URL.
31+
Discovery URLs help connect `etcd`_ instances together by storing a list of peer addresses and
32+
metadata under a unique address. You can generate a new discovery URL for use in your platform by
33+
running the following from the root of the repository:
34+
35+
.. code-block:: console
36+
37+
$ make discovery-url
38+
39+
This will write a new discovery URL to the user-data file. This file is used by DigitalOcean's v2
40+
metadata API to create and customize each machine in our cluster to our liking. Some convenience
41+
scripts are supplied in this user-data file, so it is mandatory for provisioning Deis.
42+
43+
Create CoreOS Droplets
44+
----------------------
45+
46+
Now that we have the user-data file, we can provision some Droplets. We've made this process simple
47+
by supplying a script that does all the heavy lifting for you. If you want to provision manually,
48+
however, start by uploading the SSH key you wish to use to log into each of these servers. After
49+
that, create at least three Droplets with the following specifications:
50+
51+
- At least 2GB -- more is recommended
52+
- All Droplets deployed in the same region
53+
- Region must have private networking enabled
54+
- Region must have User Data enabled. Supply the user-data file here
55+
- Select CoreOS Alpha channel
56+
- Select your SSH key from the list
57+
58+
If private networking is not available in your region, swap out ``$private_ipv4`` with
59+
``$public_ipv4`` in the user-data file.
60+
61+
If you want to use the script:
62+
63+
.. code-block:: console
64+
65+
$ gem install docl
66+
$ docl authorize
67+
$ docl upload_key deis ~/.ssh/deis.pub
68+
$ # retrieve your SSH key's ID
69+
$ docl keys
70+
deis (id: 12345)
71+
$ # retrieve the region name
72+
$ docl regions --metadata --private-networking
73+
Amsterdam 2 (ams2)
74+
Amsterdam 3 (ams3)
75+
London 1 (lon1)
76+
New York 3 (nyc3)
77+
Singapore 1 (sgp1)
78+
$ ./contrib/digitalocean/provision-do-cluster nyc3 12345 4GB
79+
80+
Which will provision 3 CoreOS nodes for use.
81+
82+
Configure DNS
83+
-------------
84+
85+
Deis requires a wildcard DNS record to function properly. If the top-level domain (TLD) that you
86+
are using is ``example.com``, your applications will exist at the ``*.example.com`` level. For example, an
87+
application called ``app`` would be accessible via ``app.example.com``.
88+
89+
One way to configure this on DigitalOcean is to setup round-robin DNS via the `DNS control panel`_.
90+
To do this, add the following records to your domain:
91+
92+
- A wildcard CNAME record at your top-level domain, i.e. a CNAME record with * as the name, and @
93+
as the canonical hostname
94+
- For each CoreOS machine created, an A-record that points to the TLD, i.e. an A-record named @,
95+
with the droplet's public IP address
96+
97+
The zone file will now have the following entries in it: (your IP addresses will be different)
98+
99+
.. code-block:: console
100+
101+
* CNAME @
102+
@ IN A 104.131.93.162
103+
@ IN A 104.131.47.125
104+
@ IN A 104.131.113.138
105+
106+
For convenience, you can also set up DNS records for each node:
107+
108+
.. code-block:: console
109+
110+
deis-1 IN A 104.131.93.162
111+
deis-2 IN A 104.131.47.125
112+
deis-3 IN A 104.131.113.138
113+
114+
If you need help using the DNS control panel, check out `this tutorial`_ on DigitalOcean's
115+
community site.
116+
117+
If you're using your own third-party DNS registrar, please refer to their documentation on this
118+
setup, along with the :ref:`dns_records` required.
119+
120+
If you don't have an available domain for testing, you can refer to the :ref:`xip_io` documentation on
121+
setting up a wildcard DNS for Deis.
122+
123+
Install Deis Control Utility
124+
----------------------------
125+
126+
Now that we have the CoreOS cluster set up, we will install the Deis Control Utility. This client
127+
will help us configure and install the platform on top of our CoreOS cluster.
128+
129+
Change to the directory where you would like to install the deisctl binary. Then, install the Deis
130+
Control Utility by downloading and running the install script with the following command:
131+
132+
.. code-block:: console
133+
134+
$ cd ~/bin
135+
$ curl -sSL http://deis.io/deisctl/install.sh | sh -s 0.14.1
136+
137+
This installs deisctl to the current directory, and refreshes the Deis systemd unit files used to
138+
schedule the components. Let's link it to /usr/local/bin, so it will be in our PATH:
139+
140+
.. code-block:: console
141+
142+
$ sudo ln -fs $PWD/deisctl /usr/local/bin/deisctl
143+
144+
Install Deis Platform
145+
---------------------
146+
147+
From the computer you installed the Deis tools on, we will provision the Deis platform. Ensure your
148+
SSH agent is running (and select the private key that corresponds to the SSH keys added to your
149+
CoreOS droplets):
150+
151+
.. code-block:: console
152+
153+
$ eval `ssh-agent -s`
154+
$ ssh-add ~/.ssh/deis
155+
156+
Find the public IP address of one of your CoreOS droplets, and export it to the DEISCTL_TUNNEL
157+
environment variable (substitute your own IP address):
158+
159+
.. code-block:: console
160+
161+
$ export DEISCTL_TUNNEL=104.131.93.162
162+
163+
If you set up the "convenience" DNS records, you can just refer to them via
164+
165+
.. code-block:: console
166+
167+
$ export DEISCTL_TUNNEL="deis-1.example.com"
168+
169+
This is the IP address where deisctl will attempt to communicate with the cluster. You can test
170+
that it is working properly by running deisctl list. If you see a single line of output, the
171+
control utility is communicating with the CoreOS machines.
172+
173+
Before provisioning the platform, we'll need to add the SSH key to deis so it can connect to remote
174+
hosts during ``deis run``:
175+
176+
.. code-block:: console
177+
178+
$ deisctl config platform set sshPrivateKey=~/.ssh/deis
179+
180+
We'll also need to tell the controller which domain name we are deploying applications under:
181+
182+
.. code-block:: console
183+
184+
$ deisctl config platform set domain=example.com
185+
186+
Once finished, run this command to provision the Deis platform:
187+
188+
.. code-block:: console
189+
190+
$ deisctl install platform
191+
192+
You will see output like the following, which indicates that the units required to run Deis have
193+
been loaded on the CoreOS cluster:
194+
195+
.. code-block:: console
196+
197+
● ▴ ■
198+
■ ● ▴ Installing Deis...
199+
▴ ■ ●
200+
201+
Scheduling data containers...
202+
...
203+
Deis installed.
204+
Please run `deisctl start platform` to boot up Deis.
205+
206+
Run this command to start the Deis platform:
207+
208+
.. code-block:: console
209+
210+
$ deisctl start platform
211+
212+
Once you see "Deis started.", your Deis platform is running on a cluster! You may verify that all
213+
of the Deis units are loaded and active by running the following command:
214+
215+
.. code-block:: console
216+
217+
$ deisctl list
218+
219+
All of the units should be active.
220+
221+
Now that you've finished provisioning a cluster, please refer to :ref:`register-admin-user` to get
222+
started using the platform.
223+
224+
225+
.. _`Community site`: https://www.digitalocean.com/community/tutorials/how-to-set-up-a-deis-cluster-on-digitalocean
226+
.. _`docl`: https://github.com/nathansamson/docl#readme
227+
.. _`Deis Control Utility`: https://github.com/deis/deis/tree/master/deisctl#readme
228+
.. _`DNS control panel`: https://cloud.digitalocean.com/domains
229+
.. _`etcd`: https://github.com/coreos/etcd
230+
.. _`this tutorial`: https://www.digitalocean.com/community/tutorials/how-to-set-up-a-host-name-with-digitalocean

0 commit comments

Comments
 (0)