From a62d6bac630a04ec2424d3282c0db1f75632ce91 Mon Sep 17 00:00:00 2001 From: Martin Falatic Date: Tue, 7 Jul 2015 11:12:05 -0700 Subject: [PATCH] Updated Magnum documentation Magnum documentation updated to reflect current usage. Cleanups for syntax and readability applied as needed. DocImpact Closes-Bug: #1472029 Change-Id: If3d8660e6763083544529f469be02eec73e9fd0c --- README.rst | 54 +---- devstack/README.rst | 19 +- doc/source/dev/dev-manual-devstack.rst | 123 ++++++---- doc/source/dev/dev-quickstart.rst | 301 ++++++++++++++----------- doc/source/index.rst | 91 ++++++-- doc/source/installation.rst | 12 - doc/source/readme.rst | 1 - doc/source/usage.rst | 7 - 8 files changed, 340 insertions(+), 268 deletions(-) delete mode 100644 doc/source/installation.rst delete mode 100644 doc/source/readme.rst delete mode 100644 doc/source/usage.rst diff --git a/README.rst b/README.rst index 7b9f3dc579..45bbbd391a 100644 --- a/README.rst +++ b/README.rst @@ -2,50 +2,14 @@ Magnum ====== -new Openstack project for containers. +Magnum is an OpenStack project which offers container orchestration engines +for deploying and managing containers as first class resources in OpenStack. -* Free software: Apache license -* Documentation: http://docs.openstack.org/developer/magnum -* Source: http://git.openstack.org/cgit/openstack/magnum -* Bugs: http://bugs.launchpad.net/magnum -* ReST Client: http://git.openstack.org/cgit/openstack/python-magnumclient +For more information, please refer to the following resources: -Architecture ------------- - -There are seven different types of objects in the Magnum system: - -* Bay: A collection of node objects where work is scheduled -* BayModel: An object stores template information about the bay which is used to create new bays consistently -* Node: A baremetal or virtual machine where work executes -* Pod: A collection of containers running on one physical or virtual machine -* Service: An abstraction which defines a logical set of pods and a policy by which to access them -* ReplicationController: An abstraction for managing a group of PODs to ensure a specified number of PODs are running -* Container: A docker container - -Two binaries work together to compose the Magnum system. The first binary -accessed by the python-magnumclient code is the magnum-api ReST server. The -ReST server may run as one process or multiple processes. When a ReST request -is sent to the client API, the request is sent via AMQP to the magnum-conductor -process. The ReST server is horizontally scalable. At this time, the -conductor is limited to one process, but we intend to add horizontal -scalability to the conductor as well. - -The magnum-conductor process runs on a controller machine and connects to a -kubernetes or docker ReST API endpoint. The kubernetes and docker ReST API -endpoints are managed by the bay object. - -When service or pod objects are created, Kubernetes is directly contacted via -the k8s ReST API. When container objects are acted upon, the docker ReST API -is directly contacted. - -Features --------- -* Abstractions for bays, containers, nodes, pods, and services -* Integration with Kubernetes and Docker for backend container technology. -* Integration with Keystone for multi-tenant security. -* Integration with Neutron for k8s multi-tenancy network security. - -Installation and Usage ----------------------- -* Getting Started Guides: http://git.openstack.org/cgit/openstack/magnum/tree/doc/source/dev/dev-quickstart.rst +* **Free software:** under the `Apache license `_ +* **Documentation:** http://docs.openstack.org/developer/magnum +* **Source:** http://git.openstack.org/cgit/openstack/magnum +* **Blueprints:** https://blueprints.launchpad.net/magnum +* **Bugs:** http://bugs.launchpad.net/magnum +* **ReST Client:** http://git.openstack.org/cgit/openstack/python-magnumclient diff --git a/devstack/README.rst b/devstack/README.rst index 0e1b64e034..6671c3b22c 100644 --- a/devstack/README.rst +++ b/devstack/README.rst @@ -1,24 +1,27 @@ ==================== -Devstack Integration +DevStack Integration ==================== -This directory contains the files necessary to integrate Magnum with devstack. +This directory contains the files necessary to integrate magnum with devstack. -Refer the quickstart guide for more information on using devstack and magnum. +Refer the quickstart guide at +http://docs.openstack.org/developer/magnum/dev/dev-quickstart.html +for more information on using devstack and magnum. Running devstack with magnum for the first time may take a long time as it -needs to download an atomic fedora 21 qcow image. If you already have this image -you can copy it to /opt/stack/devstack/files/fedora-21-atomic-3.qcow2 to save you -this time. +needs to download the Fedora Atomic micro-OS qcow2 image (e.g., +``fedora-21-atomic-3.qcow2``). If you already have this image you can copy it +to /opt/stack/devstack/files first to save time. -To install magnum into devstack, add the following settings to enable magnum plugin: :: +To install magnum into devstack, add the following settings to enable the +magnum plugin:: cat > /opt/stack/devstack/local.conf << END [[local|localrc]] enable_plugin magnum https://github.com/openstack/magnum master END -Run devstack as normal: :: +Then run devstack normally:: cd /opt/stack/devstack ./stack.sh diff --git a/doc/source/dev/dev-manual-devstack.rst b/doc/source/dev/dev-manual-devstack.rst index 4a1a973b23..1758c9fee8 100644 --- a/doc/source/dev/dev-manual-devstack.rst +++ b/doc/source/dev/dev-manual-devstack.rst @@ -1,30 +1,31 @@ .. _dev-manual-install: +================================== Manually Adding Magnum to DevStack ================================== -If you are getting started with Magnum it is recommended you follow the -:ref:`dev-quickstart` to get up and running with Magnum. This guide covers -a more in-depth process to setup Magnum with devstack. +If you are getting started with magnum it is recommended you follow the +:ref:`dev-quickstart` to get up and running with magnum. This guide covers +a more in-depth process to setup magnum with devstack. -Magnum depends on Nova, Glance, Heat and Neutron to create and schedule -virtual machines to simulate bare-metal. For bare-metal fully support, it +Magnum depends on nova, glance, heat, and neutron to create and schedule +virtual machines to simulate bare-metal. Full bare-metal support is still under active development. This session has only been tested on Ubuntu 14.04 (Trusty) and Fedora 20/21. We recommend users to select one of them if it is possible. -Clone DevStack:: +Clone devstack:: cd ~ - git clone https://github.com/openstack-dev/devstack.git devstack + git clone https://git.openstack.org/openstack-dev/devstack -Create devstack/localrc with minimal settings required to enable Heat -and Neutron, refer to http://docs.openstack.org/developer/devstack/guides/neutron.html -for more detailed neutron configuration.:: +Configure devstack with the minimal settings required to enable heat +and neutron:: cd devstack - cat >localrc < local.conf << END + [[local|localrc]] # Modify to your environment FLOATING_RANGE=192.168.1.224/27 PUBLIC_NETWORK_GATEWAY=192.168.1.225 @@ -39,7 +40,8 @@ for more detailed neutron configuration.:: enable_service rabbit - # Enable Neutron which is required by Magnum and disable nova-network. + # Ensure we are using neutron networking rather than nova networking + # (Neutron is enabled by default since Kilo) disable_service n-net enable_service q-svc enable_service q-agt @@ -48,7 +50,7 @@ for more detailed neutron configuration.:: enable_service q-meta enable_service neutron - # Enable Heat services + # Enable heat services enable_service h-eng enable_service h-api enable_service h-api-cfn @@ -70,29 +72,47 @@ for more detailed neutron configuration.:: VOLUME_BACKING_FILE_SIZE=20G END +Note: Update PUBLIC_INTERFACE and other parameters as appropriate for your +system. + +More devstack configuration information can be found at +http://docs.openstack.org/developer/devstack/configuration.html + +More neutron configuration information can be found at +http://docs.openstack.org/developer/devstack/guides/neutron.html + +Create a local.sh to automatically make necessary networking changes during +the devstack deployment process. This will allow bays spawned by magnum to +access the internet through PUBLIC_INTERFACE:: + cat > local.sh << END_LOCAL_SH #!/bin/sh sudo iptables -t nat -A POSTROUTING -o br-ex -j MASQUERADE END_LOCAL_SH chmod 755 local.sh +Run devstack:: + ./stack.sh -At this time, Magnum has only been tested with the Fedora Atomic micro-OS. -Magnum will likely work with other micro-OS platforms, but each one requires -individual support in the heat template. +Note: If using the m-1 tag or tarball, please use the documentation shipped +with the milestone as the current master instructions are slightly +incompatible. -The next step is to store the Fedora Atomic micro-OS in glance. The steps for -updating Fedora Atomic images are a bit detailed. Fortunately one of the core -developers has made Atomic images available via the web: - -If using the m-1 tag or tarball, please use the documentation shipped with the -milestone as the current master instructions are slightly incompatible. - -Create a new shell, and source the devstack openrc script:: +Prepare your session to be able to use the various openstack clients including +magnum, neutron, and glance. Create a new shell, and source the devstack openrc +script:: source ~/devstack/openrc admin admin +Magnum has been tested with the Fedora Atomic micro-OS and CoreOS. Magnum will +likely work with other micro-OS platforms, but each requires individual +support in the heat template. + +Store the Fedora Atomic micro-OS in glance. (The steps for updating Fedora +Atomic images are a bit detailed. Fortunately one of the core developers has +made Atomic images available at https://fedorapeople.org/groups/magnum):: + cd ~ wget https://fedorapeople.org/groups/magnum/fedora-21-atomic-3.qcow2 glance image-create --name fedora-21-atomic-3 \ @@ -100,10 +120,13 @@ Create a new shell, and source the devstack openrc script:: --disk-format qcow2 \ --property os_distro='fedora-atomic'\ --container-format bare < fedora-21-atomic-3.qcow2 - test -f ~/.ssh/id_rsa.pub || ssh-keygen + +Create a keypair for use with the baymodel:: + + test -f ~/.ssh/id_rsa.pub || ssh-keygen -t rsa -N "" -f ~/.ssh/id_rsa nova keypair-add --pub-key ~/.ssh/id_rsa.pub testkey -Next, create a database in MySQL for Magnum:: +Create a database in MySQL for magnum:: mysql -h 127.0.0.1 -u root -ppassword mysql <`_. +can be found at the http://fedoraproject.org/wiki/EPEL/FAQ#howtouse page. You may need to explicitly upgrade virtualenv if you've installed the one from your OS distribution and it is too old (tox will complain). You can @@ -55,7 +57,7 @@ Magnum source code should be pulled directly from git:: git clone https://git.openstack.org/openstack/magnum cd magnum -Set up a local environment for development and testing should be done with tox:: +Set up a local environment for development and testing with tox:: # create a virtualenv for development tox -evenv -- python -V @@ -65,7 +67,7 @@ All further commands in this section should be run with the venv active:: source .tox/venv/bin/activate -All unit tests should be run using tox. To run Magnum's entire test suite:: +All unit tests should be run using tox. To run magnum's entire test suite:: # run all tests (unit and pep8) tox @@ -91,58 +93,56 @@ When you're done, deactivate the virtualenv:: To discover and interact with templates, please refer to ``_ - -Exercising the Services Using DevStack +Exercising the Services Using Devstack ====================================== -DevStack can be configured to enable Magnum support. It is easy to develop Magnum -with devstack environment. Magnum depends on Nova, Glance, Heat and Neutron to -create and schedule virtual machines to simulate bare-metal. For bare-metal fully -support, it is still under active development. +Devstack can be configured to enable magnum support. It is easy to develop +magnum with the devstack environment. Magnum depends on nova, glance, heat and +neutron to create and schedule virtual machines to simulate bare-metal (full +bare-metal support is under active development). + +Note: Running devstack within a virtual machine with magnum enabled is not +recommended at this time. This session has only been tested on Ubuntu 14.04 (Trusty) and Fedora 20/21. We recommend users to select one of them if it is possible. -Clone DevStack:: +Clone devstack:: - # Create dir to run devstack from, if not done so already + # Create a root directory for devstack if needed sudo mkdir -p /opt/stack sudo chown $USER /opt/stack - git clone https://github.com/openstack-dev/devstack.git /opt/stack/devstack + git clone https://git.openstack.org/openstack-dev/devstack /opt/stack/devstack -Copy devstack/localrc with minimal settings required to enable Heat -and Neutron, refer to http://docs.openstack.org/developer/devstack/guides/neutron.html -for more detailed neutron configuration. +We will run devstack with minimal local.conf settings required to enable +magnum, heat, and neutron (neutron is enabled by default in devstack since +Kilo, and heat is enabled by the magnum plugin):: -To install magnum into devstack, add following settings to local.conf. You need to -make customized setting according to your environment requirement, refer devstack -guide for details.:: + cat > /opt/stack/devstack/local.conf << END + [[local|localrc]] + DATABASE_PASSWORD=password + RABBIT_PASSWORD=password + SERVICE_TOKEN=password + SERVICE_PASSWORD=password + ADMIN_PASSWORD=password + # magnum requires the following to be set correctly + PUBLIC_INTERFACE=eth1 + enable_plugin magnum https://github.com/openstack/magnum + VOLUME_BACKING_FILE_SIZE=20G + END - cat > /opt/stack/devstack/local.conf << END - [[local|localrc]] - enable_plugin magnum https://github.com/openstack/magnum - DATABASE_PASSWORD=password - RABBIT_PASSWORD=password - SERVICE_TOKEN=password - SERVICE_PASSWORD=password - ADMIN_PASSWORD=password - PUBLIC_INTERFACE=eth1 - VOLUME_BACKING_FILE_SIZE=20G - END +Note: Update PUBLIC_INTERFACE as appropriate for your system. -Or, if you already have localrc in /opt/stack/devstack/, then :: +More devstack configuration information can be found at +http://docs.openstack.org/developer/devstack/configuration.html - cat >> /opt/stack/devstack/localrc << END - enable_plugin magnum https://github.com/openstack/magnum - PUBLIC_INTERFACE=eth1 - VOLUME_BACKING_FILE_SIZE=20G - END +More neutron configuration information can be found at +http://docs.openstack.org/developer/devstack/guides/neutron.html -Note: Replace eth1 with your public interface for Neutron to use. - -Create a local.sh make final networking changes after devstack has spawned. This -will allow Bays spawned by Magnum to access the internet through PUBLIC_INTERFACE.:: +Create a local.sh to automatically make necessary networking changes during +the devstack deployment process. This will allow bays spawned by magnum to +access the internet through PUBLIC_INTERFACE:: cat > /opt/stack/devstack/local.sh << END_LOCAL_SH #!/bin/sh @@ -150,30 +150,34 @@ will allow Bays spawned by Magnum to access the internet through PUBLIC_INTERFAC END_LOCAL_SH chmod 755 /opt/stack/devstack/local.sh -Run DevStack:: +Run devstack:: cd /opt/stack/devstack ./stack.sh -After the script finishes, two magnum process (magnum-api and magnum-conductor) -will be running on a stack screen. If you make some code changes and want to -test their effects, just restart either magnum-api or magnum-conductor. +Note: This will take a little extra time when the Fedora Atomic micro-OS +image is downloaded for the first time. -At this time, Magnum has only been tested with the Fedora Atomic micro-OS. -Magnum will likely work with other micro-OS platforms, but each one requires -individual support in the heat template. +At this point, two magnum process (magnum-api and magnum-conductor) will be +running on devstack screens. If you make some code changes and want to +test their effects, just stop and restart magnum-api and/or magnum-conductor. Prepare your session to be able to use the various openstack clients including -magnum, neutron and glance. Create a new shell, and source the devstack openrc +magnum, neutron, and glance. Create a new shell, and source the devstack openrc script:: source /opt/stack/devstack/openrc admin admin -The fedora-21-atomic-3 image will automatically be added to glance. You can -add additional images to use manually through glance. To verify the image -created when installing DevStack:: +Magnum has been tested with the Fedora Atomic micro-OS and CoreOS. Magnum will +likely work with other micro-OS platforms, but each requires individual +support in the heat template. + +The Fedora Atomic micro-OS image will automatically be added to glance. You +can add additional images manually through glance. To verify the image created +when installing devstack use:: glance image-list + +--------------------------------------+---------------------------------+-------------+------------------+-----------+--------+ | ID | Name | Disk Format | Container Format | Size | Status | +--------------------------------------+---------------------------------+-------------+------------------+-----------+--------+ @@ -183,41 +187,43 @@ created when installing DevStack:: | 02c312e3-2d30-43fd-ab2d-1d25622c0eaa | fedora-21-atomic-3 | qcow2 | bare | 770179072 | active | +--------------------------------------+---------------------------------+-------------+------------------+-----------+--------+ -You need to define and register a keypair for use when creating baymodel's:: - - cd ~ - test -f ~/.ssh/id_rsa.pub || ssh-keygen -t rsa -N "" -f ~/.ssh/id_rsa - nova keypair-add --pub-key ~/.ssh/id_rsa.pub testkey - -To get started, list the available commands and resources:: +To list the available commands and resources for magnum, use:: magnum help -First create a baymodel, which is similar in nature to a flavor. The -coe (Container Orchestration Engine) needs to be specified for baymodel. -The baymodel informs Magnum in which way to construct a bay.:: +Create a keypair for use with the baymodel:: + + test -f ~/.ssh/id_rsa.pub || ssh-keygen -t rsa -N "" -f ~/.ssh/id_rsa + nova keypair-add --pub-key ~/.ssh/id_rsa.pub testkey + +Create a baymodel. This is similar in nature to a flavor and describes +to magnum how to construct the bay. The coe (Container Orchestration Engine) +and keypair need to be specified for the baymodel:: NIC_ID=$(neutron net-show public | awk '/ id /{print $4}') - magnum baymodel-create --name k8sbaymodel --image-id fedora-21-atomic-3 \ - --keypair-id testkey \ - --external-network-id $NIC_ID \ - --dns-nameserver 8.8.8.8 --flavor-id m1.small \ - --docker-volume-size 5 --coe kubernetes + echo ${NIC_ID} -Next create a bay. Use the baymodel UUID as a template for bay creation. -This bay will result in one master kubernetes node and one minion node.:: + magnum baymodel-create --name k8sbaymodel \ + --image-id fedora-21-atomic-3 \ + --keypair-id testkey \ + --external-network-id ${NIC_ID} \ + --dns-nameserver 8.8.8.8 \ + --flavor-id m1.small \ + --docker-volume-size 5 \ + --coe kubernetes + +Create a bay. Use the baymodel name as a template for bay creation. +This bay will result in one master kubernetes node and one minion node:: magnum bay-create --name k8sbay --baymodel k8sbaymodel --node-count 1 -The existing bays can be listed as follows:: - - magnum bay-list - Bays will have an initial status of CREATE_IN_PROGRESS. Magnum will update the status to CREATE_COMPLETE when it is done creating the bay. Do not create -containers, pods, services, or replication controllers before Magnum finishes -creating the bay. They will likely not be created, causing Magnum to become -confused. +containers, pods, services, or replication controllers before magnum finishes +creating the bay. They will likely not be created, and may cause magnum to +become confused. + +The existing bays can be listed as follows:: magnum bay-list @@ -227,41 +233,69 @@ confused. | 9dccb1e6-02dc-4e2b-b897-10656c5339ce | k8sbay | 1 | CREATE_COMPLETE | +--------------------------------------+---------+------------+-----------------+ +More detailed information for a given bay is obtained via:: + + magnum bay-show k8sbay + After a bay is created, you can dynamically add/remove node(s) to/from the bay by updating the node_count attribute. For example, to add one more node:: magnum bay-update k8sbay replace node_count=2 -Bays will have an initial status of UPDATE_IN_PROGRESS. Magnum will update -the status to UPDATE_COMPLETE when it is done updating the bay. +Bays in the process of updating will have a status of UPDATE_IN_PROGRESS. +Magnum will update the status to UPDATE_COMPLETE when it is done updating +the bay. -NOTE: If you choose to reduce the node_count, Magnum will first try to remove +Note: Reducing node_count will remove all the existing containers on the +nodes that are deleted. + +Heat can be used to see detailed information on the status of a stack or +specific bay:: + + heat stack-list + +Monitoring bay status in detail (e.g., creating, updating):: + + BAY_HEAT_NAME=$(heat stack-list | awk "/\sk8sbay-/{print \$4}") + echo ${BAY_HEAT_NAME} + heat resource-list ${BAY_HEAT_NAME} + +A bay can be deleted as follows:: + + magnum bay-delete k8sbay + +Note: If you choose to reduce the node_count, magnum will first try to remove empty nodes with no containers running on them. If you reduce node_count by -more than the number of empty nodes, Magnum must remove nodes that have running +more than the number of empty nodes, magnum must remove nodes that have running containers on them. This action will delete those containers. We strongly recommend using a replication controller before reducing the node_count so any removed containers can be automatically recovered on your remaining nodes. -Kubernetes provides a number of examples you can use to check that things -are working. You may need to clone kubernetes by:: +Using Kubernetes +================ + +Kubernetes provides a number of examples you can use to check that things are +working. You may need to clone kubernetes using:: wget https://github.com/GoogleCloudPlatform/kubernetes/releases/download/v0.15.0/kubernetes.tar.gz tar -xvzf kubernetes.tar.gz -(No require to install it, we just use the example file) +Note: We do not need to install Kubernetes, we just need the example file +from the tarball. + Here's how to set up the replicated redis example. First, create a pod for the redis-master:: cd kubernetes/examples/redis/v1beta3 magnum pod-create --manifest ./redis-master.yaml --bay k8sbay -Now turn up a service to provide a discoverable endpoint for the redis sentinels -in the cluster:: +Now create a service to provide a discoverable endpoint for the redis +sentinels in the cluster:: magnum service-create --manifest ./redis-sentinel-service.yaml --bay k8sbay -To make it a replicated redis cluster create replication controllers for the redis -slaves and sentinels:: +To make it a replicated redis cluster create replication controllers for the +redis slaves and sentinels:: sed -i 's/\(replicas: \)1/\1 2/' redis-controller.yaml magnum rc-create --manifest ./redis-controller.yaml --bay k8sbay @@ -269,13 +303,15 @@ slaves and sentinels:: sed -i 's/\(replicas: \)1/\1 2/' redis-sentinel-controller.yaml magnum rc-create --manifest ./redis-sentinel-controller.yaml --bay k8sbay -Full lifecycle and introspection operations for each object are supported. For -example, magnum bay-create, magnum baymodel-delete, magnum rc-show, magnum service-list. +Full lifecycle and introspection operations for each object are supported. +For example, magnum bay-create, magnum baymodel-delete, magnum rc-show, +magnum service-list. -Now run bay-show command to get the IP of the bay host on which the redis-master is -running on:: +Now run bay-show command to get the IP of the bay host on which the +redis-master is running:: + + magnum bay-show k8sbay - $ magnum bay-show k8sbay +----------------+--------------------------------------+ | Property | Value | +----------------+--------------------------------------+ @@ -291,8 +327,8 @@ running on:: | name | k8sbay | +----------------+--------------------------------------+ -The output indicates the redis-master is running on the -bay host with IP address 192.168.19.86. To access the redis master:: +The output indicates the redis-master is running on the bay host with IP +address 192.168.19.86. To access the redis master:: ssh minion@192.168.19.86 REDIS_ID=$(sudo docker ps | grep redis:v1 | grep k8s_master | awk '{print $1}') @@ -304,7 +340,7 @@ bay host with IP address 192.168.19.86. To access the redis master:: exit -Now log into one of the other container hosts and access a redis slave from there:: +Log into one of the other container hosts and access a redis slave from it:: ssh minion@$(nova list | grep 10.0.0.4 | awk '{print $13}') REDIS_ID=$(sudo docker ps | grep redis:v1 | grep k8s_redis | tail -n +2 | awk '{print $1}') @@ -316,32 +352,35 @@ Now log into one of the other container hosts and access a redis slave from ther exit -There are four redis instances, one master and three slaves, running across the bay, -replicating data between one another. +Now there are four redis instances (one master and three slaves) running +across the bay, replicating data between one another. -Building and using a Swarm bay +Building and Using a Swarm Bay ============================== -Create a baymodel. It is very similar to the Kubernetes baymodel, -it is only missing some Kubernetes specific arguments and uses 'swarm' as the -coe. :: + +Create a baymodel. It is very similar to the Kubernetes baymodel, except for +the absence of some Kubernetes-specific arguments and the use of 'swarm' +as the coe:: NIC_ID=$(neutron net-show public | awk '/ id /{print $4}') - magnum baymodel-create --name swarmbaymodel --image-id fedora-21-atomic-3 \ + magnum baymodel-create --name swarmbaymodel \ + --image-id fedora-21-atomic-3 \ --keypair-id testkey \ - --external-network-id $NIC_ID \ - --dns-nameserver 8.8.8.8 --flavor-id m1.small \ + --external-network-id ${NIC_ID} \ + --dns-nameserver 8.8.8.8 \ + --flavor-id m1.small \ --coe swarm Finally, create the bay. Use the baymodel 'swarmbaymodel' as a template for bay creation. This bay will result in one swarm manager node and two extra -agent nodes. :: +agent nodes:: magnum bay-create --name swarmbay --baymodel swarmbaymodel --node-count 2 -Now that we have a swarm bay we can start interacting with it. First we need -to get it's uuid. :: +Now that we have a swarm bay we can start interacting with it:: + + magnum bay-show swarmbay - $ magnum bay-show swarmbay +---------------+------------------------------------------+ | Property | Value | +---------------+------------------------------------------+ @@ -356,11 +395,13 @@ to get it's uuid. :: +---------------+------------------------------------------+ Next we will create a container in this bay. This container will ping the -address 8.8.8.8 four times. :: +address 8.8.8.8 four times:: + + magnum container-create --name testcontainer \ + --image cirros \ + --bay swarmbay \ + --command "ping -c 4 8.8.8.8" - $ magnum container-create --name testcontainer --image cirros\ - --bay swarmbay\ - --command "ping -c 4 8.8.8.8" +------------+----------------------------------------+ | Property | Value | +------------+----------------------------------------+ @@ -374,11 +415,12 @@ address 8.8.8.8 four times. :: | name | test-container | +------------+----------------------------------------+ -At this point, the container exists, but it has not been started yet. Let's -start it then check it's output. :: +At this point the container exists but it has not been started yet. To start +it and check its output run the following:: + + magnum container-start test-container + magnum container-logs test-container - $ magnum container-start test-container - $ magnum container-logs test-container PING 8.8.8.8 (8.8.8.8): 56 data bytes 64 bytes from 8.8.8.8: seq=0 ttl=40 time=25.513 ms 64 bytes from 8.8.8.8: seq=1 ttl=40 time=25.348 ms @@ -389,23 +431,22 @@ start it then check it's output. :: 4 packets transmitted, 4 packets received, 0% packet loss round-trip min/avg/max = 25.226/25.340/25.513 ms -Now that we're done with the container, we can delete it. :: +Now that we're done with the container we can delete it:: magnum container-delete test-container -Building developer documentation +Building Developer Documentation ================================ -If you would like to build the documentation locally, eg. to test your -documentation changes before uploading them for review, run these -commands to build the documentation set:: +To build the documentation locally (e.g., to test documentation changes +before uploading them for review) chdir to the magnum root folder and +run tox:: - # activate your development virtualenv - source .tox/venv/bin/activate - - # build the docs tox -edocs -Now use your browser to open the top-level index.html located at:: +Note: The first time you run this will take some extra time as it +creates a virtual environment to run in. - magnum/doc/build/html/index.html +When complete, the documentation can be accesed from:: + + doc/build/html/index.html diff --git a/doc/source/index.rst b/doc/source/index.rst index 283d420fe0..e4465ddfca 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -1,27 +1,80 @@ -.. magnum documentation master file, created by - sphinx-quickstart on Tue Jul 9 22:26:36 2013. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. +.. + Copyright 2014-2015 OpenStack Foundation + All Rights Reserved. -Welcome to Magnum's documentation! -======================================================== + Licensed under the Apache License, Version 2.0 (the "License"); you may + not use this file except in compliance with the License. You may obtain + a copy of the License at -Contents: + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + License for the specific language governing permissions and limitations + under the License. + +============================================ +Welcome to Magnum's Developer Documentation! +============================================ + +Magnum is an OpenStack project which offers container orchestration engines +for deploying and managing containers as first class resources in OpenStack. + +* **Free software:** under the `Apache license `_ +* **Source:** http://git.openstack.org/cgit/openstack/magnum +* **Blueprints:** https://blueprints.launchpad.net/magnum +* **Bugs:** http://bugs.launchpad.net/magnum +* **ReST Client:** http://git.openstack.org/cgit/openstack/python-magnumclient + +Architecture +============ + +There are several different types of objects in the magnum system: + +* **Bay:** A collection of node objects where work is scheduled +* **BayModel:** An object stores template information about the bay which is + used to create new bays consistently +* **Node:** A baremetal or virtual machine where work executes +* **Pod:** A collection of containers running on one physical or virtual + machine +* **Service:** An abstraction which defines a logical set of pods and a policy + by which to access them +* **ReplicationController:** An abstraction for managing a group of pods to + ensure a specified number of resources are running +* **Container:** A Docker container + +Two binaries work together to compose the magnum system. The first binary +(accessed by the python-magnumclient code) is the magnum-api ReST server. The +ReST server may run as one process or multiple processes. When a ReST request +is sent to the client API, the request is sent via AMQP to the +magnum-conductor process. The ReST server is horizontally scalable. At this +time, the conductor is limited to one process, but we intend to add horizontal +scalability to the conductor as well. + +The magnum-conductor process runs on a controller machine and connects to a +Kubernetes or Docker ReST API endpoint. The Kubernetes and Docker ReST API +endpoints are managed by the bay object. + +When service or pod objects are created, Kubernetes may be directly contacted +via the Kubernetes ReST API. When container objects are acted upon, the +Docker ReST API may be directly contacted. + +Features +======== + +* Abstractions for bays, containers, nodes, pods, replication controllers, and + services +* Integration with Kubernetes and Docker for backend container technology +* Integration with Keystone for multi-tenant security +* Integration with Neutron for Kubernetes multi-tenancy network security + +Developer Info +============== .. toctree:: - :maxdepth: 2 + :maxdepth: 1 - readme dev/dev-quickstart dev/dev-manual-devstack - installation - usage contributing - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` - diff --git a/doc/source/installation.rst b/doc/source/installation.rst deleted file mode 100644 index 9c0443d174..0000000000 --- a/doc/source/installation.rst +++ /dev/null @@ -1,12 +0,0 @@ -============ -Installation -============ - -At the command line:: - - $ pip install magnum - -Or, if you have virtualenvwrapper installed:: - - $ mkvirtualenv magnum - $ pip install magnum diff --git a/doc/source/readme.rst b/doc/source/readme.rst deleted file mode 100644 index a6210d3d8a..0000000000 --- a/doc/source/readme.rst +++ /dev/null @@ -1 +0,0 @@ -.. include:: ../../README.rst diff --git a/doc/source/usage.rst b/doc/source/usage.rst deleted file mode 100644 index 03c14efb09..0000000000 --- a/doc/source/usage.rst +++ /dev/null @@ -1,7 +0,0 @@ -======== -Usage -======== - -To use magnum in a project:: - - import magnum