Chapter 15. Customization

To run DevStack for the stable Havana branch on an instance in your OpenStack cloud:

1. Boot an instance from the dashboard or the nova command-line interface (CLI) with the following parameters.

   • Name: devstack-havana

   • Image: Ubuntu 12.04 LTS

   • Memory Size: 4 GB RAM

   • Disk Size: minimum 5 GB

   If you are using the nova client, specify --flavor 3 for the nova boot command to get adequate memory and disk sizes.

2. Log in and set up DevStack. Here's an example of the commands you can use to set up DevStack on a virtual machine.

   1. Log in to the instance.

      $ ssh username@my.instance.ip.address

   2. Update the virtual machine's operating system.

      # apt-get -y update

   3. Install git.

      # apt-get -y install git

   4. Clone the stable/havana branch of the devstack repository.

      $ git clone https://github.com/openstack-dev/devstack.git -b stable/havana devstack/

   5. Change to the devstack repository.

      $ cd devstack

3. (Optional) If you've logged in to your instance as the root user, you must create a "stack" user, otherwise you'll run into permission issues. If you've logged in as a user other than root, you can skip these steps.

   1. Run the DevStack script to create the stack user.

      # tools/create-stack-user.sh

   2. Give ownership of the devstack directory to the stack user.

      # chown -R stack:stack /root/devstack

   3. Set some permissions you can use to view the DevStack screen later.

      # chmod o+rwx /dev/pts/0

   4. Switch to the stack user.

      $ su stack

4. Edit the localrc configuration file that controls what DevStack will deploy. Copy the example localrc file at the end of this section. (See Example 15.1, “localrc”.)

   $ vim localrc

5. Run the stack script that will install OpenStack.

   $ ./stack.sh

6. When the stack script is done, you can open the screen session it started to view all of the running OpenStack services.

   $ screen -r stack

7. Press Ctrl+A followed by 0 to go to the first screen window.

To create the middleware and plug it in through Paste configuration:

All of the code for OpenStack lives in /opt/stack. Go to the swift directory in the shell screen and edit your middleware module.

1. Change to the directory where Object Storage is installed.

   $ cd /opt/stack/swift

2. Create the ip_whitelist.py Python source code file.

   $ vim swift/common/middleware/ip_whitelist.py

3. Copy the code in Example 15.2, “ip_whitelist.py” into ip_whitelist.py. The following code is a middleware example that restricts access to a container based on IP address as explained at the beginning of the section. Middleware passes the request on to another application. This example uses the swift "swob" library to wrap Web Server Gateway Interface (WSGI) requests and responses into objects for swift to interact with. When you're done, save and close the file.

    

   Example 15.2. ip_whitelist.py

   # vim: tabstop=4 shiftwidth=4 softtabstop=4
   # Copyright (c) 2014 OpenStack Foundation
   # All Rights Reserved.
   #
   #    Licensed under the Apache License, Version 2.0 (the "License"); you may
   #    not use this file except in compliance with the License. You may obtain
   #    a copy of the License at
   #
   #         http://www.apache.org/licenses/LICENSE-2.0
   #
   #    Unless required by applicable law or agreed to in writing, software
   #    distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
   #    WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
   #    License for the specific language governing permissions and limitations
   #    under the License.
   
   import socket
   
   from swift.common.utils import get_logger
   from swift.proxy.controllers.base import get_container_info
   from swift.common.swob import Request, Response
   
   class IPWhitelistMiddleware(object):
       """
       IP Whitelist Middleware
   
       Middleware that allows access to a container from only a set of IP
       addresses as determined by the container's metadata items that start
       with the prefix 'allow'. E.G. allow-dev=192.168.0.20
       """
   
       def __init__(self, app, conf, logger=None):
           self.app = app
   
           if logger:
               self.logger = logger
           else:
               self.logger = get_logger(conf, log_route='ip_whitelist')
   
           self.deny_message = conf.get('deny_message', "IP Denied")
           self.local_ip = socket.gethostbyname(socket.gethostname())
   
       def __call__(self, env, start_response):
           """
           WSGI entry point.
           Wraps env in swob.Request object and passes it down.
   
           :param env: WSGI environment dictionary
           :param start_response: WSGI callable
           """
           req = Request(env)
   
           try:
               version, account, container, obj = req.split_path(1, 4, True)
           except ValueError:
               return self.app(env, start_response)
   
           container_info = get_container_info(
               req.environ, self.app, swift_source='IPWhitelistMiddleware')
   
           remote_ip = env['REMOTE_ADDR']
           self.logger.debug("Remote IP: %(remote_ip)s",
                             {'remote_ip': remote_ip})
   
           meta = container_info['meta']
           allow = {k:v for k,v in meta.iteritems() if k.startswith('allow')}
           allow_ips = set(allow.values())
           allow_ips.add(self.local_ip)
           self.logger.debug("Allow IPs: %(allow_ips)s",
                             {'allow_ips': allow_ips})
   
           if remote_ip in allow_ips:
               return self.app(env, start_response)
           else:
               self.logger.debug(
                   "IP %(remote_ip)s denied access to Account=%(account)s "
                   "Container=%(container)s. Not in %(allow_ips)s", locals())
               return Response(
                   status=403,
                   body=self.deny_message,
                   request=req)(env, start_response)
   
   
   def filter_factory(global_conf, **local_conf):
       """
       paste.deploy app factory for creating WSGI proxy apps.
       """
       conf = global_conf.copy()
       conf.update(local_conf)
   
       def ip_whitelist(app):
           return IPWhitelistMiddleware(app, conf)
       return ip_whitelist

   
   

   There is a lot of useful information in env and conf that you can use to decide what to do with the request. To find out more about what properties are available, you can insert the following log statement into the __init__ method

   self.logger.debug("conf = %(conf)s", locals())

   and the following log statement into the __call__ method

   self.logger.debug("env = %(env)s", locals())

4. To plug this middleware into the swift Paste pipeline, you edit one configuration file, /etc/swift/proxy-server.conf.

   $ vim /etc/swift/proxy-server.conf

5. Find the [filter:ratelimit] section in /etc/swift/proxy-server.conf, and copy in the following configuration section after it.

   [filter:ip_whitelist]
   paste.filter_factory = swift.common.middleware.ip_whitelist:filter_factory
   # You can override the default log routing for this filter here:
   # set log_name = ratelimit
   # set log_facility = LOG_LOCAL0
   # set log_level = INFO
   # set log_headers = False
   # set log_address = /dev/log
   deny_message = You shall not pass!

6. Find the [pipeline:main] section in /etc/swift/proxy-server.conf, and add ip_whitelist after ratelimit to the list like so. When you're done, save and close the file.

   [pipeline:main]
   pipeline = catch_errors healthcheck proxy-logging cache bulk slo ratelimit ip_whitelist ...

7. Restart the Swift Proxy service to make swift use your middleware. Start by switching to the swift-proxy screen.

   1. Press Ctrl+A followed by 3.

   2. Press Ctrl+C to kill the service.

   3. Press Up Arrow to bring up the last command.

   4. Press Enter to run it.

8. Test your middleware with the swift CLI. Start by switching to the shell screen and finish by switching back to the swift-proxy screen to check the log output.

   1. Press Ctrl+A followed by 0.

   2. Make sure you're in the devstack directory.

      $ cd /root/devstack

   3. Source openrc to set up your environment variables for the CLI.

      $ source openrc

   4. Create a container called middleware-test.

      $ swift post middleware-test

   5. Press Ctrl+A followed by 3 to check the log output.

9. Among the log statements you'll see the lines.

   proxy-server Remote IP: my.instance.ip.address (txn: ...)
   proxy-server Allow IPs: set(['my.instance.ip.address']) (txn: ...)

   These two statements are produced by our middleware and show that the request was sent from our DevStack instance and was allowed.

10.  

    Test the middleware from outside DevStack on a remote machine that has access to your DevStack instance.

    1. Install the keystone and swift clients on your local machine.

       # pip install python-keystoneclient python-swiftclient

    2. Attempt to list the objects in the middleware-test container.

       $ swift --os-auth-url=http://my.instance.ip.address:5000/v2.0/ --os-region-name=RegionOne --os-username=demo:demo --os-password=devstack list middleware-test
       Container GET failed: http://my.instance.ip.address:8080/v1/AUTH_.../middleware-test?format=json 403 Forbidden   You shall not pass!

11. Press Ctrl+A followed by 3 to check the log output. Look at the swift log statements again, and among the log statements you'll see the lines:

    proxy-server Authorizing from an overriding middleware (i.e: tempurl) (txn: ...)
    proxy-server ... IPWhitelistMiddleware
    proxy-server Remote IP: my.local.ip.address (txn: ...)
    proxy-server Allow IPs: set(['my.instance.ip.address']) (txn: ...)
    proxy-server IP my.local.ip.address denied access to Account=AUTH_... Container=None. Not in set(['my.instance.ip.address']) (txn: ...)

    Here we can see that the request was denied because the remote IP address wasn't in the set of allowed IPs.

12. Back in your DevStack instance on the shell screen, add some metadata to your container to allow the request from the remote machine.

    1. Press Ctrl+A followed by 0.

    2. Add metadata to the container to allow the IP.

       $ swift post --meta allow-dev:my.local.ip.address middleware-test

    3. Now try the command from Step 10 again and it succeeds. There are no objects in the container, so there is nothing to list, however there is also no error to report.

To create the scheduler and plug it in through configuration:

1. The code for OpenStack lives in /opt/stack, so go to the nova directory and edit your scheduler module. Change to the directory where nova is installed:

   $ cd /opt/stack/nova

2. Create the ip_scheduler.py Python source code file.

   $ vim nova/scheduler/ip_scheduler.py

3. The code in Example 15.3, “ip_scheduler.py” is a driver that will schedule servers to hosts based on IP address as explained at the beginning of the section. Copy the code into ip_scheduler.py. When you're done, save and close the file.

    

   Example 15.3. ip_scheduler.py

   # vim: tabstop=4 shiftwidth=4 softtabstop=4
   # Copyright (c) 2014 OpenStack Foundation
   # All Rights Reserved.
   #
   #    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.
   
   """
   IP Scheduler implementation
   """
   
   import random
   
   from oslo.config import cfg
   
   from nova.compute import rpcapi as compute_rpcapi
   from nova import exception
   from nova.openstack.common import log as logging
   from nova.openstack.common.gettextutils import _
   from nova.scheduler import driver
   
   CONF = cfg.CONF
   CONF.import_opt('compute_topic', 'nova.compute.rpcapi')
   LOG = logging.getLogger(__name__)
   
   class IPScheduler(driver.Scheduler):
       """
       Implements Scheduler as a random node selector based on
       IP address and hostname prefix.
       """
   
       def __init__(self, *args, **kwargs):
           super(IPScheduler, self).__init__(*args, **kwargs)
           self.compute_rpcapi = compute_rpcapi.ComputeAPI()
   
       def _filter_hosts(self, request_spec, hosts, filter_properties,
           hostname_prefix):
           """Filter a list of hosts based on hostname prefix."""
   
           hosts = [host for host in hosts if host.startswith(hostname_prefix)]
           return hosts
   
       def _schedule(self, context, topic, request_spec, filter_properties):
           """Picks a host that is up at random."""
   
           elevated = context.elevated()
           hosts = self.hosts_up(elevated, topic)
           if not hosts:
               msg = _("Is the appropriate service running?")
               raise exception.NoValidHost(reason=msg)
   
           remote_ip = context.remote_address
   
           if remote_ip.startswith('10.1'):
               hostname_prefix = 'doc'
           elif remote_ip.startswith('10.2'):
               hostname_prefix = 'ops'
           else:
               hostname_prefix = 'dev'
   
           hosts = self._filter_hosts(request_spec, hosts, filter_properties,
               hostname_prefix)
           if not hosts:
               msg = _("Could not find another compute")
               raise exception.NoValidHost(reason=msg)
   
           host = random.choice(hosts)
           LOG.debug("Request from %(remote_ip)s scheduled to %(host)s" % locals())
   
           return host
   
       def select_destinations(self, context, request_spec, filter_properties):
           """Selects random destinations."""
           num_instances = request_spec['num_instances']
           # NOTE(timello): Returns a list of dicts with 'host', 'nodename' and
           # 'limits' as keys for compatibility with filter_scheduler.
           dests = []
           for i in range(num_instances):
               host = self._schedule(context, CONF.compute_topic,
                       request_spec, filter_properties)
               host_state = dict(host=host, nodename=None, limits=None)
               dests.append(host_state)
   
           if len(dests) < num_instances:
               raise exception.NoValidHost(reason='')
           return dests
   
       def schedule_run_instance(self, context, request_spec,
                                 admin_password, injected_files,
                                 requested_networks, is_first_time,
                                 filter_properties, legacy_bdm_in_spec):
           """Create and run an instance or instances."""
           instance_uuids = request_spec.get('instance_uuids')
           for num, instance_uuid in enumerate(instance_uuids):
               request_spec['instance_properties']['launch_index'] = num
               try:
                   host = self._schedule(context, CONF.compute_topic,
                                         request_spec, filter_properties)
                   updated_instance = driver.instance_update_db(context,
                           instance_uuid)
                   self.compute_rpcapi.run_instance(context,
                           instance=updated_instance, host=host,
                           requested_networks=requested_networks,
                           injected_files=injected_files,
                           admin_password=admin_password,
                           is_first_time=is_first_time,
                           request_spec=request_spec,
                           filter_properties=filter_properties,
                           legacy_bdm_in_spec=legacy_bdm_in_spec)
               except Exception as ex:
                   # NOTE(vish): we don't reraise the exception here to make sure
                   #             that all instances in the request get set to
                   #             error properly
                   driver.handle_schedule_error(context, ex, instance_uuid,
                                                request_spec)

   
   

   There is a lot of useful information in context, request_spec, and filter_properties that you can use to decide where to schedule the instance. To find out more about what properties are available, you can insert the following log statements into the schedule_run_instance method of the scheduler above.

   LOG.debug("context = %(context)s" % {'context': context.__dict__})
   LOG.debug("request_spec = %(request_spec)s" % locals())
   LOG.debug("filter_properties = %(filter_properties)s" % locals())

4. To plug this scheduler into nova, edit one configuration file, /etc/nova/nova.conf.

   $ vim /etc/nova/nova.conf

5. Find the scheduler_driver config and change it like so.

   scheduler_driver=nova.scheduler.ip_scheduler.IPScheduler

6. Restart the nova scheduler service to make nova use your scheduler. Start by switching to the n-sch screen.

   1. Press Ctrl+A followed by 9.

   2. Press Ctrl+A followed by N until you reach the n-sch screen.

   3. Press Ctrl+C to kill the service.

   4. Press Up Arrow to bring up the last command.

   5. Press Enter to run it.

7. Test your scheduler with the nova CLI. Start by switching to the shell screen and finish by switching back to the n-sch screen to check the log output.

   1. Press Ctrl+A followed by 0.

   2. Make sure you're in the devstack directory.

      $ cd /root/devstack

   3. Source openrc to set up your environment variables for the CLI.

      $ source openrc

   4. Put the image ID for the only installed image into an environment variable.

      $ IMAGE_ID=`nova image-list | egrep cirros | egrep -v "kernel|ramdisk" | awk '{print $2}'`

   5. Boot a test server.

      $ nova boot --flavor 1 --image $IMAGE_ID scheduler-test

8. Switch back to the n-sch screen. Among the log statements, you'll see the line:

   2014-01-23 19:57:47.262 DEBUG nova.scheduler.ip_scheduler [req-... demo demo] Request from 162.242.221.84 scheduled to devstack-havana _schedule /opt/stack/nova/nova/scheduler/ip_scheduler.py:76