Skip to content

Commit c4eed9c

Browse files
author
Matthew Fisher
committed
Merge pull request #2360 from bacongobbler/baremetal-docs-import
docs(installing_deis): import baremetal docs
2 parents 584fc6b + 9b36518 commit c4eed9c

2 files changed

Lines changed: 162 additions & 126 deletions

File tree

‎contrib/bare-metal/README.md‎

Lines changed: 1 addition & 121 deletions
Original file line numberDiff line numberDiff line change
@@ -1,123 +1,3 @@
11
# Provision a Deis Cluster on bare-metal hardware
22

3-
Deis clusters can be provisioned anywhere [CoreOS](https://coreos.com/) can, including on your own hardware. To get CoreOS running on raw hardware, you can boot with [PXE](https://coreos.com/docs/running-coreos/bare-metal/booting-with-pxe/) or [iPXE](https://coreos.com/docs/running-coreos/bare-metal/booting-with-ipxe/) - this will boot a CoreOS machine running entirely from RAM. Then, you can [install CoreOS to disk](https://coreos.com/docs/running-coreos/bare-metal/installing-to-disk/).
4-
5-
## Generate SSH key
6-
To avoid problems deploying/launching apps later on it is necessary to install [CoreOS](https://coreos.com/) to disk with a SSH key without a passphrase. The following command will generate a new keypair named "deis".
7-
8-
```console
9-
$ ssh-keygen -q -t rsa -f ~/.ssh/deis -N '' -C deis
10-
```
11-
12-
## Customize user-data
13-
14-
### Discovery URL
15-
16-
Create a user-data file with a new discovery URL this way:
17-
18-
```console
19-
$ make discovery-url
20-
```
21-
22-
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.
23-
24-
### SSH Key
25-
Add the public key part for the SSH key generated in the first step to the [user-data](../coreos/user-data) file:
26-
27-
```yaml
28-
ssh_authorized_keys:
29-
- ssh-rsa AAAAB3... deis
30-
```
31-
32-
### Update $private_ipv4
33-
[CoreOS](https://coreos.com/) on bare metal doesn't detect the `$private_ipv4` reliably. Replace all occurences in the [user-data](../coreos/user-data) with the (private) IP address of the node.
34-
35-
### Add environment
36-
Since [CoreOS](https://coreos.com/) doesn't detect private and public IP adresses the `/etc/environment` file doesn't get written on boot. Add it to the `write_files` section of [user-data](../coreos/user-data)
37-
38-
```yaml
39-
- path: /etc/environment
40-
permissions: 0644
41-
content: |
42-
COREOS_PUBLIC_IPV4=<your public ip>
43-
COREOS_PRIVATE_IPV4=<your private ip>
44-
```
45-
46-
## Install CoreOS to disk
47-
Assuming you have booted your bare metal server into [CoreOS](https://coreos.com/) you can perform now perform the installation to disk.
48-
49-
### Provide the config file to the installer
50-
Save the [user-data](../coreos/user-data) to your bare metal machine. The example assumes you transferred the config to `/tmp/config`
51-
52-
### Start the installation
53-
```console
54-
coreos-install -C alpha -c /tmp/config -d /dev/sda
55-
```
56-
57-
This will install the current [CoreOS](https://coreos.com/) release to disk. If you want to install the recommended [CoreOS](https://coreos.com/) version check the [Deis changelog](../../CHANGELOG.md)
58-
and specify that version by appending the `-V` parameter to the install command, e.g. `-V 472.0.0`.
59-
60-
After the installation has finished reboot your server. Once your machine is back up you should be able to log in as the `core` user using the `deis` ssh key.
61-
62-
## Configure Deis
63-
Set the default domain used to anchor your applications:
64-
65-
```console
66-
$ deisctl config platform set domain=mycluster.local
67-
```
68-
69-
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.
70-
71-
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:
72-
73-
```console
74-
$ deisctl config platform set sshPrivateKey=<path-to-private-key>
75-
```
76-
77-
## Initialize the cluster
78-
Once your server(s) are all provisioned you can proceed to install Deis. Use the hostname of one of your machines in the next step.
79-
80-
```console
81-
$ ssh-add ~/.ssh/deis
82-
$ export DEISCTL_TUNNEL=your.server.name.here
83-
$ deisctl install platform && deisctl start platform
84-
```
85-
86-
## Use Deis!
87-
After that, register with Deis!
88-
```console
89-
$ deis register http://deis.example.org
90-
username: deis
91-
password:
92-
password (confirm):
93-
email: info@opdemand.com
94-
```
95-
96-
## Considerations when deploying Deis:
97-
* Use machines with ample disk space and RAM (we use [large instances](https://aws.amazon.com/ec2/instance-types/) on EC2, for comparison)
98-
* Choose an appropriate [cluster size](https://github.com/coreos/etcd/blob/master/Documentation/optimal-cluster-size.md)
99-
100-
## Known problems
101-
102-
### Hostname is localhost
103-
If your hostname after installation to disk is `localhost` set the hostname in [user-data](../coreos/user-data) before installation:
104-
105-
```yaml
106-
hostname: your-hostname
107-
```
108-
109-
The hostname must not be the fully qualified domain name!
110-
111-
### Slow name resolution
112-
113-
Certain DNS servers and firewalls have problems with glibc sending out requests for IPv4 and IPv6 addresses in parallel. The solution is to set the option `single-request` in `/etc/resolv.conf`. This can best be accomplished in the [user-data](../coreos/user-data) when installing [CoreOS](https://coreos.com/) to disk. Add the following block to the `write_files` section:
114-
115-
```yaml
116-
- path: /etc/resolv.conf
117-
permissions: 0644
118-
content: |
119-
nameserver 8.8.8.8
120-
nameserver 8.8.4.4
121-
domain your.domain.name
122-
options single-request
123-
```
3+
Please refer to the instructions at http://docs.deis.io/en/latest/installing_deis/baremetal/.

‎docs/installing_deis/baremetal.rst‎

Lines changed: 161 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -4,11 +4,167 @@
44
.. _deis_on_bare_metal:
55

66
Bare Metal
7-
----------
7+
==========
88

9-
The `contrib/bare-metal` section of the Deis project includes documentation to help with
10-
provisioning a multi-node cluster on your own hardware.
9+
Deis clusters can be provisioned anywhere `CoreOS`_ can, including on your own hardware. To get
10+
CoreOS running on raw hardware, you can boot with `PXE`_ or `iPXE`_ - this will boot a CoreOS
11+
machine running entirely from RAM. Then, you can `install CoreOS to disk`_.
1112

12-
Please see `contrib/bare-metal`_ for details on using Deis on bare metal.
1313

14-
.. _`contrib/bare-metal`: https://github.com/deis/deis/tree/master/contrib/bare-metal
14+
Generate SSH key
15+
----------------
16+
17+
To avoid problems deploying/launching apps later on it is necessary to install `CoreOS`_ to disk
18+
with a SSH key without a passphrase. The following command will generate a new keypair named
19+
"deis":
20+
21+
.. code-block:: console
22+
23+
$ ssh-keygen -q -t rsa -f ~/.ssh/deis -N '' -C deis
24+
25+
26+
Customize user-data
27+
-------------------
28+
29+
30+
Generate a New Discovery URL
31+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
32+
33+
To get started with provisioning Deis, we will need to generate a new Discovery URL. Discovery URLs
34+
help connect `etcd`_ instances together by storing a list of peer addresses and metadata under a
35+
unique address. You can generate a new discovery URL for use in your platform by
36+
running the following from the root of the repository:
37+
38+
.. code-block:: console
39+
40+
$ make discovery-url
41+
42+
This will write a new discovery URL to the user-data file. Some convenience scripts are supplied in
43+
this user-data file, so it is mandatory for provisioning Deis.
44+
45+
46+
SSH Key
47+
^^^^^^^
48+
49+
Add the public key part for the SSH key generated in the first step to the user-data file:
50+
51+
.. code-block:: console
52+
53+
ssh_authorized_keys:
54+
- ssh-rsa AAAAB3... deis
55+
56+
57+
Update $private_ipv4
58+
^^^^^^^^^^^^^^^^^^^^
59+
60+
`CoreOS`_ on bare metal doesn't detect the ``$private_ipv4`` reliably. Replace all occurences in
61+
the user-data with the (private) IP address of the node.
62+
63+
64+
Add Environment
65+
^^^^^^^^^^^^^^^
66+
67+
Since `CoreOS`_ doesn't detect private and public IP adresses, ``/etc/environment`` file doesn't
68+
get written on boot. Add it to the `write_files` section of the user-data file:
69+
70+
.. code-block:: console
71+
72+
- path: /etc/environment
73+
permissions: 0644
74+
content: |
75+
COREOS_PUBLIC_IPV4=<your public ip>
76+
COREOS_PRIVATE_IPV4=<your private ip>
77+
78+
79+
Install CoreOS to disk
80+
----------------------
81+
82+
Assuming you have booted your bare metal server into `CoreOS`_, you can perform now perform the
83+
installation to disk.
84+
85+
Provide the config file to the installer
86+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
87+
88+
Save the user-data file to your bare metal machine. The example assumes you transferred the config
89+
to ``/tmp/config``
90+
91+
92+
Start the installation
93+
^^^^^^^^^^^^^^^^^^^^^^
94+
95+
.. code-block:: console
96+
97+
coreos-install -C alpha -c /tmp/config -d /dev/sda
98+
99+
100+
This will install the current `CoreOS`_ release to disk. If you want to install the recommended
101+
`CoreOS`_ version, check the `Deis changelog`_ and specify that version by appending the ``-V``
102+
parameter to the install command, e.g. ``-V 472.0.0``.
103+
104+
After the installation has finished, reboot your server. Once your machine is back up, you should
105+
be able to log in as the `core` user using the `deis` ssh key.
106+
107+
108+
Configure DNS
109+
-------------
110+
111+
See :ref:`configure-dns` for more information on properly setting up your DNS records with Deis.
112+
113+
114+
Install Deis Platform
115+
---------------------
116+
117+
Now that you've finished provisioning a cluster, please refer to :ref:`install_deis_platform` to
118+
start installing the platform.
119+
120+
121+
Considerations when deploying Deis
122+
----------------------------------
123+
124+
* Use machines with ample disk space and RAM (for comparison, we use m3.large instances on EC2)
125+
* Choose an appropriate `cluster size`_
126+
127+
128+
Known Problems
129+
--------------
130+
131+
132+
Hostname is localhost
133+
^^^^^^^^^^^^^^^^^^^^^
134+
135+
If your hostname after installation to disk is ``localhost``, set the hostname in user-data before
136+
installation:
137+
138+
.. code-block:: console
139+
140+
hostname: your-hostname
141+
142+
The hostname must not be the fully qualified domain name!
143+
144+
145+
Slow name resolution
146+
^^^^^^^^^^^^^^^^^^^^
147+
148+
Certain DNS servers and firewalls have problems with glibc sending out requests for IPv4 and IPv6
149+
addresses in parallel. The solution is to set the option ``single-request`` in
150+
``/etc/resolv.conf``. This can best be accomplished in the user-data when installing `CoreOS`_ to
151+
disk. Add the following block to the ``write_files`` section:
152+
153+
.. code-block:: console
154+
155+
- path: /etc/resolv.conf
156+
permissions: 0644
157+
content: |
158+
nameserver 8.8.8.8
159+
nameserver 8.8.4.4
160+
domain your.domain.name
161+
options single-request
162+
163+
164+
.. _`cluster size`: https://github.com/coreos/etcd/blob/master/Documentation/optimal-cluster-size.md
165+
.. _`CoreOS`: https://coreos.com/
166+
.. _`Deis changelog`: https://github.com/deis/deis/blob/master/CHANGELOG.md
167+
.. _`etcd`: https://github.com/coreos/etcd
168+
.. _`install CoreOS to disk`: https://coreos.com/docs/running-coreos/bare-metal/installing-to-disk/
169+
.. _`iPXE`: https://coreos.com/docs/running-coreos/bare-metal/booting-with-ipxe/
170+
.. _`PXE`: https://coreos.com/docs/running-coreos/bare-metal/booting-with-pxe/

0 commit comments

Comments
 (0)