Skip to content

Commit 8514a0e

Browse files
author
Matthew Fisher
committed
docs(installing_deis): import AWS provisioning docs
1 parent 9d18fc7 commit 8514a0e

5 files changed

Lines changed: 264 additions & 253 deletions

File tree

‎contrib/ec2/README.md‎

Lines changed: 2 additions & 165 deletions
Original file line numberDiff line numberDiff line change
@@ -1,166 +1,3 @@
1-
# Provision a Deis Cluster on Amazon EC2
1+
# Provision a Deis Cluster on Amazon AWS
22

3-
## Install the [AWS Command Line Interface][aws-cli]:
4-
```console
5-
$ pip install awscli
6-
Downloading/unpacking awscli
7-
Downloading awscli-1.5.0.tar.gz (248kB): 248kB downloaded
8-
...
9-
Successfully installed awscli
10-
```
11-
12-
## Configure aws-cli
13-
Run `aws configure` to set your AWS credentials:
14-
```console
15-
$ aws configure
16-
AWS Access Key ID [None]: ***************
17-
AWS Secret Access Key [None]: ************************
18-
Default region name [None]: us-west-1
19-
Default output format [None]:
20-
```
21-
22-
## Upload keys
23-
Generate and upload a new keypair to AWS, ensuring that the name of the keypair is set to "deis".
24-
```console
25-
$ ssh-keygen -q -t rsa -f ~/.ssh/deis -N '' -C deis
26-
$ aws ec2 import-key-pair --key-name deis --public-key-material file://~/.ssh/deis.pub
27-
```
28-
29-
## Choose number of instances
30-
By default, the script will provision 3 servers. You can override this by setting `DEIS_NUM_INSTANCES`:
31-
```console
32-
$ export DEIS_NUM_INSTANCES=5
33-
```
34-
35-
Note that for scheduling to work properly, clusters must consist of at least 3 nodes and always have an odd number of members.
36-
For more information, see [optimal etcd cluster size](https://github.com/coreos/etcd/blob/master/Documentation/optimal-cluster-size.md).
37-
38-
Deis clusters of less than 3 nodes are unsupported.
39-
40-
## Customize user-data
41-
42-
Create a user-data file with a new discovery URL this way:
43-
44-
```console
45-
$ make discovery-url
46-
```
47-
48-
Or copy [`contrib/coreos/user-data.example`](../coreos/user-data.example) to `contrib/coreos/user-data` and follow the directions in the `etcd:` section to add a unique discovery URL.
49-
50-
## Customize cloudformation.json
51-
Any of the parameter defaults defined in deis.template.json can be overridden
52-
by setting the value in [cloudformation.json](cloudformation.json) like so:
53-
54-
```
55-
{
56-
"ParameterKey": "InstanceType",
57-
"ParameterValue": "m3.xlarge"
58-
},
59-
{
60-
"ParameterKey": "KeyPair",
61-
"ParameterValue": "jsmith"
62-
},
63-
{
64-
"ParameterKey": "EC2VirtualizationType",
65-
"ParameterValue": "PV"
66-
},
67-
{
68-
"ParameterKey": "AssociatePublicIP",
69-
"ParameterValue": "false"
70-
}
71-
```
72-
73-
The only entry in cloudformation.json required to launch your cluster is `KeyPair`,
74-
which is already filled out. The defaults will be applied for the other settings.
75-
76-
If updated with update-ec2-cluster.sh, the InstanceType will only impact newly deployed instances (#1758).
77-
78-
NOTE: The smallest recommended instance size is `large`. Having not enough CPU or RAM will result
79-
in numerous issues when using the cluster.
80-
81-
## Launch into an existing VPC
82-
By default, the provided CloudFormation script will create a new VPC for Deis. However, the script
83-
supports provisioning into an existing VPC instead. You'll need to have a VPC configured with an
84-
internet gateway and a sane routing table (the default VPC in a region should be ready to go).
85-
86-
To launch your cluster into an existing VPC, export three additional environment variables: ```VPC_ID```,
87-
```VPC_SUBNETS```, ```VPC_ZONES```. ```VPC_ZONES``` must list the availability zones of the
88-
subnets in order.
89-
90-
For example, if your VPC has ID ```vpc-a26218bf``` and consists of the subnets ```subnet-04d7f942```
91-
(which is in ```us-east-1b```) and ```subnet-2b03ab7f``` (which is in ```us-east-1c```) you would
92-
export:
93-
94-
```
95-
export VPC_ID=vpc-a26218bf
96-
export VPC_SUBNETS=subnet-04d7f942,subnet-2b03ab7f
97-
export VPC_ZONES=us-east-1b,us-east-1c
98-
```
99-
100-
## Run the provision script
101-
Run the [cloudformation provision script][pro-script] to spawn a new CoreOS cluster:
102-
```console
103-
$ cd contrib/ec2
104-
$ ./provision-ec2-cluster.sh
105-
{
106-
"StackId": "arn:aws:cloudformation:us-west-1:413516094235:stack/deis/9699ec20-c257-11e3-99eb-50fa01cd4496"
107-
}
108-
Your Deis cluster has successfully deployed.
109-
Please wait for all instances to come up as "running" before continuing.
110-
```
111-
112-
Check the AWS EC2 web control panel and wait until "Status Checks" for all instances have passed.
113-
This will take several minutes.
114-
115-
## Configure Deis
116-
Set the default domain used to anchor your applications:
117-
118-
```console
119-
$ deisctl config platform set domain=mycluster.local
120-
```
121-
122-
For this to work, you'll need to configure DNS records so you can access applications hosted on Deis. See [Configuring DNS](http://docs.deis.io/en/latest/installing_deis/configure-dns/) for details.
123-
124-
If you want to allow `deis run` for one-off admin commands, you must provide an SSH private key that allows Deis to gather container logs on CoreOS hosts:
125-
126-
```console
127-
$ deisctl config platform set sshPrivateKey=<path-to-private-key>
128-
```
129-
130-
## Initialize the cluster
131-
Once the cluster is up, get the hostname of any of the machines from EC2, set
132-
DEISCTL_TUNNEL, and issue a `deisctl install`:
133-
```console
134-
$ ssh-add ~/.ssh/deis
135-
$ export DEISCTL_TUNNEL=ec2-12-345-678-90.us-west-1.compute.amazonaws.com
136-
$ deisctl install platform && deisctl start platform
137-
```
138-
Deisctl will deploy Deis and make sure the services start properly.
139-
140-
## Configure load balancer
141-
The Deis provisioning scripts for EC2 automatically create an Elastic Load Balancer for your Deis
142-
cluster. However, ELBs on EC2 have a default timeout of 60 seconds, which will disrupt a ``git push``
143-
when using Deis. You should manually [increase this timeout](http://docs.aws.amazon.com/ElasticLoadBalancing/latest/DeveloperGuide/config-idle-timeout.html)
144-
to 1200 seconds to match the timeout on the router and application unit files.
145-
146-
## Configure DNS
147-
While you can reference the controller and hosted applications with public hostnames provided by EC2, it is recommended for ease-of-use that
148-
you configure your own DNS records using a domain you own. See [Configuring DNS](http://docs.deis.io/en/latest/installing_deis/configure-dns/) for details.
149-
150-
## Use Deis!
151-
After that, register with Deis!
152-
```console
153-
$ deis register http://deis.example.org
154-
username: deis
155-
password:
156-
password (confirm):
157-
email: info@opdemand.com
158-
```
159-
160-
## Hack on Deis
161-
162-
See [Hacking on Deis](http://docs.deis.io/en/latest/contributing/hacking/).
163-
164-
[aws-cli]: https://github.com/aws/aws-cli
165-
[template]: https://s3.amazonaws.com/coreos.com/dist/aws/coreos-alpha.template
166-
[pro-script]: provision-ec2-cluster.sh
3+
Please refer to the instructions at http://docs.deis.io/en/latest/installing_deis/aws.

‎docs/installing_deis/aws.rst‎

Lines changed: 171 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -6,12 +6,178 @@
66
Amazon AWS
77
==========
88

9-
The `contrib/ec2` section of the Deis project includes shell scripts,
10-
documentation, and a customized CloudFormation template to make it easy
11-
to provision a multi-node Deis cluster on `Amazon AWS`_.
9+
In this tutorial, we will show you how to set up your own 3-node cluster on Amazon Web Services.
1210

13-
Please see `contrib/ec2`_ for details on using Deis on Amazon AWS.
11+
Please use `contrib/ec2`_ while following this documentation for details on using Deis on aws.
1412

1513

16-
.. _`Amazon EC2`: https://github.com/deis/deis/tree/master/contrib/ec2#readme
14+
Install the AWS Command Line Interface
15+
--------------------------------------
16+
17+
In order to start working with Amazon's API, let's install `awscli`_:
18+
19+
.. code-block:: console
20+
21+
$ pip install awscli
22+
Downloading/unpacking awscli
23+
Downloading awscli-1.5.0.tar.gz (248kB): 248kB downloaded
24+
...
25+
Successfully installed awscli
26+
27+
28+
Configure aws-cli
29+
-----------------
30+
31+
Run ``aws configure`` to set your AWS credentials:
32+
33+
34+
.. code-block:: console
35+
36+
$ aws configure
37+
AWS Access Key ID [None]: ***************
38+
AWS Secret Access Key [None]: ************************
39+
Default region name [None]: us-west-1
40+
Default output format [None]:
41+
42+
43+
Upload keys
44+
-----------
45+
46+
Generate and upload a new keypair to AWS, ensuring that the name of the keypair is set to "deis".
47+
48+
.. code-block:: console
49+
50+
$ ssh-keygen -q -t rsa -f ~/.ssh/deis -N '' -C deis
51+
$ aws ec2 import-key-pair --key-name deis --public-key-material file://~/.ssh/deis.pub
52+
53+
54+
Choose Number of Instances
55+
--------------------------
56+
57+
By default, the script will provision 3 servers. You can override this by setting
58+
``DEIS_NUM_INSTANCES``:
59+
60+
.. code-block:: console
61+
62+
$ export DEIS_NUM_INSTANCES=5
63+
64+
Note that for scheduling to work properly, clusters must consist of at least 3 nodes and always
65+
have an odd number of members. For more information, see `optimal etcd cluster size`_.
66+
67+
Deis clusters of less than 3 nodes are unsupported.
68+
69+
70+
Generate a New Discovery URL
71+
----------------------------
72+
73+
To get started with provisioning Deis, we will need to generate a new Discovery URL. Discovery URLs
74+
help connect `etcd`_ instances together by storing a list of peer addresses and metadata under a
75+
unique address. You can generate a new discovery URL for use in your platform by
76+
running the following from the root of the repository:
77+
78+
.. code-block:: console
79+
80+
$ make discovery-url
81+
82+
This will write a new discovery URL to the user-data file. Some convenience scripts are supplied in
83+
this user-data file, so it is mandatory for provisioning Deis.
84+
85+
86+
Customize cloudformation.json
87+
-----------------------------
88+
89+
Any of the parameter defaults defined in deis.template.json can be overridden by setting the value
90+
in `cloudformation.json`_ like so:
91+
92+
.. code-block:: console
93+
94+
{
95+
"ParameterKey": "InstanceType",
96+
"ParameterValue": "m3.xlarge"
97+
},
98+
{
99+
"ParameterKey": "KeyPair",
100+
"ParameterValue": "jsmith"
101+
},
102+
{
103+
"ParameterKey": "EC2VirtualizationType",
104+
"ParameterValue": "PV"
105+
},
106+
{
107+
"ParameterKey": "AssociatePublicIP",
108+
"ParameterValue": "false"
109+
}
110+
111+
The only entry in cloudformation.json required to launch your cluster is `KeyPair`, which is
112+
already filled out. The defaults will be applied for the other settings.
113+
114+
If updated with update-ec2-cluster.sh, the InstanceType will only impact newly deployed instances
115+
(`#1758`_).
116+
117+
NOTE: The smallest recommended instance size is `large`. Having not enough CPU or RAM will result
118+
in numerous issues when using the cluster.
119+
120+
121+
Launch into an existing VPC
122+
---------------------------
123+
124+
By default, the provided CloudFormation script will create a new VPC for Deis. However, the script
125+
supports provisioning into an existing VPC instead. You'll need to have a VPC configured with an
126+
internet gateway and a sane routing table (the default VPC in a region should be ready to go).
127+
128+
To launch your cluster into an existing VPC, export three additional environment variables:
129+
130+
- ``VPC_ID``
131+
- ``VPC_SUBNETS``
132+
- ``VPC_ZONES``
133+
134+
``VPC_ZONES`` must list the availability zones of the subnets in order.
135+
136+
For example, if your VPC has ID ``vpc-a26218bf`` and consists of the subnets ``subnet-04d7f942``
137+
(which is in ``us-east-1b``) and ``subnet-2b03ab7f`` (which is in ``us-east-1c``) you would export:
138+
139+
.. code-block:: console
140+
141+
export VPC_ID=vpc-a26218bf
142+
export VPC_SUBNETS=subnet-04d7f942,subnet-2b03ab7f
143+
export VPC_ZONES=us-east-1b,us-east-1c
144+
145+
146+
Run the Provision Script
147+
------------------------
148+
149+
Run the cloudformation provision script to spawn a new CoreOS cluster:
150+
151+
.. code-block:: console
152+
153+
$ cd contrib/ec2
154+
$ ./provision-ec2-cluster.sh
155+
{
156+
"StackId": "arn:aws:cloudformation:us-west-1:413516094235:stack/deis/9699ec20-c257-11e3-99eb-50fa01cd4496"
157+
}
158+
Your Deis cluster has successfully deployed.
159+
Please wait for all instances to come up as "running" before continuing.
160+
161+
Check the AWS EC2 web control panel and wait until "Status Checks" for all instances have passed.
162+
This will take several minutes.
163+
164+
165+
Configure DNS
166+
-------------
167+
168+
See :ref:`configure-dns` for more information on properly setting up your DNS records with Deis.
169+
170+
171+
Install Deis Platform
172+
---------------------
173+
174+
Now that you've finished provisioning a cluster, please refer to :ref:`install_deis_platform` to
175+
start installing the platform.
176+
177+
178+
.. _`#1758`: https://github.com/deis/deis/issues/1758
179+
.. _`awscli`: https://github.com/aws/aws-cli
17180
.. _`contrib/ec2`: https://github.com/deis/deis/tree/master/contrib/ec2
181+
.. _`cloudformation.json`: https://github.com/deis/deis/blob/master/contrib/ec2/cloudformation.json
182+
.. _`etcd`: https://github.com/coreos/etcd
183+
.. _`optimal etcd cluster size`: https://github.com/coreos/etcd/blob/master/Documentation/optimal-cluster-size.md

0 commit comments

Comments
 (0)