diff --git a/{{cookiecutter.repo_name}}/install-guide/source/common_configure.rst b/{{cookiecutter.repo_name}}/install-guide/source/common_configure.rst new file mode 100644 index 0000000..fe5575a --- /dev/null +++ b/{{cookiecutter.repo_name}}/install-guide/source/common_configure.rst @@ -0,0 +1,10 @@ +2. Edit the ``/etc/{{cookiecutter.codename}}/{{cookiecutter.codename}}.conf`` file and complete the following + actions: + + * In the ``[database]`` section, configure database access: + + .. code-block:: none + + [database] + ... + connection = mysql+pymysql://{{cookiecutter.codename}}:{{cookiecutter.codename|upper}}_DBPASS@controller/{{cookiecutter.codename}} diff --git a/{{cookiecutter.repo_name}}/install-guide/source/common_prerequisites.rst b/{{cookiecutter.repo_name}}/install-guide/source/common_prerequisites.rst new file mode 100644 index 0000000..e1b49bb --- /dev/null +++ b/{{cookiecutter.repo_name}}/install-guide/source/common_prerequisites.rst @@ -0,0 +1,75 @@ +Prerequisites +------------- + +Before you install and configure the {{cookiecutter.service}} service, +you must create a database, service credentials, and API endpoints. + +#. To create the database, complete these steps: + + * Use the database access client to connect to the database + server as the ``root`` user: + + .. code-block:: console + + $ mysql -u root -p + + * Create the ``{{cookiecutter.codename}}`` database: + + .. code-block:: mysql + + CREATE DATABASE {{cookiecutter.codename}}; + + * Grant proper access to the ``{{cookiecutter.codename}}`` database: + + .. code-block:: mysql + + GRANT ALL PRIVILEGES ON {{cookiecutter.codename}}.* TO '{{cookiecutter.codename}}'@'localhost' \ + IDENTIFIED BY '{{cookiecutter.codename|upper}}_DBPASS'; + GRANT ALL PRIVILEGES ON {{cookiecutter.codename}}.* TO '{{cookiecutter.codename}}'@'%' \ + IDENTIFIED BY '{{cookiecutter.codename|upper}}_DBPASS'; + + Replace ``{{cookiecutter.codename|upper}}_DBPASS`` with a suitable password. + + * Exit the database access client. + + .. code-block:: mysql + + exit; + +#. Source the ``admin`` credentials to gain access to + admin-only CLI commands: + + .. code-block:: console + + $ source admin-openrc + +#. To create the service credentials, complete these steps: + + * Create the ``{{cookiecutter.codename}}`` user: + + .. code-block:: console + + $ openstack user create --domain default --password-prompt {{cookiecutter.codename}} + + * Add the ``admin`` role to the ``{{cookiecutter.codename}}`` user: + + .. code-block:: console + + $ openstack role add --project service --user {{cookiecutter.codename}} admin + + * Create the {{cookiecutter.codename}} service entities: + + .. code-block:: console + + $ openstack service create --name {{cookiecutter.codename}} --description "{{cookiecutter.service}}" {{cookiecutter.service|lower}} + +#. Create the {{cookiecutter.service}} service API endpoints: + + .. code-block:: console + + $ openstack endpoint create --region RegionOne \ + {{cookiecutter.service|lower}} public http://controller:XXXX/vY/%\(tenant_id\)s + $ openstack endpoint create --region RegionOne \ + {{cookiecutter.service|lower}} internal http://controller:XXXX/vY/%\(tenant_id\)s + $ openstack endpoint create --region RegionOne \ + {{cookiecutter.service|lower}} admin http://controller:XXXX/vY/%\(tenant_id\)s diff --git a/{{cookiecutter.repo_name}}/install-guide/source/conf.py b/{{cookiecutter.repo_name}}/install-guide/source/conf.py index 78372f1..390eec9 100644 --- a/{{cookiecutter.repo_name}}/install-guide/source/conf.py +++ b/{{cookiecutter.repo_name}}/install-guide/source/conf.py @@ -91,7 +91,7 @@ html_context = {"gitsha": gitsha, "bug_tag": bug_tag, # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. -exclude_patterns = [] +exclude_patterns = ["common_prerequisites.rst", "common_configure.rst"] # The reST default role (used for this markup: `text`) to use for all # documents. diff --git a/{{cookiecutter.repo_name}}/install-guide/source/index.rst b/{{cookiecutter.repo_name}}/install-guide/source/index.rst index 2adb77c..01d4936 100644 --- a/{{cookiecutter.repo_name}}/install-guide/source/index.rst +++ b/{{cookiecutter.repo_name}}/install-guide/source/index.rst @@ -3,6 +3,7 @@ ===================== .. toctree:: + :maxdepth: 2 get_started.rst install.rst @@ -11,6 +12,5 @@ The {{cookiecutter.service}} service ({{cookiecutter.codename}}) provides... -This chapter assumes a working setup of OpenStack following the base -Installation Guide. - +This chapter assumes a working setup of OpenStack following the +`OpenStack Installation Tutorial `_. diff --git a/{{cookiecutter.repo_name}}/install-guide/source/install-obs.rst b/{{cookiecutter.repo_name}}/install-guide/source/install-obs.rst new file mode 100644 index 0000000..16f113f --- /dev/null +++ b/{{cookiecutter.repo_name}}/install-guide/source/install-obs.rst @@ -0,0 +1,34 @@ +.. _install-obs: + + +Install and configure for openSUSE and SUSE Linux Enterprise +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This section describes how to install and configure the {{cookiecutter.service}} service +for openSUSE Leap 42.1 and SUSE Linux Enterprise Server 12 SP1. + +.. include:: common_prerequisites.rst + +Install and configure components +-------------------------------- + +#. Install the packages: + + .. code-block:: console + + # zypper --quiet --non-interactive install + +.. include:: common_configure.rst + + +Finalize installation +--------------------- + +Start the {{cookiecutter.service}} services and configure them to start when +the system boots: + +.. code-block:: console + + # systemctl enable openstack-{{cookiecutter.codename}}-api.service + + # systemctl start openstack-{{cookiecutter.codename}}-api.service diff --git a/{{cookiecutter.repo_name}}/install-guide/source/install-rdo.rst b/{{cookiecutter.repo_name}}/install-guide/source/install-rdo.rst new file mode 100644 index 0000000..3890fdd --- /dev/null +++ b/{{cookiecutter.repo_name}}/install-guide/source/install-rdo.rst @@ -0,0 +1,33 @@ +.. _install-rdo: + +Install and configure for Red Hat Enterprise Linux and CentOS +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + +This section describes how to install and configure the {{cookiecutter.service}} service +for Red Hat Enterprise Linux 7 and CentOS 7. + +.. include:: common_prerequisites.rst + +Install and configure components +-------------------------------- + +#. Install the packages: + + .. code-block:: console + + # yum install + +.. include:: common_configure.rst + +Finalize installation +--------------------- + +Start the {{cookiecutter.service}} services and configure them to start when +the system boots: + +.. code-block:: console + + # systemctl enable openstack-{{cookiecutter.codename}}-api.service + + # systemctl start openstack-{{cookiecutter.codename}}-api.service diff --git a/{{cookiecutter.repo_name}}/install-guide/source/install-ubuntu.rst b/{{cookiecutter.repo_name}}/install-guide/source/install-ubuntu.rst new file mode 100644 index 0000000..644f732 --- /dev/null +++ b/{{cookiecutter.repo_name}}/install-guide/source/install-ubuntu.rst @@ -0,0 +1,31 @@ +.. _install-ubuntu: + +Install and configure for Ubuntu +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This section describes how to install and configure the {{cookiecutter.service}} +service for Ubuntu 14.04 (LTS). + +.. include:: common_prerequisites.rst + +Install and configure components +-------------------------------- + +#. Install the packages: + + .. code-block:: console + + # apt-get update + + # apt-get install + +.. include:: common_configure.rst + +Finalize installation +--------------------- + +Restart the {{cookiecutter.service}} services: + +.. code-block:: console + + # service openstack-{{cookiecutter.codename}}-api restart diff --git a/{{cookiecutter.repo_name}}/install-guide/source/install.rst b/{{cookiecutter.repo_name}}/install-guide/source/install.rst index dc25af4..7622a47 100644 --- a/{{cookiecutter.repo_name}}/install-guide/source/install.rst +++ b/{{cookiecutter.repo_name}}/install-guide/source/install.rst @@ -7,89 +7,14 @@ This section describes how to install and configure the {{cookiecutter.service}} service, code-named {{cookiecutter.codename}}, on the controller node. This section assumes that you already have a working OpenStack -environment with at least the Identity service, the Compute service, -and the Image service installed. +environment with at least the following components installed: +.. (add the appropriate services here and further notes) -Prerequisites -------------- +Note that installation and configuration vary by distribution. -Before you install and configure the {{cookiecutter.service}} service, -you must create a database, service credentials, and API endpoints. - -#. To create the database, complete these steps: - - * Use the database access client to connect to the database - server as the ``root`` user: - - .. code-block:: console - - $ mysql -u root -p - - * Create the ``{{cookiecutter.codename}}`` database: - - .. code-block:: mysql - - CREATE DATABASE {{cookiecutter.codename}}; - - * Grant proper access to the ``{{cookiecutter.codename}}`` database: - - .. code-block:: mysql - - GRANT ALL PRIVILEGES ON {{cookiecutter.codename}}.* TO '{{cookiecutter.codename}}'@'localhost' \ - IDENTIFIED BY '{{cookiecutter.codename|upper}}_DBPASS'; - GRANT ALL PRIVILEGES ON {{cookiecutter.codename}}.* TO '{{cookiecutter.codename}}'@'%' \ - IDENTIFIED BY '{{cookiecutter.codename|upper}}_DBPASS'; - - Replace ``{{cookiecutter.codename|upper}}_DBPASS`` with a suitable password. - - * Exit the database access client. - - .. code-block:: mysql - - exit; - -#. Source the ``admin`` credentials to gain access to - admin-only CLI commands: - - .. code-block:: console - - $ source admin-openrc - -#. To create the service credentials, complete these steps: - - * Create the ``{{cookiecutter.codename}}`` user: - - .. code-block:: console - - $ openstack user create --domain default --password-prompt {{cookiecutter.codename}} - - * Add the ``admin`` role to the ``{{cookiecutter.codename}}`` user: - - .. code-block:: console - - $ openstack role add --project service --user {{cookiecutter.codename}} admin - - * Create the {{cookiecutter.codename}} service entities: - - .. code-block:: console - - $ openstack service create --name {{cookiecutter.codename}} --description "{{cookiecutter.service}}" {{cookiecutter.service|lower}} - -#. Create the {{cookiecutter.service}} service API endpoints: - - .. code-block:: console - - $ openstack endpoint create --region RegionOne \ - {{cookiecutter.service|lower}} public http://controller:XXXX/vY/%\(tenant_id\)s - $ openstack endpoint create --region RegionOne \ - {{cookiecutter.service|lower}} internal http://controller:XXXX/vY/%\(tenant_id\)s - $ openstack endpoint create --region RegionOne \ - {{cookiecutter.service|lower}} admin http://controller:XXXX/vY/%\(tenant_id\)s - -Install and configure components --------------------------------- - - -Finalize installation ---------------------- +.. toctree:: + :maxdepth: 2 + install-obs.rst + install-rdo.rst + install-ubuntu.rst