|
| 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 | +.. note:: |
| 86 | + |
| 87 | + If you're using your own third-party DNS registrar, please refer to their documentation on this |
| 88 | + setup, along with the :ref:`dns_records` required. |
| 89 | + |
| 90 | +.. note:: |
| 91 | + |
| 92 | + If you don't have an available domain for testing, you can refer to the :ref:`xip_io` |
| 93 | + documentation on setting up a wildcard DNS for Deis. |
| 94 | + |
| 95 | +Deis requires a wildcard DNS record to function properly. If the top-level domain (TLD) that you |
| 96 | +are using is ``example.com``, your applications will exist at the ``*.example.com`` level. For example, an |
| 97 | +application called ``app`` would be accessible via ``app.example.com``. |
| 98 | + |
| 99 | +One way to configure this on DigitalOcean is to setup round-robin DNS via the `DNS control panel`_. |
| 100 | +To do this, add the following records to your domain: |
| 101 | + |
| 102 | + - A wildcard CNAME record at your top-level domain, i.e. a CNAME record with * as the name, and @ |
| 103 | + as the canonical hostname |
| 104 | + - For each CoreOS machine created, an A-record that points to the TLD, i.e. an A-record named @, |
| 105 | + with the droplet's public IP address |
| 106 | + |
| 107 | +The zone file will now have the following entries in it: (your IP addresses will be different) |
| 108 | + |
| 109 | +.. code-block:: console |
| 110 | +
|
| 111 | + * CNAME @ |
| 112 | + @ IN A 104.131.93.162 |
| 113 | + @ IN A 104.131.47.125 |
| 114 | + @ IN A 104.131.113.138 |
| 115 | +
|
| 116 | +For convenience, you can also set up DNS records for each node: |
| 117 | + |
| 118 | +.. code-block:: console |
| 119 | +
|
| 120 | + deis-1 IN A 104.131.93.162 |
| 121 | + deis-2 IN A 104.131.47.125 |
| 122 | + deis-3 IN A 104.131.113.138 |
| 123 | +
|
| 124 | +If you need help using the DNS control panel, check out `this tutorial`_ on DigitalOcean's |
| 125 | +community site. |
| 126 | + |
| 127 | +Install Deis Control Utility |
| 128 | +---------------------------- |
| 129 | + |
| 130 | +Now that we have the CoreOS cluster set up, we will install the Deis Control Utility. This client |
| 131 | +will help us configure and install the platform on top of our CoreOS cluster. Please see |
| 132 | +:ref:`install_deisctl` for instructions. |
| 133 | + |
| 134 | +Install Deis Platform |
| 135 | +--------------------- |
| 136 | + |
| 137 | +From the computer you installed the Deis tools on, we will provision the Deis platform. Ensure your |
| 138 | +SSH agent is running (and select the private key that corresponds to the SSH keys added to your |
| 139 | +CoreOS droplets): |
| 140 | + |
| 141 | +.. code-block:: console |
| 142 | +
|
| 143 | + $ eval `ssh-agent -s` |
| 144 | + $ ssh-add ~/.ssh/deis |
| 145 | +
|
| 146 | +Find the public IP address of one of your CoreOS droplets, and export it to the DEISCTL_TUNNEL |
| 147 | +environment variable (substitute your own IP address): |
| 148 | + |
| 149 | +.. code-block:: console |
| 150 | +
|
| 151 | + $ export DEISCTL_TUNNEL=104.131.93.162 |
| 152 | +
|
| 153 | +If you set up the "convenience" DNS records, you can just refer to them via |
| 154 | + |
| 155 | +.. code-block:: console |
| 156 | +
|
| 157 | + $ export DEISCTL_TUNNEL="deis-1.example.com" |
| 158 | +
|
| 159 | +This is the IP address where deisctl will attempt to communicate with the cluster. You can test |
| 160 | +that it is working properly by running deisctl list. If you see a single line of output, the |
| 161 | +control utility is communicating with the CoreOS machines. |
| 162 | + |
| 163 | +Before provisioning the platform, we'll need to add the SSH key to deis so it can connect to remote |
| 164 | +hosts during ``deis run``: |
| 165 | + |
| 166 | +.. code-block:: console |
| 167 | +
|
| 168 | + $ deisctl config platform set sshPrivateKey=~/.ssh/deis |
| 169 | +
|
| 170 | +We'll also need to tell the controller which domain name we are deploying applications under: |
| 171 | + |
| 172 | +.. code-block:: console |
| 173 | +
|
| 174 | + $ deisctl config platform set domain=example.com |
| 175 | +
|
| 176 | +Once finished, run this command to provision the Deis platform: |
| 177 | + |
| 178 | +.. code-block:: console |
| 179 | +
|
| 180 | + $ deisctl install platform |
| 181 | +
|
| 182 | +You will see output like the following, which indicates that the units required to run Deis have |
| 183 | +been loaded on the CoreOS cluster: |
| 184 | + |
| 185 | +.. code-block:: console |
| 186 | +
|
| 187 | + ● ▴ ■ |
| 188 | + ■ ● ▴ Installing Deis... |
| 189 | + ▴ ■ ● |
| 190 | +
|
| 191 | + Scheduling data containers... |
| 192 | + ... |
| 193 | + Deis installed. |
| 194 | + Please run `deisctl start platform` to boot up Deis. |
| 195 | +
|
| 196 | +Run this command to start the Deis platform: |
| 197 | + |
| 198 | +.. code-block:: console |
| 199 | +
|
| 200 | + $ deisctl start platform |
| 201 | +
|
| 202 | +Once you see "Deis started.", your Deis platform is running on a cluster! You may verify that all |
| 203 | +of the Deis units are loaded and active by running the following command: |
| 204 | + |
| 205 | +.. code-block:: console |
| 206 | +
|
| 207 | + $ deisctl list |
| 208 | +
|
| 209 | +All of the units should be active. |
| 210 | + |
| 211 | +Now that you've finished provisioning a cluster, please refer to :ref:`using_deis` to get |
| 212 | +started using the platform. |
| 213 | + |
| 214 | + |
| 215 | +.. _`Community site`: https://www.digitalocean.com/community/tutorials/how-to-set-up-a-deis-cluster-on-digitalocean |
| 216 | +.. _`docl`: https://github.com/nathansamson/docl#readme |
| 217 | +.. _`Deis Control Utility`: https://github.com/deis/deis/tree/master/deisctl#readme |
| 218 | +.. _`DNS control panel`: https://cloud.digitalocean.com/domains |
| 219 | +.. _`etcd`: https://github.com/coreos/etcd |
| 220 | +.. _`this tutorial`: https://www.digitalocean.com/community/tutorials/how-to-set-up-a-host-name-with-digitalocean |
0 commit comments