Skip to content

Re-organized OpenStack documentation #7398

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
openshift-merge-robot merged 11 commits into from
Mar 8, 2018
Merged

Re-organized OpenStack documentation #7398

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
e935e3f
Re-organized OpenStack documentation
tzumainn Mar 6, 2018
31dd277
Separated post-install doc from README; additional cleanup
tzumainn Mar 6, 2018
e1f7c03
fixed link
tzumainn Mar 6, 2018
7e41c7b
Add section about OPENSHIFT_CLUSTER env variable
tzumainn Mar 6, 2018
05bacf0
remove dangling reference to control-host-image
tzumainn Mar 6, 2018
8b964fa
Added subsection regarding OS-specific dependencies
tzumainn Mar 6, 2018
e431b7a
removed dangling link to scale documenation
tzumainn Mar 7, 2018
8fb9e3e
updated DNS section to match updated formatting; cleaned up openstack…
tzumainn Mar 7, 2018
bccc644
minor formatting
tzumainn Mar 7, 2018
33b8de3
re-formatted cinder sections
tzumainn Mar 7, 2018
7b22f41
updated uninstall section
tzumainn Mar 8, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
280 changes: 129 additions & 151 deletions playbooks/openstack/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,122 +6,97 @@ etc.). The result is an environment ready for OpenShift installation
via [openshift-ansible].

We provide everything necessary to be able to install OpenShift on
OpenStack (including the load balancer servers when
necessary). In addition, we work on providing integration with the
OpenStack-native services (storage, lbaas, baremetal as a service,
dns, etc.).
OpenStack. In addition we work on providing integration with the
OpenStack-native services (storage, lbaas, baremetal as a service, dns, etc.).


## OpenStack Requirements
## Requirements

Before you start the installation, you need to have an OpenStack
environment to connect to. You can use a public cloud or an OpenStack
within your organisation. It is also possible to
use [Devstack][devstack] or [TripleO][tripleo]. In the case of
TripleO, we will be running on top of the **overcloud**.
In order to run these Ansible playbooks, you'll need an Ansible host and an
OpenStack environment.

The OpenStack release must be Newton (for Red Hat OpenStack this is
version 10) or newer. It must also satisfy these requirements:
### Ansible Host

* Heat (Orchestration) must be available
* The deployment image (CentOS 7.4 or RHEL 7) must be loaded
* The deployment flavor must be available to your user
- `m1.medium` / 4GB RAM + 40GB disk should be enough for testing
- look at
the [Minimum Hardware Requirements page][hardware-requirements]
for production
* The keypair for SSH must be available in OpenStack
* `keystonerc` file that lets you talk to the OpenStack services
* NOTE: only Keystone V2 is currently supported
* A host with the supported version of [Ansible][ansible] installed, see the
[Setup section of the openshift-ansible README][openshift-ansible-setup]
for details on the requirements.
Start by choosing a host from which you'll run [Ansible][ansible]. This can
be the computer you read this guide on or an OpenStack VM you'll create
specifically for this purpose.

Optional:
* External Neutron network with a floating IP address pool
The required dependencies for the Ansible host are:

* [Ansible](https://pypi.python.org/pypi/ansible) version >=2.4.1
* [jinja2](http://jinja.pocoo.org/docs/2.9/) version >= 2.10
* [shade](https://pypi.python.org/pypi/shade) version >= 1.26
* python-jmespath / [jmespath](https://pypi.python.org/pypi/jmespath)
* python-dns / [dnspython](https://pypi.python.org/pypi/dnspython)
* Become (sudo) is *not* required.

## Installation

There are four main parts to the installation:
Optional dependencies include:

1. [Preparing Ansible and dependencies](#1-preparing-ansible-and-dependencies)
2. [Configuring the desired OpenStack environment and OpenShift cluster](#2-configuring-the-openstack-environment-and-openshift-cluster)
3. [Creating the OpenStack Resources and Installing OpenShift](#3-creating-the-openstack-resources-and-installing-openshift)
* `python-openstackclient`
* `python-heatclient`

This guide is going to install [OpenShift Origin][origin]
with [CentOS 7][centos7] images with minimal customisation.
There are a few OS-specific instructions:

We will create the VMs for running OpenShift, in a new Neutron network and
assign Floating IP addresses.
* RHEL: The `rhel-7-server-openstack-10-rpms` repository is required in order to install these openstack clients.
* CentOS: Run `yum install -y centos-release-openstack-pike`

The OpenShift cluster will have a single Master node that will run
`etcd`, a single Infra node and two App nodes.

You can look at
the [Advanced Configuration page][advanced-configuration] for
additional options.
Once the dependencies are installed, clone the [openshift-ansible][openshift-ansible]
repository:

```
$ git clone https://github.com/openshift/openshift-ansible
```

### OpenStack Environment

### 1. Preparing Ansible and dependencies
Before you start the installation, you'll need an OpenStack environment.
Options include:

First, you need to select where to run [Ansible][ansible] from (the
*Ansible host*). This can be the computer you read this guide on or an
OpenStack VM you'll create specifically for this purpose.
* [Devstack][devstack]
* [Packstack][packstack]
* [TripleO][tripleo] (Overcloud)

This guide will use a
[Docker image that has all the dependencies installed][control-host-image] to
make things easier. If you don't want to use Docker, take a look at
the [Ansible host dependencies][ansible-dependencies] and make sure
they are installed.
You can also use a public cloud or an OpenStack within your organization.

Your *Ansible host* needs to have the following:
The OpenStack environment must satisfy these requirements:

1. Docker
2. `keystonerc` file with your OpenStack credentials
3. SSH private key for logging in to your OpenShift nodes
* It must be Newton (equivalent to Red hat OpenStack 10) or newer
* Heat (Orchestration) must be available
* The deployment image (CentOS 7.4 or RHEL 7) must be loaded
* The deployment flavor must be available to your user
- `m1.medium` / 4GB RAM + 40GB disk should be enough for testing
- look at
the [Minimum Hardware Requirements page][hardware-requirements]
for production
* The keypair for SSH must be available in OpenStack
* You must have a`keystonerc` file that lets you talk to the OpenStack services

Assuming your private key is `~/.ssh/id_rsa` and `keystonerc` in your
current directory:
It is also strongly recommended that you configure an external Neutron network
with a floating IP address pool.

```bash
$ sudo docker run -it -v ~/.ssh:/mnt/.ssh:Z \
-v $PWD/keystonerc:/root/.config/openstack/keystonerc.sh:Z \
redhatcop/control-host-openstack bash
```

This will create the container, add your SSH key and source your
`keystonerc`. It should be set up for the installation.
## Configuration

You can verify that everything is in order:
Configuration is done through an Ansible inventory directory. You can switch
between multiple inventories to test multiple configurations.

Start by copying the sample inventory to your inventory directory.

```bash
$ less .ssh/id_rsa
$ ansible --version
$ openstack image list
```


### 2. Configuring the OpenStack Environment and OpenShift Cluster

The configuration is all done in an Ansible inventory directory. We
will clone the [openshift-ansible][openshift-ansible] repository and set
things up for a minimal installation.


```
$ git clone https://github.com/openshift/openshift-ansible
$ cp -r openshift-ansible/playbooks/openstack/sample-inventory/ inventory
```

If you're testing multiple configurations, you can have multiple
inventories and switch between them.
The sample inventory contains defaults that will do the following:

* create VMs for an OpenShift cluster with 1 Master node, 1 Infra node, and 2 App nodes
* create a new Neutron network and assign floating IP addresses to the VMs

You may have to perform further configuration in order to match the inventory
to your environment.

#### OpenStack Configuration
### OpenStack Configuration

The OpenStack configuration is in `inventory/group_vars/all.yml`.
The OpenStack configuration file is `inventory/group_vars/all.yml`.

Open the file and plug in the image, flavor and network configuration
corresponding to your OpenStack installation.
Expand All @@ -130,63 +105,60 @@ corresponding to your OpenStack installation.
$ vi inventory/group_vars/all.yml
```

1. Set the `openshift_openstack_keypair_name` to your OpenStack keypair name.
* `openshift_openstack_keypair_name` Set your OpenStack keypair name.
- See `openstack keypair list` to find the keypairs registered with
OpenShift.
- This must correspond to your private SSH key in `~/.ssh/id_rsa`
2. Set the `openshift_openstack_external_network_name` to the floating IP
network of your openstack.
* `openshift_openstack_external_network_name` Set the floating IP
network of your OpenStack.
- See `openstack network list` for the list of networks.
- It's often called `public`, `external` or `ext-net`.
3. Set the `openshift_openstack_default_image_name` to the image you want your
- Often called `public`, `external` or `ext-net`.
* `openshift_openstack_default_image_name` Set the image you want your
OpenShift VMs to run.
- See `openstack image list` for the list of available images.
4. Set the `openshift_openstack_default_flavor` to the flavor you want your
* `openshift_openstack_default_flavor` Set the flavor you want your
OpenShift VMs to use.
- See `openstack flavor list` for the list of available flavors.
5. If you opt to use Kuryr for the networking, make sure that you review all
the kuryr options in the file. At the very least, if you use Kuryr, you
should uncomment:

```bash
#openshift_use_kuryr: True
#use_trunk_ports: True
#openshift_use_openshift_sdn: False
#os_sdn_network_plugin_name: cni
#openshift_node_proxy_mode: userspace
#openshift_hosted_manage_registry: false
#kuryr_openstack_public_subnet_id: uuid of my public subnet
```

### OpenShift Configuration

#### OpenShift configuration
The OpenShift configuration file is `inventory/group_vars/OSEv3.yml`.

The OpenShift configuration is in `inventory/group_vars/OSEv3.yml`.
The default options will mostly work, but openshift-ansible's hardware check
may fail unless you specified a large flavor suitable for a production-ready
environment.

The default options will mostly work, but unless you used the large
flavors for a production-ready environment, openshift-ansible's
hardware check will fail.

Let's disable those checks by putting this in
`inventory/group_vars/OSEv3.yml`:
You can disable those checks by adding this line to `inventory/group_vars/OSEv3.yml`:

```yaml
openshift_disable_check: disk_availability,memory_availability
openshift_disable_check: disk_availability,memory_availability,docker_storage
```

**NOTE**: The default authentication method will allow **any username
**Important**: The default authentication method will allow **any username
and password** in! If you're running this in a public place, you need
to set up access control.
to set up access control by [configuring authentication][configure-authentication].

Feel free to look at
the [Sample OpenShift Inventory][sample-openshift-inventory] and
the [advanced configuration][advanced-configuration].

### Advanced Configuration

### 3. Creating the OpenStack Resources and Installing OpenShift
The [Configuration page][configuration] details several
additional options. These include:

We provide an `ansible.cfg` file which has some useful defaults -- you should
copy it to the directory you're going to run `ansible-playbook` from.
* Set Up Authentication (TODO)
* [Multiple Masters with a load balancer][loadbalancer]
* [External DNS][external-dns]
* Multiple Clusters (TODO)
* [Cinder Registry][cinder-registry]

Read the [Configuration page][configuration] for a full listing of
configuration options.


## Installation

Before running the installation playbook, you may want to create an `ansible.cfg`
file with useful defaults:

```bash
$ cp openshift-ansible/ansible.cfg ansible.cfg
Expand All @@ -201,8 +173,8 @@ any_errors_fatal = true
This will abort the Ansible playbook execution as soon as any error is
encountered.

Now, run the provision + install playbook -- this will create the OpenStack
resources:
Now, run the provision + install playbook. This will create OpenStack resources
and deploy an OpenShift cluster on top of them:

```bash
$ ansible-playbook --user openshift \
Expand All @@ -211,52 +183,58 @@ $ ansible-playbook --user openshift \
openshift-ansible/playbooks/openstack/openshift-cluster/provision_install.yml
```

In addition to *your* inventory with your OpenShift and OpenStack
configuration, we are also supplying the [dynamic inventory][dynamic] from
`openshift-ansible/inventory`. It's a script that will look at the Nova servers
and other resources that will be created and let Ansible know about them.

If you're using multiple inventories, make sure you pass the path to
* If you're using multiple inventories, make sure you pass the path to
the right one to `-i`.

If your SSH private key is not in `~/.ssh/id_rsa` use the `--private-key`
* If your SSH private key is not in `~/.ssh/id_rsa`, use the `--private-key`
option to specify the correct path.
* Note that we must pass in the [dynamic inventory][dynamic] --
`openshift-ansible/playbooks/openstack/inventory.py`. This is a script that
looks for OpenStack resources and enables Ansible to reference them.


## Post-Install

### Next Steps
Once installation completes, a few additional steps may be required or useful.

And that's it! You should have a small but functional OpenShift
cluster now.
* [Configure DNS][configure-dns]
* [Get the `oc` Client][get-the-oc-client]
* [Log in Using the Command Line][log-in-using-the-command-line]
* [Access the UI][access-the-ui]

Take a look at [how to access the cluster][accessing-openshift]
and [how to remove it][uninstall-openshift] as well as the more
advanced configuration:
Read the [Post-Install page][post-install] for a full list of options.

* [Accessing the OpenShift cluster][accessing-openshift]
* [Removing the OpenShift cluster][uninstall-openshift]
* Set Up Authentication (TODO)
* [Multiple Masters with a load balancer][loadbalancer]
* [External Dns][external-dns]
* Multiple Clusters (TODO)
* [Cinder Registry][cinder-registry]

## Uninstall

The installation process not only creates a Heat stack, but can also
perform actions such as writing DNS records or subscribing a host to RHN.
In order to do a clean uninstall, run this command:

```bash
$ ansible-playbook --user openshift \
-i openshift-ansible/playbooks/openstack/inventory.py \
-i inventory \
openshift-ansible/playbooks/openstack/openshift-cluster/uninstall.yml
```

[ansible]: https://www.ansible.com/
[openshift-ansible]: https://github.com/openshift/openshift-ansible
[openshift-ansible-setup]: https://github.com/openshift/openshift-ansible#setup
[devstack]: https://docs.openstack.org/devstack/
[tripleo]: http://tripleo.org/
[ansible-dependencies]: ./advanced-configuration.md#dependencies-for-localhost-ansible-controladmin-node
[control-host-image]: https://hub.docker.com/r/redhatcop/control-host-openstack/
[packstack]: https://www.rdoproject.org/install/packstack/
[configure-authentication]: https://docs.openshift.org/latest/install_config/configuring_authentication.html
[hardware-requirements]: https://docs.openshift.org/latest/install_config/install/prerequisites.html#hardware
[origin]: https://www.openshift.org/
[centos7]: https://www.centos.org/
[sample-openshift-inventory]: https://github.com/openshift/openshift-ansible/blob/master/inventory/hosts.example
[advanced-configuration]: ./advanced-configuration.md
[accessing-openshift]: ./advanced-configuration.md#accessing-the-openshift-cluster
[uninstall-openshift]: ./advanced-configuration.md#removing-the-openshift-cluster
[loadbalancer]: ./advanced-configuration.md#multi-master-configuration
[external-dns]: ./advanced-configuration.md#dns-configuration-variables
[cinder-registry]: ./advanced-configuration.md#creating-and-using-a-cinder-volume-for-the-openshift-registry
[configuration]: ./configuration.md
[loadbalancer]: ./configuration.md#multi-master-configuration
[external-dns]: ./configuration.md#dns-configuration
[cinder-registry]: ./configuration.md#cinder-backed-registry-configuration
[post-install]: ./post-install.md
[configure-dns]: ./post-install.md#configure-dns
[get-the-oc-client]: ./post-install.md#get-the-oc-client
[log-in-using-the-command-line]: ./post-install.md#log-in-using-the-command-line
[access-the-ui]: ./post-install.md#access-the-ui
[dynamic]: http://docs.ansible.com/ansible/latest/intro_dynamic_inventory.html
Loading