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
This commit is contained in:
Samuel Cassiba 2017-05-19 06:15:56 -07:00
parent ede4b00073
commit fd4105ac14
5 changed files with 150 additions and 139 deletions

171
README.md
View File

@ -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 <vm_name>`
```bash
$ ssh cirros@<ip address from nova list output>
$ ssh cirros@<ip address from openstack server list output>
```
#### 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 <controller>
$ 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 "<key>_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 #

View File

@ -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.

View File

@ -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`:

View File

@ -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

23
doc/multinode.md Normal file
View File

@ -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