From b4e4a6d1dd6f60063921872575d7d88c0ab778fe Mon Sep 17 00:00:00 2001 From: Tom Cammann Date: Mon, 2 Mar 2015 12:11:34 +0000 Subject: [PATCH] Add devstack module to contrib Add devstack module and with instructions on using it included in the quickstart guide. The old manual process for using magnum with devstack has been kept to retain information on how to deploy magnum manually. A localrc for use with devstack has also been included rather than forcing the user to copy and paste from the docs. Closes-bug: 1430053 Change-Id: I373021378fd25d5a6cdb6213eaa21f8045a66be6 --- contrib/devstack/README.rst | 28 +++ contrib/devstack/extras.d/70-magnum.sh | 45 +++++ contrib/devstack/lib/magnum | 251 +++++++++++++++++++++++++ contrib/devstack/localrc.example | 44 +++++ contrib/devstack/prepare_devstack.sh | 14 ++ doc/source/dev/dev-manual-devstack.rst | 186 ++++++++++++++++++ doc/source/dev/dev-quickstart.rst | 148 ++------------- 7 files changed, 586 insertions(+), 130 deletions(-) create mode 100644 contrib/devstack/README.rst create mode 100644 contrib/devstack/extras.d/70-magnum.sh create mode 100644 contrib/devstack/lib/magnum create mode 100644 contrib/devstack/localrc.example create mode 100755 contrib/devstack/prepare_devstack.sh create mode 100644 doc/source/dev/dev-manual-devstack.rst diff --git a/contrib/devstack/README.rst b/contrib/devstack/README.rst new file mode 100644 index 0000000000..77d543cf12 --- /dev/null +++ b/contrib/devstack/README.rst @@ -0,0 +1,28 @@ +==================== +Devstack Integration +==================== + +This directory contains the files necessary to integrate Magnum with devstack. + +Refer the quickstart guide for more information on using devstack and magnum. + +Running devestack with magnum for the first time may take a long time as it +needs to download an atomic fedora 21 qcow image. If you already have this image +you can copy it to /opt/stack/devstack/files/fedora-21-atomic.qcow2 to save you +this time. + +To install magnum into devstack: :: + + git clone https://git.openstack.org/stackforge/magnum /opt/stack/magnum + git clone https://git.openstack.org/openstack-dev/devstack /opt/stack/devstack + + # copy example localrc, modify as necessary + cp /opt/stack/magnum/contrib/devstack/localrc.example /opt/stack/devstack/localrc + + cd /opt/stack/magnum + ./contrib/devstack/prepare_devstack.sh + +Run devstack as normal: :: + + cd /opt/stack/magnum + ./stack.sh diff --git a/contrib/devstack/extras.d/70-magnum.sh b/contrib/devstack/extras.d/70-magnum.sh new file mode 100644 index 0000000000..c0f5ee736b --- /dev/null +++ b/contrib/devstack/extras.d/70-magnum.sh @@ -0,0 +1,45 @@ +# magnum.sh - Devstack extras script to install magnum + +if is_service_enabled m-api m-cond; then + if [[ "$1" == "source" ]]; then + # Initial source + source $TOP_DIR/lib/magnum + elif [[ "$1" == "stack" && "$2" == "install" ]]; then + echo_summary "Installing magnum" + install_magnum + + # add image to glance + if [[ "$ENABLED_SERVICES" =~ 'm-api' ]]; then + MANGUM_GUEST_IMAGE_URL=${MANGUM_GUEST_IMAGE_URL:-"https://fedorapeople.org/groups/heat/kolla/fedora-21-atomic.qcow2"} + IMAGE_URLS+=",${MANGUM_GUEST_IMAGE_URL}" + fi + + LIBS_FROM_GIT="${LIBS_FROM_GIT},python-magnumclient" + + install_magnumclient + cleanup_magnum + elif [[ "$1" == "stack" && "$2" == "post-config" ]]; then + echo_summary "Configuring magnum" + configure_magnum + + if is_service_enabled key; then + create_magnum_accounts + fi + + elif [[ "$1" == "stack" && "$2" == "extra" ]]; then + # Initialize magnum + init_magnum + + # Start the magnum API and magnum taskmgr components + echo_summary "Starting magnum" + start_magnum + fi + + if [[ "$1" == "unstack" ]]; then + stop_magnum + fi + + if [[ "$1" == "clean" ]]; then + cleanup_magnum + fi +fi diff --git a/contrib/devstack/lib/magnum b/contrib/devstack/lib/magnum new file mode 100644 index 0000000000..8b911b1af8 --- /dev/null +++ b/contrib/devstack/lib/magnum @@ -0,0 +1,251 @@ +#!/bin/bash +# +# lib/magnum +# Functions to control the configuration and operation of the **magnum** service + +# Dependencies: +# +# - ``functions`` file +# - ``DEST``, ``DATA_DIR``, ``STACK_USER`` must be defined +# - ``SERVICE_{TENANT_NAME|PASSWORD}`` must be defined + +# ``stack.sh`` calls the entry points in this order: +# +# - install_magnum +# - configure_magnum +# - create_magnum_conf +# - init_magnum +# - start_magnum +# - stop_magnum +# - cleanup_magnum + +# Save trace setting +XTRACE=$(set +o | grep xtrace) +set +o xtrace + + +# Defaults +# -------- + +# Set up default directories +MAGNUM_REPO=${MAGNUM_REPO:-${GIT_BASE}/stackforge/magnum.git} +MAGNUM_BRANCH=${MAGNUM_BRANCH:-master} +MAGNUM_DIR=$DEST/magnum + +GITREPO["python-magnumclient"]=${MAGNUMCLIENT_REPO:-${GIT_BASE}/stackforge/python-magnumclient.git} +GITBRANCH["python-magnumclient"]=${MAGNUMCLIENT_BRANCH:-master} +GITDIR["python-magnumclient"]=$DEST/python-magnumclient + +MAGNUM_STATE_PATH=${MAGNUM_STATE_PATH:=$DATA_DIR/magnum} +MAGNUM_AUTH_CACHE_DIR=${MAGNUM_AUTH_CACHE_DIR:-/var/cache/magnum} + +MAGNUM_CONF_DIR=/etc/magnum +MAGNUM_CONF=$MAGNUM_CONF_DIR/magnum.conf + +if is_ssl_enabled_service "magnum" || is_service_enabled tls-proxy; then + MAGNUM_SERVICE_PROTOCOL="https" +fi + +# Public facing bits +MAGNUM_SERVICE_HOST=${MAGNUM_SERVICE_HOST:-$SERVICE_HOST} +MAGNUM_SERVICE_PORT=${MAGNUM_SERVICE_PORT:-9511} +MAGNUM_SERVICE_PORT_INT=${MAGNUM_SERVICE_PORT_INT:-19511} +MAGNUM_SERVICE_PROTOCOL=${MAGNUM_SERVICE_PROTOCOL:-$SERVICE_PROTOCOL} + +# Support entry points installation of console scripts +if [[ -d $MAGNUM_DIR/bin ]]; then + MAGNUM_BIN_DIR=$MAGNUM_DIR/bin +else + MAGNUM_BIN_DIR=$(get_python_exec_prefix) +fi + +# Functions +# --------- + +# Test if any magnum services are enabled +# is_magnum_enabled +function is_magnum_enabled { + [[ ,${ENABLED_SERVICES} =~ ,"m-" ]] && return 0 + return 1 +} +# cleanup_magnum() - Remove residual data files, anything left over from previous +# runs that a clean run would need to clean up +function cleanup_magnum { + sudo rm -rf $MAGNUM_STATE_PATH $MAGNUM_AUTH_CACHE_DIR +} + +# configure_magnum() - Set config files, create data dirs, etc +function configure_magnum { + # Put config files in ``/etc/magnum`` for everyone to find + if [[ ! -d $MAGNUM_CONF_DIR ]]; then + sudo mkdir -p $MAGNUM_CONF_DIR + sudo chown $STACK_USER $MAGNUM_CONF_DIR + fi + + # Rebuild the config file from scratch + create_magnum_conf + +} + +# create_magnum_accounts() - Set up common required magnum accounts +# +# Project User Roles +# ------------------------------------------------------------------ +# SERVICE_TENANT_NAME magnum service +function create_magnum_accounts { + + create_service_user "magnum" "admin" + + if [[ "$KEYSTONE_CATALOG_BACKEND" = 'sql' ]]; then + + local magnum_service=$(get_or_create_service "magnum" \ + "container" "Magnum Container Service") + get_or_create_endpoint $magnum_service \ + "$REGION_NAME" \ + "$MAGNUM_SERVICE_PROTOCOL://$MAGNUM_SERVICE_HOST:$MAGNUM_SERVICE_PORT/v1" \ + "$MAGNUM_SERVICE_PROTOCOL://$MAGNUM_SERVICE_HOST:$MAGNUM_SERVICE_PORT/v1" \ + "$MAGNUM_SERVICE_PROTOCOL://$MAGNUM_SERVICE_HOST:$MAGNUM_SERVICE_PORT/v1" + fi + +} + +# create_magnum_conf() - Create a new magnum.conf file +function create_magnum_conf { + + # (Re)create ``magnum.conf`` + rm -f $MAGNUM_CONF + iniset $MAGNUM_CONF DEFAULT verbose "True" + iniset $MAGNUM_CONF DEFAULT debug "$ENABLE_DEBUG_LOG_LEVEL" + iniset $MAGNUM_CONF DEFAULT rabbit_userid $RABBIT_USERID + iniset $MAGNUM_CONF DEFAULT rabbit_password $RABBIT_PASSWORD + iniset $MAGNUM_CONF DEFAULT rabbit_host $RABBIT_HOST + + iniset $MAGNUM_CONF database connection `database_connection_url magnum` + iniset $MAGNUM_CONF api host "$MAGNUM_SERVICE_HOST" + iniset $MAGNUM_CONF api port "$MAGNUM_SERVICE_PORT" + iniset $MAGNUM_CONF conductor host "$MAGNUM_SERVICE_HOST" + + configure_auth_token_middleware $MAGNUM_CONF magnum $MAGNUM_AUTH_CACHE_DIR + + if is_fedora || is_suse; then + # magnum defaults to /usr/local/bin, but fedora and suse pip like to + # install things in /usr/bin + iniset $MAGNUM_CONF DEFAULT bindir "/usr/bin" + fi + + if [ -n "$MAGNUM_STATE_PATH" ]; then + iniset $MAGNUM_CONF DEFAULT state_path "$MAGNUM_STATE_PATH" + iniset $MAGNUM_CONF DEFAULT lock_path "$MAGNUM_STATE_PATH" + fi + + if [ "$SYSLOG" != "False" ]; then + iniset $MAGNUM_CONF DEFAULT use_syslog "True" + fi + + # Format logging + if [ "$LOG_COLOR" == "True" ] && [ "$SYSLOG" == "False" ]; then + setup_colorized_logging $MAGNUM_CONF DEFAULT + else + # Show user_name and project_name instead of user_id and project_id + iniset $MAGNUM_CONF DEFAULT logging_context_format_string "%(asctime)s.%(msecs)03d %(levelname)s %(name)s [%(request_id)s %(user_name)s %(project_name)s] %(instance)s%(message)s" + fi + + # Register SSL certificates if provided + if is_ssl_enabled_service magnum; then + ensure_certificates MAGNUM + + iniset $MAGNUM_CONF DEFAULT ssl_cert_file "$MAGNUM_SSL_CERT" + iniset $MAGNUM_CONF DEFAULT ssl_key_file "$MAGNUM_SSL_KEY" + + iniset $MAGNUM_CONF DEFAULT enabled_ssl_apis "$MAGNUM_ENABLED_APIS" + fi +} + +function create_magnum_conf_magnum_network { + iniset $MAGNUM_CONF DEFAULT network_manager "magnum.network.manager.$NETWORK_MANAGER" + iniset $MAGNUM_CONF DEFAULT public_interface "$PUBLIC_INTERFACE" + iniset $MAGNUM_CONF DEFAULT vlan_interface "$VLAN_INTERFACE" + iniset $MAGNUM_CONF DEFAULT flat_network_bridge "$FLAT_NETWORK_BRIDGE" + if [ -n "$FLAT_INTERFACE" ]; then + iniset $MAGNUM_CONF DEFAULT flat_interface "$FLAT_INTERFACE" + fi +} + +# create_magnum_cache_dir() - Part of the init_magnum() process +function create_magnum_cache_dir { + # Create cache dir + sudo mkdir -p $MAGNUM_AUTH_CACHE_DIR + sudo chown $STACK_USER $MAGNUM_AUTH_CACHE_DIR + rm -f $MAGNUM_AUTH_CACHE_DIR/* +} + + +# init_magnum() - Initialize databases, etc. +function init_magnum { + # Only do this step once on the API node for an entire cluster. + if is_service_enabled $DATABASE_BACKENDS && is_service_enabled m-api; then + # (Re)create magnum database + recreate_database magnum + + # Migrate magnum database + $MAGNUM_BIN_DIR/magnum-db-manage upgrade + fi + create_magnum_cache_dir +} + +# install_magnumclient() - Collect source and prepare +function install_magnumclient { + if use_library_from_git "python-magnumclient"; then + git_clone_by_name "python-magnumclient" + setup_dev_lib "python-magnumclient" + fi +} + +# install_magnum() - Collect source and prepare +function install_magnum { + git_clone $MAGNUM_REPO $MAGNUM_DIR $MAGNUM_BRANCH + setup_develop $MAGNUM_DIR +} + +# start_magnum_api() - Start the API process ahead of other things +function start_magnum_api { + # Get right service port for testing + local service_port=$MAGNUM_SERVICE_PORT + local service_protocol=$MAGNUM_SERVICE_PROTOCOL + if is_service_enabled tls-proxy; then + service_port=$MAGNUM_SERVICE_PORT_INT + service_protocol="http" + fi + + run_process m-api "$MAGNUM_BIN_DIR/magnum-api" + echo "Waiting for magnum-api to start..." + if ! wait_for_service $SERVICE_TIMEOUT $service_protocol://$SERVICE_HOST:$service_port; then + die $LINENO "magnum-api did not start" + fi + + # Start proxies if enabled + if is_service_enabled tls-proxy; then + start_tls_proxy '*' $MAGNUM_SERVICE_PORT $MAGNUM_SERVICE_HOST $MAGNUM_SERVICE_PORT_INT & + start_tls_proxy '*' $EC2_SERVICE_PORT $MAGNUM_SERVICE_HOST $EC2_SERVICE_PORT_INT & + fi +} + + +# start_magnum() - Start running processes, including screen +function start_magnum { + + # ``run_process`` checks ``is_service_enabled``, it is not needed here + start_magnum_api + run_process m-cond "$MAGNUM_BIN_DIR/magnum-conductor" +} + +# stop_magnum() - Stop running processes (non-screen) +function stop_magnum { + for serv in m-api m-cond; do + stop_process $serv + done +} + + +# Restore xtrace +$XTRACE diff --git a/contrib/devstack/localrc.example b/contrib/devstack/localrc.example new file mode 100644 index 0000000000..5506519bd2 --- /dev/null +++ b/contrib/devstack/localrc.example @@ -0,0 +1,44 @@ +# Modify to your environment +FLOATING_RANGE=192.168.1.224/27 +PUBLIC_NETWORK_GATEWAY=192.168.1.225 +PUBLIC_INTERFACE=em1 + +# Credentials +ADMIN_PASSWORD=password +DATABASE_PASSWORD=password +RABBIT_PASSWORD=password +SERVICE_PASSWORD=password +SERVICE_TOKEN=password + +enable_service rabbit + +# Enable Neutron which is required by Magnum and disable nova-network. + +enable_service magnum +enable_service m-cond +enable_service m-api + +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 + +enable_service magnum +enable_service m-api +enable_service m-cond + +FIXED_RANGE=10.0.0.0/24 + +Q_USE_SECGROUP=True +ENABLE_TENANT_VLANS=True +TENANT_VLAN_RANGE= + +PHYSICAL_NETWORK=public +OVS_PHYSICAL_BRIDGE=br-ex + +# Log all output to files +LOGFILE=$HOME/devstack.log +SCREEN_LOGDIR=$HOME/logs diff --git a/contrib/devstack/prepare_devstack.sh b/contrib/devstack/prepare_devstack.sh new file mode 100755 index 0000000000..0a699497b8 --- /dev/null +++ b/contrib/devstack/prepare_devstack.sh @@ -0,0 +1,14 @@ +#!/bin/sh + +set -eux + +MAGNUM_DIR=$(readlink -f $(dirname $0)/../..) +INSTALL_DIR=${INSTALL_DIR:-/opt/stack} + +cp ${MAGNUM_DIR}/contrib/devstack/lib/magnum ${INSTALL_DIR}/devstack/lib +cp ${MAGNUM_DIR}/contrib/devstack/extras.d/70-magnum.sh ${INSTALL_DIR}/devstack/extras.d + +# Add magnum specific requirements to global requirements +git clone https://git.openstack.org/openstack/requirements ${INSTALL_DIR}/requirements || true +echo "python-kubernetes>=0.2" >> ${INSTALL_DIR}/requirements/global-requirements.txt +echo "docker-py>=0.5.1" >> ${INSTALL_DIR}/requirements/global-requirements.txt diff --git a/doc/source/dev/dev-manual-devstack.rst b/doc/source/dev/dev-manual-devstack.rst new file mode 100644 index 0000000000..fa45fb1ab5 --- /dev/null +++ b/doc/source/dev/dev-manual-devstack.rst @@ -0,0 +1,186 @@ +.. _dev-quickstart: + +Manually Adding Magnum to DevStack +================================== + +If you are getting started with Magnum it is recommended you follow the +`dev quickstart guide <./dev-quickstart.rst>` to get up and running with +Magnum. This guide covers a more in-depth process to setup Magnum with devstack. + +DevStack does not yet have Magnum support. It is, however, necessary to +develop Magnum from a devstack environment at the present time. Magnum depends +on Nova, Heat, and Neutron to create and schedule virtual machines to simulate +bare-metal. For milestone #2 we intend to introduce support for Ironic +deployment of baremetal nodes. + +This session has only been tested on Ubuntu 14.04 (Trusty) and Fedora 21. +We recommend users to select one of them if it is possible. + +NB: Magnum depends on a command line tool in kubernetes called kubectl +to execute its operations with Kubernetes. We are addressing this in milestone +#2 by implementing a native ReST client for Kubernetes. In the meantime, the +required action is to install kubectl manually. + +Install binary distribution of kubectl distributed by Google:: + + wget https://github.com/GoogleCloudPlatform/kubernetes/releases/download/v0.11.0/kubernetes.tar.gz + tar -xzvf kubernetes.tar.gz + sudo cp -a kubernetes/platforms/linux/amd64/kubectl /usr/bin/kubectl + +Clone DevStack:: + + cd ~ + git clone https://github.com/openstack-dev/devstack.git devstack + +Create devstack/localrc with minimal settings required to enable Heat +and Neutron, refer to http://docs.openstack.org/developer/devstack/guides/neutron.html +for more detailed neutron configuration.:: + + cd devstack + cat >localrc <`. diff --git a/doc/source/dev/dev-quickstart.rst b/doc/source/dev/dev-quickstart.rst index 617052c381..c16ce20bd7 100644 --- a/doc/source/dev/dev-quickstart.rst +++ b/doc/source/dev/dev-quickstart.rst @@ -115,158 +115,46 @@ Install binary distribution of kubectl distributed by Google:: Clone DevStack:: - cd ~ - git clone https://github.com/openstack-dev/devstack.git devstack + # Create dir to run devstack from, if not done so already + sudo mkdir -p /opt/stack + sudo chown $USER /opt/stack -Create devstack/localrc with minimal settings required to enable Heat + git clone https://github.com/openstack-dev/devstack.git /opt/stack/devstack + git clone https://github.com/stackforge/magnum /opt/stack/magnum + +Copy devstack/localrc with minimal settings required to enable Heat and Neutron, refer to http://docs.openstack.org/developer/devstack/guides/neutron.html -for more detailed neutron configuration.:: +for more detailed neutron configuration. - cd devstack - cat >localrc <