Skip to content

Commit a71a618

Browse files
carmstrongcarmstrong
committed
Merge pull request #2783 from carmstrong/pr-2604
OpenStack: fix instructions and move to docs site
2 parents 6c88567 + 240e0b7 commit a71a618

5 files changed

Lines changed: 209 additions & 130 deletions

File tree

‎contrib/openstack/README.md‎

Lines changed: 1 addition & 124 deletions
Original file line numberDiff line numberDiff line change
@@ -1,126 +1,3 @@
11
# Provision a Deis Cluster on OpenStack
22

3-
**NOTE**
4-
OpenStack support for Deis was contributed by @shakim. OpenStack support is untested by the Deis team, so we rely on the community to improve these scripts and to fix bugs.
5-
We greatly appreciate the help!
6-
7-
### Prerequisites:
8-
Make sure that the following utilities are installed and in your execution path:
9-
- nova
10-
- neutron
11-
12-
### Configure nova
13-
Create an `openrc.sh` file to match the following:
14-
```
15-
[production]
16-
OS_AUTH_URL = {openstack_auth_url}
17-
OS_USERNAME = {openstack_username}
18-
OS_PASSWORD = {openstack_api_key}
19-
OS_TENANT_ID = {openstack_tenant_id}
20-
OS_TENANT_NAME = {openstack_tenant_name}
21-
```
22-
23-
(Alternatively, download OpenStack RC file from Horizon/Access & Security/API Access.)
24-
25-
Source your nova credentials:
26-
27-
```console
28-
# source openrc.sh
29-
```
30-
31-
### Set up your keys
32-
Choose an existing keypair or upload a new public key, if desired.
33-
34-
```console
35-
$ nova keypair-add --pub-key ~/.ssh/deis.pub deis-key
36-
```
37-
38-
### Customize user-data
39-
40-
Create a user-data file with a new discovery URL this way:
41-
42-
```console
43-
$ make discovery-url
44-
```
45-
46-
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.
47-
48-
### Choose number of instances
49-
By default, the provision script will provision 3 servers. You can override this by setting `DEIS_NUM_INSTANCES`:
50-
```console
51-
$ DEIS_NUM_INSTANCES=5 ./provision-openstack-cluster.sh deis-key
52-
```
53-
54-
Note that for scheduling to work properly, clusters must consist of at least 3 nodes and always have an odd number of members.
55-
For more information, see [optimal etcd cluster size](https://github.com/coreos/etcd/blob/master/Documentation/optimal-cluster-size.md).
56-
57-
Deis clusters of less than 3 nodes are unsupported.
58-
59-
### Deis network settings
60-
The script creates a private network called 'deis' if no such network exists.
61-
62-
By default, the deis subnet IP range is set to 10.21.12.0/24. To override it and the default DNS settings, set the following variables:
63-
```console
64-
$ export DEIS_CIDR=10.21.12.0/24
65-
$ export DEIS_DNS=10.21.12.3,8.8.8.8
66-
```
67-
68-
**_Please note that this script does not handle floating IPs or routers. These should be provisioned manually either by Horizon or CLI_**
69-
70-
### Run the provision script
71-
Run the [Openstack provision script](provision-openstack-cluster.sh) to spawn a new CoreOS cluster.
72-
You'll need to provide the name of the CoreOS image name (or ID), and the key pair you just added. Optionally, you can also specify a flavor name.
73-
```console
74-
$ cd contrib/openstack
75-
$ ./provision-openstack-cluster.sh
76-
Usage: provision-openstack-cluster.sh <coreos image name/id> <key pair name> [flavor]
77-
$ ./provision-openstack-cluster.sh coreos deis-key
78-
```
79-
80-
### Choose number of routers
81-
By default, the Makefile will provision 1 router. You can override this by setting `DEIS_NUM_ROUTERS`:
82-
```console
83-
$ export DEIS_NUM_ROUTERS=2
84-
```
85-
86-
## Configure Deis
87-
Set the default domain used to anchor your applications:
88-
89-
```console
90-
$ deisctl config platform set domain=mycluster.local
91-
```
92-
93-
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/managing_deis/configure-dns/#dns-records) for details.
94-
95-
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:
96-
97-
```console
98-
$ deisctl config platform set sshPrivateKey=<path-to-private-key>
99-
```
100-
101-
### Initialize the cluster
102-
Once the cluster is up:
103-
* **If required, allocate and associate floating IPs to any or all of your hosts**
104-
* Get the IP address of any of the machines from Openstack
105-
* set DEISCTL_TUNNEL and install the platform:
106-
107-
```console
108-
$ export DEISCTL_TUNNEL=23.253.219.94
109-
$ deisctl install platform && deisctl start platform
110-
```
111-
112-
The installer will deploy Deis and make sure the services start properly.
113-
114-
### Use Deis!
115-
After that, register with Deis!
116-
```console
117-
$ deis register http://deis.example.org
118-
username: deis
119-
password:
120-
password (confirm):
121-
email: info@opdemand.com
122-
```
123-
124-
## Hack on Deis
125-
126-
See [Hacking on Deis](http://docs.deis.io/en/latest/contributing/hacking/).
3+
Please refer to the instructions at http://docs.deis.io/en/latest/installing_deis/openstack/.

‎contrib/openstack/provision-openstack-cluster.sh‎

Lines changed: 18 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -5,11 +5,14 @@
55
# Supported environment variables:
66
# DEIS_DNS: Comma separated list of names servers for use in the deis private network (default: none)
77
# DEIS_NUM_INSTANCES: Number of instances to create (default: 3)
8+
# DEIS_NETWORK: name of neutron network to use.
89

910
set -e
1011

1112
THIS_DIR=$(cd $(dirname $0); pwd) # absolute path
1213
CONTRIB_DIR=$(dirname $THIS_DIR)
14+
DEIS_NETWORK=${DEIS_NETWORK:-deis}
15+
DEIS_SECGROUP=${DEIS_SECGROUP:-deis}
1316

1417
source $CONTRIB_DIR/utils.sh
1518

@@ -41,18 +44,25 @@ if [ -z "$OS_AUTH_URL" ]; then
4144
exit 1
4245
fi
4346

44-
if ! nova network-list|grep -q deis &>/dev/null; then
47+
if neutron net-list|grep -q $DEIS_NETWORK &>/dev/null; then
48+
NETWORK_ID=$(neutron net-list | grep internal | awk -F'| ' '{print $2}')
49+
else
4550
echo_yellow "Creating deis private network..."
4651
CIDR=${DEIS_CIDR:-10.21.12.0/24}
4752
SUBNET_OPTIONS=""
4853
[ ! -z "$DEIS_DNS" ] && SUBNET_OPTIONS=$(echo $DEIS_DNS|awk -F "," '{for (i=1; i<=NF; i++) printf "--dns-nameserver %s ", $i}')
49-
NETWORK_ID=$(neutron net-create deis | awk '{ printf "%s", ($2 == "id" ? $4 : "")}')
54+
NETWORK_ID=$(neutron net-create $DEIS_NETWORK | awk '{ printf "%s", ($2 == "id" ? $4 : "")}')
5055
echo "DBG: SUBNET_OPTIONS=$SUBNET_OPTIONS"
51-
SUBNET_ID=$(neutron subnet-create --name deis_subnet $SUBNET_OPTIONS deis $CIDR| awk '{ printf "%s", ($2 == "id" ? $4 : "")}')
52-
else
53-
NETWORK_ID=$(neutron net-list | awk '{printf "%s", ($4 == "deis" ? $2 : "")}')
56+
SUBNET_ID=$(neutron subnet-create --name deis_subnet $SUBNET_OPTIONS $NETWORK_ID $CIDR| awk '{ printf "%s", ($2 == "id" ? $4 : "")}')
5457
fi
5558

59+
if ! neutron security-group-list | grep -q $DEIS_SECGROUP &>/dev/null; then
60+
neutron security-group-create $DEIS_SECGROUP
61+
neutron security-group-rule-create --protocol tcp --remote-ip-prefix 0/0 --port-range-min 22 --port-range-max 22 $DEIS_SECGROUP
62+
neutron security-group-rule-create --protocol tcp --remote-ip-prefix 0/0 --port-range-min 2222 --port-range-max 22222 $DEIS_SECGROUP
63+
neutron security-group-rule-create --protocol tcp --remote-ip-prefix 0/0 --port-range-min 80 --port-range-max 80 $DEIS_SECGROUP
64+
neutron security-group-rule-create --protocol icmp --remote-ip-prefix 0/0 $DEIS_SECGROUP
65+
fi
5666

5767
if [ -z "$DEIS_NUM_INSTANCES" ]; then
5868
DEIS_NUM_INSTANCES=3
@@ -63,7 +73,9 @@ $CONTRIB_DIR/util/check-user-data.sh
6373

6474
i=1 ; while [[ $i -le $DEIS_NUM_INSTANCES ]] ; do \
6575
echo_yellow "Provisioning deis-$i..."
66-
nova boot --image $COREOS_IMAGE --flavor $FLAVOR --key-name $KEYPAIR --user-data ../coreos/user-data --nic net-id=$NETWORK_ID deis-$i ; \
76+
nova boot --image $COREOS_IMAGE --flavor $FLAVOR --key-name $KEYPAIR \
77+
--security-groups $DEIS_SECGROUP --user-data ../coreos/user-data \
78+
--nic net-id=$NETWORK_ID deis-$i ; \
6779
((i = i + 1)) ; \
6880
done
6981

‎docs/installing_deis/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,7 @@ with CoreOS.
2828
rackspace
2929
vagrant
3030
baremetal
31+
openstack
3132
install-deisctl
3233
install-platform
3334

‎docs/installing_deis/openstack.rst‎

Lines changed: 188 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,188 @@
1+
:title: Installing Deis on OpenStack
2+
:description: How to provision a multi-node Deis cluster on OpenStack
3+
4+
.. _deis_on_openstack:
5+
6+
OpenStack
7+
=========
8+
9+
Please :ref:`get the source <get_the_source>` and refer to the scripts in `contrib/openstack`_
10+
while following this documentation.
11+
12+
.. important::
13+
14+
OpenStack support for Deis was originally contributed by `Shlomo Hakim`_ and has been updated
15+
by Deis community members. OpenStack support is untested by the Deis team, so we rely on
16+
the community to improve this documentation and to fix bugs. We greatly appreciate the help!
17+
18+
19+
Check System Requirements
20+
-------------------------
21+
22+
Please refer to :ref:`system-requirements` for resource considerations when choosing a machine
23+
size to run Deis.
24+
25+
Prerequisites
26+
-------------
27+
28+
Make sure that the following utilities are installed and in your execution path:
29+
30+
* nova
31+
* neutron
32+
* glance
33+
34+
Configure OpenStack
35+
-------------------
36+
37+
Create an ``openrc.sh`` file to match the following:
38+
39+
.. code-block:: console
40+
41+
$ export OS_AUTH_URL={openstack_auth_url}
42+
$ export OS_USERNAME={openstack_username}
43+
$ export OS_PASSWORD={openstack_password}
44+
$ export OS_TENANT_NAME={openstack_tenant_name}
45+
46+
47+
(Alternatively, download OpenStack RC file from Horizon/Access & Security/API Access.)
48+
49+
Source your nova credentials:
50+
51+
.. code-block:: console
52+
53+
$ source openrc.sh
54+
55+
56+
Set up your keys
57+
----------------
58+
59+
Choose an existing keypair or upload a new public key, if desired.
60+
61+
.. code-block:: console
62+
63+
$ nova keypair-add --pub-key ~/.ssh/deis.pub deis-key
64+
65+
66+
Upload a CoreOS image to Glance
67+
-------------------------------
68+
69+
You need to have a relatively recent CoreOS image.
70+
71+
.. important::
72+
73+
Deis runs on CoreOS version 494.5.0 or later in the Stable channel.
74+
75+
If you don't already have a suitable CoreOS image and your OpenStack install allows you to upload
76+
your own images, the following snippet will use the latest CoreOS image from the stable channel:
77+
78+
.. code-block:: console
79+
80+
$ wget http://stable.release.core-os.net/amd64-usr/current/coreos_production_openstack_image.img.bz2
81+
$ bunzip2 coreos_production_openstack_image.img.bz2
82+
$ glance image-create --name coreos \
83+
--container-format bare \
84+
--disk-format qcow2 \
85+
--file coreos_production_openstack_image.img \
86+
--is-public True
87+
88+
89+
Generate a New Discovery URL
90+
----------------------------
91+
92+
.. include:: ../_includes/_generate-discovery-url.rst
93+
94+
95+
Choose number of instances
96+
--------------------------
97+
98+
For scheduling to work properly, clusters must consist of at least 3 nodes and always have an odd
99+
number of members. Please refer to :ref:`system-requirements` for more information about cluster
100+
size requirements.
101+
102+
Instruct the provision script to launch the desired number of nodes:
103+
104+
.. code-block:: console
105+
106+
$ export DEIS_NUM_INSTANCES=3
107+
108+
109+
Deis network settings
110+
---------------------
111+
112+
The script creates a private network called 'deis' if no such network exists.
113+
114+
By default, the deis subnet IP range is set to 10.21.12.0/24. To override it and the default
115+
DNS settings, set the following variables:
116+
117+
.. code-block:: console
118+
119+
$ export DEIS_CIDR=10.21.12.0/24
120+
$ export DEIS_DNS=10.21.12.3,8.8.8.8
121+
122+
.. note::
123+
124+
This script does not handle floating IPs or routers. These should be provisioned manually by
125+
either Horizon or the CLI.
126+
127+
128+
Run the provision script
129+
------------------------
130+
131+
If you have a fairly straightforward OpenStack install, you should be able to use the provided
132+
provisioning script. This script assumes you are using neutron and have security-groups enabled.
133+
134+
Run the ``provision-openstack-cluster.sh`` to spawn a new CoreOS cluster. You'll need to provide
135+
the name of the CoreOS image name (or ID), and the key pair you just added. Optionally, you can also
136+
specify a flavor name.
137+
138+
.. code-block:: console
139+
140+
$ cd contrib/openstack
141+
$ ./provision-openstack-cluster.sh
142+
Usage: provision-openstack-cluster.sh <coreos image name/id> <key pair name> [flavor]
143+
$ ./provision-openstack-cluster.sh coreos deis-key
144+
145+
146+
You can override the name of the internal network to use by setting the environment variable
147+
``DEIS_NETWORK=internal``. If this doesn't exist the script will try to create it with the default
148+
CIDR which requires your OpenStack cluster to support tenant VLANs.
149+
150+
You can also override the name of the security group to attach to the instances by setting
151+
``DEIS_SECGROUP=deis_test``. If this doesn't exist the script will attempt to create it.
152+
If you are creating your own security groups you can use the provision script as a guide. Make sure
153+
that you have a rule to enable full communication inside the security group, or you will have a bad day.
154+
155+
Manually start the instances
156+
----------------------------
157+
158+
Start the instances and ensure they're operational before continuing.
159+
160+
Configure floating IPs
161+
----------------------
162+
163+
You will want to attach a floating IP to at least one of your instances. You'll do that like this:
164+
165+
.. code-block:: console
166+
167+
$ nova floating-ip-create <pool>
168+
$ nova floating-ip-associate deis-1 <IP provided by above command>
169+
170+
Deploy a load balancer
171+
----------------------
172+
173+
It is recommended that you deploy a load balancer for user requests to your Deis cluster.
174+
See :ref:`configure-load-balancers` for more details on using load balancers with Deis.
175+
176+
Configure DNS
177+
-------------
178+
179+
See :ref:`configure-dns` for more information on properly setting up your DNS records with Deis.
180+
181+
Install Deis Platform
182+
---------------------
183+
184+
Now that you've finished provisioning a cluster, please refer to :ref:`install_deis_platform` to
185+
start installing the platform.
186+
187+
.. _`contrib/openstack`: https://github.com/deis/deis/tree/master/contrib/openstack
188+
.. _`Shlomo Hakim`: https://github.com/shakim

‎docs/installing_deis/quick-start.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -49,6 +49,7 @@ Choose one of the following providers and deploy a new cluster:
4949
- :ref:`deis_on_rackspace`
5050
- :ref:`deis_on_vagrant`
5151
- :ref:`deis_on_bare_metal`
52+
- :ref:`deis_on_openstack`
5253

5354

5455
Configure DNS

0 commit comments

Comments
 (0)