openstack/openstack-chef-repo
Code Issues Proposed changes

Add Chef OpenStack contributor, install guides

Browse Source 
This change removes the markdown documentation in favor of a set of
rST documents generated with OpenStack branding.

Change-Id: I364ef53e24aed5f4721c5f3d56cc1d63966b4e88
This commit is contained in:
Samuel Cassiba 2018-05-19 01:43:11 -07:00
parent 1ab0e70201
commit cc6681b7f8
25 changed files with 666 additions and 262 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
.gitignore vendored
View File

@ -14,3 +14,4 @@ vms/
.chef/validator.pem .chef/validator.pem
.chef/local-mode-cache/ .chef/local-mode-cache/
.project .project
.tox

3
doc/allinone.md
View File

@ -1,3 +0,0 @@
# allinone with Neutron
Note: It is advised to only use allinone in a CI setting. This is not production-ready. No changes should need to be made.

171
doc/data_bags.md
View File

@ -1,171 +0,0 @@
# Data Bags
Some basic information about the use of data bags within this repo.
```
# Show the list of data bags
$ chef exec knife data bag list -z
db_passwords
secrets
service_passwords
user_passwords
# Show the list of data bag items
$ chef exec knife data bag show db_passwords -z
ceilometer
cinder
dash
glance
heat
horizon
ironic
keystone
neutron
nova
# Show contents of data bag item
$ chef exec knife data bag show db_passwords ceilometer -z
Encrypted data bag detected, decrypting with provided secret.
ceilometer: mypass
id: ceilometer
# Update contents of data bag item
# set EDITOR env var to your editor. For powershell, I used nano
$ chef exec knife data bag edit secrets dispersion_auth_user -z
```
| 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" |
## 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
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
Then you need to create new data bags for each of the databases you'll want to
use, such as:
An example json:
```json
{
"id": "ceilometer",
"ceilometer": "SOME_PASSWORD"
}
```
```
chef exec knife data bag create db_passwords ceilometer --secret-file .chef/encrypted_data_bag_secret
chef exec knife data bag create db_passwords cinder --secret-file .chef/encrypted_data_bag_secret
chef exec knife data bag create db_passwords dash --secret-file .chef/encrypted_data_bag_secret
chef exec knife data bag create db_passwords glance --secret-file .chef/encrypted_data_bag_secret
chef exec knife data bag create db_passwords heat --secret-file .chef/encrypted_data_bag_secret
chef exec knife data bag create db_passwords horizon --secret-file .chef/encrypted_data_bag_secret
chef exec knife data bag create db_passwords ironic --secret-file .chef/encrypted_data_bag_secret
chef exec knife data bag create db_passwords keystone --secret-file .chef/encrypted_data_bag_secret
chef exec knife data bag create db_passwords neutron --secret-file .chef/encrypted_data_bag_secret
chef exec knife data bag create db_passwords nova --secret-file .chef/encrypted_data_bag_secret
```
### Swift Secrets
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.
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
{
"id": "swift_hash_path_prefix",
"swift_hash_path_prefix": "SOME_PREFIX"
}
```
```
chef exec knife data bag create secrets swift_hash_path_prefix --secret-file .chef/encrypted_data_bag_secret
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 auth key, and dispersion keys:
```
chef exec knife data bag create secrets swift_authkey --secret-file .chef/encrypted_data_bag_secret
chef exec knife data bag create secrets dispersion_auth_user --secret-file .chef/encrypted_data_bag_secret
chef exec knife data bag create secrets dispersion_auth_key --secret-file .chef/encrypted_data_bag_secret
```
### Neutron Secrets
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
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
How to update the service passwords:
```json
{
"id": "openstack-compute",
"openstack-compute": "SOME_PASSWORD"
}
```
```
chef exec knife data bag create service_passwords openstack-bare-metal --secret-file .chef/encrypted_data_bag_secret
chef exec knife data bag create service_passwords openstack-block-storage --secret-file .chef/encrypted_data_bag_secret
chef exec knife data bag create service_passwords openstack-compute --secret-file .chef/encrypted_data_bag_secret
chef exec knife data bag create service_passwords openstack-image --secret-file .chef/encrypted_data_bag_secret
chef exec knife data bag create service_passwords openstack-network --secret-file .chef/encrypted_data_bag_secret
chef exec knife data bag create service_passwords openstack-object-storage --secret-file .chef/encrypted_data_bag_secret
chef exec knife data bag create service_passwords openstack-orchestration --secret-file .chef/encrypted_data_bag_secret
chef exec knife data bag create service_passwords rbd --secret-file .chef/encrypted_data_bag_secret
```
### User Passwords
If you would like to change the user passwords from `mypass`:
```json
{
"id": "guest",
"guest": "SOME_PASSWORD"
}
```
```
chef exec knife data bag create user_passwords admin --secret-file .chef/encrypted_data_bag_secret
chef exec knife data bag create user_passwords guest --secret-file .chef/encrypted_data_bag_secret
chef exec knife data bag create user_passwords mysqlroot --secret-file .chef/encrypted_data_bag_secret
```

23
doc/multinode.md
View File

@ -1,23 +0,0 @@
# 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

40
doc/openstack-service.conf.erb.md
View File

@ -1,40 +0,0 @@
# Render all openstack-service configuration files from attributes
Note: This functionality has been added in mitaka and replaces most of the
previously existing template files to generate service configurations like
nova.conf, neutron.conf or even ml2_conf.ini.
# Usage
All service configuration files following the [INI file
format](https://en.wikipedia.org/wiki/INI_file) can be created with the template
from the [openstack-common cookbook]
(https://github.com/openstack/cookbook-openstack-common/blob/master/templates/default/openstack-service.conf.erb).
The attributes to create for example the neutron.conf have to follow this
format:
```
default['openstack']['network']['conf'][$SECTION][$PROPERTY][$VALUE]
```
In the case given above, you first have to select the proper section ($SECTION)
like 'DEFAULT' or 'keystone_authtoken'. After that you can simply select the
property (e.g. 'log_file', 'verbose' or 'password') and its value (e.g.
'/var/log/neutron/neutron-server.log', true or 'mypass'). The given examples would render
something similar to this:
```
['DEFAULT']
log_file = /var/log/neutron/neutron-server.log
verbose = true
['keystone_authtoken']
password = mypass
```
The exact same logic is used for most services (currently keystone, nova,
neutron (conf and plugin files), cinder and glance) and will be adapted for all
other services and config files throughout the openstack cookbooks if possible.
TODO: add more specifics of the used defaults to each service cookbook and link
these sections here

3
doc/requirements.txt Normal file
View File

@ -0,0 +1,3 @@
sphinx!=1.6.6,!=1.6.7,>=1.6.2 # BSD
openstackdocstheme>=1.18.0 # Apache-2.0
pbr>=1.6 # Apache-2.0

189
doc/source/conf.py Normal file
View File

@ -0,0 +1,189 @@
# -*- coding: utf-8 -*-
#
# Configuration file for the Sphinx documentation builder.
#
# This file does only contain a selection of the most common options. For a
# full list see the documentation:
# http://www.sphinx-doc.org/en/stable/config
# -- Path setup --------------------------------------------------------------
import imp
import os
import re
import sys
import openstackdocstheme
# -- Chef OpenStack configuration --------------------------------------------
previous_series_name = 'pike'
current_series_name = 'queens'
# -- Project information -----------------------------------------------------
title = u'Chef OpenStack Documentation'
copyright = u'2018, Chef OpenStack Contributors'
author = u'Chef OpenStack Contributors'
# The short X.Y version
version = u''
# The full version, including alpha/beta/rc tags
release = u''
current_series = openstackdocstheme.ext._get_series_name()
if current_series == "latest":
watermark = "Pre-release"
latest_tag = "master"
branch = "master"
upgrade_warning = "Upgrading to master is not recommended. Master is under heavy development, and is not stable."
else:
watermark = series_names = current_series.capitalize()
latest_tag = os.popen('git describe --abbrev=0 --tags').read().strip('\n')
branch = "stable/{}".format(current_series)
upgrade_warning = "The upgrade is always under active development."
# Substitutions loader
rst_epilog = """
.. |current_release_git_branch_name| replace:: {current_release_git_branch_name}
.. |previous_release_formal_name| replace:: {previous_release_formal_name}
.. |current_release_formal_name| replace:: {current_release_formal_name}
.. |latest_tag| replace:: {latest_tag}
.. |upgrade_warning| replace:: {upgrade_warning}
""".format(
current_release_git_branch_name=branch,
previous_release_formal_name=previous_series_name.capitalize(),
current_release_formal_name=current_series_name.capitalize(),
latest_tag=latest_tag,
upgrade_warning=upgrade_warning,
)
# -- General configuration ---------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
#
# needs_sphinx = '1.0'
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
'openstackdocstheme',
'sphinx.ext.autodoc',
'sphinx.ext.todo',
'sphinx.ext.viewcode',
]
todo_include_docs = True
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
# The suffix(es) of source filenames.
source_suffix = '.rst'
# The master toctree document.
master_doc = 'index'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#
# This is also used if you do content translation via gettext catalogs.
# Usually you set "language" from the command line for these cases.
language = None
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This pattern also affects html_static_path and html_extra_path .
exclude_patterns = ['_build']
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
# A list of ignored prefixes for mod_index sorting.
modindex_common_prefix = ['chef-openstack-guide.']
# -- Options for HTML output -------------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
#
html_theme = 'openstackdocs'
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
#
# html_theme_options = {}
# The default sidebars (for documents that don't match any pattern) are
# defined by theme itself. Builtin themes are using these templates by
# default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
# 'searchbox.html']``.
#
# html_sidebars = {}
# -- Options for HTMLHelp output ---------------------------------------------
# Output file base name for HTML help builder.
htmlhelp_basename = 'ChefOpenStackGuidedoc'
# -- Options for LaTeX output ------------------------------------------------
latex_elements = {
# The paper size ('letterpaper' or 'a4paper').
#
# 'papersize': 'letterpaper',
# The font size ('10pt', '11pt' or '12pt').
#
# 'pointsize': '10pt',
# Additional stuff for the LaTeX preamble.
#
# 'preamble': '',
# Latex figure (float) alignment
#
# 'figure_align': 'htbp',
}
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title,
# author, documentclass [howto, manual, or own class]).
latex_documents = [
(master_doc, 'ChefOpenStackGuide.tex', u'Chef OpenStack Guide Documentation',
u'OpenStack Contributors', 'manual'),
]
# -- Options for manual page output ------------------------------------------
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
(master_doc, 'chefopenstackguide', u'Chef OpenStack Guide Documentation',
[author], 1)
]
# -- Options for Texinfo output ----------------------------------------------
# Grouping the document tree into Texinfo files. List of tuples
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
(master_doc, 'ChefOpenStackGuide', u'Chef OpenStack Guide Documentation',
author, 'ChefOpenStackGuide', 'One line description of project.',
'Miscellaneous'),
]
# -- Extension configuration -------------------------------------------------
# -- Options for todo extension ----------------------------------------------
# If true, `todo` and `todoList` produce output, else they produce nothing.
todo_include_todos = True

26
doc/source/contributor/ci.rst Normal file
View File

@ -0,0 +1,26 @@
.. _ci:
######################
Continuous Integration
######################
This is a list of the CI jobs that are running against most of the Chef
OpenStack cookbooks. The code that configures Zuul jobs is hosted in
`openstack-chef-repo <https://git.openstack.org/cgit/openstack/openstack-chef-repo/tree/playbooks/>`_.
.. list-table:: **CI Jobs in Chef OpenStack**
:widths: 31 25 8 55
:header-rows: 1
* - Job name
- Description
- Voting
- If it fails
* - openstack-chef-repo-rake
- It ensures the code follows the `Chef style guidelines <https://docs.chef.io/ruby.html>`_.
- Yes
- Read the build logs to see which part of the code does not follow the recommended patterns.
* - openstack-chef-repo-integration
- Functional testing job that converges OpenStack, testing using Tempest.
- Yes
- Read the build logs to see where the failure originated.

39
doc/source/contributor/community.rst Normal file
View File

@ -0,0 +1,39 @@
=========
Community
=========
Governance
==========
Chef OpenStack governance is well defined and `documented`_. It documents:
* The current Project Team Lead
* The mission statement
* The repositories managed by the group
PTL duty
========
While the official OpenStack PTL duty `guide`_ is general, the Chef
OpenStack PTL is usually in charge of:
* continuity of the project. This can include reviewing or writing code.
* OpenStack cross-project liaison.
* meeting organization.
Core reviewers team
===================
Chef OpenStack has a `core reviewers`_ team, that can merge any code in our
repositories.
Release management
==================
Releases are currently managed by the release `subteam`_. This is sometimes a
PTL task. This includes updating Supermarket.
.. _documented: https://governance.openstack.org/reference/projects/chef-openstack.html
.. _core reviewers: https://review.openstack.org/#/admin/groups/1260,members
.. _subteam: https://review.openstack.org/#/admin/groups/1261,members
.. _guide: https://docs.openstack.org/project-team-guide/ptl.html

37
doc/source/contributor/cookbook-list.rst Normal file
View File

@ -0,0 +1,37 @@
=============
Cookbook List
=============
Each Chef OpenStack cookbook corresponds to an OpenStack component and has its
own git repository. The cookbooks produce a number of deliverables, in order to
achieve a clearly stated objective: deploy OpenStack.
OpenStack Cookbooks
===================
* `Block Storage <https://git.openstack.org/cgit/openstack/cookbook-openstack-block-storage/>`_ (*Cinder*)
* `Compute <https://git.openstack.org/cgit/openstack/cookbook-openstack-compute/>`_ (*Nova*)
* `Dashboard <https://git.openstack.org/cgit/openstack/cookbook-openstack-dashboard/>`_ (*Horizon*)
* `DNS <https://git.openstack.org/cgit/openstack/cookbook-openstack-dns/>`_ (*Designate*)
* `Image <https://git.openstack.org/cgit/openstack/cookbook-openstack-image/>`_ (*Glance*)
* `Network <https://git.openstack.org/cgit/openstack/cookbook-openstack-network/>`_ (*Neutron*)
* `Orchestration <https://git.openstack.org/cgit/openstack/cookbook-openstack-orchestration/>`_ (*Heat*)
* `Telemetry <https://git.openstack.org/cgit/openstack/cookbook-openstack-telemetry/>`_ (*Ceilometer*/*Gnocchi*)
Operations Cookbooks
====================
* `Database <https://git.openstack.org/cgit/openstack/cookbook-openstack-ops-database/>`_ (*MariaDB*/*MySQL*)
* `Messaging <https://git.openstack.org/cgit/openstack/cookbook-openstack-ops-messaging/>`_ (*RabbitMQ*)
Supporting Repositories
=======================
* `Client <https://git.openstack.org/cgit/openstack/cookbook-openstackclient>`_ (LWRPs for using fog-openstack inside Chef recipes)
* `Integration Test <https://git.openstack.org/cgit/openstack/cookbook-openstack-integration-test/>`_ (Build cookbook to deploy and test using Tempest)
Unmaintained Cookbooks
==============================
* `Object Storage <https://git.openstack.org/cgit/openstack/cookbook-openstack-object-storage/>`_ (*Swift*)
* `Bare Metal <https://git.openstack.org/cgit/openstack/cookbook-openstack-bare-metal/>`_ (*Ironic*)
* `Data Processing <https://git.openstack.org/cgit/openstack/cookbook-openstack-data-processing/>`_ (*Sahara*)
* `Application Catalog <https://git.openstack.org/cgit/opentack/cookbook-openstack-application-catalog/>`_ (*Murano*)
* `Database as a Service <https://git.openstack.org/cgit/openstack/cookbook-openstack-database/>`_ (*Trove*)

9
doc/source/contributor/how-to-contribute.rst Normal file
View File

@ -0,0 +1,9 @@
======================
How to submit a change
======================
Do you want to submit a change to OpenStack?
Review the `Developer's Guide`_.
.. _Developer's Guide: https://docs.openstack.org/infra/manual/developers.html

12
doc/source/contributor/index.rst Normal file
View File

@ -0,0 +1,12 @@
Chef OpenStack Contributor Guide
================================
.. toctree::
:maxdepth: 2
:includehidden:
cookbook-list
how-to-contribute
community
talk-to-us
ci

15
doc/source/contributor/mailing-list.rst Normal file
View File

@ -0,0 +1,15 @@
.. _mailing_list:
=============
Mailing lists
=============
The mailing lists are preferred, as it makes the information more readily available so that others who have the same question or issue can search for and find the answers.
- Dev discussions:
`openstack-dev@lists.openstack.org <http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev>`__
with ``[chef]`` tag.
- Usage discussions:
`openstack-operators@lists.openstack.org <http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators>`__
with ``[chef]`` tag.

32
doc/source/contributor/meetings.rst Normal file
View File

@ -0,0 +1,32 @@
.. _meetings:
########
Meetings
########
1. `General Availability`_
2. `IRC Meetings`_
General Availability
====================
The Chef OpenStack team is distributed around the world, but comes together on
IRC_ between the hours of 14:00 UTC and 17:00 UTC.
.. _IRC: talk-to-us.html
IRC Meetings
============
We hold public meetings as needed on ``#openstack-chef`` on Freenode. If a
meeting needs to be held, it will be announced on the OpenStack-dev mailing
list.
.. list-table::
:widths: 30 60
:header-rows: 1
* - Meeting Time
- Local Time
* - UTC 1500 Mondays as needed
- https://www.timeanddate.com/worldclock/converter.html

14
doc/source/contributor/talk-to-us.rst Normal file
View File

@ -0,0 +1,14 @@
==========
Talk to us
==========
* Find us on `Freenode <https://freenode.net/>`_. Join the ``#openstack-chef`` channel.
* Join the conversation on the `mailing lists <mailing-list.html>`_.
* Participate in or propose `an IRC meeting <meetings.html>`_.
.. toctree::
:maxdepth: 1
:hidden:
mailing-list
meetings

23
doc/source/index.rst Normal file
View File

@ -0,0 +1,23 @@
Welcome to the Chef OpenStack Guide!
=====================================
The Chef cookbooks for OpenStack automate the building, operation and
consumption of OpenStack cloud deployments.
Contributor Guide
-----------------
.. toctree::
:maxdepth: 2
:includehidden:
contributor/index
Install Guide
-------------
.. toctree::
:maxdepth: 2
:includehidden:
install/index

56
doc/source/install/genealogy.rst Normal file
View File

@ -0,0 +1,56 @@
=========
Genealogy
=========
- `Releases Summary`_
- `Supermarket Releases`_
- `How to release Chef cookbooks`_
Releases Summary
================
+----------------------------+------------------------------+------------------------+
| Module Version | OpenStack Version Codename | Community Supported |
+============================+==============================+========================+
| 7.y.z | Grizzly | no - EOL (2014-03-29) |
+----------------------------+------------------------------+------------------------+
| 8.y.z | Havana | no - EOL (2014-09-30) |
+----------------------------+------------------------------+------------------------+
| 9.y.z | Icehouse | no - EOL (2015-07-02) |
+----------------------------+------------------------------+------------------------+
| 10.z.y | Juno | no - EOL (2015-12-07) |
+----------------------------+------------------------------+------------------------+
| 11.z.y | Kilo | no - EOL (2016-05-02) |
+----------------------------+------------------------------+------------------------+
| 12.z.y | Liberty | no - EOL (2016-11-17) |
+----------------------------+------------------------------+------------------------+
| 13.z.y | Mitaka | no - EOL (2017-04-10) |
+----------------------------+------------------------------+------------------------+
| 14.z.y | Newton | yes - EOL (2017-10-11) |
+----------------------------+------------------------------+------------------------+
| 15.z.y | Ocata | yes - EOL (2017-02-26) |
+----------------------------+------------------------------+------------------------+
| 16.z.y | Pike | yes |
+----------------------------+------------------------------+------------------------+
| 17.z.y | Queens | yes (current master) |
+----------------------------+------------------------------+------------------------+
| 18.z.y | Rocky | Future |
+----------------------------+------------------------------+------------------------+
Supermarket releases
====================
- From Ocata, the cookbooks are released on the Chef Supermarket_.
.. _Supermarket: https://supermarket.chef.io/openstack
How to release Chef cookbooks
=============================
- A core member will create the new branch based on the desired SHA.
Example: https://review.openstack.org/#/admin/projects/openstack/cookbook-openstack-compute,branches
- For all cookbooks to be released: update .gitreview, Berksfile,
and bootstrap.sh to stable/<release>
Example: https://review.openstack.org/547505
- Create a review with the above and propose it against the stable/<release> branch.
- Solicit for reviews and approval.

21
doc/source/install/getting-started.rst Normal file
View File

@ -0,0 +1,21 @@
===============
Getting Started
===============
Learn about Chef OpenStack
==========================
* To learn about the Chef automation framework,
consult the `online documentation <https://docs.chef.io>`_ or
`Learn Chef <https://learn.chef.io>`_.
* `Supported Platforms <supported-platforms.html>`_
* `Deploy <quickstart.html>`_ on your own development OpenStack Cloud with `Test Kitchen <https://kitchen.ci>`_.
* Chef OpenStack `genealogy <genealogy.html>`_.
.. toctree::
:maxdepth: 1
:hidden:
supported-platforms
quickstart
genealogy

11
doc/source/install/index.rst Normal file
View File

@ -0,0 +1,11 @@
Chef Openstack Install Guide
============================
.. toctree::
:maxdepth: 2
:includehidden:
getting-started
quickstart
genealogy
supported-platforms

102
doc/source/install/quickstart.rst Normal file
View File

@ -0,0 +1,102 @@
.. _quickstart-test-kitchen:
`Test Kitchen`_ is a no-fuss, no BS way to get a Chef OpenStack build for:
* development of OpenStack or applications on top of it
* a reference for how the services fit together
* a simple lab environment
.. _Test Kitchen: https://kitchen.ci/
Test Kitchen builds are not recommended for production deployments, but they can work in
a pinch when you just need OpenStack.
At an absolute minimum, you should use the following resources. What is listed
is currently used in CI for the gate checks, as well as the tested minimum:
* 8 vCPU (tests as low as 4, but it tends to get CPU bound)
* 8 GB RAM (7 GB sort of works, but it's tight - expect OOM/slowness)
* 50 GB free disk space on the root partition
Recommended server resources:
* CPU/motherboard that supports `hardware-assisted virtualization`_
* 8 CPU cores
* 16 GB RAM
* 80 GB free disk space on the root partition, or 50+ GB on a blank secondary volume.
It is `possible` to perform builds within a virtual machine for
demonstration and evaluation, but your virtual machines will perform poorly.
For production workloads, multiple nodes for specific roles are recommended.
.. _hardware-assisted virtualization: https://en.wikipedia.org/wiki/Hardware-assisted_virtualization
Building with Test Kitchen
--------------------------
There are three basic steps to building OpenStack with Test Kitchen, with an optional first step should you need to customize your build:
* Configuration *(this step is optional)*
* Install and bootstrap the Chef Development Kit
* Run Test Kitchen
When building on a new server, it is recommended that all system
packages are updated and then rebooted into the new kernel:
.. note:: Execute the following commands and scripts as the root user.
.. code-block:: shell-session
## Ubuntu
# apt-get update
# apt-get dist-upgrade
# reboot
.. code-block:: shell-session
## CentOS
# yum upgrade
# reboot
Start by cloing the OpenStack chef-repo repository and changing into the root directory:
.. code-block:: shell-session
# git clone https://git.openstack.org/openstack/openstack-chef-repo \
/opt/openstack-chef-repo
# cd openstack-chef-repo
Next, switch to the applicable branch/tag to be deployed. Note that deploying
from the head of a branch may result in an unstable build due to changes in
flight and upstream OpenStack changes. For a test (not a development) build, it
is usually best to checkout the latest tagged version.
.. parsed-literal::
## List all existing branches.
# git branch -v
## Checkout the stable branch
# git checkout |current_release_git_branch_name|
.. note::
The |current_release_formal_name| release is compatible with Ubuntu 16.04
(Xenial Xerus) and CentOS 7
By default the cookbooks deploy all OpenStack services with sensible defaults
for the purpose of a gate check, development or testing system.
Deployers have the option to change how the build is configured by overriding
in the respective kitche YAML file. This can be useful when you want to make
use of different services or test new cookbooks.
To use a different driver for Test Kitchen, such as for a multi-node
development environment, pass the ``KITCHEN_YAML`` environment variable as an
additional option to the ``kitchen`` command. For example, if you want to
deploy a multi-node development environment, instead of an AIO, then execute:
.. code-block:: shell-session
# KITCHEN_YAML=.kitchen.multi.yml kitchen converge [7|1604|all]

16
doc/source/install/supported-platforms.rst Normal file
View File

@ -0,0 +1,16 @@
Supported Platforms
===================
The following operating systems and versions are supported by the OpenStack cookbooks:
* RHEL / CentOS 7
* Ubuntu 16.04 LTS (Xenial Xerus)
The cookbooks are tested and verified to work on the Chef stable track using
the `Chef Development Kit <https://docs.chef.io/about_chefdk.html>`_.
Your success rate may vary with the bleeding edge. Chef 12 and older is NOT
supported.
See `Chef CI <http://docs.openstack.org/developer/chef-openstack-guide/ci.html>`_
to see what is currently tested.

25
doc/tools.md
View File

@ -1,25 +0,0 @@
# Tools
## Using the test_patch tool
The tools/test_patch.rb tool will do most of the heavy lifting of testing out one or more patches.
It will basically create a clean environment with a copy of the repo and the patched cookbook, and then run
one of the test environments.
To see the various options and help:
```shell
$ chef exec ruby tools\test_patch.rb help test
```
## Cookbook Patch Development
The Berksfile in this repo has been enhanced to look for local working cookbook development directories and use them
to when running the test suite. Simply set REPO_DEV=True and create a directory tree as follows:
* base_dev_dir\
** openstack-chef-repo
** cookbook-openstack-***
When doing the 'chef exec rake berks_vendor', the Berks file will pick up cookbooks changes from the
cookbook-openstack-*** directories.

23
setup.cfg Normal file
View File

@ -0,0 +1,23 @@
[metadata]
name = chef-openstack-guide
summary = Chef OpenStack Guide
description-file =
README.md
author = OpenStack
author-email = openstack@lists.openstack.org
home-page = http://www.openstack.org/
classifier =
Intended Audience :: Developers
License :: OSI Approved :: Apache Software License
Operating System :: POSIX :: Linux
[build_sphinx]
all_files = 1
build-dir = doc/build
source-dir = doc/source
[pbr]
warnerrors = True
[wheel]
universal = 1

21
setup.py Normal file
View File

@ -0,0 +1,21 @@
#!/usr/bin/env python
# Copyright (c) 2013 Hewlett-Packard Development Company, L.P.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
# implied.
# See the License for the specific language governing permissions and
# limitations under the License.
import setuptools
setuptools.setup(
setup_requires=['pbr'],
pbr=True)

16
tox.ini Normal file
View File

@ -0,0 +1,16 @@
[tox]
minversion = 1.6
envlist = docs
skipsdist = True
[testenv]
usedevelop = True
setenv = VIRTUAL_ENV={envdir}
install_command = pip install -c{env:UPPER_CONSTRAINTS_FILE:https://git.openstack.org/cgit/openstack/requirements/plain/upper-constraints.txt} {opts} {packages}
[testenv:venv]
commands = {posargs}
[testenv:docs]
deps = -r{toxinidir}/doc/requirements.txt
commands = sphinx-build -b html doc/source doc/build/html