From bbcf22cc1298dd0ad4f0826c9e1186298c64569e Mon Sep 17 00:00:00 2001 From: Steven Dake Date: Thu, 20 Aug 2015 23:00:55 -0700 Subject: Prepare for MD to RST conversion Sphinx and OpenStack documentation standards require the use of RST formatted documentation. In order to get out docs integrated into docs.openstack.org, the following steps must be taken: 1. we need to first convert the documentation to RST 2. sphinx support must be added to the repository 3. project-config must be updated with a publish-docs job The ability to pubish to docs.openstack.org is a privilege only available to Big Tent projects. As a result, we should be taking advantage of this to help spread the word on our implementation. Note the documentation was converted with a tool called pandoc the syntax of which was: pandoc -f markdown -t rst file.md > z mv z file.rst In order for git to preserve history the files have to be git mv'ed in one commit followed by the pandoc operation in a separate commit. Change-Id: Iba2a70b989e8305da03e8204a9b130d457b00cf0 --- docs/ansible-deployment.md | 102 -------------------------------------------- docs/ansible-deployment.rst | 102 ++++++++++++++++++++++++++++++++++++++++++++ docs/dev-quickstart.md | 76 --------------------------------- docs/dev-quickstart.rst | 76 +++++++++++++++++++++++++++++++++ docs/image-building.md | 77 --------------------------------- docs/image-building.rst | 77 +++++++++++++++++++++++++++++++++ docs/vagrant.md | 81 ----------------------------------- docs/vagrant.rst | 81 +++++++++++++++++++++++++++++++++++ 8 files changed, 336 insertions(+), 336 deletions(-) delete mode 100644 docs/ansible-deployment.md create mode 100644 docs/ansible-deployment.rst delete mode 100644 docs/dev-quickstart.md create mode 100644 docs/dev-quickstart.rst delete mode 100644 docs/image-building.md create mode 100644 docs/image-building.rst delete mode 100644 docs/vagrant.md create mode 100644 docs/vagrant.rst (limited to 'docs') diff --git a/docs/ansible-deployment.md b/docs/ansible-deployment.md deleted file mode 100644 index 9f277c2ab..000000000 --- a/docs/ansible-deployment.md +++ /dev/null @@ -1,102 +0,0 @@ -Kolla with Ansible! -============================ - -Kolla supports deploying Openstack using [Ansible][]. - -[Ansible]: https://docs.ansible.com - - -Getting Started ---------------- - -To run the Ansible playbooks, an inventory file which tracks all of the -available nodes in the environment must be speficied. With this inventory file -Ansible will log into each node via ssh (configurable) and run tasks. Ansible -does not require password-less logins via ssh, however it is highly recommended -to setup ssh-keys. - -Two sample inventory files are provided, *all-in-one*, and *multinode*. The -"all-in-one" inventory defaults to use the Ansible "local" connection type, -which removes the need to setup ssh keys in order to get started quickly. - -More information on the Ansible inventory file can be found [here][]. - -[here]: https://docs.ansible.com/intro_inventory.html - -Prerequisites -------------- - -On the deployment host you must have Ansible>=1.8.4 installed. That is the only -requirement for deploying. To build the images locally you must also have the -Python library docker-py>=1.2.0 installed. - -On the target nodes you must have docker>=1.6.0 and docker-py>=1.2.0 installed. - -Deploying ---------- - -Add the etc/kolla directory to /etc/kolla on the deployment host. Inside of -this directory are two files and a minimum number of parameters which are -listed below. - -All variables for the environment can be specified in the files: -"/etc/kolla/globals.yml" and "/etc/kolla/passwords.yml" - -The kolla_*_address variables can both be the same. Please specify an unused IP -address in your network to act as a VIP for kolla_internal_address. The VIP will -be used with keepalived and added to your "api_interface" as specified in the -globals.yml - - kolla_external_address: "openstack.example.com" - kolla_internal_address: "10.10.10.254" - -The "network_interface" variable is the interface that we bind all our services -to. For example, when starting up Mariadb it will bind to the IP on the -interface list in the "network_interface" variable. - - network_interface: "eth0" - -The "neutron_external_interface" variable is the interface that will be used for -your external bridge in Neutron. Without this bridge your instance traffic will -be unable to access the rest of the Internet. In the case of a single interface -on a machine, you may use a veth pair where one end of the veth pair is listed -here and the other end is in a bridge on your system. - - neutron_external_interface: "eth1" - -The docker_pull_policy specifies whether Docker should always pull images from -the repository it is configured for, or only in the case where the image isn't -present locally. If you are building your own images locally without pushing -them to the Docker Registry, or a local registry, you must set this value to -"missing" or when you run the playbooks docker will attempt to fetch the latest -image upstream. - - docker_pull_policy: "always" - -For All-In-One deploys, the following commands can be run. These will setup all -of the containers on the localhost. These commands will be wrapped in the -kolla-script in the future. - - cd ./kolla/ansible - ansible-playbook -i inventory/all-in-one -e @/etc/kolla/globals.yml -e @/etc/kolla/passwords.yml site.yml - -To run the playbooks for only a particular service, Ansible tags can be used. -Multiple tags may be specified, and order is still determined by the playbooks. - - cd ./kolla/ansible - ansible-playbook -i inventory/all-in-one -e @/etc/kolla/globals.yml -e @/etc/kolla/passwords.yml site.yml --tags rabbitmq - ansible-playbook -i inventory/all-in-one -e @/etc/kolla/globals.yml -e @/etc/kolla/passwords.yml site.yml --tags rabbitmq,mariadb - -Finally, you can view ./kolla/tools/openrc-example for an example of an openrc -you can use with your environment. If you wish you may also run the following -command to initiate your environment with an glance image and neutron networks. - - cd ./kolla/tools - ./init-runonce - -Further Reading ---------------- - -Ansible playbook documentation can be found [here][]. - -[here]: http://docs.ansible.com/playbooks.html diff --git a/docs/ansible-deployment.rst b/docs/ansible-deployment.rst new file mode 100644 index 000000000..9f277c2ab --- /dev/null +++ b/docs/ansible-deployment.rst @@ -0,0 +1,102 @@ +Kolla with Ansible! +============================ + +Kolla supports deploying Openstack using [Ansible][]. + +[Ansible]: https://docs.ansible.com + + +Getting Started +--------------- + +To run the Ansible playbooks, an inventory file which tracks all of the +available nodes in the environment must be speficied. With this inventory file +Ansible will log into each node via ssh (configurable) and run tasks. Ansible +does not require password-less logins via ssh, however it is highly recommended +to setup ssh-keys. + +Two sample inventory files are provided, *all-in-one*, and *multinode*. The +"all-in-one" inventory defaults to use the Ansible "local" connection type, +which removes the need to setup ssh keys in order to get started quickly. + +More information on the Ansible inventory file can be found [here][]. + +[here]: https://docs.ansible.com/intro_inventory.html + +Prerequisites +------------- + +On the deployment host you must have Ansible>=1.8.4 installed. That is the only +requirement for deploying. To build the images locally you must also have the +Python library docker-py>=1.2.0 installed. + +On the target nodes you must have docker>=1.6.0 and docker-py>=1.2.0 installed. + +Deploying +--------- + +Add the etc/kolla directory to /etc/kolla on the deployment host. Inside of +this directory are two files and a minimum number of parameters which are +listed below. + +All variables for the environment can be specified in the files: +"/etc/kolla/globals.yml" and "/etc/kolla/passwords.yml" + +The kolla_*_address variables can both be the same. Please specify an unused IP +address in your network to act as a VIP for kolla_internal_address. The VIP will +be used with keepalived and added to your "api_interface" as specified in the +globals.yml + + kolla_external_address: "openstack.example.com" + kolla_internal_address: "10.10.10.254" + +The "network_interface" variable is the interface that we bind all our services +to. For example, when starting up Mariadb it will bind to the IP on the +interface list in the "network_interface" variable. + + network_interface: "eth0" + +The "neutron_external_interface" variable is the interface that will be used for +your external bridge in Neutron. Without this bridge your instance traffic will +be unable to access the rest of the Internet. In the case of a single interface +on a machine, you may use a veth pair where one end of the veth pair is listed +here and the other end is in a bridge on your system. + + neutron_external_interface: "eth1" + +The docker_pull_policy specifies whether Docker should always pull images from +the repository it is configured for, or only in the case where the image isn't +present locally. If you are building your own images locally without pushing +them to the Docker Registry, or a local registry, you must set this value to +"missing" or when you run the playbooks docker will attempt to fetch the latest +image upstream. + + docker_pull_policy: "always" + +For All-In-One deploys, the following commands can be run. These will setup all +of the containers on the localhost. These commands will be wrapped in the +kolla-script in the future. + + cd ./kolla/ansible + ansible-playbook -i inventory/all-in-one -e @/etc/kolla/globals.yml -e @/etc/kolla/passwords.yml site.yml + +To run the playbooks for only a particular service, Ansible tags can be used. +Multiple tags may be specified, and order is still determined by the playbooks. + + cd ./kolla/ansible + ansible-playbook -i inventory/all-in-one -e @/etc/kolla/globals.yml -e @/etc/kolla/passwords.yml site.yml --tags rabbitmq + ansible-playbook -i inventory/all-in-one -e @/etc/kolla/globals.yml -e @/etc/kolla/passwords.yml site.yml --tags rabbitmq,mariadb + +Finally, you can view ./kolla/tools/openrc-example for an example of an openrc +you can use with your environment. If you wish you may also run the following +command to initiate your environment with an glance image and neutron networks. + + cd ./kolla/tools + ./init-runonce + +Further Reading +--------------- + +Ansible playbook documentation can be found [here][]. + +[here]: http://docs.ansible.com/playbooks.html diff --git a/docs/dev-quickstart.md b/docs/dev-quickstart.md deleted file mode 100644 index 2b79097e4..000000000 --- a/docs/dev-quickstart.md +++ /dev/null @@ -1,76 +0,0 @@ -# Developer Environment - -If you are developing Kolla on an existing OpenStack cloud that supports -Heat, then follow the Heat template [README][]. Another option available -on systems with VirutalBox is the use of [Vagrant][]. - -The best experience is available with bare metal deployment by following -the instructions below to manually create your Kolla deployment. - -[README]: https://github.com/stackforge/kolla/blob/master/devenv/README.md -[Vagrant]: https://github.com/stackforge/kolla/blob/master/docs/vagrant.md - -## Installing Dependencies - -NB: Kolla will not run on Fedora 22 or later. Fedora 22 compresses kernel -modules with the .xz compressed format. The guestfs system cannot read -these images because a dependent package supermin in CentOS needs to be -updated to add .xz compressed format support. - -To install Kolla depenedencies use: - - git clone http://github.com/stackforge/kolla - cd kolla - sudo pip install -r requirements.txt - -In order to run Kolla, it is mandatory to run a version of `docker` that is -1.7.0 or later. - -For most systems you can install the latest stable version of Docker with the -following command: - - curl -sSL https://get.docker.io | bash - -For Ubuntu based systems, do not use AUFS when starting Docker daemon unless -you are running the Utopic (3.19) kernel. AUFS requires CONFIG_AUFS_XATTR=y -set when building the kernel. On Ubuntu, versions prior to 3.19 did not set that -flag. If you are unable to upgrade your kernel, you should use a different -storage backend such as btrfs. - -Next, install the OpenStack python clients if they are not installed: - - sudo pip install -U python-openstackclient - -Finally stop libvirt on the host machine. Only one copy of libvirt may be -running at a time. - - service libvirtd stop - -The basic starting environment will be created using `ansible`. -This environment will start up the OpenStack services listed in the -inventory file. - -## Starting Kolla - -Configure Ansible by reading the Kolla Ansible configuration documentation -[DEPLOY][]. - -[DEPLOY]: https://github.com/stackforge/kolla/blob/master/docs/ansible-deployment.md - -Next, run the start command: - - $ sudo ./tools/kolla-ansible deploy - -A bare metal system takes three minutes to deploy AIO. A virtual machine -takes five minutes to deploy AIO. These are estimates; your hardware may -be faster or slower but should near these results. - -## Debugging Kolla - -You can determine a container's status by executing: - - $ sudo docker ps -a - -If any of the containers exited you can check the logs by executing: - - $ sudo docker logs diff --git a/docs/dev-quickstart.rst b/docs/dev-quickstart.rst new file mode 100644 index 000000000..2b79097e4 --- /dev/null +++ b/docs/dev-quickstart.rst @@ -0,0 +1,76 @@ +# Developer Environment + +If you are developing Kolla on an existing OpenStack cloud that supports +Heat, then follow the Heat template [README][]. Another option available +on systems with VirutalBox is the use of [Vagrant][]. + +The best experience is available with bare metal deployment by following +the instructions below to manually create your Kolla deployment. + +[README]: https://github.com/stackforge/kolla/blob/master/devenv/README.md +[Vagrant]: https://github.com/stackforge/kolla/blob/master/docs/vagrant.md + +## Installing Dependencies + +NB: Kolla will not run on Fedora 22 or later. Fedora 22 compresses kernel +modules with the .xz compressed format. The guestfs system cannot read +these images because a dependent package supermin in CentOS needs to be +updated to add .xz compressed format support. + +To install Kolla depenedencies use: + + git clone http://github.com/stackforge/kolla + cd kolla + sudo pip install -r requirements.txt + +In order to run Kolla, it is mandatory to run a version of `docker` that is +1.7.0 or later. + +For most systems you can install the latest stable version of Docker with the +following command: + + curl -sSL https://get.docker.io | bash + +For Ubuntu based systems, do not use AUFS when starting Docker daemon unless +you are running the Utopic (3.19) kernel. AUFS requires CONFIG_AUFS_XATTR=y +set when building the kernel. On Ubuntu, versions prior to 3.19 did not set that +flag. If you are unable to upgrade your kernel, you should use a different +storage backend such as btrfs. + +Next, install the OpenStack python clients if they are not installed: + + sudo pip install -U python-openstackclient + +Finally stop libvirt on the host machine. Only one copy of libvirt may be +running at a time. + + service libvirtd stop + +The basic starting environment will be created using `ansible`. +This environment will start up the OpenStack services listed in the +inventory file. + +## Starting Kolla + +Configure Ansible by reading the Kolla Ansible configuration documentation +[DEPLOY][]. + +[DEPLOY]: https://github.com/stackforge/kolla/blob/master/docs/ansible-deployment.md + +Next, run the start command: + + $ sudo ./tools/kolla-ansible deploy + +A bare metal system takes three minutes to deploy AIO. A virtual machine +takes five minutes to deploy AIO. These are estimates; your hardware may +be faster or slower but should near these results. + +## Debugging Kolla + +You can determine a container's status by executing: + + $ sudo docker ps -a + +If any of the containers exited you can check the logs by executing: + + $ sudo docker logs diff --git a/docs/image-building.md b/docs/image-building.md deleted file mode 100644 index a67f3da08..000000000 --- a/docs/image-building.md +++ /dev/null @@ -1,77 +0,0 @@ -# Image building - -The `tools/build-docker-image` script in this repository is -responsible for building docker images. It is symlinked as `./build` -inside each Docker image directory. - -When creating new image directories, you can run the -`tools/update-build-links` scripts to install the `build` symlink -(this script will install the symlink anywhere it find a file named -`Dockerfile`). - -## Workflow - -In general, you will build images like this: - - $ cd docker/keystone - $ ./build - -By default, the above command would build -`kollaglue/centos-rdo-keystone:CID`, where `CID` is the current short -commit ID. That is, given: - - $ git rev-parse HEAD - 76a16029006a2f5d3b79f1198d81acb6653110e9 - -The above command would generate -`kollaglue/centos-rdo-keystone:76a1602`. This tagging is meant to -prevent developers from stepping on each other or on release images -during the development process. - -To push the image after building, add `--push`: - - $ ./build --push - -To use these images, you must specify the tag in your `docker run` -commands: - - $ docker run kollaglue/centos-rdo-keystone:76a1602 - -## Building releases - -To build into the `latest` tag, add `--release`: - - $ ./build --release - -Or to build and push: - - $ ./build --push --release - -## Build all images at once - -The `build-all-docker-images` script in the tools directory is a wrapper for -the `build-docker-image` that builds all images, as the name suggests, in the -correct order. It responds to the same options as `build-docker-image` with the -additional `--from` and `--to` options that allows building only images that -have changed between the specified git revisions. - -For example, to build all images contained in docker directory and push new release: - - $ tools/build-all-docker-images --release --push - -To build only images modified in test-branch along with their children: - - $ tools/build-all-docker-images --from master --to test-branch - -## Configuration - -The `build-docker-image` script will look for a file named `.buildconf` -in the image directory and in the top level of the repository. You -can use this to set defaults, such as: - - NAMESPACE=larsks - PREFIX=fedora-rdo- - -This setting would cause images to be tagged into the `larsks/` -namespace and use Fedora as base image instead of the default CentOS. - diff --git a/docs/image-building.rst b/docs/image-building.rst new file mode 100644 index 000000000..a67f3da08 --- /dev/null +++ b/docs/image-building.rst @@ -0,0 +1,77 @@ +# Image building + +The `tools/build-docker-image` script in this repository is +responsible for building docker images. It is symlinked as `./build` +inside each Docker image directory. + +When creating new image directories, you can run the +`tools/update-build-links` scripts to install the `build` symlink +(this script will install the symlink anywhere it find a file named +`Dockerfile`). + +## Workflow + +In general, you will build images like this: + + $ cd docker/keystone + $ ./build + +By default, the above command would build +`kollaglue/centos-rdo-keystone:CID`, where `CID` is the current short +commit ID. That is, given: + + $ git rev-parse HEAD + 76a16029006a2f5d3b79f1198d81acb6653110e9 + +The above command would generate +`kollaglue/centos-rdo-keystone:76a1602`. This tagging is meant to +prevent developers from stepping on each other or on release images +during the development process. + +To push the image after building, add `--push`: + + $ ./build --push + +To use these images, you must specify the tag in your `docker run` +commands: + + $ docker run kollaglue/centos-rdo-keystone:76a1602 + +## Building releases + +To build into the `latest` tag, add `--release`: + + $ ./build --release + +Or to build and push: + + $ ./build --push --release + +## Build all images at once + +The `build-all-docker-images` script in the tools directory is a wrapper for +the `build-docker-image` that builds all images, as the name suggests, in the +correct order. It responds to the same options as `build-docker-image` with the +additional `--from` and `--to` options that allows building only images that +have changed between the specified git revisions. + +For example, to build all images contained in docker directory and push new release: + + $ tools/build-all-docker-images --release --push + +To build only images modified in test-branch along with their children: + + $ tools/build-all-docker-images --from master --to test-branch + +## Configuration + +The `build-docker-image` script will look for a file named `.buildconf` +in the image directory and in the top level of the repository. You +can use this to set defaults, such as: + + NAMESPACE=larsks + PREFIX=fedora-rdo- + +This setting would cause images to be tagged into the `larsks/` +namespace and use Fedora as base image instead of the default CentOS. + diff --git a/docs/vagrant.md b/docs/vagrant.md deleted file mode 100644 index b6f47f179..000000000 --- a/docs/vagrant.md +++ /dev/null @@ -1,81 +0,0 @@ -Vagrant up! -============================ - -This guide describes how to use [Vagrant][] to assist in developing for Kolla. - -Vagrant is a tool to assist in scripted creation of virtual machines, it will -take care of setting up a CentOS-based cluster of virtual machines, each with -proper hardware like memory amount and number of network interfaces. - -[Vagrant]: http://vagrantup.com - - -Getting Started ---------------- - -The vagrant setup will build a cluster with the following nodes: - -- 3 control nodes -- 1 compute node -- 1 operator node - -Kolla runs from the operator node to deploy OpenStack on the other nodes. - -All nodes are connected with each other on the secondary nic, the primary nic -is behind a NAT interface for connecting with the internet. A third nic is -connected without IP configuration to a public bridge interface. This may be -used for Neutron/Nova to connect to instances. - -Start with downloading and installing the Vagrant package for your distro of -choice. Various downloads can be found [here][]. After we will install the -hostmanager plugin so all hosts are recorded in /etc/hosts (inside each vm): - - vagrant plugin install vagrant-hostmanager - -Vagrant supports a wide range of virtualization technologies, of which we will -use VirtualBox for now. - -Find some place in your homedir and checkout the Kolla repo - - git clone https://github.com/stackforge/kolla.git ~/dev/kolla - -You can now tweak the Vagrantfile or start a CentOS7-based cluster right away: - - cd ~/dev/kolla/vagrant && vagrant up - -The command `vagrant up` will build your cluster, `vagrant status` will give -you a quick overview once done. - -[here]: https://www.vagrantup.com/downloads.html - -Vagrant Up ---------- - -Once vagrant has completed deploying all nodes, we can focus on launching Kolla. -First, connect with the _operator_ node: - - vagrant ssh operator - -Once connected you can run a simple Ansible-style ping to verify if the cluster is operable: - - ansible -i kolla/ansible/inventory/multinode all -m ping -e ansible_ssh_user=root - -Congratulations, your cluster is usable and you can start deploying OpenStack using Ansible! - -To speed things up, there is a local registry running on the operator. All nodes are configured -so they can use this insecure repo to pull from, and they will use it as mirror. Ansible may -use this registry to pull images from. - -All nodes have a local folder shared between the group and the hypervisor, and a folder shared -between _all_ nodes and the hypervisor. This mapping is lost after reboots, so make sure you use -the command `vagrant reload ` when reboots are required. Having this shared folder you -have a method to supply 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`. - -Further Reading ---------------- - -All Vagrant documentation can be found on their [website][]. - -[website]: http://docs.vagrantup.com diff --git a/docs/vagrant.rst b/docs/vagrant.rst new file mode 100644 index 000000000..b6f47f179 --- /dev/null +++ b/docs/vagrant.rst @@ -0,0 +1,81 @@ +Vagrant up! +============================ + +This guide describes how to use [Vagrant][] to assist in developing for Kolla. + +Vagrant is a tool to assist in scripted creation of virtual machines, it will +take care of setting up a CentOS-based cluster of virtual machines, each with +proper hardware like memory amount and number of network interfaces. + +[Vagrant]: http://vagrantup.com + + +Getting Started +--------------- + +The vagrant setup will build a cluster with the following nodes: + +- 3 control nodes +- 1 compute node +- 1 operator node + +Kolla runs from the operator node to deploy OpenStack on the other nodes. + +All nodes are connected with each other on the secondary nic, the primary nic +is behind a NAT interface for connecting with the internet. A third nic is +connected without IP configuration to a public bridge interface. This may be +used for Neutron/Nova to connect to instances. + +Start with downloading and installing the Vagrant package for your distro of +choice. Various downloads can be found [here][]. After we will install the +hostmanager plugin so all hosts are recorded in /etc/hosts (inside each vm): + + vagrant plugin install vagrant-hostmanager + +Vagrant supports a wide range of virtualization technologies, of which we will +use VirtualBox for now. + +Find some place in your homedir and checkout the Kolla repo + + git clone https://github.com/stackforge/kolla.git ~/dev/kolla + +You can now tweak the Vagrantfile or start a CentOS7-based cluster right away: + + cd ~/dev/kolla/vagrant && vagrant up + +The command `vagrant up` will build your cluster, `vagrant status` will give +you a quick overview once done. + +[here]: https://www.vagrantup.com/downloads.html + +Vagrant Up +--------- + +Once vagrant has completed deploying all nodes, we can focus on launching Kolla. +First, connect with the _operator_ node: + + vagrant ssh operator + +Once connected you can run a simple Ansible-style ping to verify if the cluster is operable: + + ansible -i kolla/ansible/inventory/multinode all -m ping -e ansible_ssh_user=root + +Congratulations, your cluster is usable and you can start deploying OpenStack using Ansible! + +To speed things up, there is a local registry running on the operator. All nodes are configured +so they can use this insecure repo to pull from, and they will use it as mirror. Ansible may +use this registry to pull images from. + +All nodes have a local folder shared between the group and the hypervisor, and a folder shared +between _all_ nodes and the hypervisor. This mapping is lost after reboots, so make sure you use +the command `vagrant reload ` when reboots are required. Having this shared folder you +have a method to supply 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`. + +Further Reading +--------------- + +All Vagrant documentation can be found on their [website][]. + +[website]: http://docs.vagrantup.com -- cgit v1.2.3