diff --git a/.gitignore b/.gitignore index 172202b..a36b18b 100644 --- a/.gitignore +++ b/.gitignore @@ -14,3 +14,4 @@ vms/ .chef/validator.pem .chef/local-mode-cache/ .project +.tox diff --git a/doc/allinone.md b/doc/allinone.md deleted file mode 100644 index 7c786be..0000000 --- a/doc/allinone.md +++ /dev/null @@ -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. diff --git a/doc/data_bags.md b/doc/data_bags.md deleted file mode 100644 index d74eeb6..0000000 --- a/doc/data_bags.md +++ /dev/null @@ -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 "_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 -``` diff --git a/doc/multinode.md b/doc/multinode.md deleted file mode 100644 index 54d8964..0000000 --- a/doc/multinode.md +++ /dev/null @@ -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 diff --git a/doc/openstack-service.conf.erb.md b/doc/openstack-service.conf.erb.md deleted file mode 100644 index 1941fbc..0000000 --- a/doc/openstack-service.conf.erb.md +++ /dev/null @@ -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 diff --git a/doc/requirements.txt b/doc/requirements.txt new file mode 100644 index 0000000..626130f --- /dev/null +++ b/doc/requirements.txt @@ -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 diff --git a/doc/source/conf.py b/doc/source/conf.py new file mode 100644 index 0000000..6e2e107 --- /dev/null +++ b/doc/source/conf.py @@ -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 diff --git a/doc/source/contributor/ci.rst b/doc/source/contributor/ci.rst new file mode 100644 index 0000000..e5e5a5e --- /dev/null +++ b/doc/source/contributor/ci.rst @@ -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 `_. + +.. 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 `_. + - 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. diff --git a/doc/source/contributor/community.rst b/doc/source/contributor/community.rst new file mode 100644 index 0000000..fb18447 --- /dev/null +++ b/doc/source/contributor/community.rst @@ -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 diff --git a/doc/source/contributor/cookbook-list.rst b/doc/source/contributor/cookbook-list.rst new file mode 100644 index 0000000..4c8de8b --- /dev/null +++ b/doc/source/contributor/cookbook-list.rst @@ -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 `_ (*Cinder*) +* `Compute `_ (*Nova*) +* `Dashboard `_ (*Horizon*) +* `DNS `_ (*Designate*) +* `Image `_ (*Glance*) +* `Network `_ (*Neutron*) +* `Orchestration `_ (*Heat*) +* `Telemetry `_ (*Ceilometer*/*Gnocchi*) + +Operations Cookbooks +==================== +* `Database `_ (*MariaDB*/*MySQL*) +* `Messaging `_ (*RabbitMQ*) + +Supporting Repositories +======================= +* `Client `_ (LWRPs for using fog-openstack inside Chef recipes) +* `Integration Test `_ (Build cookbook to deploy and test using Tempest) + +Unmaintained Cookbooks +============================== +* `Object Storage `_ (*Swift*) +* `Bare Metal `_ (*Ironic*) +* `Data Processing `_ (*Sahara*) +* `Application Catalog `_ (*Murano*) +* `Database as a Service `_ (*Trove*) diff --git a/doc/source/contributor/how-to-contribute.rst b/doc/source/contributor/how-to-contribute.rst new file mode 100644 index 0000000..71070f5 --- /dev/null +++ b/doc/source/contributor/how-to-contribute.rst @@ -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 diff --git a/doc/source/contributor/index.rst b/doc/source/contributor/index.rst new file mode 100644 index 0000000..2d336e8 --- /dev/null +++ b/doc/source/contributor/index.rst @@ -0,0 +1,12 @@ +Chef OpenStack Contributor Guide +================================ + +.. toctree:: + :maxdepth: 2 + :includehidden: + + cookbook-list + how-to-contribute + community + talk-to-us + ci diff --git a/doc/source/contributor/mailing-list.rst b/doc/source/contributor/mailing-list.rst new file mode 100644 index 0000000..756aa66 --- /dev/null +++ b/doc/source/contributor/mailing-list.rst @@ -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 `__ + with ``[chef]`` tag. +- Usage discussions: + `openstack-operators@lists.openstack.org `__ + with ``[chef]`` tag. + diff --git a/doc/source/contributor/meetings.rst b/doc/source/contributor/meetings.rst new file mode 100644 index 0000000..e0d6c6d --- /dev/null +++ b/doc/source/contributor/meetings.rst @@ -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 diff --git a/doc/source/contributor/talk-to-us.rst b/doc/source/contributor/talk-to-us.rst new file mode 100644 index 0000000..3a4dce8 --- /dev/null +++ b/doc/source/contributor/talk-to-us.rst @@ -0,0 +1,14 @@ +========== +Talk to us +========== + +* Find us on `Freenode `_. Join the ``#openstack-chef`` channel. +* Join the conversation on the `mailing lists `_. +* Participate in or propose `an IRC meeting `_. + +.. toctree:: + :maxdepth: 1 + :hidden: + + mailing-list + meetings diff --git a/doc/source/index.rst b/doc/source/index.rst new file mode 100644 index 0000000..20f8aa6 --- /dev/null +++ b/doc/source/index.rst @@ -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 diff --git a/doc/source/install/genealogy.rst b/doc/source/install/genealogy.rst new file mode 100644 index 0000000..98974da --- /dev/null +++ b/doc/source/install/genealogy.rst @@ -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/ + Example: https://review.openstack.org/547505 +- Create a review with the above and propose it against the stable/ branch. +- Solicit for reviews and approval. diff --git a/doc/source/install/getting-started.rst b/doc/source/install/getting-started.rst new file mode 100644 index 0000000..3c528ed --- /dev/null +++ b/doc/source/install/getting-started.rst @@ -0,0 +1,21 @@ +=============== +Getting Started +=============== + +Learn about Chef OpenStack +========================== + +* To learn about the Chef automation framework, + consult the `online documentation `_ or + `Learn Chef `_. +* `Supported Platforms `_ +* `Deploy `_ on your own development OpenStack Cloud with `Test Kitchen `_. +* Chef OpenStack `genealogy `_. + +.. toctree:: + :maxdepth: 1 + :hidden: + + supported-platforms + quickstart + genealogy diff --git a/doc/source/install/index.rst b/doc/source/install/index.rst new file mode 100644 index 0000000..30ad87d --- /dev/null +++ b/doc/source/install/index.rst @@ -0,0 +1,11 @@ +Chef Openstack Install Guide +============================ + +.. toctree:: + :maxdepth: 2 + :includehidden: + + getting-started + quickstart + genealogy + supported-platforms diff --git a/doc/source/install/quickstart.rst b/doc/source/install/quickstart.rst new file mode 100644 index 0000000..8ce48d7 --- /dev/null +++ b/doc/source/install/quickstart.rst @@ -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] + + diff --git a/doc/source/install/supported-platforms.rst b/doc/source/install/supported-platforms.rst new file mode 100644 index 0000000..eeaac09 --- /dev/null +++ b/doc/source/install/supported-platforms.rst @@ -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 `_. + +Your success rate may vary with the bleeding edge. Chef 12 and older is NOT +supported. + +See `Chef CI `_ +to see what is currently tested. diff --git a/doc/tools.md b/doc/tools.md deleted file mode 100644 index 46a58b1..0000000 --- a/doc/tools.md +++ /dev/null @@ -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. diff --git a/setup.cfg b/setup.cfg new file mode 100644 index 0000000..0e9d7a7 --- /dev/null +++ b/setup.cfg @@ -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 diff --git a/setup.py b/setup.py new file mode 100644 index 0000000..c0a24ea --- /dev/null +++ b/setup.py @@ -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) diff --git a/tox.ini b/tox.ini new file mode 100644 index 0000000..8fcdadf --- /dev/null +++ b/tox.ini @@ -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