Of course! Here's a comprehensive guide to using the python-novaclient, the official command-line client for OpenStack Compute (Nova).

This guide covers:

1. What is python-novaclient?
2. Installation
3. Configuration (The Crucial First Step)
4. Commonly Used Commands (with examples)
5. Scripting with the API
6. Troubleshooting & Best Practices

What is python-novaclient?

python-novaclient is a command-line tool (CLI) and a Python library that allows you to interact with the OpenStack Compute service, known as Nova.

Nova is responsible for managing the lifecycle of virtual machines (VMs), often called "instances" in OpenStack. With this tool, you can:

• Create, start, stop, pause, suspend, and delete instances.
• Manage flavors (the size of the instance, e.g., CPU, RAM, disk).
• Manage key pairs for secure SSH access.
• Manage security groups (firewalls for your instances).
• View the status of your instances and the overall cloud.

Installation

You need to have Python and pip installed. Then, you can install the client via pip.

# Install the latest version
pip install python-novaclient
# If you need a specific version
pip install python-novaclient==<version_number>

Configuration (The Crucial First Step)

Before you can run any commands, python-novaclient needs to know how to authenticate with your OpenStack cloud. This is done using a configuration file, typically located at ~/.config/openstack/clouds.yaml.

This file stores your credentials and the endpoint URLs for your OpenStack services.

Example ~/.config/openstack/clouds.yaml

clouds:
  my-openstack-cloud: # A name you choose for this cloud profile
    auth:
      auth_url: https://my-openstack-api.com:5000/v3
      project_name: my-project
      username: my-username
      password: my-super-secret-password
      user_domain_name: Default
      project_domain_name: Default
    region_name: RegionOne
    identity_api_version: 3

Explanation of Key Fields:

• my-openstack-cloud: A unique name you give to this cloud configuration. You'll use this name with the --os-cloud flag.
• auth_url: The URL of your OpenStack Identity service (Keystone).
• project_name: The name of the project (or tenant) you want to work in.
• username / password: Your OpenStack username and password.
• user_domain_name / project_domain_name: Usually Default in most simple setups.
• region_name: The specific region of your OpenStack deployment.
• identity_api_version: Typically 3 for modern OpenStack installations.

Commonly Used Commands

You'll run commands using the nova command. The general syntax is:

nova [--os-cloud <cloud_name>] <command> <options>

If you set the OS_CLOUD environment variable, you don't need to specify --os-cloud every time.

export OS_CLOUD=my-openstack-cloud
nova list

Here are the most common commands:

A. Checking Information

List all running instances:

nova list
# or
nova server list

List available flavors (instance sizes):

nova flavor-list

List available images (operating systems):

nova image-list

List available networks:

nova network-list

List available security groups:

nova secgroup-list

List available key pairs:

nova keypair-list

B. Managing Instances (Servers)

Create a new instance: This is the most complex command. You need to specify an image, a flavor, and a name.

nova boot \
  --flavor m1.small \          # The size/instance type
  --image ubuntu-20.04 \       # The OS image to use
  --security-group default \   # The firewall rules to apply
  --keypair my-keypair \       # Your SSH key for access
  my-new-instance              # The name for your instance

Show details of a specific instance: You need the ID of the instance from nova list.

nova show <instance_id_or_name>

Start a stopped instance:

nova start <instance_id_or_name>

Stop a running instance:

nova stop <instance_id_or_name>

Pause a running instance (CPU and memory are kept in RAM):

nova pause <instance_id_or_name>

Suspend a paused instance (state is saved to disk, RAM is freed):

nova suspend <instance_id_or_name>

Resume a suspended instance:

nova resume <instance_id_or_name>

Delete an instance: This is a permanent action. Be careful!

nova delete <instance_id_or_name>

C. Managing Key Pairs

Import a public key from a file: This allows you to SSH into your instances. The file must contain only the public key (e.g., ~/.ssh/id_rsa.pub).

nova keypair-add --pub-key ~/.ssh/id_rsa.pub my-keypair-name

Delete a key pair:

nova keypair-delete my-keypair-name

D. Managing Security Groups

Create a new security group:

nova secgroup-create my-new-group "Description of my new group"

Add a rule to a security group (e.g., allow SSH):

# Allow SSH (port 22) from any IP address
nova secgroup-add-rule default tcp 22 22 0.0.0.0/0
# Allow HTTP (port 80) from any IP address
nova secgroup-add-rule default tcp 80 80 0.0.0.0/0

Delete a rule from a security group: You need the rule ID from nova secgroup-list-rules <group_name>.

nova secgroup-delete-rule <rule_id>

Scripting with the API

While the CLI is great for humans, you often need to automate tasks. The python-novaclient library provides a Python API for this.

First, install the library if you haven't (it's the same package): pip install python-novaclient

Then, you can write a Python script to interact with Nova.

Example Python Script (list_instances.py):

import novaclient.client
# Authenticate and get a client object
# This will automatically look for the clouds.yaml file
# or environment variables like OS_*
nova = novaclient.client.Client(2, os.environ.get('OS_USERNAME'),
                                os.environ.get('OS_PASSWORD'),
                                os.environ.get('OS_PROJECT_ID'),
                                os.environ.get('OS_AUTH_URL'),
                                region_name=os.environ.get('OS_REGION_NAME'))
# List all servers
servers = nova.servers.list()
print("--- My Instances ---")
for server in servers:
    print(f"Name: {server.name}, ID: {server.id}, Status: {server.status}")

To run this script, you need to set the environment variables from your clouds.yaml file:

export OS_USERNAME=my-username
export OS_PASSWORD=my-super-secret-password
export OS_PROJECT_ID=$(openstack project show my-project -f value -c id)
export OS_AUTH_URL=https://my-openstack-api.com:5000/v3
export OS_REGION_NAME=RegionOne
python list_instances.py

Troubleshooting & Best Practices

"Command not found: nova"

• Solution: Make sure you installed python-novaclient and that your Python environment's bin directory is in your system's PATH.

"Authentication failed" or "KeystoneException"

• Solution: This is the most common error.
  • Double-check your clouds.yaml file for typos.
  • Ensure your username, password, and project name are correct.
  • Verify the auth_url is correct and accessible.
  • Check that your user has the necessary permissions (roles) in the specified project.

"No valid region"

• Solution: The region_name in your clouds.yaml doesn't match any available region in your OpenStack deployment. Check the correct region name with your cloud administrator or via the OpenStack dashboard.

Best Practice: Use OpenStack Client (openstack) For many modern OpenStack installations, a more unified client called openstack is available. It can perform the actions of nova, neutron (networking), glance (images), etc., from a single command-line tool. It's often recommended to use openstack if it's available in your environment.

Example with openstack client:

# List servers (same as nova list)
openstack server list
# Boot a server (similar to nova boot)
openstack server create --flavor m1.small --image ubuntu-20.04 --security-group default --key-name my-keypair my-new-instance

The openstack client uses the same clouds.yaml configuration file, making it a drop-in replacement in many cases.