developing-service.md

Developing a new Composable Service with Tripleo-Quicstart

In order to develop a new composable service for Tripleo, you need to:

• Develop the new Heat templates
• Ensure any required software is packaged
• Develop appropriate Puppet modules for installing/configuring the packages
• Deploy an undercloud using your new Heat templates
• Deploy an overcloud with your new Puppet modules and any required packages installed.

This guide will help you use tripleo-quickstart to perform these steps.

Setting up the undercloud

We'll use tripleo-quickstart to bring up the undercloud and create (but not start) the virtual overcloud hosts. The quickstart scripts already know how to fetch tripleo-heat-templates from a git repository.

Place the following configuration into a file named servicedev.yml:

# skip introspection (unnecessary in a virtual environment)
step_introspect: false

# clone tripleo-heat-templates from this repository...
overcloud_templates_repo: https://git.openstack.org/openstack/tripleo-heat-templates
# ...into this repository...
overcloud_templates_path: tripleo-heat-templates
# ...and check out this review.
overcloud_templates_refspec: refs/changes/88/254788/24

This above configuration, when passed to the quickstart, will clone the tripelo-heat-templates repository into the tripleo-heat-templates directory of the stack user on the undercloud, and will then fetch the specified Gerrit review.

You can get the appropriate value for overcloud_templates_ref from the "Download" link on the Gerrit review page.

If instead you wanted to test changes from a GitHub repository, you might do something like this instead:

# clone tripleo-heat-templates from this repository...
overcloud_templates_repo: https://github.com/larsks/tripleo-heat-templates
# ...into this repository...
overcloud_templates_path: tripleo-heat-templates
# ...and check out this branch.
overcloud_templates_branch: feature/fluentd

Run the quickstart like this:

./quickstart.sh -T all -n \
  -e @config/general_config/devmode.yml \
  -e @config/release/master-tripleo.yml \
  -e @servicedev.yml virthost

(Where virthost is the name of the physical host that will be hosting your virtual environment.)

This enables developer mode (the quickstart won't try to fetch new images if you already have them locally and uses delorean "current" delorean repositories), and uses "current" undercloud/overcloud images.

When the quickstart completes, you will have a functioning undercloud with the tripleo-heat-templates checked out in the home directory of the stack user. At this point, you can log into the undercloud like this:

ssh -F ~/.quickstart/ssh.config.ansible undercloud

Modifying the overcloud images

You may need to install additional packages inside the overcloud images, and you will also need to update the tripleo puppet modules contained in the overcloud image. This is easiest if you first install the virt-customize tool on the undercloud:

sudo yum -y install /usr/bin/virt-customize

And then use the following script as a model to perform the image customization:

#!/bin/sh

LIBGUESTFS_BACKEND=direct
PACKAGES=sensu,fluentd

# in this example, we'll fetch a gerrit review of
# puppet-tripleo
PUPPET_GERRIT_REF=refs/changes/03/323303/18

export LIBGUESTFS_BACKEND

cat > centos-opstools.repo <<EOF
[centos-opstools]
name=CentOS-7 - OpsTools
baseurl=https://cbs.centos.org/repos/cloud7-openstack-optools-candidate/x86_64/os/
gpgcheck=0
enabled=1
EOF

cat > update-puppet <<EOF
#!/bin/sh
set -e

# git is unhappy running under virt-customize without this.
# (https://bugzilla.redhat.com/show_bug.cgi?id=1306557)
exec </dev/null

cd /usr/share/openstack-puppet/modules
rm -rf tripleo
git clone https://git.openstack.org/openstack/puppet-tripleo tripleo
EOF

if [ -n "$PUPPET_GERRIT_REF" ]; then
cat >> update-puppet <<EOF
cd /usr/share/openstack-puppet/modules/tripleo
git fetch https://git.openstack.org/openstack/puppet-tripleo $PUPPET_GERRIT_REF &&
  git checkout FETCH_HEAD
EOF
fi

# upload the repository configuration, git script, and a resolver
# configuration; install some packages; run the git script
virt-customize -a overcloud-full.qcow2 \
  --upload centos-opstools.repo:/etc/yum.repos.d/centos-opstools.repo \
  --upload update-puppet:/root/update-puppet \
  --upload /etc/resolv.conf:/etc/resolv.conf \
  --install $PACKAGES \
  --run-command "sh /root/update-puppet"

Running the script will result in output along the lines of:

[   0.0] Examining the guest ...
[  12.0] Setting a random seed
[  12.0] Uploading: centos-opstools.repo to /etc/yum.repos.d/centos-opstools.repo
[  12.0] Uploading: update-puppet to /root/update-puppet
[  12.0] Uploading: /etc/resolv.conf to /etc/resolv.conf
[  12.0] Installing packages: sensu fluentd
[  43.0] Running: sh /root/update-puppet
[  50.0] Finishing off

When the script has finished, you need to upload the update image to the undercloud Glance instance:

openstack overcloud image upload --update-existing

Deploying the overcloud

The easiest way to deploy the overcloud is to run the overcloud-deploy.sh script placed in the stack user home directory:

sh overcloud-deploy.sh

When configuring your new composable service, you will probably need to add an additional environment file using the -e command line option. For example:

sh overcloud-deploy.sh -e my-custom-environment.yml