Chapter 2. Using OpenStack Command Line Interfaces

Contents

2.1. OpenStack Commands—Overview
2.2. OpenStack RC File
2.3. Managing Images
2.4. Launching Instances
2.5. Configuring Access to the Instances

The OpenStack project provides a variety of command line tools with which you can manage the services within your cloud and automate tasks by using scripts. Each of the core OpenStack components has its own command line tool.

2.1. OpenStack Commands—Overview

The following command line tools are available for the respective services' APIs:

keystone

For managing users and projects. Provided by the python-keystoneclient package.

nova

For managing instances and flavors. Provided by the python-novaclient package.

glance

For managing images. Provided by the python-glanceclient package.

swift

For managing the object store. Provided by the python-swiftclient package.

All of them have tab completion.

Help and detailed information about the individual commands and their arguments are available with

COMMAND help

For help on subcommands, use

COMMAND help SUBCOMMAND 

For example: glance help or glance help image-create

2.2. OpenStack RC File

To set the necessary environment variables for the OpenStack command line tools, you need to download and source an environment file, openrc.sh. It is project-specific and contains the credentials used by OpenStack Compute, Image, and Identity services. You can download it from the SUSE Cloud Dashboard (either as user admin or as any other user).

Procedure 2.1. Downloading the OpenStack RC File

  1. Log in to the SUSE Cloud Dashboard.

  2. In the top-level row of the main screen, click Settings+OpenStack Credentials.

  3. Select the project for which you want to download the OpenStack RC file, click Download RC File and save the file.

  4. Copy the openrc.sh file to the machine on which you want to execute OpenStack commands (for example, uploading an image with the glance command).

  5. On any shell that you want to execute OpenStack commands from, source the openrc.sh file for the respective project:

    source openrc.sh

    You will be prompted for an OpenStack password.

  6. Enter the OpenStack password of the user who downloaded the openrc.sh file.

    With sourcing the file and entering the password, environment variables are set for that shell. They allow the commands to communicate to the OpenStack services running in the cloud.

2.3. Managing Images

User permissions to manage images are defined by the cloud operator during setup of SUSE Cloud. Image upload and management may be restricted to cloud administrators or cloud operators only.

After uploading an image to Nova, it cannot be changed any more (golden image).

Whereas nearly all key tasks can either be executed from the SUSE Cloud Web interface or from the command line, images can only be uploaded with a command line tool, glance image-create. For details, refer to Section “Adding Images” (Chapter 2, Using OpenStack Command Line Interfaces, ↑User Guide for Administrators).

2.4. Launching Instances

Instances are virtual machines that run inside the cloud. To start an instance, a virtual machine image must exist that contains the following information: which operating system to use, a username and password with which to log in to the instance, file storage etc. The cloud contains a pool of such images that have been uploaded to Glance and are accessible to members of different projects.

Upon start of an instance, you need to specify the following key parameters:

Flavor

In OpenStack, flavors define the compute, memory, and storage capacity of nova computing instances. To put it simply, 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, refer to Section “Managing Flavors” (Chapter 2, Using OpenStack Command Line Interfaces, ↑User Guide for Administrators).

Keypair

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.

Create at least one keypair per project. If you already have generated a keypair with an external tool, you can import it into OpenStack. The keypair can be used for multiple instances belonging to that project.

For details, refer to Section 2.5.1, “Creating or Importing Keys”.

Security Group

In SUSE Cloud, security groups are used to define which incoming network traffic should be forwarded to instances. Security groups hold a set of firewall policies (security group rules).

For details, refer to Section 2.5.2, “Configuring Security Groups and Rules”.

If needed, you can assign a floating (public) IP address to a running instance and attach a block storage device (volume) for persistent storage. For details, refer to Section 2.5.3, “Managing IP Addresses”.

Before you can launch an instance, you need to look up a few parameters, for example, which images, flavors, and security groups are available. Proceed as follows:

Procedure 2.2. Launching an Instance

  1. On a shell, source the OpenStack RC file. For details, refer to Section 2.2, “OpenStack RC File”.

  2. Look up the available flavors:

    nova flavor-list

    Memorize the ID of the flavor that you want to use for your instance.

  3. Look up the available images:

    nova image-list

    Memorize the ID of the image that you want to boot your instance from.

  4. Look up the available security groups:

    nova secgroup-list

    If you have not created any specific security groups, you can only assign the instance to the default security group.

  5. Look up your keypair's name (for SSH access) and memorize it:

    nova keypair-list
  6. Now you have all the parameters at hand for starting an instance. Do so with the following command:

    nova boot --flavor FLAVOR_ID --imageIMAGE_ID --key_name KEY_NAME \
    --security_group NAME_OF_SEC_GROUP NAME_FOR_INSTANCE 

    The command returns a list of instance properties, including the status of the instance. The status BUILD indicates that the instance has started, but is not yet online.

  7. 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 your instance's status is ACTIVE, the instance is online.

    To refine the search, run nova help list to view the available options for the command.

If you did not provide a keypair on starting and have not touched security groups or rules so far, by default the instance can only be accessed from inside the cloud via VNC at this point. Even pinging the instance is not possible. To change this, proceed with Section 2.5, “Configuring Access to the Instances”.

2.5. Configuring Access to the Instances

Access to an instance is mainly influenced by the following parameters:

  • keypairs

  • security groups and rules

  • IP addresses

For SSH access to an instance, you usually need to provide a keypair at launch time. The security rules need adjustment, too, since the default rules block access to SSH ports and prevent pinging an instance. To make the instance also accessible from outside the cloud, assign a floating (public) IP address.

2.5.1. Creating or Importing Keys

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.

Create at least one keypair per project. If you already have generated a keypair with an external tool, you can import it into OpenStack. The keypair can be used for multiple instances belonging to that project.

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 on starting of the instance.

Procedure 2.3. Creating or Importing Keys

Use the nova keypair-add command to generate a new keypair, or to upload an existing public key.

  1. To generate a new keypair, execute the following commands:

    nova keypair-add KEY_NAME > MY_KEY.pem
    chmod 600  MY_KEY.pem

    The first command generates a new keypair named KEY_NAME, writing the private key to the file MY_KEY.pem and registering the public key at the Nova database. The second command changes the permissions of the file MY_KEY.pem so that only you can read and write to it.

  2. If you already have generated a keypair, with the public key located at ~/.ssh/id_rsa.pub, you can upload the public key with the following command:

    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.

  3. Check if the uploaded keypair appears in the list of availabe keypairs:

    nova keypair-list

2.5.2. Configuring Security Groups and Rules

In SUSE Cloud, security groups are used to define which incoming network traffic should be forwarded to instances. Security groups hold a set of firewall policies (security group rules).

2.5.2.1. Security Groups

When launching an instance, you need to define which security groups it should belong to. A default security group is available for each project. It allows all network traffic from other members of this group and discards traffic from other IP addresses and groups.

Multiple security groups for a project can be defined, with each group holding a different set of firewall policies. This is useful if you have groups of instances that should differ in firewall configuration (for example, front-end and back-end servers). An instance can be assigned to multiple security groups.

Security groups can be managed with the nova secgroup-* commands, provided by the python-novaclient package.

Listing Security Groups
nova secgroup-list

Lists all security groups for the current project, including the groups' descriptions.

Creating a Security Group
nova secgroup-create SEC_GROUP_NAME GROUP_DESCRIPTION 

Creates a new security group with the specified name and description.

Deleting a Security Group
nova secgroup-delete SEC_GROUP_NAME 

Deletes the specified group.

[Note]Deleting Security Groups

The default security group for a project cannot be deleted.

If another group cannot be deleted, it is because it is still assigned to a running instance.

2.5.2.2. Security Group Rules

You can adjust rules of the default security group as well as rules of any other security group that has been created. As soon as the rules for a group are modified, the new rules are automatically applied to all running instances belonging to that security group.

Adjust the rules in a security group to allow access to instances via different ports and protocols. This is necessary to be able to access instances via SSH, to ping them, or to allow UDP traffic (for example, for a DNS server running on an instance).

Rules in security groups are specified by the following parameters:

Source of traffic

Decide whether to allow traffic to instances only from IP addresses inside the cloud (from other group members) or from all IP addresses.

Protocol

Choose between TCP (for SSH), ICMP (for pings), and UDP.

Destination Port on Virtual Machine

Define a port range. To open a single port only, enter the same value twice. ICMP does not support ports. In that case, enter values that define the codes and types of ICMP traffic to be allowed.

If no further security groups have been created, any instances are automatically assigned to the default security group (if not specified otherwise). Unless you change the rules for the default group, those instances cannot be accessed from any IP addresses outside the cloud.

Procedure 2.4. Configuring Security Group Rules

Modify security group rules with the nova secgroup-*-rule commands. Proceed as follows:

  1. On a shell, source the OpenStack RC file. For details, refer to Section 2.2, “OpenStack RC File”.

  2. Look up the existing rules for a security group:

    nova secgroup-list-rules SEC_GROUP_NAME 
  3. To allow SSH access to the instances:

    1. 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
    2. 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 
  4. To allow pinging the instances:

    1. 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 icmp -1 -1 0.0.0.0/0

      This command allows access to all codes and all types of ICMP traffic, respectively.

    2. Alternatively, you can 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 
  5. To allow access via UDP port (for example, for a DNS server running on a VM):

    1. 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 udp 53 53 0.0.0.0/0
    2. 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 udp --from_port 53 \
      --to_port 53 SEC_GROUP_NAME SOURCE_GROUP_NAME 
  6. To delete security group rules, you need to specify the same arguments that you used to create the rule. For example:

    To delete the security rule that you created in Step 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 in Step 3.b:

    nova secgroup-delete-group-rule --ip_proto tcp --from_port 22 \
    --to_port 22 SEC_GROUP_NAME SOURCE_GROUP_NAME 

2.5.3. Managing IP Addresses

Each instance can have two IP addresses: a private (fixed) IP address and a public (floating) one. Private IP addresses are used for communication between instances, and public ones are used for communication with the outside world. When an instance is launched, it is automatically assigned a private IP address, which stays the same until the instance is explicitly terminated. (Rebooting the instance does not have an effect on the private IP address.)

A pool of floating IPs is available in OpenStack Nova, as configured by the cloud operator. 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. From this set, you can then add a floating IP address 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 need to 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.

Listing Pools with Floating IP Addresses
nova floating-ip-pool-list

Lists the name of all pools that provide floating IP addresses.

Allocating a Floating IP Address to the Current Project
nova floating-ip-pool-list

The output of the command shows the freshly allocated IP address. If there is more than one pool of IP addresses available, you can also specify the pool from which to allocate the IP address (optional):

floating-ip-create POOL_NAME 
Listing Floating IP Addresses Allocated to the Current Project
nova floating-ip-list

Lists all floating IP addresses that have been allocated to the current project. If an IP is already associated with an instance, the output also shows the instance's IP, the instance's fixed IP address and the name of the pool that provides the floating IP address.

Releasing a Floating IP Address from the Current Project
nova floating-ip-delete FLOATING_IP 

The IP address is put back into the pool of IP addresses that are available for all projects. If an IP address is currently assigned to a running instance, it will automatically be disassociated from the instance.

Assigning a Floating IP Address to an Instance
nova add-floating-ip INSTANCE_NAME_OR_ID FLOATING_IP 

To associate an IP address with an instance, one or multiple floating IP addresses must have been allocated to the current project. Check this with nova floating-ip-list. In addition, you need to know the instance's name (or ID). To look up the instances that belong to the current project, use the nova list command.

After assigning the IP with nova add-floating-ip, the instance is now publicly available under the respective floating IP address (provided you have also configured the security group rules for the instance accordingly). For details, refer to Section 1.5.2, “Configuring Security Groups and Rules”.

Removing a Floating IP Address from an Instance
nova remove-floating-ip INSTANCE_NAME_OR_ID FLOATING_IP 

To remove a floating IP address from an instance, you need to specify the same arguments that you used to assign the IP.


SUSE Cloud End User Guide 1.0