8eb74b0509
Adding DISTRO parameter for makefile to invoke distribution specific Dockerfile and build image accordingly. Updated logic for existing jobs to have distro specific logic for building and publishing images. Added multiple distro specific document in operator section. Change-Id: I415ab28b06ea17b21e76d28ccb3e284041c8072d
344 lines
9.0 KiB
ReStructuredText
344 lines
9.0 KiB
ReStructuredText
Getting Started
|
|
===============
|
|
|
|
Pre-requisites
|
|
--------------
|
|
|
|
* tox
|
|
|
|
To install tox run::
|
|
|
|
$ [sudo] apt-get install tox
|
|
|
|
* PostgreSQL
|
|
|
|
Deckhand only supports PostgreSQL. Install it by running::
|
|
|
|
$ [sudo] apt-get update
|
|
$ [sudo] apt-get install postgresql postgresql-contrib
|
|
|
|
Quickstart
|
|
----------
|
|
|
|
SQLite
|
|
^^^^^^
|
|
|
|
The guide below provides details on how to run Deckhand quickly using
|
|
SQLite.
|
|
|
|
`Docker`_ can be used to quickly instantiate the Deckhand image. After
|
|
installing `Docker`_, create a basic configuration file::
|
|
|
|
$ tox -e genconfig
|
|
|
|
Resulting deckhand.conf.sample file is output to
|
|
:path:etc/deckhand/deckhand.conf.sample
|
|
|
|
Move the sample configuration file into a desired directory
|
|
(i.e. ``$CONF_DIR``).
|
|
|
|
Set the database string in the configuration file to ``sqlite://``
|
|
|
|
.. code-block:: ini
|
|
|
|
[database]
|
|
|
|
#
|
|
# From oslo.db
|
|
#
|
|
|
|
# The SQLAlchemy connection string to use to connect to the database.
|
|
# (string value)
|
|
connection = sqlite://
|
|
|
|
Finally, run Deckhand via Docker::
|
|
|
|
$ [sudo] docker run --rm \
|
|
--net=host \
|
|
-p 9000:9000 \
|
|
-v $CONF_DIR:/etc/deckhand \
|
|
quay.io/airshipit/deckhand:latest-ubuntu_xenial
|
|
|
|
PostgreSQL
|
|
^^^^^^^^^^
|
|
|
|
The guide below provides details on how to run Deckhand quickly using
|
|
PostgreSQL.
|
|
|
|
`Docker`_ can be used to quickly instantiate the Deckhand image. After
|
|
installing `Docker`_, create a basic configuration file::
|
|
|
|
$ tox -e genconfig
|
|
|
|
Resulting deckhand.conf.sample file is output to
|
|
:path:etc/deckhand/deckhand.conf.sample
|
|
|
|
Move the sample configuration file into a desired directory
|
|
(i.e. ``$CONF_DIR``).
|
|
|
|
At a minimum the ``[database].connection`` config option must be set.
|
|
Provide it with a PostgreSQL database connection. Or to conveniently create an
|
|
ephemeral PostgreSQL DB run::
|
|
|
|
$ eval `pifpaf run postgresql`
|
|
|
|
Substitute the connection information (which can be retrieved by running
|
|
``export | grep PIFPAF_POSTGRESQL_URL``) into the config file inside
|
|
``etc/deckhand/deckhand.conf.sample``::
|
|
|
|
[database]
|
|
|
|
#
|
|
# From oslo.db
|
|
#
|
|
|
|
# The SQLAlchemy connection string to use to connect to the database.
|
|
# (string value)
|
|
connection = postgresql://localhost/postgres?host=/tmp/tmpsg6tn3l9&port=9824
|
|
|
|
Run an update to the Database to bring it to the current code level::
|
|
|
|
$ [sudo] docker run --rm \
|
|
--net=host \
|
|
-v $CONF_DIR:/etc/deckhand \
|
|
quay.io/airshipit/deckhand:latest-ubuntu_xenial\
|
|
alembic upgrade head
|
|
|
|
Finally, run Deckhand via Docker::
|
|
|
|
$ [sudo] docker run --rm \
|
|
--net=host \
|
|
-p 9000:9000 \
|
|
-v $CONF_DIR:/etc/deckhand \
|
|
quay.io/airshipit/deckhand:latest-ubuntu_xenial
|
|
|
|
To kill the ephemeral DB afterward::
|
|
|
|
$ pifpaf_stop
|
|
|
|
.. _Docker: https://docs.docker.com/install/
|
|
|
|
Manual Installation
|
|
-------------------
|
|
|
|
.. note::
|
|
|
|
The commands below assume that they are being executed from the root
|
|
Deckhand directory.
|
|
|
|
Install dependencies needed to spin up Deckhand via ``uwsgi``::
|
|
|
|
$ [sudo] pip install uwsgi
|
|
$ virtualenv -p python3 /var/tmp/deckhand
|
|
$ . /var/tmp/deckhand/bin/activate
|
|
$ pip install -r requirements.txt -r test-requirements.txt
|
|
$ python setup.py install
|
|
|
|
Afterward, create a sample configuration file automatically::
|
|
|
|
$ tox -e genconfig
|
|
|
|
Resulting deckhand.conf.sample file is output to
|
|
:path:etc/deckhand/deckhand.conf.sample
|
|
|
|
Create the directory ``/etc/deckhand`` and copy the config file there::
|
|
|
|
$ [sudo] cp etc/deckhand/deckhand.conf.sample /etc/deckhand/deckhand.conf
|
|
|
|
To specify an alternative directory for the config file, run::
|
|
|
|
$ export DECKHAND_CONFIG_DIR=<PATH>
|
|
$ [sudo] cp etc/deckhand/deckhand.conf.sample ${DECKHAND_CONFIG_DIR}/deckhand.conf
|
|
|
|
To conveniently create an ephemeral PostgreSQL DB run::
|
|
|
|
$ eval `pifpaf run postgresql`
|
|
|
|
Retrieve the environment variable which contains connection information::
|
|
|
|
$ export | grep PIFPAF_POSTGRESQL_URL
|
|
declare -x PIFPAF_POSTGRESQL_URL="postgresql://localhost/postgres?host=/tmp/tmpsg6tn3l9&port=9824"
|
|
|
|
Substitute the connection information into the config file in
|
|
``${DECKHAND_CONFIG_DIR}``::
|
|
|
|
[database]
|
|
|
|
#
|
|
# From oslo.db
|
|
#
|
|
|
|
# The SQLAlchemy connection string to use to connect to the database.
|
|
# (string value)
|
|
connection = postgresql://localhost/postgres?host=/tmp/tmpsg6tn3l9&port=9824
|
|
|
|
Finally, run Deckhand::
|
|
|
|
# Perform DB migrations
|
|
$ ./entrypoint.sh alembic upgrade head
|
|
# Instantiate the Deckhand server
|
|
$ ./entrypoint.sh server
|
|
|
|
To kill the ephemeral DB afterward::
|
|
|
|
$ pifpaf_stop
|
|
|
|
Development Mode
|
|
----------------
|
|
|
|
Development mode means running Deckhand without Keystone authentication.
|
|
Note that enabling development mode will effectively disable all authN
|
|
and authZ in Deckhand.
|
|
|
|
To enable development mode, add the following to the ``deckhand.conf``
|
|
inside ``$CONF_DIR``:
|
|
|
|
.. code-block:: ini
|
|
|
|
[DEFAULT]
|
|
development_mode = True
|
|
|
|
After, from the command line, execute:
|
|
|
|
.. code-block:: console
|
|
|
|
$ [sudo] docker run --rm \
|
|
--net=host \
|
|
-p 9000:9000 \
|
|
-v $CONF_DIR:/etc/deckhand \
|
|
quay.io/airshipit/deckhand:latest-ubuntu_xenial server
|
|
|
|
.. _development-utilities:
|
|
|
|
Development Utilities
|
|
---------------------
|
|
|
|
Deckhand comes equipped with many utilities useful for developers, such as
|
|
unit test or linting jobs.
|
|
|
|
Many of these commands require that ``tox`` be installed. To do so, run::
|
|
|
|
$ pip3 install tox
|
|
|
|
To run the Python linter, execute::
|
|
|
|
$ tox -e pep8
|
|
|
|
To run unit tests, execute::
|
|
|
|
$ tox -e py35
|
|
|
|
To run the test coverage job::
|
|
|
|
$ tox -e coverage
|
|
|
|
To run security checks via `Bandit`_ execute::
|
|
|
|
$ tox -e bandit
|
|
|
|
To build all Deckhand charts, execute::
|
|
|
|
$ make charts
|
|
|
|
To generate sample configuration and policy files needed for Deckhand
|
|
deployment, execute (respectively)::
|
|
|
|
$ tox -e genconfig
|
|
$ tox -e genpolicy
|
|
|
|
.. _Bandit: https://github.com/openstack/bandit
|
|
|
|
For additional commands, reference the ``tox.ini`` file for a list of all
|
|
the jobs.
|
|
|
|
Database Model Updates
|
|
----------------------
|
|
|
|
Deckhand utilizes `Alembic`_ to handle database setup and upgrades. Alembic
|
|
provides a straightforward way to manage the migrations necessary from one
|
|
database structure version to another through the use of scripts found in
|
|
deckhand/alembic/versions.
|
|
|
|
Setting up a migration can be automatic or manual. The `Alembic`_ documentation
|
|
provides instructions for how to create a new migration.
|
|
|
|
Creating automatic migrations requires that the Deckhand database model is
|
|
updated in the source code first. With that database model in the code, and
|
|
pointing to an existing Deckhand database structure, Alembic can produce the
|
|
steps necessary to move from the current version to the next version.
|
|
|
|
One way of creating an automatic migration is to deploy a development Deckhand
|
|
database using the pre-updated data model and following the following steps::
|
|
|
|
Navigate to the root Deckhand directory
|
|
$ export DH_ROOT=$(pwd)
|
|
$ mkdir ${DH_ROOT}/alembic_tmp
|
|
|
|
Create a deckhand.conf file that will have the correct DB connection string.
|
|
$ tox -e genconfig
|
|
$ cp ${DH_ROOT}/etc/deckhand/deckhand.conf.sample ${DH_ROOT}/alembic_tmp/deckhand.conf
|
|
|
|
Update the connection string to the deckhand db instance e.g.::
|
|
|
|
[Database]
|
|
connection = postgresql+psycopg2://deckhand:password@postgresql.airship.svc.cluster.local:5432/deckhand
|
|
|
|
$ export DECKHAND_CONFIG_DIR=${DH_ROOT}/alembic_tmp
|
|
$ alembic revision --autogenerate -m "The short description for this change"
|
|
|
|
$ rm -r ${DH_ROOT}/alembic_tmp
|
|
|
|
This will create a new .py file in the deckhand/alembic/versions directory that
|
|
can then be modified to indicate exact steps. The generated migration should
|
|
always be inspected to ensure correctness.
|
|
|
|
Migrations exist in a linked list of files (the files in versions). Each file
|
|
is updated by Alembic to reference its revision linkage. E.g.::
|
|
|
|
# revision identifiers, used by Alembic.
|
|
revision = '918bbfd28185'
|
|
down_revision = None
|
|
branch_labels = None
|
|
depends_on = None
|
|
|
|
Any manual changes to this linkage must be approached carefully or Alembic will
|
|
fail to operate.
|
|
|
|
.. _Alembic: http://alembic.zzzcomputing.com/en/latest/
|
|
|
|
Troubleshooting
|
|
---------------
|
|
|
|
The error messages are included in bullets below and tips to resolution are
|
|
included beneath each bullet.
|
|
|
|
* "FileNotFoundError: [Errno 2] No such file or directory: '/etc/deckhand/api-paste.ini'"
|
|
|
|
Reason: this means that Deckhand is trying to instantiate the server but
|
|
failing to do so because it can't find an essential configuration file.
|
|
|
|
Solution::
|
|
|
|
$ cp etc/deckhand/deckhand.conf.sample /etc/deckhand/deckhand.conf
|
|
|
|
This copies the sample Deckhand configuration file to the appropriate
|
|
directory.
|
|
|
|
* For any errors related to ``tox``:
|
|
|
|
Ensure that ``tox`` is installed::
|
|
|
|
$ [sudo] apt-get install tox -y
|
|
|
|
* For any errors related to running ``tox -e py35``:
|
|
|
|
Ensure that ``python3-dev`` is installed::
|
|
|
|
$ [sudo] apt-get install python3-dev -y
|
|
|
|
* For any errors related to running ``tox -e py27``:
|
|
|
|
Ensure that ``python3-dev`` is installed::
|
|
|
|
$ [sudo] apt-get install python-dev -y
|