clearlinux/clear-linux-documentation
2
0
Fork 0
mirror of https://github.com/clearlinux/clear-linux-documentation.git synced 2026-09-05 21:31:30 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'master' of clrgitlab.intel.com:clr-documentation/project-docs

Browse Source
This commit is contained in:
Leona
2016-04-28 14:10:16 -07:00
parent 1b3afeb150 81427deb9d
commit 61b57124a7
10 changed files with 333 additions and 69 deletions
Download Patch File Download Diff File Expand all files Collapse all files
source/ceph-deploy.rst
+158
View File
@@ -0,0 +1,158 @@
Ceph*
#####
Ceph is a distributed storage system designed to scale well. It can be integrated with
OpenStack* as the storage backend for the OS images and volumes.
Deploying a Ceph storage cluster is simple using Clear Linux* OS for Intel® Architecture
and Ansible*.
Environment
===========
For this example, we'll use a total of five nodes: a **deployment node** which we will use
to run the playbooks, a **monitor node**, and three **storage nodes**.
Install each component on its own server for best results; however, for testing
purposes you can install the monitor and storage nodes on the same hosts.
Prerequisites
=============
Ansible uses ssh to run commands on the remote servers. In order to do that, the servers
must be configured to allow passwordless ssh connections from the root user. Follow these
steps to configure your nodes.
#. Generate ssh keys::
# ssh-keygen
#. Enable root login::
# echo "PermitRootLogin yes" >> /etc/ssh/sshd_config
#. Enable sshd service::
# systemctl enable sshd
# systemctl start sshd
#. Allow passwordless login::
# ssh-copy-id root@node
Install the software
====================
Install the ``sysadmin-hostmgmt`` bundle on the development node. This bundle contains
the Ansible software required to run the playbooks, as well as some Ansible roles and
sample playbooks that you can use to build your own::
# swupd bundle-add sysadmin-hostmgmt
Create the playbook
===================
The ``sysadmin-hostmgmt`` bundle includes some sample playbooks that you may use and
customize for your own needs. Start by making a copy of the sample playbook into your
home folder.::
# cp /usr/share/ansible/examples/ceph ~/
The playbook consist of four files that you should modify to fit your needs::
ceph
|-- group_vars/
| |-- all
| +-- mons
|-- hosts
+-- ceph_deploy.yml
The hosts file contains the IP addresses of your servers grouped under the roles
they will serve::
[mons]
172.28.128.7
[osds]
172.28.128.8
172.28.128.9
172.28.128.10
This :file:`groups_var/all` file contains variables that will applied to all your nodes.
The mandatory variables are already there; be sure to change the values accordingly to
fit your environment. It should look something like this::
---
journal_size: 1024
monitor_interface: enp0s8
public_network: 172.28.128.0/24
cluster_network: "{{ public_network }}"
A full list of available variables can be found under
:file:`/usr/share/ansible/roles/<role>/defaults/main.yml`
This :file:`groups_var/osd` file contains variables that apply only to the hosts under the
``[mons]`` section in your hosts file. You can choose one of the three available scenarios
for this playbook.
#. **Journal and osd_data on the same device**: This will co-locate both journal and data
on the same disk, creating a partition at the beginning of the device::
journal_collocation: true
devices:
- /dev/sdb
- /dev/sdc
- /dev/sdd
#. **N journal devices for N OSDs**: In this example, the ``sdb`` partition will be used
for journaling of ``sdc`` and ``sdd sdf`` will be used for journaling of ``sde``::
raw_multi_journal: true
devices:
- /dev/sdc
- /dev/sdd
- /dev/sde
raw_journal_devices:
- /dev/sdb
- /dev/sdb
- /dev/sdf
#. **Specify directory instead of disk for OSDs**::
osd_directory: true
osd_directories:
- /var/lib/ceph/osd/mydir1
- /var/lib/ceph/osd/mydir2
- /var/lib/ceph/osd/mydir3
Run the playbook
================
Once you have your variables and hosts file configured, the deployment can be fired
with the following command::
# ansible-playbook -i hosts ceph_deploy.yml
Verify
======
Now that Ansible has finished with the deployment, you can verify the health of the cluster
with the Ceph utilites like ``ceph status`` and ``ceph osd tree``::
# ceph status
cluster ee1fae3b-b95b-494c-abd7-f0629d113446
health HEALTH_OK
monmap e1: 1 mons at {node2=172.28.128.5:6789/0}
election epoch 2, quorum 0 node2
osdmap e8: 3 osds: 3 up, 3 in
flags sortbitwise
pgmap v14: 64 pgs, 1 pools, 0 bytes data, 0 objects
7566 MB used, 49647 MB / 59896 MB avail
64 active+clean
::
# ceph osd tree
ID WEIGHT TYPE NAME UP/DOWN REWEIGHT PRIMARY-AFFINITY
-1 0.05699 root default
-2 0.01900 host node3
0 0.01900 osd.0 up 1.00000 1.00000
-3 0.01900 host node4
1 0.01900 osd.1 up 1.00000 1.00000
-4 0.01900 host node5
2 0.01900 osd.2 up 1.00000 1.00000
source/gs_supported_hardware.rst
+3 -3
View File
@@ -5,14 +5,14 @@ Supported hardware
If you're unsure, you can determine ahead of time whether your system will be
capable of running the Clear Linux* OS for Intel® Architecture by downloading
and running the simple `clear-linux-check-config`_ script locally. This script
and running the simple `clear-linux-check-config.sh`_ script locally. This script
is available in the `current`_ download directory; it checks the hardware
capabilities of your system to determine whether it will work with the
latest current release of Clear Linux.
For developers who are already familiar with the hardware capabilities of their
system(s), the following processors have been tested to be successful
in running Clear Linux OS:
in running Clear Linux OS for Intel Architecture:
- 4th Generation Intel® Core™ processor family on the system of your choice.
- 5th Generation Intel® Core™ processor family on the system of your choice.
@@ -20,5 +20,5 @@ in running Clear Linux OS:
- Intel® Xeon® Processor E3 v5 processor family on the server of your choice.
.. _clear-linux-check-config: http://download.clearlinux.org/current/clear-linux-check-config.sh
.. _clear-linux-check-config.sh: http://download.clearlinux.org/current/clear-linux-check-config.sh
.. _current: http://download.clearlinux.org/current
source/index-storage.rst
+7
View File
@@ -0,0 +1,7 @@
Storage solutions
#################
.. toctree::
:maxdepth: 2
ceph-deploy
source/index.rst
+11 -3
View File
@@ -1,5 +1,5 @@
.. ClearLinux Documentation documentation master file, created by
sphinx-quickstart on Fri Nov 13 12:23:35 2015.
sphinx-quickstart on Fri Nov 13 12:23:35 2015.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
@@ -61,6 +61,15 @@ OpenStack* implementation
index-openstack.rst
Storage solutions
=================
.. toctree::
:maxdepth: 2
index-storage.rst
Indices and tables
==================
@@ -70,7 +79,6 @@ Indices and tables
License and disclaimers
=======================
.. toctree::
.. toctree::
.. include:: documentation_license.rst
source/installing_openstack.rst
+9 -9
View File
@@ -1,9 +1,9 @@
.. _installing_openstack:
Installing OpenStack
####################
Installing OpenStack*
#####################
This section details an OpenStack* installation that uses
This section details an OpenStack installation that uses
bundles available for Clear Linux* OS for Intel® Architecture.
The sample configuration files that are included will likely
@@ -26,18 +26,18 @@ components:
- Neutron
- Dashboard (In identity node)
- Heat
- Swift
Note:
-----
Below you will find the reference to componets supported on ClearLinux* but
its support in Clear Config Management is still pending of development:
Below you will find the reference to componets supported on Clear Linux OS for Intel Architecture, but
its support in Clear Config Management is still pending development:
.. csv-table:: "Supported Components on ClearLinux*, but unsupported by Clear Config Management"
:header: "Component", "Bundles", "OpenStack* official documentation"
:widths: 20, 70, 100
:widths: 20, 70, 100
"Swift", "openstack-object-storage and openstack-block-storage-controller", "http://docs.openstack.org/developer/swift/"
"Cinder", "openstack-block-storage and openstack-block-storage-controller", "http://docs.openstack.org/developer/cinder/"
"Ceilometer", "openstack-telemetry", "http://docs.openstack.org/developer/ceilometer/"
@@ -45,7 +45,7 @@ its support in Clear Config Management is still pending of development:
Prerequisites
=============
Before the installer can set up your cloud environment, these requirements
Before the installer can set up your cloud environment, these prerequisites
should be completed (if they aren't already):
#. Create a pair of SSH keys.
@@ -65,7 +65,7 @@ should be completed (if they aren't already):
Using the Installer
===================
This step presumes a Clear Linux* machine as the ansible host.
This step presumes a machine running Clear Linux OS for Intel Architecture as the ansible host.
Install the bundle
source/mixer.rst
+44 -45
View File
@@ -4,10 +4,10 @@ Mixer Tool
##########
*Mixing* refers to composing an operating system for specific use cases.
While the default ClearLinux provides options to install bundles for various
server capabilities, some developers may wish to augment the operating system
itself with functionality from their own packages, or to modify the structure of
current bundles to cater to their particular needs.
While the default Clear Linux* OS for Intel® Architecture provides options to install
bundles for various server capabilities, some developers may wish to 1) augment the
operating system itself with functionality from their own packages or 2) modify the
structure of current bundles to cater to their particular needs.
Current Workflow
@@ -16,37 +16,37 @@ Current Workflow
Prerequisites
-------------
To start working with the Mixer tools, you'll need a recent Clear Linux* image,
and to have the following bundles installed. If you don't have them already,
To start working with the Mixer tools, you'll need a recent image of Clear Linux OS for Intel Architecture
with the following bundles installed. If you don't have them already,
you can add them with the :command:`swupd bundle-add` command::
# swupd bundle-add mixer
# swupd bundle-add mixer
To satisfy all dependencies (until further development), you'll need the
following additional bundles::
# swupd bundle-add os-clr-on-clr os-core-dev
# swupd bundle-add os-clr-on-clr os-core-dev
Mixing
------
#. **Create a workspace**. Create an empty directory in your Clear image to
use as a "workspace" for mixing. For these steps, assume that the workspace
use as a "workspace" for mixing. For these steps, we assume your workspace
location is :file:`/home/clr/mix`.
#. **Configure builder.conf**. Copy the template conf file:
#. **Configure builder.conf**. Copy the template conf file::
``# cp /usr/share/defaults/bundle-chroot-builder/builder.conf /etc/bundle-chroot-builder/``
# cp /usr/share/defaults/bundle-chroot-builder/builder.conf /etc/bundle-chroot-builder/`
Note there are different sections to the builder.conf. The [Builder] section
Note there are different sections to the builder.conf. The ``[Builder]`` section
provides the mixer tools with required configuration options, defining where
generated bundles and update metadata should get published. The [swupd] section
generated bundles and update metadata should get published. The ``[swupd]`` section
is used by swupd-server to create an update with the newly mixed content.
Edit the template configuration file according to your needs:
Edit the template configuration file according to your needs::
# vim /etc/bundle-chroot-builder/builder.conf:
``# vim /etc/bundle-chroot-builder/builder.conf:``
::
[Builder]
SERVER_STATE_DIR = /var/lib/update
BUNDLE_DIR = /home/clr/mix/bundles
@@ -61,10 +61,9 @@ Mixing
FORMAT=1 ### Can be any number.
# See 'OS Epoch' discussion for details
reflects the path of the current workspace we are working in. The
:file:`builder.conf` will read automatically from ``/etc/bundle-chroot-builder``,
but all of the scripts accept a :option:`-c/--config` option to specify where
the file is, should you want to store it elsewhere. The :file:`.yum-mix.conf`
The file ``builder.conf`` will be read automatically from ``/etc/bundle-chroot-builder``,
but all of the scripts accept a ``-c/--config`` option to specify where
the file is if you want to store it elsewhere. The :file:``.yum-mix.conf``
file will be auto-generated for you.
#. **Generate the starting point for your Mixer**. In your workspace, run::
@@ -82,19 +81,19 @@ Mixing
want to add your own RPMs to the Mix. If you are simply working with Clear
only bundles, then skip to Step 7.)
If you are creating RPMs from scratch, you may use :command:`autospec`,
:command:`mock`, :command:`rpmbuild`, etc. to build them. If they are not
If you are creating RPMs from scratch, you may use ``autospec``,
``mock``, ``rpmbuild``, etc. to build them. If they are not
built on Clear, make sure your configuration builds them correctly for Clear.
#. **Import RPMs into workspace**. The easiest way to do this is to create a
``results`` directory in your workspace *ala* ``/home/clr/mix/results``,
``results`` directory in your workspace (for example ``/home/clr/mix/results``),
and to copy the RPMs you want into that directory. The mixer script will
look here for RPMs needed to build a local RPM repo for yum to use.
#. **Create a local RPM repo**. Create an empty directory in your workspace
name ``local`` and run::
named ``local`` and run::
# mixer-add-rpms.sh --rpmdir results --repodir local
# mixer-add-rpms.sh --rpmdir results --repodir local
After the script exits, you should see your RPMs and a repodata directory in
``/home/clr/mix/local``. If the RPMs are not all in the local directory, check
@@ -102,7 +101,7 @@ Mixing
#. **Initialize Clear/Mix version info**. In the workspace, run::
# mixer-init-versions.sh -m 20
# mixer-init-versions.sh -m 20
This takes the Clear version from your image (or override it with
``-c/--clear-version`` to use another Clear build's content), and uses
@@ -111,7 +110,7 @@ Mixing
#. **Download Bundles**. Download ``clr-bundles``. In the workspace,
run::
# mixer-update-bundles.sh
# mixer-update-bundles.sh
This creates a ``.repos`` directory with git repos that are needed for
later steps; it also creates a ``bundles/`` directory (symlink) in your
@@ -128,12 +127,12 @@ Mixing
$ git add .
$ git commit -s -m 'Update bundles for mix'
Why do this? With git history, mixes are easy to revert to or refer
Why do this? With Git history, mixes are easy to revert to or refer
to in the future if something were to go wrong with a new mix. If
you're just testing this out, or really do not want to mess with git,
you're just testing this out, or if you really do not want to mess with Git,
you can ignore committing for now. The next feature will be to
implement an interactive way to modify/add/delete bundles, so much of
this work can be abstracted out and git work will be more automated.
this work can be abstracted out so Git work will be more automated.
To add your own bundle, create a bundle definition file in ``bundles/``
and refer to :file:`os-core-update` for formatting, but be sure that
@@ -144,13 +143,13 @@ Mixing
#. **Build the bundle chroots** To build all of the ``chroots``
that are based on the bundles you defined, in your workspace run::
# mixer-build-chroots.sh
# mixer-build-chroots.sh
If you have many bundles defined for your mix, this step may take some time.
#. **Create update**. In the workspace, run::
# mixer-create-update.sh
# mixer-create-update.sh
When the script completes, you'll find your mix update content under
``/var/lib/update/www/VER``, in this example, it will be located in
@@ -160,18 +159,18 @@ Mixing
OS Epoch or Format version
--------------------------
The "format" used in builder.conf might be more precisely referred to as an
OS "compatibility epoch". Versions of the OS within a given epoch are fully
compatible with themselves. Across the epoch boundary _something_ has
changed in the OS. This change is impactful enough that release where the
change has taken place must be visited, to ensure operations occur in the
correct order. A format increment is the way we insure pre- and co-requisite
changes flow out with proper ordering.
The "format" used in ``builder.conf`` might be more precisely referred to as an
OS "compatibility epoch". Versions of the OS within a given epoch are fully
compatible with themselves. Across the epoch boundary *something* has
changed in the OS. This change is impactful enough that the release where the
change has taken place must be visited to ensure operations occur in the
correct order. A format increment is the way we insure pre- and co-requisite
changes flow out with proper ordering.
From an update perspective, the format, or compatibility epoch, limits the
extent to which the client can be updated in a single step.
From an update perspective, the format, or compatibility epoch, limits the
extent to which the client can be updated in a single step.
For the creation of a custom mix, the format version should start at '1',
or some known number, and increment only when a compatibility breakage is
introduced. Normal updates, updating a software package for example,
do not require a format increment.
For the creation of a custom mix, the format version should start at '1',
or some known number, and increment only when a compatibility breakage is
introduced. Normal updates (updating a software package for example)
do not require a format increment.
source/network_boot.rst
+17 -5
View File
@@ -55,14 +55,23 @@ Configure the tftpd service using ``dnsmasq``. To do this, create the
Step 3
-------
Download the ``undionly.kpxe`` (legacy) and ``ipxe.efi`` (EFI) files from `the
iPXE website <http://boot.ipxe.org/>`_, and place them in your TFTP directory.
Copy the :file:`/usr/share/ipxe/undionly.kpxe` (legacy) and
:file:`/usr/share/ipxe/ipxe-x86_64.efi` files, and place them in your TFTP
directory.
You can also download the ``undionly.kpxe`` (legacy) and ``ipxe.efi`` (EFI)
files from `the iPXE website <http://boot.ipxe.org/>`_.
.. code-block:: console
# mkdir /srv/tftp/
# curl -o /srv/tftp/undionly.kpxe http://boot.ipxe.org/undionly.kpxe
# curl -o /srv/tftp/ipxe.efi http://boot.ipxe.org/ipxe.efi
# cp /usr/share/ipxe/undionly.kpxe /srv/tftp/undionly.kpxe
# cp /usr/share/ipxe/ipxe-x86_64.efi /srv/tftp/ipxe.efi
Note.
If you are booting on a 32-bit UEFI, you should copy the
:file:`/usr/share/ipxe/ipxe-i386.efi` file.
Step 4
-------
@@ -84,7 +93,7 @@ server root ``/var/www/pxe/``.
# mkdir -p /var/www/pxe/
# version=$(cat /usr/share/clear/version)
# curl -o /var/www/pxe/clear-${version}-pxe.tar.xz https://download.clearlinux.org/image/clear-${version}-pxe.tar.xz
# curl -o /var/www/pxe/clear-${version}-pxe.tar.xz https://download.clearlinux.org/current/clear-${version}-pxe.tar.xz
# tar -xJf /var/www/pxe/clear-${version}-pxe.tar.xz -C /var/www/pxe/ && rm /var/www/pxe/clear-${version}-pxe.tar.xz
# unset version
@@ -191,8 +200,11 @@ from options configured in your ``http://my.web.server/real_boot_script.txt``
file.
Note.
``192.168.1.1`` is set to the address your TFTP server is using.
``my.web.server`` is set to the address your web server is using.
``DHCPDARGS`` is set to the interface you are using.
Step 10
source/openstack_conf_vars_list.rst
+11 -2
View File
@@ -1,7 +1,7 @@
.. _openstack_conf_vars_list:
Variables for OpenStack Deployment
##################################
Variables for OpenStack* Deployment
###################################
This installer provides a variety of configurations you can set through
variables; below you will find a reference of the components supported
@@ -29,6 +29,13 @@ Required Variables
"*(Heat)* **heat_user_password**", "Password for heat user"
"*(Heat)* **heat_database_password**", "Password for heat database"
"*(Heat)* **heat_domain**", "The heat domain that contains projects and users for stacks"
"*(Swift)* **swift_user_password**", "Password for 'swift' user"
"*(Swift)* **swift_database_password**", "Password for 'swift' database"
"*(Swift)* **swift_replica_count**", "Replica number for each object. IMPORTANT: This number must be lower than the sum of all the storage devices among all storage nodes. It can be changed later."
"*(Swift)* **swift_hash_path_suffix**", "Suffix for the object path name"
"*(Swift)* **swift_hash_path_prefix**", "Prefix for the object path name"
"*(Swift)* **swift_storage_device_path**", "The path of the storage devices"
"*(Swift)* **swift_storage_devices**", "A list of the storage devices dedicated to swift deployment. For more information, see :ref:`openstack_swift_deployment_scenarios`"
Optional Variables
==================
@@ -44,6 +51,8 @@ Optional Variables
"*(Nova)* **nova_public_interface_name**: unset", "Public interface of Neutron machines, if is not set, it will take the default interface reported by **ip route**"
"*(Nova)* **nova_virt_type**: qemu", "Virtualization type (qemu | kvm), if this is not set, then the playbook will try to guess it"
"*(Neutron)* **os_tuning_params**: net.ipv4.ip_forward: 1, net.ipv4.conf.default.rp_filter: 0, net.ipv4.conf.all.rp_filter: 0, net.bridge.bridge-nf-call-iptables: 1, net.bridge.bridge-nf-call-ip6tables: 1", "syctl values needed by neutron when using openvswitch deployment scenario"
"*(Swift)* **swift_public_interface_name**, "Public interface of storage nodes, also known as the storage network interface name; If is not set, it will take the default interface reported by **ip route**"
Note:
-----
source/openstack_env_inventory_file.rst
+4 -2
View File
@@ -31,7 +31,7 @@ Below you will find the description of each group in the `hosts` file.
.. csv-table:: "Inventory File Groups"
:header: "Group", "Components", "Comments"
:widths: 40, 40, 300
:widths: 40, 40, 300
"[dbservers]", "MariaDB", ""
"[messaging_servers]", "RabbitMQ", ""
@@ -41,9 +41,11 @@ Below you will find the description of each group in the `hosts` file.
"[openstack_compute]", "Nova", "Accepts multiple entries to have multiple compute nodes. You can add more entries and re-run the installer to add them to your environment."
"[openstack_networking]", "Neutron", ""
"[openstack_orchestration]", "Heat", ""
"[openstack_object_storage_controller]", "Swift", "The Swift storage controller. It runs the swift proxy server and the memcache server"
"[openstack_object_storage]", "Swift", "The Swift Storage nodes. Accepts multiple entries to have multiple storage nodes"
Important Notes
Important notes
---------------
* To omit any role, do not add an entry under its group section.
source/openstack_swift_deployment_scenarios.rst
+69
View File
@@ -0,0 +1,69 @@
.. _openstack_swift_deployment_scenarios:
OpenStack* Swift* Deployment Scenarios
######################################
You can install OpenStack Swift using clear-config-management through two
possible scenarios.
- **Scenario #1:** All the storage nodes are identical, with the same number of storage devices with the same names.
- **Scenario #2:** The storage setup is heterogeneous. The list of storage devices must be provided for each storage node individually.
Scenario #1: Identical storage nodes scenario
=============================================
To set up this scenario, the ``swift_storage_devices`` variable needs to be
defined in ``../group_vars/all`` as follows:
.. code-block:: yaml
...
swift_storage_device_path: /dev/
swift_storage_devices:
- sda
- sdb
...
Scenario #2: Different storage nodes scenario
=============================================
With this setup, specific information about each storage node has to be provided.
First, in the root of your Ansible* directory setup, create a new directory called ``host_vars``.
Inside ``host_vars``, for each storage node, create a new file with the name of the
storage node's hostname or IP. In each file, provide the list of the storage
devices.
The Ansible directory setup should look similar to the following directory tree:
.. code-block:: console
openstack/
├── group_vars
│ └── all
├── hosts
├── host_vars
│ ├── storage-one
│ └── storage-two
├── openstack_deployment.yml
└── README.md
And the ``storage-one`` and ``storage-two`` storage node files should look similar to this:
.. code-block:: yaml
---
devices:
- sdb
- sdc
- sdd
.. code-block:: yaml
---
devices:
- vdb
- vdc