Skip to content

Commit 240e0b7

Browse files
carmstrongcarmstrong
committed
docs(openstack): move OpenStack docs to docs site
1 parent 0351b99 commit 240e0b7

4 files changed

Lines changed: 191 additions & 159 deletions

File tree

‎contrib/openstack/README.md‎

Lines changed: 1 addition & 159 deletions
Original file line numberDiff line numberDiff line change
@@ -1,161 +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-
- glance
12-
13-
### Install Deis CLI tools
14-
15-
```console
16-
$ sudo pip install deis
17-
$ curl -sSL http://deis.io/deisctl/install.sh | sh -s 1.0.1
18-
$ mv deisctl /usr/local/bin
19-
$ chmod +x /usr/local/bin/deisctl
20-
```
21-
22-
### Configure openstack
23-
Create an `openrc.sh` file to match the following:
24-
```
25-
export OS_AUTH_URL={openstack_auth_url}
26-
export OS_USERNAME={openstack_username}
27-
export OS_PASSWORD={openstack_password}
28-
export OS_TENANT_NAME={openstack_tenant_name}
29-
```
30-
31-
(Alternatively, download OpenStack RC file from Horizon/Access & Security/API Access.)
32-
33-
Source your nova credentials:
34-
35-
```console
36-
$ source openrc.sh
37-
```
38-
39-
### Set up your keys
40-
Choose an existing keypair or upload a new public key, if desired.
41-
42-
```console
43-
$ nova keypair-add --pub-key ~/.ssh/deis.pub deis-key
44-
```
45-
46-
### Upload a coreos image to Glance
47-
48-
You need to have a relatively recent CoreOS image. If you don't have one and your Openstack install allows you to upload your own images you can do the following:
49-
50-
```console
51-
$ wget http://alpha.release.core-os.net/amd64-usr/current/coreos_production_openstack_image.img.bz2
52-
$ bunzip2 coreos_production_openstack_image.img.bz2
53-
$ glance image-create --name coreos \
54-
--container-format bare \
55-
--disk-format qcow2 \
56-
--file coreos_production_openstack_image.img \
57-
--is-public True
58-
```
59-
60-
### Customize user-data
61-
62-
Create a user-data file with a new discovery URL this way:
63-
64-
```console
65-
$ make discovery-url
66-
```
67-
68-
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.
69-
70-
### Choose number of instances and routers
71-
72-
```console
73-
$ export DEIS_NUM_INSTANCES=3
74-
$ export DEIS_NUM_ROUTERS=1
75-
```
76-
77-
Note that for scheduling to work properly, clusters must consist of at least 3 nodes and always have an odd number of members.
78-
For more information, see [optimal etcd cluster size](https://github.com/coreos/etcd/blob/master/Documentation/optimal-cluster-size.md).
79-
80-
Deis clusters of less than 3 nodes are unsupported.
81-
82-
### Deis network settings
83-
The script creates a private network called 'deis' if no such network exists.
84-
85-
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:
86-
87-
```console
88-
$ export DEIS_CIDR=10.21.12.0/24
89-
$ export DEIS_DNS=10.21.12.3,8.8.8.8
90-
```
91-
92-
**_Please note that this script does not handle floating IPs or routers. These should be provisioned manually either by Horizon or CLI_**
93-
94-
### Run the provision script
95-
96-
If you have a fairly straight forward openstack install you should be able to use the provisioning script provided. This script assumes you are using neutron and have security-groups enabled.
97-
98-
Run the [Openstack provision script](provision-openstack-cluster.sh) to spawn a new CoreOS cluster.
99-
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.
100-
```console
101-
$ cd contrib/openstack
102-
$ ./provision-openstack-cluster.sh
103-
Usage: provision-openstack-cluster.sh <coreos image name/id> <key pair name> [flavor]
104-
$ ./provision-openstack-cluster.sh coreos deis-key
105-
```
106-
107-
You can override the name of the internal network to use by setting the environment variable `DEIS_NETWORK=internal`. If this doesn't exist the script will try to create it with the default CIDR which requires your openstack cluster to support tenant vlans.
108-
109-
You can also override the name of the security group to attach to the instances by setting `DEIS_SECGROUP=deis_test`. If this doesn't exist the script will attempt to create it. If you are creating your own security groups you can use the provision script as a guide. Make sure that you have a rule to enable full communication inside the security group, or you will have a bad day.
110-
111-
### Manually start the instances
112-
113-
### Finish of your openstack configuration by setting up floating IPs.
114-
115-
You will want to attach a floating ip to at least one of your instances. You'll do that like this:
116-
117-
```
118-
$ nova floating-ip-create <pool>
119-
$ nova floating-ip-associate deis-1 <IP provided by above command>
120-
```
121-
122-
### Initialize the cluster
123-
Once the cluster is up:
124-
* **If required, allocate and associate floating IPs to any or all of your hosts**
125-
* Get the IP address of any of the machines from Openstack
126-
* Set the default domain used to anchor your applications:
127-
128-
```console
129-
$ deisctl config platform set domain=mycluster.local
130-
```
131-
132-
** 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.
133-
134-
* 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:
135-
136-
```console
137-
$ deisctl config platform set sshPrivateKey=<path-to-private-key>
138-
```
139-
140-
* set DEISCTL_TUNNEL to one of your floating IPs and install the platform:
141-
142-
```console
143-
$ export DEISCTL_TUNNEL=<Floating IP>
144-
$ deisctl install platform && deisctl start platform
145-
```
146-
147-
The installer will deploy Deis and make sure the services start properly.
148-
149-
### Use Deis!
150-
After that, register with Deis!
151-
```console
152-
$ deis register http://deis.example.org
153-
username: deis
154-
password:
155-
password (confirm):
156-
email: info@opdemand.com
157-
```
158-
159-
## Hack on Deis
160-
161-
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/.

‎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)