diff --git a/doc/CONTRIBUTING.rst b/doc/CONTRIBUTING.rst index 08866bf321..ae248028c8 100644 --- a/doc/CONTRIBUTING.rst +++ b/doc/CONTRIBUTING.rst @@ -1,9 +1,11 @@ +.. _CONTRIBUTING: + ================= How To Contribute ================= Basics -~~~~~~ +====== * Our source code is hosted on `OpenStack GitHub`_, but pull requests submitted through GitHub will be ignored. Bugs should be filed on launchpad_, @@ -28,7 +30,7 @@ Basics .. _here: https://wiki.openstack.org/wiki/GitCommitMessages Development Environment -~~~~~~~~~~~~~~~~~~~~~~~ +======================== * Please follow our `quickstart`_ to deploy your environment and test your changes diff --git a/doc/advanced-configuration.rst b/doc/advanced-configuration.rst index aa4cd3f398..220664f44c 100644 --- a/doc/advanced-configuration.rst +++ b/doc/advanced-configuration.rst @@ -1,8 +1,12 @@ +.. _advanced-configuration: + +====================== Advanced Configuration ====================== Endpoint Network Configuration ------------------------------- +============================== + When an OpenStack cloud is deployed, each services' REST API is presented as a series of endpoints. These endpoints are the admin URL, the internal URL, and the external URL. @@ -37,9 +41,9 @@ networks. kolla_external_vip_address: "10.10.20.254" kolla_external_vip_interface: "eth1" - Fully Qualified Domain Name Configuration ------------------------------------------ +========================================= + When addressing a server on the internet, it is more common to use a name, like www.example.net, instead of an address like 10.10.10.254. If you prefer to use names to address the endpoints in your kolla @@ -56,7 +60,8 @@ configured IP addresses. Using a DNS server or the /etc/hosts file are two ways to create this mapping. TLS Configuration ------------------ +================= + An additional endpoint configuration option is to enable or disable TLS protection for the external VIP. TLS allows a client to authenticate the OpenStack service endpoint and allows for encryption of the requests @@ -109,7 +114,8 @@ have settings similar to this: export OS_IDENTITY_API_VERSION=3 Self-Signed Certificates ------------------------- +======================== + .. NOTE:: Self-signed certificates should never be used in production. It is not always practical to get a certificate signed by a well-known @@ -126,13 +132,14 @@ file. The files haproxy.pem and haproxy-ca.pem will be generated and stored in the /etc/kolla/certificates/ directory. - Deployment Configuration ------------------------- +======================== + TODO(all) fill this section out OpenStack Service Configuration in Kolla ----------------------------------------- +======================================== + .. NOTE:: As of now kolla only supports config overrides for ini based configs. Kolla allows deployer to override configuration of services. Kolla will look @@ -148,7 +155,7 @@ need to create `/etc/kolla/config/nova/nova-scheduler.conf with content`: scheduler_max_attempts = 100 If the operator wants to configure compute node ram allocation ratio -on host myhost, the operator needs to create file +on host myhost, the operator needs to create file `/etc/kolla/config/nova/myhost/nova.conf` with content: :: @@ -157,13 +164,14 @@ on host myhost, the operator needs to create file ram_allocation_ratio = 5.0 The operator can make these changes after services were already deployed by using -following command -. +following command. + :: kolla-ansible reconfigure IP Address Constrained Environments ------------------------------------ +=================================== + If a development environment doesn't have a free IP address available for VIP configuration, the host's IP address may be used here by disabling HAProxy by adding: diff --git a/doc/ceph-guide.rst b/doc/ceph-guide.rst index e69a2adbbd..3d2623bf86 100644 --- a/doc/ceph-guide.rst +++ b/doc/ceph-guide.rst @@ -1,3 +1,6 @@ +.. _ceph-guide: + +============= Ceph in Kolla ============= @@ -7,13 +10,13 @@ tweaks to the Ceph cluster you can deploy a "healthy" cluster with a single host and a single block device. Requirements ------------- +============ * A minimum of 3 hosts for a vanilla deploy * A minimum of 1 block device per host Preparation and Deployment --------------------------- +========================== To prepare a disk for use as a `Ceph OSD `_ you must add a @@ -83,9 +86,8 @@ Finally deploy the Ceph-enabled OpenStack: kolla-ansible deploy -i path/to/inventory - Using a Cache Tier ------------------- +================== An optional `cache tier `_ @@ -115,9 +117,8 @@ After this run the playbooks as you normally would. For example: kolla-ansible deploy -i path/to/inventory - Setting up an Erasure Coded Pool --------------------------------- +================================ `Erasure code `_ is the new big thing from Ceph. Kolla has the ability to setup your Ceph pools @@ -138,9 +139,8 @@ To enable erasure coded pools add the following options to your # Optionally, you can change the profile #ceph_erasure_profile: "k=4 m=2 ruleset-failure-domain=host" - Managing Ceph -------------- +============= Check the Ceph status for more diagnostic information. The sample output below indicates a healthy cluster: diff --git a/doc/cinder-guide.rst b/doc/cinder-guide.rst index 7446c00910..47a713dafa 100644 --- a/doc/cinder-guide.rst +++ b/doc/cinder-guide.rst @@ -1,8 +1,12 @@ +.. _cinder-guide: + +=============== Cinder in Kolla =============== Overview --------- +======== + Currently Kolla can deploy the cinder services: - cinder-api @@ -15,7 +19,7 @@ implementation requires a volume group be set up. This can either be a real physical volume or a loopback mounted file for development. Create a Volume Group ---------------------- +===================== Use pvcreate and vgcreate to create the volume group. For example with the devices /dev/sdb and /dev/sdc: @@ -39,7 +43,7 @@ system. vgcreate cinder-volumes /dev/loop2 Validation ----------- +========== Create a volume as follows: @@ -77,7 +81,8 @@ If the disk stays in the available state, something went wrong during the iSCSI mounting of the volume to the guest VM. Cinder LVM2 backend with iSCSI ------------------------------- +============================== + As of Newton-1 milestone, Kolla supports LVM2 as cinder backend. It is accomplished by introducing two new containers tgtd and iscsid. tgtd container serves as a bridge between cinder-volume process and a server @@ -85,11 +90,10 @@ hosting Logical Volume Groups (LVG). iscsid container serves as a bridge between nova-compute process and the server hosting LVG. There are two methods to apply new configuration to cinder: - 1 - New deployments: create cinder.conf and place it at /etc/kolla/config - folder, then add below configuration lines and run kolla deloyment. - 2 - Existing cinder deployments: modify cinder.conf located at - /etc/kolla/config by adding below configuration lines and run kolla - reconfigure. + - New deployments: create cinder.conf and place it at /etc/kolla/config + folder, then add below configuration lines and run kolla deloyment. + - Existing cinder deployments: modify cinder.conf located at /etc/kolla/config + by adding below configuration lines and run kolla reconfigure. :: @@ -109,14 +113,12 @@ There are two methods to apply new configuration to cinder: Where: -- local_lvm_name is a name chosen by a user for a spefic LVM2 backend, multiple -LVM2 backend can be confiugred and each should have a unique name. - -- lvg_name is a name Logical Volume Group created for cinder to store volumes. - -- management_ip_address_of_server_hosting_LVG is IP address of an interface -where cinder process is bound to. (Do not use VIP address here, LVG does not -move from server to server as VIP address does in case of a server failure). + - local_lvm_name is a name chosen by a user for a spefic LVM2 backend, multiple + LVM2 backend can be confiugred and each should have a unique name. + - lvg_name is a name Logical Volume Group created for cinder to store volumes. + - management_ip_address_of_server_hosting_LVG is IP address of an interface + where cinder process is bound to. (Do not use VIP address here, LVG does not + move from server to server as VIP address does in case of a server failure). NOTE: For Ubuntu and LVM2/iSCSI @@ -126,9 +128,8 @@ file system gets mounted automatically, which is not the case on debian/ubuntu. Since iscsid container runs on every nova compute node, the following steps must be completed on every Ubuntu server targeted for nova compute role. - 1 - Add configfs module to /etc/modules - 2 - Rebuild initramfs using: "update-initramfs -u" command - 3 - Make sure configfs gets mounted during a server boot up process. There are - multiple ways to accomplish it, one example is adding this command to - "mount -t configfs configfs /sys/kernel/config" to /etc/rc.local - + - Add configfs module to /etc/modules + - Rebuild initramfs using: "update-initramfs -u" command + - Make sure configfs gets mounted during a server boot up process. There are + multiple ways to accomplish it, one example is adding this command to + "mount -t configfs configfs /sys/kernel/config" to /etc/rc.local diff --git a/doc/deployment-philosophy.rst b/doc/deployment-philosophy.rst index bea9f51bb9..6a08e418f6 100644 --- a/doc/deployment-philosophy.rst +++ b/doc/deployment-philosophy.rst @@ -1,8 +1,11 @@ +.. _deployment-philosophy: + +============================= Kolla's Deployment Philosophy ============================= Overview --------- +======== Kolla has an objective to replace the inflexible, painful, resource intensive deployment process of OpenStack with a flexible, painless, inexpensive @@ -20,7 +23,7 @@ OpenStack services increases, Kolla offers full capability to override every OpenStack service configuration option in the deployment. Why not Template Customization? -------------------------------- +=============================== The Kolla upstream community does not want to place key/value pairs in the Ansible playbook configuration options that are not essential to obtaining @@ -35,9 +38,8 @@ cycle is required in order to successfully add a new customization. Essentially templating in configuration options is not a scalable solution and would result in an inability of the project to execute its mission. - Kolla's Solution to Customization ---------------------------------- +================================= Rather than deal with the customization madness of templating configuration options in Kolla's Ansible playbooks, Kolla eliminates all the inefficiencies diff --git a/doc/heat-dev-env.rst b/doc/heat-dev-env.rst index 380194da1d..07dd439801 100644 --- a/doc/heat-dev-env.rst +++ b/doc/heat-dev-env.rst @@ -1,3 +1,6 @@ +.. _heat-dev-env: + +================================= Development Environment with Heat ================================= @@ -33,7 +36,7 @@ correct a bug with template validation when using the "Fn::Join" function). Create the Glance Image ------------------------ +======================= After cloning the project, run the get-image.sh script from the project's devenv directory: @@ -55,7 +58,7 @@ Add the image to your Glance image store: --is-public True --progress Create the Stack ----------------- +================ Copy local.yaml.example to local.yaml and edit the contents to match your deployment environment. Here is an example of a customized @@ -100,7 +103,7 @@ And then create the stack, referencing that environment file: $ heat stack-create -f kollacluster.yaml -e local.yaml kolla-cluster Access the Kolla Nodes ----------------------- +====================== You can get the ip address of the Kolla nodes using the ``heat output-show`` command: @@ -149,7 +152,7 @@ If you want to start a container set by hand use this template $ docker-compose -f glance-api-registry.yml up -d Debugging ---------- +========= All Docker commands should be run from the directory of the Docker binary, by default this is ``/``. @@ -191,4 +194,3 @@ appear as follows Trying 10.0.0.4... Connected to 10.0.0.4. Escape character is '^]'. - diff --git a/doc/image-building.rst b/doc/image-building.rst index 798c7cab05..da2f3f703c 100644 --- a/doc/image-building.rst +++ b/doc/image-building.rst @@ -1,3 +1,6 @@ +.. _image-building: + +========================= Building Container Images ========================= @@ -5,7 +8,7 @@ The ``tools/build.py`` script in this repository is responsible for building docker images. Generating kolla-build.conf ---------------------------- +=========================== Install tox and generate the build configuration. The build configuration is designed to hold advanced customizations when building @@ -21,9 +24,8 @@ The location of the generated configuration file is ``etc/kolla/kolla-build.conf You can also copy it to ``/etc/kolla``. The default location is one of ``/etc/kolla/kolla-build.conf`` or ``etc/kolla/kolla-build.conf``. - Guide ------ +===== In general, you will build images like this: @@ -94,9 +96,8 @@ command: tox -e genconfig - Build OpenStack from Source ---------------------------- +=========================== When building images, there are two methods of the OpenStack install. One is ``binary``. Another is ``source``. @@ -154,9 +155,8 @@ Then build RHEL containers: build -b rhel -i ./rhel-include - Custom Repos ------------- +============ The build method allows you to build your containers from custom repos. The repos are accepted as a list of comma separated values and can be in @@ -173,9 +173,8 @@ same directory as the base Dockerfile (kolla/docker/base). rpm_setup_config = epel.repo,delorean.repo,delorean-deps.repo - Plugin Functionality --------------------- +==================== .. note:: @@ -210,10 +209,8 @@ image, one would add the following block to ``/etc/kolla/kolla-build.conf``: location = https://github.com/openstack/networking-cisco reference = master - Known issues ------------- - +============ 1. Can't build base image because docker fails to install systemd. @@ -222,9 +219,8 @@ Known issues to avoid the issue is that add ``-s devicemapper`` to ``DOCKER_OPTS``. Get more information about the issue from DockerBug_. - Docker Local Registry ---------------------- +===================== It is recommended to set up local registry for Kolla developers or deploying multinode. The reason using a local registry is @@ -235,7 +231,7 @@ If there is no local registry, nodes pull images from Docker Hub when images are not found in local caches. Setting up Docker Local Registry -++++++++++++++++++++++++++++++++ +-------------------------------- Running Docker registry is easy. Just use the following command: @@ -250,7 +246,7 @@ To avoid conflict, use 4000 port as Docker registry port. Now the Docker registry service is running. Docker Insecure Registry Config -+++++++++++++++++++++++++++++++ +------------------------------- For docker to pull images, it is necessary to modify the Docker configuration. The guide assumes that @@ -271,7 +267,7 @@ To build and push images to local registry, use the following command: tools/build.py --registry 172.22.2.81:4000 --push Kolla-ansible with Local Registry -+++++++++++++++++++++++++++++++++ +--------------------------------- To make kolla-ansible pull images from local registry, set ``"docker_registry"`` to ``"172.22.2.81:4000"`` in @@ -281,7 +277,7 @@ images from insecure registry. See Building behind a proxy -+++++++++++++++++++++++ +----------------------- The build script supports augmenting the Dockerfiles under build via so called `header` and `footer` files. Statements in the `header` file are included at diff --git a/doc/ironic-guide.rst b/doc/ironic-guide.rst index e0ed9baff5..e026865538 100644 --- a/doc/ironic-guide.rst +++ b/doc/ironic-guide.rst @@ -1,8 +1,11 @@ +.. _ironic-guide: + +=============== Ironic in Kolla =============== Overview --------- +======== Currently Kolla can deploy the Ironic services: - ironic-api @@ -12,13 +15,13 @@ Currently Kolla can deploy the Ironic services: As well as a required PXE service, deployed as ironic-pxe. Current status --------------- +============== The Ironic implementation is "tech preview", so currently instances can only be deployed on baremetal. Further work will be done to allow scheduling for both virtualized and baremetal deployments. Post-deployment configuration ------------------------------ +============================= Configuration based off upstream documentation_. Again, remember that enabling Ironic reconfigures nova compute (driver and diff --git a/doc/kibana-guide.rst b/doc/kibana-guide.rst index 40071ffedc..46694acf1b 100644 --- a/doc/kibana-guide.rst +++ b/doc/kibana-guide.rst @@ -1,8 +1,11 @@ +.. _kibana-guide: + +=============== Kibana in Kolla =============== Default index pattern ---------------------- +===================== After successful Kibana deployment, it can be accessed on : @@ -32,7 +35,7 @@ Note: This step is necessary until the default Kibana dashboard is implemented in Kolla. Search logs - Discover tab --------------------------- +=========================== Logs search is available under Discover tab. In the menu on the left side, one can choose any field that will be included in a new search. To do this, @@ -45,7 +48,7 @@ Current search can be saved by using 'Save search' option in the menu on the right. Visualize data - Visualize tab ------------------------------- +============================== In the visualization tab a wide range of charts is available. If any visualization has not been saved yet, after choosing this tab 'Create a new @@ -65,7 +68,7 @@ visualization' option in the menu on the right. If it is not saved, it will be lost after leaving a page or creating another visualization. Organize visualizations and searches - Dashboard tab ----------------------------------------------------- +==================================================== In the Dashboard tab all of saved visualizations and searches can be organized in one Dashboard. To add visualization or search, one can choose @@ -82,7 +85,7 @@ If a Dashboard has already been saved, it can be opened by choosing 'open dashboard' option in the menu on the right. Exporting and importing created items - Settings tab ------------------------------------------------------------- +===================================================== Once visualizations, searches or dashboards are created, they can be exported to a json format by choosing Settings tab and then Objects tab. Each of the @@ -90,4 +93,3 @@ item can be exported separately by selecting it in the menu. All of the items can also be exported at once by choosing 'export everything' option. In the same tab (Settings - Objects) one can also import saved items by choosing 'import' option. - diff --git a/doc/liberty-deployment-warning.rst b/doc/liberty-deployment-warning.rst index f5e6e3db2a..ebd206c6bf 100644 --- a/doc/liberty-deployment-warning.rst +++ b/doc/liberty-deployment-warning.rst @@ -1,14 +1,17 @@ +.. _liberty-deployment-warning: + +================================ Liberty 1.0.0 Deployment Warning ================================ Warning Overview ----------------- +================ Please use Liberty 1.1.0 tag or later when using Kolla. No data loss occurs with this version. stable/liberty is also fully functional and suffers no data loss. Data loss with 1.0.0 --------------------- +==================== The Kolla community discovered in the of middle Mitaka development that it was possible for data loss to occur if the data container is rebuilt. In this scenario, Docker pulls a new container, and the new container doesn't @@ -17,7 +20,7 @@ contain the data from the old container. Kolla stable/liberty and Kolla problems*. Resolution ----------- +========== To rectify this problem, the OpenStack release and infrastructure teams in coordination with the Kolla team executed the following actions: @@ -29,7 +32,7 @@ in coordination with the Kolla team executed the following actions: * Released Kolla 1.1.0 from the newly created stable/liberty branch. End Result ----------- +========== A fully functional Liberty OpenStack deployment based upon the two years of testing that went into the development that went into stable/mitaka. diff --git a/doc/manila-guide.rst b/doc/manila-guide.rst index 04f6cd34bd..1525925a7c 100644 --- a/doc/manila-guide.rst +++ b/doc/manila-guide.rst @@ -1,8 +1,11 @@ +.. _manila-guide: + +=============== Manila in Kolla =============== Overview --------- +======== Currently, Kolla can deploy following manila services: * manila-api @@ -16,7 +19,7 @@ management of share types as well as share snapshots if a driver supports them. Important ---------- +========= For simplicity, this guide describes configuring the Shared File Systems service to use the ``generic`` back end with the driver handles share @@ -29,7 +32,7 @@ Before you proceed, ensure that Compute, Networking and Block storage services are properly working. Preparation and Deployment --------------------------- +========================== Cinder and Ceph are required, enable it in /etc/kolla/globals.yml: @@ -57,8 +60,8 @@ Create or modify the file /etc/kolla/config/manila.conf and add the contents: [generic] service_instance_flavor_id = 2 -Verify operation ----------------- +Verify Operation +================ Verify operation of the Shared File Systems service. List service components to verify successful launch of each process: @@ -74,7 +77,7 @@ to verify successful launch of each process: +------------------+----------------+------+---------+-------+----------------------------+-----------------+ Launch an Instance ------------------- +================== Before being able to create a share, the manila with the generic driver and the DHSS mode enabled requires the definition of at least an image, @@ -83,7 +86,7 @@ For that back end configuration, the share server is an instance where NFS/CIFS shares are served. Determine the configuration of the share server ------------------------------------------------ +=============================================== Create a default share type before running manila-share service: @@ -171,7 +174,7 @@ Create a flavor (Required if you not defined manila_instance_flavor_id in # nova flavor-create manila-service-flavor 100 128 0 1 Create a share --------------- +============== Create a NFS share using the share network: @@ -225,7 +228,7 @@ network: # manila access-allow demo-share1 ip INSTANCE_PRIVATE_NETWORK_IP Mount the share from an instance --------------------------------- +================================ Get export location from share @@ -284,4 +287,3 @@ Mount the NFS share in the instance using the export location of the share: For more information about how to manage shares, see the `OpenStack User Guide `__. - diff --git a/doc/multinode.rst b/doc/multinode.rst index 2d6e984c18..e7b6c1f874 100644 --- a/doc/multinode.rst +++ b/doc/multinode.rst @@ -1,8 +1,11 @@ +.. _multinode: + +============================= Multinode Deployment of Kolla ============================= Deploy a registry (required for multinode) ------------------------------------------- +========================================== A Docker registry is a locally hosted registry that replaces the need to pull from the Docker Hub to get images. Kolla can function with @@ -72,7 +75,7 @@ And restart docker by executing the following commands: sudo service docker restart Edit the Inventory File ------------------------ +======================= The ansible inventory file contains all the information needed to determine what services will land on which hosts. Edit the inventory file in the kolla @@ -108,7 +111,7 @@ and changing these around can break your deployment: network Deploying Kolla ---------------- +=============== First, check that the deployment targets are in a state where Kolla may deploy to them: @@ -117,12 +120,10 @@ to them: kolla-ansible prechecks -i -For additional environment setup see the `quickstart guide`_. +For additional environment setup see the :ref:`deploying-kolla`. Run the deployment: :: kolla-ansible deploy -i - -.. _quickstart guide: ./quickstart.rst#deploying-kolla diff --git a/doc/nova-fake-driver.rst b/doc/nova-fake-driver.rst index 33f46bead5..d5ed86efff 100644 --- a/doc/nova-fake-driver.rst +++ b/doc/nova-fake-driver.rst @@ -1,3 +1,6 @@ +.. nova-fake-driver: + +================ Nova Fake Driver ================ @@ -13,7 +16,7 @@ we can create 100 nova-compute containers on a real host to simulate the 100-hypervisor workload to the nova-conductor and the messaging queue. Use nova-fake driver ---------------------- +==================== Nova fake driver can not work with all-in-one deployment. This is because the fake neutron-openvswitch-agent for the fake nova-compute container conflicts diff --git a/doc/operating-kolla.rst b/doc/operating-kolla.rst index 37ce96e2ba..98addd99dc 100644 --- a/doc/operating-kolla.rst +++ b/doc/operating-kolla.rst @@ -1,24 +1,27 @@ +.. _operating-kolla: + +=============== Operating Kolla =============== Upgrading ---------- +========= TODO(all) fill this section out Diagnostics ------------ +=========== TODO(all) fill this section out Failure Recovery ----------------- +================ TODO(all) fill this section out Reconfiguration of an existing environment ------------------------------------------- +========================================== TODO(all) fill this section out Tips and Tricks ---------------- +=============== Kolla ships with several utilities intended to facilitate ease of operation. ``tools/cleanup-containers`` can be used to remove deployed containers from diff --git a/doc/quickstart.rst b/doc/quickstart.rst index 3349d29073..4ddf4b71bf 100644 --- a/doc/quickstart.rst +++ b/doc/quickstart.rst @@ -1,8 +1,11 @@ +.. quickstart: + +==================================================== Deployment of Kolla on Bare Metal or Virtual Machine ==================================================== Host machine requirements -------------------------- +========================= The recommended deployment target requirements: @@ -13,18 +16,15 @@ The recommended deployment target requirements: .. NOTE:: Some commands below may require root permissions (e.g. pip, apt-get). Recommended Environment ------------------------ +======================= If developing or evaluating Kolla, the community strongly recommends using bare metal or a virtual machine. Follow the instructions in this document to get started with deploying OpenStack on bare metal or a virtual machine with Kolla. - -.. NOTE:: There are other deployment environments referenced below in -`Additional Environments`_. - +There are other deployment environments referenced below in `Additional Environments`_. Install Dependencies ------------------------ +==================== Kolla is tested on CentOS, Oracle Linux, RHEL and Ubuntu as both container OS platforms and bare metal deployment targets. @@ -244,9 +244,8 @@ to /etc: cd kolla cp -r etc/kolla /etc/ - Install Python Clients ----------------------- +====================== On the system where the OpenStack CLI/Python code is run, the Kolla community recommends installing the OpenStack python clients if they are not installed. @@ -273,27 +272,26 @@ To install the clients use: pip install -U python-openstackclient python-neutronclient Local Registry --------------- +============== A local registry is not required for an all-in-one installation. Check out the -`multinode doc`_ for more information on using a local registry. Otherwise, the -`dockerhub image registry https://hub.docker.com/u/kollaglue/`__ contains all images from each of Kolla's major releases. The latest release tag is +:doc:`multinode` for more information on using a local registry. Otherwise, the +`Docker Hub Image Registry`_ contains all images from each of Kolla's major releases. The latest release tag is 2.0.0 for Mitaka. - Additional Environments ------------------------ +======================= Two virtualized development environment options are available for Kolla. These options permit the development of Kolla without disrupting the host operating system. If developing Kolla on an OpenStack cloud environment that supports Heat, -follow the `Heat developer environment guide `__. +follow the :doc:`heat-dev-env`. If developing Kolla on a system that provides VirtualBox or Libvirt in addition to Vagrant, use the Vagrant virtual environment documented in -`Vagrant developer environment guide `__. +:doc:`vagrant-dev-env`. Currently the Heat development environment is entirely non-functional. The Kolla core reviewers have debated removing it from the repository @@ -305,9 +303,8 @@ bare metal, or a manually setup virtual machine. For more information refer to `_bug 1562334 `__. - Building Container Images -------------------------- +========================== The Kolla community does not currently generate new images for each commit to the repository. The push time for a full image build to the docker registry @@ -317,7 +314,7 @@ using the Docker Hub registry with the current OpenStack CI/CD systems. The Kolla community builds and pushes tested images for each tagged release of Kolla, but if running from master, it is recommended to build images locally. -Checkout the `image-building doc`_ for more advanced build configuration. +Checkout the :doc:`image-building` for more advanced build configuration. Before running the below instructions, ensure the docker daemon is running or the build process will fail. To build images using default parameters run: @@ -365,9 +362,10 @@ In order to see all available parameters, run: kolla-build -h +.. _deploying-kolla: Deploying Kolla ---------------- +=============== The Kolla community provides two example methods of Kolla deploy: *all-in-one* and *multinode*. The "all-in-one" deploy is similar @@ -375,7 +373,7 @@ to `devstack `__ deploy which installs all OpenStack services on a single host. In the "multinode" deploy, OpenStack services can be run on specific hosts. This documentation only describes deploying *all-in-one* method as most simple one. To setup multinode -see the `multinode doc`_. +see the :doc:`multinode`. Each method is represented as an Ansible inventory file. More information on the Ansible inventory file can be found in the Ansible `inventory introduction @@ -525,7 +523,7 @@ environment with a glance image and neutron networks: kolla/tools/init-runonce Failures --------- +======== Nearly always when Kolla fails, it is caused by a CTRL-C during the deployment process or a problem in the globals.yml configuration. @@ -572,7 +570,7 @@ can occur. To refresh the docker cache from the local Docker registry: kolla-ansible pull Debugging Kolla ---------------- +=============== The container's status can be determined on the deployment targets by executing: @@ -626,7 +624,4 @@ prompted to create an index. Please create an index using the name ``log-*``. This step is necessary until the default Kibana dashboard is implemented in Kolla. -.. _Additional Environments: ./quickstart.rst#additional-environments -.. _multinode doc: ./multinode.rst -.. _dockerhub image: https://hub.docker.com/u/kollaglue/ -.. _image-building doc: ./image-building.rst +.. _Docker Hub Image Registry: https://hub.docker.com/u/kollaglue/ diff --git a/doc/selinux.rst b/doc/selinux.rst index 2affcd70bf..dd89a70cad 100644 --- a/doc/selinux.rst +++ b/doc/selinux.rst @@ -1,13 +1,16 @@ +.. _selinux: + +================ SELinux in Kolla ================ Overview --------- +======== The state of SELinux in Kolla is a work in progress. The short answer is you must disable it until selinux polices are written for the Docker containers. The Long Answer ---------------- +=============== To understand why Kolla needs to set certain selinux policies for services that you wouldn't expect to need them (rabbitmq, mariadb, glance, etc.) we must take a step back and talk about Docker. diff --git a/doc/swift-guide.rst b/doc/swift-guide.rst index 87bbdb1af2..6531fc88df 100644 --- a/doc/swift-guide.rst +++ b/doc/swift-guide.rst @@ -1,18 +1,21 @@ +.. _swift-guide: + +============== Swift in Kolla ============== Overview --------- +======== Kolla can deploy a full working Swift setup in either a AIO or multi node setup. Prerequisites -------------- +============= Before running Swift we need to generate "rings", which are binary compressed files that at a high level let the various Swift services know where data is in the cluster. We hope to automate this process in a future release. Disks with a partition table (recommended) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +========================================== Swift also expects block devices to be available for storage. To prepare a disk for use as Swift storage device, a special partition name and filesystem label @@ -45,7 +48,7 @@ For evaluation, loopback devices can be used in lieu of real disks: done Disks without a partition table -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=============================== Kolla also supports unpartitioned disk (filesystem on /dev/sdc instead of /dev/sdc1) detection purely based on filesystem label. This is generally not a @@ -61,7 +64,7 @@ ansible/roles/swift/defaults/main.yml swift_devices_name: "swd" Rings -~~~~~ +===== Run following commands locally to generate Rings for AIO demo setup. The commands work with "disks with partition table" example listed above. Please @@ -126,7 +129,7 @@ For more info, see http://docs.openstack.org/kilo/install-guide/install/apt/content/swift-initial-rings.html Deploying ---------- +========= Enable Swift in /etc/kolla/globals.yml: :: @@ -146,7 +149,7 @@ is the minimal command to bring up Swift AIO, and it's dependencies: --tags=rabbitmq,mariadb,keystone,swift Validation ----------- +========== A very basic smoke test: :: diff --git a/doc/vagrant-dev-env.rst b/doc/vagrant-dev-env.rst index 4bd6bf97c0..1d861156e4 100644 --- a/doc/vagrant-dev-env.rst +++ b/doc/vagrant-dev-env.rst @@ -1,3 +1,6 @@ +.. vagrant-dev-env: + +==================================== Development Environment with Vagrant ==================================== @@ -9,7 +12,7 @@ takes care of setting up CentOS-based VMs for Kolla development, each with proper hardware like memory amount and number of network interfaces. Getting Started ---------------- +=============== The Vagrant script implements All-in-One (AIO) or multi-node deployments. AIO is the default. @@ -91,7 +94,7 @@ The command ``vagrant status`` provides a quick overview of the VMs composing the environment. Vagrant Up ----------- +========== Once Vagrant has completed deploying all nodes, the next step is to launch Kolla. First, connect with the *operator* node:: @@ -110,9 +113,8 @@ a different docker binary to the cluster. The shared folder is also used to store the docker-registry files, so they are save from destructive operations like ``vagrant destroy``. - Building images -^^^^^^^^^^^^^^^ +--------------- Once logged on the *operator* VM call the ``kolla-build`` utility:: @@ -122,10 +124,8 @@ Once logged on the *operator* VM call the ``kolla-build`` utility:: builds Docker images and pushes them to the local registry if the *push* option is enabled (in Vagrant this is the default behaviour). - - Deploying OpenStack with Kolla -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +------------------------------ Deploy AIO with:: @@ -143,9 +143,8 @@ Validate OpenStack is operational:: Or navigate to http://10.10.10.254/ with a web browser. - Further Reading ---------------- +=============== All Vagrant documentation can be found at `docs.vagrantup.com `__.