The purpose of this guide is to explain how to create an instance using the command line through OpenStackClient.

An example will be demonstrated where an instance is created on a private network. The intent of the instance will be to act as a “jumpstation” where OpenStackClient will be installed. Finally, this jumpstation can be used to administer the OpenStack cloud using OpenStackClient.

An instance is another name for a virtual machine in OpenStack. Instances are created by the Nova service and contribute to the processing power of the cloud.

You’ll also learn how to upload or create an SSH key pair, assign storage using a volume, and create a security group. Each of these components will be added to the instance.

NOTE! — You will need to have OpenStackClient installed already to follow this guide.


OpenStackClient is how you would manage an OpenStack cloud using the command line.

For general information on OpenStackClient and how to install it, see the Day 1 guide.

Throughout these guides OpenStackClient will be also be known as OSC.

To get a full list of the available commands, run:

openstack --help

NOTE! — In addition to OpenStackClient, there are other command line clients for various OpenStack services that can be used. For example, Nova and Cinder each have their own command line client, as well as other services.

In later releases of OpenStack use of service-specific command line interfaces will be deprecated. When using the command line to administer OpenStack it is recommended to use OpenStackClient where possible as opposed to individual service’s command line interfaces such as nova‘s CLI.


Prerequisites for Creating an Instance

Before making an instance, ensure these items exist:

  • A flavor
  • An image
  • A network
  • A security group
  • An SSH public key

At minimum, a flavor, an image, and a network should exist. You may also want to attach a volume, specify security groups to use, and attach an SSH public key.


SSH key pairs

An SSH key pair will be required to access any instances over SSH. Password authentication is by default disabled in the operating system images.

You can either have an SSH key created or you can upload the public key of your SSH key pair.

Create an SSH key pair

SSH keys can be managed, created, and uploaded through the command line using OpenStackClient.

To make a key pair, use:

$ openstack keypair create KEY_NAME

KEY_NAME is the name of the SSH key pair.

This will generate a key pair for you and return the private key. The private key should be kept somewhere safe and be inaccessible to others.

To upload your public key, use:

$ openstack keypair create --public-key PATH_TO_PUBLIC_KEY KEY_NAME

KEY_NAME is the name of the SSH key pair and PATH_TO_PUBLIC_KEY is the path on the filesystem to the public key.

Here’s an example of uploading an SSH public key:

$ openstack keypair create --public-key ~/.ssh/ ssh_key_2
| Field       | Value                                           |
| fingerprint | ff:a4:81:c7:59:07:aa:54:43:39:52:cd:b2:12:aa:fb |
| name        | ssh_key_2                                       |
| user_id     | 43317575cccc440fbcb38a1f23b45125                |


Security groups

A security group in OpenStack controls network access. If no security group is assigned, a default one will be used. The default security group disables all inbound traffic and only allows outbound traffic, which may not be useful.

A security group should be made that allows the type of incoming and outgoing traffic required. OpenStack’s default security group does not allow incoming traffic so if you wanted to SSH into an instance, port 22 will be closed. An example of a security group would be one that allows web traffic by opening ports 80 and 443 and you may want another security group that opens port 22 for SSH traffic.

Create and manage security groups

This section will demonstrate creating a security group that allows SSH traffic from a specific host.


> The command to create a security group appears like so, where SECURITY_GROUP is the name of the security group:

$ openstack security group create SECURITY_GROUP

> To list security groups, run:

$ openstack security group list
| ID                                   | Name                  | Description                                                | Project                          | Tags |
| 8639e3c5-47ce-4072-a1f5-1c1e931a8f75 | default               | Default security group                                     | 3c5591e744fa4fdcb38409781596182d | []   |
| ebffcf78-52d9-436c-81db-5ea788a0c33d | devstack              |                                                            | 5ad1f9e795604f4390d274d7388c4b9f | []   |
| ec8a02ba-4bc2-4b78-a555-902caead87fe | basic_webserver_group | This will open standard ports for web services             | 5ad1f9e795604f4390d274d7388c4b9f | []   |

> To list the details of a specify security group, where UUID is the security group’s UUID, run:

$ openstack security group show UUID



The following example demonstrates opening port 22 for incoming traffic coming from

There are two steps to the example: The first step shows creating a security group called ssh_demo and the next step shows adding the SSH rule to that group.

Open port 22 for incoming SSH traffic:

# Create the security group
$ openstack security group create ssh_demo

# Add rule for port 22
$ openstack security group rule create --remote-ip 
--dst-port 22:22 --ingress --protocol tcp ssh_demo


The next section is not required, but shows how to make a security group allowing incoming traffic to the common HTTP ports, 80 and 443.

Example security group for HTTP incoming traffic:

$ openstack security group rule create --remote-ip 
--dst-port 80:80 --ingress --protocol tcp SECURITY_GROUP

$ openstack security group rule create --remote-ip 
--dst-port 443:443 --ingress --protocol tcp SECURITY_GROUP


Assign Storage

Storage can be assigned through volumes. A volume in OpenStack is like a removable USB drive that can be attached to instances as seen fit. Cinder is the OpenStack service that allows volumes to be created. A volume can also be used to boot an instance.

Create and attach a volume

Use the following command to create a volume with size 15GB:

$ openstack volume create volume_1 --size 15

List the newly created volume:

$ openstack volume list
| ID                                   | Name         | Status    | Size | Attached to                                          |
| 1fe4f750-62fc-4c53-b661-44481d0f72b3 | volume_1     | available |   15 |                                                      |

Attach the volume to an instance:

$ openstack server add volume $INSTANCE_UUID $VOLUME_UUID


Create an instance

If at this step and you have followed the previous steps, you should have everything needed to create the instance. Again, this example will demonstrate how to create an instance on a private network.

NOTE! — If your infrastructure does not need to be on a public network, then ensure the appropriate parts are created on a private network, and be sure the security groups are set to only allow the needed traffic through. This information goes a long way in improving overall security when using OpenStack.

Before creating an instance

Before creating an instance, you will need to collect some information.

Needed details:

  • The flavor, image, and network UUIDs
  • SSH key
  • Security group

You can list the above using OpenStackClient. The next section will provide examples using each command and their outputs.

NOTE! — When listing items using OpenStackClient, almost everything will have a UUID. However, if a UUID does not exist, you’ll need to use the name specified in the ID column or the name of the item itself.

Here are commands that can be used to collect the needed information:

Summary of commands:

$ openstack flavor list
$ openstack image list
$ openstack network list
$ openstack security group list
$ openstack keypair list


Detailed commands:

List flavors:

$ openstack flavor list
| ID           | Name         |   RAM | Disk | Ephemeral | VCPUs | Is Public |
| hc1.large    | hc1.large    |  8192 |   80 |         0 |     8 | True      |
| hc1.medium   | hc1.medium   |  4096 |   40 |         0 |     4 | True      |
| hc1.micro    | hc1.micro    |  1024 |   10 |         0 |     1 | True      |
| hc1.small    | hc1.small    |  2048 |   20 |         0 |     2 | True      |
| hc1.xlarge   | hc1.xlarge   | 16768 |  160 |         0 |    16 | True      |
| hram1.medium | hram1.medium | 16768 |   40 |         0 |     4 | True      |

Flavors are a way to set things like the amount of RAM, disk space, and CPU cores to be assigned to an instance. The Is Public heading says that this flavor is shared among all OpenStack projects.

List images:

$ openstack image list
| ID                                   | Name                        | Status |
| 22c437b3-18cd-4af0-bd3d-ad26c85bb00f | CentOS 7 (ce7-x86_64)       | active |
| cd18f302-d3bf-49a1-8f5d-a6805404b9ff | CentOS 8 (ce8-x86_64)       | active |
| 507ca3c5-ed57-4997-b21d-bc0f32406322 | Debian 10 (buster-amd64)    | active |
| c19c4d9d-59c9-49e4-8e5f-988d3c1ae4d4 | Debian 9 (stretch-amd65)    | active |
| 46b14073-bd4e-4aa2-b901-63c86ab15961 | Ubuntu 18.04 (bionic-amd64) | active |
| 40b09133-a1a0-4ea1-a8aa-958541314ac5 | Ubuntu 20.04 (focal-amd64)  | active |

Images are typically an operating system image and usually can be found publicly available. CentOS has a repository of cloud instances for example.

Images can also created using a snapshot of an instance.

List networks:

$ openstack network list
| ID                                   | Name                                               | Subnets                              |
| 0db14de2-9dd0-469f-a76c-46b99119d607 | External                                           | f6ee60a8-7371-4986-8d90-2810018289dd |
| bdb2dbfc-e3ef-4da0-a79b-fe48c4a413fb | Internal                                           | 06dfb691-8035-49b9-ac41-c53344531bd0 |
| fcd8166c-0fdb-4bc9-ab29-ce54a8bd5959 | HA network tenant b9e8639372014c0b85cbfaffa6e1b5a8 | 45514f89-d931-44fa-b82b-ae20f49b09a7 |

List security groups:

$ openstack security group list
| ID                                   | Name      | Description                | Project                          | Tags |
| 06785fc8-492c-477b-9928-9708cb550a14 | ssh_demo  | ssh_demo                   | b9e8639372014c0b85cbfaffa6e1b5a8 | []   |
| 9e20fbef-9eca-4029-8111-625945409ae2 | default   | Default security group     | 6a654535b8f04445bbc4974b2e4802cd | []   |
| cc25e2d6-6a5c-469f-ba89-c2e04e6f6850 | SSH       | General SSH security group | b9e8639372014c0b85cbfaffa6e1b5a8 | []   |

List SSH key pairs:

$ openstack keypair list
| Name         | Fingerprint                                     |
| st_timespace | a7:ab:bd:9c:78:85:e1:a1:c4:07:0f:6d:e9:36:0b:68 |

Procedure to create an instance

Base command needed to make an instance:

$ openstack server create

From this command you will specify additional flags such as the SSH key, the network UUID, the instance name, and the like.

For the full list of options to make an instance, run:

$ openstack help server create

The command to create an instance will look something like this:

$ openstack server create --image IMAGE_UUID 
--flavor hc1.medium --network NETWORK_UUID 
--key-name SSH_KEY_NAME --security-group SECURITY_GROUP_UUID 

Note that IMAGE_UUID is the UUID of the image you want to use, NETWORK_UUID is the UUID of the network to be associated with the instance, SSH_KEY_NAME is the name of the SSH key, SECURITY_GROUP_UUID is the UUID of the security group to use, and INSTANCE_NAME is the name to call the instance.

NOTE — By default, the instance creation will occur in the background. You can add --wait to the flags to have the command wait until the instance creation is done which will show you the status of instance creation.


Example instance creation:

Here are the collected details to make an instance from the previous section:

  • Flavor: hc1.small
  • Image UUID: 40b09133-a1a0-4ea1-a8aa-958541314ac5
  • Network UUID: bdb2dbfc-e3ef-4da0-a79b-fe48c4a413fb
  • SSH key: st_timespace
  • Security group UUID: cc25e2d6-6a5c-469f-ba89-c2e04e6f6850

Full command:

$ openstack server create --image 40b09133-a1a0-4ea1-a8aa-958541314ac5 
--flavor hc1.small --network bdb2dbfc-e3ef-4da0-a79b-fe48c4a413fb 
--key-name st_timespace --security-group 
cc25e2d6-6a5c-469f-ba89-c2e04e6f6850 openstackclient_js_demo

After creating the instance, verify the build process by running $ openstack server show INSTANCE_NAME.

The status column will indicate the status. See the Nova compute API documentation for a list of instance status meanings and additional commands that can be used to troubleshoot any issues.

You also may find the table output is too large for your display. Add --fit-width to the command to force the table to fit to your display’s width making reading easier.


NOTE! — This section is incomplete but will receive updates in the future.

There may be an issue with spawning the instance. Using the above command will display any errors with the build process under the fault field.


Troubleshooting Instance Error Status

Sometimes, instance creation will not succeed which can be for a variety of reasons. Running openstack server list will show the Status of an instance.

Here’s an example of an instance with Status, “ERROR”:

$ openstack server list
| ID                                   | Name                        | Status  | Networks                | Image                      | Flavor     |
| 35d624fe-785d-4915-aa7e-4bb580b29325 | centos_instance_2           | ERROR   |                         | CentOS 8 (ce8-x86_64)      | hc1.micro  |

Get more information on the error status by running:

$ openstack server show $INSTANCE_UUID --fit-width

Look for the fault row for the reason as to why the instance failed to create.

It is suggested to look over for common issues that may arise and how to troubleshoot them.

Location of OpenStack service logs

You may need to look at service’s logs to get a better idea of an issue. The default log location for an OpenStack deployment is /var/log/$service_name, however OpenStack in this case has been deployed using kolla-ansible and logs are stored in /var/log/kolla/$service_name on each hardware node.

The next guide in this series will explain how to connect an instance to the provider network, allowing Internet access.


Next Steps

The next guide in this series will explain how to SSH into this instance.

If you wish to skip the SSH guide, see the managing images in OpenStack guide.