From 31b31410f9dd6721e0e2322af677482fbe52465b Mon Sep 17 00:00:00 2001 From: KATO Tomoyuki Date: Sat, 14 May 2016 09:40:46 +0900 Subject: [PATCH] Factor out Install Guide for Debian with debconf To simplify the build tool chain, factor out Install Guide for Debian with debconf. Continueously, keep Install Guide for Debian without debconf in the doc/install-guide directory. Also, use the contents at doc/install-guide as possible for consistency. On the following patches, clean up doc/install-guide sources to cleanup the contents and build tool chains. Change-Id: I8df6b3b382137d08d60f85bc41bcd98ac1f4eb47 --- .gitignore | 1 + doc/install-guide-debconf/setup.cfg | 30 ++ doc/install-guide-debconf/setup.py | 30 ++ .../source/ceilometer-aodh.rst | 1 + .../source/ceilometer-cinder.rst | 1 + .../source/ceilometer-glance.rst | 1 + .../source/ceilometer-install.rst | 210 ++++++++++++ .../source/ceilometer-next-steps.rst | 1 + .../source/ceilometer-nova.rst | 1 + .../source/ceilometer-swift.rst | 1 + .../source/ceilometer-verify.rst | 1 + .../source/ceilometer.rst | 1 + .../source/cinder-controller-install.rst | 63 ++++ .../source/cinder-next-steps.rst | 1 + .../source/cinder-storage-install.rst | 1 + .../source/cinder-verify.rst | 1 + doc/install-guide-debconf/source/cinder.rst | 1 + doc/install-guide-debconf/source/common | 1 + doc/install-guide-debconf/source/conf.py | 308 ++++++++++++++++++ .../source/debconf/debconf-api-endpoints.rst | 101 ++++++ .../source/debconf/debconf-concepts.rst | 120 +++++++ .../debconf/debconf-dbconfig-common.rst | 167 ++++++++++ .../debconf/debconf-keystone-authtoken.rst | 56 ++++ .../source/debconf/debconf-rabbitmq.rst | 36 ++ .../source/debconf/debconf.rst | 14 + .../source/environment-memcached.rst | 1 + .../source/environment-messaging.rst | 1 + .../source/environment-networking-compute.rst | 1 + .../environment-networking-controller.rst | 1 + .../environment-networking-storage-cinder.rst | 1 + .../environment-networking-storage-swift.rst | 1 + .../source/environment-networking-verify.rst | 1 + .../source/environment-networking.rst | 1 + .../source/environment-nosql-database.rst | 1 + .../source/environment-ntp-controller.rst | 1 + .../source/environment-ntp-other.rst | 1 + .../source/environment-ntp-verify.rst | 1 + .../source/environment-ntp.rst | 1 + .../source/environment-packages.rst | 1 + .../source/environment-security.rst | 1 + .../source/environment-sql-database.rst | 1 + .../source/environment.rst | 1 + doc/install-guide-debconf/source/figures | 1 + .../source/glance-install.rst | 27 ++ .../source/glance-verify.rst | 1 + doc/install-guide-debconf/source/glance.rst | 1 + .../source/heat-install.rst | 44 +++ .../source/heat-next-steps.rst | 1 + .../source/heat-verify.rst | 1 + doc/install-guide-debconf/source/heat.rst | 1 + .../source/horizon-install.rst | 1 + .../source/horizon-next-steps.rst | 1 + .../source/horizon-verify.rst | 1 + doc/install-guide-debconf/source/horizon.rst | 1 + doc/install-guide-debconf/source/index.rst | 75 +++++ .../source/keystone-install.rst | 160 +++++++++ .../source/keystone-openrc.rst | 1 + .../source/keystone-services.rst | 1 + .../source/keystone-users.rst | 1 + .../source/keystone-verify.rst | 1 + doc/install-guide-debconf/source/keystone.rst | 1 + .../source/launch-instance-cinder.rst | 1 + .../source/launch-instance-heat.rst | 1 + ...nch-instance-manila-dhss-false-option1.rst | 1 + ...unch-instance-manila-dhss-true-option2.rst | 1 + .../source/launch-instance-manila.rst | 1 + .../launch-instance-networks-provider.rst | 1 + .../launch-instance-networks-selfservice.rst | 1 + .../source/launch-instance-provider.rst | 1 + .../source/launch-instance-selfservice.rst | 1 + .../source/launch-instance.rst | 1 + .../source/manila-controller-install.rst | 243 ++++++++++++++ .../source/manila-next-steps.rst | 1 + ...anila-share-install-dhss-false-option1.rst | 1 + ...manila-share-install-dhss-true-option2.rst | 1 + .../source/manila-share-install.rst | 1 + .../source/manila-verify.rst | 1 + doc/install-guide-debconf/source/manila.rst | 1 + .../neutron-compute-install-option1.rst | 1 + .../neutron-compute-install-option2.rst | 1 + .../source/neutron-compute-install.rst | 1 + .../source/neutron-concepts.rst | 1 + .../neutron-controller-install-option1.rst | 192 +++++++++++ .../neutron-controller-install-option2.rst | 205 ++++++++++++ .../source/neutron-controller-install.rst | 97 ++++++ .../source/neutron-next-steps.rst | 1 + .../source/neutron-verify-option1.rst | 1 + .../source/neutron-verify-option2.rst | 1 + .../source/neutron-verify.rst | 1 + doc/install-guide-debconf/source/neutron.rst | 1 + .../source/nova-compute-install.rst | 148 +++++++++ .../source/nova-controller-install.rst | 109 +++++++ .../source/nova-verify.rst | 1 + doc/install-guide-debconf/source/nova.rst | 1 + doc/install-guide-debconf/source/overview.rst | 1 + doc/install-guide-debconf/source/shared | 1 + .../source/swift-controller-include.txt | 1 + .../source/swift-controller-install.rst | 1 + .../source/swift-finalize-installation.rst | 1 + .../source/swift-initial-rings.rst | 1 + .../source/swift-next-steps.rst | 1 + .../source/swift-storage-include1.txt | 1 + .../source/swift-storage-include2.txt | 1 + .../source/swift-storage-include3.txt | 1 + .../source/swift-storage-install.rst | 1 + .../source/swift-verify.rst | 1 + doc/install-guide-debconf/source/swift.rst | 1 + .../source/trove-install.rst | 157 +++++++++ .../source/trove-next-steps.rst | 1 + .../source/trove-verify.rst | 1 + doc/install-guide-debconf/source/trove.rst | 1 + tools/build-install-guides-rst.sh | 94 +++--- tox.ini | 6 +- 113 files changed, 2737 insertions(+), 44 deletions(-) create mode 100644 doc/install-guide-debconf/setup.cfg create mode 100644 doc/install-guide-debconf/setup.py create mode 120000 doc/install-guide-debconf/source/ceilometer-aodh.rst create mode 120000 doc/install-guide-debconf/source/ceilometer-cinder.rst create mode 120000 doc/install-guide-debconf/source/ceilometer-glance.rst create mode 100644 doc/install-guide-debconf/source/ceilometer-install.rst create mode 120000 doc/install-guide-debconf/source/ceilometer-next-steps.rst create mode 120000 doc/install-guide-debconf/source/ceilometer-nova.rst create mode 120000 doc/install-guide-debconf/source/ceilometer-swift.rst create mode 120000 doc/install-guide-debconf/source/ceilometer-verify.rst create mode 120000 doc/install-guide-debconf/source/ceilometer.rst create mode 100644 doc/install-guide-debconf/source/cinder-controller-install.rst create mode 120000 doc/install-guide-debconf/source/cinder-next-steps.rst create mode 120000 doc/install-guide-debconf/source/cinder-storage-install.rst create mode 120000 doc/install-guide-debconf/source/cinder-verify.rst create mode 120000 doc/install-guide-debconf/source/cinder.rst create mode 120000 doc/install-guide-debconf/source/common create mode 100644 doc/install-guide-debconf/source/conf.py create mode 100644 doc/install-guide-debconf/source/debconf/debconf-api-endpoints.rst create mode 100644 doc/install-guide-debconf/source/debconf/debconf-concepts.rst create mode 100644 doc/install-guide-debconf/source/debconf/debconf-dbconfig-common.rst create mode 100644 doc/install-guide-debconf/source/debconf/debconf-keystone-authtoken.rst create mode 100644 doc/install-guide-debconf/source/debconf/debconf-rabbitmq.rst create mode 100644 doc/install-guide-debconf/source/debconf/debconf.rst create mode 120000 doc/install-guide-debconf/source/environment-memcached.rst create mode 120000 doc/install-guide-debconf/source/environment-messaging.rst create mode 120000 doc/install-guide-debconf/source/environment-networking-compute.rst create mode 120000 doc/install-guide-debconf/source/environment-networking-controller.rst create mode 120000 doc/install-guide-debconf/source/environment-networking-storage-cinder.rst create mode 120000 doc/install-guide-debconf/source/environment-networking-storage-swift.rst create mode 120000 doc/install-guide-debconf/source/environment-networking-verify.rst create mode 120000 doc/install-guide-debconf/source/environment-networking.rst create mode 120000 doc/install-guide-debconf/source/environment-nosql-database.rst create mode 120000 doc/install-guide-debconf/source/environment-ntp-controller.rst create mode 120000 doc/install-guide-debconf/source/environment-ntp-other.rst create mode 120000 doc/install-guide-debconf/source/environment-ntp-verify.rst create mode 120000 doc/install-guide-debconf/source/environment-ntp.rst create mode 120000 doc/install-guide-debconf/source/environment-packages.rst create mode 120000 doc/install-guide-debconf/source/environment-security.rst create mode 120000 doc/install-guide-debconf/source/environment-sql-database.rst create mode 120000 doc/install-guide-debconf/source/environment.rst create mode 120000 doc/install-guide-debconf/source/figures create mode 100644 doc/install-guide-debconf/source/glance-install.rst create mode 120000 doc/install-guide-debconf/source/glance-verify.rst create mode 120000 doc/install-guide-debconf/source/glance.rst create mode 100644 doc/install-guide-debconf/source/heat-install.rst create mode 120000 doc/install-guide-debconf/source/heat-next-steps.rst create mode 120000 doc/install-guide-debconf/source/heat-verify.rst create mode 120000 doc/install-guide-debconf/source/heat.rst create mode 120000 doc/install-guide-debconf/source/horizon-install.rst create mode 120000 doc/install-guide-debconf/source/horizon-next-steps.rst create mode 120000 doc/install-guide-debconf/source/horizon-verify.rst create mode 120000 doc/install-guide-debconf/source/horizon.rst create mode 100644 doc/install-guide-debconf/source/index.rst create mode 100644 doc/install-guide-debconf/source/keystone-install.rst create mode 120000 doc/install-guide-debconf/source/keystone-openrc.rst create mode 120000 doc/install-guide-debconf/source/keystone-services.rst create mode 120000 doc/install-guide-debconf/source/keystone-users.rst create mode 120000 doc/install-guide-debconf/source/keystone-verify.rst create mode 120000 doc/install-guide-debconf/source/keystone.rst create mode 120000 doc/install-guide-debconf/source/launch-instance-cinder.rst create mode 120000 doc/install-guide-debconf/source/launch-instance-heat.rst create mode 120000 doc/install-guide-debconf/source/launch-instance-manila-dhss-false-option1.rst create mode 120000 doc/install-guide-debconf/source/launch-instance-manila-dhss-true-option2.rst create mode 120000 doc/install-guide-debconf/source/launch-instance-manila.rst create mode 120000 doc/install-guide-debconf/source/launch-instance-networks-provider.rst create mode 120000 doc/install-guide-debconf/source/launch-instance-networks-selfservice.rst create mode 120000 doc/install-guide-debconf/source/launch-instance-provider.rst create mode 120000 doc/install-guide-debconf/source/launch-instance-selfservice.rst create mode 120000 doc/install-guide-debconf/source/launch-instance.rst create mode 100644 doc/install-guide-debconf/source/manila-controller-install.rst create mode 120000 doc/install-guide-debconf/source/manila-next-steps.rst create mode 120000 doc/install-guide-debconf/source/manila-share-install-dhss-false-option1.rst create mode 120000 doc/install-guide-debconf/source/manila-share-install-dhss-true-option2.rst create mode 120000 doc/install-guide-debconf/source/manila-share-install.rst create mode 120000 doc/install-guide-debconf/source/manila-verify.rst create mode 120000 doc/install-guide-debconf/source/manila.rst create mode 120000 doc/install-guide-debconf/source/neutron-compute-install-option1.rst create mode 120000 doc/install-guide-debconf/source/neutron-compute-install-option2.rst create mode 120000 doc/install-guide-debconf/source/neutron-compute-install.rst create mode 120000 doc/install-guide-debconf/source/neutron-concepts.rst create mode 100644 doc/install-guide-debconf/source/neutron-controller-install-option1.rst create mode 100644 doc/install-guide-debconf/source/neutron-controller-install-option2.rst create mode 100644 doc/install-guide-debconf/source/neutron-controller-install.rst create mode 120000 doc/install-guide-debconf/source/neutron-next-steps.rst create mode 120000 doc/install-guide-debconf/source/neutron-verify-option1.rst create mode 120000 doc/install-guide-debconf/source/neutron-verify-option2.rst create mode 120000 doc/install-guide-debconf/source/neutron-verify.rst create mode 120000 doc/install-guide-debconf/source/neutron.rst create mode 100644 doc/install-guide-debconf/source/nova-compute-install.rst create mode 100644 doc/install-guide-debconf/source/nova-controller-install.rst create mode 120000 doc/install-guide-debconf/source/nova-verify.rst create mode 120000 doc/install-guide-debconf/source/nova.rst create mode 120000 doc/install-guide-debconf/source/overview.rst create mode 120000 doc/install-guide-debconf/source/shared create mode 120000 doc/install-guide-debconf/source/swift-controller-include.txt create mode 120000 doc/install-guide-debconf/source/swift-controller-install.rst create mode 120000 doc/install-guide-debconf/source/swift-finalize-installation.rst create mode 120000 doc/install-guide-debconf/source/swift-initial-rings.rst create mode 120000 doc/install-guide-debconf/source/swift-next-steps.rst create mode 120000 doc/install-guide-debconf/source/swift-storage-include1.txt create mode 120000 doc/install-guide-debconf/source/swift-storage-include2.txt create mode 120000 doc/install-guide-debconf/source/swift-storage-include3.txt create mode 120000 doc/install-guide-debconf/source/swift-storage-install.rst create mode 120000 doc/install-guide-debconf/source/swift-verify.rst create mode 120000 doc/install-guide-debconf/source/swift.rst create mode 100644 doc/install-guide-debconf/source/trove-install.rst create mode 120000 doc/install-guide-debconf/source/trove-next-steps.rst create mode 120000 doc/install-guide-debconf/source/trove-verify.rst create mode 120000 doc/install-guide-debconf/source/trove.rst diff --git a/.gitignore b/.gitignore index 824275e299..d982ef8e21 100644 --- a/.gitignore +++ b/.gitignore @@ -10,6 +10,7 @@ target/ /doc/install-guide/build-obs/ /doc/install-guide/build-ubuntu/ /doc/install-guide/build-debian/ +/doc/install-guide-debconf/build-debian/ .doctrees build/ /build-*.log.gz diff --git a/doc/install-guide-debconf/setup.cfg b/doc/install-guide-debconf/setup.cfg new file mode 100644 index 0000000000..236e72ba82 --- /dev/null +++ b/doc/install-guide-debconf/setup.cfg @@ -0,0 +1,30 @@ +[metadata] +name = openstackinstallguide +summary = OpenStack Installation Guides +author = OpenStack +author-email = openstack-docs@lists.openstack.org +home-page = http://docs.openstack.org/ +classifier = +Environment :: OpenStack +Intended Audience :: Information Technology +Intended Audience :: System Administrators +License :: OSI Approved :: Apache Software License +Operating System :: POSIX :: Linux +Topic :: Documentation + +[global] +setup-hooks = + pbr.hooks.setup_hook + +[files] + +[build_sphinx] +all_files = 1 +build-dir = build +source-dir = source + +[wheel] +universal = 1 + +[pbr] +warnerrors = True diff --git a/doc/install-guide-debconf/setup.py b/doc/install-guide-debconf/setup.py new file mode 100644 index 0000000000..736375744d --- /dev/null +++ b/doc/install-guide-debconf/setup.py @@ -0,0 +1,30 @@ +#!/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. + +# THIS FILE IS MANAGED BY THE GLOBAL REQUIREMENTS REPO - DO NOT EDIT +import setuptools + +# In python < 2.7.4, a lazy loading of package `pbr` will break +# setuptools if some other modules registered functions in `atexit`. +# solution from: http://bugs.python.org/issue15881#msg170215 +try: + import multiprocessing # noqa +except ImportError: + pass + +setuptools.setup( + setup_requires=['pbr'], + pbr=True) diff --git a/doc/install-guide-debconf/source/ceilometer-aodh.rst b/doc/install-guide-debconf/source/ceilometer-aodh.rst new file mode 120000 index 0000000000..04f655dca8 --- /dev/null +++ b/doc/install-guide-debconf/source/ceilometer-aodh.rst @@ -0,0 +1 @@ +../../install-guide/source/ceilometer-aodh.rst \ No newline at end of file diff --git a/doc/install-guide-debconf/source/ceilometer-cinder.rst b/doc/install-guide-debconf/source/ceilometer-cinder.rst new file mode 120000 index 0000000000..528aafc786 --- /dev/null +++ b/doc/install-guide-debconf/source/ceilometer-cinder.rst @@ -0,0 +1 @@ +../../install-guide/source/ceilometer-cinder.rst \ No newline at end of file diff --git a/doc/install-guide-debconf/source/ceilometer-glance.rst b/doc/install-guide-debconf/source/ceilometer-glance.rst new file mode 120000 index 0000000000..26984cd7b8 --- /dev/null +++ b/doc/install-guide-debconf/source/ceilometer-glance.rst @@ -0,0 +1 @@ +../../install-guide/source/ceilometer-glance.rst \ No newline at end of file diff --git a/doc/install-guide-debconf/source/ceilometer-install.rst b/doc/install-guide-debconf/source/ceilometer-install.rst new file mode 100644 index 0000000000..186d4c9d0c --- /dev/null +++ b/doc/install-guide-debconf/source/ceilometer-install.rst @@ -0,0 +1,210 @@ +Install and configure +~~~~~~~~~~~~~~~~~~~~~ + +This section describes how to install and configure the Telemetry +service, code-named ceilometer, on the controller node. The Telemetry +service collects measurements from most OpenStack services and +optionally triggers alarms. + +Prerequisites +------------- + +Before you install and configure the Telemetry service, you must +create a database, service credentials, and API endpoints. However, +unlike other services, the Telemetry service uses a NoSQL database. +See :ref:`environment-nosql-database` to install and configure +MongoDB before proceeding further. + +#. Create the ``ceilometer`` database: + + .. code-block:: console + + # mongo --host controller --eval ' + db = db.getSiblingDB("ceilometer"); + db.createUser({user: "ceilometer", + pwd: "CEILOMETER_DBPASS", + roles: [ "readWrite", "dbAdmin" ]})' + + MongoDB shell version: 2.4.x + connecting to: controller:27017/test + { + "user" : "ceilometer", + "pwd" : "72f25aeee7ad4be52437d7cd3fc60f6f", + "roles" : [ + "readWrite", + "dbAdmin" + ], + "_id" : ObjectId("5489c22270d7fad1ba631dc3") + } + + Replace ``CEILOMETER_DBPASS`` with a suitable password. + + .. note:: + + If the command fails saying you are not authorized to insert a user, + you may need to temporarily comment out the ``auth`` option in + the ``/etc/mongodb.conf`` file, restart the MongoDB service using + ``systemctl restart mongodb``, and try calling the command again. + +#. Source the ``admin`` credentials to gain access to admin-only + CLI commands: + + .. code-block:: console + + $ . admin-openrc + +#. To create the service credentials, complete these steps: + + * Create the ``ceilometer`` user: + + .. code-block:: console + + $ openstack user create --domain default --password-prompt ceilometer + User Password: + Repeat User Password: + +-----------+----------------------------------+ + | Field | Value | + +-----------+----------------------------------+ + | domain_id | e0353a670a9e496da891347c589539e9 | + | enabled | True | + | id | c859c96f57bd4989a8ea1a0b1d8ff7cd | + | name | ceilometer | + +-----------+----------------------------------+ + + * Add the ``admin`` role to the ``ceilometer`` user. + + .. code-block:: console + + $ openstack role add --project service --user ceilometer admin + + .. note:: + + This command provides no output. + + * Create the ``ceilometer`` service entity: + + .. code-block:: console + + $ openstack service create --name ceilometer \ + --description "Telemetry" metering + +-------------+----------------------------------+ + | Field | Value | + +-------------+----------------------------------+ + | description | Telemetry | + | enabled | True | + | id | 5fb7fd1bb2954fddb378d4031c28c0e4 | + | name | ceilometer | + | type | metering | + +-------------+----------------------------------+ + +#. Create the Telemetry service API endpoints: + + .. code-block:: console + + $ openstack endpoint create --region RegionOne \ + metering public http://controller:8777 + +--------------+----------------------------------+ + | Field | Value | + +--------------+----------------------------------+ + | enabled | True | + | id | b808b67b848d443e9eaaa5e5d796970c | + | interface | public | + | region | RegionOne | + | region_id | RegionOne | + | service_id | 5fb7fd1bb2954fddb378d4031c28c0e4 | + | service_name | ceilometer | + | service_type | metering | + | url | http://controller:8777 | + +--------------+----------------------------------+ + + $ openstack endpoint create --region RegionOne \ + metering internal http://controller:8777 + +--------------+----------------------------------+ + | Field | Value | + +--------------+----------------------------------+ + | enabled | True | + | id | c7009b1c2ee54b71b771fa3d0ae4f948 | + | interface | internal | + | region | RegionOne | + | region_id | RegionOne | + | service_id | 5fb7fd1bb2954fddb378d4031c28c0e4 | + | service_name | ceilometer | + | service_type | metering | + | url | http://controller:8777 | + +--------------+----------------------------------+ + + $ openstack endpoint create --region RegionOne \ + metering admin http://controller:8777 + +--------------+----------------------------------+ + | Field | Value | + +--------------+----------------------------------+ + | enabled | True | + | id | b2c00566d0604551b5fe1540c699db3d | + | interface | admin | + | region | RegionOne | + | region_id | RegionOne | + | service_id | 5fb7fd1bb2954fddb378d4031c28c0e4 | + | service_name | ceilometer | + | service_type | metering | + | url | http://controller:8777 | + +--------------+----------------------------------+ + +Install and configure components +-------------------------------- + +#. Install the packages: + + .. code-block:: console + + # apt-get install ceilometer-api ceilometer-collector \ + ceilometer-agent-central ceilometer-agent-notification + python-ceilometerclient + + Respond to prompts for + :doc:`Identity service credentials `, + :doc:`service endpoint registration `, + and :doc:`message broker credentials `. + +#. Edit the ``/etc/ceilometer/ceilometer.conf`` file and complete + the following actions: + + * In the ``[database]`` section, configure database access: + + .. code-block:: ini + + [database] + ... + connection = mongodb://ceilometer:CEILOMETER_DBPASS@controller:27017/ceilometer + + Replace ``CEILOMETER_DBPASS`` with the password you chose for the + Telemetry service database. You must escape special characters such + as ':', '/', '+', and '@' in the connection string in accordance + with `RFC2396 `_. + + * In the ``[service_credentials]`` section, configure service credentials: + + .. code-block:: ini + + [service_credentials] + ... + os_auth_url = http://controller:5000/v2.0 + os_username = ceilometer + os_tenant_name = service + os_password = CEILOMETER_PASS + interface = internalURL + region_name = RegionOne + + Replace ``CEILOMETER_PASS`` with the password you chose for + the ``ceilometer`` user in the Identity service. + +Finalize installation +--------------------- + +#. Restart the Telemetry services: + + .. code-block:: console + + # service ceilometer-agent-central restart + # service ceilometer-agent-notification restart + # service ceilometer-api restart + # service ceilometer-collector restart diff --git a/doc/install-guide-debconf/source/ceilometer-next-steps.rst b/doc/install-guide-debconf/source/ceilometer-next-steps.rst new file mode 120000 index 0000000000..f99c68234d --- /dev/null +++ b/doc/install-guide-debconf/source/ceilometer-next-steps.rst @@ -0,0 +1 @@ +../../install-guide/source/ceilometer-next-steps.rst \ No newline at end of file diff --git a/doc/install-guide-debconf/source/ceilometer-nova.rst b/doc/install-guide-debconf/source/ceilometer-nova.rst new file mode 120000 index 0000000000..3b5940bd77 --- /dev/null +++ b/doc/install-guide-debconf/source/ceilometer-nova.rst @@ -0,0 +1 @@ +../../install-guide/source/ceilometer-nova.rst \ No newline at end of file diff --git a/doc/install-guide-debconf/source/ceilometer-swift.rst b/doc/install-guide-debconf/source/ceilometer-swift.rst new file mode 120000 index 0000000000..516156699d --- /dev/null +++ b/doc/install-guide-debconf/source/ceilometer-swift.rst @@ -0,0 +1 @@ +../../install-guide/source/ceilometer-swift.rst \ No newline at end of file diff --git a/doc/install-guide-debconf/source/ceilometer-verify.rst b/doc/install-guide-debconf/source/ceilometer-verify.rst new file mode 120000 index 0000000000..2d7b809613 --- /dev/null +++ b/doc/install-guide-debconf/source/ceilometer-verify.rst @@ -0,0 +1 @@ +../../install-guide/source/ceilometer-verify.rst \ No newline at end of file diff --git a/doc/install-guide-debconf/source/ceilometer.rst b/doc/install-guide-debconf/source/ceilometer.rst new file mode 120000 index 0000000000..73211daa52 --- /dev/null +++ b/doc/install-guide-debconf/source/ceilometer.rst @@ -0,0 +1 @@ +../../install-guide/source/ceilometer.rst \ No newline at end of file diff --git a/doc/install-guide-debconf/source/cinder-controller-install.rst b/doc/install-guide-debconf/source/cinder-controller-install.rst new file mode 100644 index 0000000000..2120406131 --- /dev/null +++ b/doc/install-guide-debconf/source/cinder-controller-install.rst @@ -0,0 +1,63 @@ +.. _cinder-controller: + +Install and configure controller node +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This section describes how to install and configure the Block +Storage service, code-named cinder, on the controller node. This +service requires at least one additional storage node that provides +volumes to instances. + +Install and configure components +-------------------------------- + +#. Install the packages: + + .. code-block:: console + + # apt-get install cinder-api cinder-scheduler + + Respond to prompts for + :doc:`database management `, + :doc:`Identity service credentials `, + :doc:`service endpoint registration `, + and :doc:`message broker credentials `. + +#. Edit the ``/etc/cinder/cinder.conf`` file and complete the + following actions: + + * In the ``[DEFAULT]`` section, configure the ``my_ip`` option to + use the management interface IP address of the controller node: + + .. code-block:: ini + + [DEFAULT] + ... + my_ip = 10.0.0.11 + +Configure Compute to use Block Storage +-------------------------------------- + +* Edit the ``/etc/nova/nova.conf`` file and add the following + to it: + + .. code-block:: ini + + [cinder] + os_region_name = RegionOne + +Finalize installation +--------------------- + +#. Restart the Compute API service: + + .. code-block:: console + + # service nova-api restart + +#. Restart the Block Storage services: + + .. code-block:: console + + # service cinder-scheduler restart + # service cinder-api restart diff --git a/doc/install-guide-debconf/source/cinder-next-steps.rst b/doc/install-guide-debconf/source/cinder-next-steps.rst new file mode 120000 index 0000000000..fa99d5734f --- /dev/null +++ b/doc/install-guide-debconf/source/cinder-next-steps.rst @@ -0,0 +1 @@ +../../install-guide/source/cinder-next-steps.rst \ No newline at end of file diff --git a/doc/install-guide-debconf/source/cinder-storage-install.rst b/doc/install-guide-debconf/source/cinder-storage-install.rst new file mode 120000 index 0000000000..5d2e8dd5df --- /dev/null +++ b/doc/install-guide-debconf/source/cinder-storage-install.rst @@ -0,0 +1 @@ +../../install-guide/source/cinder-storage-install.rst \ No newline at end of file diff --git a/doc/install-guide-debconf/source/cinder-verify.rst b/doc/install-guide-debconf/source/cinder-verify.rst new file mode 120000 index 0000000000..e858727605 --- /dev/null +++ b/doc/install-guide-debconf/source/cinder-verify.rst @@ -0,0 +1 @@ +../../install-guide/source/cinder-verify.rst \ No newline at end of file diff --git a/doc/install-guide-debconf/source/cinder.rst b/doc/install-guide-debconf/source/cinder.rst new file mode 120000 index 0000000000..f39f7af9d3 --- /dev/null +++ b/doc/install-guide-debconf/source/cinder.rst @@ -0,0 +1 @@ +../../install-guide/source/cinder.rst \ No newline at end of file diff --git a/doc/install-guide-debconf/source/common b/doc/install-guide-debconf/source/common new file mode 120000 index 0000000000..dc879abe93 --- /dev/null +++ b/doc/install-guide-debconf/source/common @@ -0,0 +1 @@ +../../common \ No newline at end of file diff --git a/doc/install-guide-debconf/source/conf.py b/doc/install-guide-debconf/source/conf.py new file mode 100644 index 0000000000..8e9acd9783 --- /dev/null +++ b/doc/install-guide-debconf/source/conf.py @@ -0,0 +1,308 @@ +# 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. + +# This file is execfile()d with the current directory set to its +# containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +import os +# import sys + + +import openstackdocstheme + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# sys.path.insert(0, os.path.abspath('.')) + +# -- 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. +# TODO(ajaeger): enable PDF building, for example add 'rst2pdf.pdfbuilder' +# extensions = + +# Add any paths that contain templates here, relative to this directory. +# templates_path = ['_templates'] + +# The suffix of source filenames. +source_suffix = '.rst' + +# The encoding of source files. +# source_encoding = 'utf-8-sig' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'Installation Guide' +bug_tag = u'install-guide' +copyright = u'2015-2016, OpenStack contributors' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = '0.1' +# The full version, including alpha/beta/rc tags. +release = '0.1' + +# A few variables have to be set for the log-a-bug feature. +# giturl: The location of conf.py on Git. Must be set manually. +# gitsha: The SHA checksum of the bug description. Automatically extracted from git log. +# bug_tag: Tag for categorizing the bug. Must be set manually. +# These variables are passed to the logabug code via html_context. +giturl = u'http://git.openstack.org/cgit/openstack/openstack-manuals/tree/doc/install-guide-debconf/source' +git_cmd = "/usr/bin/git log | head -n1 | cut -f2 -d' '" +gitsha = os.popen(git_cmd).read().strip('\n') +html_context = {"gitsha": gitsha, "bug_tag": bug_tag, + "giturl": giturl} + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# language = None + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +# today = '' +# Else, today_fmt is used as the format for a strftime call. +# today_fmt = '%B %d, %Y' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = ['common/cli*', 'common/nova*', + 'common/get_started_with_openstack.rst', + 'common/get_started_openstack_services.rst', + 'common/get_started_feedback.rst', + 'common/get_started_logical_architecture.rst', + 'common/get_started_dashboard.rst', + 'common/get_started_storage_concepts.rst', + 'common/get_started_data_processing.rst', + 'common/dashboard_customizing.rst', + 'shared/note_configuration_vary_by_distribution.rst'] + +# The reST default role (used for this markup: `text`) to use for all +# documents. +# default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +# add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +# add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +# show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# A list of ignored prefixes for module index sorting. +# modindex_common_prefix = [] + +# If true, keep warnings as "system message" paragraphs in the built documents. +# keep_warnings = False + + +# -- 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 = {} + +# Add any paths that contain custom themes here, relative to this directory. +html_theme_path = [openstackdocstheme.get_html_theme_path()] + +# The name for this set of Sphinx documents. If None, it defaults to +# " v documentation". +# html_title = None + +# A shorter title for the navigation bar. Default is the same as html_title. +# html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +# html_logo = None + +# The name of an image file (within the static path) to use as favicon of the +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +# html_favicon = None + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +# html_static_path = [] + +# Add any extra paths that contain custom files (such as robots.txt or +# .htaccess) here, relative to this directory. These files are copied +# directly to the root of the documentation. +# html_extra_path = [] + +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, +# using the given strftime format. +# So that we can enable "log-a-bug" links from each output HTML page, this +# variable must be set to a format that includes year, month, day, hours and +# minutes. +html_last_updated_fmt = '%Y-%m-%d %H:%M' + + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +# html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +# html_sidebars = {} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +# html_additional_pages = {} + +# If false, no module index is generated. +# html_domain_indices = True + +# If false, no index is generated. +html_use_index = False + +# If true, the index is split into individual pages for each letter. +# html_split_index = False + +# If true, links to the reST sources are added to the pages. +html_show_sourcelink = False + +# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. +# html_show_sphinx = True + +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. +# html_show_copyright = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +# html_use_opensearch = '' + +# This is the file name suffix for HTML files (e.g. ".xhtml"). +# html_file_suffix = None + +# Output file base name for HTML help builder. +htmlhelp_basename = 'install-guide' + +# If true, publish source files +html_copy_source = False + +# -- 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': '', +} + +# 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 = [ + ('index', 'InstallGuide.tex', u'Install Guide', + u'OpenStack contributors', 'manual'), +] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +# latex_logo = None + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +# latex_use_parts = False + +# If true, show page references after internal links. +# latex_show_pagerefs = False + +# If true, show URL addresses after external links. +# latex_show_urls = False + +# Documents to append as an appendix to all manuals. +# latex_appendices = [] + +# If false, no module index is generated. +# latex_domain_indices = True + + +# -- Options for manual page output --------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + ('index', 'installguide', u'Install Guide', + [u'OpenStack contributors'], 1) +] + +# If true, show URL addresses after external links. +# man_show_urls = False + + +# -- 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 = [ + ('index', 'InstallGuide', u'Install Guide', + u'OpenStack contributors', 'InstallGuide', + 'This guide shows OpenStack end users how to install ' + 'an OpenStack cloud.', 'Miscellaneous'), +] + +# Documents to append as an appendix to all manuals. +# texinfo_appendices = [] + +# If false, no module index is generated. +# texinfo_domain_indices = True + +# How to display URL addresses: 'footnote', 'no', or 'inline'. +# texinfo_show_urls = 'footnote' + +# If true, do not generate a @detailmenu in the "Top" node's menu. +# texinfo_no_detailmenu = False + +# -- Options for Internationalization output ------------------------------ +locale_dirs = ['locale/'] + +# -- Options for PDF output -------------------------------------------------- + +pdf_documents = [ + ('index', u'InstallGuide', u'Install Guide', + u'OpenStack contributors') +] diff --git a/doc/install-guide-debconf/source/debconf/debconf-api-endpoints.rst b/doc/install-guide-debconf/source/debconf/debconf-api-endpoints.rst new file mode 100644 index 0000000000..9ffc1b8f45 --- /dev/null +++ b/doc/install-guide-debconf/source/debconf/debconf-api-endpoints.rst @@ -0,0 +1,101 @@ +:orphan: + +====================== +Register API endpoints +====================== + +All Debian packages for API services, except the ``heat-api`` package, +register the service in the Identity service catalog. This feature is +helpful because API endpoints are difficult to remember. + +.. note:: + + The ``heat-common`` package and not the ``heat-api`` package configures the + Orchestration service. + +When you install a package for an API service, you are prompted to +register that service. However, after you install or upgrade the package +for an API service, Debian immediately removes your response to this +prompt from the debconf database. Consequently, you are prompted to +re-register the service with the Identity service. If you already +registered the API service, respond ``no`` when you upgrade. + +.. image:: ../figures/debconf-screenshots/api-endpoint_1_register_endpoint.png + +| + +This screen registers packages in the Identity service catalog: + +.. image:: ../figures/debconf-screenshots/api-endpoint_2_keystone_server_ip.png + +| + +You are prompted for the Identity service ``admin_token`` value. The +Identity service uses this value to register the API service. When you +set up the ``keystone`` package, this value is configured automatically. + +.. image:: ../figures/debconf-screenshots/api-endpoint_3_keystone_authtoken.png + +| + +This screen configures the IP addresses for the service. The +configuration script automatically detects the IP address used by the +interface that is connected to the default route (``/sbin/route`` and +``/sbin/ip``). + +Unless you have a unique set up for your network, press **ENTER**. + +.. image:: ../figures/debconf-screenshots/api-endpoint_4_service_endpoint_ip_address.png + +| + +This screen configures the region name for the service. For example, +``us-east-coast`` or ``europe-paris``. + +.. image:: ../figures/debconf-screenshots/api-endpoint_5_region_name.png + +| + +The Debian package post installation scripts will then perform the below +commands for you: + +.. code-block:: console + + # openstack --os-token ${AUTH_TOKEN} \ + --os-url=http://${KEYSTONE_ENDPOINT_IP}:35357/v3/ \ + --os-domain-name default \ + --os-identity-api-version=3 \ + service create \ + --name=${SERVICE_NAME} \ + --description="${SERVICE_DESC}" \ + ${SERVICE_TYPE} + + # openstack --os-token ${AUTH_TOKEN} \ + --os-url=http://${KEYSTONE_ENDPOINT_IP}:35357/v3/ \ + --os-domain-name default \ + --os-identity-api-version=3 \ + endpoint create \ + --region "${REGION_NAME}" \ + ${SERVICE_NAME} public http://${PKG_ENDPOINT_IP}:${SERVICE_PORT}${SERVICE_URL} + + # openstack --os-token ${AUTH_TOKEN} \ + --os-url=http://${KEYSTONE_ENDPOINT_IP}:35357/v3/ \ + --os-domain-name default \ + --os-identity-api-version=3 \ + endpoint create \ + --region "${REGION_NAME}" \ + ${SERVICE_NAME} internal http://${PKG_ENDPOINT_IP}:${SERVICE_PORT}${SERVICE_URL} + + # openstack --os-token ${AUTH_TOKEN} \ + --os-url=http://${KEYSTONE_ENDPOINT_IP}:35357/v3/ \ + --os-domain-name default \ + --os-identity-api-version=3 \ + endpoint create \ + --region "${REGION_NAME}" \ + ${SERVICE_NAME} admin http://${PKG_ENDPOINT_IP}:${SERVICE_PORT}${SERVICE_URL} + +The values of ``AUTH_TOKEN``, ``KEYSTONE_ENDPOINT_IP``, +``PKG_ENDPOINT_IP``, and ``REGION_NAME`` depend on the answer you will +provide to the debconf prompts. But the values of ``SERVICE_NAME``, +``SERVICE_TYPE``, ``SERVICE_DESC``, and ``SERVICE_URL`` are already +pre-wired in each package, so you don't have to remember them. diff --git a/doc/install-guide-debconf/source/debconf/debconf-concepts.rst b/doc/install-guide-debconf/source/debconf/debconf-concepts.rst new file mode 100644 index 0000000000..872480cb17 --- /dev/null +++ b/doc/install-guide-debconf/source/debconf/debconf-concepts.rst @@ -0,0 +1,120 @@ +:orphan: + +================ +debconf concepts +================ + +This chapter explains how to use the Debian ``debconf`` and +``dbconfig-common`` packages to configure OpenStack services. These +packages enable users to perform configuration tasks. When users +install OpenStack packages, ``debconf`` prompts the user for responses, +which seed the contents of configuration files associated with that package. +After package installation, users can update the configuration of a +package by using the :command:`dpkg-reconfigure` program. + +If you are familiar with these packages and pre-seeding, you can proceed +to :doc:`../keystone`. + + +The Debian packages +------------------- + +The rules described here are from the `Debian Policy +Manual `__. If any rule +described in this chapter is not respected, you have found a serious bug +that must be fixed. + +When you install or upgrade a Debian package, all configuration file +values are preserved. Using the ``debconf`` database as a registry is +considered a bug in Debian. If you edit something in any OpenStack +configuration file, the ``debconf`` package reads that value when it +prepares to prompt the user. For example, to change the log in name for +the RabbitMQ messaging queue for a service, you can edit its value in +the corresponding configuration file. + +To opt out of using the ``debconf`` package, run the +:command:`dpkg-reconfigure` command and select non-interactive mode: + +.. code-block:: console + + # dpkg-reconfigure -plow debconf + +Then, ``debconf`` does not prompt you. + +Another way to disable the ``debconf`` package is to prefix the +:command:`apt` command with ``DEBIAN_FRONTEND=noninteractive``, +as follows: + +.. code-block:: console + + # DEBIAN_FRONTEND=noninteractive apt-get install nova-api + +If you configure a package with ``debconf`` incorrectly, you can +re-configure it, as follows: + +.. code-block:: console + + # dpkg-reconfigure PACKAGE-NAME + + +This calls the post-installation script for the ``PACKAGE-NAME`` package +after the user responds to all prompts. If you cannot install a Debian +package in a non-interactive way, you have found a release-critical bug +in Debian. Report it to the Debian bug tracking system. + +Generally, the ``-common`` packages install the configuration files. For +example, the ``glance-common`` package installs the ``glance-api.conf`` +and ``glance-registry.conf`` files. So, for the Image service, you must +re-configure the ``glance-common`` package. The same applies for +``cinder-common``, ``nova-common``, and ``heat-common`` packages. + +In ``debconf``, the higher the priority for a screen, the greater the +chance that the user sees that screen. If a ``debconf`` screen has +``medium`` priority and you configure the Debian system to show only +``critical`` prompts, which is the default in Debian, the user does not +see that ``debconf`` screen. Instead, the default for the related package +is used. In the Debian OpenStack packages, a number of ``debconf`` screens +are set with ``medium`` priority. Consequently, if you want to respond to +all ``debconf`` screens from the Debian OpenStack packages, you must run +the following command and select the ``medium`` priority before you install +any packages: + +.. code-block:: console + + # dpkg-reconfigure debconf + +.. note:: + + The packages do not require pre-depends. If ``dbconfig-common`` is + already installed on the system, the user sees all prompts. However, + you cannot define the order in which the ``debconf`` screens appear. + The user must make sense of it even if the prompts appear in an + illogical order. + +| + +Pre-seed debconf prompts +------------------------ + +You can pre-seed all ``debconf`` prompts. To pre-seed means to store +responses in the ``debconf`` database so that ``debconf`` does not prompt +the user for responses. Pre-seeding enables a hands-free installation for +users. The package maintainer creates scripts that automatically +configure the services. + +The following example shows how to pre-seed an automated MySQL Server +installation: + +.. code-block:: bash + + MYSQL_PASSWORD=MYSQL_PASSWORD + echo "mysql-server-5.5 mysql-server/root_password password ${MYSQL_PASSWORD} + mysql-server-5.5 mysql-server/root_password seen true + mysql-server-5.5 mysql-server/root_password_again password ${MYSQL_PASSWORD} + mysql-server-5.5 mysql-server/root_password_again seen true + " | debconf-set-selections + DEBIAN_FRONTEND=noninteractive apt-get install -y --force-yes mysql-server + +The ``seen true`` option tells ``debconf`` that a specified screen was +already seen by the user so do not show it again. This option is useful +for upgrades. diff --git a/doc/install-guide-debconf/source/debconf/debconf-dbconfig-common.rst b/doc/install-guide-debconf/source/debconf/debconf-dbconfig-common.rst new file mode 100644 index 0000000000..e1ef2082e9 --- /dev/null +++ b/doc/install-guide-debconf/source/debconf/debconf-dbconfig-common.rst @@ -0,0 +1,167 @@ +:orphan: + +=========================================== +Configure the database with dbconfig-common +=========================================== + +Many of the OpenStack services need to be configured to access a +database. These are configured through a DSN (Database Source Name) +directive as follows: + +.. code-block:: ini + + [database] + connection = mysql+pymysql://keystone:0dec658e3f14a7d@localhost/keystonedb + +This ``connection`` directive will be handled by the ``dbconfig-common`` +package, which provides a standard Debian interface. It enables you to +configure Debian database parameters. It includes localized prompts for +many languages and it supports the following database backends: SQLite, +MySQL, and PostgreSQL. + +By default, the ``dbconfig-common`` package configures the OpenStack +services to use SQLite. So if you use debconf in non-interactive mode +and without pre-seeding, the OpenStack services that you install will +use SQLite. + +By default, ``dbconfig-common`` does not provide access to database servers +over a network. If you want the ``dbconfig-common`` package to prompt for +remote database servers that are accessed over a network and not through +a UNIX socket file, reconfigure it, as follows: + +.. code-block:: console + + # apt-get install dbconfig-common && dpkg-reconfigure dbconfig-common + +These screens appear when you re-configure the ``dbconfig-common`` package: + +.. image:: ../figures/debconf-screenshots/dbconfig-common_keep_admin_pass.png + +| + +.. image:: ../figures/debconf-screenshots/dbconfig-common_used_for_remote_db.png + +| + +Unlike other debconf prompts, you cannot pre-seed the responses for the +``dbconfig-common`` prompts by using ``debconf-set-selections``. Instead, +you must create a file in :file:`/etc/dbconfig-common`. For example, you +might create a keystone configuration file for ``dbconfig-common`` that is +located in :file:`/etc/dbconfig-common/keystone.conf`, as follows: + +.. code-block:: ini + + dbc_install='true' + dbc_upgrade='true' + dbc_remove='' + dbc_dbtype='mysql' + dbc_dbuser='keystone' + dbc_dbpass='PASSWORD' + dbc_dbserver='' + dbc_dbport='' + dbc_dbname='keystonedb' + dbc_dbadmin='root' + dbc_basepath='' + dbc_ssl='' + dbc_authmethod_admin='' + dbc_authmethod_user='' + +After you create this file, run this command: + +.. code-block:: console + + # apt-get install keystone + +The Identity service is installed with MySQL as the database back end, +``keystonedb`` as database name, and the localhost socket file. The +corresponding DSN (Database Source Name) will then be: + +.. code-block:: ini + + [database] + connection = mysql+pymysql://keystone:PASSWORD@localhost/keystonedb + +The ``dbconfig-common`` package will configure MySQL for these access +rights, and create the database for you. Since OpenStack 2014.1.1, all +OpenStack packages in Debian are performing the following MySQL query +after database creation (if you decide to use MySQL as a back-end): + +.. code-block:: ini + + ALTER DATABASE keystone CHARACTER SET utf8 COLLATE utf8_unicode_ci + +So, if using Debian, you wont need to care about database creation, +access rights and character sets. All that is handled for you by the +packages. + +As an example, here are screenshots from the ``cinder-common`` package: + +.. image:: ../figures/debconf-screenshots/dbconfig-common_1_configure-with-dbconfig-yes-no.png + +| + +.. image:: ../figures/debconf-screenshots/dbconfig-common_2_db-types.png + +| + +.. image:: ../figures/debconf-screenshots/dbconfig-common_3_connection_method.png + +| + +.. image:: ../figures/debconf-screenshots/dbconfig-common_4_mysql_root_password.png + +| + +.. image:: ../figures/debconf-screenshots/dbconfig-common_5_mysql_app_password.png + +| + +.. image:: ../figures/debconf-screenshots/dbconfig-common_6_mysql_app_password_confirm.png + +| + +By default in Debian, you can access the MySQL server from either +localhost through the socket file or 127.0.0.1. To access it over the +network, you must edit the :file:`/etc/mysql/my.cnf` file, and the +``mysql.user`` table. To do so, Debian provides a helper script in the +``openstack-deploy`` package. To use it, install the package: + +.. code-block:: console + + # apt-get install openstack-deploy + +and run the helper script: + +.. code-block:: console + + # /usr/share/openstack-deploy/mysql-remote-root + +Alternatively, if you do not want to install this package, run this +script to enable remote root access: + +.. code-block:: bash + + #!/bin/sh + + set -e + + SQL="mysql --defaults-file=/etc/mysql/debian.cnf -Dmysql -e" + + ROOT_PASS=`${SQL} "SELECT Password FROM user WHERE User='root' LIMIT 1;" \ + | tail -n 1` + ${SQL} "REPLACE INTO user SET host='%', user='root',\ + password='${ROOT_PASS}', Select_priv='Y', Insert_priv='Y',\ + Update_priv='Y', Delete_priv='Y', Create_priv='Y', Drop_priv='Y',\ + Reload_priv='Y', Shutdown_priv='Y', Process_priv='Y', File_priv='Y',\ + Grant_priv='Y', References_priv='Y', Index_priv='Y', Alter_priv='Y',\ + Super_priv='Y', Show_db_priv='Y', Create_tmp_table_priv='Y',\ + Lock_tables_priv='Y', Execute_priv='Y', Repl_slave_priv='Y',\ + Repl_client_priv='Y', Create_view_priv='Y', Show_view_priv='Y',\ + Create_routine_priv='Y', Alter_routine_priv='Y', Create_user_priv='Y',\ + Event_priv='Y', Trigger_priv='Y' " + ${SQL} "FLUSH PRIVILEGES" + sed -i 's|^bind-address[ \t]*=.*|bind-address = 0.0.0.0|' /etc/mysql/my.cnf + /etc/init.d/mysql restart + +You must enable remote access before you install OpenStack services on +multiple nodes. diff --git a/doc/install-guide-debconf/source/debconf/debconf-keystone-authtoken.rst b/doc/install-guide-debconf/source/debconf/debconf-keystone-authtoken.rst new file mode 100644 index 0000000000..de35171dd1 --- /dev/null +++ b/doc/install-guide-debconf/source/debconf/debconf-keystone-authtoken.rst @@ -0,0 +1,56 @@ +:orphan: + +====================================== +Services and the [keystone_authtoken] +====================================== + +Because most OpenStack services must access the Identity service, you +must configure the IP address of the ``keystone`` server to be able to +access it. You must also configure the ``admin_tenant_name``, +``admin_user``, and ``admin_password`` options for each service to work. + +Generally, this section looks like this: + +.. code-block:: ini + + [keystone_authtoken] + auth_uri = http://controller:5000/v2.0 + identity_uri = http://controller:35357 + admin_tenant_name = %SERVICE_TENANT_NAME% + admin_user = %SERVICE_USER% + admin_password = %SERVICE_PASSWORD% + +The debconf system helps users configure the ``auth_uri``, +``identity_uri``, ``admin_tenant_name``, ``admin_user``, and +``admin_password`` options. + +The following screens show an example Image service configuration: + +.. image:: ../figures/debconf-screenshots/service_keystone_authtoken_server_hostname.png + +| + +.. image:: ../figures/debconf-screenshots/service_keystone_authtoken_admin_tenant_name.png + +| + +.. image:: ../figures/debconf-screenshots/service_keystone_authtoken_tenant_admin_user.png + +| + +.. image:: ../figures/debconf-screenshots/service_keystone_authtoken_admin_password.png + +This information is stored in the configuration file for each service. +For example: + +.. code-block:: ini + + /etc/ceilometer/ceilometer.conf + /etc/nova/api-paste.ini + /etc/glance/glance-api-paste.ini + /etc/glance/glance-registry.ini + /etc/cinder/cinder.conf + /etc/neutron/neutron.conf + +The Debian OpenStack packages offer automation for this, so OpenStack +users do not have to manually edit the configuration files. diff --git a/doc/install-guide-debconf/source/debconf/debconf-rabbitmq.rst b/doc/install-guide-debconf/source/debconf/debconf-rabbitmq.rst new file mode 100644 index 0000000000..ebfab8a2ff --- /dev/null +++ b/doc/install-guide-debconf/source/debconf/debconf-rabbitmq.rst @@ -0,0 +1,36 @@ +:orphan: + +=============================== +RabbitMQ credentials parameters +=============================== + +For every package that must connect to a Messaging Server, the Debian +package enables you to configure the IP address for that server and the +user name and password that is used to connect. The following example +shows configuration with the ``ceilometer-common`` package: + +.. image:: ../figures/debconf-screenshots/rabbitmq-host.png + +| + +.. image:: ../figures/debconf-screenshots/rabbitmq-user.png + +| + +.. image:: ../figures/debconf-screenshots/rabbitmq-password.png + +| + +These debconf screens appear in: ``ceilometer-common``, ``cinder-common``, +``glance-common``, ``heat-common``, ``neutron-common``, and ``nova-common``. + +This will configure the below directives (example from ``nova.conf``): + +.. code-block:: ini + + [DEFAULT] + rabbit_host=localhost + rabbit_userid=guest + rabbit_password=guest + +The other directives concerning RabbitMQ will stay untouched. diff --git a/doc/install-guide-debconf/source/debconf/debconf.rst b/doc/install-guide-debconf/source/debconf/debconf.rst new file mode 100644 index 0000000000..53a39836e1 --- /dev/null +++ b/doc/install-guide-debconf/source/debconf/debconf.rst @@ -0,0 +1,14 @@ +:orphan: + +================================ +Configure OpenStack with debconf +================================ + +.. toctree:: + :maxdepth: 2 + + debconf-concepts.rst + debconf-dbconfig-common.rst + debconf-rabbitmq.rst + debconf-keystone-authtoken.rst + debconf-api-endpoints.rst diff --git a/doc/install-guide-debconf/source/environment-memcached.rst b/doc/install-guide-debconf/source/environment-memcached.rst new file mode 120000 index 0000000000..53d85c678e --- /dev/null +++ b/doc/install-guide-debconf/source/environment-memcached.rst @@ -0,0 +1 @@ +../../install-guide/source/environment-memcached.rst \ No newline at end of file diff --git a/doc/install-guide-debconf/source/environment-messaging.rst b/doc/install-guide-debconf/source/environment-messaging.rst new file mode 120000 index 0000000000..258eca8b4f --- /dev/null +++ b/doc/install-guide-debconf/source/environment-messaging.rst @@ -0,0 +1 @@ +../../install-guide/source/environment-messaging.rst \ No newline at end of file diff --git a/doc/install-guide-debconf/source/environment-networking-compute.rst b/doc/install-guide-debconf/source/environment-networking-compute.rst new file mode 120000 index 0000000000..5b65160e12 --- /dev/null +++ b/doc/install-guide-debconf/source/environment-networking-compute.rst @@ -0,0 +1 @@ +../../install-guide/source/environment-networking-compute.rst \ No newline at end of file diff --git a/doc/install-guide-debconf/source/environment-networking-controller.rst b/doc/install-guide-debconf/source/environment-networking-controller.rst new file mode 120000 index 0000000000..2555b2de99 --- /dev/null +++ b/doc/install-guide-debconf/source/environment-networking-controller.rst @@ -0,0 +1 @@ +../../install-guide/source/environment-networking-controller.rst \ No newline at end of file diff --git a/doc/install-guide-debconf/source/environment-networking-storage-cinder.rst b/doc/install-guide-debconf/source/environment-networking-storage-cinder.rst new file mode 120000 index 0000000000..3dc714f31e --- /dev/null +++ b/doc/install-guide-debconf/source/environment-networking-storage-cinder.rst @@ -0,0 +1 @@ +../../install-guide/source/environment-networking-storage-cinder.rst \ No newline at end of file diff --git a/doc/install-guide-debconf/source/environment-networking-storage-swift.rst b/doc/install-guide-debconf/source/environment-networking-storage-swift.rst new file mode 120000 index 0000000000..d354385842 --- /dev/null +++ b/doc/install-guide-debconf/source/environment-networking-storage-swift.rst @@ -0,0 +1 @@ +../../install-guide/source/environment-networking-storage-swift.rst \ No newline at end of file diff --git a/doc/install-guide-debconf/source/environment-networking-verify.rst b/doc/install-guide-debconf/source/environment-networking-verify.rst new file mode 120000 index 0000000000..5c39be0c7f --- /dev/null +++ b/doc/install-guide-debconf/source/environment-networking-verify.rst @@ -0,0 +1 @@ +../../install-guide/source/environment-networking-verify.rst \ No newline at end of file diff --git a/doc/install-guide-debconf/source/environment-networking.rst b/doc/install-guide-debconf/source/environment-networking.rst new file mode 120000 index 0000000000..83c89ff138 --- /dev/null +++ b/doc/install-guide-debconf/source/environment-networking.rst @@ -0,0 +1 @@ +../../install-guide/source/environment-networking.rst \ No newline at end of file diff --git a/doc/install-guide-debconf/source/environment-nosql-database.rst b/doc/install-guide-debconf/source/environment-nosql-database.rst new file mode 120000 index 0000000000..21128a0629 --- /dev/null +++ b/doc/install-guide-debconf/source/environment-nosql-database.rst @@ -0,0 +1 @@ +../../install-guide/source/environment-nosql-database.rst \ No newline at end of file diff --git a/doc/install-guide-debconf/source/environment-ntp-controller.rst b/doc/install-guide-debconf/source/environment-ntp-controller.rst new file mode 120000 index 0000000000..d8a15b9dd8 --- /dev/null +++ b/doc/install-guide-debconf/source/environment-ntp-controller.rst @@ -0,0 +1 @@ +../../install-guide/source/environment-ntp-controller.rst \ No newline at end of file diff --git a/doc/install-guide-debconf/source/environment-ntp-other.rst b/doc/install-guide-debconf/source/environment-ntp-other.rst new file mode 120000 index 0000000000..4e90147d0d --- /dev/null +++ b/doc/install-guide-debconf/source/environment-ntp-other.rst @@ -0,0 +1 @@ +../../install-guide/source/environment-ntp-other.rst \ No newline at end of file diff --git a/doc/install-guide-debconf/source/environment-ntp-verify.rst b/doc/install-guide-debconf/source/environment-ntp-verify.rst new file mode 120000 index 0000000000..02e9b0e6be --- /dev/null +++ b/doc/install-guide-debconf/source/environment-ntp-verify.rst @@ -0,0 +1 @@ +../../install-guide/source/environment-ntp-verify.rst \ No newline at end of file diff --git a/doc/install-guide-debconf/source/environment-ntp.rst b/doc/install-guide-debconf/source/environment-ntp.rst new file mode 120000 index 0000000000..b90619322a --- /dev/null +++ b/doc/install-guide-debconf/source/environment-ntp.rst @@ -0,0 +1 @@ +../../install-guide/source/environment-ntp.rst \ No newline at end of file diff --git a/doc/install-guide-debconf/source/environment-packages.rst b/doc/install-guide-debconf/source/environment-packages.rst new file mode 120000 index 0000000000..5714afcd28 --- /dev/null +++ b/doc/install-guide-debconf/source/environment-packages.rst @@ -0,0 +1 @@ +../../install-guide/source/environment-packages.rst \ No newline at end of file diff --git a/doc/install-guide-debconf/source/environment-security.rst b/doc/install-guide-debconf/source/environment-security.rst new file mode 120000 index 0000000000..11a0dfc5c1 --- /dev/null +++ b/doc/install-guide-debconf/source/environment-security.rst @@ -0,0 +1 @@ +../../install-guide/source/environment-security.rst \ No newline at end of file diff --git a/doc/install-guide-debconf/source/environment-sql-database.rst b/doc/install-guide-debconf/source/environment-sql-database.rst new file mode 120000 index 0000000000..9971ba9e44 --- /dev/null +++ b/doc/install-guide-debconf/source/environment-sql-database.rst @@ -0,0 +1 @@ +../../install-guide/source/environment-sql-database.rst \ No newline at end of file diff --git a/doc/install-guide-debconf/source/environment.rst b/doc/install-guide-debconf/source/environment.rst new file mode 120000 index 0000000000..f2a183f4ad --- /dev/null +++ b/doc/install-guide-debconf/source/environment.rst @@ -0,0 +1 @@ +../../install-guide/source/environment.rst \ No newline at end of file diff --git a/doc/install-guide-debconf/source/figures b/doc/install-guide-debconf/source/figures new file mode 120000 index 0000000000..62fee757b8 --- /dev/null +++ b/doc/install-guide-debconf/source/figures @@ -0,0 +1 @@ +../../install-guide/source/figures \ No newline at end of file diff --git a/doc/install-guide-debconf/source/glance-install.rst b/doc/install-guide-debconf/source/glance-install.rst new file mode 100644 index 0000000000..440ad78f57 --- /dev/null +++ b/doc/install-guide-debconf/source/glance-install.rst @@ -0,0 +1,27 @@ +Install and configure +~~~~~~~~~~~~~~~~~~~~~ + +This section describes how to install and configure the Image service, +code-named glance, on the controller node. For simplicity, this +configuration stores images on the local file system. + +Install and configure components +-------------------------------- + +#. Install the packages: + + .. code-block:: console + + # apt-get install glance python-glanceclient + +#. Respond to prompts for + :doc:`database management `, + :doc:`Identity service credentials `, + :doc:`service endpoint registration `, + and :doc:`message broker credentials `. + +#. Select the ``keystone`` pipeline to configure the Image service + to use the Identity service: + + .. image:: figures/debconf-screenshots/glance-common_pipeline_flavor.png + :width: 100% diff --git a/doc/install-guide-debconf/source/glance-verify.rst b/doc/install-guide-debconf/source/glance-verify.rst new file mode 120000 index 0000000000..967ad760a9 --- /dev/null +++ b/doc/install-guide-debconf/source/glance-verify.rst @@ -0,0 +1 @@ +../../install-guide/source/glance-verify.rst \ No newline at end of file diff --git a/doc/install-guide-debconf/source/glance.rst b/doc/install-guide-debconf/source/glance.rst new file mode 120000 index 0000000000..8b83363a13 --- /dev/null +++ b/doc/install-guide-debconf/source/glance.rst @@ -0,0 +1 @@ +../../install-guide/source/glance.rst \ No newline at end of file diff --git a/doc/install-guide-debconf/source/heat-install.rst b/doc/install-guide-debconf/source/heat-install.rst new file mode 100644 index 0000000000..2fa91b74ac --- /dev/null +++ b/doc/install-guide-debconf/source/heat-install.rst @@ -0,0 +1,44 @@ +.. _heat-install: + +Install and configure +~~~~~~~~~~~~~~~~~~~~~ + +This section describes how to install and configure the +Orchestration service, code-named heat, on the controller node. + +Install and configure components +-------------------------------- + +#. Run the following commands to install the packages: + + .. code-block:: console + + # apt-get install heat-api heat-api-cfn heat-engine python-heat-client + +#. Respond to prompts for + :doc:`database management `, + :doc:`Identity service credentials `, + :doc:`service endpoint registration `, + and :doc:`message broker credentials `. + +#. Edit the ``/etc/heat/heat.conf`` file and complete the following + actions: + + * In the ``[ec2authtoken]`` section, configure Identity service access: + + .. code-block:: ini + + [ec2authtoken] + ... + auth_uri = http://controller:5000/v2.0 + +Finalize installation +--------------------- + +#. Restart the Orchestration services: + + .. code-block:: console + + # service heat-api restart + # service heat-api-cfn restart + # service heat-engine restart diff --git a/doc/install-guide-debconf/source/heat-next-steps.rst b/doc/install-guide-debconf/source/heat-next-steps.rst new file mode 120000 index 0000000000..0732cb06f4 --- /dev/null +++ b/doc/install-guide-debconf/source/heat-next-steps.rst @@ -0,0 +1 @@ +../../install-guide/source/heat-next-steps.rst \ No newline at end of file diff --git a/doc/install-guide-debconf/source/heat-verify.rst b/doc/install-guide-debconf/source/heat-verify.rst new file mode 120000 index 0000000000..4c534c41cf --- /dev/null +++ b/doc/install-guide-debconf/source/heat-verify.rst @@ -0,0 +1 @@ +../../install-guide/source/heat-verify.rst \ No newline at end of file diff --git a/doc/install-guide-debconf/source/heat.rst b/doc/install-guide-debconf/source/heat.rst new file mode 120000 index 0000000000..de70c6856c --- /dev/null +++ b/doc/install-guide-debconf/source/heat.rst @@ -0,0 +1 @@ +../../install-guide/source/heat.rst \ No newline at end of file diff --git a/doc/install-guide-debconf/source/horizon-install.rst b/doc/install-guide-debconf/source/horizon-install.rst new file mode 120000 index 0000000000..b1214ff71e --- /dev/null +++ b/doc/install-guide-debconf/source/horizon-install.rst @@ -0,0 +1 @@ +../../install-guide/source/horizon-install.rst \ No newline at end of file diff --git a/doc/install-guide-debconf/source/horizon-next-steps.rst b/doc/install-guide-debconf/source/horizon-next-steps.rst new file mode 120000 index 0000000000..3dfdf0aa0c --- /dev/null +++ b/doc/install-guide-debconf/source/horizon-next-steps.rst @@ -0,0 +1 @@ +../../install-guide/source/horizon-next-steps.rst \ No newline at end of file diff --git a/doc/install-guide-debconf/source/horizon-verify.rst b/doc/install-guide-debconf/source/horizon-verify.rst new file mode 120000 index 0000000000..4e3cef3279 --- /dev/null +++ b/doc/install-guide-debconf/source/horizon-verify.rst @@ -0,0 +1 @@ +../../install-guide/source/horizon-verify.rst \ No newline at end of file diff --git a/doc/install-guide-debconf/source/horizon.rst b/doc/install-guide-debconf/source/horizon.rst new file mode 120000 index 0000000000..51a81e290f --- /dev/null +++ b/doc/install-guide-debconf/source/horizon.rst @@ -0,0 +1 @@ +../../install-guide/source/horizon.rst \ No newline at end of file diff --git a/doc/install-guide-debconf/source/index.rst b/doc/install-guide-debconf/source/index.rst new file mode 100644 index 0000000000..aeebc4a5e9 --- /dev/null +++ b/doc/install-guide-debconf/source/index.rst @@ -0,0 +1,75 @@ +.. title:: OpenStack Installation Guide + +======================================= +OpenStack Installation Guide for Debian +======================================= + +Abstract +~~~~~~~~ + +The OpenStack system consists of several key services that are separately +installed. These services work together depending on your cloud +needs. These services include Compute service, Identity service, +Networking service, Image service, Block Storage service, Object Storage +service, Telemetry service, Orchestration service, and Database service. You +can install any of these projects separately and configure them stand-alone +or as connected entities. + +This guide walks through an installation by using packages +available through Debian 8 (code name: Jessie). + +Explanations of configuration options and sample configuration files +are included. + +This guide documents OpenStack Newton release. + +.. warning:: + + This guide is a work-in-progress and is subject to updates frequently. + Pre-release packages have been used for testing, and some instructions + may not work with final versions. Please help us make this guide better + by reporting any errors you encounter. + +Contents +~~~~~~~~ + +.. toctree:: + :maxdepth: 2 + + common/conventions.rst + overview.rst + environment.rst + debconf/debconf.rst + keystone.rst + glance.rst + nova.rst + neutron.rst + horizon.rst + cinder.rst + manila.rst + swift.rst + heat.rst + ceilometer.rst + trove.rst + launch-instance.rst + +Appendix +~~~~~~~~ + +.. toctree:: + :maxdepth: 1 + + common/app_support.rst + +Glossary +~~~~~~~~ + +.. toctree:: + :maxdepth: 1 + + common/glossary.rst + +Search in this guide +~~~~~~~~~~~~~~~~~~~~ + +* :ref:`search` diff --git a/doc/install-guide-debconf/source/keystone-install.rst b/doc/install-guide-debconf/source/keystone-install.rst new file mode 100644 index 0000000000..45b4fe105e --- /dev/null +++ b/doc/install-guide-debconf/source/keystone-install.rst @@ -0,0 +1,160 @@ +.. _keystone-install: + +Install and configure +~~~~~~~~~~~~~~~~~~~~~ + +This section describes how to install and configure the OpenStack +Identity service, code-named keystone, on the controller node. For +performance, this configuration deploys Fernet tokens and the Apache +HTTP server to handle requests. + +Install and configure the components +------------------------------------ + +#. Run the following command to install the packages: + + .. code-block:: console + + # apt-get install keystone + +#. Respond to prompts for :doc:`debconf/debconf-dbconfig-common`, + which will fill the below database access directive. + + .. code-block:: ini + + [database] + ... + connection = mysql+pymysql://keystone:KEYSTONE_DBPASS@controller/keystone + + If you decide to not use ``dbconfig-common``, then you have to + create the database and manage its access rights yourself, and run the + following by hand. + + .. code-block:: console + + # keystone-manage db_sync + +#. Generate a random value to use as the administration token during + initial configuration: + + .. code-block:: console + + $ openssl rand -hex 10 + +#. Configure the initial administration token: + + .. image:: figures/debconf-screenshots/keystone_1_admin_token.png + :scale: 50 + + Use the random value that you generated in a previous step. If you + install using non-interactive mode or you do not specify this token, the + configuration tool generates a random value. + + Later on, the package will configure the below directive with the value + you entered: + + .. code-block:: ini + + [DEFAULT] + ... + admin_token = ADMIN_TOKEN + +#. Create the ``admin`` project and user: + + During the final stage of the package installation, it is possible to + automatically create an ``admin`` and ``service`` project, and an ``admin`` + user. This can later be used for other OpenStack services to contact the + Identity service. This is the equivalent of running the below commands: + + .. code-block:: console + + # openstack --os-token ${AUTH_TOKEN} \ + --os-url=http://127.0.0.1:35357/v3/ \ + --os-domain-name default \ + --os-identity-api-version=3 \ + project create --or-show \ + admin --domain default \ + --description "Default Debian admin project" + + # openstack --os-token ${AUTH_TOKEN} \ + --os-url=http://127.0.0.1:35357/v3/ \ + --os-domain-name default \ + --os-identity-api-version=3 \ + project create --or-show \ + service --domain default \ + --description "Default Debian admin project" + + # openstack --os-token ${AUTH_TOKEN} \ + --os-url=http://127.0.0.1:35357/v3/ \ + --os-domain-name default \ + --os-identity-api-version=3 \ + user create --or-show \ + --password ADMIN_PASS \ + --project admin \ + --email root@localhost \ + --enable \ + admin \ + --domain default \ + --description "Default Debian admin user" + + # openstack --os-token ${AUTH_TOKEN} \ + --os-url=http://127.0.0.1:35357/v3/ \ + --os-domain-name default \ + --os-identity-api-version=3 \ + role create --or-show admin + + # openstack --os-token ${AUTH_TOKEN} \ + --os-url=http://127.0.0.1:35357/v3/ \ + --os-domain-name default \ + --os-identity-api-version=3 \ + role add --project admin --user admin admin + + .. image:: figures/debconf-screenshots/keystone_2_register_admin_tenant_yes_no.png + :scale: 50 + + .. image:: figures/debconf-screenshots/keystone_3_admin_user_name.png + :scale: 50 + + .. image:: figures/debconf-screenshots/keystone_4_admin_user_email.png + :scale: 50 + + .. image:: figures/debconf-screenshots/keystone_5_admin_user_pass.png + :scale: 50 + + .. image:: figures/debconf-screenshots/keystone_6_admin_user_pass_confirm.png + :scale: 50 + + In Debian, the Keystone package offers automatic registration of + Keystone in the service catalogue. This is equivalent of running the + below commands: + + .. code-block:: console + + # openstack --os-token ${AUTH_TOKEN} \ + --os-url=http://127.0.0.1:35357/v3/ \ + --os-domain-name default \ + --os-identity-api-version=3 \ + service create \ + --name keystone \ + --description "OpenStack Identity" \ + identity + + # openstack --os-token ${AUTH_TOKEN} \ + --os-url=http://127.0.0.1:35357/v3/ \ + --os-domain-name default \ + --os-identity-api-version=3 \ + keystone public http://controller:5000/v2.0 + + # openstack --os-token ${AUTH_TOKEN} \ + --os-url=http://127.0.0.1:35357/v3/ \ + --os-domain-name default \ + --os-identity-api-version=3 \ + keystone internal http://controller:5000/v2.0 + + # openstack --os-token ${AUTH_TOKEN} \ + --os-url=http://127.0.0.1:35357/v3/ \ + --os-domain-name default \ + --os-identity-api-version=3 \ + keystone admin http://controller:35357/v2.0 + + .. image:: figures/debconf-screenshots/keystone_7_register_endpoint.png diff --git a/doc/install-guide-debconf/source/keystone-openrc.rst b/doc/install-guide-debconf/source/keystone-openrc.rst new file mode 120000 index 0000000000..0cf99072f7 --- /dev/null +++ b/doc/install-guide-debconf/source/keystone-openrc.rst @@ -0,0 +1 @@ +../../install-guide/source/keystone-openrc.rst \ No newline at end of file diff --git a/doc/install-guide-debconf/source/keystone-services.rst b/doc/install-guide-debconf/source/keystone-services.rst new file mode 120000 index 0000000000..8f8328e05e --- /dev/null +++ b/doc/install-guide-debconf/source/keystone-services.rst @@ -0,0 +1 @@ +../../install-guide/source/keystone-services.rst \ No newline at end of file diff --git a/doc/install-guide-debconf/source/keystone-users.rst b/doc/install-guide-debconf/source/keystone-users.rst new file mode 120000 index 0000000000..cd465d9619 --- /dev/null +++ b/doc/install-guide-debconf/source/keystone-users.rst @@ -0,0 +1 @@ +../../install-guide/source/keystone-users.rst \ No newline at end of file diff --git a/doc/install-guide-debconf/source/keystone-verify.rst b/doc/install-guide-debconf/source/keystone-verify.rst new file mode 120000 index 0000000000..3db2b9c9e4 --- /dev/null +++ b/doc/install-guide-debconf/source/keystone-verify.rst @@ -0,0 +1 @@ +../../install-guide/source/keystone-verify.rst \ No newline at end of file diff --git a/doc/install-guide-debconf/source/keystone.rst b/doc/install-guide-debconf/source/keystone.rst new file mode 120000 index 0000000000..0519edf8b4 --- /dev/null +++ b/doc/install-guide-debconf/source/keystone.rst @@ -0,0 +1 @@ +../../install-guide/source/keystone.rst \ No newline at end of file diff --git a/doc/install-guide-debconf/source/launch-instance-cinder.rst b/doc/install-guide-debconf/source/launch-instance-cinder.rst new file mode 120000 index 0000000000..9721e8bc09 --- /dev/null +++ b/doc/install-guide-debconf/source/launch-instance-cinder.rst @@ -0,0 +1 @@ +../../install-guide/source/launch-instance-cinder.rst \ No newline at end of file diff --git a/doc/install-guide-debconf/source/launch-instance-heat.rst b/doc/install-guide-debconf/source/launch-instance-heat.rst new file mode 120000 index 0000000000..0379434a3a --- /dev/null +++ b/doc/install-guide-debconf/source/launch-instance-heat.rst @@ -0,0 +1 @@ +../../install-guide/source/launch-instance-heat.rst \ No newline at end of file diff --git a/doc/install-guide-debconf/source/launch-instance-manila-dhss-false-option1.rst b/doc/install-guide-debconf/source/launch-instance-manila-dhss-false-option1.rst new file mode 120000 index 0000000000..3589d45aaf --- /dev/null +++ b/doc/install-guide-debconf/source/launch-instance-manila-dhss-false-option1.rst @@ -0,0 +1 @@ +../../install-guide/source/launch-instance-manila-dhss-false-option1.rst \ No newline at end of file diff --git a/doc/install-guide-debconf/source/launch-instance-manila-dhss-true-option2.rst b/doc/install-guide-debconf/source/launch-instance-manila-dhss-true-option2.rst new file mode 120000 index 0000000000..978d54aaf2 --- /dev/null +++ b/doc/install-guide-debconf/source/launch-instance-manila-dhss-true-option2.rst @@ -0,0 +1 @@ +../../install-guide/source/launch-instance-manila-dhss-true-option2.rst \ No newline at end of file diff --git a/doc/install-guide-debconf/source/launch-instance-manila.rst b/doc/install-guide-debconf/source/launch-instance-manila.rst new file mode 120000 index 0000000000..415e2df2ea --- /dev/null +++ b/doc/install-guide-debconf/source/launch-instance-manila.rst @@ -0,0 +1 @@ +../../install-guide/source/launch-instance-manila.rst \ No newline at end of file diff --git a/doc/install-guide-debconf/source/launch-instance-networks-provider.rst b/doc/install-guide-debconf/source/launch-instance-networks-provider.rst new file mode 120000 index 0000000000..c911bf6dfc --- /dev/null +++ b/doc/install-guide-debconf/source/launch-instance-networks-provider.rst @@ -0,0 +1 @@ +../../install-guide/source/launch-instance-networks-provider.rst \ No newline at end of file diff --git a/doc/install-guide-debconf/source/launch-instance-networks-selfservice.rst b/doc/install-guide-debconf/source/launch-instance-networks-selfservice.rst new file mode 120000 index 0000000000..4c1f718580 --- /dev/null +++ b/doc/install-guide-debconf/source/launch-instance-networks-selfservice.rst @@ -0,0 +1 @@ +../../install-guide/source/launch-instance-networks-selfservice.rst \ No newline at end of file diff --git a/doc/install-guide-debconf/source/launch-instance-provider.rst b/doc/install-guide-debconf/source/launch-instance-provider.rst new file mode 120000 index 0000000000..7db86e4818 --- /dev/null +++ b/doc/install-guide-debconf/source/launch-instance-provider.rst @@ -0,0 +1 @@ +../../install-guide/source/launch-instance-provider.rst \ No newline at end of file diff --git a/doc/install-guide-debconf/source/launch-instance-selfservice.rst b/doc/install-guide-debconf/source/launch-instance-selfservice.rst new file mode 120000 index 0000000000..834329835e --- /dev/null +++ b/doc/install-guide-debconf/source/launch-instance-selfservice.rst @@ -0,0 +1 @@ +../../install-guide/source/launch-instance-selfservice.rst \ No newline at end of file diff --git a/doc/install-guide-debconf/source/launch-instance.rst b/doc/install-guide-debconf/source/launch-instance.rst new file mode 120000 index 0000000000..ffb53dbcbf --- /dev/null +++ b/doc/install-guide-debconf/source/launch-instance.rst @@ -0,0 +1 @@ +../../install-guide/source/launch-instance.rst \ No newline at end of file diff --git a/doc/install-guide-debconf/source/manila-controller-install.rst b/doc/install-guide-debconf/source/manila-controller-install.rst new file mode 100644 index 0000000000..8a7db79542 --- /dev/null +++ b/doc/install-guide-debconf/source/manila-controller-install.rst @@ -0,0 +1,243 @@ +.. _manila-controller: + +Install and configure controller node +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This section describes how to install and configure the Shared File Systems +service, code-named manila, on the controller node. This service requires at +least one additional share node that manages file storage drivers. + +Prerequisites +------------- + +Before you install and configure the Share File System 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 ``manila`` database: + + .. code-block:: console + + CREATE DATABASE manila; + + * Grant proper access to the ``manila`` database: + + .. code-block:: console + + GRANT ALL PRIVILEGES ON manila.* TO 'manila'@'localhost' \ + IDENTIFIED BY 'MANILA_DBPASS'; + GRANT ALL PRIVILEGES ON manila.* TO 'manila'@'%' \ + IDENTIFIED BY 'MANILA_DBPASS'; + + Replace ``MANILA_DBPASS`` with a suitable password. + + * Exit the database access client. + +#. Source the ``admin`` credentials to gain access to admin-only CLI commands: + + .. code-block:: console + + $ . admin-openrc + +#. To create the service credentials, complete these steps: + + * Create a ``manila`` user: + + .. code-block:: console + + $ openstack user create --domain default --password-prompt manila + User Password: + Repeat User Password: + +-----------+----------------------------------+ + | Field | Value | + +-----------+----------------------------------+ + | domain_id | e0353a670a9e496da891347c589539e9 | + | enabled | True | + | id | 83a3990fc2144100ba0e2e23886d8acc | + | name | manila | + +-----------+----------------------------------+ + + * Add the ``admin`` role to the ``manila`` user: + + .. code-block:: console + + $ openstack role add --project service --user manila admin + + .. note:: + + This command provides no output. + + * Create the ``manila`` and ``manilav2`` service entities: + + .. code-block:: console + + $ openstack service create --name manila \ + --description "OpenStack Shared File Systems" share + +-------------+----------------------------------+ + | Field | Value | + +-------------+----------------------------------+ + | description | OpenStack Shared File Systems | + | enabled | True | + | id | 82378b5a16b340aa9cc790cdd46a03ba | + | name | manila | + | type | share | + +-------------+----------------------------------+ + + .. code-block:: console + + $ openstack service create --name manilav2 \ + --description "OpenStack Shared File Systems" sharev2 + +-------------+----------------------------------+ + | Field | Value | + +-------------+----------------------------------+ + | description | OpenStack Shared File Systems | + | enabled | True | + | id | 30d92a97a81a4e5d8fd97a32bafd7b88 | + | name | manilav2 | + | type | sharev2 | + +-------------+----------------------------------+ + + .. note:: + + The Share File System services require two service entities. + +#. Create the Shared File Systems service API endpoints: + + .. code-block:: console + + $ openstack endpoint create --region RegionOne \ + share public http://controller:8786/v1/%\(tenant_id\)s + +--------------+-----------------------------------------+ + | Field | Value | + +--------------+-----------------------------------------+ + | enabled | True | + | id | 0bd2bbf8d28b433aaea56a254c69f69d | + | interface | public | + | region | RegionOne | + | region_id | RegionOne | + | service_id | 82378b5a16b340aa9cc790cdd46a03ba | + | service_name | manila | + | service_type | share | + | url | http://controller:8786/v1/%(tenant_id)s | + +--------------+-----------------------------------------+ + + $ openstack endpoint create --region RegionOne \ + share internal http://controller:8786/v1/%\(tenant_id\)s + +--------------+-----------------------------------------+ + | Field | Value | + +--------------+-----------------------------------------+ + | enabled | True | + | id | a2859b5732cc48b5b083dd36dafb6fd9 | + | interface | internal | + | region | RegionOne | + | region_id | RegionOne | + | service_id | 82378b5a16b340aa9cc790cdd46a03ba | + | service_name | manila | + | service_type | share | + | url | http://controller:8786/v1/%(tenant_id)s | + +--------------+-----------------------------------------+ + + $ openstack endpoint create --region RegionOne \ + share admin http://controller:8786/v1/%\(tenant_id\)s + +--------------+-----------------------------------------+ + | Field | Value | + +--------------+-----------------------------------------+ + | enabled | True | + | id | f7f46df93a374cc49c0121bef41da03c | + | interface | admin | + | region | RegionOne | + | region_id | RegionOne | + | service_id | 82378b5a16b340aa9cc790cdd46a03ba | + | service_name | manila | + | service_type | share | + | url | http://controller:8786/v1/%(tenant_id)s | + +--------------+-----------------------------------------+ + + .. code-block:: console + + $ openstack endpoint create --region RegionOne \ + sharev2 public http://controller:8786/v2/%\(tenant_id\)s + +--------------+-----------------------------------------+ + | Field | Value | + +--------------+-----------------------------------------+ + | enabled | True | + | id | d63cc0d358da4ea680178657291eddc1 | + | interface | public | + | region | RegionOne | + | region_id | RegionOne | + | service_id | 30d92a97a81a4e5d8fd97a32bafd7b88 | + | service_name | manilav2 | + | service_type | sharev2 | + | url | http://controller:8786/v2/%(tenant_id)s | + +--------------+-----------------------------------------+ + + $ openstack endpoint create --region RegionOne \ + sharev2 internal http://controller:8786/v2/%\(tenant_id\)s + +--------------+-----------------------------------------+ + | Field | Value | + +--------------+-----------------------------------------+ + | enabled | True | + | id | afc86e5f50804008add349dba605da54 | + | interface | internal | + | region | RegionOne | + | region_id | RegionOne | + | service_id | 30d92a97a81a4e5d8fd97a32bafd7b88 | + | service_name | manilav2 | + | service_type | sharev2 | + | url | http://controller:8786/v2/%(tenant_id)s | + +--------------+-----------------------------------------+ + + $ openstack endpoint create --region RegionOne \ + sharev2 admin http://controller:8786/v2/%\(tenant_id\)s + +--------------+-----------------------------------------+ + | Field | Value | + +--------------+-----------------------------------------+ + | enabled | True | + | id | e814a0cec40546e98cf0c25a82498483 | + | interface | admin | + | region | RegionOne | + | region_id | RegionOne | + | service_id | 30d92a97a81a4e5d8fd97a32bafd7b88 | + | service_name | manilav2 | + | service_type | sharev2 | + | url | http://controller:8786/v2/%(tenant_id)s | + +--------------+-----------------------------------------+ + + .. note:: + + The Share File System services require endpoints for each service + entity. + +Install and configure components +-------------------------------- + +#. Install the packages: + + .. code-block:: console + + # apt-get install manila-api manila-scheduler \ + python-manilaclient + + Respond to prompts for + :doc:`database management `, + :doc:`Identity service credentials `, + :doc:`service endpoint registration `, + and :doc:`message broker credentials `. + +Finalize installation +--------------------- + +* Restart the Share File Systems services: + + .. code-block:: console + + # service manila-scheduler restart + # service manila-api restart diff --git a/doc/install-guide-debconf/source/manila-next-steps.rst b/doc/install-guide-debconf/source/manila-next-steps.rst new file mode 120000 index 0000000000..1bf8388c27 --- /dev/null +++ b/doc/install-guide-debconf/source/manila-next-steps.rst @@ -0,0 +1 @@ +../../install-guide/source/manila-next-steps.rst \ No newline at end of file diff --git a/doc/install-guide-debconf/source/manila-share-install-dhss-false-option1.rst b/doc/install-guide-debconf/source/manila-share-install-dhss-false-option1.rst new file mode 120000 index 0000000000..119dc46596 --- /dev/null +++ b/doc/install-guide-debconf/source/manila-share-install-dhss-false-option1.rst @@ -0,0 +1 @@ +../../install-guide/source/manila-share-install-dhss-false-option1.rst \ No newline at end of file diff --git a/doc/install-guide-debconf/source/manila-share-install-dhss-true-option2.rst b/doc/install-guide-debconf/source/manila-share-install-dhss-true-option2.rst new file mode 120000 index 0000000000..32c97092c6 --- /dev/null +++ b/doc/install-guide-debconf/source/manila-share-install-dhss-true-option2.rst @@ -0,0 +1 @@ +../../install-guide/source/manila-share-install-dhss-true-option2.rst \ No newline at end of file diff --git a/doc/install-guide-debconf/source/manila-share-install.rst b/doc/install-guide-debconf/source/manila-share-install.rst new file mode 120000 index 0000000000..0bd9c3ae3c --- /dev/null +++ b/doc/install-guide-debconf/source/manila-share-install.rst @@ -0,0 +1 @@ +../../install-guide/source/manila-share-install.rst \ No newline at end of file diff --git a/doc/install-guide-debconf/source/manila-verify.rst b/doc/install-guide-debconf/source/manila-verify.rst new file mode 120000 index 0000000000..89f8a42634 --- /dev/null +++ b/doc/install-guide-debconf/source/manila-verify.rst @@ -0,0 +1 @@ +../../install-guide/source/manila-verify.rst \ No newline at end of file diff --git a/doc/install-guide-debconf/source/manila.rst b/doc/install-guide-debconf/source/manila.rst new file mode 120000 index 0000000000..6d6e023495 --- /dev/null +++ b/doc/install-guide-debconf/source/manila.rst @@ -0,0 +1 @@ +../../install-guide/source/manila.rst \ No newline at end of file diff --git a/doc/install-guide-debconf/source/neutron-compute-install-option1.rst b/doc/install-guide-debconf/source/neutron-compute-install-option1.rst new file mode 120000 index 0000000000..2ce809cd58 --- /dev/null +++ b/doc/install-guide-debconf/source/neutron-compute-install-option1.rst @@ -0,0 +1 @@ +../../install-guide/source/neutron-compute-install-option1.rst \ No newline at end of file diff --git a/doc/install-guide-debconf/source/neutron-compute-install-option2.rst b/doc/install-guide-debconf/source/neutron-compute-install-option2.rst new file mode 120000 index 0000000000..5c7c52825f --- /dev/null +++ b/doc/install-guide-debconf/source/neutron-compute-install-option2.rst @@ -0,0 +1 @@ +../../install-guide/source/neutron-compute-install-option2.rst \ No newline at end of file diff --git a/doc/install-guide-debconf/source/neutron-compute-install.rst b/doc/install-guide-debconf/source/neutron-compute-install.rst new file mode 120000 index 0000000000..ed70d84adb --- /dev/null +++ b/doc/install-guide-debconf/source/neutron-compute-install.rst @@ -0,0 +1 @@ +../../install-guide/source/neutron-compute-install.rst \ No newline at end of file diff --git a/doc/install-guide-debconf/source/neutron-concepts.rst b/doc/install-guide-debconf/source/neutron-concepts.rst new file mode 120000 index 0000000000..4f7dd83496 --- /dev/null +++ b/doc/install-guide-debconf/source/neutron-concepts.rst @@ -0,0 +1 @@ +../../install-guide/source/neutron-concepts.rst \ No newline at end of file diff --git a/doc/install-guide-debconf/source/neutron-controller-install-option1.rst b/doc/install-guide-debconf/source/neutron-controller-install-option1.rst new file mode 100644 index 0000000000..81be7a6ab3 --- /dev/null +++ b/doc/install-guide-debconf/source/neutron-controller-install-option1.rst @@ -0,0 +1,192 @@ +Networking Option 1: Provider networks +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Install and configure the Networking components on the *controller* node. + +Install the components +---------------------- + +.. code-block:: console + + # apt-get install neutron-server neutron-linuxbridge-agent \ + neutron-dhcp-agent neutron-metadata-agent python-neutronclient + +Respond to prompts for `database +management <#debconf-dbconfig-common>`__, `Identity service +credentials <#debconf-keystone_authtoken>`__, `service endpoint +registration <#debconf-api-endpoints>`__, and `message queue +credentials <#debconf-rabbitmq>`__. + +Select the ML2 plug-in: + +.. image:: figures/debconf-screenshots/neutron_1_plugin_selection.png + +.. note:: + + Selecting the ML2 plug-in also populates the ``core_plugin`` option + in the ``/etc/neutron/neutron.conf`` file with the appropriate values + (in this case, it is set to the value ``ml2``). + +Configure the server component +------------------------------ + +#. Edit the ``/etc/neutron/neutron.conf`` file and complete the following + actions: + + * In the ``[DEFAULT]`` section, disable additional plug-ins: + + .. code-block:: ini + + [DEFAULT] + ... + service_plugins = + + * In the ``[DEFAULT]`` and ``[nova]`` sections, configure Networking to + notify Compute of network topology changes: + + .. code-block:: ini + + [DEFAULT] + ... + notify_nova_on_port_status_changes = True + notify_nova_on_port_data_changes = True + + [nova] + ... + auth_url = http://controller:35357 + auth_type = password + project_domain_name = default + user_domain_name = default + region_name = RegionOne + project_name = service + username = nova + password = NOVA_PASS + + Replace ``NOVA_PASS`` with the password you chose for the ``nova`` + user in the Identity service. + +Configure the Modular Layer 2 (ML2) plug-in +------------------------------------------- + +The ML2 plug-in uses the Linux bridge mechanism to build layer-2 (bridging +and switching) virtual networking infrastructure for instances. + +* Edit the ``/etc/neutron/plugins/ml2/ml2_conf.ini`` file and complete the + following actions: + + * In the ``[ml2]`` section, enable flat and VLAN networks: + + .. code-block:: ini + + [ml2] + ... + type_drivers = flat,vlan + + * In the ``[ml2]`` section, disable self-service networks: + + .. code-block:: ini + + [ml2] + ... + tenant_network_types = + + * In the ``[ml2]`` section, enable the Linux bridge mechanism: + + .. code-block:: ini + + [ml2] + ... + mechanism_drivers = linuxbridge + + .. warning:: + + After you configure the ML2 plug-in, removing values in the + ``type_drivers`` option can lead to database inconsistency. + + * In the ``[ml2]`` section, enable the port security extension driver: + + .. code-block:: ini + + [ml2] + ... + extension_drivers = port_security + + * In the ``[ml2_type_flat]`` section, configure the provider virtual + network as a flat network: + + .. code-block:: ini + + [ml2_type_flat] + ... + flat_networks = provider + + * In the ``[securitygroup]`` section, enable :term:`ipset` to increase + efficiency of security group rules: + + .. code-block:: ini + + [securitygroup] + ... + enable_ipset = True + +Configure the Linux bridge agent +-------------------------------- + +The Linux bridge agent builds layer-2 (bridging and switching) virtual +networking infrastructure for instances and handles security groups. + +* Edit the ``/etc/neutron/plugins/ml2/linuxbridge_agent.ini`` file and + complete the following actions: + + * In the ``[linux_bridge]`` section, map the provider virtual network to the + provider physical network interface: + + .. code-block:: ini + + [linux_bridge] + physical_interface_mappings = provider:PROVIDER_INTERFACE_NAME + + Replace ``PROVIDER_INTERFACE_NAME`` with the name of the underlying + provider physical network interface. See :ref:`environment-networking` + for more information. + + * In the ``[vxlan]`` section, disable VXLAN overlay networks: + + .. code-block:: ini + + [vxlan] + enable_vxlan = False + + * In the ``[securitygroup]`` section, enable security groups and + configure the Linux bridge :term:`iptables` firewall driver: + + .. code-block:: ini + + [securitygroup] + ... + enable_security_group = True + firewall_driver = neutron.agent.linux.iptables_firewall.IptablesFirewallDriver + +Configure the DHCP agent +------------------------ + +The :term:`DHCP agent` provides DHCP services for virtual networks. + +* Edit the ``/etc/neutron/dhcp_agent.ini`` file and complete the following + actions: + + * In the ``[DEFAULT]`` section, configure the Linux bridge interface driver, + Dnsmasq DHCP driver, and enable isolated metadata so instances on provider + networks can access metadata over the network: + + .. code-block:: ini + + [DEFAULT] + ... + interface_driver = neutron.agent.linux.interface.BridgeInterfaceDriver + dhcp_driver = neutron.agent.linux.dhcp.Dnsmasq + enable_isolated_metadata = True + +Return to +:ref:`Networking controller node configuration +`. diff --git a/doc/install-guide-debconf/source/neutron-controller-install-option2.rst b/doc/install-guide-debconf/source/neutron-controller-install-option2.rst new file mode 100644 index 0000000000..285e5fd5f4 --- /dev/null +++ b/doc/install-guide-debconf/source/neutron-controller-install-option2.rst @@ -0,0 +1,205 @@ +Networking Option 2: Self-service networks +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Install and configure the Networking components on the *controller* node. + +Install and configure the Networking components +----------------------------------------------- + +#. .. code-block:: console + + # apt-get install neutron-server neutron-plugin-linuxbridge-agent \ + neutron-dhcp-agent neutron-metadata-agent + + For networking option 2, also install the ``neutron-l3-agent`` package. + +#. Respond to prompts for `database + management <#debconf-dbconfig-common>`__, `Identity service + credentials <#debconf-keystone_authtoken>`__, `service endpoint + registration <#debconf-api-endpoints>`__, and `message queue + credentials <#debconf-rabbitmq>`__. + +#. Select the ML2 plug-in: + + .. image:: figures/debconf-screenshots/neutron_1_plugin_selection.png + + .. note:: + + Selecting the ML2 plug-in also populates the ``service_plugins`` and + ``allow_overlapping_ips`` options in the + ``/etc/neutron/neutron.conf`` file with the appropriate values. + +Configure the Modular Layer 2 (ML2) plug-in +------------------------------------------- + +The ML2 plug-in uses the Linux bridge mechanism to build layer-2 (bridging +and switching) virtual networking infrastructure for instances. + +* Edit the ``/etc/neutron/plugins/ml2/ml2_conf.ini`` file and complete the + following actions: + + * In the ``[ml2]`` section, enable flat, VLAN, and VXLAN networks: + + .. code-block:: ini + + [ml2] + ... + type_drivers = flat,vlan,vxlan + + * In the ``[ml2]`` section, enable VXLAN self-service networks: + + .. code-block:: ini + + [ml2] + ... + tenant_network_types = vxlan + + * In the ``[ml2]`` section, enable the Linux bridge and layer-2 population + mechanisms: + + .. code-block:: ini + + [ml2] + ... + mechanism_drivers = linuxbridge,l2population + + .. warning:: + + After you configure the ML2 plug-in, removing values in the + ``type_drivers`` option can lead to database inconsistency. + + .. note:: + + The Linux bridge agent only supports VXLAN overlay networks. + + * In the ``[ml2]`` section, enable the port security extension driver: + + .. code-block:: ini + + [ml2] + ... + extension_drivers = port_security + + * In the ``[ml2_type_flat]`` section, configure the provider virtual + network as a flat network: + + .. code-block:: ini + + [ml2_type_flat] + ... + flat_networks = provider + + * In the ``[ml2_type_vxlan]`` section, configure the VXLAN network identifier + range for self-service networks: + + .. code-block:: ini + + [ml2_type_vxlan] + ... + vni_ranges = 1:1000 + + * In the ``[securitygroup]`` section, enable :term:`ipset` to increase + efficiency of security group rules: + + .. code-block:: ini + + [securitygroup] + ... + enable_ipset = True + +Configure the Linux bridge agent +-------------------------------- + +The Linux bridge agent builds layer-2 (bridging and switching) virtual +networking infrastructure for instances and handles security groups. + +* Edit the ``/etc/neutron/plugins/ml2/linuxbridge_agent.ini`` file and + complete the following actions: + + * In the ``[linux_bridge]`` section, map the provider virtual network to the + provider physical network interface: + + .. code-block:: ini + + [linux_bridge] + physical_interface_mappings = provider:PROVIDER_INTERFACE_NAME + + Replace ``PROVIDER_INTERFACE_NAME`` with the name of the underlying + provider physical network interface. See :ref:`environment-networking` + for more information. + + * In the ``[vxlan]`` section, enable VXLAN overlay networks, configure the + IP address of the physical network interface that handles overlay + networks, and enable layer-2 population: + + .. code-block:: ini + + [vxlan] + enable_vxlan = True + local_ip = OVERLAY_INTERFACE_IP_ADDRESS + l2_population = True + + Replace ``OVERLAY_INTERFACE_IP_ADDRESS`` with the IP address of the + underlying physical network interface that handles overlay networks. The + example architecture uses the management interface to tunnel traffic to + the other nodes. Therefore, replace ``OVERLAY_INTERFACE_IP_ADDRESS`` with + the management IP address of the controller node. See + :ref:`environment-networking` for more information. + + * In the ``[securitygroup]`` section, enable security groups and + configure the Linux bridge :term:`iptables` firewall driver: + + .. code-block:: ini + + [securitygroup] + ... + enable_security_group = True + firewall_driver = neutron.agent.linux.iptables_firewall.IptablesFirewallDriver + +Configure the layer-3 agent +--------------------------- + +The :term:`Layer-3 (L3) agent` provides routing and NAT services for +self-service virtual networks. + +* Edit the ``/etc/neutron/l3_agent.ini`` file and complete the following + actions: + + * In the ``[DEFAULT]`` section, configure the Linux bridge interface driver + and external network bridge: + + .. code-block:: ini + + [DEFAULT] + ... + interface_driver = neutron.agent.linux.interface.BridgeInterfaceDriver + external_network_bridge = + + .. note:: + + The ``external_network_bridge`` option intentionally lacks a value + to enable multiple external networks on a single agent. + +Configure the DHCP agent +------------------------ + +The :term:`DHCP agent` provides DHCP services for virtual networks. + +* Edit the ``/etc/neutron/dhcp_agent.ini`` file and complete the following + actions: + + * In the ``[DEFAULT]`` section, configure the Linux bridge interface driver, + Dnsmasq DHCP driver, and enable isolated metadata so instances on provider + networks can access metadata over the network: + + .. code-block:: ini + + [DEFAULT] + ... + interface_driver = neutron.agent.linux.interface.BridgeInterfaceDriver + dhcp_driver = neutron.agent.linux.dhcp.Dnsmasq + enable_isolated_metadata = True + +Return to +:ref:`Networking controller node configuration +`. diff --git a/doc/install-guide-debconf/source/neutron-controller-install.rst b/doc/install-guide-debconf/source/neutron-controller-install.rst new file mode 100644 index 0000000000..b6bd8d3e68 --- /dev/null +++ b/doc/install-guide-debconf/source/neutron-controller-install.rst @@ -0,0 +1,97 @@ +Install and configure controller node +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Configure networking options +---------------------------- + +You can deploy the Networking service using one of two architectures +represented by options 1 and 2. + +Option 1 deploys the simplest possible architecture that only supports +attaching instances to provider (external) networks. No self-service (private) +networks, routers, or floating IP addresses. Only the ``admin`` or other +privileged user can manage provider networks. + +Option 2 augments option 1 with layer-3 services that support attaching +instances to self-service networks. The ``demo`` or other unprivileged +user can manage self-service networks including routers that provide +connectivity between self-service and provider networks. Additionally, +floating IP addresses provide connectivity to instances using self-service +networks from external networks such as the Internet. + +Self-service networks typically use overlay networks. Overlay network +protocols such as VXLAN include additional headers that increase overhead +and decrease space available for the payload or user data. Without knowledge +of the virtual network infrastructure, instances attempt to send packets +using the default Ethernet :term:`maximum transmission unit (MTU)` of 1500 +bytes. The Networking service automatically provides the correct MTU value +to instances via DHCP. However, some cloud images do not use DHCP or ignore +the DHCP MTU option and require configuration using metadata or a script. + +.. note:: + + Option 2 also supports attaching instances to provider networks. + +Choose one of the following networking options to configure services +specific to it. Afterwards, return here and proceed to +:ref:`neutron-controller-metadata-agent`. + +.. toctree:: + :maxdepth: 1 + + neutron-controller-install-option1.rst + neutron-controller-install-option2.rst + +.. _neutron-controller-metadata-agent: + +Configure the metadata agent +---------------------------- + +The :term:`metadata agent ` provides configuration information +such as credentials to instances. + +* Edit the ``/etc/neutron/metadata_agent.ini`` file and complete the following + actions: + + * In the ``[DEFAULT]`` section, configure the metadata host and shared + secret: + + .. code-block:: ini + + [DEFAULT] + ... + nova_metadata_ip = controller + metadata_proxy_shared_secret = METADATA_SECRET + + Replace ``METADATA_SECRET`` with a suitable secret for the metadata proxy. + +Configure Compute to use Networking +----------------------------------- + +* Edit the ``/etc/nova/nova.conf`` file and perform the following actions: + + * In the ``[neutron]`` section, configure access parameters, enable the + metadata proxy, and configure the secret: + + .. code-block:: ini + + [neutron] + ... + url = http://controller:9696 + auth_url = http://controller:35357 + auth_type = password + project_domain_name = default + user_domain_name = default + region_name = RegionOne + project_name = service + username = neutron + password = NEUTRON_PASS + + service_metadata_proxy = True + metadata_proxy_shared_secret = METADATA_SECRET + + Replace ``NEUTRON_PASS`` with the password you chose for the ``neutron`` + user in the Identity service. + + Replace ``METADATA_SECRET`` with the secret you chose for the metadata + proxy. diff --git a/doc/install-guide-debconf/source/neutron-next-steps.rst b/doc/install-guide-debconf/source/neutron-next-steps.rst new file mode 120000 index 0000000000..10c52bae1e --- /dev/null +++ b/doc/install-guide-debconf/source/neutron-next-steps.rst @@ -0,0 +1 @@ +../../install-guide/source/neutron-next-steps.rst \ No newline at end of file diff --git a/doc/install-guide-debconf/source/neutron-verify-option1.rst b/doc/install-guide-debconf/source/neutron-verify-option1.rst new file mode 120000 index 0000000000..26ac1c833e --- /dev/null +++ b/doc/install-guide-debconf/source/neutron-verify-option1.rst @@ -0,0 +1 @@ +../../install-guide/source/neutron-verify-option1.rst \ No newline at end of file diff --git a/doc/install-guide-debconf/source/neutron-verify-option2.rst b/doc/install-guide-debconf/source/neutron-verify-option2.rst new file mode 120000 index 0000000000..470f6c0753 --- /dev/null +++ b/doc/install-guide-debconf/source/neutron-verify-option2.rst @@ -0,0 +1 @@ +../../install-guide/source/neutron-verify-option2.rst \ No newline at end of file diff --git a/doc/install-guide-debconf/source/neutron-verify.rst b/doc/install-guide-debconf/source/neutron-verify.rst new file mode 120000 index 0000000000..688dd8bd1b --- /dev/null +++ b/doc/install-guide-debconf/source/neutron-verify.rst @@ -0,0 +1 @@ +../../install-guide/source/neutron-verify.rst \ No newline at end of file diff --git a/doc/install-guide-debconf/source/neutron.rst b/doc/install-guide-debconf/source/neutron.rst new file mode 120000 index 0000000000..8041851c6d --- /dev/null +++ b/doc/install-guide-debconf/source/neutron.rst @@ -0,0 +1 @@ +../../install-guide/source/neutron.rst \ No newline at end of file diff --git a/doc/install-guide-debconf/source/nova-compute-install.rst b/doc/install-guide-debconf/source/nova-compute-install.rst new file mode 100644 index 0000000000..475dfcc54f --- /dev/null +++ b/doc/install-guide-debconf/source/nova-compute-install.rst @@ -0,0 +1,148 @@ +Install and configure a compute node +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This section describes how to install and configure the Compute +service on a compute node. The service supports several +:term:`hypervisors ` to deploy :term:`instances ` +or :term:`VMs `. For simplicity, this configuration +uses the :term:`QEMU ` hypervisor with the +:term:`KVM ` extension +on compute nodes that support hardware acceleration for virtual machines. +On legacy hardware, this configuration uses the generic QEMU hypervisor. +You can follow these instructions with minor modifications to horizontally +scale your environment with additional compute nodes. + +.. note:: + + This section assumes that you are following the instructions in + this guide step-by-step to configure the first compute node. If you + want to configure additional compute nodes, prepare them in a similar + fashion to the first compute node in the :ref:`example architectures + ` section. Each additional compute node + requires a unique IP address. + +Install and configure components +-------------------------------- + +.. include:: shared/note_configuration_vary_by_distribution.rst + +#. Install the packages: + + .. code-block:: console + + # apt-get install nova-compute + + Respond to prompts for + :doc:`database management `, + :doc:`Identity service credentials `, + and :doc:`message broker credentials `. Make + sure that you do not activate database management handling by debconf, + as a compute node should not access the central database. + +#. Edit the ``/etc/nova/nova.conf`` file and + complete the following actions: + + * In the ``[DEFAULT]`` section, check that the ``my_ip`` option + is correctly set (this value is handled by the config and postinst + scripts of the ``nova-common`` package using debconf): + + .. code-block:: ini + + [DEFAULT] + ... + my_ip = MANAGEMENT_INTERFACE_IP_ADDRESS + + Replace ``MANAGEMENT_INTERFACE_IP_ADDRESS`` with the IP address + of the management network interface on your compute node, + typically 10.0.0.31 for the first node in the + :ref:`example architecture `. + + * In the ``[DEFAULT]`` section, enable support for the Networking service: + + .. code-block:: ini + + [DEFAULT] + ... + use_neutron = True + firewall_driver = nova.virt.firewall.NoopFirewallDriver + + .. note:: + + By default, Compute uses an internal firewall service. Since + Networking includes a firewall service, you must disable the Compute + firewall service by using the + ``nova.virt.firewall.NoopFirewallDriver`` firewall driver. + + * In the ``[vnc]`` section, enable and configure remote console access: + + .. code-block:: ini + + [vnc] + ... + enabled = True + vncserver_listen = 0.0.0.0 + vncserver_proxyclient_address = $my_ip + novncproxy_base_url = http://controller:6080/vnc_auto.html + + The server component listens on all IP addresses and the proxy + component only listens on the management interface IP address of + the compute node. The base URL indicates the location where you + can use a web browser to access remote consoles of instances + on this compute node. + + .. note:: + + If the web browser to access remote consoles resides on + a host that cannot resolve the ``controller`` hostname, + you must replace ``controller`` with the management + interface IP address of the controller node. + + * In the ``[glance]`` section, configure the location of the + Image service API: + + .. code-block:: ini + + [glance] + ... + api_servers = http://controller:9292 + +#. Ensure the kernel module ``nbd`` is loaded. + + .. code-block:: console + + # modprobe nbd + +#. Ensure the module loads on every boot by adding ``nbd`` + to the ``/etc/modules-load.d/nbd.conf`` file. + +Finalize installation +--------------------- + +#. Determine whether your compute node supports hardware acceleration + for virtual machines: + + .. code-block:: console + + $ egrep -c '(vmx|svm)' /proc/cpuinfo + + If this command returns a value of ``one or greater``, your compute + node supports hardware acceleration which typically requires no + additional configuration. + + If this command returns a value of ``zero``, your compute node does + not support hardware acceleration and you must configure ``libvirt`` + to use QEMU instead of KVM. + + * Replace the ``nova-compute-kvm`` package with ``nova-compute-qemu`` + which automatically changes the ``/etc/nova/nova-compute.conf`` + file and installs the necessary dependencies: + + .. code-block:: console + + # apt-get install nova-compute-qemu + +#. Restart the Compute service: + + .. code-block:: console + + # service nova-compute restart diff --git a/doc/install-guide-debconf/source/nova-controller-install.rst b/doc/install-guide-debconf/source/nova-controller-install.rst new file mode 100644 index 0000000000..a1a74ff206 --- /dev/null +++ b/doc/install-guide-debconf/source/nova-controller-install.rst @@ -0,0 +1,109 @@ +Install and configure controller node +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This section describes how to install and configure the +Compute service, code-named nova, on the controller node. + +Install and configure components +-------------------------------- + +.. include:: shared/note_configuration_vary_by_distribution.rst + +#. Install the packages: + + .. code-block:: console + + # apt-get install nova-api nova-conductor nova-consoleauth \ + nova-consoleproxy nova-scheduler python-novaclient + + Respond to prompts for + :doc:`database management `, + :doc:`Identity service credentials `, + :doc:`service endpoint registration `, + and :doc:`message broker credentials `. + + .. note:: + + ``nova-api-metadata`` is included in the ``nova-api`` package, + and can be selected through debconf. + + .. note:: + + A unique ``nova-consoleproxy`` package provides the + ``nova-novncproxy``, ``nova-spicehtml5proxy``, and + ``nova-xvpvncproxy`` packages. To select packages, edit the + ``/etc/default/nova-consoleproxy`` file or use the debconf interface. + You can also manually edit the ``/etc/default/nova-consoleproxy`` + file, and stop and start the console daemons. + +#. Edit the ``/etc/nova/nova.conf`` file and + complete the following actions: + + * In the ``[DEFAULT]`` section, enable only the compute and metadata + APIs: + + .. code-block:: ini + + [DEFAULT] + ... + enabled_apis = osapi_compute,metadata + + * The ``.config`` and ``.postinst`` maintainer scripts of the + ``nova-common`` package detect automatically the IP address which + goes in the ``my_ip`` directive of the ``[DEFAULT]`` section. This + value will normally still be prompted, and you can check that it + is correct in the nova.conf after ``nova-common`` is installed: + + .. code-block:: ini + + [DEFAULT] + ... + my_ip = 10.0.0.11 + + * In the ``[DEFAULT]`` section, enable support for the Networking service: + + .. code-block:: ini + + [DEFAULT] + ... + use_neutron = True + firewall_driver = nova.virt.firewall.NoopFirewallDriver + + .. note:: + + By default, Compute uses an internal firewall driver. Since the + Networking service includes a firewall driver, you must disable the + Compute firewall driver by using the + ``nova.virt.firewall.NoopFirewallDriver`` firewall driver. + + * In the ``[vnc]`` section, configure the VNC proxy to use the management + interface IP address of the controller node: + + .. code-block:: ini + + [vnc] + ... + vncserver_listen = $my_ip + vncserver_proxyclient_address = $my_ip + + * In the ``[glance]`` section, configure the location of the + Image service API: + + .. code-block:: ini + + [glance] + ... + api_servers = http://controller:9292 + +Finalize installation +--------------------- + +* Restart the Compute services: + + .. code-block:: console + + # service nova-api restart + # service nova-consoleauth restart + # service nova-scheduler restart + # service nova-conductor restart + # service nova-novncproxy restart diff --git a/doc/install-guide-debconf/source/nova-verify.rst b/doc/install-guide-debconf/source/nova-verify.rst new file mode 120000 index 0000000000..5f332d3b41 --- /dev/null +++ b/doc/install-guide-debconf/source/nova-verify.rst @@ -0,0 +1 @@ +../../install-guide/source/nova-verify.rst \ No newline at end of file diff --git a/doc/install-guide-debconf/source/nova.rst b/doc/install-guide-debconf/source/nova.rst new file mode 120000 index 0000000000..dc3baf92b9 --- /dev/null +++ b/doc/install-guide-debconf/source/nova.rst @@ -0,0 +1 @@ +../../install-guide/source/nova.rst \ No newline at end of file diff --git a/doc/install-guide-debconf/source/overview.rst b/doc/install-guide-debconf/source/overview.rst new file mode 120000 index 0000000000..c78fb18d61 --- /dev/null +++ b/doc/install-guide-debconf/source/overview.rst @@ -0,0 +1 @@ +../../install-guide/source/overview.rst \ No newline at end of file diff --git a/doc/install-guide-debconf/source/shared b/doc/install-guide-debconf/source/shared new file mode 120000 index 0000000000..c474beb642 --- /dev/null +++ b/doc/install-guide-debconf/source/shared @@ -0,0 +1 @@ +../../install-guide/source/shared \ No newline at end of file diff --git a/doc/install-guide-debconf/source/swift-controller-include.txt b/doc/install-guide-debconf/source/swift-controller-include.txt new file mode 120000 index 0000000000..18038a732e --- /dev/null +++ b/doc/install-guide-debconf/source/swift-controller-include.txt @@ -0,0 +1 @@ +../../install-guide/source/swift-controller-include.txt \ No newline at end of file diff --git a/doc/install-guide-debconf/source/swift-controller-install.rst b/doc/install-guide-debconf/source/swift-controller-install.rst new file mode 120000 index 0000000000..037f2797cb --- /dev/null +++ b/doc/install-guide-debconf/source/swift-controller-install.rst @@ -0,0 +1 @@ +../../install-guide/source/swift-controller-install.rst \ No newline at end of file diff --git a/doc/install-guide-debconf/source/swift-finalize-installation.rst b/doc/install-guide-debconf/source/swift-finalize-installation.rst new file mode 120000 index 0000000000..4eb786e5e6 --- /dev/null +++ b/doc/install-guide-debconf/source/swift-finalize-installation.rst @@ -0,0 +1 @@ +../../install-guide/source/swift-finalize-installation.rst \ No newline at end of file diff --git a/doc/install-guide-debconf/source/swift-initial-rings.rst b/doc/install-guide-debconf/source/swift-initial-rings.rst new file mode 120000 index 0000000000..e336215591 --- /dev/null +++ b/doc/install-guide-debconf/source/swift-initial-rings.rst @@ -0,0 +1 @@ +../../install-guide/source/swift-initial-rings.rst \ No newline at end of file diff --git a/doc/install-guide-debconf/source/swift-next-steps.rst b/doc/install-guide-debconf/source/swift-next-steps.rst new file mode 120000 index 0000000000..4d2a3905ae --- /dev/null +++ b/doc/install-guide-debconf/source/swift-next-steps.rst @@ -0,0 +1 @@ +../../install-guide/source/swift-next-steps.rst \ No newline at end of file diff --git a/doc/install-guide-debconf/source/swift-storage-include1.txt b/doc/install-guide-debconf/source/swift-storage-include1.txt new file mode 120000 index 0000000000..29937790dd --- /dev/null +++ b/doc/install-guide-debconf/source/swift-storage-include1.txt @@ -0,0 +1 @@ +../../install-guide/source/swift-storage-include1.txt \ No newline at end of file diff --git a/doc/install-guide-debconf/source/swift-storage-include2.txt b/doc/install-guide-debconf/source/swift-storage-include2.txt new file mode 120000 index 0000000000..06c07254ca --- /dev/null +++ b/doc/install-guide-debconf/source/swift-storage-include2.txt @@ -0,0 +1 @@ +../../install-guide/source/swift-storage-include2.txt \ No newline at end of file diff --git a/doc/install-guide-debconf/source/swift-storage-include3.txt b/doc/install-guide-debconf/source/swift-storage-include3.txt new file mode 120000 index 0000000000..b723f6a284 --- /dev/null +++ b/doc/install-guide-debconf/source/swift-storage-include3.txt @@ -0,0 +1 @@ +../../install-guide/source/swift-storage-include3.txt \ No newline at end of file diff --git a/doc/install-guide-debconf/source/swift-storage-install.rst b/doc/install-guide-debconf/source/swift-storage-install.rst new file mode 120000 index 0000000000..d248627f19 --- /dev/null +++ b/doc/install-guide-debconf/source/swift-storage-install.rst @@ -0,0 +1 @@ +../../install-guide/source/swift-storage-install.rst \ No newline at end of file diff --git a/doc/install-guide-debconf/source/swift-verify.rst b/doc/install-guide-debconf/source/swift-verify.rst new file mode 120000 index 0000000000..c62b991c93 --- /dev/null +++ b/doc/install-guide-debconf/source/swift-verify.rst @@ -0,0 +1 @@ +../../install-guide/source/swift-verify.rst \ No newline at end of file diff --git a/doc/install-guide-debconf/source/swift.rst b/doc/install-guide-debconf/source/swift.rst new file mode 120000 index 0000000000..743dd1f06a --- /dev/null +++ b/doc/install-guide-debconf/source/swift.rst @@ -0,0 +1 @@ +../../install-guide/source/swift.rst \ No newline at end of file diff --git a/doc/install-guide-debconf/source/trove-install.rst b/doc/install-guide-debconf/source/trove-install.rst new file mode 100644 index 0000000000..e70445946a --- /dev/null +++ b/doc/install-guide-debconf/source/trove-install.rst @@ -0,0 +1,157 @@ +.. _trove-install: + +Install and configure +~~~~~~~~~~~~~~~~~~~~~ + +This section describes how to install and configure the +Database service, code-named trove, on the controller node. + +This section assumes that you already have a working OpenStack +environment with at least the following components installed: +Compute, Image Service, Identity. + +* If you want to do backup and restore, you also need Object Storage. + +* If you want to provision datastores on block-storage volumes, you also + need Block Storage. + +Install and configure components +-------------------------------- + +.. include:: shared/note_configuration_vary_by_distribution.rst + +#. Install the packages: + + .. code-block:: console + + # apt-get update + + # apt-get install python-trove python-troveclient \ + python-glanceclient trove-common trove-api trove-taskmanager \ + trove-conductor + +#. In ``/etc/trove``, edit the following configuration files, + taking the below actions for each file: + + ``trove.conf`` + + ``trove-taskmanager.conf`` + + ``trove-conductor.conf`` + + * Provide appropriate + values for the following settings: + + .. code-block:: ini + + [DEFAULT] + log_dir = /var/log/trove + trove_auth_url = http://controller:5000/v2.0 + nova_compute_url = http://controller:8774/v2 + cinder_url = http://controller:8776/v1 + swift_url = http://controller:8080/v1/AUTH_ + notifier_queue_hostname = controller + ... + [database] + connection = mysql://trove:TROVE_DBPASS@controller/trove + + * Configure the Database module to use the ``RabbitMQ`` message broker + by setting the following options in the ``[DEFAULT]`` configuration + group of each file: + + .. code-block:: ini + + [DEFAULT] + ... + rpc_backend = rabbit + + [oslo_messaging_rabbit] + ... + rabbit_host = controller + rabbit_userid = openstack + rabbit_password = RABBIT_PASS + +#. Verify that the ``api-paste.ini`` + file is present in ``/etc/trove``. + + If the file is not present, you can get it from this + `location `__. + +#. Edit the ``trove.conf`` file so it includes appropriate values for the + settings shown below: + + .. code-block:: ini + + [DEFAULT] + auth_strategy = keystone + ... + # Config option for showing the IP address that nova doles out + add_addresses = True + network_label_regex = ^NETWORK_LABEL$ + ... + api_paste_config = /etc/trove/api-paste.ini + ... + [keystone_authtoken] + ... + auth_uri = http://controller:5000 + auth_url = http://controller:35357 + auth_type = password + project_domain_name = default + user_domain_name = default + project_name = service + username = trove + password = TROVE_PASS + +#. Edit the ``trove-taskmanager.conf`` file so it includes the required + settings to connect to the OpenStack Compute service as shown below: + + .. code-block:: ini + + [DEFAULT] + ... + # Configuration options for talking to nova via the novaclient. + # These options are for an admin user in your keystone config. + # It proxy's the token received from the user to send to nova + # via this admin users creds, + # basically acting like the client via that proxy token. + nova_proxy_admin_user = admin + nova_proxy_admin_pass = ADMIN_PASS + nova_proxy_admin_tenant_name = service + taskmanager_manager = trove.taskmanager.manager.Manager + +#. In ``etc/trove``, edit the ``trove-guestagent.conf`` file + so that future trove guests can connect to your OpenStack environment: + + .. code-block:: ini + + rabbit_host = controller + rabbit_password = RABBIT_PASS + nova_proxy_admin_user = admin + nova_proxy_admin_pass = ADMIN_PASS + nova_proxy_admin_tenant_name = service + trove_auth_url = http://controller:35357/v2.0 + +#. Populate the trove database you created earlier in this procedure: + + .. code-block:: console + + # su -s /bin/sh -c "trove-manage db_sync" trove + ... + 2016-04-06 22:00:17.771 10706 INFO trove.db.sqlalchemy.migration [-] + Upgrading mysql://trove:dbaasdb@controller/trove to version latest + + .. note:: + + Ignore any deprecation messages in this output. + + +Finalize installation +--------------------- + +#. Restart the Database services: + + .. code-block:: console + + # service trove-api restart + # service trove-taskmanager restart + # service trove-conductor restart diff --git a/doc/install-guide-debconf/source/trove-next-steps.rst b/doc/install-guide-debconf/source/trove-next-steps.rst new file mode 120000 index 0000000000..6672d4bc74 --- /dev/null +++ b/doc/install-guide-debconf/source/trove-next-steps.rst @@ -0,0 +1 @@ +../../install-guide/source/trove-next-steps.rst \ No newline at end of file diff --git a/doc/install-guide-debconf/source/trove-verify.rst b/doc/install-guide-debconf/source/trove-verify.rst new file mode 120000 index 0000000000..70b0e15450 --- /dev/null +++ b/doc/install-guide-debconf/source/trove-verify.rst @@ -0,0 +1 @@ +../../install-guide/source/trove-verify.rst \ No newline at end of file diff --git a/doc/install-guide-debconf/source/trove.rst b/doc/install-guide-debconf/source/trove.rst new file mode 120000 index 0000000000..ce5a9fd7d6 --- /dev/null +++ b/doc/install-guide-debconf/source/trove.rst @@ -0,0 +1 @@ +../../install-guide/source/trove.rst \ No newline at end of file diff --git a/tools/build-install-guides-rst.sh b/tools/build-install-guides-rst.sh index c338ddace7..e656fa03da 100755 --- a/tools/build-install-guides-rst.sh +++ b/tools/build-install-guides-rst.sh @@ -2,7 +2,7 @@ mkdir -p publish-docs -TAGS=${1:-obs rdo ubuntu debian} +TAGS=${1:-obs rdo ubuntu debian debconf} INDEX=doc/install-guide/source/index.rst LINKCHECK="" @@ -23,51 +23,59 @@ cp -f ${INDEX} ${INDEX}.save trap "mv -f ${INDEX}.save ${INDEX}" EXIT for tag in $TAGS; do - ## - # Because Sphinx uses the first heading as title regardless of - # only directive, replace title directive with the proper title - # for each distribution to set the title explicitly. - - title=$(grep -m 1 -A 5 "^.. only:: ${tag}" ${INDEX} | \ - sed -n 4p | sed -e 's/^ *//g') - sed -i -e "s/\.\. title::.*/.. title:: ${title}/" ${INDEX} - - ## - # Sphinx builds the navigation before processing directives, - # so the conditional toctree does not work. - # We need to prepare toctree depending on distribution - # only with one toctree before exectuing sphinx-build. - - # Get line number of each tag - lineno_start=$(grep -n "^Contents" ${INDEX} | sed -e 's/:.*//') - lineno_end=$(grep -n "^.. end of contents" ${INDEX} | sed -e 's/:.*//') - lineno_debian=$(grep -n "^.. only:: debian" ${INDEX} \ - | tail -1 | sed -e 's/:.*//') - lineno_notdebian=$(grep -n "^.. only:: [^d]" ${INDEX} \ - | tail -1 | sed -e 's/:.*//') - - # Remove indent for pseudo only directive - sed -i "${lineno_start},${lineno_end} s/^ *\.\. toctree/.. toctree/" ${INDEX} - sed -i "${lineno_start},${lineno_end} s/^ */ /" ${INDEX} - - # Remove unnecessary toctree for each distribution - if [[ "$tag" == "debian" ]]; then - sed -i "${lineno_notdebian},${lineno_debian}d" ${INDEX} + if [[ "$tag" == "debconf" ]]; then + # Build the guide with debconf + # To use debian only contents, use "debian" tag. + tools/build-rst.sh doc/install-guide-debconf \ + $GLOSSARY --tag debian --target "draft/install-guide-debconf" \ + $LINKCHECK else - sed -i "${lineno_debian},$((${lineno_end}-1))d" ${INDEX} - sed -i "${lineno_notdebian}d" ${INDEX} - fi + ## + # Because Sphinx uses the first heading as title regardless of + # only directive, replace title directive with the proper title + # for each distribution to set the title explicitly. - # Build the guide - tools/build-rst.sh doc/install-guide \ - --tag ${tag} --target "draft/install-guide-${tag}" $LINKCHECK + title=$(grep -m 1 -A 5 "^.. only:: ${tag}" ${INDEX} | \ + sed -n 4p | sed -e 's/^ *//g') + sed -i -e "s/\.\. title::.*/.. title:: ${title}/" ${INDEX} - # Restore the index file - cp -f ${INDEX}.save ${INDEX} + ## + # Sphinx builds the navigation before processing directives, + # so the conditional toctree does not work. + # We need to prepare toctree depending on distribution + # only with one toctree before exectuing sphinx-build. - ## - # Remove Debian specific content from other guides - if [[ "$tag" != "debian" ]]; then - rm -rf publish-docs/draft/install-guide-$tag/debconf + # Get line number of each tag + lineno_start=$(grep -n "^Contents" ${INDEX} | sed -e 's/:.*//') + lineno_end=$(grep -n "^.. end of contents" ${INDEX} | sed -e 's/:.*//') + lineno_debian=$(grep -n "^.. only:: debian" ${INDEX} \ + | tail -1 | sed -e 's/:.*//') + lineno_notdebian=$(grep -n "^.. only:: [^d]" ${INDEX} \ + | tail -1 | sed -e 's/:.*//') + + # Remove indent for pseudo only directive + sed -i "${lineno_start},${lineno_end} s/^ *\.\. toctree/.. toctree/" ${INDEX} + sed -i "${lineno_start},${lineno_end} s/^ */ /" ${INDEX} + + # Remove unnecessary toctree for each distribution + if [[ "$tag" == "debian" ]]; then + sed -i "${lineno_notdebian},${lineno_debian}d" ${INDEX} + else + sed -i "${lineno_debian},$((${lineno_end}-1))d" ${INDEX} + sed -i "${lineno_notdebian}d" ${INDEX} + fi + + # Build the guide + tools/build-rst.sh doc/install-guide \ + --tag ${tag} --target "draft/install-guide-${tag}" $LINKCHECK + + # Restore the index file + cp -f ${INDEX}.save ${INDEX} + + ## + # Remove Debian specific content from other guides + if [[ "$tag" != "debian" ]]; then + rm -rf publish-docs/draft/install-guide-$tag/debconf + fi fi done diff --git a/tox.ini b/tox.ini index ac890daafa..3a68e52cf6 100644 --- a/tox.ini +++ b/tox.ini @@ -41,6 +41,10 @@ commands = commands = {toxinidir}/tools/build-install-guides-rst.sh +[testenv:install-guide-debconf] +commands = + {toxinidir}/tools/build-install-guides-rst.sh debconf + [testenv:install-guide-debian] commands = {toxinidir}/tools/build-install-guides-rst.sh debian @@ -112,7 +116,7 @@ commands = [doc8] # Settings for doc8: # Ignore target directories -ignore-path = doc/*/target,doc/*/build*,doc/install-guide/source/swift-controller-include.txt +ignore-path = doc/*/target,doc/*/build*,doc/install-guide/source/swift-controller-include.txt,doc/install-guide-debconf/source/swift-controller-include.txt # File extensions to use extensions = .rst,.txt # Maximal line length should be 79 but we have some overlong lines.