From 58426acb47d2e2ab4376ef19dc9b6b6cde3b5e58 Mon Sep 17 00:00:00 2001 From: Christian Berendt Date: Fri, 11 Sep 2015 10:52:07 +0200 Subject: [PATCH] Migrate README files to RST The syntax of the README files is broken. Fix the syntax and change the file suffix from md to rst. Change-Id: I07461e6f931c610464092488f5a72a7516a2c064 --- README.md => README.rst | 4 +- .../v2/calculator/{README.md => README.rst} | 26 ++++++------- .../join/{README.md => README.rst} | 19 ++++----- .../v2/openstack/{README.md => README.rst} | 39 ++++++++++--------- .../{README.md => README.rst} | 27 ++++++------- .../vyatta/{README.md => README.rst} | 15 +++---- .../zabbix/{README.md => README.rst} | 13 +++---- .../{README.md => README.rst} | 23 +++++------ setup.cfg | 2 +- 9 files changed, 81 insertions(+), 87 deletions(-) rename README.md => README.rst (66%) rename examples/v2/calculator/{README.md => README.rst} (78%) rename examples/v2/capabilities/join/{README.md => README.rst} (61%) rename examples/v2/openstack/{README.md => README.rst} (55%) rename examples/v2/services_registration/{README.md => README.rst} (72%) rename examples/v2/services_registration/vyatta/{README.md => README.rst} (81%) rename examples/v2/services_registration/zabbix/{README.md => README.rst} (82%) rename examples/v2/tenant_statistics/{README.md => README.rst} (52%) diff --git a/README.md b/README.rst similarity index 66% rename from README.md rename to README.rst index 577cdfe..84b7098 100644 --- a/README.md +++ b/README.rst @@ -1,8 +1,8 @@ +============== Mistral Extras ============== Contains Mistral examples. - To see more detailed information about particular examples use README files -located in corresponding folders under "examples/". +located in corresponding folders under ``examples/``. diff --git a/examples/v2/calculator/README.md b/examples/v2/calculator/README.rst similarity index 78% rename from examples/v2/calculator/README.md rename to examples/v2/calculator/README.rst index 5dc2b52..03e4442 100644 --- a/examples/v2/calculator/README.md +++ b/examples/v2/calculator/README.rst @@ -1,19 +1,20 @@ +======================================== Calculator example (based on v2 API/DSL) ======================================== -'Calculator example' is created to demonstrate Mistral project features: +``Calculator example`` is created to demonstrate Mistral project features: It spins up a VM and uses it to do some useful work. Particularly, created vm is used to deploy a simple web application on it which works a as a calculator returning over HTTP results of sum operations. What this example does --------------------- +---------------------- 1. Creates a VM 2. Waits till it is up and running 3. Runs small web server on VM 4. Sends request to the server -5. If an error occurred, it sends a email to admin with error message +5. If an error occurred, it sends an email to admin with error message How to run ---------- @@ -23,37 +24,37 @@ How to run * Create an image of virtual machine * Make sure that VM has SSH server in running state * Make sure that VM has password access via SSH - * Install packages (example for Debian/Ubuntu based systems) + * Install packages (example for Debian/Ubuntu based systems):: sudo apt-get install python-dev sudo apt-get install python-pip sudo pip install flask - * Put *web_app.py* file into user's home directory. To check if it works, type + * Put *web_app.py* file into user's home directory. To check if it works, type:: python ~/web_app.py - This should run a small server on 5000 port. + This should run a small server on ``5000`` port. * Save image -2. Make sure that python-mistralclient have been installed. If not, install it: +2. Make sure that python-mistralclient have been installed. If not, install it:: - git clone https://github.com/stackforge/python-mistralclient.git + git clone https://github.com/openstack/python-mistralclient.git cd python-mistralclient python setup.py install 3. Make sure that Mistral API and at least one Mistral-executor are up and running -4. Make sure that OpenStack actions are active and all actions are shown via: +4. Make sure that OpenStack actions are active and all actions are shown via:: mistral action-list Otherwise need to run *tools/sync.py* from mistral folder. -5. Create workbook and upload the definition +5. Create workbook and upload the definition:: mistral workbook-create *path to calculator.yaml* -6. Create workflow input file (simple json) +6. Create workflow input file (simple json):: { "server_name": "mistral-vm", @@ -67,7 +68,6 @@ Otherwise need to run *tools/sync.py* from mistral folder. "admin_email": "[address the message should be sent to]", } -7. Start execution +7. Start execution:: mistral execution-create calculator.run_calculator *path-to-input-file* - diff --git a/examples/v2/capabilities/join/README.md b/examples/v2/capabilities/join/README.rst similarity index 61% rename from examples/v2/capabilities/join/README.md rename to examples/v2/capabilities/join/README.rst index 6439f90..9007ef6 100644 --- a/examples/v2/capabilities/join/README.md +++ b/examples/v2/capabilities/join/README.rst @@ -1,23 +1,24 @@ +============================================= "join" control example (based on v2 API/DSL) ============================================= -Workflow "create_vm_with_volume" demonstrates usage of "join" workflow control +Workflow ``create_vm_with_volume`` demonstrates usage of ``join`` workflow control to synchronize multiple workflow routes. Specifically, it creates a virtual -machine and Cinder volume in parallel, waits till their completion using "join" +machine and Cinder volume in parallel, waits till their completion using ``join`` and attaches the volume to the newly created virtual machine. Note: Unlike some other examples this example doesn't use workbook concept. -File "create_vm_with_volume" contains a workflow definition in the first place +File ``create_vm_with_volume.yaml`` contains a workflow definition in the first place so in order to load the workflow "mistral workflow-create" CLI command must be used (not "mistral workbook-create"). To run the example: -1. Load workflow create_vm_with_volume.yaml: +1. Load workflow ``create_vm_with_volume.yaml``:: mistral workflow-create create_vm_with_volume.yaml -1. Create input.json file containing workflow input parameters as follows: +2. Create ``input.json`` file containing workflow input parameters as follows:: { "server_name": "mistral_test_vm", @@ -28,13 +29,13 @@ To run the example: "volume_name": "mistral_test_volume" } -1. Start workflow: +3. Start workflow:: mistral execution-create create_vm_with_volume input.json -1. Using execution id from the previous step wait for completion (workflow SUCCESS state): +4. Using execution id from the previous step wait for completion (workflow ``SUCCESS`` state):: mistral execution-get -1. Make sure that a virtual machine and a volume have been created. -It can be done by opening Horizon UI or using Nova client (python-novaclient). +5. Make sure that a virtual machine and a volume have been created. + It can be done by opening Horizon UI or using Nova client (python-novaclient). diff --git a/examples/v2/openstack/README.md b/examples/v2/openstack/README.rst similarity index 55% rename from examples/v2/openstack/README.md rename to examples/v2/openstack/README.rst index 3c34ad7..f86b2e8 100644 --- a/examples/v2/openstack/README.md +++ b/examples/v2/openstack/README.rst @@ -1,4 +1,5 @@ -OpenStack actions examples (based on v2 API/DSL) +================================================ +OpenStack actions examples (based on v3 API/DSL) ================================================ These examples demonstrate how to use OpenStack Mistral actions in Mistral @@ -7,52 +8,52 @@ workflows. Glance actions -------------- -glance_actions.yaml file contains workbook "glance_action" with one workflow -"get_first_glance_image". The purpose of this workflow is to interact with +``glance_actions.yaml`` file contains workbook ``glance_action`` with one workflow +``get_first_glance_image``. The purpose of this workflow is to interact with OpenStack Glance service and obtain information about first encountered Glance image. To run the example: -1. Load workbook from glance_actions.yaml: +1. Load workbook from ``glance_actions.yaml``:: mistral workbook-create glance_actions.yaml -1. Start workflow: +2. Start workflow:: mistral execution-create glance_actions.get_first_glance_image -1. Using execution id from the previous step wait for completion (workflow SUCCESS state): +3. Using execution id from the previous step wait for completion (workflow ``SUCCESS`` state):: mistral execution-get -1. See the result of the workflow (image info): +4. See the result of the workflow (image info):: mistral execution-get-output Keystone actions ---------------- -Similar to the previous example (Glance actions) keystone_actions.yaml file -contains workbook "keystone_actions" with one workflow "get_first_keystone_project". +Similar to the previous example (Glance actions) ``keystone_actions.yaml`` file +contains workbook ``keystone_actions`` with one workflow ``get_first_keystone_project``. The purpose of this workflow is to interact with OpenStack Keystone service and obtain information about first encountered Keystone project. To run the example: -1. Load workbook from keystone_actions.yaml: +1. Load workbook from ``keystone_actions.yaml``:: mistral workbook-create keystone_actions.yaml -1. Start workflow: +2. Start workflow:: mistral execution-create keystone_actions.get_first_keystone_project -1. Using execution id from the previous step wait for completion (workflow SUCCESS state): +3. Using execution id from the previous step wait for completion (workflow ``SUCCESS`` state):: mistral execution-get -1. See the result of the workflow (Keystone project info): +4. See the result of the workflow (Keystone project info):: mistral execution-get-output @@ -60,7 +61,7 @@ To run the example: Nova actions ------------ -Workflow "create_vm" located in workbook file "nova_actions" demonstrates +Workflow ``create_vm`` located in workbook file ``nova_actions.yaml`` demonstrates how to create a new virtual machine with Nova service and wait till it is in active state using "retry" task policy. Unlike other examples this workflow takes input parameters. @@ -68,11 +69,11 @@ takes input parameters. To run the example: -1. Load workbook from nova_actions.yaml: +1. Load workbook from ``nova_actions.yaml``:: mistral workbook-create nova_actions.yaml -1. Create input.json file containing workflow input parameters as follows: +2. Create ``input.json`` file containing workflow input parameters as follows:: { "vm_name": "my_test_virtual_machine", @@ -80,14 +81,14 @@ To run the example: "flavor_ref": "2" } -1. Start workflow: +3. Start workflow:: mistral execution-create nova_actions.create_vm input.json -1. Using execution id from the previous step wait for completion (workflow SUCCESS state): +4. Using execution id from the previous step wait for completion (workflow ``SUCCESS`` state):: mistral execution-get -1. See the result of the workflow (virtual machine identifier): +5. See the result of the workflow (virtual machine identifier):: mistral execution-get-output diff --git a/examples/v2/services_registration/README.md b/examples/v2/services_registration/README.rst similarity index 72% rename from examples/v2/services_registration/README.md rename to examples/v2/services_registration/README.rst index a22e618..18c1e9d 100644 --- a/examples/v2/services_registration/README.md +++ b/examples/v2/services_registration/README.rst @@ -1,3 +1,4 @@ +============================================================ Multiple services registration example (based on v2 API/DSL) ============================================================ @@ -6,25 +7,22 @@ with multiple third party service's API. This specific example works with Vyatta Firewall service and Zabbix monitoring service. It registers a newly created VM in Zabbix service and Vyatta Firewall. It requires two created workflows - Zabbix machine registration and Vyatta -Firewall. They can be found in corresponding directories - 'zabbix' and -'vyatta'. +Firewall. They can be found in corresponding directories - ``zabbix`` and +``vyatta``. How to run ---------- -1. Load workbook from multiple_services_registration.yaml: - +1. Load workbook from multiple_services_registration.yaml:: mistral workbook-create multiple_services_registration.yaml -2. Make sure you have created Zabbix and Vyatta workflows: - +2. Make sure you have created Zabbix and Vyatta workflows:: mistral workbook-update vyatta_firewall.yaml mistral workbook-update zabbix_machine_registration.yaml -3. Create input.json file containing workflow input: - +3. Create ``input.json`` file containing workflow input:: { "server_name": [Name of the new instance], @@ -41,16 +39,15 @@ How to run "vyatta_password": [Vyatta password], } -4. Run the execution: - +4. Run the execution:: mistral execution-create register_in_multiple_services.create_and_register input.json -5. Using execution id from the previous step wait for completion (workflow SUCCESS state): - +5. Using execution id from the previous step wait for completion (workflow + ``SUCCESS`` state):: mistral execution-get -6. Check your Zabbix host group. You will see new host group, one host in it and one simple check item. -Log in your Vyatta and check Firewall service. You will see new accept rule with configured -IP address, protocol and port. \ No newline at end of file +6. Check your Zabbix host group. You will see new host group, one host in it + and one simple check item. Log in your Vyatta and check Firewall service. + You will see new accept rule with configured IP address, protocol and port. diff --git a/examples/v2/services_registration/vyatta/README.md b/examples/v2/services_registration/vyatta/README.rst similarity index 81% rename from examples/v2/services_registration/vyatta/README.md rename to examples/v2/services_registration/vyatta/README.rst index 4830dbd..ad20d32 100644 --- a/examples/v2/services_registration/vyatta/README.md +++ b/examples/v2/services_registration/vyatta/README.rst @@ -1,3 +1,4 @@ +============================================= Vyatta Firewall example (based on v2 API/DSL) ============================================= @@ -10,13 +11,11 @@ service, sets IP address, protocol and port to this rule and commit transaction. How to run ---------- -1. Load workbook from vyatta_firewall.yaml: - +1. Load workbook from ``vyatta_firewall.yaml``:: mistral workbook-create vyatta_firewall.yaml -2. Create input.json file containing workflow input: - +2. Create ``input.json`` file containing workflow input:: { "machine_ip": [your machine IP], @@ -27,15 +26,13 @@ How to run "vyatta_password": [Zabbix password], } -3. Run the execution: - +3. Run the execution:: mistral execution-create vyatta.register_in_vyatta_firewall input.json -4. Using execution id from the previous step wait for completion (workflow SUCCESS state): - +4. Using execution id from the previous step wait for completion (workflow ``SUCCESS`` state):: mistral execution-get 5. Log in your Vyatta and check Firewall service. You will see new accept rule with configured -IP address, protocol and port. \ No newline at end of file + IP address, protocol and port. diff --git a/examples/v2/services_registration/zabbix/README.md b/examples/v2/services_registration/zabbix/README.rst similarity index 82% rename from examples/v2/services_registration/zabbix/README.md rename to examples/v2/services_registration/zabbix/README.rst index 4f81ebe..839cfd4 100644 --- a/examples/v2/services_registration/zabbix/README.md +++ b/examples/v2/services_registration/zabbix/README.rst @@ -1,3 +1,4 @@ +================================================= Zabbix registration example (based on v2 API/DSL) ================================================= @@ -11,13 +12,11 @@ every 5 seconds. How to run ---------- -1. Load workbook from zabbix_machine_registration.yaml: - +1. Load workbook from ``zabbix_machine_registration.yaml``:: mistral workbook-create zabbix_machine_registration.yaml -2. Create input.json file containing workflow input: - +2. Create ``input.json`` file containing workflow input:: { "machine_ip": [your machine IP], @@ -27,13 +26,11 @@ How to run "zabbix_password": [Zabbix password], } -3. Run the execution: - +3. Run the execution:: mistral execution-create zabbix.register_in_zabbix input.json -4. Using execution id from the previous step wait for completion (workflow SUCCESS state): - +4. Using execution id from the previous step wait for completion (workflow ``SUCCESS`` state):: mistral execution-get diff --git a/examples/v2/tenant_statistics/README.md b/examples/v2/tenant_statistics/README.rst similarity index 52% rename from examples/v2/tenant_statistics/README.md rename to examples/v2/tenant_statistics/README.rst index f655b55..6bb16fb 100644 --- a/examples/v2/tenant_statistics/README.md +++ b/examples/v2/tenant_statistics/README.rst @@ -1,22 +1,23 @@ +=============================================== Tenant statistics example (based on v2 API/DSL) =============================================== The example shows how Mistral can be used to gather information about -OpenStack tenant. The workbook "tenant_statistics" contains two workflows +OpenStack tenant. The workbook ``tenant_statistics`` contains two workflows that solve the same task: they send an email report containing a number of virtual machines, number of active virtual machines and number of -networks. Workflow "tenant_statistics_plain" runs runs all its tasks -sequentially one after another. Workflow "tenant_statistics_join" runs +networks. Workflow ``tenant_statistics_plain`` runs runs all its tasks +sequentially one after another. Workflow ``tenant_statistics_join`` runs two tasks in parallel to gather tenant metrics, waits their completion -using "join" workflow control and after that sends a report. +using ``join`` workflow control and after that sends a report. To run the example: -1. Load workbook from tenant_statistics.yaml: +1. Load workbook from ``tenant_statistics.yaml``:: - mistral workbook-create tenant_statistics.yaml + mistral workbook-create tenant_statistics.yaml -1. Create input.json file containing workflow input parameters as follows: +2. Create ``input.json`` file containing workflow input parameters as follows:: { "to_email": "admin@my_domain.com", @@ -25,12 +26,12 @@ To run the example: "smtp_password": "my_password" } -1. Start workflow: +3. Start workflow:: mistral execution-create tenant_statistics.tenant_statistics_join input.json - -1. Using execution id from the previous step wait for completion (workflow SUCCESS state): + +4. Using execution id from the previous step wait for completion (workflow ``SUCCESS`` state):: mistral execution-get -1. Check email inbox for the expected report. +5. Check email inbox for the expected report. diff --git a/setup.cfg b/setup.cfg index bbe2e48..cfda83c 100644 --- a/setup.cfg +++ b/setup.cfg @@ -1,7 +1,7 @@ [metadata] name = mistral-extra summary = Mistral Extras -description-file = README.md +description-file = README.rst #license = Apache Software License classifiers = Programming Language :: Python