Chapter 2. Using OpenStack Command Line Interfaces

Contents

2.1. OpenStack Commands—Overview
2.2. OpenStack RC File
2.3. Managing Projects and Users
2.4. Managing Images
2.5. Managing Flavors
2.6. Setting Quotas

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 Projects and Users

SUSE Cloud allows you to manage projects independently from each other. Projects represent different organizational units in the cloud to which users can be assigned. Both project and user management are cloud administrator's tasks.

During the basic system setup, the cloud operator needs to minimally define one project, one user, and one role to link the project and user. Roles define which actions users are allowed to perform.

The python-keystoneclient provides the keystone command line tool which you can use to manage projects and users from any machine outside the cloud. Prior to using the tool, download and source an OpenStack RC file. For details, refer to Section 2.2, “OpenStack RC File”.

[Note]Administrator Credentials

Administering projects and users requires administrator credentials. Make sure to download and source the OpenStack RC file as administrator prior to running keystone commands. Alternatively, export the respective environment variables, using the token or password authentication method. For details, refer to http://docs.openstack.org/essex/openstack-compute/admin/content/adding-users-tenants-and-roles-with-python-keystoneclient.html

2.3.1. Viewing, Creating, Disabling, or Deleting Projects

Find examples for the key administration tasks below.

Listing All Projects
keystone tenant-list

Lists all projects with their ID, name, and the information if they are enabled or not.

Creating a Project
keystone tenant-create --name PROJECT_NAME 

Creates a new project with the specified name.

Temporarily Disabling a Project
keystone tenant-update PROJECT_ID --enabled false

For the details of the impact, refer to Consequences of Disabling a Project .

Deleting a Project
keystone tenant-delete PROJECT_ID 

Deletes the specified project.

2.3.2. Viewing, Creating, Disabling, or Deleting User Accounts

Find examples for the key administration tasks below.

Listing All Users
keystone user-list

Lists all user accounts with their ID, name, e-mail address, and the information if they are enabled or not.

Creating a User Account
keystone user-create --name USER_NAME --tenant_id PROJECT_ID \
  --pass PRELIM_PASSWD
      

Creates a new user with the specified name. While the only required argument is --name, at least specify the optional parameters --tenant_id and --pass. Otherwise the newly created user cannot log in to the SUSE Cloud Dashboard.

Temporarily Disabling a User Account
keystone user-update USER_ID --enabled false

If you disable a user account, the user can no longer log in, but his data is kept so that the account can be re-enabled at any time.

Deleting a User Account
keystone user-delete USER_ID 

Deletes the specified user account.

2.3.3. Managing Roles

Roles define the actions that the user is allowed to perform. Configure roles in OpenStack Identity (Keystone). Actions are defined per OpenStack service in the respective /etc/[SERVICE_CODENAME]/policy.json file, for example in /etc/nova/policy.json for the Compute (Nova) service.

Find examples for the key administration tasks below.

Listing All Roles
keystone role-list

Lists all roles with their ID and name.

Creating a Role
keystone role-create --name=ROLE_NAME 

Creates a role with the specified name.

Deleting a Role
keystone role-delete ROLE_ID 

Deletes the specified role.

2.3.4. Modifying User Assignments for a Project

Whereas each user is assigned to a primary project when his user account is created, users can be members of multiple projects. The keystone client does not allow to directly assign users to additional projects. Instead you need to define a role and grant that role to a user-project pair.

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

  2. Check if there is already a member role defined:

    keystone role-list
  3. If not, create it:

    keystone role-create --name=member
  4. To grant the role to a user-project pair (and to thus assign a user to this project), you need to know the IDs of the role, the user, and the project. You can look them up with keystone role-list, keystone user-list, and keystone tenant-list.

  5. To grant the user membership of a project:

    keystone user-role-add --role-id=ROLE_ID --tenant_id=TENANT_ID \
      --user_id=USER_ID 
  6. To assign the user to multiple projects, repeat the last step.

  7. To verify the assignments, use:

    keystone user-role-list --user_id=USER_ID --tenant_id=TENANT_ID 

2.4. Managing Images

In the SUSE Cloud context, images are virtual disk images that represent the contents and structure of a storage medium or device, such as a hard drive, in a single file. Images are used as a template from which a virtual machine can be started. For starting a virtual machine, SUSE Cloud always uses a copy of the image.

Images can only be uploaded to SUSE Cloud with the glance command line tool. Images are owned by projects and can be private (accessible to members of the particular project only) or public (accessible to members of all projects). Private images can also be explicitly shared with other projects, so that members of those projects can access the images, too. Any image uploaded to Glance will get an owner attribute. By default, ownership is set to the primary project of the user that uploads the image.

2.4.1. Building Images with SUSE Studio

To build the images to use within the cloud, use SUSE Studio or SUSE Studio Onsite. For detailed information on how to build appliance images, refer to the SUSE Studio Onsite Quick Start or the SUSE Studio Onsite User Guide, available at http://www.suse.com/documentation/suse_studio/.

[Note]Image Requirements

Make sure any images that you build for the cloud fulfill the following requirements:

  • The network is set to DHCP.

  • The image does not include YaST2 Firstboot.

  • The image does not include any end-user license agreement (EULA) dialogs.

  • The image contains the following package: cloud-init (part of the SUSE Cloud ISO). It contains tools used for communication with the instance metadata API, which is provided by Nova. The instance metadata API is specific to each virtual machine and is only accessible from inside the VM. The package is needed to pull keypairs into the virtual machine that will run the image.

  • The image has one of the following formats: SUSE Cloud/OpenStack/KVM or USB Stick/Hard Disk Image.

As announced in http://blog.susestudio.com/2012/10/kvm-build-format-suse-cloud-support.html, SUSE Studio now supports building native KVM images in qcow2 format. They can be directly uploaded to SUSE Cloud.

If you are building images with SUSE Studio Onsite, you need to use the format USB Stick/Hard Disk Image and convert the image to qcow2 before uploading it. Future versions of SUSE Studio Onsite will also support building native KVM images in qcow2 format.

2.4.2. Adding Images

If you have created an image for SUSE Cloud/OpenStack/KVM with SUSE Studio, you can upload it directly as described in Procedure 2.3, “Uploading Disk Images to SUSE Cloud”. If you used SUSE Studio Onsite and have created an image for USB Stick/Hard Disk Image, convert it first as described in Procedure 2.2, “Converting Disk Images to qcow2 Format”.

Procedure 2.2. Converting Disk Images to qcow2 Format

The qcow2 format helps to optimize disk space as it consumes disk space only when contents are written on it.

  1. Make sure the virt-utils package is installed on the machine used for conversion.

  2. Download the disk image from SUSE Studio.

  3. Convert the image:

    qemu-img convert -c -f raw -O qcow2 IMAGE_FILE FINAL_IMAGE_FILE

Procedure 2.3. Uploading Disk Images to SUSE Cloud

The following procedure shows how to upload a disk image using the glance variant that is contained in the package python-glanceclient.

  1. In a shell, source the OpenStack RC file for the project that you want to upload an image to. For details, refer to Section 2.2, “OpenStack RC File”.

  2. Upload the image with the following command:

    glance image-create --name="IMAGE_NAME" --is-public=True --container-format=bare \
      --disk-format=qcow2 < PATH_TO_FINAL_IMAGE_FILE 
    [Note]Image File Required

    The glance client does not support piping images from standard input. Therefore make sure that PATH_TO_FINAL_IMAGE_FILE really specifies an image file.

    If you need to pipe images, use the former glance client version /usr/bin/glance.essex, which is available from the openstack-glance package.

    Glance does not check any image properties during upload, therefore you need to specify the image's properties as command line options.

    Images have both contents and meta-data; the latter are also called properties. The following properties can be attached to an image in SUSE Cloud:

    Image Properties

    Name (--name, optional)

    Specifies a name with which the image will be listed in the SUSE Cloud Dashboard and in the command line interface.

    Kernel ID (optional)

    The image's kernel ID. This parameter is only needed if an external Kernel is associated with the image. The ID points to the Kernel glance image.

    Ramdisk ID (optional)

    The image's ramdisk ID. This parameter is only needed if an external ramdisk is associated with the image. The ID points to the ramdisk glance image.

    Architecture (optional)

    The image's architecture.

    Container Format (--container-format, optional)

    Indicates if the VM image's file format contains metadata about the actual virtual machine. Set it to bare as the container format string is not currently used in any OpenStack components anyway. For details, refer to http://docs.openstack.org/developer/glance/formats.html.

    Disk Format (--disk-format, required)

    Specifies the image's disk format. Example formats include raw, qcow2, and ami. For details, refer to http://docs.openstack.org/developer/glance/formats.html.

    Public (--is-public, optional)

    Boolean value, default: false. If set to true, the image is publicly available.

    VM Mode (optional)

    Specify the hypervisor ABI (application binary interface) with the vm_mode flag. It can take the values pv, hvm, or xen. Use vm_mode=xen for XEN PV image import, or vm_mode=hvm for XEN HVM image import. For KVM, the correct mode is selected automatically.

    If the image upload has been successful, a message appears, displaying the ID that has been assigned to the image.

[Note]Updating Images

After having uploaded an image to SUSE Cloud, the image contents cannot be modified (only the image's metadata). To update image contents, you need to delete the current image and upload a modified version of the image.

To modify the metadata of an image, use the glance image-update command.

2.4.3. Viewing Images and Image Properties

In the following, find some examples on how to view images or image properties that are available in Glance.

Listing Images
glance image-list

Lists ID, name, disk format, and container format for all publicly available images in Glance.

Showing Metadata for a Particular Image
glance image-show IMAGE_ID 

Shows metadata of the specified image.

2.4.4. Removing Disk Images from Glance

To delete an image, you need to know the image's ID. If necessary, look it up as described in Section 2.4.3, “Viewing Images and Image Properties”. Delete the image with the following command:

glance image-delete IMAGE_ID 

If you need to delete all images and all image metadata, use the glance clear command.

2.4.5. Viewing and Modifying Membership of Private Images

In the following, find some examples on how to view or modify membership of private images:

Listing Members a Private Image is Shared With
glance member-list --image-id IMAGE_ID 

Lists the IDs of the projects whose members have access to the private image.

Listing Private Images Shared With a Member
glance member-list --tenant-id PROJECT_ID 

Lists the IDs of private images that members of the specified project can access.

Granting Members Access to a Private Image
glance member-create [--can-share] IMAGE_ID PROJECT_ID 

Grants the specified member access to the specified private image.

By adding the --can-share option, you can allow the members to further share the image.

Revoking Member Access to a Private Image
glance member-delete IMAGE_ID PROJECT_ID 

Revokes the access of the specified member to the specified private image.

2.5. Managing Flavors

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.

A flavor consists of the following parameters:

Flavor Parameters

Flavor ID

Automatically proposed by SUSE Cloud.

Name

Name for the new flavor.

VCPUs

Number of virtual CPUs to use.

Memory MB

Amount of RAM to use (in megabytes).

Root Disk GB

Amount of disk space (in gigabytes) to use for the root (/) partition.

Ephemeral Disk GB

Amount of disk space (in gigabytes) to use for the ephemeral partition. If unspecified, the value is 0 by default.

Ephemeral disks offer machine local disk storage linked to the lifecycle of a VM instance. When a VM is terminated, all data on the ephemeral disk is lost. Ephemeral disks are not included in any snapshots.

Swap

Amount of swap space (in megabytes) to use. If unspecified, the value is 0 by default.

Default Flavors

  • m1.tiny (1 VCPU/0 GB Disk/512 MB RAM)

  • m1.smaller (1 VCPU/0 GB Disk/1024 MB RAM)

  • m1.small (1 VCPU/10 GB Disk/2048 MB RAM)

  • m1.medium (2 VCPU/10 GB Disk/3072 MB RAM)

  • m1.large (4 VCPU/10 GB Disk/8192 MB RAM)

  • m1.xlarge (8 VCPU/10 GB Disk/8192 MB RAM)

Flavors can be managed with the nova flavor-* commands, provided by the python-novaclient package.

Find examples for the key administration tasks below.

Listing Flavors
nova flavor-list

Lists all flavors with their ID and name, the amount of memory, the amount of disk space for the root partition and for the ephemeral partition, the swap, and the number of virtual CPUs.

Creating a Flavor
nova flavor-create FLAVOR_NAME FLAVOR_ID RAM_IN_MB ROOT_DISK_IN_GB \
  NUMBER_OF_VCPUS
     

When creating a flavor, you need to specify at least the parameters listed above. For optional parameters, refer to nova help flavor-create.

Deleting a Flavor
nova flavor-delete FLAVOR_ID 

Deletes the specified flavor.

2.6. Setting Quotas

To prevent system capacities from being exhausted without notification, cloud administrators can set up quotas. In OpenStack, quotas are currently defined per project.

Quotas contain the following parameters:

Quota Parameters

ID (Name)

ID for the quota settings. Automatically proposed by SUSE Cloud.

Metadata Items

Number of metadata items per instance.

Injected Files

Number of injected files.

Injected File Content Bytes

Number of bytes per injected file.

VCPUs

Number of virtual CPUs that can be allocated in total.

Instances

Total number of instances.

Volumes

Total number of volumes.

Gigabytes

Total size of all volumes, measured in gigabytes.

RAM (in MB)

Total RAM size of all instances, measured in megabytes.

Floating IPs

Total number of floating IP addresses.

Security Group Rules

Number of security rules per security group.

Security Groups

Number of security groups.

Quotas can be managed with the nova quota-* commands, provided by the python-novaclient package.

Find examples for the key administration tasks below.

Showing Default Quota Values
nova quota-defaults PROJECT_ID 

Lists the default quotas for a tenant. They are hard-coded in OpenStack Nova.

Showing Quota Values for a Project
nova quota-show PROJECT_ID 

Lists the currently set quota values for a project.

Setting Quota Values for a Project
nova quota-update --instances 2 PROJECT_ID 

Sets the quota value for the instances parameter to 2. For a list of further options, refer to nova help quota-update.


SUSE Cloud User Guide for Administrators 1.0