sig_cloud/diskimage-builder
2
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Fix up doc errors

Browse Source 
It seems that pbr's "warnerrors" isn't actually doing anything at the
moment (I680b448471e687919d202e8f2abe57f8ba3b22ee) meaning we're able
to commit docs with RST parser errors.  Fix all these up in some
minimal way (I have not audited content, just made it pass build).

Link the specs in so they're referenced from the top level.

Change-Id: Id67b9ea7ba8f49b43969c58ca3fb7fa1243538a4
This commit is contained in:
Ian Wienand 2017-02-08 15:45:12 +11:00
parent 234f44d703
commit f3121f0fb7
9 changed files with 142 additions and 97 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

9
doc/source/index.rst
View File

@ -8,7 +8,7 @@ It includes support for building images based on many major
distributions and can produce cloud-images in all common formats distributions and can produce cloud-images in all common formats
(``qcow2``, ``vhd``, ``raw``, etc), bare metal file-system images and (``qcow2``, ``vhd``, ``raw``, etc), bare metal file-system images and
ram-disk images. These images are composed from the many included ram-disk images. These images are composed from the many included
`elements`; ``diskimage-builder`` acts as a framework to easily add ``elements``; ``diskimage-builder`` acts as a framework to easily add
your own elements for even further customization. your own elements for even further customization.
``diskimage-builder`` is used extensively by the `TripleO project ``diskimage-builder`` is used extensively by the `TripleO project
@ -35,15 +35,15 @@ Issues
Issues are tracked on launchpad at: Issues are tracked on launchpad at:
* `https://bugs.launchpad.net/diskimage-builder/+bugs` * `<https://bugs.launchpad.net/diskimage-builder/+bugs>`__
<https://bugs.launchpad.net/diskimage-builder/+bugs>
Communication Communication
------------- -------------
Communication among the diskimage-builder developers happens on IRC in Communication among the diskimage-builder developers happens on IRC in
#openstack-dib on freenode and on the openstack-dev mailing list (openstack-dev@lists.openstack.org). ``#openstack-dib`` on freenode and on the ``openstack-dev`` mailing list
(``openstack-dev@lists.openstack.org``).
Table of Contents Table of Contents
@ -55,3 +55,4 @@ Table of Contents
user_guide/index user_guide/index
developer/index developer/index
elements elements
specs/README

17
doc/source/specs/README.rst
View File

@ -1,10 +1,9 @@
======= ================================
README
=======
diskimage-builder Specifications diskimage-builder Specifications
================================ ================================
Overview
========
This directory is used to hold approved design specifications for changes to This directory is used to hold approved design specifications for changes to
the diskimage-builder project. Reviews of the specs are done in gerrit, using a the diskimage-builder project. Reviews of the specs are done in gerrit, using a
@ -46,7 +45,7 @@ given release should only refer to the ``implemented`` directory.
Example specifications Example specifications
---------------------- ----------------------
You can find an example spec in ``specs/template.rst``. You can find an example spec in :doc:`v1/approved/v1-template`
Backlog specifications Backlog specifications
---------------------- ----------------------
@ -80,3 +79,11 @@ change any of our public APIs are sometimes not required to provide a
specification. The decision of whether something is trivial or not is a specification. The decision of whether something is trivial or not is a
judgement made by the author or by consensus of the project cores, generally judgement made by the author or by consensus of the project cores, generally
trying to err on the side of spec creation. trying to err on the side of spec creation.
Approved Specifications
=======================
.. toctree::
:glob:
v1/approved/*

5
doc/source/specs/v1/approved/block-device-lvl1-partitioning.rst
View File

@ -20,7 +20,9 @@ The implementation for this proposed changed already exists, was
discussed and is currently waiting for reviews [1]. To have a discussed and is currently waiting for reviews [1]. To have a
complete overview over the block device setup, this document is complete overview over the block device setup, this document is
provided. provided.
The dependencies are not implemented as they should be, because The dependencies are not implemented as they should be, because
* the spec process is currently in the phase of discussion and not * the spec process is currently in the phase of discussion and not
finalized [2], finalized [2],
* the implementation was finished and reviewed before the spec process * the implementation was finished and reviewed before the spec process
@ -137,7 +139,8 @@ size
Example: Example:
:: .. code-block:: yaml
["partitioning", ["partitioning",
{"rootdisk": { {"rootdisk": {
"label": "mbr", "label": "mbr",

2
doc/source/specs/v1/approved/block-device-overview.rst
View File

@ -123,6 +123,7 @@ level or module needs it's own spec.
A first step is to reimplement the existing functionality, this A first step is to reimplement the existing functionality, this
contains: contains:
#. Level 0: Local Loop module #. Level 0: Local Loop module
Use loop device on local image file Use loop device on local image file
(This is already implemented: [1]) (This is already implemented: [1])
@ -133,6 +134,7 @@ contains:
#. Level 3: Mounting #. Level 3: Mounting
As a second step the following functionality can be added: As a second step the following functionality can be added:
* Level 1: LVM module * Level 1: LVM module
* Level 2: Create File System * Level 2: Create File System
(swap) (swap)

4
elements/cloud-init/README.rst
View File

@ -1,6 +1,6 @@
======== ==========
cloud-init cloud-init
======== ==========
Install's and enables cloud-init for systems that don't come with it Install's and enables cloud-init for systems that don't come with it
pre-installed pre-installed

71
elements/debian-minimal/README.rst
View File

@ -2,48 +2,51 @@
debian-minimal debian-minimal
============== ==============
Create a minimal image based on Debian. We default to unstable but `DIB_RELEASE` Create a minimal image based on Debian. We default to unstable but
can be set to any series of Debian. ``DIB_RELEASE`` can be set to any series of Debian.
There are two ways to configure apt-sources: There are two ways to configure apt-sources:
1. Using the standard way of defining the default, backports, updates 1. Using the standard way of defining the default, backports, updates
and security repositories is the default. In this case you can and security repositories is the default. In this case you can
overwrite the two environment variables to adapt the behavior: overwrite the two environment variables to adapt the behavior:
`DIB_DISTRIBUTION_MIRROR`: the mirror to use
default: http://ftp.us.debian.org/debian
`DIB_DEBIAN_COMPONENTS`: (default) `main`
a comma separated list of components. For Debian this can be
e.g. `main,contrib,non-free`.
Note it is not recommended to use http://httpredir.debian.org/ for * ``DIB_DISTRIBUTION_MIRROR``: the mirror to use (default:
`DIB_DISTRIBUTION_MIRROR` due to how unreliable it is. Be sure to `<http://ftp.us.debian.org/debian>`__)
select a mirror from the official mirror list:
https://www.debian.org/mirror/list * ``DIB_DEBIAN_COMPONENTS``: (default: ``main``) a comma
separated list of components. For Debian this can be
e.g. ``main,contrib,non-free``.
By default only `main` component is used. If Note it is not recommended to use
`DIB_DEBIAN_COMPONENTS` (comma separated) from the `debootstrap` `<http://httpredir.debian.org/>`__ for ``DIB_DISTRIBUTION_MIRROR``
element has been set, that list of components will be used instead. due to how unreliable it is. Be sure to select a mirror from the
official mirror list at `<https://www.debian.org/mirror/list>`__
Backports, updates and security are included unless `DIB_RELEASE` By default only the ``main`` component is used. If
is `unstable`. ``DIB_DEBIAN_COMPONENTS`` (comma separated) from the
``debootstrap`` element has been set, that list of components will
be used instead.
Backports, updates and security are included unless ``DIB_RELEASE``
is ``unstable``.
2. Complete configuration given in the variable ``DIB_APT_SOURCES_CONF``.
2. Complete configuration given in the variable
`DIB_APT_SOURCES_CONF`.
Each line contains exactly one entry for the sources.list.d Each line contains exactly one entry for the sources.list.d
directory. directory. The first word must be the logical name (which is used
The first word must be the logical name (which is used as file name as file name with ``.list`` automatically appended), followed by a
with `.list` automatically appended), followed by a colon `:`, colon ``:``, followed by the complete repository specification.
followed by the complete repository specification.
Example: .. code-block:: bash
DIB_APT_SOURCES_CONF=\ DIB_APT_SOURCES_CONF=\
"default:deb http://10.0.0.10/ stretch main contrib "default:deb http://10.0.0.10/ stretch main contrib
mysecurity:deb http://10.0.0.10/ stretch-security main contrib" mysecurity:deb http://10.0.0.10/ stretch-security main contrib"
If necessary, a custom apt keyring and debootstrap script can be If necessary, a custom apt keyring and debootstrap script can be
supplied to the `debootstrap` command via `DIB_APT_KEYRING` and supplied to the ``debootstrap`` command via ``DIB_APT_KEYRING`` and
`DIB_DEBIAN_DEBOOTSTRAP_SCRIPT` respectively. Both options require the ``DIB_DEBIAN_DEBOOTSTRAP_SCRIPT`` respectively. Both options require the
use of absolute rather than relative paths. use of absolute rather than relative paths.
Use of this element will also require the tool 'debootstrap' to be Use of this element will also require the tool 'debootstrap' to be
@ -51,24 +54,24 @@ available on your system. It should be available on Ubuntu, Debian,
and Fedora. It is also recommended that the 'debian-keyring' package and Fedora. It is also recommended that the 'debian-keyring' package
be installed. be installed.
The `DIB_OFFLINE` or more specific `DIB_DEBIAN_USE_DEBOOTSTRAP_CACHE` The ``DIB_OFFLINE`` or more specific ``DIB_DEBIAN_USE_DEBOOTSTRAP_CACHE``
variables can be set to prefer the use of a pre-cached root filesystem variables can be set to prefer the use of a pre-cached root filesystem
tarball. tarball.
The `DIB_DEBOOTSTRAP_EXTRA_ARGS` environment variable may be used to The ``DIB_DEBOOTSTRAP_EXTRA_ARGS`` environment variable may be used to
pass extra arguments to the debootstrap command used to create the pass extra arguments to the debootstrap command used to create the
base filesystem image. If --keyring is is used in `DIB_DEBOOTSTRAP_EXTRA_ARGS`, base filesystem image. If --keyring is is used in ``DIB_DEBOOTSTRAP_EXTRA_ARGS``,
it will override `DIB_APT_KEYRING` if that is used as well. it will override ``DIB_APT_KEYRING`` if that is used as well.
For further information about `DIB_DEBIAN_DEBOOTSTRAP_SCRIPT` , For further information about ``DIB_DEBIAN_DEBOOTSTRAP_SCRIPT`` ,
`DIB_DEBIAN_USE_DEBOOTSTRAP_CACHE` and `DIB_DEBOOTSTRAP_EXTRA_ARGS` ``DIB_DEBIAN_USE_DEBOOTSTRAP_CACHE`` and ``DIB_DEBOOTSTRAP_EXTRA_ARGS``
please consult "README.rst" of the debootstrap element. please consult "README.rst" of the debootstrap element.
------------------- -------------------
Note on ARM systems Note on ARM systems
------------------- -------------------
Because there is not a one-to-one mapping of `ARCH` to a kernel package, if Because there is not a one-to-one mapping of ``ARCH`` to a kernel package, if
you are building an image for ARM on debian, you need to specify which kernel you are building an image for ARM on debian, you need to specify which kernel
you want in the environment variable `DIB_ARM_KERNEL`. For instance, if you want you want in the environment variable ``DIB_ARM_KERNEL``. For instance, if you want
the `linux-image-mx5` package installed, set `DIB_ARM_KERNEL` to `mx5`. the ``linux-image-mx5`` package installed, set ``DIB_ARM_KERNEL`` to ``mx5``.

26
elements/partitioning-sfdisk/README.rst
View File

@ -5,15 +5,27 @@ Sets up a partitioned disk using sfdisk, according to user needs.
Environment Variables Environment Variables
--------------------- ---------------------
DIB_PARTITIONING_SFDISK_SCHEMA
: Required: Yes ``DIB_PARTITIONING_SFDISK_SCHEMA``
: Default: 2048,,L *
:Required:
Yes
:Default:
::
2048,,L *
0 0; 0 0;
0 0; 0 0;
0 0; 0 0;
: Description: A multi-line string specifying a disk schema in sectors. :Description:
: Example: ``DIB_PARTITIONING_SFDISK_SCHEMA=" A multi-line string specifying a disk schema in sectors.
:Example:
.. code-block:: bash
DIB_PARTITIONING_SFDISK_SCHEMA="
2048,10000,L * 2048,10000,L *
10248,,L 10248,,L
0 0; 0 0;"
" will create two partitions on disk, first one will be bootable.
will create two partitions on disk, first one will be bootable.

52
elements/python-brickclient/README.rst
View File

@ -1,20 +1,29 @@
python-brickclient python-brickclient
================== ==================
* This element is aimed for providing cinder local attach/detach functionality. * This element is aimed for providing cinder local attach/detach
* Currently the feature has a dependency on a known bug functionality.
"https://launchpad.net/bugs/1623549", which has been resolved and will be part
of the upstream with the next release of python-brick-cinderclient-ext. * Currently the feature has a dependency on a known bug
Note: Current version of python-brick-cinderclient-ext i.e. 0.2.0 requires and update `<https://launchpad.net/bugs/1623549>`__, which has been resolved
to be made in Line32 fo below script. and will be part of the upstream with the next release of
/usr/share/python-brickclient/venv/lib/python2.7/site-packages/brick_cinderclient_ext/__init__.py ``python-brick-cinderclient-ext``. Note: Current version of
update "brick-python-cinderclient-ext" to "python-brick-cinderclient-ext". ``python-brick-cinderclient-ext`` i.e. 0.2.0 requires and update to
be made in Line32 for
``/usr/share/python-brickclient/venv/lib/python2.7/site-packages/brick_cinderclient_ext/__init__.py``:
update ``brick-python-cinderclient-ext`` to
``python-brick-cinderclient-ext``.
Usage
-----
Pass the below shell script to parameter ``user-data`` and set
``config-drive=true`` at the time of provisioning the node via
nova-boot to make cinder local attach/detach commands talk to your
cloud controller.
.. code-block:: bash
* Usage:
Pass the below shell script to parameter 'user-data' and set 'config-drive=true'
at the time of provisioning the node via nova-boot to make cinder local
attach/detach commands talk to your cloud controller.
[Example of Config Drive Script]
#!/bin/bash #!/bin/bash
FILE="/etc/bash.bashrc" FILE="/etc/bash.bashrc"
[ ! -f "$FILE" ] && touch "$FILE" [ ! -f "$FILE" ] && touch "$FILE"
@ -24,11 +33,16 @@ python-brickclient
echo 'export OS_TENANT_NAME="demo"' >> "$FILE" echo 'export OS_TENANT_NAME="demo"' >> "$FILE"
echo 'export OS_PROJECT_NAME="demo"' >> "$FILE" echo 'export OS_PROJECT_NAME="demo"' >> "$FILE"
exec bash exec bash
To attach: /usr/share/python-brickclient/venv/bin/cinder local-attach <volume_id>
To detach: /usr/share/python-brickclient/venv/bin/cinder local-detach <volume_id>
* Alternatively, the same action can be completed manually at the node which does To attach: ``/usr/share/python-brickclient/venv/bin/cinder local-attach <volume_id>``
not require setting up of config drive such as: To detach: ``/usr/share/python-brickclient/venv/bin/cinder local-detach <volume_id>``
/usr/share/python-brickclient/venv/bin/cinder --os-username demo --os-password \
password --os-tenant-name demo --os-project-name demo \ Alternatively, the same action can be completed manually at the node
which does not require setting up of config drive such as:
.. code-block:: bash
/usr/share/python-brickclient/venv/bin/cinder \
--os-username demo --os-password password \
--os-tenant-name demo --os-project-name demo \
--os-auth-url=http://<controller_ip>:5000/v2.0 local-attach <volume_id> --os-auth-url=http://<controller_ip>:5000/v2.0 local-attach <volume_id>

3
elements/rhel7/README.rst
View File

@ -13,6 +13,9 @@ https://access.redhat.com/downloads/content/69/ver=/rhel---7/7.1/x86_64/product-
Then before running the image build, define DIB_LOCAL_IMAGE (replace the file Then before running the image build, define DIB_LOCAL_IMAGE (replace the file
name with the one downloaded, if it differs from the example):: name with the one downloaded, if it differs from the example)::
.. code-block:: bash
export DIB_LOCAL_IMAGE=rhel-guest-image-7.1-20150224.0.x86_64.qcow2 export DIB_LOCAL_IMAGE=rhel-guest-image-7.1-20150224.0.x86_64.qcow2
The downloaded file will then be used as the basis for any subsequent image The downloaded file will then be used as the basis for any subsequent image