This guide is for experienced software developers who want to deploy applications to OpenStack clouds.
If you are familiar with OpenStack but have not created a cloud application in general or an OpenStack application in particular, this section teaches you how to program with OpenStack components.
Deploying applications in a cloud environment can be very different from deploying them in a traditional IT environment. This guide teaches you how to deploy applications on OpenStack and some best practices for cloud application development.
This tutorial shows two applications. The first application is a simple fractal generator that uses mathematical equations to generate beautiful fractal images. We show you this application in its entirety so that you can compare it to a second, more robust, application.
The second application is an OpenStack application that enables you to:
Anyone with a programming background can easily read the code in this guide. Although this guide focuses on a particular SDK, you can use other languages and toolkits with the OpenStack cloud:
Language | Name | Description | URL |
---|---|---|---|
Python | Libcloud | A Python-based library that the Apache Foundation manages. Use it to work with multiple cloud types. | https://libcloud.readthedocs.org/en/latest/compute/drivers/openstack.html |
Python | OpenStack SDK | A Python-based library for OpenStack. | https://developer.openstack.org/sdks/python/openstacksdk/ |
Python | Shade | A Python-based library developed by OpenStack Infra team. Use it to operate multiple OpenStack clouds. | https://docs.openstack.org/infra/shade/ |
Java | jClouds | A Java-based library that the Apache Foundation manages. Use it to work with multiple cloud types. | https://jclouds.apache.org/guides/openstack/ |
Ruby | fog | A Ruby-based SDK. Use it to work with multiple clouds. | https://github.com/fog/fog-openstack/blob/master/docs/getting_started.md |
node.js | pkgcloud | A Node.js-based SDK. Use it work with multiple clouds. | https://github.com/pkgcloud/pkgcloud/tree/master/docs/providers/openstack |
PHP | php-opencloud | A PHP-based library. Use it to write PHP code that works with OpenStack clouds. | http://php-opencloud.readthedocs.org/en/latest/getting-started-with-openstack.html |
.NET Framework | OpenStack SDK for Microsoft .NET | A .NET-based library. Use it to write C++ or C# code for Microsoft applications. | https://www.nuget.org/packages/openstack.net |
Go | gophercloud | A go-based SDK. Use it to write Golang code that works with OpenStack clouds. | http://gophercloud.io/ |
For a list of available SDKs, see Software Development Kits.
Other versions of this guide show you how to use the other SDKs and languages to complete these tasks. If you are a developer for another toolkit that you would like this guide to include, feel free to submit code snippets. For more information, contact OpenStack Documentation team members.
We assume that you can already access an OpenStack cloud. You must have a project, also known as a tenant, with a minimum quota of six instances. Because the Fractals application runs in Ubuntu, Debian, Fedora-based, and openSUSE-based distributions, you must create instances that use one of these operating systems.
To interact with the cloud, you must also have
a recent version of shade library installed.
Note
Before proceeding, install the latest version of shade.
Obtain the following information from your cloud provider:
You can also download the OpenStack RC file from the OpenStack Horizon
dashboard. Log in to the dashboard and click Project->Access &
Security->API Access->Download OpenStack RC file. If you use this method, be
aware that the “auth URL” does not include the path. For example, if your
openrc.sh
file shows:
export OS_AUTH_URL=http://controller:5000/v2.0
The actual auth URL is:
http://controller:5000
In this tutorial, you interact with your OpenStack cloud through the SDK that you chose in “Choose your OpenStack SDK.” This guide assumes that you know how to run code snippets in your language of choice.
Note
Because the tutorial reuses the conn
object,
make sure that you always have one handy.
Use your credentials above to specify the cloud provider name,
username, password, project_name and region_name in the file
~/.config/openstack/clouds.yml
.
clouds:
myfavoriteopenstack:
auth:
auth_url: https://controller:5000/
username: $YOUR_USERNAME
password: $YOUR_PASSWORD
project_name: $YOUR_PROJECT
region_name: $REGION
Note
If you do use a public cloud known by shade,
you can avoid specifying auth_url:
and instead specify
profile: $PROVIDER_NAME
in the clouds.yml file.
To configure shade using a profile, use your credentials above to specify the cloud provider
name, username, password, project name, and region name in the file
~/.config/openstack/clouds.yml
.
my-provider:
profile: $PROVIDER_NAME
auth:
username: $YOUR_USERNAME
password: $YOUR_PASSWORD
project_name: $YOUR_PROJECT
region_name: $REGION
See configure shade, to configure your cloud using a profile.
from shade import *
simple_logging(debug=True)
conn = openstack_cloud(cloud='myfavoriteopenstack')
To run your application, you must launch an instance. This instance serves as a virtual machine.
To launch an instance, you choose a flavor and an image. The flavor represents the size of the instance, including the number of CPUs and amount of RAM and disk space. An image is a prepared OS installation from which you clone your instance. When you boot instances in a public cloud, larger flavors can be more expensive than smaller ones in terms of resources and monetary cost.
To list the images that are available in your cloud, run some API calls:
images = conn.list_images()
for image in images:
print(image)
This code returns output like this:
checksum: 750a56555d4ec7303f5dc33b007ff632
container_format: bare
created_at: '2014-07-14T19:02:15Z'
direct_url:
rbd://7e14670e-a6f8-445b-b632-4b79bafc4781/masseffect-images/b4efbc2a-6130-4f2e-b436-55a618c4de20/snap
disk_format: raw
file: /v2/images/b4efbc2a-6130-4f2e-b436-55a618c4de20/file
id: b4efbc2a-6130-4f2e-b436-55a618c4de20
min_disk: 10
min_ram: 1024
name: Debian-7.0-Wheezy
owner: 0bacd8121bb548698f340455b38bf561
protected: false
schema: /v2/schemas/image
size: 5242880000
status: active
tags: []
updated_at: '2014-10-15T22:42:52Z'
visibility: public
You can also get information about available flavors:
flavors = conn.list_flavors()
for flavor in flavors:
print(flavor)
This code returns output like this:
HUMAN_ID: true
NAME_ATTR: name
OS-FLV-DISABLED:disabled: false
OS-FLV-EXT-DATA:ephemeral: 0
disk: 80
ephemeral: 0
human_id: supersonic
id: '200'
is_public: true
links:
- href:
https://compute.dream.io:8774/v2/5d013ac5962749a49af7ff18c2fb228c/flavors/200
rel: self
- href:
https://compute.dream.io:8774/5d013ac5962749a49af7ff18c2fb228c/flavors/200
rel: bookmark
name: supersonic
os-flavor-access:is_public: true
ram: 2048
swap: ''
vcpus: 1
Your images and flavors will be different, of course.
Choose an image and flavor for your instance. You need about 1GB RAM, 1 CPU, and a 1GB disk. This example uses the Ubuntu image with a small flavor, which is a safe choice. In subsequent tutorial sections in this guide, you must change the image and flavor IDs to correspond to the image and flavor that you choose.
If the image that you want is not available in your cloud, you can usually upload one depending on the policy settings of your cloud. For information about how to upload images, see obtaining images.
Set the image and size variables to appropriate values for your cloud. We will use these variables in later sections.
First, tell the connection to get a specified image by using the ID of the image that you picked in the previous section:
image_id = 'c55094e9-699c-4da9-95b4-2e2e75f4c66e'
image = conn.get_image(image_id)
print(image)
This code returns output like this:
checksum: da578dd59289a35a0ac7744a0bd85cf5
container_format: bare
created_at: '2014-10-27T22:05:37Z'
direct_url:
rbd://7e14670e-a6f8-445b-b632-4b79bafc4781/masseffect-images/c55094e9-699c-4da9-95b4-2e2e75f4c66e/snap
disk_format: raw
file: /v2/images/c55094e9-699c-4da9-95b4-2e2e75f4c66e/file
id: c55094e9-699c-4da9-95b4-2e2e75f4c66e
min_disk: 0
min_ram: 0
name: Ubuntu-14.04-Trusty
owner: 0bacd8121bb548698f340455b38bf561
protected: false
schema: /v2/schemas/image
size: 10737418240
status: active
tags: []
updated_at: '2014-10-27T22:08:55Z'
visibility: public
Next, tell the script which flavor you want to use:
Specify the flavor ID that you would like to use.
flavor_id = '100'
flavor = conn.get_flavor(flavor_id)
print(flavor)
This code returns output like this:
HUMAN_ID: true
NAME_ATTR: name
OS-FLV-DISABLED:disabled: false
OS-FLV-EXT-DATA:ephemeral: 0
disk: 80
ephemeral: 0
human_id: subsonic
id: '100'
is_public: true
links:
- href:
https://compute.dream.io:8774/v2/5d013ac5962749a49af7ff18c2fb228c/flavors/100
rel: self
- href:
https://compute.dream.io:8774/5d013ac5962749a49af7ff18c2fb228c/flavors/100
rel: bookmark
name: subsonic
os-flavor-access:is_public: true
ram: 1024
swap: ''
vcpus: 1
Now, you can launch the instance.
Use your selected image and flavor to create an instance.
Note
The following instance creation example assumes that you have a single-tenant network. If you receive the ‘Exception: 400 Bad Request Multiple possible networks found, use a Network ID to be more specific’ error, you have multiple-tenant networks. You must add a networks parameter to the call that creates the server. See Appendix for details.
Create the instance.
Note
Your SDK might call an instance a ‘node’ or ‘server’.
instance_name = 'testing'
testing_instance = conn.create_server(wait=True, auto_ip=True,
name=instance_name,
image=image_id,
flavor=flavor_id)
print(testing_instance)
If you list existing instances:
instances = conn.list_servers()
for instance in instances:
print(instance)
The new instance appears.
HUMAN_ID: true
NAME_ATTR: name
OS-DCF:diskConfig: MANUAL
OS-EXT-AZ:availability_zone: iad-1
OS-EXT-STS:power_state: 1
OS-EXT-STS:task_state: null
OS-EXT-STS:vm_state: active
OS-SRV-USG:launched_at: '2015-07-20T20:31:10.000000'
OS-SRV-USG:terminated_at: null
accessIPv4: ''
accessIPv6: ''
addresses:
private-network:
- OS-EXT-IPS-MAC:mac_addr: fa:16:3e:60:f5:cd
OS-EXT-IPS:type: fixed
addr: 2607:f298:6050:4e14:f816:3eff:fe60:f5cd
version: 6
- OS-EXT-IPS-MAC:mac_addr: fa:16:3e:60:f5:cd
OS-EXT-IPS:type: fixed
addr: 10.10.10.14
version: 4
config_drive: ''
created: '2015-07-20T20:30:23Z'
flavor:
id: '100'
links:
- href:
https://compute.dream.io:8774/5d013ac5962749a49af7ff18c2fb228c/flavors/100
rel: bookmark
hostId: f71865b497e6fa71063e292b11846eb64b5a41cd5c00fbb7465b6a48
human_id: testing
id: 67ecebdc-daff-4d84-bd04-bc76c67b48ec
image:
id: c55094e9-699c-4da9-95b4-2e2e75f4c66e
links:
- href:
https://compute.dream.io:8774/5d013ac5962749a49af7ff18c2fb228c/images/c55094e9-699c-4da9-95b4-2e2e75f4c66e
rel: bookmark
key_name: null
links:
- href:
https://compute.dream.io:8774/v2/5d013ac5962749a49af7ff18c2fb228c/servers/67ecebdc-daff-4d84-bd04-bc76c67b48ec
rel: self
- href:
https://compute.dream.io:8774/5d013ac5962749a49af7ff18c2fb228c/servers/67ecebdc-daff-4d84-bd04-bc76c67b48ec
rel: bookmark
metadata: {}
name: testing
networks:
private-network:
- 2607:f298:6050:4e14:f816:3eff:fe60:f5cd
- 10.10.10.14
os-extended-volumes:volumes_attached: []
progress: 0
security_groups:
- name: default
status: ACTIVE
tenant_id: 5d013ac5962749a49af7ff18c2fb228c
updated: '2015-07-20T20:31:10Z'
user_id: bfd3dbf1c8a242cd90884408de547bb9
Before you continue, you must do one more thing.
Cloud resources, such as running instances that you no longer use, can cost money. To avoid unexpected expenses, destroy cloud resources.
conn.delete_server(name_or_id=instance_name)
If you list the instances again, the instance disappears.
Leave your shell open to use it for another instance deployment in this section.
Now that you know how to create and delete instances, you can deploy the sample application. The instance that you create for the application is similar to the first instance that you created, but this time, we introduce a few extra concepts.
Note
Internet connectivity from your cloud instance is required to download the application.
When you create an instance for the application, you want to give it a bit more information than you supplied to the bare instance that you just created and deleted. We will go into more detail in later sections, but for now, simply create the following resources so that you can feed them to the instance:
.ssh/id_rsa.pub
. If
you do not have an SSH public key file, follow
these instructions first.
We will cover these instructions in depth in Introduction to the fractals application architecture.In the following example, set pub_key_file
to the location of
your public SSH key file.
print('Checking for existing SSH keypair...')
keypair_name = 'demokey'
pub_key_file = '/home/username/.ssh/id_rsa.pub'
if conn.search_keypairs(keypair_name):
print('Keypair already exists. Skipping import.')
else:
print('Adding keypair...')
conn.create_keypair(keypair_name, open(pub_key_file, 'r').read().strip())
for keypair in conn.list_keypairs():
print(keypair)
print('Checking for existing security groups...')
sec_group_name = 'all-in-one'
if conn.search_security_groups(sec_group_name):
print('Security group already exists. Skipping creation.')
else:
print('Creating security group.')
conn.create_security_group(sec_group_name, 'network access for all-in-one application.')
conn.create_security_group_rule(sec_group_name, 80, 80, 'TCP')
conn.create_security_group_rule(sec_group_name, 22, 22, 'TCP')
conn.search_security_groups(sec_group_name)
ex_userdata = '''#!/usr/bin/env bash
curl -L -s https://git.openstack.org/cgit/openstack/faafo/plain/contrib/install.sh | bash -s -- \
-i faafo -i messaging -r api -r worker -r demo
'''
Now, you can boot and configure the instance.
Use the image, flavor, key pair, and userdata to create an instance. After you request the instance, wait for it to build.
The shade framework can select and assign a free floating IP quickly
instance_name = 'all-in-one'
testing_instance = conn.create_server(wait=True, auto_ip=False,
name=instance_name,
image=image_id,
flavor=flavor_id,
key_name=keypair_name,
security_groups=[sec_group_name],
userdata=ex_userdata)
When the instance boots, the ex_userdata variable value instructs the instance to deploy the Fractals application.
We cover networking in detail in Networking.
To see the application running, you must know where to look for it. By default, your instance has outbound network access. To make your instance reachable from the Internet, you need an IP address. By default in some cases, your instance is provisioned with a publicly rout-able IP address. In this case, you see an IP address listed under public_ips or private_ips when you list the instances. If not, you must create and attach a floating IP address to your instance.
f_ip = conn.available_floating_ip()
Run the script to start the deployment.
Deploying application data and configuration to the instance can take some time. Consider enjoying a cup of coffee while you wait. After the application deploys, you can use your preferred browser to visit the awesome graphic interface at the following link.
print('The Fractals app will be deployed to http://%s' % f_ip['floating_ip_address'] )
Note
If you do not use floating IP addresses, substitute another IP address, as appropriate.
Do not worry if these concepts are not yet completely clear. In Introduction to the fractals application architecture, we explore these concepts in more detail.
The following file contains all of the code from this section of the tutorial. This comprehensive code sample lets you view and run the code as a single script.
Before you run this script, confirm that you have set your authentication information, the flavor ID, and image ID.
#step-1
from shade import *
simple_logging(debug=True)
conn = openstack_cloud(cloud='myfavoriteopenstack')
#step-2
images = conn.list_images()
for image in images:
print(image)
#step-3
flavors = conn.list_flavors()
for flavor in flavors:
print(flavor)
#step-4
image_id = 'c55094e9-699c-4da9-95b4-2e2e75f4c66e'
image = conn.get_image(image_id)
print(image)
#step-5
flavor_id = '100'
flavor = conn.get_flavor(flavor_id)
print(flavor)
#step-6
instance_name = 'testing'
testing_instance = conn.create_server(wait=True, auto_ip=True,
name=instance_name,
image=image_id,
flavor=flavor_id)
print(testing_instance)
#step-7
instances = conn.list_servers()
for instance in instances:
print(instance)
#step-8
conn.delete_server(name_or_id=instance_name)
#step-9
print('Checking for existing SSH keypair...')
keypair_name = 'demokey'
pub_key_file = '/home/username/.ssh/id_rsa.pub'
if conn.search_keypairs(keypair_name):
print('Keypair already exists. Skipping import.')
else:
print('Adding keypair...')
conn.create_keypair(keypair_name, open(pub_key_file, 'r').read().strip())
for keypair in conn.list_keypairs():
print(keypair)
#step-10
print('Checking for existing security groups...')
sec_group_name = 'all-in-one'
if conn.search_security_groups(sec_group_name):
print('Security group already exists. Skipping creation.')
else:
print('Creating security group.')
conn.create_security_group(sec_group_name, 'network access for all-in-one application.')
conn.create_security_group_rule(sec_group_name, 80, 80, 'TCP')
conn.create_security_group_rule(sec_group_name, 22, 22, 'TCP')
conn.search_security_groups(sec_group_name)
#step-11
ex_userdata = '''#!/usr/bin/env bash
curl -L -s https://git.openstack.org/cgit/openstack/faafo/plain/contrib/install.sh | bash -s -- \
-i faafo -i messaging -r api -r worker -r demo
'''
#step-12
instance_name = 'all-in-one'
testing_instance = conn.create_server(wait=True, auto_ip=False,
name=instance_name,
image=image_id,
flavor=flavor_id,
key_name=keypair_name,
security_groups=[sec_group_name],
userdata=ex_userdata)
#step-13
f_ip = conn.available_floating_ip()
#step-14
conn.add_ip_list(testing_instance, [f_ip['floating_ip_address']])
#step-15
print('The Fractals app will be deployed to http://%s' % f_ip['floating_ip_address'] )
Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.