Linux
A full working client environment is configured on the lxplus service but there may be a need to install clients on other machines such as a personal laptop or an application server which needs to interact with OpenStack.
If you are developing an application, it is advised to use one of the software development toolkits rather than scripting around the command line tools.
Note
Currently, local installation of the OpenStack clients provides support for the OS_PASSWORD openrc method of authentication.
Puppet clients
If your machine uses Puppet, you can include the standard OpenStack clients by adding the following to your manifests.
Container image clients
Users can opt for running the clients in a containerised environment using the cci-openstack-client container image to access the CERN OpenStack cloud.
This image can be run via Docker or Podman, usually available in the default repos of the main distributions.
Run commands interactively using kerberos
The image can be used to run commands interactively. In this case, using the default Kerberos authentication method is the recommended approach:
username@linux:~$ docker run -it registry.cern.ch/cloud/cci-openstack-client:cern bash
[root@d3b3cba9b18b /]# kinit your-user-name
Password for fernandl@CERN.CH:
[root@d3b3cba9b18b /]# export OS_PROJECT_NAME="Personal your-user-name"
[root@d3b3cba9b18b /]# openstack server list
+--------------------------------------+---------------+--------+------------------------------+
| ID | Name | Status | Networks |
+--------------------------------------+---------------+--------+------------------------------+
| 00000000-0000-0000-0000-000000000000 | instance-name | ACTIVE | CERN_NETWORK=0.0.0.0 |
+--------------------------------------+---------------+--------+------------------------------+
Run commands using password authentication
By default the image is configured to use Kerberos, but it is possible as well to use password based authentication. This approach can be handy while automating tasks:
username@linux:~$ echo "Enter your OpenStack password: " && read -sr OS_PASSWORD_INPUT && export OS_PASSWORD=$OS_PASSWORD_INPUT
username@linux:~$ docker run --env OS_USERNAME=your-user-name --env OS_PASSWORD --env OS_PROJECT_NAME="Personal your-user-name" --env OS_AUTH_TYPE=v3password -it registry.cern.ch/cloud/cci-openstack-client:cern openstack server list
+--------------------------------------+---------------+--------+------------------------------+
| ID | Name | Status | Networks |
+--------------------------------------+---------------+--------+------------------------------+
| 00000000-0000-0000-0000-000000000000 | instance-name | ACTIVE | CERN_NETWORK=0.0.0.0 |
+--------------------------------------+---------------+--------+------------------------------+
Integrate with OpenStack using Application Credentials
This is not an exhaustive guide
For further details please refer to the OpenStack documentation.
Application Credentials may be used to grant a user's privileges, or a subset of these, to a client application. The application will use a special secret to authenticate, and not the user's password or Kerberos ticket. This approach may be especially suited for making applications integrate with OpenStack, as one avoids having to tie the user's account credentials to the setup.
Do note, however, that any Application Credential is tied to a user account.
This means one must pay attention to its life cycle with regards to changes in team membership.
In return, Application Credentials allow for smooth transitions by use of the --expiration flag for setting expiration times, and the possibility of smoothly transferring responsibility from one to another by rotating overlapping credentials.
1: Create an Application Credential
Application Credential secrets
When creating the Application Credential, remember to take note of the displayed secret. It will be displayed only once.
Alternatively, provide a secret of your own using the --secret flag (but do not use your password!).
An Application Credential will by default inherit the full Roles of your user account, which usually means the Member, reader, and potentially owner roles to your selected project. Create an Application Credential like so:
openstack application credential create --description "Application credential with my user permissions" user_credentials
To further restrict the rule's privileges we specify an Access Rule that only grants access to specific APIs when creating the Application Credential. In this example the credential will grant access to listing the user's VMs, but you may adapt it to your specific use case. The correct endpoints can be found in the OpenStack API references, such as the Nova Compute reference.
openstack project list # Find the ID of your project
openstack application credential create --description "Grant my application the ability to list servers" list_servers_only --access-rules '[
{
"path": "/v2.1/<project_id>/servers/*",
"method": "GET",
"service": "compute"
}
]'
Then run a command to test:
Access rules and secondary actions
Beware that some openstack commands may trigger secondary actions for which your Application Credential doesn't have sufficient privileges. In the example below we add --name-lookup-one-by-one to avoid such an action.
OS_PROJECT_NAME='' openstack --os-auth-type v3applicationcredential --os-application-credential-id <credential_id> --os-application-credential-secret <credential_secret> server list --name-lookup-one-by-one
2: Use the Application Credential
Check the API reference
More details on how to authenticate using application credentials can be found in the API reference.
Once you have created an Application Credential you may use it to create a token, and submit that token when performing your desired OpenStack request. You may do this using using our programming language and even OpenStack framework of choice for said language:
#!/usr/bin/env python3
"""
A simple Application Credential example using the Python SDK.
"""
import openstack
AUTH_URL = "https://keystone.cern.ch"
REGION = "cern"
API_URL = "https://openstack.cern.ch:8774"
CREDENTIAL_ID = "<credential_id>"
CREDENTIAL_SECRET = "<credential_secret>"
#openstack.enable_logging(debug=True)
def connect():
return openstack.connect(
auth_url=AUTH_URL,
auth_type="v3applicationcredential",
application_credential_id=CREDENTIAL_ID,
application_credential_secret=CREDENTIAL_SECRET,
region_name=REGION,
)
def list_servers(connection):
return connection.list_servers(bare=True, all_projects=False)
def main():
connection = connect()
print(list_servers(connection))
if __name__ == '__main__':
main()
#!/usr/bin/env python3
"""
An example of how to use the API using requests.
"""
import json
import requests
AUTH_URL = "https://keystone.cern.ch/v3/auth/tokens"
API_URL = "https://openstack.cern.ch:8774/v2.1"
NOVA_API_VERSION = "2.72"
PROJECT_ID = '<project_id>'
CREDENTIAL_ID = "<credential_id>"
CREDENTIAL_SECRET = "<credential_secret>"
def authenticate():
req_body = {
"auth": {
"identity": {
"methods": [
"application_credential"
],
"application_credential": {
"id": CREDENTIAL_ID,
"secret": CREDENTIAL_SECRET
}
}
}
}
r = requests.post(AUTH_URL, json=req_body)
#print(r.headers) # This is where your token is
#print(json.dumps(r.json(), sort_keys=True, indent=4)) # More details
return r.headers['x-subject-token']
def list_servers(token):
headers = {
"Accept": "application/json",
"X-Auth-Token": f'{token}',
"OpenStack-API-Version": f"compute {NOVA_API_VERSION}",
"X-OpenStack-Nova-API-Version": f"{NOVA_API_VERSION}",
"User-Agent": "python-novaclient"
}
r = requests.get(
f"{API_URL}/{PROJECT_ID}/servers/detail",
headers=headers
)
print(json.dumps(r.json(), sort_keys=True, indent=4))
def main():
token = authenticate()
list_servers(token)
if __name__ == '__main__':
main()
Commands accessing local files
Commands that required access to local files (e.g. create glance images) can be executed using the standard docker options to share files from the host to the container. The following example downloads a cloud image and uploads it to glance:
username@linux:~$ curl -L http://download.cirros-cloud.net/0.6.2/cirros-0.6.2-x86_64-disk.img -o ./Downloads/cirros.img
username@linux:~$ docker run -it -v ./Downloads:/mnt registry.cern.ch/cloud/cci-openstack-client:cern bash
[root@d3b3cba9b18b /]# kinit your-user-name
Password for fernandl@CERN.CH:
[root@d3b3cba9b18b /]# export OS_PROJECT_NAME="Personal your-user-name"
[root@4aa4970972f2 /]# openstack image create cirros-test --file /mnt/cirros.img
+------------------+-----------------------+
| Field | Value |
+------------------+-----------------------+
| container_format | bare |
| created_at | 2024-01-23T12:53:25Z |
(...)
ciadm container image
We currently recommend using cci-openstack-client
container image as it will be the one more actively maintained. If users still rely on the ciadm one, it is
still accessible in the existing location:
If you want your home and afs directories available in the container, do instead (after getting your afs credentials set):
kinit <YOURAFSUSER>
sudo docker run -it --privileged -e KRB5CCNAME=/tmp/krb5cc_$UID -e AFS_USER=<YOURAFSUSER> -v /tmp:/tmp -v /afs:/afs gitlab-registry.cern.ch/cloud/ciadm
Once you got a shell in the container, you can use the clients as before:
Local installation
If you have a standalone Enterprise Linux like machine (e.g. Red Hat Linux or AlmaLinux) and would like to install the OpenStack clients manually, you can do the following using the RDO packages.
This has been tested on Red Hat Enterprise Linux and AlmaLinux 8 and 9 versions. Installation issues on Fedora should be followed up with the Fedora and RDO community
Enterprise Linux environment
This recipe installs the Yoga version of the OpenStack client packages, which are compatible with the CERN Cloud Infrastructure.