voms-client
EGI VOMS Client
General information
About VOMS and VOs
This is an Ansible role which configures VOMS clients. VOMS is a web service for managing membership of Virtual Organisations. VOMS clients are necessary to obtain authorisation (in the form of short-lived proxies) for interacting with specific services, based on VO membership. VOMS clients are set of command-line utilities which send authenticated requests to the relevant VOMS server in order to request authorisation from them.
In order to use the VOMS client, an individual needs to
- have a personal x.509 certificate
- be registered in the VO they want to get an authorisation for
VOMS clients are typically installed on the User Interface or Worker Node profiles.
Configuration
Configuration of the VOMS clients is done with a few files:
.lsc
filesvomses
files
See the VOMS documentation for more detailed information.
For every VO you wish to interact with, the relevant configuration needs to be in place. This can be quite a time-consuming task, especially in cases where a site administrator does not know a-priori which VOs to configure.
To make life bearable, we take a data-driven approach.
The necessary data is available via the EGI Operations Portal API, which is used in this role as a data source. This allows us to configure all VOs registered in the Operations Portal in one foul swoop. Two approaches could be taken to generating the configuration:
- configuration from raw data pulled from Lavoisier at Ansible runtime
- configuration from filtered data pulled from Lavoisier prior to Ansible runtime.
In the former approach, a well-crafted
json_query
could be used to iterate over the data returned from Lavoisier. The query in
this case needs to reflect the complexity and structure of the data object
returned by Lavoisier, which cannot be assumed to return an array of consistent
data. In the latter approach, a much simpler is used to iterate over a cached
data object, which has been filtered to exclude items which do not contain the
relevant information. This cached data can be easily created by a simple python
script - files/create_clean_vo_data.py which
reads the role vars and creates a local cache of data. The data format has been
chosen to be YAML so that we can add it to the repository and keep track of
changes - this would be difficult with JSON, due to the lack of lines.
We have opted for the latter (see 4215026e18c) for the following reasons:
- It is easier to maintain a well-documented script than a complex json query.
- It is easier to read a well-documented script than a complex json query
- If the role is added as a dependency to playbooks (as will certainly be the case, since the voms clients are used all over the place), the data needs to be present.
There is however the drawback that the data in the repo can quickly become out of synch with the actual data on Lavoisier. This could happen either by individuals editing the cache by hand, or by the maintainer not running the script when necessary. The only way to overcome this is to maintain a strong test suite.
Updating the VO data
In order to update the VO data using files/create_clean_vo_data.py, an authentication token is required to interact with the EGI Operations Portal API.
The token can be generated by accessing, while being authenticated via EGI Check-in, the Operations Portal API documentation page, follow the instructions on the page, and then export the token into the environment before running files/create_clean_vo_data.py.
It is possible to test that the token is working using a curl call:
# Exporting Operations Portal API token
$ export OPS_PORTAL_API_TOKEN='...'
# Testing an API call using curl
$ curl -X GET "https://operations-portal.egi.eu/api/vo-voms/json" \
-H "Accept: application/json" \
-H "X-API-Key: $OPS_PORTAL_API_TOKEN"
Once the curl
call is confirmed to work, it's possible to use the provided
script:
# Exporting Operations Portal API token
$ export OPS_PORTAL_API_TOKEN='...'
# Updating the VO data
$ ./files/create_clean_vo_data.py
Testing
The role is tested with molecule for the following scenarios:
default
(tested with TestInfra)
Tests cover unit and integration tests, but not functional tests, since a personal certificate is necessary for using the VOMS client. Specific tests included are:
- presence of binary executables
- presence of configuration directories
- contents of configuration files for selected VOs
Requirements
See requirements.txt
.
Role Variables
Role variables kept on defaults/main.yml
include:
prerequisites
- the prerequisite packages on an OS-basisvoms_dir
,vomses_dir
- directory locations on the target host which contain the voms informationlavoisier
- the lavoisier framework endpoints necessary for extracting the data necessary to populate the configuration files.
There is no need to change the default variables.
Dependencies
Dependencies are not explicitly declared in the metadata, but this role depends on the UMD role:
- { role: EGI-Foundation.umd, release: 4 }
Example Playbook
- hosts: servers
roles:
- { role: EGI-Foundation.umd, release: 4 }
- { role: EGI-Foundation.voms-client }
License
Apache-2.0
Author Information
See AUTHORS.md
ansible-galaxy install EGI-Foundation/ansible-VOMS-client-role