Deploy instance using CLI

An instance can be deployed from the OpenStack command-line interface as well as from the Horizon GUI. This guide describes the steps needed to deploy a server ready to host live applications. The CLI offers a higher degree of flexibility often needed for more complex projects and enables the automation of tasks.

Contents

To use Pan-Net Cloud Services, you need to have a tenant. The first step is to create or order a tenant on Pan- described in Create a tenant.

We can think of the tenant as the space or resources used for a project, such as implementing a particular service. You need to select a project name for the tenant, hereafter denoted by <project-name> in this chapter. We refer to some properties as pertaining to the tenant or the associated project somewhat exchangeably, which hopefully will not cause any confusion.

After creation of the first tenant in a data center, the portal will send you an e-mail with a machine-generated password, denoted <password> in the text. This password is valid for all your tenants in the same data center. At this point it is also convenient to create a project folder on your client.

This guide describes how to create a virtual machine with networking, including the following steps:

  • Creation of instance using the OpenStack CLI

  • Configuration of an internal network and subnet

  • Assignment and association of a public IP address

The client communicates with the VM over SSH. To enable this connection, it is necessary to

  • Create and add the certificate to the SSH client (or import the public key to the instance)

  • Allow SSH traffic to the instance by assigning to it a security group with suitable rules

Please note that assignment of network, security group and floating IP can be done after the instance has been created and when it is running, whereas the key pair cannot be changed on a running instance.

Configure client

In this guide, we assume that the client is configured on a PC running on Ubuntu and with Python 3 installed.

It is good practice is to create a virtual environment for the project to prevent Python conflict with other applications. For details on how to configure the client on different environments, see Configure client

Install OpenStack client

OpenStack commands are run from the client, which needs to have the OpenStack client package installed. It is easily installed through the Python package manager pip (following a package list update to ensure the latest version is installed) by the commands

sudo apt-get update
pip install python-openstackclient

In some Python configurations, the pip command may fail. In that case replacing pip by pip3 in the command above should work. See also the relevant section in Troubleshooting.

Download OpenStack RC file

On the Pan-Net portal, an OpenStack RC resource script file with environment variables is generated at the same time as the tenancy space and it can be downloaded from there clicking the button Project / Compute / API Access / Download OpenStack RC File v2.0 (Figure 1).

Alternatively, it can be found in the user profile in the right-hand upper corner (Figure 2).

The name of the OpenStack RC file is <project-name>-openrc.sh, which is a bash script file that can be opened in any text editor. The <project-name> is the name given to your tenant at the time of its creation. By opening the script file in a text editor, your credentials should be visible in some of the variables, for example

export OS_TENANT_ID=<project-id> 
export OS_TENANT_NAME="<project-name>"
export OS_USERNAME="<openstack-username>”

Connect to cloud via OpenStack CLI

To connect to the cloud via the OpenStack CLI you first need to run the RC script you downloaded to set the environment variables properly by

source <project-name>-openrc.sh

You will be prompted to enter your tenant password, which is the same password used when logging in to the Horizon portal.

Try the interface with, for example

openstack flavor list

Note that when the client is restarted, the exported environment variables can be lost. If the variables are undefined, an OpenStack command will raise the error

Missing value auth-url required for auth plugin password

It is then necessary to execute the source command again.

Create key pair in tenant

A key pair can be generated and shared by a single OpenStack command. The shared key is locally stored in PEM (Privacy Enhanced Mail) format, so the following command creates a key with name that you give it, denoted by <key-pair-name> and then stores the file as <key-pair-name>.pem.

openstack keypair create <key-pair-name> > <key-pair-name>.pem

Note that in this command, the variable <key-pair-name> is followed by the scripting output operator >, which writes the result to the specified file, <key-pair-name>.pem.

A suitable location to store the file is a project directory created for the tenant on the client machine. It is also necessary to set the correct permissions by

chmod 0600 <key-pair-name>.pem

To verify that the key pair has been created on the cloud side, use the command

openstack keypair list

to prints a list of available key pairs.

Finally, import the file to the SSH client by

ssh-add <key-pair-name>.pem

Note that to establish a connection with an instance with the key <key-pair-name> associated to it, no password is needed, only the command

ssh <username>@<IP address>

For Ubuntu, <username> is ubuntu. The path to the key file to be used can be specified explicitly in the SSH command as

ssh -i <key-pair-name> <username>@<IP address>

Configure network

If there is no internal network present, created automatically with the tenant or in a previous deployment, then it needs to be configured in a few steps. Whether an internal network exists or not can easily be established from the query

openstack network list

If there is only an external network (like is shown in Figure 3), then proceed with the steps below. Otherwise, this section can be skipped over.

Create network

An internal network is created by

openstack network create <network-name>

Network properties are set in a subnet that belongs to this network, created next.

Create subnet

When creating the subnet, the chosen IP range on the local network needs to be passed as an argument value. This range is expressed in CIDR notation and can be almost any legal IP address range. Common address ranges are 10.x.x.x or 192.168.x.x. In CIDR notation, a subrange is written 10.0.0.0/24.

Other arguments determine address assignment through DHCP and sets the DNS name servers (primary and secondary) for domain name resolution. The addresses below are pointing to the Google public DNS servers with IP addresses 8.8.8.8 and 8.8.4.4.

openstack subnet create --subnet-range 10.0.0.0/24 --dhcp --network <network-name> --dns-nameserver 8.8.8.8 --dns-nameserver 8.8.4.4 <subnet-name>

Create router

The internal network needs to have a router, which is created by

openstack router create <router-name>

Then, it is connected to the local subnet with

openstack router add subnet <router-name> <subnet-name>

Finally, router internet connectivity is enabled by setting the external gateway represented by the external network in the tenant

openstack router set <router-name> --external-gateway <external-network>

Create an instance

To create an instance from the OpenStack client, we need to execute a command with the syntax and arguments as described below. The command generating the VM instance (also called server) is

openstack server create --flavor <flavor> --image <image> --nic net-id=<network-id> --security-group default --key-name <key-pair-name> <server-name>

The command syntax details are printed with the help flag: openstack -h server create.

Valid argument values for <flavor>, <image>, <network-id> and <key-pair-name> can be obtained or verified with the OpenStack client list command. The chosen values can then be pasted into the command line above, and the whole command copied to the console and executed. The ID is almost always a valid identifier in OpenStack client commands. In most cases, the name of the object can be used as well.

To find the valid options of the argument <flavor> (Figure 4), enter

openstack flavor list

The actual flavors may differ from the ones shown in the figure. A list of available flavors can also be found in Virtual machines

For the valid options of the arguments <image> (Figure 5), use

openstack image list

and to find valid options for the argument --nic net-id, run openstack network list (see also the previous section on configuration of the internal network).

Select the network ID corresponding to the internal network created for the tenant space, either automatically or following the steps in the section Configure network. Valid options of the arguments security-group can be found by

openstack security group list

The security group default is created at the initiation of the tenant space. At this time, this security group can be used for simplicity. Note that security groups can be added or modified while the instance is running.

For valid values of the arguments <key-pair-name>, use

openstack keypair list

Note that this is the public key that is required for the SSH client. Further details can be found in Configure client
Now, execute the command with the selected argument values and a chosen server name in place of <server-name> to create the instance, for example

openstack server create --flavor g1.standard-1-1 --image ubuntu-18.04-x86_64 --nic net-id=72b4844e-a072-4ab7-b654-b040aec8f515 --security-group default --key-name mykey myserver

This process takes a few moments to complete. After the server has been created, a summary table is printed out as shown in Figure 6, with the private IP address marked.

At any time, the details of any instance can be found with

openstack server show <server-name>

Associate IP address

To associate an IP address with the new VM, we need to perform a few operations. Note that the VM has been assigned a private (local) IP address already, but this address needs to be mapped to a public IP address (a floating IP) for direct internet access. When running

openstack floating ip list

OpenStack will probably not report anything, meaning that no floating IP is available. First, we need to allocate an IP address. To do this, use the command

openstack floating ip create <external-network>

where <external-network> is the resource from where the floating IPs are obtained. To verify that an IP address has been created, do

openstack floating ip list

which should list a floating IP address without any associated fixed IP address or port. Denoting the created floating IP address by <IP address>, assign it to the instance with

openstack server add floating ip <server-name> <IP address>

To to see the instance configuration including the public IP address, run

openstack server list

The IP assignment can also be verified in the output from openstack floating ip list.

Add security group

A security group acts as an external firewall protecting compute instances. By default, access to the instance is blocked, and a security group with rules specifying allowed traffic needs to be created and assigned to the server before it can be reached.

Create security group

Security groups determines the type of traffic that is allowed to reach the network interface on the instance. To create a security group for SSH, we first create a new security group and then add a rule for allowing TCP over port 22. A new security group is created by

openstack security group create <security-group-name>

Create a SSH security group, here called ssh-only by

openstack security group create ssh-only

The SSH rule is created with

openstack security group rule create --dst-port 22 --protocol tcp --ingress ssh-only

To enable ping (ICMP), we can create the rule and add it to ssh-only by

openstack security group rule create --protocol icmp --remote-ip 0.0.0.0/0 ssh-only

A list of rules is obtained from the command-line by

openstack security group rule list

For many practical purposes, it is useful to have a security group for HTTP traffic (on port 80) as well. It is created, calling the security group global-http, by

openstack security group create global-http

openstack security group rule create --protocol tcp --dst-port 80:80 --remote-ip 0.0.0.0/0 global-http

For more details, see Configure security

Assign security group

A security group can be assigned to an instance when created, or added to it later to a running instance from the OpenStack client. The command

openstack server add security group <server-name> <security-group>

takes the arguments (ID or name) of the server and the security group. Valid values for <server-name> and <security-group> can be found by querying

openstack server list
openstack security group list

Note that all relevant security groups need to be added to an instance, in this case both ssh-only and global-http, that is

openstack server add security group <server-name> ssh-only
openstack server add security group <server-name> global-http

Connect to instance

The SSH connection step is identical to Deploy instance using Horizon.

Now, everything has been set up and you should be able to access your VM over SSH. The connection is established by the command

ssh <user-name>@<IP address>

where <IP address> is the public IP address previously associated with the VM. The user name <user-name> is a default name associated with the image chosen for your VM’s operating system, for example ubuntu for Ubuntu. A table with these names can be found in Image service. The login is password-less and authentication is only performed by key pairs.

The first time SSH is invoked, you are presented with the fingerprint of the public key of the server and prompted to accept it. Answering yes at the prompt launches the session and the server’s key is stored in the file /.ssh/known_hosts on the client for future use. The prompt now shows the user and remote host name (Figure 7).

To use a specific key for setting up a connection, use the argument -i with the key name, for example

ssh -i <key-pair-name>.pem ubuntu@<IP address>

where the key is named <key-pair-name>.pem.

A common error is forgetting to change permissions of the key file. Instead of opening the session, an error message is shown (Figure 8).

To fix this, simply do

sudo chown 0600 <key-pair-name>.pem

and issue the SSH command again.

Using the instance

Now, your virtual machine is configured with internet access and prepared for installation of applications. After connecting to the VM by SSH, you may, for example, perform a system update and upgrade directly on your VM by

sudo apt update && sudo apt upgrade

The procedure described in this chapter can be done directly from the command-line, as described in Deploy instance using CLI. In general, the command-line interface offers a higher degree of flexibility and efficiency - a single command can replace a number of GUI operations.

When the instance is ready to use, its floating IP can be reused after providing access through a bastion host for management operations, see Configure bastion host