Introduction

In Using the OpenStack CLI you were introduced to the general form for issuing CLI commands. Here we will explore how some of the most common commands can be used to perform typical tasks like creating and managing instances. Along the way we'll discuss some details about using CLI commands on Jetstream2 that will help you be successful with the CLI.

With the OpenStack CLI you can refer to entities by their names as well as by their Universally Unique Identifiers (UUIDS). This can simplify the process of issuing commands that reference entities created by previous commands. If the name you are specifying includes spaces, you will need to surround it with quotes.

Note that OpenStack does not prevent you from assigning the same name to multiple entities of the same type. You will either need to be careful to use unique names or be prepared to use UUIDs to differentiate between entities that share names. In particular, if you are sharing a project with other users it is a good practice to include an identifier like your username in the entity names you assign. In the examples below, we will include the sample identifier "johndoe" in entity names and assume that these names have not already been assigned to entities.

Create a Security Group

You will need to have several entities in hand before you create an instance, and this can be done either through the Horizon web interface or through the OpenStack CLI. For this example we will assume that you already have a private network named "auto_allocated_network" and will use the CLI to create a security group for SSH access and to upload an existing key pair.

The command to create a security group requires one argument, the name of the new group. To see the additional options for this (or any other) command, use a CLI command like openstack help security group create. Commands to create security group rules do not include names for the rules, but instead specify the name of the group to which the rule will be added. You will need to specify a number of options to fully define a rule, including the protocol, port range and IP address range. The sample command below opens the SSH port (TCP 22) to all IP addresses. Note that the second command string is split into multiple lines for clarity.

openstack security group create "johndoe-security"

openstack security group rule create "johndoe-security" \
--protocol tcp --dst-port 22:22 \
--remote-ip 0.0.0.0/0

Both of these commands will print information about the newly created entities when they finish, unless you include the --quiet option in the command. These commands do not return until the entity creation is complete. You can now use the Horizon web interface to easily see the entities you have created.

Create a Key Pair

When creating an instance you will have to identify a key pair to be injected into the instance. You may use an existing key pair for this if you have already created one. If you wish to create a new key pair in OpenStack you have two choices. You can generate the key pair on your own computer using a command like ssh-keygen and then upload the public part of the key to OpenStack. Or, you can let OpenStack create a key pair and download the private part of the key to your computer.

In both cases, the CLI command to create a key is openstack keypair create <"key-name">. If you are uploading a public key, supply its file name with the --public-key option. If you are downloading a newly created private key, specify the file where it should be stored with the --private-key option. In this example, we are uploading our public key, which is in the file "is_rsa.pub".

openstack keypair create --public-key id_rsa.pub "johndoe-key"

Find an Image

The Jetstream2 staff maintains a number of images that are recommended for creating your instances, and these have names that begin with "Featured". To see a list of such images, use the command openstack image list | grep Featured.

$ openstack image list | grep Featured
| b3458bd3-d380-4672-a666-6aca01b96281 | Featured-AlmaLinux8                             | active |
| a82532f8-9184-43e7-8e57-9e6b07e60d9f | Featured-AlmaLinux9                             | active |
| 229cab54-765a-48c9-8c41-42cab520ded9 | Featured-CentOS7                                | active |
| 88206b19-74d0-412a-a451-3e68f3d5f43c | Featured-RockyLinux8                            | active |
| f578ae62-a989-452a-9ac2-9ff15cdfc162 | Featured-RockyLinux9                            | active |
| 80a28329-e077-4b47-aec0-dc8adda5603d | Featured-Ubuntu20                               | active |
| 80329a3a-2cb9-4fe6-8238-9059251e9621 | Featured-Ubuntu22                               | active |

Take note of the UUID (first column) or name (second column) of the image you want to use.

Create an Instance

Before creating an instance, use the command openstack flavor list to identify the flavor (size) you would like to use for the instance. Flavors can be specified by names "like m3.small" or IDs like "2".

When creating a new instance you will need to supply its name and options that specify its network, security groups, key pair, flavor and source image. You may also want to include the option --wait to make the command return only when the instance creation is complete (this is very helpful when creating instances in a script).

Assuming we have a network named "auto_allocated_network" and want to use the "m3.small" flavor, we will create an instance named "johndoe-instance" from a recent Ubuntu image using the other entities we created above. Note that the command family for instances is named "server" and the option to specify a network ( NIC ) requires its own "net-id" argument. Also, you can add multiple security groups to the instance.

openstack server create "johndoe-instance" \
--nic net-id="auto_allocated_network" \
--security-group "default" \
--security-group "johndoe-security" \
--key-name "johndoe-key" \
--flavor m3.small \
--image "Featured-Ubuntu20" \
--wait

If you have specified everything correctly, the command will take a minute or two to return, after which the instance should be active. You can now view the instance's console output with the command:

openstack console log show "johndoe-instance"

Assign a Floating IP Address

In order to access your instance from the internet, it will need to be assigned a floating IP address. If there are no available floating IP addresses in your project, you can create one with:

openstack floating ip create public

Here, "public" is the name of the external network to which the address belongs. Since floating IP addresses do not have names in OpenStack, you will need to copy the address number from the command's output. Then you can assign that address to your instance with a command like:

openstack server add floating ip "johndoe-instance" 149.165.123.123

With the floating IP address assigned, you should be able to SSH into your instance.

Manage an Instance

Once you have an instance, you can use the CLI to do anything to it that you are able to do through the Horizon web interface (and more). Some of the most common operations can be performed as follows:

Shelve an instance

openstack server shelve "johndoe-instance"

Unshelve an instance

openstack server unshelve "johndoe-instance"

Attach a volume to an instance

openstack server add volume "johndoe-instance" "johndoe-volume"
(The volume must have previously been created. This can be done with an openstack volume create command.)

Detach a volume from an instance

openstack server remove volume "johndoe-instance" "johndoe-volume"