OpenStack command line interface¶

Basic requirements¶

OpenStack is written in python3 and need to have python3 installed. On Linux, it should be out-of-the-box, on Mac OS you can install it through Homebrew.

Official documentation¶

The official CLI documentation is hosted on OpenStack documentation website and OpenStack Client Tools webpage.

Installation¶

Mac OS X installation procedure¶

$ mkdir ~/.venv
$ python3 -m venv ~/.venv/openstack-cli
$ source ~/.venv/openstack-cli/bin/activate
$ pip install python-openstackclient
$

OpenStack configuration¶

OpenStack CLI configuration is store on ~/.config/openstack/clouds.yaml file, this file allow user to define multiple OpenStack clouds and / or project.

$ cat ~/.config/openstack/clouds.yaml
clouds:
  virtualdata:
    auth:
      auth_url: https://keystone.lal.in2p3.fr:5000/v3
      domain_name: stratuslab
      project_name: <my-project>
      tenant_name: <my-project>
      username: <my-username>
      password: <my-passwd>
    identity_api_version: 3

Testing environment¶

Now, you should be able to interact with Cloud@VirtualData infrastructure. To test your environment, you can request for a token, it will test your CLI installation and your clouds.yaml file.

$ openstack token issue --os-cloud virtualdata
+------------+----------------------------+
| Field      | Value                      |
+------------+----------------------------+
| expires    | 2024-04-26T12:27:09+0000   |
| id         | gAAAAABmK4-Nt5WbwFvKi[...] |
| project_id | 1b693dd6ab914fc0b5398[...] |
| user_id    | 4af03e06fc127ab62f674[...] |
+------------+----------------------------+

Importing ssh public key¶

OpenStack virtual machine are only available through ssh-key authentication. To access to your VM, you should provide a valid public ssh key.

$ ssh-keygen -t ed25519 -f ~/.ssh/id_openstack # Generating ssh key
$ openstack keypair create \
  --os-cloud virtualdata \
  --public-key ~/.ssh/id_openstack.pub vd-key
$ openstack keypair list --os-cloud virtualdata
+--------+-------------------------------------------------+------+
| Name   | Fingerprint                                     | Type |
+--------+-------------------------------------------------+------+
| vd-key | 00:11:22:33:44:55:66:77:88:99:aa:bb:cc:dd:ee:ff | ssh  |
+--------+-------------------------------------------------+------+

Quick start¶

Starting a virtual machine¶

To create a vm you have to provide a lot of different information, we will explain them later.

$ openstack server create \
  --os-cloud virtualdata \
  --flavor vd.4 \
  --image CentOS-Stream-GenericCloud-9-20220201.0.x86_64 \
  --key-name vd-key \
  --network public-2 \
   vm1.virtualdata.fr
$ openstack server list --os-cloud virtualdata
+----------+-------------+--------+--------------------+--------------+--------+
| ID       | Name        | Status | Networks           | Image        | Flavor |
+----------+-------------+--------+--------------------+--------------+--------+
| c1c[...] | vm1.vi[...] | ACTIVE | public-2=<ip-addr> | CentOS-[...] | vd.4   |
+----------+-------------+--------+--------------------+--------------+--------+

Accessing a virtual machine¶

All virtual machine have root ssh account disable. Each distribution provide a user account with sudo access. To known which user account use, the distribution return it when you try to log as root.

$ ssh -i ~/.ssh/id_openstack root@<ip-addr>
Please login as the user "cloud-user" rather than the user "root".
$ ssh -i ~/.ssh/id_openstack cloud-user@<ip-addr>
[cloud-user@vm1-virtualdata-fr~]$ hostname
vm1-virtualdata-fr.lal.in2p3.fr

Stopping a virtual machine¶

$ openstack server delete \
  --os-cloud virtualdata \
  vm1.virtualdata.fr

Advanced usage¶

Flavor¶

A flavor is the virtual ressource that will be allocated to virtual machine. A flavor is defined by Cloud@VirtualData administrator and based on hardware architecture to optimize the ressource usage. At Cloud@VirtualData, the flavor is based on a thread/memory ratio of 1 thread for 2 GB for RAM.

Cloud@VirtualData are named vd.<x> where <x> is the number of vCPU. Basically, flavor vd.4 mean 4 vCPUs and 8 GB of RAM.

You can list all available flavor with the command

$ openstack flavor list \
  --os-cloud virtualdata
+----------+-------+---------+------+-----------+-------+-----------+
| ID       | Name  |     RAM | Disk | Ephemeral | VCPUs | Is Public |
+----------+-------+---------+------+-----------+-------+-----------+
| 042[...] | vd.2  |    4000 |   20 |         0 |     2 | True      |
[...]
+----------+-------+---------+------+-----------+-------+-----------+

Image¶

Image is the based operating system installation that will be run by your virtual machine. All mayor linux distribution provide some basic image for OpenStack called GenericCloud. This is basically a "USB-like" version of the distribution.

As a user you can create a new image from a existing one. Creating a new image avoid installing from scratch everything each time you have to create a new virtual machine.

List existing images¶

$ openstack image list \
   --os-cloud virtualdata

Create a new image from a running virtual machine¶

$ openstack server image create \
   --os-cloud virtualdata \
   --name my-new-image \
   vm1.virtualdata.fr

Deleting a image¶

$ openstack server image delete my-new-image \
   --os-cloud virtualdata

Network¶

Network is the network provider for your virtual machine. On Cloud@VirtualData, you have access to a network called public-2 (note: public is deprecated and will be removed).

By default, if you provide no information during the virtual machine creation OpenStack will provide a random free IP address from the network you provide with --network option.

$ openstack network list \
   --os-cloud virtualdata

Reserve specific IP address¶

If you want to provide some services on Cloud@VirtualData, you need to reserve.

$ openstack port create \
  --os-cloud virtualdata \
  --network public-2 \
  my-port
$ openstack port show my-port \
   --os-cloud virtualdata | grep ip_address
| fixed_ips | ip_address=<my-ip>, subnet_id='63e[...]' |

Starting a virtual machine with a reserved IP¶

$ openstack server create \
  --os-cloud virtualdata \
  --flavor vd.4 \
  --image CentOS-Stream-GenericCloud-9-20220201.0.x86_64 \
  --key-name vd-key \
  --port my-port \
   vm-with-port-attached
$ ssh cloud-user@<my-ip>
[cloud-user@vm-with-port-attached ~]$
[cloud-user@vm-with-port-attached ~]$exit
$ openstack server delete vm-with-port-attached --os-cloud virtualdata

Releasing a reserved port¶

$ openstack port delete my-port \
   --os-cloud virtualdata

Security¶

OpenStack provide a network security feature called security-group. This feature allow user to configure out-of-the-vm firewall fully manageable by users.

Create security-group¶

$ openstack security group create my_security_group \
   --os-cloud virtualdata
$

Add firewall rules¶

$ openstack security group rule create \
   --os-cloud virtualdata \
   --remote-ip 0.0.0.0/0 \
   --dst-port 80 \
   --protocol TCP my_security_group
$

list current firewall rules¶

$ openstack security group rule list my_security_group \
   --os-cloud virtualdata
$

Start a VM with security group¶

$ openstack server create [...] --security-group my-security-group
$

Volume¶

A volume is a block device that can be attached to a virtual machine to provide some extra-space. A volume has it's own lifecycle and is not destroyed when you delete a virtual machine.

It can be view as a usb-key that can be attached and detach to virtual machine on demand and allow user to have persistent data on virtual machine that can survive to the virtual machine.

Create a volume¶

$ openstack volume create \
  --os-cloud virtualdata \
  --size 10 \
  my-volume
$

Attach a volume to a virtual machine¶

$ openstack server add volume \
  --os-cloud virtualdata \
  vm1.virtualdata.fr my-volume

Detach a volume¶

$ openstack server remove volume \
  --os-cloud virtualdata \
  --os-compute-api-version 2.20 \
  vm1.virtualdata.fr my-volume
$

Remove a existing volume¶

$ openstack volume delete \
  --os-cloud virtualdata \
  my-volume
$