How can I use an OpenStack cloud? As an OpenStack cloud end user, you can provision your own resources within the limits set by administrators. The examples in this guide show you how to complete these tasks by using the OpenStack dashboard and command-line clients. The dashboard, also known as horizon, is a Web-based graphical interface. The command-line clients let you run simple commands to create and manage resources in a cloud and automate tasks by using scripts. Each of the core OpenStack projects has its own command-line client. You can modify these examples for your specific use cases. In addition to these ways of interacting with a cloud, you can access the OpenStack APIs indirectly through cURLcommands or open SDKs, or directly through the APIs. You can automate access or build tools to manage resources and services by using the native OpenStack APIs or the EC2 compatibility API. To use the OpenStack APIs, it helps to be familiar with HTTP/1.1, RESTful web services, the OpenStack services, and JSON or XML data serialization formats. OpenStack dashboard As a cloud end user, the OpenStack dashboard lets you to provision your own resources within the limits set by administrators. You can modify these examples to create other types and sizes of server instances. Overview The following requirements must be fulfilled to access the OpenStack dashboard: The cloud operator has set up an OpenStack cloud. You have a recent Web browser that supports HTML5. It must have cookies and JavaScript enabled. To use the VNC client for the dashboard, which is based on noVNC, your browser must support HTML5 Canvas and HTML5 WebSockets. For more details and a list of browsers that support noVNC, seehttps://github.com/kanaka/noVNC/blob/master/README.md, andhttps://github.com/kanaka/noVNC/wiki/Browser-support, respectively. Learn how to log in to the dashboard and get a short overview of the interface. Log in to the dashboard To log in to the dashboard Ask your cloud operator for the following information: The hostname or public IP address from which you can access the dashboard. The dashboard is available on the node that has the nova-dashboard server role. The username and password with which you can log in to the dashboard. Open a Web browser that supports HTML5. Make sure that JavaScript and cookies are enabled. As a URL, enter the host name or IP address that you got from the cloud operator. https://IP_ADDRESS_OR_HOSTNAME/ On the dashboard log in page, enter your user name and password and click Sign In. After you log in, the following page appears:

The top-level row shows the username that you logged in with. You can also access Settingsor Sign Outof the Web interface. If you are logged in as an end user rather than an admin user, the main screen shows only the Projecttab. OpenStack dashboard – Project tab This tab shows details for the projects, or projects, of which you are a member. Select a project from the drop-down list on the left-hand side to access the following categories: Overview Shows basic reports on the project. Instances Lists instances and volumes created by users of the project. From here, you can stop, pause, or reboot any instances or connect to them through virtual network computing (VNC). Volumes Lists volumes created by users of the project. From here, you can create or delete volumes. Images & Snapshots Lists images and snapshots created by users of the project, plus any images that are publicly available. Includes volume snapshots. From here, you can create and delete images and snapshots, and launch instances from images and snapshots. Access & Security On the Security Groupstab, you can list, create, and delete security groups and edit rules for security groups. On the Keypairstab, you can list, create, and import keypairs, and delete keypairs. On the Floating IPstab, you can allocate an IP address to or release it from a project. On the API Accesstab, you can list the API endpoints. Manage images During setup of OpenStack cloud, the cloud operator sets user permissions to manage images. Image upload and management might be restricted to only cloud administrators or cloud operators. Though you can complete most tasks with the OpenStack dashboard, you can manage images through only the glance and nova clients or the Image Service and Compute APIs. Set up access and security Before you launch a virtual machine, you can add security group rules to enable users to ping and SSH to the instances. To do so, you either add rules to the default security group or add a security group with rules. For information, seethe section called “Add security group rules”. Keypairs are SSH credentials that are injected into images when they are launched. For this to work, the image must contain the cloud-init package. For information, seethe section called “Add keypairs”. Add security group rules The following procedure shows you how to add rules to the default security group. To add rules to the default security group Log in to the OpenStack dashboard. If you are a member of multiple projects, select a project from the drop-down list at the top of the Projecttab. Click the Access & Securitycategory. The dashboard shows the security groups that are available for this project.

Select the default security group and click Edit Rules. The Security Group Rulespage appears:

Add a TCP rule Click Add Rule. The Add Rulewindow appears. In the IP Protocollist, select TCP. In the Openlist, select Port. In the Portbox, enter 22. In the Sourcelist, select CIDR. In the CIDRbox, enter 0.0.0.0/0. Click Add. Port 22 is now open for requests from any IP address. If you want to accept requests from a particular range of IP addresses, specify the IP address block in the CIDRbox. Add an ICMP rule Click Add Rule. The Add Rulewindow appears. In the IP Protocollist, select ICMP. In the Typebox, enter -1. In the Codebox, enter -1. In the Sourcelist, select CIDR. In the CIDRbox, enter 0.0.0.0/0. Click Add. Add keypairs Create at least one keypair for each project. If you have generated a keypair with an external tool, you can import it into OpenStack. The keypair can be used for multiple instances that belong to a project. To add a keypair Log in to the OpenStack dashboard. If you are a member of multiple projects, select a project from the drop-down list at the top of the Projecttab. Click the Access & Securitycategory. Click the Keypairstab. The dashboard shows the keypairs that are available for this project. To add a keypair Click Create Keypair. The Create Keypairwindow appears. In the Keypair Namebox, enter a name for your keypair. Click Create Keypair. Respond to the prompt to download the keypair. To import a keypair Click Import Keypair. The Import Keypairwindow appears. In the Keypair Namebox, enter the name of your keypair. In the Public Keybox, copy the public key. Click Import Keypair. Save the *.pem file locally and change its permissions so that only you can read and write to the file: $ chmod 0600 MY_PRIV_KEY.pem Use the ssh-addcommand to make the keypair known to SSH: $ ssh-add MY_PRIV_KEY.pem The public key of the keypair is registered in the Nova database. The dashboard lists the keypair in the Access & Securitycategory. Launch instances Instances are virtual machines that run inside the cloud. You can launch an instance directly from one of the available OpenStack images or from an image that you have copied to a persistent volume. The OpenStack Image Service provides a pool of images that are accessible to members of different projects. Launch an instance from an image When you launch an instance from an image, OpenStack creates a local copy of the image on the respective compute node where the instance is started. To launch an instance from an image Log in to the OpenStack dashboard. If you are a member of multiple projects, select a project from the drop-down list at the top of the Projecttab. Click the Images & Snapshotcategory. The dashboard shows the images that have been uploaded to OpenStack Image Service and are available for this project. Select an image and click Launch. In the Launch Imagewindow, specify the following: Enter an instance name to assign to the virtual machine. From the Flavordrop-down list, select the size of the virtual machine to launch. Select a keypair. In case an image uses a static root password or a static key set (neither is recommended), you do not need to provide a keypair to launch the instance. In Instance Count, enter the number of virtual machines to launch from this image. Activate the security groups that you want to assign to the instance. Security groups are a kind of cloud firewall that define which incoming network traffic should be forwarded to instances. For details, seethe section called “Add security group rules”. If you have not created any specific security groups, you can only assign the instance to the default security group. If you want to boot from volume, click the respective entry to expand its options. Set the options as described inthe section called “Launch an instance from a volume”. Click Launch Instance. The instance is started on any of the compute nodes in the cloud. After you have launched an instance, switch to the Instancescategory to view the instance name, its (private or public) IP address, size, status, task, and power state. Figure 5. OpenStack dashboard – Instances If you did not provide a keypair, security groups, or rules so far, by default the instance can only be accessed from inside the cloud through VNC at this point. Even pinging the instance is not possible. To access the instance through a VNC console, seethe section called “Get a console to an instance”. Launch an instance from a volume You can launch an instance directly from an image that has been copied to a persistent volume. In that case, the instance is booted from the volume, which is provided by nova-volume, through iSCSI. For preparation details, seethe section called “Create or delete a volume”. To boot an instance from the volume, especially note the following steps: To be able to select from which volume to boot, launch an instance from an arbitrary image. The image you select does not boot. It is replaced by the image on the volume that you choose in the next steps. In case you want to boot a Xen image from a volume, note the following requirement: The image you launch in must be the same type, fully virtualized or paravirtualized, as the one on the volume. Select the volume or volume snapshot to boot from. Enter a device name. Enter vda for KVM images or xvda for Xen images. To launch an instance from a volume You can launch an instance directly from one of the images available through the OpenStack Image Service or from an image that you have copied to a persistent volume. When you launch an instance from a volume, the procedure is basically the same as when launching an instance from an image in OpenStack Image Service, except for some additional steps. Create a volume as described inthe section called “Create or delete a volume”. It must be large enough to store an unzipped image. Create an image. For details, see Creating images manually in the OpenStack Virtual Machine Image Guide. Launch an instance. Attach the volume to the instance as described inthe section called “Attach volumes to instances”. Assuming that the attached volume is mounted as /dev/vdb, use one of the following commands to copy the image to the attached volume: For a raw image: $ cat IMAGE >/dev/null Alternatively, use dd. For a non-raw image: $ qemu-img convert -O raw IMAGE /dev/vdb For a *.tar.bz2 image: $ tar xfjO IMAGE >/dev/null Only detached volumes are available for booting. Detach the volume. To launch an instance from the volume, continue withthe section called “Launch an instance from an image”. You can launch an instance directly from one of the images available through the OpenStack Image Service. When you do that, OpenStack creates a local copy of the image on the respective compute node where the instance is started. SSH in to your instance To SSH into your instance, you use the downloaded keypair file. To SSH into your instance Copy the IP address for your instance. Use the SSH command to make a secure connection to the instance. For example: $ ssh -i MyKey.pem ubuntu@10.0.0.2 A prompt asks, "Are you sure you want to continue connection (yes/no)?" Type yes and you have successfully connected. Manage instances Create instance snapshots

To create instance snapshots Log in to the OpenStack dashboard. If you are a member of multiple projects, select a project from the drop-down list at the top of the Projecttab. Click the Instancescategory. The dashboard lists the instances that are available for this project. Select the instance of which to create a snapshot. From the Actionsdrop-down list, select Create Snapshot. In the Create Snapshotwindow, enter a name for the snapshot. Click Create Snapshot. The dashboard shows the instance snapshot in the Images & Snapshotscategory. To launch an instance from the snapshot, select the snapshot and click Launch. Proceed withthe section called “Launch an instance from an image”. Control the state of an instance To control the state of an instance Log in to the OpenStack dashboard. If you are a member of multiple projects, select a project from the drop-down list at the top of the Projecttab. Click the Instancescategory. The dashboard lists the instances that are available for this project. Select the instance for which you want to change the state. In the Moredrop-down list in the Actionscolumn, select the state. Depending on the current state of the instance, you can choose to pause, un-pause, suspend, resume, soft or hard reboot, or terminate an instance.

Track usage Use the dashboard's Overviewcategory to track usage of instances for each project.

You can track costs per month by showing metrics like number of VCPUs, disks, RAM, and uptime of all your instances. To track usage If you are a member of multiple projects, select a project from the drop-down list at the top of the Projecttab. Select a month and click Submitto query the instance usage for that month. Click Download CSV Summaryto download a CVS summary. Manage volumes Volumes are block storage devices that you can attach to instances. They allow for persistent storage as they can be attached to a running instance, or detached and attached to another instance at any time. In contrast to the instance's root disk, the data of volumes is not destroyed when the instance is deleted. Create or delete a volume To create or delete a volume Log in to the OpenStack dashboard. If you are a member of multiple projects, select a Projectfrom the drop-down list at the top of the tab. Click the Volumescategory. To create a volume Click Create Volume. In the window that opens, enter a name to assign to a volume, a description (optional), and define the size in GBs. Confirm your changes. The dashboard shows the volume in the Volumescategory. To delete one or multiple volumes Activate the checkboxes in front of the volumes that you want to delete. Click Delete Volumesand confirm your choice in the pop-up that appears. A message indicates whether the action was successful. After you create one or more volumes, you can attach them to instances. You can attach a volume to one instance at a time. View the status of a volume in the Instances & Volumescategory of the dashboard: the volume is either available or In-Use. Attach volumes to instances To attach volumes to instances Log in to OpenStack dashboard. If you are a member of multiple projects, select a Projectfrom the drop-down list at the top of the tab. Click the Volumescategory. Select the volume to add to an instance and click Edit Attachments. In the Manage Volume Attachmentswindow, select an instance. Enter a device name under which the volume should be accessible on the virtual machine. Click Attach Volumeto confirm your changes. The dashboard shows the instance to which the volume has been attached and the volume's device name. Now you can log in to the instance, mount the disk, format it, and use it. To detach a volume from an instance Select the volume and click Edit Attachments. Click Detach Volumeand confirm your changes. A message indicates whether the action was successful. OpenStack command-line clients Overview You can use the OpenStack command-line clients to run simple commands that make API calls and automate tasks by using scripts. Internally, each client command runs cURL commands that embed API requests. The OpenStack APIs are RESTful APIs that use the HTTP protocol, including methods, URIs, media types, and response codes. These open-source Python clients run on Linux or Mac OS X systems and are easy to learn and use. Each OpenStack service has its own command-line client. On some client commands, you can specify a debugparameter to show the underlying API request for the command. This is a good way to become familiar with the OpenStack API calls. The following command-line clients are available for the respective services' APIs: cinder(python-cinderclient) Client for the Block Storage service API. Use to create and manage volumes. glance(python-glanceclient) Client for the Image Service API. Use to create and manage images. keystone(python-keystoneclient) Client for the Identity Service API. Use to create and manage users, tenants, roles, endpoints, and credentials. nova(python-novaclient) Client for the Compute API and its extensions. Use to create and manage images, instances, and flavors. neutron(python-neutronclient) Client for the Networking API. Use to configure networks for guest servers. This client was previously known as neutron. swift(python-swiftclient) Client for the Object Storage API. Use to gather statistics, list items, update metadata, upload, download and delete files stored by the object storage service. Provides access to a swift installation for ad hoc processing. heat(python-heatclient) Client for the Orchestration API. Use to launch stacks from templates, view details of running stacks including events and resources, and update and delete stacks. Install the OpenStack command-line clients To install the clients, install the prerequisite software and the Python package for each OpenStack client. Install the clients Use pipto install the OpenStack clients on a Mac OS X or Linux system. It is easy and ensures that you get the latest version of the client from thePython Package Index. Also, piplets you update or remove a package. After you install the clients, you must source an openrc file to set required environment variables before you can request OpenStack services through the clients or the APIs. To install the clients You must install each client separately. Run the following command to install or update a client package: # pip install [--update] python-<project>client Where <project> is the project name and has one of the following values: nova. Compute API and extensions. neutron. Networking API. keystone. Identity Service API. glance. Image Service API. swift. Object Storage API. cinder. Block Storage service API. heat. Orchestration API. For example, to install the nova client, run the following command: # pip install python-novaclient To update the nova client, run the following command: # pip install --upgrade python-novaclient To remove the nova client, run the following command: # pip uninstall python-novaclient Before you can issue client commands, you must download and source the openrc file to set environment variables. Proceed tothe section called “OpenStack RC file”. Get the version for a client After you install an OpenStack client, you can search for its version number, as follows: $ pip freeze | grep python- python-glanceclient==0.4.0python-keystoneclient==0.1.2-e git+https://github.com/openstack/python-novaclient.git@077cc0bf22e378c4c4b970f2331a695e440a939f#egg=python_novaclient-devpython-neutronclient==0.1.1python-swiftclient==1.1.1 You can also use the yolk -lcommand to see which version of the client is installed: $ yolk -l | grep python-novaclient python-novaclient - 2.6.10.27 - active development (/Users/your.name/src/cloud-servers/src/src/python-novaclient)python-novaclient - 2012.1 - non-active OpenStack RC file To set the required environment variables for the OpenStack command-line clients, you must download and source an environment file, openrc.sh. It is project-specific and contains the credentials used by OpenStack Compute, Image, and Identity services. When you source the file and enter the password, environment variables are set for that shell. They allow the commands to communicate to the OpenStack services that run in the cloud. You can download the file from the OpenStack dashboard as an administrative user or any other user. To download the OpenStack RC file Log in to the OpenStack dashboard. On the Projecttab, select the project for which you want to download the OpenStack RC file. Click Access & Security. Then, click Download OpenStack RC Fileand save the file. Copy the openrc.sh file to the machine from where you want to run OpenStack commands. For example, copy the file to the machine from where you want to upload an image with a glance client command. On any shell from where you want to run OpenStack commands, source the openrc.sh file for the respective project. In this example, we source the demo-openrc.sh file for the demo project: $ source demo-openrc.sh When you are prompted for an OpenStack password, enter the OpenStack password for the user who downloaded the openrc.sh file. When you run OpenStack client commands, you can override some environment variable settings by using the options that are listed at the end of the nova helpoutput. For example, you can override the OS_PASSWORD setting in the openrc.sh file by specifying a password on a nova command, as follows: $ nova --password <password> image-list Where password is your password. Manage images During setup of OpenStack cloud, the cloud operator sets user permissions to manage images. Image upload and management might be restricted to only cloud administrators or cloud operators. After you upload an image, it is considered golden and you cannot change it. You can upload images through the glance client or the Image Service API. You can also use the nova client to list images, set and delete image metadata, delete images, and take a snapshot of a running instance to create an image. Manage images with the glance client To list or get details for images To list the available images: $ glance image-list You can use grep to filter the list, as follows: $ glance image-list | grep 'cirros' To get image details, by name or ID: $ glance image-show myCirrosImage To add an image The following example uploads a CentOS 6.3 image in qcow2 format and configures it for public access: $glance image-create --name centos63-image --disk-format=qcow2 --container-format=bare --is-public=True ./centos63.qcow2 To create an image Write any buffered data to disk. For more information, see theTaking Snapshots in the OpenStack Operations Guide. To create the image, list instances to get the server ID: $ nova list In this example, the server is named myCirrosServer. Use this server to create a snapshot, as follows: $ nova image-create myCirrosServer myCirrosImage The command creates a qemu snapshot and automatically uploads the image to your repository. Only the tenant that creates the image has access to it. Get details for your image to check its status: $ nova image-show IMAGE The image status changes from SAVING to ACTIVE. Only the tenant who creates the image has access to it. To launch an instance from your image To launch an instance from your image, include the image ID and flavor ID, as follows: $ nova boot newServer --image 7e5142af-1253-4634-bcc6-89482c5f2e8a --flavor 3 Troubleshoot image creation You cannot create a snapshot from an instance that has an attached volume. Detach the volume, create the image, and re-mount the volume. Make sure the version of qemu you are using is version 0.14 or greater. Older versions of qemu result in an "unknown option -s" error message in the nova-compute.log. Examine the /var/log/nova-api.log and /var/log/nova-compute.log log files for error messages. Set up access and security for instances When you launch a virtual machine, you can inject a key pair, which provides SSH access to your instance. For this to work, the image must contain the cloud-init package. Create at least one key pair for each project. If you generate a keypair with an external tool, you can import it into OpenStack. You can use the key pair for multiple instances that belong to that project. In case an image uses a static root password or a static key set – neither is recommended – you must not provide a key pair when you launch the instance. A security group is a named collection of network access rules that you use to limit the types of traffic that have access to instances. When you launch an instance, you can assign one or more security groups to it. If you do not create security groups, new instances are automatically assigned to the default security group, unless you explicitly specify a different security group. The associated rules in each security group control the traffic to instances in the group. Any incoming traffic that is not matched by a rule is denied access by default. You can add rules to or remove rules from a security group. You can modify rules for the default and any other security group. You must modify the rules for the default security group because users cannot access instances that use the default group from any IP address outside the cloud. You can modify the rules in a security group to allow access to instances through different ports and protocols. For example, you can modify rules to allow access to instances through SSH, to ping them, or to allow UDP traffic – for example, for a DNS server running on an instance. You specify the following parameters for rules: Source of traffic. Enable traffic to instances from either IP addresses inside the cloud from other group members or from all IP addresses. Protocol. Choose TCP for SSH, ICMP for pings, or UDP. Destination port on virtual machine. Defines a port range. To open a single port only, enter the same value twice. ICMP does not support ports: Enter values to define the codes and types of ICMP traffic to be allowed. Rules are automatically enforced as soon as you create or modify them. You can also assign a floating IP address to a running instance to make it accessible from outside the cloud. You assign a floating IP address to an instance and attach a block storage device, or volume, for persistent storage. Add or import keypairs To add a key You can generate a keypair or upload an existing public key. To generate a keypair, run the following command: $ nova keypair-add KEY_NAME > MY_KEY.pem The command generates a keypair named KEY_NAME, writes the private key to the MY_KEY.pem file, and registers the public key at the Nova database. To set the permissions of the MY_KEY.pem file, run the following command: $ chmod 600 MY_KEY.pem The command changes the permissions of the MY_KEY.pem file so that only you can read and write to it. To import a key If you have already generated a keypair with the public key located at ~/.ssh/id_rsa.pub, run the following command to upload the public key: $ nova keypair-add --pub_key ~/.ssh/id_rsa.pub KEY_NAME The command registers the public key at the Nova database and names the keypair KEY_NAME. List keypairs to make sure that the uploaded keypair appears in the list: $ nova keypair-list Configure security groups and rules To configure security groups To list all security groups To list security groups for the current project, including descriptions, enter the following command: $ nova secgroup-list To create a security group To create a security group with a specified name and description, enter the following command: $ nova secgroup-create SEC_GROUP_NAME GROUP_DESCRIPTION To delete a security group To delete a specified group, enter the following command: $ nova secgroup-delete SEC_GROUP_NAME To configure security group rules Modify security group rules with the nova secgroup-*-rulecommands. On a shell, source the OpenStack RC file. For details, seethe section called “OpenStack RC file”. To list the rules for a security group $ nova secgroup-list-rules SEC_GROUP_NAME To allow SSH access to the instances Choose one of the following sub-steps: Add rule for all IPs Either from all IP addresses (specified as IP subnet in CIDR notation as 0.0.0.0/0): $ nova secgroup-add-rule SEC_GROUP_NAME tcp 22 22 0.0.0.0/0 Add rule for security groups Alternatively, you can allow only IP addresses from other security groups (source groups) to access the specified port: $ nova secgroup-add-group-rule --ip_proto tcp --from_port 22 \ --to_port 22 SEC_GROUP_NAME SOURCE_GROUP_NAME To allow pinging the instances Choose one of the following sub-steps: To allow pinging from IPs Specify all IP addresses as IP subnet in CIDR notation: 0.0.0.0/0. This command allows access to all codes and all types of ICMP traffic, respectively: $ nova secgroup-add-rule SEC_GROUP_NAME icmp -1 -1 0.0.0.0/0 To allow pinging from other security groups To allow only members of other security groups (source groups) to ping instances: $ nova secgroup-add-group-rule --ip_proto icmp --from_port -1 \ --to_port -1 SEC_GROUP_NAME SOURCE_GROUP_NAME To allow access through UDP port To allow access through a UDP port, such as allowing access to a DNS server that runs on a VM, complete one of the following sub-steps: To allow UDP access from IPs Specify all IP addresses as IP subnet in CIDR notation: 0.0.0.0/0. $ nova secgroup-add-rule SEC_GROUP_NAME udp 53 53 0.0.0.0/0 To allow UDP access To allow only IP addresses from other security groups (source groups) to access the specified port: $ nova secgroup-add-group-rule --ip_proto udp --from_port 53 \ --to_port 53 SEC_GROUP_NAME SOURCE_GROUP_NAME To delete a security group rule, specify the same arguments that you used to create the rule. To delete the security rule that you created inStep 3.a: $ nova secgroup-delete-rule SEC_GROUP_NAME tcp 22 22 0.0.0.0/0 To delete the security rule that you created inStep 3.b: $ nova secgroup-delete-group-rule --ip_proto tcp --from_port 22 \ --to_port 22 SEC_GROUP_NAME SOURCE_GROUP_NAME Launch instances Instances are virtual machines that run inside the cloud. Before you can launch an instance, you must gather parameters such as the image and flavor from which you want to launch your instance. You can launch an instance directly from one of the available OpenStack images or from an image that you have copied to a persistent volume. The OpenStack Image Service provides a pool of images that are accessible to members of different projects. Gather parameters to launch an instance To launch an instance, you must specify the following parameters: The instance source, which is an image or snapshot. Alternatively, you can boot from a volume, which is block storage, to which you've copied an image or snapshot. The image or snapshot, which represents the operating system. A name for your instance. The flavor for your instance, which defines the compute, memory, and storage capacity of nova computing instances. A flavor is an available hardware configuration for a server. It defines the "size" of a virtual server that can be launched. For more details and a list of default flavors available, see Section 1.5, "Managing Flavors," (⇽ User Guide for Administrators ). User Data is a special key in the metadata service which holds a file that cloud aware applications within the guest instance can access. For example thecloudinitsystem is an open source package from Ubuntu that handles early initialization of a cloud instance that makes use of this user data. Access and security credentials, which include one or both of the following credentials: A key-pair for your instance, which are SSH credentials that are injected into images when they are launched. For this to work, the image must contain the cloud-init package. Create at least one keypair for each project. If you already have generated a key-pair with an external tool, you can import it into OpenStack. You can use the keypair for multiple instances that belong to that project. For details, refer to Section 1.5.1, Creating or Importing Keys. A security group, which defines which incoming network traffic is forwarded to instances. Security groups hold a set of firewall policies, known as security group rules. For details, see xx. If needed, you can assign a floating (public) IP addressto a running instance and attach a block storage device, or volume, for persistent storage. For details, see Section 1.5.3, Managing IP Addresses and Section 1.7, Managing Volumes. After you gather the parameters you need to launch an instance, you can launch it from animageor avolume. To gather the parameters to launch an instance On a shell, source the OpenStack RC file. List the available flavors: $ nova flavor-list Note the ID of the flavor that you want to use for your instance. List the available images: $ nova image-list You can also filter the image list by using grep to find a specific image, like this: $ nova image-list | grep 'kernel' Note the ID of the image that you want to boot your instance from. List the available security groups: $ nova secgroup-list --all-tenants If you have not created any security groups, you can assign the instance to only the default security group. You can also list rules for a specified security group: $ nova secgroup-list-rules default In this example, the default security group has been modified to allow HTTP traffic on the instance by permitting TCP traffic on Port 80. List the available keypairs. $ nova keypair-list Note the name of the keypair that you use for SSH access. Launch an instance from an image Use this procedure to launch an instance from an image. To launch an instance from an image Now you have all parameters required to launch an instance, run the following command and specify the server name, flavor ID, and image ID. Optionally, you can provide a key name for access control and security group for security. You can also include metadata key and value pairs. For example you can add a description for your server by providing the --meta description="My Server"parameter. You can pass user data in a file on your local system and pass it at instance launch by using the flag --user-data <user-data-file>. $ nova boot --flavor FLAVOR_ID --image IMAGE_ID --key_name KEY_NAME --user-data mydata.file \ --security_group SEC_GROUP NAME_FOR_INSTANCE --meta KEY=VALUE --meta KEY=VALUE The command returns a list of server properties, depending on which parameters you provide. A status of BUILD indicates that the instance has started, but is not yet online. A status of ACTIVE indicates that your server is active. Copy the server ID value from the id field in the output. You use this ID to get details for or delete your server. Copy the administrative password value from the adminPass field. You use this value to log into your server. Check if the instance is online: $ nova list This command lists all instances of the project you belong to, including their ID, their name, their status, and their private (and if assigned, their public) IP addresses. If the status for the instance is ACTIVE, the instance is online. To view the available options for the nova listcommand, run the following command: $ nova help list If you did not provide a keypair, security groups, or rules, you can only access the instance from inside the cloud through VNC. Even pinging the instance is not possible. Launch an instance from a volume After youcreate a bootable volume, youlaunch an instance from the volume. To launch an instance from a volume To create a bootable volume To create a volume from an image, run the following command: # cinder create --image-id 397e713c-b95b-4186-ad46-6126863ea0a9 --display-name my-bootable-vol 8 Optionally, to configure your volume, see the Configuring Image Service and Storage for Computechapter in the OpenStack Configuration Reference. To list volumes Enter the following command: $ nova volume-list Copy the value in the ID field for your volume. To launch an instance Enter the nova boot command with the --block_device_mapping parameter, as follows: $ nova boot --flavor <flavor> --block_device_mapping <dev_name>=<id>:<type>:<size>:<delete_on_terminate> <name> The command arguments are: --flavor flavor The flavor ID. --block_device_mapping dev- name=id:type:size:delete-on-terminate dev-name. A device name where the volume is attached in the system at /dev/dev_name. This value is typically vda. id. The ID of the volume to boot from, as shown in the output of nova volume-list. type. Either snap or any other value, including a blank string. snap means that the volume was created from a snapshot. size. The size of the volume, in GBs. It is safe to leave this blank and have the Compute service infer the size. delete-on-terminate. A boolean that indicates whether the volume should be deleted when the instance is terminated. You can specify True or 1 False or 0 name The name for the server. For example, you might enter the following command to boot from a volume with ID bd7cf584-45de-44e3-bf7f-f7b50bf235e. The volume is not deleted when the instance is terminated: $ nova boot --flavor 2 --image 397e713c-b95b-4186-ad46-6126863ea0a9 --block_device_mapping vda=bd7cf584-45de-44e3-bf7f-f7b50bf235e3:::0 myInstanceFromVolume Now when you list volumes, you can see that the volume is attached to a server: $ nova volume-list Additionally, when you list servers, you see the server that you booted from a volume: $ nova list Manage instances and hosts Instances are virtual machines that run inside the cloud. Manage IP addresses Each instance can have a private, or fixed, IP address and a public, or floating, one. Private IP addresses are used for communication between instances, and public ones are used for communication with the outside world. When you launch an instance, it is automatically assigned a private IP address that stays the same until you explicitly terminate the instance. Rebooting an instance has no effect on the private IP address. A pool of floating IPs, configured by the cloud operator, is available in OpenStack Compute. You can allocate a certain number of these to a project: The maximum number of floating IP addresses per project is defined by the quota. You can add a floating IP address from this set to an instance of the project. Floating IP addresses can be dynamically disassociated and associated with other instances of the same project at any time. Before you can assign a floating IP address to an instance, you first must allocate floating IPs to a project. After floating IP addresses have been allocated to the current project, you can assign them to running instances. One floating IP address can be assigned to only one instance at a time. Floating IP addresses can be managed with the nova *floating-ip-*commands, provided by the python-novaclient package. To list pools with floating IP addresses To list all pools that provide floating IP addresses: $ nova floating-ip-pool-list To allocate a floating IP address to the current project The output of the following command shows the freshly allocated IP address: $ nova floating-ip-pool-list If more than one pool of IP addresses is available, you can also specify the pool from which to allocate the IP address: $ floating-ip-create POOL_NAME To list floating IP addresses allocated to the current project If an IP is already associated with an instance, the output also shows the IP for the instance, thefixed IP address for the instance, and the name of the pool that provides the floating IP address. $ nova floating-ip-list To release a floating IP address from the current project The IP address is returned to the pool of IP addresses that are available for all projects. If an IP address is currently assigned to a running instance, it is automatically disassociated from the instance. $ nova floating-ip-delete FLOATING_IP To assign a floating IP address to an instance To associate an IP address with an instance, one or multiple floating IP addresses must be allocated to the current project. Check this with: $ nova floating-ip-list In addition, you must know the instance's name (or ID). To look up the instances that belong to the current project, use the nova list command. $ nova add-floating-ip INSTANCE_NAME_OR_ID FLOATING_IP After you assign the IP with nova add-floating-ipand configure security group rules for the instance, the instance is publicly available at the floating IP address. To remove a floating IP address from an instance To remove a floating IP address from an instance, you must specify the same arguments that you used to assign the IP. $ nova remove-floating-ip INSTANCE_NAME_OR_ID FLOATING_IP Change the size of your server You change the size of a server by changing its flavor. To change the size of your server List the available flavors: $ nova flavor-list Show information about your server, including its size: $ nova show myCirrosServer The size of the server is m1.small (2). To resize the server, pass the server ID and the desired flavor to the nova resizecommand. Include the --poll parameter to report the resize progress. $ nova resize myCirrosServer 4 --poll Instance resizing... 100% completeFinished Show the status for your server: $ nova list When the resize completes, the status becomes VERIFY_RESIZE. To confirm the resize: $ nova resize-confirm 6beefcf7-9de6-48b3-9ba9-e11b343189b3 The server status becomes ACTIVE. If the resize fails or does not work as expected, you can revert the resize: $ nova resize-revert 6beefcf7-9de6-48b3-9ba9-e11b343189b3 The server status becomes ACTIVE. Stop and start an instance Use one of the following methods to stop and start an instance. Pause and un-pause an instance To pause and un-pause a server To pause a server, run the following command: $ nova pause SERVER This command stores the state of the VM in RAM. A paused instance continues to run in a frozen state. To un-pause the server, run the following command: $ nova unpause SERVER Suspend and resume an instance To suspend and resume a server Administrative users might want to suspend an infrequently used instance or to perform system maintenance. When you suspend an instance, its VM state is stored on disk, all memory is written to disk, and the virtual machine is stopped. Suspending an instance is similar to placing a device in hibernation; memory and vCPUs become available. To initiate a hypervisor-level suspend operation, run the following command: $ nova suspend SERVER To resume a suspended server: $ nova resume SERVER Reboot an instance You can perform a soft or hard reboot of a running instance. A soft reboot attempts a graceful shutdown and restart of the instance. A hard reboot power cycles the instance. To reboot a server By default, when you reboot a server, it is a soft reboot. $ nova reboot SERVER To perform a hard reboot, pass the --hard parameter, as follows: $ nova reboot --hard SERVER Evacuate instances If a cloud compute node fails due to a hardware malfunction or another reason, you can evacuate instances to make them available again. You can choose evacuation parameters for your use case. To preserve user data on server disk, you must configure shared storage on the target host. Also, you must validate that the current VM host is down. Otherwise the evacuation fails with an error. To evacuate your server To find a different host for the evacuated instance, run the following command to lists hosts: $ nova host-list You can pass the instance password to the command by using the --password <pwd> option. If you do not specify a password, one is generated and printed after the command finishes successfully. The following command evacuates a server without shared storage: $ nova evacuate evacuated_server_name host_b The command evacuates an instance from a down host to a specified host. The instance is booted from a new disk, but preserves its configuration including its ID, name, uid, IP address, and so on. The command returns a password: To preserve the user disk data on the evacuated server, deploy OpenStack Compute with shared filesystem. $ nova evacuate evacuated_server_name host_b --on-shared-storage Delete an instance When you no longer need an instance, you can delete it. To delete an instance List all instances: $ nova list Use the following command to delete the newServer instance, which is in ERROR state: $ nova delete newServer The command does not notify that your server was deleted. Instead, run the nova list command: $ nova list The deleted instance does not appear in the list. Get a console to an instance To get a console to an instance To get a VNC console to an instance, run the following command: $ nova get-vnc-console myCirrosServer xvpvnc The command returns a URL from which you can access your instance: Manage bare metal nodes If you use the bare metal driver, you must create a bare metal node and add a network interface to it. You then launch an instance from a bare metal image. You can list and delete bare metal nodes. When you delete a node, any associated network interfaces are removed. You can list and remove network interfaces that are associated with a bare metal node. Commands baremetal-interface-add Adds a network interface to a bare metal node. baremetal-interface-list Lists network interfaces associated with a bare metal node. baremetal-interface-remove Removes a network interface from a bare metal node. baremetal-node-create Creates a bare metal node. baremetal-node-delete Removes a bare metal node and any associated interfaces. baremetal-node-list Lists available bare metal nodes. baremetal-node-show Shows information about a bare metal node. To manage bare metal nodes Create a bare metal node. $ nova baremetal-node-create --pm_address=1.2.3.4 --pm_user=ipmi --pm_password=ipmi $(hostname -f) 1 512 10 aa:bb:cc:dd:ee:ff Add network interface information to the node: $ nova baremetal-interface-add 1 aa:bb:cc:dd:ee:ff Launch an instance from a bare metal image: $ nova boot --image my-baremetal-image --flavor my-baremetal-flavor test |... wait for instance to become active ... You can list bare metal nodes and interfaces. When a node is in use, its status includes the UUID of the instance that runs on it: $ nova baremetal-node-list Show details about a bare metal node: $ nova baremetal-node-show 1 Show usage statistics for hosts and instances You can show basic statistics on resource usage for hosts and instances. To show host usage statistics List the hosts and the nova-related services that run on them: $ nova host-list Get a summary of resource usage of all of the instances running on the host. $ nova host-describe devstack-grizzly The cpu column shows the sum of the virtual CPUs for instances running on the host. The memory_mb column shows the sum of the memory (in MB) allocated to the instances that run on the hosts. The disk_gb column shows the sum of the root and ephemeral disk sizes (in GB) of the instances that run on the hosts. To show instance usage statistics Get CPU, memory, I/O, and network statistics for an instance. First, list instances: $ nova list Then, get diagnostic statistics: $ nova diagnostics myCirrosServer Get summary statistics for each tenant: $ nova usage-list Usage from 2013-06-25 to 2013-07-24: Create and manage networks Before you run commands, set the following environment variables: export OS_USERNAME=adminexport OS_PASSWORD=passwordexport OS_TENANT_NAME=adminexport OS_AUTH_URL=http://localhost:5000/v2.0 To create and manage networks List the extensions of the system: $ neutron ext-list -c alias -c name Create a network: $ neutron net-create net1 Created a new network: Create a network with specified provider network type: $ neutron net-create net2 --provider:network-type local Created a new network: Just as shown previous, the unknown option --provider:network-type is used to create a local provider network. Create a subnet: $ neutron subnet-create net1 192.168.2.0/24 --name subnet1 Created a new subnet: In the previous command, net1 is the network name, 192.168.2.0/24 is the subnet's CIDR. They are positional arguments. --name subnet1 is an unknown option, which specifies the subnet's name. Create a port with specified IP address: $ neutron port-create net1 --fixed-ip ip_address=192.168.2.40 Created a new port: In the previous command, net1 is the network name, which is a positional argument. --fixed-ip ip_address=192.168.2.40 is an option, which specifies the port's fixed IP address we wanted. Create a port without specified IP address: $ neutron port-create net1 Created a new port: We can see that the system will allocate one IP address if we don't specify the IP address in command line. Query ports with specified fixed IP addresses: $ neutron port-list --fixed-ips ip_address=192.168.2.2 ip_address=192.168.2.40 --fixed-ips ip_address=192.168.2.2 ip_address=192.168.2.40 is one unknown option. How to find unknown options?The unknown options can be easily found by watching the output of create_xxx or show_xxx command. For example, in the port creation command, we see the fixed_ips fields, which can be used as an unknown option. Create and manage stacks To create a stack from an example template file To create a stack, or template, from anexample template file, run following command: $ heat stack-create mystack --template-file=/path/to/heat/templates/WordPress_Single_Instance.template--parameters="InstanceType=m1.large;DBUsername=wp;DBPassword=verybadpassword;KeyName=heat_key;LinuxDistribution=F17" The --parameters values that you specify depend on which parameters are defined in the template. If the template file is hosted on a website, you can specify the URL with --template-url parameter instead of the --template-file parameter. The command returns the following output: You can also use the stack-createcommand to validate a template file without creating a stack from it. To do so, run the following command: $ heat stack-create mystack --template-file=/path/to/heat/templates/WordPress_Single_Instance.template If validation fails, the response returns an error message. To list stacks To see which stacks are visible to the current user, run the following command: $ heat stack-list To view stack details To explore the state and history of a particular stack, you can run a number of commands. To show the details of a stack, run the following command: $ heat stack-show mystack A stack consists of a collection of resources. To list the resources, including their status, in a stack, run the following command: $ heat resource-list mystack To show the details for the specified resource in a stack, run the following command: $ heat resource-show mystack WikiDatabase Some resources have associated metadata which can change throughout the life-cycle of a resource: $ heat resource-metadata mystack WikiDatabase A series of events is generated during the life-cycle of a stack. This command will display those events. $ heat event-list mystack To show the details for a particular event, run the following command: $ heat event-show WikiDatabase 1 To update a stack To update an existing stack from a modified template file, run a command like the following command: $ heat stack-update mystack --template-file=/path/to/heat/templates/WordPress_Single_Instance_v2.template --parameters="InstanceType=m1.large;DBUsername=wp;DBPassword=verybadpassword;KeyName=heat_key;LinuxDistribution=F17" Some resources are updated in-place, while others are replaced with new resources.