From 85181ea469ed5f541cbac6f73aefc134526aca8d Mon Sep 17 00:00:00 2001 From: Tomas Sedovic Date: Tue, 7 Nov 2017 14:34:03 +1100 Subject: Move the OpenStack playbooks We move them from `playbooks/provisioning/openstack` to `playbooks/openstack` to mirror `playbooks/aws`. --- playbooks/openstack/README.md | 258 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 258 insertions(+) create mode 100644 playbooks/openstack/README.md (limited to 'playbooks/openstack/README.md') diff --git a/playbooks/openstack/README.md b/playbooks/openstack/README.md new file mode 100644 index 000000000..a2f553f4c --- /dev/null +++ b/playbooks/openstack/README.md @@ -0,0 +1,258 @@ +# OpenStack Provisioning + +This directory contains [Ansible][ansible] playbooks and roles to create +OpenStack resources (servers, networking, volumes, security groups, +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 DNS and 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 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**. + +The OpenStack release must be Newton (for Red Hat OpenStack this is +version 10) or newer. It must also satisfy these requirements: + +* Heat (Orchestration) must be available +* The deployment image (CentOS 7 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 + +Optional: +* External Neutron network with a floating IP address pool + + +## Installation + +There are four main parts to the installation: + +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 (VMs, networking, etc.)](#3-creating-the-openstack-resources-vms-networking-etc) +4. [Installing OpenShift](#4-installing-openshift) + +This guide is going to install [OpenShift Origin][origin] +with [CentOS 7][centos7] images with minimal customisation. + +We will create the VMs for running OpenShift, in a new Neutron +network, assign Floating IP addresses and configure DNS. + +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. + + + +### 1. Preparing Ansible and dependencies + +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. + +We 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're installed. + +Your *Ansible host* needs to have the following: + +1. Docker +2. `keystonerc` file with your OpenStack credentials +3. SSH private key for logging in to your OpenShift nodes + +Assuming your private key is `~/.ssh/id_rsa` and `keystonerc` in your +current directory: + +```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. + +You can verify that everything is in order: + + +```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-contrib][contrib] repository and set +things up for a minimal installation. + + +``` +$ git clone https://github.com/openshift/openshift-ansible-contrib +$ cp -r openshift-ansible-contrib/playbooks/provisioning/openstack/sample-inventory/ inventory +``` + +If you're testing multiple configurations, you can have multiple +inventories and switch between them. + +#### OpenStack Configuration + +The OpenStack configuration is in `inventory/group_vars/all.yml`. + +Open the file and plug in the image, flavor and network configuration +corresponding to your OpenStack installation. + +```bash +$ vi inventory/group_vars/all.yml +``` + +1. Set the `openstack_ssh_public_key` to 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 `openstack_external_network_name` to 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 `openstack_default_image_name` to the image you want your + OpenShift VMs to run. + - See `openstack image list` for the list of available images. +4. Set the `openstack_default_flavor` to the flavor you want your + OpenShift VMs to use. + - See `openstack flavor list` for the list of available flavors. + +**NOTE**: In most OpenStack environments, you will also need to +configure the forwarders for the DNS server we create. This depends on +your environment. + +Launch a VM in your OpenStack and look at its `/etc/resolv.conf` and +put the IP addresses into `public_dns_nameservers` in +`inventory/group_vars/all.yml`. + + +#### OpenShift configuration + +The OpenShift configuration is in `inventory/group_vars/OSEv3.yml`. + +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`: + +```yaml +openshift_disable_check: disk_availability,memory_availability +``` + +**NOTE**: 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. + +Feel free to look at +the [Sample OpenShift Inventory][sample-openshift-inventory] and +the [advanced configuration][advanced-configuration]. + + +### 3. Creating the OpenStack resources (VMs, networking, etc.) + +We will install the DNS server roles using ansible galaxy and then run +the openstack provisioning playbook. The `ansible.cfg` file we provide +has useful defaults -- copy it to the directory you're going to run +Ansible from. + +```bash +$ ansible-galaxy install -r openshift-ansible-contrib/playbooks/provisioning/openstack/galaxy-requirements.yaml -p openshift-ansible-contrib/roles +$ cp openshift-ansible-contrib/playbooks/provisioning/openstack/ansible.cfg ansible.cfg +``` +(you will only need to do this once) + +Then run the provisioning playbook -- this will create the OpenStack +resources: + +```bash +$ ansible-playbook -i inventory openshift-ansible-contrib/playbooks/provisioning/openstack/provision.yaml +``` + +If you're using multiple inventories, make sure you pass the path to +the right one to `-i`. + + +### 4. Installing OpenShift + +We will use the `openshift-ansible` project to install openshift on +top of the OpenStack nodes we have prepared: + +```bash +$ git clone https://github.com/openshift/openshift-ansible +$ ansible-playbook -i inventory openshift-ansible/playbooks/byo/config.yml +``` + + +### Next Steps + +And that's it! You should have a small but functional OpenShift +cluster now. + +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: + +* [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] +* [Bastion Node][bastion] + + +[ansible]: https://www.ansible.com/ +[openshift-ansible]: https://github.com/openshift/openshift-ansible +[devstack]: https://docs.openstack.org/devstack/ +[tripleo]: http://tripleo.org/ +[ansible-dependencies]: ./advanced-configuration.md#dependencies-for-localhost-ansible-controladmin-node +[contrib]: https://github.com/openshift/openshift-ansible-contrib +[control-host-image]: https://hub.docker.com/r/redhatcop/control-host-openstack/ +[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/byo/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 +[bastion]: ./advanced-configuration.md#configure-static-inventory-and-access-via-a-bastion-node + + + +## License + +Like the rest of the openshift-ansible-contrib repository, the code +here is licensed under Apache 2. -- cgit v1.2.3 From 479ba2dec446016cb0cea38e4c679f54dea24193 Mon Sep 17 00:00:00 2001 From: Tomas Sedovic Date: Mon, 16 Oct 2017 17:35:22 +0200 Subject: Update readme --- playbooks/openstack/README.md | 25 ++++++++----------------- 1 file changed, 8 insertions(+), 17 deletions(-) (limited to 'playbooks/openstack/README.md') diff --git a/playbooks/openstack/README.md b/playbooks/openstack/README.md index a2f553f4c..f3d5b5aa8 100644 --- a/playbooks/openstack/README.md +++ b/playbooks/openstack/README.md @@ -106,13 +106,13 @@ $ 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-contrib][contrib] repository and set +will clone the [openshift-ansible][openshift-ansible] repository and set things up for a minimal installation. ``` -$ git clone https://github.com/openshift/openshift-ansible-contrib -$ cp -r openshift-ansible-contrib/playbooks/provisioning/openstack/sample-inventory/ inventory +$ 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 @@ -185,8 +185,8 @@ has useful defaults -- copy it to the directory you're going to run Ansible from. ```bash -$ ansible-galaxy install -r openshift-ansible-contrib/playbooks/provisioning/openstack/galaxy-requirements.yaml -p openshift-ansible-contrib/roles -$ cp openshift-ansible-contrib/playbooks/provisioning/openstack/ansible.cfg ansible.cfg +$ ansible-galaxy install -r openshift-ansible/playbooks/openstack/galaxy-requirements.yaml -p openshift-ansible/roles +$ cp openshift-ansible/playbooks/openstack/ansible.cfg ansible.cfg ``` (you will only need to do this once) @@ -194,7 +194,7 @@ Then run the provisioning playbook -- this will create the OpenStack resources: ```bash -$ ansible-playbook -i inventory openshift-ansible-contrib/playbooks/provisioning/openstack/provision.yaml +$ ansible-playbook -i inventory openshift-ansible/playbooks/openstack/openshift-cluster/provision.yaml ``` If you're using multiple inventories, make sure you pass the path to @@ -203,11 +203,10 @@ the right one to `-i`. ### 4. Installing OpenShift -We will use the `openshift-ansible` project to install openshift on -top of the OpenStack nodes we have prepared: +Run the `byo/config.yml` playbook on top of the OpenStack nodes we have +prepared. ```bash -$ git clone https://github.com/openshift/openshift-ansible $ ansible-playbook -i inventory openshift-ansible/playbooks/byo/config.yml ``` @@ -236,7 +235,6 @@ advanced configuration: [devstack]: https://docs.openstack.org/devstack/ [tripleo]: http://tripleo.org/ [ansible-dependencies]: ./advanced-configuration.md#dependencies-for-localhost-ansible-controladmin-node -[contrib]: https://github.com/openshift/openshift-ansible-contrib [control-host-image]: https://hub.docker.com/r/redhatcop/control-host-openstack/ [hardware-requirements]: https://docs.openshift.org/latest/install_config/install/prerequisites.html#hardware [origin]: https://www.openshift.org/ @@ -249,10 +247,3 @@ advanced configuration: [external-dns]: ./advanced-configuration.md#dns-configuration-variables [cinder-registry]: ./advanced-configuration.md#creating-and-using-a-cinder-volume-for-the-openshift-registry [bastion]: ./advanced-configuration.md#configure-static-inventory-and-access-via-a-bastion-node - - - -## License - -Like the rest of the openshift-ansible-contrib repository, the code -here is licensed under Apache 2. -- cgit v1.2.3 From 4ed9aef6f8ed0850e70b498e780d0d8e22bc277f Mon Sep 17 00:00:00 2001 From: Tomas Sedovic Date: Mon, 23 Oct 2017 12:57:29 +0200 Subject: Add openshift_openstack role and move tasks there All the tasks that were previously in playbooks are now under `roles/openshift_openstack`. The `openshift-cluster` directory now only contains playbooks that include tasks from that role. This makes the structure much closer to that of the AWS provider. --- playbooks/openstack/README.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) (limited to 'playbooks/openstack/README.md') diff --git a/playbooks/openstack/README.md b/playbooks/openstack/README.md index f3d5b5aa8..875004cc9 100644 --- a/playbooks/openstack/README.md +++ b/playbooks/openstack/README.md @@ -38,6 +38,19 @@ Optional: * External Neutron network with a floating IP address pool +## DNS Requirements + +OpenShift requires DNS to operate properly. OpenStack supports DNS-as-a-service +in the form of the Designate project, but the playbooks here don't support it +yet. Until we do, you will need to provide a DNS solution yourself (or in case +you are not running Designate when we do). + +If your server supports nsupdate, we will use it to add the necessary records. + +TODO(shadower): describe how to build a sample DNS server and how to configure +our playbooks for nsupdate. + + ## Installation There are four main parts to the installation: @@ -143,6 +156,8 @@ $ vi inventory/group_vars/all.yml 4. Set the `openstack_default_flavor` to the flavor you want your OpenShift VMs to use. - See `openstack flavor list` for the list of available flavors. +5. Set the `public_dns_nameservers` to the list of the IP addresses + of the DNS servers used for the **private** address resolution[1]. **NOTE**: In most OpenStack environments, you will also need to configure the forwarders for the DNS server we create. This depends on @@ -153,6 +168,9 @@ put the IP addresses into `public_dns_nameservers` in `inventory/group_vars/all.yml`. +[1]: Yes, the name is bad. We will fix it. + + #### OpenShift configuration The OpenShift configuration is in `inventory/group_vars/OSEv3.yml`. -- cgit v1.2.3 From 88907aca794716d1a2db4cc31e03375720695424 Mon Sep 17 00:00:00 2001 From: Tomas Sedovic Date: Wed, 1 Nov 2017 11:33:38 +0100 Subject: Use the existing ansible.cfg file --- playbooks/openstack/README.md | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) (limited to 'playbooks/openstack/README.md') diff --git a/playbooks/openstack/README.md b/playbooks/openstack/README.md index 875004cc9..4347ddaa8 100644 --- a/playbooks/openstack/README.md +++ b/playbooks/openstack/README.md @@ -197,27 +197,26 @@ the [advanced configuration][advanced-configuration]. ### 3. Creating the OpenStack resources (VMs, networking, etc.) -We will install the DNS server roles using ansible galaxy and then run -the openstack provisioning playbook. The `ansible.cfg` file we provide -has useful defaults -- copy it to the directory you're going to run -Ansible from. +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. ```bash -$ ansible-galaxy install -r openshift-ansible/playbooks/openstack/galaxy-requirements.yaml -p openshift-ansible/roles -$ cp openshift-ansible/playbooks/openstack/ansible.cfg ansible.cfg +$ cp openshift-ansible/ansible.cfg ansible.cfg ``` -(you will only need to do this once) Then run the provisioning playbook -- this will create the OpenStack resources: ```bash -$ ansible-playbook -i inventory openshift-ansible/playbooks/openstack/openshift-cluster/provision.yaml +$ ansible-playbook --user openshift -i inventory openshift-ansible/playbooks/openstack/openshift-cluster/provision.yaml ``` 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` +option to specify the correct path. + ### 4. Installing OpenShift -- cgit v1.2.3 From 79f29bc825286c4f69073827a5b6d71f71f47c91 Mon Sep 17 00:00:00 2001 From: Tomas Sedovic Date: Wed, 1 Nov 2017 16:43:13 +0100 Subject: Add the DNS updates and rename the openstack vars Most of the vars in `roles/openshift_openstack/defaults/main.yml` are now prefixed with `openstack_`. --- playbooks/openstack/README.md | 18 +++++++----------- 1 file changed, 7 insertions(+), 11 deletions(-) (limited to 'playbooks/openstack/README.md') diff --git a/playbooks/openstack/README.md b/playbooks/openstack/README.md index 4347ddaa8..99f4ab12f 100644 --- a/playbooks/openstack/README.md +++ b/playbooks/openstack/README.md @@ -142,7 +142,7 @@ corresponding to your OpenStack installation. $ vi inventory/group_vars/all.yml ``` -1. Set the `openstack_ssh_public_key` to your OpenStack keypair name. +1. Set the `openstack_keypair_name` to 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` @@ -156,20 +156,16 @@ $ vi inventory/group_vars/all.yml 4. Set the `openstack_default_flavor` to the flavor you want your OpenShift VMs to use. - See `openstack flavor list` for the list of available flavors. -5. Set the `public_dns_nameservers` to the list of the IP addresses - of the DNS servers used for the **private** address resolution[1]. +5. Set the `openstack_dns_nameservers` to the list of the IP addresses + of the DNS servers used for the **private** address resolution. -**NOTE**: In most OpenStack environments, you will also need to -configure the forwarders for the DNS server we create. This depends on -your environment. +**NOTE ON DNS**: at minimum, the OpenShift nodes need to be able to access each +other by their hostname. OpenStack doesn't provide this by default, so you +need to provide a DNS server. Put the address of that DNS server in +`openstack_dns_nameservers` variable. -Launch a VM in your OpenStack and look at its `/etc/resolv.conf` and -put the IP addresses into `public_dns_nameservers` in -`inventory/group_vars/all.yml`. -[1]: Yes, the name is bad. We will fix it. - #### OpenShift configuration -- cgit v1.2.3 From b95170503613bb97c00175324b31ed91f6f41ea1 Mon Sep 17 00:00:00 2001 From: Tomas Sedovic Date: Thu, 2 Nov 2017 11:03:39 +0100 Subject: Namespace the OpenStack vars This makes sure that all the variables used in the `openshift_openstack` role are prefixed with `openshift_openstack_` as is the convention. --- playbooks/openstack/README.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) (limited to 'playbooks/openstack/README.md') diff --git a/playbooks/openstack/README.md b/playbooks/openstack/README.md index 99f4ab12f..f3fe13530 100644 --- a/playbooks/openstack/README.md +++ b/playbooks/openstack/README.md @@ -142,27 +142,27 @@ corresponding to your OpenStack installation. $ vi inventory/group_vars/all.yml ``` -1. Set the `openstack_keypair_name` to your OpenStack keypair name. +1. Set the `openshift_openstack_keypair_name` to 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 `openstack_external_network_name` to the floating IP +2. Set the `openshift_openstack_external_network_name` to 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 `openstack_default_image_name` to the image you want your +3. Set the `openshift_openstack_default_image_name` to the image you want your OpenShift VMs to run. - See `openstack image list` for the list of available images. -4. Set the `openstack_default_flavor` to the flavor you want your +4. Set the `openshift_openstack_default_flavor` to the flavor you want your OpenShift VMs to use. - See `openstack flavor list` for the list of available flavors. -5. Set the `openstack_dns_nameservers` to the list of the IP addresses +5. Set the `openshift_openstack_dns_nameservers` to the list of the IP addresses of the DNS servers used for the **private** address resolution. **NOTE ON DNS**: at minimum, the OpenShift nodes need to be able to access each other by their hostname. OpenStack doesn't provide this by default, so you need to provide a DNS server. Put the address of that DNS server in -`openstack_dns_nameservers` variable. +`openshift_openstack_dns_nameservers` variable. -- cgit v1.2.3