diff --git a/README.md b/README.md index acc3e5a747..df0df917a4 100644 --- a/README.md +++ b/README.md @@ -93,345 +93,14 @@ for example). # Customizing -You can override environment variables used in `stack.sh` by creating file -name `local.conf` with a ``localrc`` section as shown below. It is likely -that you will need to do this to tweak your networking configuration should -you need to access your cloud from a different host. +You can override environment variables used in `stack.sh` by creating +file name `local.conf` with a ``localrc`` section as shown below. It +is likely that you will need to do this to tweak several settings for +your environment. [[local|localrc]] VARIABLE=value -See the **Local Configuration** section below for more details. - -# Database Backend - -Multiple database backends are available. The available databases are defined -in the lib/databases directory. -`mysql` is the default database, choose a different one by putting the -following in the `localrc` section: - - disable_service mysql - enable_service postgresql - -`mysql` is the default database. - -# RPC Backend - -Support for a RabbitMQ RPC backend is included. Additional RPC backends may -be available via external plugins. Enabling or disabling RabbitMQ is handled -via the usual service functions and ``ENABLED_SERVICES``. - -Example disabling RabbitMQ in ``local.conf``: - - disable_service rabbit - -# Apache Frontend - -Apache web server can be enabled for wsgi services that support being deployed -under HTTPD + mod_wsgi. By default, services that recommend running under -HTTPD + mod_wsgi are deployed under Apache. To use an alternative deployment -strategy (e.g. eventlet) for services that support an alternative to HTTPD + -mod_wsgi set ``ENABLE_HTTPD_MOD_WSGI_SERVICES`` to ``False`` in your -``local.conf``. - -Each service that can be run under HTTPD + mod_wsgi also has an override -toggle available that can be set in your ``local.conf``. - -Keystone is run under HTTPD + mod_wsgi by default. - -Example (Keystone): - - KEYSTONE_USE_MOD_WSGI="True" - -Example (Nova): - - NOVA_USE_MOD_WSGI="True" - -Example (Swift): - - SWIFT_USE_MOD_WSGI="True" - -# Swift - -Swift is disabled by default. When enabled, it is configured with -only one replica to avoid being IO/memory intensive on a small -vm. When running with only one replica the account, container and -object services will run directly in screen. The others services like -replicator, updaters or auditor runs in background. - -If you would like to enable Swift you can add this to your `localrc` section: - - enable_service s-proxy s-object s-container s-account - -If you want a minimal Swift install with only Swift and Keystone you -can have this instead in your `localrc` section: - - disable_all_services - enable_service key mysql s-proxy s-object s-container s-account - -If you only want to do some testing of a real normal swift cluster -with multiple replicas you can do so by customizing the variable -`SWIFT_REPLICAS` in your `localrc` section (usually to 3). - -# Swift S3 - -If you are enabling `swift3` in `ENABLED_SERVICES` DevStack will -install the swift3 middleware emulation. Swift will be configured to -act as a S3 endpoint for Keystone so effectively replacing the -`nova-objectstore`. - -Only Swift proxy server is launched in the screen session all other -services are started in background and managed by `swift-init` tool. - -# Neutron - -Basic Setup - -In order to enable Neutron in a single node setup, you'll need the -following settings in your `local.conf`: - - disable_service n-net - enable_service q-svc - enable_service q-agt - enable_service q-dhcp - enable_service q-l3 - enable_service q-meta - enable_service q-metering - -Then run `stack.sh` as normal. - -DevStack supports setting specific Neutron configuration flags to the -service, ML2 plugin, DHCP and L3 configuration files: - - [[post-config|/$Q_PLUGIN_CONF_FILE]] - [ml2] - mechanism_drivers=openvswitch,l2population - - [[post-config|$NEUTRON_CONF]] - [DEFAULT] - quota_port=42 - - [[post-config|$Q_L3_CONF_FILE]] - [DEFAULT] - agent_mode=legacy - - [[post-config|$Q_DHCP_CONF_FILE]] - [DEFAULT] - dnsmasq_dns_servers = 8.8.8.8,8.8.4.4 - -The ML2 plugin can run with the OVS, LinuxBridge, or Hyper-V agents on compute -hosts. This is a simple way to configure the ml2 plugin: - - # VLAN configuration - ENABLE_TENANT_VLANS=True - - # GRE tunnel configuration - ENABLE_TENANT_TUNNELS=True - - # VXLAN tunnel configuration - Q_ML2_TENANT_NETWORK_TYPE=vxlan - -The above will default in DevStack to using the OVS on each compute host. -To change this, set the `Q_AGENT` variable to the agent you want to run -(e.g. linuxbridge). - - Variable Name Notes - ---------------------------------------------------------------------------- - Q_AGENT This specifies which agent to run with the - ML2 Plugin (Typically either `openvswitch` - or `linuxbridge`). - Defaults to `openvswitch`. - Q_ML2_PLUGIN_MECHANISM_DRIVERS The ML2 MechanismDrivers to load. The default - is `openvswitch,linuxbridge`. - Q_ML2_PLUGIN_TYPE_DRIVERS The ML2 TypeDrivers to load. Defaults to - all available TypeDrivers. - Q_ML2_PLUGIN_GRE_TYPE_OPTIONS GRE TypeDriver options. Defaults to - `tunnel_id_ranges=1:1000'. - Q_ML2_PLUGIN_VXLAN_TYPE_OPTIONS VXLAN TypeDriver options. Defaults to - `vni_ranges=1001:2000` - Q_ML2_PLUGIN_VLAN_TYPE_OPTIONS VLAN TypeDriver options. Defaults to none. - -# Heat - -Heat is disabled by default (see `stackrc` file). To enable it explicitly -you'll need the following settings in your `localrc` section: - - enable_service heat h-api h-api-cfn h-api-cw h-eng - -Heat can also run in standalone mode, and be configured to orchestrate -on an external OpenStack cloud. To launch only Heat in standalone mode -you'll need the following settings in your `localrc` section: - - disable_all_services - enable_service rabbit mysql heat h-api h-api-cfn h-api-cw h-eng - HEAT_STANDALONE=True - KEYSTONE_SERVICE_HOST=... - KEYSTONE_AUTH_HOST=... - -# Tempest - -If tempest has been successfully configured, a basic set of smoke -tests can be run as follows: - - $ cd /opt/stack/tempest - $ tox -efull tempest.scenario.test_network_basic_ops - -By default tempest is downloaded and the config file is generated, but the -tempest package is not installed in the system's global site-packages (the -package install includes installing dependences). So tempest won't run -outside of tox. If you would like to install it add the following to your -``localrc`` section: - - INSTALL_TEMPEST=True - -# DevStack on Xenserver - -If you would like to use Xenserver as the hypervisor, please refer -to the instructions in `./tools/xen/README.md`. - -# Additional Projects - -DevStack has a hook mechanism to call out to a dispatch script at specific -points in the execution of `stack.sh`, `unstack.sh` and `clean.sh`. This -allows upper-layer projects, especially those that the lower layer projects -have no dependency on, to be added to DevStack without modifying the core -scripts. Tempest is built this way as an example of how to structure the -dispatch script, see `extras.d/80-tempest.sh`. See `extras.d/README.md` -for more information. - -# Multi-Node Setup - -A more interesting setup involves running multiple compute nodes, with Neutron -networks connecting VMs on different compute nodes. -You should run at least one "controller node", which should have a `stackrc` -that includes at least: - - disable_service n-net - enable_service q-svc - enable_service q-agt - enable_service q-dhcp - enable_service q-l3 - enable_service q-meta - enable_service neutron - -You likely want to change your `localrc` section to run a scheduler that -will balance VMs across hosts: - - SCHEDULER=nova.scheduler.filter_scheduler.FilterScheduler - -You can then run many compute nodes, each of which should have a `stackrc` -which includes the following, with the IP address of the above controller node: - - ENABLED_SERVICES=n-cpu,rabbit,neutron,q-agt - SERVICE_HOST=[IP of controller node] - MYSQL_HOST=$SERVICE_HOST - RABBIT_HOST=$SERVICE_HOST - Q_HOST=$SERVICE_HOST - MATCHMAKER_REDIS_HOST=$SERVICE_HOST - -# Multi-Region Setup - -We want to setup two devstack (RegionOne and RegionTwo) with shared keystone -(same users and services) and horizon. -Keystone and Horizon will be located in RegionOne. -Full spec is available at: -https://wiki.openstack.org/wiki/Heat/Blueprints/Multi_Region_Support_for_Heat. - -In RegionOne: - - REGION_NAME=RegionOne - -In RegionTwo: - - disable_service horizon - KEYSTONE_SERVICE_HOST= - KEYSTONE_AUTH_HOST= - REGION_NAME=RegionTwo - -# Cells - -Cells is a new scaling option with a full spec at: -http://wiki.openstack.org/blueprint-nova-compute-cells. - -To setup a cells environment add the following to your `localrc` section: - - enable_service n-cell - -Be aware that there are some features currently missing in cells, one notable -one being security groups. The exercises have been patched to disable -functionality not supported by cells. - -# IPv6 - -By default, most Openstack services are bound to 0.0.0.0 -and service endpoints are registered as IPv4 addresses. -A new variable was created to control this behavior, and to -allow for operation over IPv6 instead of IPv4. - -For this, add the following to `local.conf`: - - SERVICE_IP_VERSION=6 - -When set to "6" devstack services will open listen sockets on :: -and service endpoints will be registered using HOST_IPV6 as the -address. The default value for this setting is `4`. Dual-mode -support, for example `4+6` is not currently supported. - - -# Local Configuration - -Historically DevStack has used ``localrc`` to contain all local configuration -and customizations. More and more of the configuration variables available for -DevStack are passed-through to the individual project configuration files. -The old mechanism for this required specific code for each file and did not -scale well. This is handled now by a master local configuration file. - -# local.conf - -The new config file ``local.conf`` is an extended-INI format that introduces -a new meta-section header that provides some additional information such -as a phase name and destination config filename: - - [[ | ]] - -where ```` is one of a set of phase names defined by ``stack.sh`` -and ```` is the configuration filename. The filename is -eval'ed in the ``stack.sh`` context so all environment variables are -available and may be used. Using the project config file variables in -the header is strongly suggested (see the ``NOVA_CONF`` example below). -If the path of the config file does not exist it is skipped. - -The defined phases are: - -* **local** - extracts ``localrc`` from ``local.conf`` before ``stackrc`` is sourced -* **post-config** - runs after the layer 2 services are configured - and before they are started -* **extra** - runs after services are started and before any files - in ``extra.d`` are executed -* **post-extra** - runs after files in ``extra.d`` are executed - -The file is processed strictly in sequence; meta-sections may be specified more -than once but if any settings are duplicated the last to appear in the file -will be used. - - [[post-config|$NOVA_CONF]] - [DEFAULT] - use_syslog = True - - [osapi_v3] - enabled = False - -A specific meta-section ``local|localrc`` is used to provide a default -``localrc`` file (actually ``.localrc.auto``). This allows all custom -settings for DevStack to be contained in a single file. If ``localrc`` -exists it will be used instead to preserve backward-compatibility. - - [[local|localrc]] - FIXED_RANGE=10.254.1.0/24 - ADMIN_PASSWORD=speciale - LOGFILE=$DEST/logs/stack.sh.log - -Note that ``Q_PLUGIN_CONF_FILE`` is unique in that it is assumed to *NOT* -start with a ``/`` (slash) character. A slash will need to be added: - - [[post-config|/$Q_PLUGIN_CONF_FILE]] +Start by reading the [configuration +guide](doc/source/configuration.rst) for details of the many available +options. \ No newline at end of file diff --git a/doc/source/configuration.rst b/doc/source/configuration.rst index 90b7d44dec..ed17924d45 100644 --- a/doc/source/configuration.rst +++ b/doc/source/configuration.rst @@ -148,6 +148,34 @@ will not be set if there is no IPv6 address on the default Ethernet interface. Setting it here also makes it available for ``openrc`` to set ``OS_AUTH_URL``. ``HOST_IPV6`` is not set by default. +Examples +======== + +- Eliminate a Cinder pass-through (``CINDER_PERIODIC_INTERVAL``): + + :: + + [[post-config|$CINDER_CONF]] + [DEFAULT] + periodic_interval = 60 + +- Sample ``local.conf`` with screen logging enabled: + + :: + + [[local|localrc]] + FIXED_RANGE=10.254.1.0/24 + NETWORK_GATEWAY=10.254.1.1 + LOGDAYS=1 + LOGDIR=$DEST/logs + LOGFILE=$LOGDIR/stack.sh.log + ADMIN_PASSWORD=quiet + DATABASE_PASSWORD=$ADMIN_PASSWORD + RABBIT_PASSWORD=$ADMIN_PASSWORD + SERVICE_PASSWORD=$ADMIN_PASSWORD + SERVICE_TOKEN=a682f596-76f3-11e3-b3b2-e716f9080d50 + + Configuration Notes =================== @@ -228,6 +256,72 @@ to direct the message stream to the log host. | SYSLOG_HOST=$HOST_IP SYSLOG_PORT=516 + +Database Backend +---------------- + +Multiple database backends are available. The available databases are defined +in the lib/databases directory. +`mysql` is the default database, choose a different one by putting the +following in the `localrc` section: + + :: + + disable_service mysql + enable_service postgresql + +`mysql` is the default database. + +RPC Backend +----------- + +Support for a RabbitMQ RPC backend is included. Additional RPC +backends may be available via external plugins. Enabling or disabling +RabbitMQ is handled via the usual service functions and +``ENABLED_SERVICES``. + +Example disabling RabbitMQ in ``local.conf``: + +:: + disable_service rabbit + + +Apache Frontend +--------------- + +The Apache web server can be enabled for wsgi services that support +being deployed under HTTPD + mod_wsgi. By default, services that +recommend running under HTTPD + mod_wsgi are deployed under Apache. To +use an alternative deployment strategy (e.g. eventlet) for services +that support an alternative to HTTPD + mod_wsgi set +``ENABLE_HTTPD_MOD_WSGI_SERVICES`` to ``False`` in your +``local.conf``. + +Each service that can be run under HTTPD + mod_wsgi also has an +override toggle available that can be set in your ``local.conf``. + +Keystone is run under Apache with ``mod_wsgi`` by default. + +Example (Keystone) + +:: + + KEYSTONE_USE_MOD_WSGI="True" + +Example (Nova): + +:: + + NOVA_USE_MOD_WSGI="True" + +Example (Swift): + +:: + + SWIFT_USE_MOD_WSGI="True" + + + Libraries from Git ------------------ @@ -295,48 +389,6 @@ that matches requirements. PIP_UPGRADE=True -Swift ------ - -Swift is now used as the back-end for the S3-like object store. When -enabled Nova's objectstore (``n-obj`` in ``ENABLED_SERVICES``) is -automatically disabled. Enable Swift by adding it services to -``ENABLED_SERVICES`` - - :: - - enable_service s-proxy s-object s-container s-account - -Setting Swift's hash value is required and you will be prompted for it -if Swift is enabled so just set it to something already: - - :: - - SWIFT_HASH=66a3d6b56c1f479c8b4e70ab5c2000f5 - -For development purposes the default number of replicas is set to -``1`` to reduce the overhead required. To better simulate a production -deployment set this to ``3`` or more. - - :: - - SWIFT_REPLICAS=3 - -The data for Swift is stored in the source tree by default (in -``$DEST/swift/data``) and can be moved by setting -``SWIFT_DATA_DIR``. The specified directory will be created if it does -not exist. - - :: - - SWIFT_DATA_DIR=$DEST/data/swift - -*Note*: Previously just enabling ``swift`` was sufficient to start the -Swift services. That does not provide proper service granularity, -particularly in multi-host configurations, and is considered -deprecated. Some service combination tests now check for specific -Swift services and the old blanket acceptance will longer work -correctly. Service Catalog Backend ----------------------- @@ -354,47 +406,6 @@ with ``KEYSTONE_CATALOG_BACKEND``: DevStack's default configuration in ``sql`` mode is set in ``files/keystone_data.sh`` -Cinder ------- - -The logical volume group used to hold the Cinder-managed volumes is -set by ``VOLUME_GROUP``, the logical volume name prefix is set with -``VOLUME_NAME_PREFIX`` and the size of the volume backing file is set -with ``VOLUME_BACKING_FILE_SIZE``. - - :: - - VOLUME_GROUP="stack-volumes" - VOLUME_NAME_PREFIX="volume-" - VOLUME_BACKING_FILE_SIZE=10250M - -Multi-host DevStack -------------------- - -Running DevStack with multiple hosts requires a custom ``local.conf`` -section for each host. The master is the same as a single host -installation with ``MULTI_HOST=True``. The slaves have fewer services -enabled and a couple of host variables pointing to the master. - -Master -~~~~~~ - -Set ``MULTI_HOST`` to true - :: - - MULTI_HOST=True - -Slave -~~~~~ - -Set the following options to point to the master - - :: - - MYSQL_HOST=w.x.y.z - RABBIT_HOST=w.x.y.z - GLANCE_HOSTPORT=w.x.y.z:9292 - ENABLED_SERVICES=n-vol,n-cpu,n-net,n-api IP Version ---------- @@ -447,29 +458,163 @@ optionally be used to alter the default IPv6 address HOST_IPV6=${some_local_ipv6_address} -Examples -======== +Multi-node setup +~~~~~~~~~~~~~~~~ -- Eliminate a Cinder pass-through (``CINDER_PERIODIC_INTERVAL``): +See the :doc:`multi-node lab guide` - :: +Projects +-------- - [[post-config|$CINDER_CONF]] - [DEFAULT] - periodic_interval = 60 +Neutron +~~~~~~~ -- Sample ``local.conf`` with screen logging enabled: +See the :doc:`neutron configuration guide` for +details on configuration of Neutron - :: - [[local|localrc]] - FIXED_RANGE=10.254.1.0/24 - NETWORK_GATEWAY=10.254.1.1 - LOGDAYS=1 - LOGDIR=$DEST/logs - LOGFILE=$LOGDIR/stack.sh.log - ADMIN_PASSWORD=quiet - DATABASE_PASSWORD=$ADMIN_PASSWORD - RABBIT_PASSWORD=$ADMIN_PASSWORD - SERVICE_PASSWORD=$ADMIN_PASSWORD - SERVICE_TOKEN=a682f596-76f3-11e3-b3b2-e716f9080d50 +Swift +~~~~~ + +Swift is disabled by default. When enabled, it is configured with +only one replica to avoid being IO/memory intensive on a small +VM. When running with only one replica the account, container and +object services will run directly in screen. The others services like +replicator, updaters or auditor runs in background. + +If you would like to enable Swift you can add this to your `localrc` +section: + +:: + + enable_service s-proxy s-object s-container s-account + +If you want a minimal Swift install with only Swift and Keystone you +can have this instead in your `localrc` section: + +:: + + disable_all_services + enable_service key mysql s-proxy s-object s-container s-account + +If you only want to do some testing of a real normal swift cluster +with multiple replicas you can do so by customizing the variable +`SWIFT_REPLICAS` in your `localrc` section (usually to 3). + +Swift S3 +++++++++ + +If you are enabling `swift3` in `ENABLED_SERVICES` DevStack will +install the swift3 middleware emulation. Swift will be configured to +act as a S3 endpoint for Keystone so effectively replacing the +`nova-objectstore`. + +Only Swift proxy server is launched in the screen session all other +services are started in background and managed by `swift-init` tool. + +Heat +~~~~ + +Heat is disabled by default (see `stackrc` file). To enable it +explicitly you'll need the following settings in your `localrc` +section + +:: + + enable_service heat h-api h-api-cfn h-api-cw h-eng + +Heat can also run in standalone mode, and be configured to orchestrate +on an external OpenStack cloud. To launch only Heat in standalone mode +you'll need the following settings in your `localrc` section + +:: + + disable_all_services + enable_service rabbit mysql heat h-api h-api-cfn h-api-cw h-eng + HEAT_STANDALONE=True + KEYSTONE_SERVICE_HOST=... + KEYSTONE_AUTH_HOST=... + +Tempest +~~~~~~~ + +If tempest has been successfully configured, a basic set of smoke +tests can be run as follows: + +:: + + $ cd /opt/stack/tempest + $ tox -efull tempest.scenario.test_network_basic_ops + +By default tempest is downloaded and the config file is generated, but the +tempest package is not installed in the system's global site-packages (the +package install includes installing dependences). So tempest won't run +outside of tox. If you would like to install it add the following to your +``localrc`` section: + +:: + + INSTALL_TEMPEST=True + + +Xenserver +~~~~~~~~~ + +If you would like to use Xenserver as the hypervisor, please refer to +the instructions in `./tools/xen/README.md`. + +Cells +~~~~~ + +`Cells `__ is +an alternative scaling option. To setup a cells environment add the +following to your `localrc` section: + +:: + + enable_service n-cell + +Be aware that there are some features currently missing in cells, one +notable one being security groups. The exercises have been patched to +disable functionality not supported by cells. + +Cinder +~~~~~~ + +The logical volume group used to hold the Cinder-managed volumes is +set by ``VOLUME_GROUP``, the logical volume name prefix is set with +``VOLUME_NAME_PREFIX`` and the size of the volume backing file is set +with ``VOLUME_BACKING_FILE_SIZE``. + + :: + + VOLUME_GROUP="stack-volumes" + VOLUME_NAME_PREFIX="volume-" + VOLUME_BACKING_FILE_SIZE=10250M + + +Keystone +~~~~~~~~ + +Multi-Region Setup +++++++++++++++++++ + +We want to setup two devstack (RegionOne and RegionTwo) with shared +keystone (same users and services) and horizon. Keystone and Horizon +will be located in RegionOne. Full spec is available at: +``__. + +In RegionOne: + +:: + + REGION_NAME=RegionOne + +In RegionTwo: + +:: + + disable_service horizon + KEYSTONE_SERVICE_HOST= + KEYSTONE_AUTH_HOST= + REGION_NAME=RegionTwo