From fd4105ac14b1efa19e5a646229264f47054d868f Mon Sep 17 00:00:00 2001 From: Samuel Cassiba Date: Fri, 19 May 2017 06:15:56 -0700 Subject: [PATCH] Documentation updates for Ocata - corrects grammatical flows - updates for the current master release - aligns documentation with local provisioning changes - rewrites multinode doc to reflect network node Change-Id: I820266b0f2885629211a917858ca7ea35f5f08d3 --- README.md | 171 +++++++++++++++++------------- doc/allinone.md | 25 +---- doc/{databags.md => data_bags.md} | 41 ++++--- doc/multi_node.md | 29 ----- doc/multinode.md | 23 ++++ 5 files changed, 150 insertions(+), 139 deletions(-) rename doc/{databags.md => data_bags.md} (82%) delete mode 100644 doc/multi_node.md create mode 100644 doc/multinode.md diff --git a/README.md b/README.md index 7523864..e528725 100644 --- a/README.md +++ b/README.md @@ -7,56 +7,76 @@ Team and repository tags ![Chef OpenStack Logo](https://www.openstack.org/themes/openstack/images/project-mascots/Chef%20OpenStack/OpenStack_Project_Chef_horizontal.png) -# OpenStack cluster with chef-provisioning +# Testing framework for deploying OpenStack using Chef -This is the testing framework for OpenStack and Chef. We leverage this to test against our changes to our [cookbooks](https://wiki.openstack.org/wiki/Chef/GettingStarted) to make sure -that you can still build a cluster from the ground up with any changes we push up. +This is the testing framework for OpenStack deployed using +[Chef](https://www.chef.io). We leverage this to test against our changes to our +[cookbooks](https://wiki.openstack.org/wiki/Chef/GettingStarted) to make sure +that you can still build a cluster from the ground up with any changes we +introduce. -This framework also gives us an opportunity to show different Reference Architectures and a sane example on how to start with OpenStack and Chef. +This framework also gives us an opportunity to show different Reference +Architectures and a sane example on how to start with OpenStack using Chef. -With the `master` branch of the cookbooks, which is currently tied to the base OpenStack Liberty release, this supports deploying to Ubuntu 14.04 and CentOS 7.1 for all-in-one with nova-network. Support for all-in-one with Neutron, and multi-node support, is a work in progress. +With the `master` branch of the cookbooks, which is currently tied to the base +OpenStack Ocata release, this supports deploying to Ubuntu 16.04 and CentOS 7 +in monolithic, or allinone, and non-HA multinode configurations with Neutron. The cookbooks support a fully +HA configuration, but we do not test for that as there are far numerous paths to +HA. -## Prereqs +## Prerequisites -- [ChefDK](https://downloads.chef.io/chef-dk/) 0.9.0 or later -- [Vagrant](https://www.vagrantup.com/downloads.html) 1.7.2 or later with [VirtualBox](https://www.virtualbox.org/wiki/Downloads) or some other provider +- [ChefDK](https://downloads.chef.io/chef-dk/) 1.0 or later for a relatively + recent Berkshelf +- [Vagrant](https://www.vagrantup.com/downloads.html) 1.9 or later with + [VirtualBox](https://www.virtualbox.org/wiki/Downloads) or some other provider -## Initial Setup Steps +### Getting the Code (this repo) ```shell $ git clone https://github.com/openstack/openstack-chef-repo.git $ cd openstack-chef-repo -$ chef exec rake berks_vendor ``` -The OpenStack cookbooks by default use databags for configuring passwords. There are four -data_bags : *user_passwords*, *db_passwords*, *service_passwords*, *secrets*. I have a already created -the `data_bags/` directory, so you shouldn't need to make them, if you do something's broken. -See [Databags](#databags) section below for more details. - -**NOTE**: If you are running Ubuntu 14.04 LTS and as your **base** compute machine, you should note that the shipped -kernel `3.13.0-24-generic` has networking issues, and the best way to resolve this is -via: `apt-get install linux-image-generic-lts-utopic`. This will install at least `3.16.0` from the Utopic hardware enablement. +The OpenStack cookbooks by default use encrypted data bags for configuring +passwords. There are four data bags : *user_passwords*, *db_passwords*, +*service_passwords*, *secrets*. There already exists a `data_bags/` directory, +so you shouldn't need to create any for a proof of concept. If you do, something is wrong. +See the [Data Bags](doc/data_bags.md) doc for the gory details. ## Supported Deployments -* All-in-One - * Neutron -* Multi-Node - * Neutron - -For each deployment model, there is a corresponding readme file in the doc/ directory. Please review that for specific details and additional setup that might be required before deploying the cloud. +For each deployment model, there is a corresponding file in the doc/ directory. +Please review that for specific details and additional setup that might be +required before deploying the cloud. ## Rake Deploy Commands -These commands will spin up various OpenStack cluster configurations, the simplest being the all-in-one controller with nova-network. +These commands will produce various OpenStack cluster configurations, the +simplest being a monolithic Compute Controller with Neutron (allinone). These +deployments are not intended to be production-ready, and will need adaptation +to your environment. This is intended for development and proof of concept +deployments. -For CentOS, set the environment variable REPO_OS=centos7 +For CentOS, set the environment variable REPO_OS=centos7. Ubuntu is the default. + +### Everything self-contained (allinone) +```bash +# allinone with Neutron +$ chef exec rake allinone +``` + +### Access the machine ```bash -# All-in-one controller with neutron-network -$ chef exec rake allinone -# Multi-Node Setup with neutron-network (1 controller + 2 compute nodes) +$ cd vms +$ vagrant ssh controller +$ sudo su - +``` + +### Multiple nodes (non-HA) +```bash +# Multinode with Neutron (1 controller + 1 network + 2 compute nodes) $ chef exec rake multi_node ``` @@ -68,6 +88,14 @@ $ vagrant ssh controller $ sudo su - ``` +### Access the Network Node + +```bash +$ cd vms +$ vagrant ssh network +$ sudo su - +``` + ### Access the Compute nodes ```bash @@ -78,65 +106,68 @@ $ vagrant ssh compute2 $ sudo su - ``` -### Testing the Controller +### Testing The Controller ```bash # Access the controller as noted above -$ source openrc -$ nova-manage version -$ nova service-list && nova hypervisor-list -$ glance image-list -$ keystone user-list -$ nova list +$ source /root/openrc +$ nova --version +$ openstack service list && openstack hypervisor list +$ openstack image list +$ openstack user list +$ openstack server list ``` -### Working with Security Groups ### +### Working With Security Groups ### -To allow SSH access to instances, a nova security group is defined as follows: +To allow SSH access to instances, a security group is defined as follows: ```bash -$ nova secgroup-list -$ nova secgroup-list-rules default -$ nova secgroup-create allow_ssh "allow ssh to instance" -$ nova secgroup-add-rule allow_ssh tcp 22 22 0.0.0.0/0 -$ nova secgroup-list-rules allow_ssh +$ openstack security group list +$ openstack security group list default +$ openstack security group create allow_ssh --description "allow ssh to instances" +$ openstack security group rule create allow_ssh --protocol tcp --dst-port 22:22 --remote-ip 0.0.0.0/0 +$ openstack security group list allow_ssh ``` -### Working with keys ### +### Working With Keys ### -To allow SSH keys to be injected into instance, a nova keypair is defined as follows: +To allow SSH keys to be injected into instance, a key pair is defined as follows: ```bash -# Just press Enter to all the questions -$ ssh-keygen -$ nova keypair-add --pub-key=/root/.ssh/id_rsa.pub mykey +# generate a new key pair +$ openstack keypair create mykey > mykey.pem +$ chmod 600 mykey.pem +$ openstack keypair create --public-key ~/.ssh/id_rsa.pub mykey +# verify the key pair has been imported +$ openstack keypair list ``` #### Booting up a cirros image on the Controller ```bash -$ nova boot test --image cirros --flavor 1 --security-groups=allow_ssh --key-name=mykey +$ openstack server create --flavor 1 --image cirros --security-group allow_ssh --key-name mykey test ``` -Wait a few seconds and the run `nova list` if Status is not Active, wait a few seconds and repeat. +Wait a few seconds and the run `openstack server list` if Status is not Active, wait a few seconds and repeat. -Once status is active you should be able to log in via ssh to the listed IP. +Once status is active you should be able to log in using SSH, or `vagrant ssh ` ```bash -$ ssh cirros@ +$ ssh cirros@ ``` -#### Accessing the OpenStack Dashboard +#### Accessing The OpenStack Dashboard If you would like to use the OpenStack dashboard you should go to https://localhost:9443 and the username and password is `admin/mypass`. -#### Verifying stack with tempest +#### Verifying OpenStack With Tempest -If you ssh into the `controller` machine you can test via the most recent [tempest](https://github.com/openstack/tempest) release. +If you log in to the `controller` machine you can test via the most recent [Tempest](https://github.com/openstack/tempest) release. ```bash $ cd vms -$ vagrant ssh controller +$ vagrant ssh $ sudo su - root@controller:~ cd /opt/tempest root@controller:/opt/tempest$ ./run_tempest.sh -V --smoke --serial @@ -165,14 +196,14 @@ To remove all the nodes and start over again with a different environment or dif $ chef exec rake destroy_machines ``` -To refresh all the cookbooks, use the following rake commands. +To refresh all cookbooks, use the following commands. ```bash -$ chef exec rake destroy_cookbooks +$ rm -rf cookbooks $ chef exec rake berks_vendor ``` -To cleanup everything, use the following rake command. +To clean up everything, use the following rake command. ```bash $ chef exec rake clean @@ -182,17 +213,13 @@ $ chef exec rake clean See the doc/tools.md for more information. -## The provisioning cookbook +## Data Bags -See site-cookbooks/provisioning/README.md for more information - -## Databags - -Some basic information about the use of databags within this repo. +Some basic information about the use of data bags within this repo. ``` -# Show the list of databags -$ chef exec knife data bag list -z +# Show the list of data bags +$ chef exec knife data bag list -z db_passwords secrets service_passwords @@ -215,20 +242,23 @@ nova: mypass id: nova # Update contents of data bag item -# set EDITOR env var to your editor. For PowerShell, I used nano +# set EDITOR env var to your editor. eg. EDITOR=vi $ chef exec knife data bag edit secrets dispersion_auth_user -z ``` -### Data bag default values +### Data Bag Default Values db_passwords are set to "mypass" secrets are set to "_token" service_passwords are set to "mypass" user_passwords are set to "mypass" -### Default encrypted data bag secret +### Default Encrypted Data Bag Secret The default secret is stored here .chef/encrypted_data_bag_secret and referenced by .chef/knife.rb. +When we say defaults, we mean that they are known by everyone with access to +this repository. Change these to something else before deploying for real. + ## Known Issues and Workarounds ### Windows Platform @@ -241,7 +271,6 @@ When using this on a Windows platform, here are some tweaks to make this work: - Support for floating IPs - Better instructions for multi-node network setup -- Split out the `multi-neutron-network-node` cluster also so the network node is it's own machine - Easier debugging. Maybe a script to pull the logs from the controller. # License # diff --git a/doc/allinone.md b/doc/allinone.md index ebbe1ce..7c786be 100644 --- a/doc/allinone.md +++ b/doc/allinone.md @@ -1,24 +1,3 @@ -# All in One with Neutron +# allinone with Neutron -Note: Default operating system is Ubuntu. If you would like CentOS, set env var REPO_OS=centos7 - -## Networking setup - -Changes need to be made to the allinone.rb file. - -### Device interface - -OVS needs to bridge in an adaptor for internet access. An attempt -has been made to work out of the box, however it is quite probable -you'll need to specify the bridge to use. You can set the environment -variable `OS_BRIDGE` before running the vagrant command to set it. - -For example on my Ubuntu laptop I run `export OS_BRIDGE=eth0` before -running the rake commands. - -Note: To see a list of virtualbox network interface names use: - `$ vboxmanage list bridgedifs` - -+ For Windows 7, open the Control Panel, Network and Internet, Network Connections. Look in the Connectivity column for a row with "Internet access", and use the "Device Name". For example, `'Intel(R) Centrino(R) Advanced-N 6205'`. -+ For Mac, this works from some: `'en0: Wi-Fi (AirPort)'`, but there is an issue with VirtualBox and the Airport. You should look into using an Ethernet adaptor and something like: `'en3: Ethernet'` -+ For Linux, ...TODO... +Note: It is advised to only use allinone in a CI setting. This is not production-ready. No changes should need to be made. diff --git a/doc/databags.md b/doc/data_bags.md similarity index 82% rename from doc/databags.md rename to doc/data_bags.md index 919c78b..d74eeb6 100644 --- a/doc/databags.md +++ b/doc/data_bags.md @@ -1,9 +1,9 @@ -# Databags +# Data Bags -Some basic information about the use of databags within this repo. +Some basic information about the use of data bags within this repo. ``` -# Show the list of databags +# Show the list of data bags $ chef exec knife data bag list -z db_passwords secrets @@ -43,21 +43,23 @@ $ chef exec knife data bag edit secrets dispersion_auth_user -z | service_passwords are set to "mypass" | | user_passwords are set to "mypass" | -## Encrypted data bag secret +## Encrypted Data Bag Secret The default secret is stored here `.chef/encrypted_data_bag_secret` and referenced by `.chef/knife.rb`. -## Creating "new data_bags" +## Creating New Data Bags -If you would like to create a new set of data_bags, first you need to update your `encrypted_data_bag_secret` with something like the following: +If you would like to create a new set of data bags, first you need to update +your `encrypted_data_bag_secret` with something like the following: ``` openssl rand -base64 512 | tr -d '\r\n' > encrypted_data_bag_secret ``` -### Database passwords +### Database Passwords -Then you need to create new data_bags for each of the databases you'll want to use, such as: +Then you need to create new data bags for each of the databases you'll want to +use, such as: An example json: ```json @@ -80,11 +82,18 @@ chef exec knife data bag create db_passwords neutron --secret-file .chef/encrypt chef exec knife data bag create db_passwords nova --secret-file .chef/encrypted_data_bag_secret ``` -### Swift secrets +### Swift Secrets -If you're using swift, you'll need to update the attributes from [data_bags/secrets](data_bags/secrets), and the changes are [here](https://github.com/openstack/cookbook-openstack-object-storage/blob/master/README.md#attributes). + NOTE: Swift is currently not supported with the OpenStack cookbooks, so these + directions may or may not work. If you would like to help maintain it, + please get in contact with the maintainer team. -These are for anything after Juno's release. If you're doing something before Juno, please check that attributes.rb +If you're using swift, you'll need to update the attributes from +[data_bags/secrets](data_bags/secrets), and the changes are +[here](https://github.com/openstack/cookbook-openstack-object-storage/blob/master/README.md#attributes). + +These are for anything after Juno's release. If you're doing something before +Juno, please check that attributes.rb ```json { @@ -98,7 +107,7 @@ chef exec knife data bag create secrets swift_hash_path_prefix --secret-file .ch chef exec knife data bag create secrets swift_hash_path_suffix --secret-file .chef/encrypted_data_bag_secret ``` -You'll want to create a new authkey, and dispersion keys: +You'll want to create a new auth key, and dispersion keys: ``` chef exec knife data bag create secrets swift_authkey --secret-file .chef/encrypted_data_bag_secret @@ -106,7 +115,7 @@ chef exec knife data bag create secrets dispersion_auth_user --secret-file .chef chef exec knife data bag create secrets dispersion_auth_key --secret-file .chef/encrypted_data_bag_secret ``` -### Neutron secrets +### Neutron Secrets Next you'll want to update your neutron metadata secret: @@ -114,7 +123,7 @@ Next you'll want to update your neutron metadata secret: chef exec knife data bag create secrets neutron_metadata_secret --secret-file .chef/encrypted_data_bag_secret ``` -### Keystone secrets +### Keystone Secrets You'll want to update your keystone identity bootstrap token: @@ -122,7 +131,7 @@ You'll want to update your keystone identity bootstrap token: chef exec knife data bag create secrets openstack_idenitity_bootstrap_token --secret-file .chef/encrypted_data_bag_secret ``` -### Service passwords +### Service Passwords How to update the service passwords: @@ -144,7 +153,7 @@ chef exec knife data bag create service_passwords openstack-orchestration --secr chef exec knife data bag create service_passwords rbd --secret-file .chef/encrypted_data_bag_secret ``` -### User passwords +### User Passwords If you would like to change the user passwords from `mypass`: diff --git a/doc/multi_node.md b/doc/multi_node.md deleted file mode 100644 index 4d3ec85..0000000 --- a/doc/multi_node.md +++ /dev/null @@ -1,29 +0,0 @@ -# Multi Node with Neutron - -Note: Default operating system is Ubuntu. If you would like CentOS, set env var REPO_OS=centos7 - -## Networking setup - -Changes need to be made to the multi-node.rb file. - -## Node setup - -The current multi_node rake task will create a three node OpenStack cluster -consisting of: - -One controller-node hosting all the APIs (nova, neutron, cinder, glance, -keystone and heat) as well as a mysql database and a rabbitmq server. The -dasboard is run by default inside of an apache2 server. In addition to the APIs, -the controller also functions as the "network-node" and hosts the -neutron- (l3, dhcp and ovs) -agent to provide network connectivity (currently -only internal, and not to the outside world or the internet). - -Two compute-nodes with the nova-compute service to run instances using qemu and -the neutron-ovs-agent for network connectivity to the contoller/network-node. - -## TODO - -* Currently no connectivity to the outside is supported out of the box. To do - this, we need to bridge one of the interfaces of the controller/network node - to the outside and utilise it as a public network. -* Add more detailed documentation diff --git a/doc/multinode.md b/doc/multinode.md new file mode 100644 index 0000000..54d8964 --- /dev/null +++ b/doc/multinode.md @@ -0,0 +1,23 @@ +# Multinode With Neutron + +Note: Default operating system is Ubuntu. CentOS is also supported. + +## Node setup + +The current multinode rake task will create a four node OpenStack cluster +consisting of: + +One controller node hosting all the APIs (Nova, Neutron, Cinder, Glance, +Keystone and Heat) as well as a MySQL database and a RabbitMQ server. The +dashboard is run by default inside of an apache2 server. + +The "network node" hosts the neutron agents (L3, DHCP, OVS) to provide network +connectivity internally and to the outside world. It provides this connectivity +by bridging to an interface running on the host machine. + +Two compute nodes with the nova-compute service to run instances using qemu and +the neutron-ovs-agent for network connectivity to the controller/network node. + +## TODO + +* Add more detailed documentation