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 --- README.md | 107 ----------------------- README.rst | 107 +++++++++++++++++++++++ compose/README.md | 29 ------- compose/README.rst | 29 +++++++ demos/heat/README.md | 13 --- demos/heat/README.rst | 13 +++ demos/magnum/redis-kube/README.md | 115 ------------------------- demos/magnum/redis-kube/README.rst | 115 +++++++++++++++++++++++++ devenv/README.md | 169 ------------------------------------- devenv/README.rst | 169 +++++++++++++++++++++++++++++++++++++ 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 ++++++++++++++++++ 18 files changed, 769 insertions(+), 769 deletions(-) delete mode 100644 README.md create mode 100644 README.rst delete mode 100644 compose/README.md create mode 100644 compose/README.rst delete mode 100644 demos/heat/README.md create mode 100644 demos/heat/README.rst delete mode 100644 demos/magnum/redis-kube/README.md create mode 100644 demos/magnum/redis-kube/README.rst delete mode 100644 devenv/README.md create mode 100644 devenv/README.rst 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 diff --git a/README.md b/README.md deleted file mode 100644 index c7e1ce0c5..000000000 --- a/README.md +++ /dev/null @@ -1,107 +0,0 @@ -Kolla Overview -============== - -The Kolla project is a member of the OpenStack [Big Tent Governance][]. -Kolla's mission statement is: - - Kolla provides production-ready containers and deployment tools for - operating OpenStack clouds. - -Kolla provides [Docker][] containers and [Ansible][] playbooks to meet Kolla's -mission. Kolla is highly opinionated out of the box, but allows for complete -customization. This permits operators with little experience to deploy -OpenStack quickly and as experience grows modify the OpenStack configuration -to suit the operator's exact requirements. - -[Big Tent Governance]: http://governance.openstack.org/reference/projects/index.html -[Docker]: http://docker.com/ -[Ansible]: http://ansible.com/ - -Getting Started -=============== - -Please get started by reading the [Developer Quickstart][] followed by the -[Ansible Deployment Guide][]. - -[Developer Quickstart]: https://github.com/stackforge/kolla/blob/master/docs/dev-quickstart.md -[Ansible Deployment guide]: https://github.com/stackforge/kolla/blob/master/docs/ansible-deployment.md] - -Docker Images -------------- - -The [Docker images][] are built by the Kolla project maintainers. A detailed -process for contributing to the images can be found in the -[image building guide][]. Images reside in the Docker Hub [Kollaglue repo][]. - -[image building guide]: https://github.com/stackforge/kolla/blob/master/docs/image-building.md -[Docker images]: https://docs.docker.com/userguide/dockerimages/ -[Kollaglue repo]: https://registry.hub.docker.com/repos/kollaglue/ - -The Kolla developers build images in the kollaglue namespace for the following -services for every tagged release and implement Ansible deployment for them: - -* Ceilometer -* Cinder -* Glance -* Haproxy -* Heat -* Horizon -* Keepalived -* Keystone -* Mariadb + galera -* Mongodb -* Neutron (linuxbridge or neutron) -* Nova -* Openvswitch -* Rabbitmq - -``` -$ sudo docker search kollaglue -``` -A list of the upstream built docker images will be shown. - -Directories -=========== - -* ansible - Contains Anible playbooks to deploy Kolla in Docker containers. -* compose - Contains the docker-compose files serving as a compose reference. - Note compose support is removed from Kolla. These are for community members - which want to use Kolla container content without Ansible. -* demos - Contains a few demos to use with Kolla. -* devenv - Contains an OpenStack-Heat based development environment. -* docker - Contains a normal Dockerfile based set of artifacts for building - docker. This is planned for removal when docker_templates is completed. -* docs - Contains documentation. -* etc - Contains a reference etc directory structure which requires - configuration of a small number of configuration variables to achieve a - working All-in-One (AIO) deployment. -* docker_templates - Contains jinja2 templates for the docker build system. -* tools - Contains tools for interacting with Kolla. -* specs - Contains the Kolla communities key arguments about architectural - shifts in the code base. -* tests - Contains functional testing tools. -* vagrant - Contains a vagrant VirtualBox-based development environment. - -Getting Involved -================ - -Need a feature? Find a bug? Let us know! Contributions are much appreciated -and should follow the standard [Gerrit workflow][]. - -- We communicate using the #kolla irc channel. -- File bugs, blueprints, track releases, etc on [Launchpad][]. -- Attend weekly [meetings][]. -- Contribute [code][] - -[Gerrit workflow]: https://wiki.openstack.org/wiki/Gerrit_Workflow -[Launchpad]: https://launchpad.net/kolla -[meetings]: https://wiki.openstack.org/wiki/Meetings/Kolla -[code]: https://github.com/stackforge/kolla - -Contributors -============ - -Check out who's [contributing code][] and [contributing reviews][]. - -[contributing code]: http://stackalytics.com/?module=kolla-group&metric=commits -[contributing reviews]: http://stackalytics.com/?module=kolla-group&metric=marks diff --git a/README.rst b/README.rst new file mode 100644 index 000000000..c7e1ce0c5 --- /dev/null +++ b/README.rst @@ -0,0 +1,107 @@ +Kolla Overview +============== + +The Kolla project is a member of the OpenStack [Big Tent Governance][]. +Kolla's mission statement is: + + Kolla provides production-ready containers and deployment tools for + operating OpenStack clouds. + +Kolla provides [Docker][] containers and [Ansible][] playbooks to meet Kolla's +mission. Kolla is highly opinionated out of the box, but allows for complete +customization. This permits operators with little experience to deploy +OpenStack quickly and as experience grows modify the OpenStack configuration +to suit the operator's exact requirements. + +[Big Tent Governance]: http://governance.openstack.org/reference/projects/index.html +[Docker]: http://docker.com/ +[Ansible]: http://ansible.com/ + +Getting Started +=============== + +Please get started by reading the [Developer Quickstart][] followed by the +[Ansible Deployment Guide][]. + +[Developer Quickstart]: https://github.com/stackforge/kolla/blob/master/docs/dev-quickstart.md +[Ansible Deployment guide]: https://github.com/stackforge/kolla/blob/master/docs/ansible-deployment.md] + +Docker Images +------------- + +The [Docker images][] are built by the Kolla project maintainers. A detailed +process for contributing to the images can be found in the +[image building guide][]. Images reside in the Docker Hub [Kollaglue repo][]. + +[image building guide]: https://github.com/stackforge/kolla/blob/master/docs/image-building.md +[Docker images]: https://docs.docker.com/userguide/dockerimages/ +[Kollaglue repo]: https://registry.hub.docker.com/repos/kollaglue/ + +The Kolla developers build images in the kollaglue namespace for the following +services for every tagged release and implement Ansible deployment for them: + +* Ceilometer +* Cinder +* Glance +* Haproxy +* Heat +* Horizon +* Keepalived +* Keystone +* Mariadb + galera +* Mongodb +* Neutron (linuxbridge or neutron) +* Nova +* Openvswitch +* Rabbitmq + +``` +$ sudo docker search kollaglue +``` +A list of the upstream built docker images will be shown. + +Directories +=========== + +* ansible - Contains Anible playbooks to deploy Kolla in Docker containers. +* compose - Contains the docker-compose files serving as a compose reference. + Note compose support is removed from Kolla. These are for community members + which want to use Kolla container content without Ansible. +* demos - Contains a few demos to use with Kolla. +* devenv - Contains an OpenStack-Heat based development environment. +* docker - Contains a normal Dockerfile based set of artifacts for building + docker. This is planned for removal when docker_templates is completed. +* docs - Contains documentation. +* etc - Contains a reference etc directory structure which requires + configuration of a small number of configuration variables to achieve a + working All-in-One (AIO) deployment. +* docker_templates - Contains jinja2 templates for the docker build system. +* tools - Contains tools for interacting with Kolla. +* specs - Contains the Kolla communities key arguments about architectural + shifts in the code base. +* tests - Contains functional testing tools. +* vagrant - Contains a vagrant VirtualBox-based development environment. + +Getting Involved +================ + +Need a feature? Find a bug? Let us know! Contributions are much appreciated +and should follow the standard [Gerrit workflow][]. + +- We communicate using the #kolla irc channel. +- File bugs, blueprints, track releases, etc on [Launchpad][]. +- Attend weekly [meetings][]. +- Contribute [code][] + +[Gerrit workflow]: https://wiki.openstack.org/wiki/Gerrit_Workflow +[Launchpad]: https://launchpad.net/kolla +[meetings]: https://wiki.openstack.org/wiki/Meetings/Kolla +[code]: https://github.com/stackforge/kolla + +Contributors +============ + +Check out who's [contributing code][] and [contributing reviews][]. + +[contributing code]: http://stackalytics.com/?module=kolla-group&metric=commits +[contributing reviews]: http://stackalytics.com/?module=kolla-group&metric=marks diff --git a/compose/README.md b/compose/README.md deleted file mode 100644 index 6300ff5b9..000000000 --- a/compose/README.md +++ /dev/null @@ -1,29 +0,0 @@ -Docker compose -============== - -These scripts and docker compose files can be used to stand up a simple -installation of openstack. Running the 'tools/genenv' script creates an -'openstack.env' suitable for running on a single host system as well as an -'openrc' to allow access to the installation. - -Once you have run that you can either manually start the containers using the -'docker-compose' command or try the 'tools/kolla-compose start' script which tries to -start them all in a reasonable order, waiting at key points for services to -become available. Once stood up you can issue the typical openstack commands -to use the installation. If using nova networking use: - -``` -# source openrc -# tools/init-runonce -# nova boot --flavor m1.medium --key_name mykey --image puffy_clouds instance_name -# ssh cirros@ -``` - -Else if using neutron networking use: - -``` -# source openrc -# tools/init-runonce -# nova boot --flavor m1.medium --key_name mykey --image puffy_clouds instance_name --nic net-id: -# ssh cirros@ -``` diff --git a/compose/README.rst b/compose/README.rst new file mode 100644 index 000000000..6300ff5b9 --- /dev/null +++ b/compose/README.rst @@ -0,0 +1,29 @@ +Docker compose +============== + +These scripts and docker compose files can be used to stand up a simple +installation of openstack. Running the 'tools/genenv' script creates an +'openstack.env' suitable for running on a single host system as well as an +'openrc' to allow access to the installation. + +Once you have run that you can either manually start the containers using the +'docker-compose' command or try the 'tools/kolla-compose start' script which tries to +start them all in a reasonable order, waiting at key points for services to +become available. Once stood up you can issue the typical openstack commands +to use the installation. If using nova networking use: + +``` +# source openrc +# tools/init-runonce +# nova boot --flavor m1.medium --key_name mykey --image puffy_clouds instance_name +# ssh cirros@ +``` + +Else if using neutron networking use: + +``` +# source openrc +# tools/init-runonce +# nova boot --flavor m1.medium --key_name mykey --image puffy_clouds instance_name --nic net-id: +# ssh cirros@ +``` diff --git a/demos/heat/README.md b/demos/heat/README.md deleted file mode 100644 index 78236ac1f..000000000 --- a/demos/heat/README.md +++ /dev/null @@ -1,13 +0,0 @@ -A Kolla Demo using Heat -======================= - -By default, the launch script will spawn 3 Nova instances on a -Neutron network created from the tools/init-runonce script. Edit -the VM_COUNT parameter in the launch script if you would like to -spawn a different amount of Nova instances. Edit the IMAGE_FLAVOR -if you would like to launch images using a flavor other than -m1.tiny. - -Then run the script: - - $ ./launch diff --git a/demos/heat/README.rst b/demos/heat/README.rst new file mode 100644 index 000000000..78236ac1f --- /dev/null +++ b/demos/heat/README.rst @@ -0,0 +1,13 @@ +A Kolla Demo using Heat +======================= + +By default, the launch script will spawn 3 Nova instances on a +Neutron network created from the tools/init-runonce script. Edit +the VM_COUNT parameter in the launch script if you would like to +spawn a different amount of Nova instances. Edit the IMAGE_FLAVOR +if you would like to launch images using a flavor other than +m1.tiny. + +Then run the script: + + $ ./launch diff --git a/demos/magnum/redis-kube/README.md b/demos/magnum/redis-kube/README.md deleted file mode 100644 index 73e2dc50b..000000000 --- a/demos/magnum/redis-kube/README.md +++ /dev/null @@ -1,115 +0,0 @@ -## Reliable, Scalable Redis on Kubernetes - -The following document describes the deployment of a reliable, multi-node Redis on Kubernetes. It deploys a master with replicated slaves, as well as replicated redis sentinels which are use for health checking and failover. - -### Prerequisites -This example assumes that you have a Kubernetes cluster installed and running, and that you have installed the ```kubectl``` command line tool somewhere in your path. Please see the [getting started](https://github.com/GoogleCloudPlatform/kubernetes/tree/master/docs/getting-started-guides) for installation instructions for your platform. - -### A note for the impatient -This is a somewhat long tutorial. If you want to jump straight to the "do it now" commands, please see the [tl; dr](#tl-dr) at the end. - -### Turning up an initial master/sentinel pod. -is a [_Pod_](https://github.com/GoogleCloudPlatform/kubernetes/blob/master/docs/pods.md). A Pod is one or more containers that _must_ be scheduled onto the same host. All containers in a pod share a network namespace, and may optionally share mounted volumes. - -We will used the shared network namespace to bootstrap our Redis cluster. In particular, the very first sentinel needs to know how to find the master (subsequent sentinels just ask the first sentinel). Because all containers in a Pod share a network namespace, the sentinel can simply look at ```$(hostname -i):6379```. - -Here is the config for the initial master and sentinel pod: [redis-master.yaml](redis-master.yaml) - - -Create this master as follows: -```sh -kubectl create -f examples/redis/v1beta3/redis-master.yaml -``` - -### Turning up a sentinel service -In Kubernetes a _Service_ describes a set of Pods that perform the same task. For example, the set of nodes in a Cassandra cluster, or even the single node we created above. An important use for a Service is to create a load balancer which distributes traffic across members of the set. But a _Service_ can also be used as a standing query which makes a dynamically changing set of Pods (or the single Pod we've already created) available via the Kubernetes API. - -In Redis, we will use a Kubernetes Service to provide a discoverable endpoints for the Redis sentinels in the cluster. From the sentinels Redis clients can find the master, and then the slaves and other relevant info for the cluster. This enables new members to join the cluster when failures occur. - -Here is the definition of the sentinel service:[redis-sentinel-service.yaml](redis-sentinel-service.yaml) - -Create this service: -```sh -kubectl create -f examples/redis/v1beta3/redis-sentinel-service.yaml -``` - -### Turning up replicated redis servers -So far, what we have done is pretty manual, and not very fault-tolerant. If the ```redis-master``` pod that we previously created is destroyed for some reason (e.g. a machine dying) our Redis service goes away with it. - -In Kubernetes a _Replication Controller_ is responsible for replicating sets of identical pods. Like a _Service_ it has a selector query which identifies the members of it's set. Unlike a _Service_ it also has a desired number of replicas, and it will create or delete _Pods_ to ensure that the number of _Pods_ matches up with it's desired state. - -Replication Controllers will "adopt" existing pods that match their selector query, so let's create a Replication Controller with a single replica to adopt our existing Redis server. -[redis-controller.yaml](redis-controller.yaml) - -The bulk of this controller config is actually identical to the redis-master pod definition above. It forms the template or "cookie cutter" that defines what it means to be a member of this set. - -Create this controller: - -```sh -kubectl create -f examples/redis/v1beta3/redis-controller.yaml -``` - -We'll do the same thing for the sentinel. Here is the controller config:[redis-sentinel-controller.yaml](redis-sentinel-controller.yaml) - -We create it as follows: -```sh -kubectl create -f examples/redis/v1beta3/redis-sentinel-controller.yaml -``` - -### Resize our replicated pods -Initially creating those pods didn't actually do anything, since we only asked for one sentinel and one redis server, and they already existed, nothing changed. Now we will add more replicas: - -```sh -kubectl resize rc redis --replicas=3 -``` - -```sh -kubectl resize rc redis-sentinel --replicas=3 -``` - -This will create two additional replicas of the redis server and two additional replicas of the redis sentinel. - -Unlike our original redis-master pod, these pods exist independently, and they use the ```redis-sentinel-service``` that we defined above to discover and join the cluster. - -### Delete our manual pod -The final step in the cluster turn up is to delete the original redis-master pod that we created manually. While it was useful for bootstrapping discovery in the cluster, we really don't want the lifespan of our sentinel to be tied to the lifespan of one of our redis servers, and now that we have a successful, replicated redis sentinel service up and running, the binding is unnecessary. - -Delete the master as follows: -```sh -kubectl delete pods redis-master -``` - -Now let's take a close look at what happens after this pod is deleted. There are three things that happen: - - 1. The redis replication controller notices that its desired state is 3 replicas, but there are currently only 2 replicas, and so it creates a new redis server to bring the replica count back up to 3 - 2. The redis-sentinel replication controller likewise notices the missing sentinel, and also creates a new sentinel. - 3. The redis sentinels themselves, realize that the master has disappeared from the cluster, and begin the election procedure for selecting a new master. They perform this election and selection, and chose one of the existing redis server replicas to be the new master. - -### Conclusion -At this point we now have a reliable, scalable Redis installation. By resizing the replication controller for redis servers, we can increase or decrease the number of read-slaves in our cluster. Likewise, if failures occur, the redis-sentinels will perform master election and select a new master. - -### tl; dr -For those of you who are impatient, here is the summary of commands we ran in this tutorial - -```sh -# Create a bootstrap master -kubectl create -f examples/redis/v1beta3/redis-master.yaml - -# Create a service to track the sentinels -kubectl create -f examples/redis/v1beta3/redis-sentinel-service.yaml - -# Create a replication controller for redis servers -kubectl create -f examples/redis/v1beta3/redis-controller.yaml - -# Create a replication controller for redis sentinels -kubectl create -f examples/redis/v1beta3/redis-sentinel-controller.yaml - -# Resize both replication controllers -kubectl resize rc redis --replicas=3 -kubectl resize rc redis-sentinel --replicas=3 - -# Delete the original master pod -kubectl delete pods redis-master -``` - - diff --git a/demos/magnum/redis-kube/README.rst b/demos/magnum/redis-kube/README.rst new file mode 100644 index 000000000..73e2dc50b --- /dev/null +++ b/demos/magnum/redis-kube/README.rst @@ -0,0 +1,115 @@ +## Reliable, Scalable Redis on Kubernetes + +The following document describes the deployment of a reliable, multi-node Redis on Kubernetes. It deploys a master with replicated slaves, as well as replicated redis sentinels which are use for health checking and failover. + +### Prerequisites +This example assumes that you have a Kubernetes cluster installed and running, and that you have installed the ```kubectl``` command line tool somewhere in your path. Please see the [getting started](https://github.com/GoogleCloudPlatform/kubernetes/tree/master/docs/getting-started-guides) for installation instructions for your platform. + +### A note for the impatient +This is a somewhat long tutorial. If you want to jump straight to the "do it now" commands, please see the [tl; dr](#tl-dr) at the end. + +### Turning up an initial master/sentinel pod. +is a [_Pod_](https://github.com/GoogleCloudPlatform/kubernetes/blob/master/docs/pods.md). A Pod is one or more containers that _must_ be scheduled onto the same host. All containers in a pod share a network namespace, and may optionally share mounted volumes. + +We will used the shared network namespace to bootstrap our Redis cluster. In particular, the very first sentinel needs to know how to find the master (subsequent sentinels just ask the first sentinel). Because all containers in a Pod share a network namespace, the sentinel can simply look at ```$(hostname -i):6379```. + +Here is the config for the initial master and sentinel pod: [redis-master.yaml](redis-master.yaml) + + +Create this master as follows: +```sh +kubectl create -f examples/redis/v1beta3/redis-master.yaml +``` + +### Turning up a sentinel service +In Kubernetes a _Service_ describes a set of Pods that perform the same task. For example, the set of nodes in a Cassandra cluster, or even the single node we created above. An important use for a Service is to create a load balancer which distributes traffic across members of the set. But a _Service_ can also be used as a standing query which makes a dynamically changing set of Pods (or the single Pod we've already created) available via the Kubernetes API. + +In Redis, we will use a Kubernetes Service to provide a discoverable endpoints for the Redis sentinels in the cluster. From the sentinels Redis clients can find the master, and then the slaves and other relevant info for the cluster. This enables new members to join the cluster when failures occur. + +Here is the definition of the sentinel service:[redis-sentinel-service.yaml](redis-sentinel-service.yaml) + +Create this service: +```sh +kubectl create -f examples/redis/v1beta3/redis-sentinel-service.yaml +``` + +### Turning up replicated redis servers +So far, what we have done is pretty manual, and not very fault-tolerant. If the ```redis-master``` pod that we previously created is destroyed for some reason (e.g. a machine dying) our Redis service goes away with it. + +In Kubernetes a _Replication Controller_ is responsible for replicating sets of identical pods. Like a _Service_ it has a selector query which identifies the members of it's set. Unlike a _Service_ it also has a desired number of replicas, and it will create or delete _Pods_ to ensure that the number of _Pods_ matches up with it's desired state. + +Replication Controllers will "adopt" existing pods that match their selector query, so let's create a Replication Controller with a single replica to adopt our existing Redis server. +[redis-controller.yaml](redis-controller.yaml) + +The bulk of this controller config is actually identical to the redis-master pod definition above. It forms the template or "cookie cutter" that defines what it means to be a member of this set. + +Create this controller: + +```sh +kubectl create -f examples/redis/v1beta3/redis-controller.yaml +``` + +We'll do the same thing for the sentinel. Here is the controller config:[redis-sentinel-controller.yaml](redis-sentinel-controller.yaml) + +We create it as follows: +```sh +kubectl create -f examples/redis/v1beta3/redis-sentinel-controller.yaml +``` + +### Resize our replicated pods +Initially creating those pods didn't actually do anything, since we only asked for one sentinel and one redis server, and they already existed, nothing changed. Now we will add more replicas: + +```sh +kubectl resize rc redis --replicas=3 +``` + +```sh +kubectl resize rc redis-sentinel --replicas=3 +``` + +This will create two additional replicas of the redis server and two additional replicas of the redis sentinel. + +Unlike our original redis-master pod, these pods exist independently, and they use the ```redis-sentinel-service``` that we defined above to discover and join the cluster. + +### Delete our manual pod +The final step in the cluster turn up is to delete the original redis-master pod that we created manually. While it was useful for bootstrapping discovery in the cluster, we really don't want the lifespan of our sentinel to be tied to the lifespan of one of our redis servers, and now that we have a successful, replicated redis sentinel service up and running, the binding is unnecessary. + +Delete the master as follows: +```sh +kubectl delete pods redis-master +``` + +Now let's take a close look at what happens after this pod is deleted. There are three things that happen: + + 1. The redis replication controller notices that its desired state is 3 replicas, but there are currently only 2 replicas, and so it creates a new redis server to bring the replica count back up to 3 + 2. The redis-sentinel replication controller likewise notices the missing sentinel, and also creates a new sentinel. + 3. The redis sentinels themselves, realize that the master has disappeared from the cluster, and begin the election procedure for selecting a new master. They perform this election and selection, and chose one of the existing redis server replicas to be the new master. + +### Conclusion +At this point we now have a reliable, scalable Redis installation. By resizing the replication controller for redis servers, we can increase or decrease the number of read-slaves in our cluster. Likewise, if failures occur, the redis-sentinels will perform master election and select a new master. + +### tl; dr +For those of you who are impatient, here is the summary of commands we ran in this tutorial + +```sh +# Create a bootstrap master +kubectl create -f examples/redis/v1beta3/redis-master.yaml + +# Create a service to track the sentinels +kubectl create -f examples/redis/v1beta3/redis-sentinel-service.yaml + +# Create a replication controller for redis servers +kubectl create -f examples/redis/v1beta3/redis-controller.yaml + +# Create a replication controller for redis sentinels +kubectl create -f examples/redis/v1beta3/redis-sentinel-controller.yaml + +# Resize both replication controllers +kubectl resize rc redis --replicas=3 +kubectl resize rc redis-sentinel --replicas=3 + +# Delete the original master pod +kubectl delete pods redis-master +``` + + diff --git a/devenv/README.md b/devenv/README.md deleted file mode 100644 index 53f0a3417..000000000 --- a/devenv/README.md +++ /dev/null @@ -1,169 +0,0 @@ -A Kolla Cluster with Heat -========================= - -These [Heat][] templates will deploy an *N*-node [Kolla][] cluster, -where *N* is the value of the `number_of_nodes` parameter you -specify when creating the stack. - -Kolla has recently undergone a considerable design change. The details -of the design change is addressed in this [spec][]. As part of the -design change, containers share pid and networking namespaces with -the Docker host. Therefore, containers no longer connect to a docker0 -bridge and have separate networking from the host. As a result, Kolla -networking has a configuration similar to: - -![Image](https://raw.githubusercontent.com/stackforge/kolla/master/devenv/kollanet.png) - -Sharing pid and networking namespaces is detailed in the -[super privileged containers][] concept. - -The Kolla cluster is based on Fedora 21, requires the minimum Docker version of 1.7.0 -[binary][]. - -These templates are designed to work with the Icehouse or Juno -versions of Heat. If using Icehouse Heat, this [patch][] is -required to correct a bug with template validation when using the -"Fn::Join" function). - -[heat]: https://wiki.openstack.org/wiki/Heat -[kolla]: https://launchpad.net/kolla -[binary]: https://docs.docker.com/installation/binaries/ -[copr]: https://copr.fedoraproject.org/ -[spec]: https://review.openstack.org/#/c/153798/ -[super privileged containers]: http://sdake.io/2015/01/28/an-atomic-upgrade-process-for-openstack-compute-nodes/ -[patch]: https://review.openstack.org/#/c/121139/ - -Create the Glance Image -======================= - -After cloning the project, run the get-image.sh script from the project's -devenv directory: - - $ ./get-image.sh - -The script will create a Fedora 21 image with the required modifications. - -Add the image to your Glance image store: - - $ glance image-create --name "fedora-21-x86_64" \ - --file /var/lib/libvirt/images/fedora-21-x86_64 \ - --disk-format qcow2 --container-format bare \ - --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 -local.yaml: - - parameters: - ssh_key_name: admin-key - external_network_id: 028d70dd-67b8-4901-8bdd-0c62b06cce2d - container_external_network_id: 028d70dd-67b8-4901-8bdd-0c62b06cce2d - container_external_subnet_id: 575770dd-6828-1101-34dd-0c62b06fjf8s - dns_nameserver: 192.168.200.1 - -The external_network_id is used by Heat to automatically assign -floating IP's to your Kolla nodes. You can then access your Kolla nodes -directly using the floating IP. The network ID is derived from the -`neutron net-list` command. - -The container_external_network_id is used by the nova-network container -within the Kolla node as the FLAT_INTERFACE. The FLAT_INTERFACE tells Nova what -device to use (i.e. eth1) to pass network traffic between Nova instances -across Kolla nodes. This network should be seperate from the external_network_id -above and is derived from the 'neutron net-list' command. - -The container_external_subnet_id: is the subnet equivalent to -container_external_network_id - -Review the parameters section of kollacluster.yaml for a full list of -configuration options. **Note:** You must provide values for: - -- `ssh_key_name` -- `external_network_id` -- `container_external_network_id` -- `container_external_subnet_id` - -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: - - $ heat output-show kolla-cluster kolla_node_external_ip - "192.168.200.86" - -You can ssh into that server as the `fedora` user: - - $ ssh fedora@192.168.200.86 - -Once logged into your Kolla node, setup your environment. -The basic starting environment will be created using `docker-compose`. -This environment will start up the openstack services listed in the -compose directory. - -To start, setup your environment variables. - - $ cd kolla - $ ./tools/genenv - -The `genenv` script will create a compose/openstack.env file -and an openrc file in your current directory. The openstack.env -file contains all of your initialized environment variables, which -you can edit for a different setup. - -Next, run the start script. - - $ ./tools/kolla-compose start - -The `start` script is responsible for starting the containers -using `docker-compose -f up -d`. - -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 binaray, -by default this is `/`. - -A few commands for debugging the system. - -``` -$ sudo ./docker images -``` -Lists all images that have been pulled from the upstream kollaglue repository -thus far. This can be run on the node during the `./start` operation to -check on the download progress. - -``` -$ sudo ./docker ps -a -``` -This will show all processes that docker has started. Removing the `-a` will -show only active processes. This can be run on the node during the `./start` -operation to check that the containers are orchestrated. - -``` -$ sudo ./docker logs -``` -``` -$ curl http://:3306 -``` -You can use curl to test connectivity to a container. This example demonstrates -the Mariadb service is running on the node. Output should appear as follows - -``` -$ curl http://10.0.0.4:3306 -Trying 10.0.0.4... -Connected to 10.0.0.4. -Escape character is '^]'. - -``` diff --git a/devenv/README.rst b/devenv/README.rst new file mode 100644 index 000000000..53f0a3417 --- /dev/null +++ b/devenv/README.rst @@ -0,0 +1,169 @@ +A Kolla Cluster with Heat +========================= + +These [Heat][] templates will deploy an *N*-node [Kolla][] cluster, +where *N* is the value of the `number_of_nodes` parameter you +specify when creating the stack. + +Kolla has recently undergone a considerable design change. The details +of the design change is addressed in this [spec][]. As part of the +design change, containers share pid and networking namespaces with +the Docker host. Therefore, containers no longer connect to a docker0 +bridge and have separate networking from the host. As a result, Kolla +networking has a configuration similar to: + +![Image](https://raw.githubusercontent.com/stackforge/kolla/master/devenv/kollanet.png) + +Sharing pid and networking namespaces is detailed in the +[super privileged containers][] concept. + +The Kolla cluster is based on Fedora 21, requires the minimum Docker version of 1.7.0 +[binary][]. + +These templates are designed to work with the Icehouse or Juno +versions of Heat. If using Icehouse Heat, this [patch][] is +required to correct a bug with template validation when using the +"Fn::Join" function). + +[heat]: https://wiki.openstack.org/wiki/Heat +[kolla]: https://launchpad.net/kolla +[binary]: https://docs.docker.com/installation/binaries/ +[copr]: https://copr.fedoraproject.org/ +[spec]: https://review.openstack.org/#/c/153798/ +[super privileged containers]: http://sdake.io/2015/01/28/an-atomic-upgrade-process-for-openstack-compute-nodes/ +[patch]: https://review.openstack.org/#/c/121139/ + +Create the Glance Image +======================= + +After cloning the project, run the get-image.sh script from the project's +devenv directory: + + $ ./get-image.sh + +The script will create a Fedora 21 image with the required modifications. + +Add the image to your Glance image store: + + $ glance image-create --name "fedora-21-x86_64" \ + --file /var/lib/libvirt/images/fedora-21-x86_64 \ + --disk-format qcow2 --container-format bare \ + --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 +local.yaml: + + parameters: + ssh_key_name: admin-key + external_network_id: 028d70dd-67b8-4901-8bdd-0c62b06cce2d + container_external_network_id: 028d70dd-67b8-4901-8bdd-0c62b06cce2d + container_external_subnet_id: 575770dd-6828-1101-34dd-0c62b06fjf8s + dns_nameserver: 192.168.200.1 + +The external_network_id is used by Heat to automatically assign +floating IP's to your Kolla nodes. You can then access your Kolla nodes +directly using the floating IP. The network ID is derived from the +`neutron net-list` command. + +The container_external_network_id is used by the nova-network container +within the Kolla node as the FLAT_INTERFACE. The FLAT_INTERFACE tells Nova what +device to use (i.e. eth1) to pass network traffic between Nova instances +across Kolla nodes. This network should be seperate from the external_network_id +above and is derived from the 'neutron net-list' command. + +The container_external_subnet_id: is the subnet equivalent to +container_external_network_id + +Review the parameters section of kollacluster.yaml for a full list of +configuration options. **Note:** You must provide values for: + +- `ssh_key_name` +- `external_network_id` +- `container_external_network_id` +- `container_external_subnet_id` + +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: + + $ heat output-show kolla-cluster kolla_node_external_ip + "192.168.200.86" + +You can ssh into that server as the `fedora` user: + + $ ssh fedora@192.168.200.86 + +Once logged into your Kolla node, setup your environment. +The basic starting environment will be created using `docker-compose`. +This environment will start up the openstack services listed in the +compose directory. + +To start, setup your environment variables. + + $ cd kolla + $ ./tools/genenv + +The `genenv` script will create a compose/openstack.env file +and an openrc file in your current directory. The openstack.env +file contains all of your initialized environment variables, which +you can edit for a different setup. + +Next, run the start script. + + $ ./tools/kolla-compose start + +The `start` script is responsible for starting the containers +using `docker-compose -f up -d`. + +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 binaray, +by default this is `/`. + +A few commands for debugging the system. + +``` +$ sudo ./docker images +``` +Lists all images that have been pulled from the upstream kollaglue repository +thus far. This can be run on the node during the `./start` operation to +check on the download progress. + +``` +$ sudo ./docker ps -a +``` +This will show all processes that docker has started. Removing the `-a` will +show only active processes. This can be run on the node during the `./start` +operation to check that the containers are orchestrated. + +``` +$ sudo ./docker logs +``` +``` +$ curl http://:3306 +``` +You can use curl to test connectivity to a container. This example demonstrates +the Mariadb service is running on the node. Output should appear as follows + +``` +$ curl http://10.0.0.4:3306 +Trying 10.0.0.4... +Connected to 10.0.0.4. +Escape character is '^]'. + +``` 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