opendev
/
puppet-openstackci
Code Issues Proposed changes

Clarifications to the getting started notes in contrib/README 

The existing notes were very easy to follow. I especially appreciated the
step-by-step flow and inclusion of commands to run. As I followed the
documentation, I found a couple of typos and added a few clarifications.

Change-Id: I604679f70c2474a440befa44af15ac3cc6d18c08
This commit is contained in:
Dan Moravec 2015-12-03 13:21:49 -06:00
parent e50dc48645
commit 670300f842
1 changed files with 39 additions and 24 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

63
contrib/README.md
View File

@ -26,21 +26,21 @@ This CI solution uses a few open-source tools:
* [Jenkins Job Builder](http://docs.openstack.org/infra/system-config/jjb.html) - a tool to manage jenkins job definitions
* [os-loganalyze](http://git.openstack.org/cgit/openstack-infra/os-loganalyze/) - a tool to faciltate
* [os-loganalyze](http://git.openstack.org/cgit/openstack-infra/os-loganalyze/) - a tool to facilitate
browsing, sharing, and filtering log files by log level.
The follow steps will help you integrate and deploy the first 4 tools on a single
host. An initial system with 8GB RAM, 4CPUs, 80GB HD should be sufficient,
The following steps will help you integrate and deploy the first 4 tools on a single
node. An initial system with 8GB RAM, 4CPUs, 80GB HD should be sufficient,
running Ubuntu 14.04.
A second host will be used to store the log files and create a public log server to
host the static log files generated by jenkins jobs. This log server is an Apache
A second node will be used to store the log files and create a public log server to
host the static log files generated by jenkins jobs. This log server node is an Apache
server serving log files stored on disk or on a Swift service.
It is hosted on a seperate server because it usually
It is hosted on a separate node because it usually
needs to be publicly accessible to share job results whereas the rest of the CI
system can be located behind a firewall or within a VPN. At the end of a Jenkins Job,
`publishers` will scp log files from the jenkins slave to the log server or upload
`publishers` will scp log files from the jenkins slave to the log server node or upload
to the Swift Service.
The system requires two external resources:
@ -53,7 +53,7 @@ The system requires two external resources:
* A Gerrit server (for OpenStack users, this is provided to you at review.openstack.org)
Zuul will listen to the Gerrit even stream to decide which jobs to run when it receives
Zuul will listen to the Gerrit event stream to decide which jobs to run when it receives
a desired event. Zuul will also post a comment with results to this Gerrit with the
job results along with a link to the related log files.
@ -63,7 +63,7 @@ version to set up for those not familiar with puppet.
## Install and Configure Puppet
On each host, you will need to install and configure puppet.
On each node, you will need to install and configure puppet.
### Install Puppet
@ -81,7 +81,6 @@ You can get the latest version of the puppet modules needed using this script.
git clone https://git.openstack.org/openstack-infra/system-config
cd system-config
sudo ./install_modules.sh
cd ..
This script will install all the puppet modules used by upstream to
`/etc/puppet/modules`. In many cases, these are git cloned, and running
@ -90,18 +89,24 @@ This script uses `modules.env` as its configuration input.
### Configure Masterless Puppet
First, it is useful to save the history, so set up a git repo as root user:
The instructions in this section apply to both the single-node CI server node as
well as the log server node.
First, it is useful to save the history, so set up a
git repo as root user:
sudo su -
cd /etc/puppet
git init
exit
You will be configuring 3 puppet files. The first is `site.pp` which is the top
level entry point for puppet to start managing the node. The second is a `hiera.yaml`
which configures Puppet Hiera to store local configurations and secrets
such as passwords and private keys, and finaly some `yaml` files which store the
such as passwords and private keys, and finally some `yaml` files which store the
actual configurations and secrets.
First, set up these 3 files by starting with the samples provided. For each host,
First, set up these 3 files by starting with the samples provided. For each node,
select the corresponding `single_node_ci*` or `log_server*` files.
cp /etc/puppet/modules/openstackci/contrib/hiera.yaml /etc/puppet
@ -121,14 +126,23 @@ documentation described in `../manifests/single_node_ci.pp` or
the top level puppet class that is used in `site.pp`).
Once completed, you should commit these 3 files to the `/etc/puppet` git repo.
Your git workflow may vary a bit, but here is an example:
# Setup the log server
sudo su -
cd /etc/puppet
git checkout -b setup
git add environments/common.yaml
# repeat for other modified files
git commit -a -m 'initial setup'
exit
Setup the log server first, because it is simpler, and its FQDN (or IP address)
will be needed when setting up the CI server.
# Set up the log server
Set up the log server node first as it is simpler to configure. Besides, its FQDN
(or IP address) is needed to set up the CI server node.
While setting up jenkins_ssh_public_key in `common.yaml` it is important that
the same ssh key pair is used when setting up the CI server in the next step.
the same ssh key pair is used when setting up the CI server node in the next step.
This is the ssh key that Jenkins will use to scp files.
At this point you are ready to invoke Puppet for the first time. Puppet needs to
@ -138,11 +152,12 @@ be run as root.
You can simulate a jenkins file upload using:
scp -i $JENKINS_SSH_PUBLIC_KEY -o StrictHostKeyChecking=no $your-log-file jenkins@<fqdn_or_ip>:/srv/static/logs/
scp -i $JENKINS_SSH_PRIVATE_KEY_FILE -o StrictHostKeyChecking=no $your-log-file jenkins@<fqdn_or_ip>:/srv/static/logs/
You should now be able to see the file you uploaded at `http://<fqnd_or_ip>/$your-log-file`
# Setup the CI server
# Set up the CI server
Follow the steps above to install and configure puppet on the CI server node.
## Create an Initial 'project-config' Repository
@ -156,8 +171,8 @@ The second is project configuration, which includes the configuration files
that the services use to perform the desired project-specific operations.
The instructions provided here are mainly focused on the system configuration aspect.
However, they need an initial set of project configurations in order to work. These
project configurations are provided via a git URL to a `project-config` repository.
However, system configuration requires an initial set of project configurations in order
to work. These project configurations are provided via a git URL to a `project-config` repository.
Before moving on, create an initial `project-config` repository. You can start with this
[project-config-example](https://git.openstack.org/cgit/openstack-infra/project-config-example/)
following the instructions provided in its README.md. While tailored for OpenStack users,
@ -229,8 +244,8 @@ You can view the log files for any errors:
view /var/log/zuul/zuul.log
Most zuul files are located in either. They should not need to be modified directly, but
are useful to help identify root causes:
Most zuul files are located in either of the following directories. They should not need
to be modified directly, but are useful to help identify root causes:
/var/lib/zuul
/etc/zuul
@ -257,7 +272,7 @@ If you run into issues building the image, the [documentation provided
here can help you debug](https://git.openstack.org/cgit/openstack-infra/project-config/tree/nodepool/elements/README.rst)
After you have sucessfully built an image, manually upload it to the provider to ensure
After you have successfully built an image, manually upload it to the provider to ensure
provider authentication and image uploading work:
nodepool image-upload all <image-name>