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.

Your account¶

When we grant you access to cloud@vd, we provide some information about your account:

project: An OpenStack project is a container for Virtual Servers.
domain: An authentication domain. cloud@vd provides several domains depending on your institute affiliation:
- stratuslab: An external user
- u-psud: A Université Paris-Saclay user
- ijclab: An IJCLab user
username: Your username

For more convenient reading, we will refer to these attributes as environment variables.

$ export vd_project="my projet"
$ export vd_domain="u-psud"
$ export vd_username="username"

Installation¶

Mac OS X installation procedure¶

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

Application credential¶

OpenStack allow token type authentication through application credential. The main idea is to create a token for every application (gitlab CI/CD, laptop, ...). So, you don't have to store clear-text password anymore and if you lose a device you can easily remove the access by destroying the corresponding token.

Creating application token¶

To create token, you have to use OpenStack CLI and set some environments

$ openstack application credential create \
    --os-auth-url https://keystone.ijclab.in2p3.fr:5000/v3 \
    --os-username ${vd_username}\
    --os-domain-name ${vd_domain}\
    --os-project-name ${vd_project} \
    $(hostname)
+--------------+-------------+
| Field        | Value       |
+--------------+-------------+
| description  | None        |
| expires_at   | None        |
| id           | ed278[...]  |
| name         | ${HOST}     |
| project_id   | 245bc[...]  |
| roles        | users       |
| secret       | EtjI8[...]  |
| system       | None        |
| unrestricted | False       |
| user_id      | 5d3c9[...]  |
+--------------+-------------+

Note

A application credential is scope to all of your current roles. If we grant you another role, you have to renew your application credential. In same idea, you can restrict your application credential to specifics roles. To learn more about application credential, refer to official OpenStack documentation.

Danger

This is the last time OpenStack will be able to give you the secret, if you lose it, you will not be able to retrieve it.

List application token¶

After configuration your CLI according the documentation you can manage your token.

$ openstack application credential list
+-----------+-------------+------------+-------------+------------+
| ID        | Name        | Project ID | Description | Expires At |
+-----------+-------------+------------+-------------+------------+
| 3e46[...] | ${HOST}     | 5e42[...]  | None        | None       |
+-----------+-------------+------------+-------------+------------+

Removing application token¶

Danger

If you remove your token, you will not be able to authenticate with this token anymore

$ openstack application credential delete \
    $(hostname)

OpenStack configuration¶

OpenStack's configuration is store in two different file. The first one will define cloud provider information (clouds-public.yaml), the second one information about projects specific information (cloud.yaml).

clouds-public.yaml¶

$ cat > ~/.config/openstack/clouds-public.yaml <<EOF
public-clouds:
  virtualdata:
    auth_type: v3applicationcredential
    identity_api_version: 3
    auth:
      auth_url: https://keystone.ijclab.in2p3.fr:5000/v3
EOF

cloud.yaml file information¶

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 <<EOF
clouds:
  virtualdata:
    cloud: virtualdata
    auth:
      application_credential_id: ed278[...]
      application_credential_secret: EtjI8[...]
EOF
$ export OS_CLOUD=virtualdata

Testing environment¶

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

$ openstack token issue
+------------+----------------------------+
| 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 \
  --public-key ~/.ssh/id_openstack.pub vd-key
$ openstack keypair list
+--------+-------------------------------------------------+------+
| Name   | Fingerprint                                     | Type |
+--------+-------------------------------------------------+------+
| vd-key | 00:11:22:33:44:55:66:77:88:99:aa:bb:cc:dd:ee:ff | ssh  |
+--------+-------------------------------------------------+------+

Quick start¶

Authorize ssh connection¶

By default, your project forbid all connection from outside. To allow ssh connection, you have to create a security group rule. You can have more information in section security.

$ openstack security group rule create \
   --remote-ip 0.0.0.0/0 \
   --dst-port 22 \
   --protocol TCP default

Note

For security consideration, in production you have to limit the ssh access to a small set of IP (basically from lab IP range)

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 \
  --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
+----------+-------------+--------+--------------------+--------------+--------+
| 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 \
  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@vd administrator and based on hardware architecture to optimize the ressource usage. At cloud@vd, the flavor is based on a thread/memory ratio of 1 thread for 2 GB for RAM.

cloud@vd 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
+----------+-------+---------+------+-----------+-------+-----------+
| 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
$

Create a new image from a running virtual machine¶

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

Download a image¶

If you want to get a image to save it, or to upload it on another cloud infrastructure, you can download it on your workstation with the following command.

$ openstack image save \
   --file /tmp/my-local-image-name \
   my-new-image
$ file /tmp/my-local-image-name
/tmp/u14: QEMU QCOW2 Image (v2), 2361393152 bytes

Uploading a new image¶

If you have prepared locally a new image or get an image from outside sources. You can upload it to OpenStack with the following command.

$ openstack image create \
   --disk-format qcow2
   --container-format bare \
   --file /tmp/my-local-image-name \
   my-new-image-v2
+------------------+---------------------------+
| Field            | Value                     |
+------------------+---------------------------+
| container_format | bare                      |
| created_at       | 2025-03-22T08:52:31Z      |
| disk_format      | qcow2                     |
| file             | /v2/images/3903[...]/file |
| id               | 3903[...]                 |
| min_disk         | 0                         |
| min_ram          | 0                         |
| name             | my-new-image-v2           |
| owner            | 5e42[...]                 |
| properties       | [...]                     |
| protected        | False                     |
| schema           | /v2/schemas/image         |
| status           | queued                    |
| tags             |                           |
| updated_at       | 2025-03-22T08:52:31Z      |
| visibility       | public                    |
+------------------+---------------------------+
$ openstack image show 3903[...]  
+------------------+---------------------------------------------------------------------------------+
| Field            | Value                                                                           |
+------------------+---------------------------------------------------------------------------------+
| checksum         | 3402[...]                                                                       |
| container_format | bare                                                                            |
| created_at       | 2025-03-22T08:52:31Z                                                            |
| disk_format      | qcow2                                                                           |
| file             | /v2/images/3903[...]                                                            |
| id               | 3903[...]                                                                       |
| min_disk         | 0                                                                               |
| min_ram          | 0                                                                               |
| name             | my-new-image-v2                                                                 |
| owner            | 5e42[...]                                                                       |
| properties       | direct_url='rbd://5ba6[...]/images/3903[..]/snap', os_hash_algo='sha512',       |
|                  | os_hash_value='c3cd[...]', os_hidden='False', owner_specified.openstack.md5='', |
| protected        | False                                                                           |
| schema           | /v2/schemas/image                                                               |
| size             | 711524352                                                                       |
| status           | active                                                                          |
| tags             |                                                                                 |
| updated_at       | 2025-03-22T08:53:42Z                                                            |
| virtual_size     | 10737418240                                                                     |
| visibility       | public                                                                          |
+------------------+---------------------------------------------------------------------------------+

Deleting a image¶

$ openstack server image delete my-new-image
$

Network¶

Network is the network provider for your virtual machine. On cloud@vd, 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.

Note

cloud@vd allow user to start a VM with a public IP. On most cloud infrastructure you have to use a self-provisionned private network and use floating ip to make your virtual machine reachable.

$ openstack network list
$

Reserve specific IP address¶

If you want to provide some services on cloud@vd, you need to reserve.

$ openstack port create \
  --network public-2 \
  my-port
$ openstack port show my-port | grep ip_address
| fixed_ips | ip_address=${ip}, subnet_id='63e[...]' |

Starting a virtual machine with a reserved IP¶

$ openstack server create \
  --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@${ip}
[cloud-user@vm-with-port-attached ~]$
[cloud-user@vm-with-port-attached ~]$exit
$ openstack server delete vm-with-port-attached

Releasing a reserved port¶

$ openstack port delete my-port
$

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
$

Add firewall rules¶

$ openstack security group rule create \
   --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
$

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 \
  --size 10 \
  my-volume
$

Attach a volume to a virtual machine¶

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

Detach a volume¶

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

Remove a existing volume¶

$ openstack volume delete \
  my-volume
$

Object storage¶

cloud@vd provide a object storage service which allow users to put data using there cloud@vd credential. For more info about object storage you can find a short introduction here

Creating a bucket¶

Warning

As we use ceph as backend, containers need to have a unique name for all users, to avoid painful experience to find a unused name, you should prefix all your container name by your cloud@vd project name. If you have Conflict (HTTP 409) (Request-ID: [...]-swift_z1) while creating your container, this mean you have to choose another name.

$ export CONTAINER_PREFIX=$(openstack token issue \
    |grep project_id | awk '{print $4}')
$ openstack container create ${CONTAINER_PREFIX}-my-container
$ openstack container list
+----------------------------------+
| Name                             |
+----------------------------------+
| ${CONTAINER_PREFIX}-my-container |
+----------------------------------+
$

Upload a object¶

$ echo "Hello world !" > my-file
$ openstack object create ${CONTAINER_PREFIX}-my-container my-file
$

List all objects¶

$ openstack object list
+---------+
| Name    |
+---------+
| my-file |
+---------+

Retrieve a object¶

$ openstack object save --file $(date +%s) ${CONTAINER_PREFIX}-my-container my-file
$

Delete a object¶

$ openstack object delete ${CONTAINER_PREFIX}-my-container my-file
$

Use S3 credentials¶

$ openstack ec2 credential create
+------------+-------------------------------------------------------------+
| Field      | Value                                                       |
+------------+-------------------------------------------------------------+
| access     | d66f5e[...]                                                 |
| links      | {'self': 'https://keystone.lal.in2p3.fr:5000/v3/users/[...] |
| project_id | 5e4266[...]                                                 |
| secret     | 549200[...]                                                 |
| trust_id   | None                                                        |
| user_id    | f1e4d8[...]                                                 |
+------------+-------------------------------------------------------------+

If you want to use a pure S3 client as s5cmd you have to treat access value as AWS_ACCESS_KEY_ID and secret as AWS_SECRET_ACCESS_KEY. The S3 endpoint for cloud@vd is https://swift.ijclab. in2p3.fr:8080/.

For s5cmd, the final value should be something like

export S3_ENDPOINT_URL="https://swift.ijclab.in2p3.fr:8080/"
export AWS_ACCESS_KEY_ID=d66f5e[...]
export AWS_SECRET_ACCESS_KEY=549200[...]