Alert.png The wiki is deprecated and due to be decommissioned by the end of September 2022.
The content is being migrated to other supports, new updates will be ignored and lost.
If needed you can get in touch with EGI SDIS team using operations @ egi.eu.

Difference between revisions of "MAN10"

From EGIWiki
Jump to navigation Jump to search
(9 intermediate revisions by 2 users not shown)
Line 13: Line 13:
}}  
}}  


{{Template:Block-comment
| name=Warning
| text=The installation manual is now available at https://egi-federated-cloud-integration.readthedocs.io/. Information below just points to the relevant sections of that manual
}}


= Common prerequirements and documentation =
= Common prerequirements and documentation =


General minimal requirements are:
Requirements are described at the [https://egi-federated-cloud-integration.readthedocs.io/en/latest/requirements.html integration manual]


* Very minimal hardware is required to join. Hardware requirements depend on:
= Integration =
** the cloud stack you use
** the amount of resources you want to make available
** the number of users/use cases you want to support
*Servers need to authenticate each other in the EGI Federated Cloud context; this is fulfilled using X.509 certificates, so a Resource Centre should be able to obtain server certificates for some services.
*User and research communities are called Virtual Organisations (VO). At least support for 3 VOs is needed to join as a Resource Centre:
** ops and dteam, used for operational purposes as per RC OLA
** fedcloud.egi.eu: this VO provides resources for application prototyping and validation
*The operating systems supported by the EGI Federated Cloud Management Framework are:
** Scientific Linux 6, CentOS7 (and in general RHEL-compatible)
** Ubuntu (and in general Debian-based)


In order to configure Virtual Organisations and private image lists, please consider the following guides to:
Documentation is available at https://egi-federated-cloud-integration.readthedocs.io/
 
* [[HOWTO16|enable a Virtual Organisation on a EGI Federated Cloud site]]
* [https://wiki.appdb.egi.eu/main:faq:how_to_get_access_to_vo-wide_image_lists get access to VO wide image lists]
* [https://wiki.appdb.egi.eu/main:faq:how_to_subscribe_to_a_private_image_list_using_the_vmcatcher subscribe to a private image list]
 
= Integrating OpenStack  =
 
Integration with FedCloud requires a working OpenStack installation as a prerequirement (see http://docs.openstack.org/ for details). There are packages ready to use for most distributions (check for example [https://www.rdoproject.org/ RDO] for RedHat based distributions).
 
OpenStack integration with FedCloud is known to work with the following versions of OpenStack:
 
* ''Havana'' (EOL by OpenStack)
* ''Icehouse'' (EOL by OpenStack)
* ''Juno'' (EOL by OpenStack)
* ''Kilo'' (EOL by OpenStack)
* ''Liberty'' (EOL by OpenStack)
* '''Mitaka''' (Current stable release for Ubuntu 16.04, otherwise EOL by OpenStack)
* '''Newton''' (Current stable release for SUSE OpenStack Cloud 7 and RedHat OpenStack Platform 10), otherwise Phase II – Maintained release)
* '''Ocata''' (Phase II – Maintained release)
* '''Pike''' (Phase I – Latest release)
* ''Queens'' (under development)
 
See http://releases.openstack.org/ for more details on the OpenStack releases.
 
== Integration components ==
 
Which components must be installed and configured depends on the services the RC wants to provide.
* Keystone must be always available
* If providing '''VM Management''' features (OCCI access or OpenStack access), then '''Nova, Cinder and Glance''' must be available; also '''Neutron''' is needed, but nova-network can also be used for legacy installations (see  [http://docs.openstack.org/havana/install-guide/install/yum/content/section_networking-routers-with-private-networks.html here] how to configure per-tenant routers with private networks).
 
[[File:Openstack-fedcloud.png|800px]]
 
As you can see from the schema above, the integration is performed installing some EGI extensions on top of the OpenStack components.
 
*'''Keystone-VOMS Authorization plugin''' allow users with a valid VOMS proxy to access the OpenStack deployment
*'''OpenStack OCCI Interface (ooi)''' translates between OpenStack API and OCCI
*'''cASO''' collects accounting data from OpenStack
*'''SSM''' sends the records extracted by cASO to the central accounting database on the EGI Accounting service (APEL)
*'''BDII cloud provider''' registers the RC configuration and description through the EGI Information System to facilitate service discovery
*'''vmcatcher''' checks the [https://appdb.egi.eu/browse/cloud EGI App DB] for new or updated images that can be provided by the RC to the user communities (VO) supported
*The vmcatcher hooks ('''glancepush''' and '''OpenStack handler for vmcatcher''') push updated subscribed images from vmcatcher to Glance, using Openstack Python API 
 
== EGI User Management/AAI (Keystone-VOMS) ==
 
Every FedCloud site must support authentication of users with X.509 certificates with VOMS extensions. The Keystone-VOMS extension enables this kind of authentication on Keystone.
 
Documentation on the installation is available on https://keystone-voms.readthedocs.org/
 
Notes:
* '''You need a host certificate from a recognised CA for your keystone server'''.
* Take into account that using keystone-voms plugin will enforce the use of https for your Keystone service, you will need to update your URLs at the Keystone catalog and in the configuration of your services:
** You will probably need to include your CA to your system's CA bundle to avoid certificate validation issues: <code>/etc/ssl/certs/ca-certificates.crt</code> from the <code>ca-certificates</code> package on Debian/Ubuntu systems or <code>/etc/pki/tls/certs/ca-bundle.crt</code> from the <code>ca-certificates</code> on RH and derived systems. The [[Federated_Cloud_APIs_and_SDKs#CA_CertificatesCheck|Federated Cloud OpenStack Client guide]] includes information on how to do it.
** replace http with https in <code>auth_[protocol|uri|url]</code> and <code>auth_[host|uri|url]</code> in the nova, cinder, glance and neutron config files (<code>/etc/nova/nova.conf</code>, <code>/etc/nova/api-paste.ini</code>, <code>/etc/neutron/neutron.conf</code>, <code>/etc/neutron/api-paste.ini</code>, <code>/etc/neutron/metadata_agent.ini</code>, <code>/etc/cinder/cinder.conf</code>, <code>/etc/cinder/api-paste.ini</code>, <code>/etc/glance/glance-api.conf</code>, <code>/etc/glance/glance-registry.conf</code>, <code>/etc/glance/glance-cache.conf</code>) and any other service that needs to check keystone tokens.
** You can update the URLs of the services directly in the database:
<pre>
mysql> use keystone;
mysql> update endpoint set url="https://<keystone-host>:5000/v2.0" where url="http://<keystone-host>:5000/v2.0";
mysql> update endpoint set url="https://<keystone-host>:35357/v2.0" where url="http://<keystone-host>:35357/v2.0";
</pre>
 
* Support for EGI VOs: [[HOWTO16 | VOMS configuration]], you should configure fedcloud.egi.eu, dteam and ops VOs.
 
* VOMS-Keystone configuration: most sites should enable the <code>autocreate_users</code> option in the <code>[voms]</code> section of [https://keystone-voms.readthedocs.org/en/latest/configuration.html Keystone-VOMS configuration]. This will enable that new users are automatically created in your local keystone the first time they login into your site.
 
* if (and only if) you need to configure the Per-User Subproxy (PUSP) feature, please follow the specific guide at [https://wiki.egi.eu/wiki/Long-tail_of_science_-_information_for_providers#Instructions_for_OpenStack_providers Instructions_for_OpenStack_providers]
 
== EGI Virtual Machine Management Interface ==
 
EGI currently operates two realms: the Open Standards Realm and the OpenStack Realm. Both are completely integrated with the EGI federation services but they expose different interfaces to offer IaaS capabilities to the users. The Open Standards Realm uses OCCI standard (supported by providers with OpenNebula, OpenStack and Synnefo cloud management frameworks), while the OpenStack Realm uses the OpenStack native Nova API (support limited to OpenStack providers).
 
You can provide your service in one or both of the realms. For the OpenStack Realm, you just need to declare your endpoint in GOCDB as described below. For the Open Standards realm you will need to deploy an additional service for providing OCCI access.
 
[https://github.com/openstack/ooi ooi] is the recommended software to provide OCCI for OpenStack (from Juno onwards). Installation and configuration of ooi is available at [http://ooi.readthedocs.org/en/stable/index.html ooi documentation]. Packages for several distributions can be found at [https://appdb.egi.eu/store/software/ooi ooi entry at EGI's AppDB] (recommended version is 0.2.0)
 
For older OpenStack releases [https://github.com/EGI-FCTF/OCCI-OS OCCI-OS] can be used. Follow the <code>README.md</code> file in the github repo for instructions on installation and configuration. Be sure to select the branch (e.g. <code>stable/icehouse</code>) corresponding to your OpenStack deployment.
 
Once the OCCI interface is installed, you should register it on your installation (adapt the region and URL to your deployment):
<pre>
$ openstack service create --name occi --description "OCCI Interface" occi
+-------------+----------------------------------+
| Field      | Value                            |
+-------------+----------------------------------+
| description | OCCI Interface                  |
| enabled    | True                            |
| id          | 6dfd6a56c9a6456b84e8c86038e58f56 |
| name        | occi                            |
| type        | occi                            |
+-------------+----------------------------------+
 
$ openstack endpoint create --region RegionOne occi --publicurl http://172.16.4.70:8787/occi1.1
 
+-------------+----------------------------------+
|  Property  |              Value              |
+-------------+----------------------------------+
| description |          OCCI service          |
|      id    | 8e6de5d0d7624584bed6bec9bef7c9e0 |
|    name    |            occi_api            |
|    type    |              occi              |
+-------------+----------------------------------+
</pre>
 
== Integration with EGI FedCloud Appliance ==
 
Check the [[Federated Cloud OpenStack Appliance]] manual for information on how to perform the integration with the appliance.
 
== Integration with individual components ==
=== EGI Accounting (cASO/SSM) ===
 
Every cloud RC should publish utilization data to the EGI accounting database. You will need to install '''cASO''', a pluggable extractor of Cloud Accounting Usage Records from OpenStack.
 
Documentation on how to install and configure cASO is available at https://caso.readthedocs.org/en/latest/
 
In order to send the records to the accounting database, you will also need to configure '''SSM''', whose documentation can be found at https://github.com/apel/ssm
 
=== EGI Information System (BDII) ===
 
Sites must publish information to EGI information system which is based on BDII. The BDII can be installed easily directly from the distribution repository, the package is usually named "bdii".
 
There is a common cloud information provider for all cloud management frameworks that collects the information from the used CMF and send them to the aforementioned BDII. It can be installed on the same machine as the BDII or on another machine. The installation and configuration guide for the cloud information provider can be found in the following [[HOWTO15|Fedclouds BDII instructions]]; more detailed installation and configuration instructions are available at https://github.com/EGI-FCTF/cloud-bdii-provider
 
=== EGI Image Management (Cloudkeeper) ===
 
Sites in FedCloud offering VM management capability must give access to VO-endorsed VM images. This functionality is provided by the conjugation of two tools :
* [https://github.com/the-cloudkeeper-project/cloudkeeper Cloudkeeper] is a tool for subscribing to the image lists available in AppDB and retrieving the images
* [https://github.com/the-cloudkeeper-project/cloudkeeper-os Cloudkeeper-OS] is the OpenStack backend for Cloudkeeper
 
[[File:Cloudkeeper-openstack.png]]
 
==== Prerequisites ====
 
<code>cloudkeeper</code> uses VO-wide image lists provided by AppDB to synchronize virtual appliances to clouds. In order to use VO-wide image lists you need to have a valid access token to AppDB. Check [https://wiki.appdb.egi.eu/main:faq:how_to_get_access_to_vo-wide_image_lists how to access to VO-wide image lists] and [https://wiki.appdb.egi.eu/main:faq:how_to_subscribe_to_a_private_image_list_using_the_vmcatcher how to subscribe to a private image list] documentation for more information.
 
 
==== Cloudkeeper ====
 
Cloudkeeper is distributed as packages for multiple Linux distributions which are available in AppDB. This guide will expect CentOS 7 distribution but installation on any other supported distribution is very similar.
* Register the <code>cloudkeeper</code>  repository
wget http://repository.egi.eu/community/software/cloudkeeper/1.5.x/releases/repofiles/sl-7-x86_64.repo -O /etc/yum.repos.d/cloudkeeper.repo
* Install <code>cloudkeeper</code>
yum install -y cloudkeeper
 
<code>cloudkeeper</code> configuration file can be found in <code>/etc/cloudkeeper/cloudkeeper.yml</code>.
 
;image-lists
: URLs of image lists containing appliances which you want to synchronize to your cloud. Must contain authentication token.
  image-lists: # List of image lists to sync against
    - https://APPDB_TOKEN:x-oauth-basic@vmcaster.appdb.egi.eu/store/vo/somevo/image.list
    - https://APPDB_TOKEN:x-oauth-basic@vmcaster.appdb.egi.eu/store/vo/othervo/image.list
;image-dir
: Directory where images will be downloaded and converted before uploading to OpenStack. Directory is cleaned after each appliance registration/update nonetheless, it should provide sufficient free space (some runs may require up to 200GB of free space).
;remote-mode
: Says whether to serve downloaded images via web server or to copy them locally. Should be <code>true</code> especially if OpenStack is running on different machine than <code>cloudkeeper</code> and <code>cloudkeeper-os</code>.
;nginx->ip-address
: IP address on which NGINX will serve images in remote mode. This address MUST be accessible from the machine hosting <code>cloudkeeper-os</code> and your OpenStack installation.
;formats
: List of image formats images can be converted to and are supported by the cloud.
 
 
==== Cloudkeeper-OS ====
 
Cloudkeeper-os is distributed as packages for RHEL 7 and its derivatives (CentOS 7, Scientific Linux 7). In case you are using other Linux distributions, the software can be easily installed using the source code as described in the [https://github.com/the-cloudkeeper-project/cloudkeeper-os/blob/master/README.md README file]. To install Cloudkeeper-OS on CentOS 7, follow this procedure:
* Register <code>cloudkeeper-os</code> repository
wget http://grand-est.fr/resources/software/cloudkeeper-os/repofiles/centos7/cloudkeeper-os.repo
* Install <code>cloudkeeper-os</code>
yum install -y cloudkeeper-os
 
 
The <code>cloudkeeper-os.conf</code> configuration file has several sections and has a description for each option. Most of the options have default values. You should check at least the following parameters in the <code>keystone_authtoken</code> section:
* username
* password
* auth_url
 
For example:
<pre>
[keystone_authtoken]
username = cloudkeeper
password = cloudkeeper
auth_url = http://controller:5000/v3
</pre>
 
In addition, you have to edit the <code>voms.json</code> JSON file to map correctly the VO and the OpenStack project's name. Note that you can use the same JSON file as for the <code>keystone-voms</code> component, by setting the mapping_file parameter with the right path in the <code>cloudkeeper-os.conf</code> file.
 
Note that the user defined by the username parameter in the <code>cloudkeeper-os.conf</code> file should have the right to manage the images for all the project defined in the <code>voms.json</code> file.
 
To take into account the modifications, do not forget to restart the <code>cloudkeeper-os</code> service.
 
 
==== Usage ====
 
* Start and enable <code>cloudkeeper-os</code> service
service cloudkeeper-os start
chkconfig cloudkeeper-os on
<code>cloudkeeper-os</code> will be now listening for communication from <code>cloudkeeper</code>.
 
* Perform the first synchronization manually
# This process may take a long time, consider using '''tmux''' or '''screen'''
sudo -u cloudkeeper /opt/cloudkeeper/bin/cloudkeeper
 
* Start and enable <code>cloudkeeper-cron</code> service
service cloudkeeper-cron start
chkconfig cloudkeeper-cron on
 
This service registers a cron job which will run <code>cloudkeeper</code> every 2 hours.
 
== Post-installation ==
 
After the installation of all the needed components, it is recommended to set the following policies on Nova to avoid users accessing other users resources:
<pre>
[root@egi-cloud]# sed -i 's|"admin_or_owner":  "is_admin:True or project_id:%(project_id)s",|"admin_or_owner":  "is_admin:True or project_id:%(project_id)s",\n    "admin_or_user":  "is_admin:True or user_id:%(user_id)s",|g' /etc/nova/policy.json
[root@egi-cloud]# sed -i 's|"default": "rule:admin_or_owner",|"default": "rule:admin_or_user",|g' /etc/nova/policy.json
[root@egi-cloud]# sed -i 's|"compute:get_all": "",|"compute:get": "rule:admin_or_owner",\n    "compute:get_all": "",|g' /etc/nova/policy.json
</pre>
 
== Registration, validation and certification ==
 
As mentioned in the [https://wiki.egi.eu/wiki/Federated_Cloud_resource_providers_support main page], RC services must be '''registered''' in the [https://goc.egi.eu EGI Configuration Management Database (GOCDB)]. If you are creating a new site for your cloud services, please follow the [https://wiki.egi.eu/wiki/PROC09 Resource Centre Registration and Certification] with the help of EGI Operations and your reference Resource Infrastructure.
 
You will need to register the following services (all of them can be provided by the Federated Cloud Appliance):
* '''Site-BDII'''. This service collects and publishes site's data for the Information System. Existing sites should already have this registered.
* '''eu.egi.cloud.accounting'''. Register here the host sending the records to the accounting repository (executing SSM send).
* '''eu.egi.cloud.vm-metadata.vmcatcher''' for the VMI replication mechanism. Register here the host providing the replication.
 
If offering OCCI interface, the site must register also:
* '''eu.egi.cloud.vm-management.occi''' for the OCCI endpoint offered by the site. Please note the special endpoint URL syntax described at [[Federated_Cloud_Technology#eu.egi.cloud.vm-management.occi|GOCDB usage in FedCloud]]
 
If offering native OpenStack access, you must register:
* '''org.openstack.nova''' for the Nova endpoint of the site.  Please note the special endpoint URL syntax described at [[Federated_Cloud_Technology#org.openstack.nova|GOCDB usage in FedCloud]]
 
 
Site should also declare the following properties using the ''Site Extension Properties'' feature:
*# Max number of virtual cores for VM with parameter name: <code>cloud_max_cores4VM</code>
*# Max amount of RAM for VM with parameter name: <code>cloud_max_RAM4VM</code> using the format: value+unit, e.g. "16GB".
*# Max amount of storage that could be mounted in a VM with parameter name: <code>cloud_max_storage4VM</code> using the format: value+unit, e.g. "16GB".
 
The '''installation validation''' is part of the aforementioned [https://wiki.egi.eu/wiki/PROC09 Resource Centre Registration and Certification] procedure. After you register the services in GOCDB, EGI Operations will test your services using the [[HOWTO04_Site_Certification_Manual_tests#Check_the_functionality_of_the_cloud_elements|site certification manual tests]] mentioned in the same procedure. It is important to use that guide to test the services published to check that they are behaving properly.
 
Once the site services are registered in GOCDB (and flagged as "monitored") they will appear in the EGI service monitoring tools. EGI will check the status of the services (see [https://wiki.egi.eu/wiki/Federated_Cloud_infrastructure_status Infrastructure Status] for details). Check if your services are present in the EGI service monitoring tools and passing the tests; if you experience any issues (services not shown, services are not OK...) please contact back EGI Operations or your reference Resource Infrastructure.
 
= Integrating OpenNebula  =
 
EGI Federated Cloud Site based on OpenNebula is an ordinary OpenNebula installation with some EGI-specific integration components. There are no additional requirements placed on internal site architecture.
Follow [http://opennebula.org/documentation/ OpenNebula Documentation] if you need advice on how to install and configure OpenNebula itself.
 
'''The following OpenNebula versions are supported:'''
* OpenNebula v5.2.x
* OpenNebula v5.4.x
 
'''Integration Prerequisites:'''
* Working OpenNebula installation.
* Valid IGTF-trusted host certificates for selected hosts.
 
'''Please consider that:'''
* '''CDMI''' storage endpoints are currently '''not supported''' for OpenNebula-based sites.
* GUI integration is '''not''' supported.
 
[[File:OpenNebulaSite.png]]
 
The following '''components''' must be installed:
* '''rOCCI-server''' -- provides a standard virtual machine management interface. Configuration is [[#EGI_Virtual_Machine_Management|explained bellow]].
* '''keystorm''' -- serves federated authentication and authorization. Configuration is [[#EGI_User_Management|explained bellow]].
* '''cloudkeeper''' and '''cloudkeeper-one''', synchronize site with appliances from [https://appdb.egi.eu/browse/cloud EGI AppDB] Configuration is [[#EGI_Image_Management|explained bellow]].
* '''oneacct-export''' and '''apel-ssm''' -- collect accounting and publishe it into EGI's accounting database. Configuration is [[#EGI_Accounting|explained bellow]].
* '''cloud-info-provider''' and '''BDII''', register site in the EGI Information System. Configuration is [[#EGI_Information_System|explained bellow]].
 
The following '''ports''' must be open to allow access to an OpenNebula-based FedCloud sites:
 
{| class="wikitable" style="margin: auto; margin-top: 30px; margin-bottom: 30px;"
|+ Open Ports for OpenNebula and other components
! style="width: 90px;" | Port
! style="width: 110px;" | Application
! style="width: 430px;" | Host
! style="width: 250px;" | Note
|-
|'''2633'''/TCP
|'''OpenNebula'''/XML-RPC
|'''OpenNebula'''
|Communication between integration components and OpenNebula.
|-
|'''2170'''/TCP
|'''BDII'''/LDAP
|'''cloud-info-provider'''/'''BDII'''
|EGI Service Discovery/Information System
|-
|'''11443'''/TCP
|'''OCCI'''/HTTPS
|'''rOCCI-server'''
|EGI Virtual Machine Management
|-
|'''5000'''/TCP
|'''keystorm'''/HTTPS
|'''keystorm'''
|EGI User Management
|-
|'''50505'''/TCP
|'''cloudkeeper'''/HTTP
|'''cloudkeeper'''
|EGI Image Management, needs to be accessible from '''cloudkeeper-one''' node only
|-
|'''50051'''/TCP
|'''cloudkeeper-one'''/gRPC
|'''cloudkeeper-one'''
|EGI Image Management, needs to be accessible from '''cloudkeeper''' node only
|}
 
There are no additional requirements for '''OpenNebula''' hosts used to run virtual machines.
 
This is an overview of '''service accounts''' used in an OpenNebula-based site. The names are default and can be changed if required.
 
{| class="wikitable" style="margin: auto; margin-top: 30px; margin-bottom: 30px;"
|+ Service Accounts
! style="width: 90px;" | Type
! style="width: 110px;" | Account name
! style="width: 180px;" | Host
! style="width: 500px;" | Use
|-
|rowspan="6"|System accounts
|<code>rocci</code>
|rOCCI-server
|Service account for '''rOCCI-server'''. It is only a service account, no access required.
|-
|<code>keystorm</code>
|keystorm
|Service account for '''keystorm'''. It is only a service account, no access required.
|-
|<code>apel</code>
|oneacct-export/APEL
|Service account for '''oneacct-export/APEL'''. Just a service account, no access required.
|-
|<code>openldap</code>
|cloud-info-provider/BDII
|Service account for '''cloud-info-provider/BDII'''. Just a service account, no access required.
|-
|<code>cloudkeeper</code>
|cloudkeeper
|Service account for '''cloudkeeper'''. Just a service account, no access required.
|-
|<code>cloudkeeper-one</code>
|cloudkeeper-one
|Service account for '''cloudkeeper-one'''. Just a service account, no access required.
|}
 
=== EGI Virtual Machine Management ===
==== Prerequisites ====
Enable EPEL and install the following packages prior to installation:
  yum install -y epel-release wget
 
==== Installation ====
rOCCI-server is distributed as package for multiple Linux distributions which is available in AppDB. This guide will expect CentOS 7 distribution but installation on any other supported distribution is very similar.
 
* Register <code>rOCCI-server</code> repositories
  wget http://repository.egi.eu/community/software/rocci.server/2.x/releases/repofiles/sl-7-x86_64.repo -O /etc/yum.repos.d/rocci-server.repo
* Install package
  yum install -y occi-server
 
==== Configuration ====
* Make rOCCI-server listen on a public interface
<pre>
mkdir -p /etc/systemd/system/occi-server.socket.d
cat > /etc/systemd/system/occi-server.socket.d/override.conf <<EOS
[Socket]
# lines below are NOT duplicated by mistake
ListenStream=
ListenStream=0.0.0.0:11443
EOS
</pre>
<pre>
sed -i 's/HOST=127.0.0.1/HOST=0.0.0.0/g' /etc/occi-server/variables
</pre>
* Uncomment and configure optional parameters in ''/etc/occi-server/variables''
<pre>
export HOST_CERT=/path/to/cert                                    # host certificate readable by the rocci user
export HOST_KEY=/path/to/key                                      # host key readable by the rocci user
</pre>
<pre>
export ROCCI_SERVER_KEYSTONE_URI=https://localhost:5000/          # URL pointing to keystorm installation
</pre>
<pre>
export ROCCI_SERVER_OPENNEBULA_ENDPOINT=http://localhost:2633/RPC2 # URL pointing to OpenNebula installation
</pre>
<pre>
export ROCCI_SERVER_ENCRYPTION_TOKEN_CIPHER=                      # crypto options MUST MATCH keystorm's crypto options, see /etc/keystorm/variables
export ROCCI_SERVER_ENCRYPTION_TOKEN_KEY=                          # crypto options MUST MATCH keystorm's crypto options, see /etc/keystorm/variables
export ROCCI_SERVER_ENCRYPTION_TOKEN_IV=                          # crypto options MUST MATCH keystorm's crypto options, see /etc/keystorm/variables
</pre>
* Enable and start the service
<pre>
systemctl enable occi-server
systemctl start occi-server
</pre>
 
==== Runtime ====
* Import resource templates to OpenNebula
<pre>
/opt/occi-server/bin/oneresource create --endpoint http://one.example.org:2633/RPC2 # --username PRIVILEGED_USER --password PASSWD
# re-run with `--resources /opt/occi-server/embedded/app/rOCCI-server/lib/resources/gpu/` to enable GPU resource templates
</pre>
* In OpenNebula, set flags for groups by adding attributes:
<pre>
DEFAULT_CLUSTER_ID="0"              # Default cluster for this group
DEFAULT_CONNECTIVITY="public"      # Default connectivity for this group: public|nat|private
</pre>
* In OpenNebula, set network type on networks used via OCCI by adding an attribute:
<pre>
NETWORK_TYPE="public"              # Supported types: public|nat|private
</pre>
* In OpenNebula, set flag for networks that should be treated as public IP pools (for IP reservations) by adding an attribute:
<pre>
FLOATING_IP_POOL="yes"
</pre>
* In OpenNebula, set additional network attributes:
<pre>
NETWORK_ADDRESS=""                  # e.g., "172.16.100.0"
NETWORK_MASK=""                    # e.g., "255.255.255.0"
GATEWAY=""                          # e.g., "172.16.100.1"
</pre>
 
==== Migration from v1 to v2 ====
In order to migrate from rOCCI-server v1 with Perun-managed user accounts, perform the following steps.
 
===== Preparation =====
* Disconnect direct propagation (slave scripts)
* Remove all user accounts that do not have any resource allocations
 
===== Migration =====
* Merge multiple single-group accounts into one account with multiple groups
<pre>
Single-group accounts owned by the same person can be identified as having:
 
* `NAME` following the naming convention $VONAME_$ID where the same user always has the same $ID
* `TEMPLATE/X509_DN` where the same user always has the same DN
</pre>
<pre>
Name of the merged user MUST be a SHA256 digest of the `TEMPLATE/X509_DN` attribute value.
 
In ruby, SHA256 digest can be generated as:
 
require 'digest'
Digest::SHA256.hexdigest 'DN_STRING_HERE'
</pre>
* Manually add user attributes
<pre>
For each user, add the following attributes:
 
* TEMPLATE/ID
* TEMPLATE/NAME
* TEMPLATE/IDENTITY
* TEMPLATE/AUTHENTICATION
 
Where
 
* `TEMPLATE/ID` is a SHA256 digest of the `TEMPLATE/X509_DN` attribute value
* `TEMPLATE/IDENTITY` and `TEMPLATE/NAME` contain the old `TEMPLATE/X509_DN` value
* `TEMPLATE/AUTHENTICATION` is a static value 'voms'
</pre>
* ''chown'' all user-owned resources to the new user
 
=== EGI User Management ===
==== Prerequisites ====
Enable EPEL and install the following packages prior to installation:
  yum install -y epel-release wget
 
==== Installation ====
keystorm is distributed as package for multiple Linux distributions which is available in AppDB. This guide will expect CentOS 7 distribution but installation on any other supported distribution is very similar.
 
* Register <code>keystorm</code> repositories
  wget http://repository.egi.eu/community/software/keystorm/1.x/releases/repofiles/sl-7-x86_64.repo -O /etc/yum.repos.d/keystorm.repo
* Install package
  yum install -y keystorm
 
==== Configuration ====
* Uncomment and configure optional parameters in ''/etc/keystorm/variables''
<pre>
export KEYSTORM_OPENNEBULA_ENDPOINT=http://localhost:2633/RPC2    # URL pointing to OpenNebula installation
export KEYSTORM_OPENNEBULA_SECRET=oneadmin:opennebula              # Privileged OpenNebula credentials (with user and group management permissions)
</pre>
* Enable and start the service
<pre>
systemctl enable keystorm
systemctl start keystorm
</pre>
* Configure Apache2/httpd
<pre>
# on Ubuntu/Debian only
a2enmod ssl && \
  a2enmod headers && \
  a2enmod proxy && \
  a2enmod proxy_http && \
  a2enmod remoteip && \
  a2enmod auth_openidc && \
  a2enmod zgridsite
</pre>
<pre>
# make sure the following files exist
SSLCertificateFile /etc/grid-security/hostcert.pem
SSLCertificateKeyFile /etc/grid-security/hostkey.pem
 
# make sure the following directory exists
SSLCACertificatePath /etc/grid-security/certificates
</pre>
* Enable and start Apache2/httpd
<pre>
# on Ubuntu/Debian only
systemctl enable apache2
systemctl restart apache2
</pre>
<pre>
# on CentOS/SL only
systemctl enable httpd
systemctl start httpd
</pre>
* Enable support for EGI VOs via VOMS: [[HOWTO16 | VOMS configuration]]
* Enable support for EGI VOs via OIDC: ''TBD''
 
==== Runtime ====
* In OpenNebula, create empty groups for ''fedcloud.egi.eu'', ''ops'', and ''dteam'' with group attribute:
<pre>
KEYSTORM="YES"                  # Allow keystorm to manage membership for this group
</pre>
 
=== EGI Accounting ===
 
==== Prerequisites ====
<code>oneacct-export</code> uses '''Secure Stomp Messenger''' to send accounting records to the central repository. Please, refer to <code>ssm</code> documentation for [https://github.com/apel/ssm installation instructions]. By default, accounting records are placed in <code>/var/spool/apel/outgoing/00000000</code>. You '''have to''' configure and run <code>ssmsend</code> periodically, this is not handled by oneacct-export.
 
Enable EPEL and install the following packages prior to oneacct-export installation:
  yum install -y epel-release wget
 
==== Installation ====
 
oneacct-export is distributed as package for multiple Linux distributions which is available in AppDB. This guide will expect CentOS 7 distribution but installation on any other supported distribution is very similar.
 
* Register <code>oneacct-export</code> repositories
  wget http://repository.egi.eu/community/software/oneacct.export/0.4.x/releases/repofiles/sl-7-x86_64.repo -O /etc/yum.repos.d/oneacct-export.repo
* Install package
  yum install -y oneacct-export
 
==== Configuration ====
* Edit <code>/etc/oneacct-export/conf.yml</code>
 
  apel:
    site_name: Undefined                    # Usually a short provider name, e.g. CESNET
    cloud_type: OpenNebula                  # CMF type, only OpenNebula is supported
    endpoint: https://localhost.edu:11443/ # Public URL of your OCCI endpoint
 
  xml_rpc:
    secret: oneadmin:opennebula            # OpenNebula credentials, privileged
    endpoint: http://localhost:2633/RPC2 # OpenNebula XML RPC endpoint
 
* Add the following lines to <code>/etc/one/oned.conf</code> and restart OpenNebula
  INHERIT_IMAGE_ATTR = "VMCATCHER_EVENT_AD_MPURI"
  INHERIT_IMAGE_ATTR = "VMCATCHER_EVENT_DC_IDENTIFIER"
  INHERIT_IMAGE_ATTR = "VMCATCHER_EVENT_IL_DC_IDENTIFIER"
  INHERIT_IMAGE_ATTR = "VMCATCHER_EVENT_SL_CHECKSUM_SHA512"
  INHERIT_IMAGE_ATTR = "VMCATCHER_EVENT_HV_VERSION"
 
* Set benchmark values on CLUSTERs (applies to all hosts in the cluster) or HOSTs (only for that host) in OpenNebula
  BENCHMARK_TYPE  = "HEP-SPEC06" # benchmark type
  BENCHMARK_VALUE = "84.46"      # represents a per-core measured value of said benchmark
 
* Use <code>/etc/oneacct-export/groups.include</code> or <code>/etc/oneacct-export/groups.exclude</code> to control which information gets exported. Specify one group name per line.
 
==== Usage ====
* Enable and register service 'redis'
  service redis start
  chkconfig redis on
 
* Enable and register service 'oneacct-export-sidekiq'
  service oneacct-export-sidekiq start
  chkconfig oneacct-export-sidekiq on
 
* Perform the first export manually
  # This process may take a long time, consider using '''tmux''' or '''screen'''
  sudo -u apel /usr/bin/oneacct-export-cron --all
 
* Enable and register service 'oneacct-export-cron'
  service oneacct-export-cron start
  chkconfig oneacct-export-cron on
 
This service registers a cron job which will run oneacct-export every 2 hours.
 
=== EGI Information System ===
 
Sites must publish information to EGI information system which is based on BDII. There is a common [https://github.com/EGI-FCTF/cloud-bdii-provider bdii provider] for all cloud management frameworks. Information on installation and configuration is available in the cloud-bdii-provider [https://github.com/EGI-FCTF/cloud-bdii-provider/blob/master/README.md README.md] and in the [[Fedclouds BDII instructions]], there is a [[Fedclouds_BDII_instructions#OpenNebula_.2B_rOCCI|specific section with OpenNebula details]].
 
=== EGI Image Management ===
[https://github.com/the-cloudkeeper-project/cloudkeeper cloudkeeper] and [https://github.com/the-cloudkeeper-project/cloudkeeper-one cloudkeeper-one] are tools used to ensure synchronization of virtual appliances with an [https://opennebula.org/ OpenNebula]-based cloud.
 
[[File:Cloudkeeper-setup.png]]
 
==== Prerequisites ====
<code>cloudkeeper</code> uses VO-wide image lists provided by AppDB to synchronize virtual appliances to clouds. In order to use VO-wide image lists you need to have a valid access token to AppDB. Check [https://wiki.appdb.egi.eu/main:faq:how_to_get_access_to_vo-wide_image_lists how to access to VO-wide image lists] and [https://wiki.appdb.egi.eu/main:faq:how_to_subscribe_to_a_private_image_list_using_the_vmcatcher how to subscribe to a private image list] documentation for more information.
 
* Install recent <code>qemu-img</code> and <code>wget</code>
  yum install -y centos-release-qemu-ev wget sudo
 
==== Installation ====
Both <code>cloudkeeper</code> and <code>cloudkeeper-one</code> are distributed as packages for multiple Linux distributions which are available in AppDB. This guide will expect CentOS 7 distribution but installation on any other supported distribution is very similar.
* Register <code>cloudkeeper</code> and <code>cloudkeeper-one</code> repositories
wget http://repository.egi.eu/community/software/cloudkeeper/1.x/releases/repofiles/sl-7-x86_64.repo -O /etc/yum.repos.d/cloudkeeper.repo
wget http://repository.egi.eu/community/software/cloudkeeper.one/1.x/releases/repofiles/sl-7-x86_64.repo -O /etc/yum.repos.d/cloudkeeper-one.repo
 
* Install <code>cloudkeeper</code> and <code>cloudkeeper-one</code>
yum install -y cloudkeeper cloudkeeper-one
 
==== <code>cloudkeeper</code> configuration ====
<code>cloudkeeper</code> configuration file can be found in <code>/etc/cloudkeeper/cloudkeeper.yml</code>.
 
;image-lists
: URLs of image lists containing appliances which you want to synchronize to your cloud. Must contain authentication token.
  image-lists: # List of image lists to sync against
    - https://APPDB_TOKEN:x-oauth-basic@vmcaster.appdb.egi.eu/store/vo/somevo/image.list
    - https://APPDB_TOKEN:x-oauth-basic@vmcaster.appdb.egi.eu/store/vo/othervo/image.list
;authentication
: Says whether <code>cloudkeeper</code> and <code>cloudkeeper-one</code> will communicate securely via TLS. This requires options <code>certificate</code>, <code>key</code> and <code>backend->certificate</code> to be properly set.
;image-dir
: Directory where images will be downloaded and converted before uploading to OpenNebula. Directory is cleaned after each appliance registration/update nonetheless, it should provide sufficient free space (some runs may require up to 200GB of free space).
;remote-mode
: Says whether to serve downloaded images via web server or to copy them locally. Should be <code>true</code> especially if OpenNebula is running on different machine than <code>cloudkeeper</code> and <code>cloudkeeper-one</code>.
;nginx->ip-address
: IP address on which NGINX will serve images in remote mode. This address MUST be accessible from the machine hosting <code>cloudkeeper-one</code> and your OpenNebula installation.
;formats
: List of image formats images can be converted to and are supported by the cloud.
 
==== <code>cloudkeeper-one</code> configuration ====
<code>cloudkeeper-one</code> configuration file can be found in <code>/etc/cloudkeeper-one/cloudkeeper-one.yml</code>.
 
;authentication
: Says whether <code>cloudkeeper</code> and <code>cloudkeeper-one</code> will communicate securely via TLS. This requires options <code>certificate</code>, <code>key</code> and <code>core->certificate</code> to be properly set.
;appliances->tmp-dir
: Directory images will be copied to before registration in OpenNebula when in non-remote mode.
;appliances->template-dir
: Directory for ERB-enabled templates of OpenNebula images and templates used for registration. More information in the next section.
;opennebula->datastores
: List of OpenNebula datastores images are uploaded to.
;opennebula->allow-remote-source
: Allows OpenNebula to directly download images in remote mode.
 
==== Templates configuration ====
The directory specified by option <code>appliances->template-dir</code> contains templates for OpenNebula images and templates in files <code>image.erb</code> and <code>template.erb</code>. These files can be customized to register images and templates according to your needs. Files are using standard ERB templating mechanism. By default, these files can be found in <code>/etc/cloudkeeper-one/templates/</code>.
 
* <code>image.erb</code> available variables:
;name
: Name, under which will the image be registered
;appliance
: Appliance object. Contains following attributes: <code>identifier</code>, <code>title</code>, <code>description</code>, <code>mpuri</code>, <code>group</code>, <code>ram</code>, <code>core</code>, <code>version</code>, <code>architecture</code>, <code>operating_system</code>, <code>vo</code>, <code>expiration_date</code>, <code>image_list_identifier</code>, <code>attributes</code>.
;image
: Image object. Contains following attributes: <code>format</code>, <code>uri</code>, <code>checksum</code>, <code>size</code>
 
* <code>template.erb</code> available variables:
;name
: Name, under which will the template be registered
;image_id
: ID of the previously registered image (same appliance)
;appliance
: Appliance object. Same as for <code>image.erb</code>
;image
: Image object. Same as for <code>image.erb</code>
 
 
'''For compatibility with other integration components, add the following lines to <code>image.rb</code>:'''
VMCATCHER_EVENT_AD_MPURI="<%= appliance.mpuri %>"
VMCATCHER_EVENT_HV_VERSION="<%= appliance.version %>"
VMCATCHER_EVENT_DC_DESCRIPTION="<%= appliance.description %>"
VMCATCHER_EVENT_DC_TITLE="<%= appliance.title %>"
 
==== Usage ====
* Start and enable <code>cloudkeeper-one</code> service
service cloudkeeper-one start
chkconfig cloudkeeper-one on
<code>cloudkeeper-one</code> will be now listening for communication from <code>cloudkeeper</code>.
 
* Perform the first synchronization manually
# This process may take a long time, consider using '''tmux''' or '''screen'''
sudo -u cloudkeeper /opt/cloudkeeper/bin/cloudkeeper
 
* Start and enable <code>cloudkeeper-cron</code> service
service cloudkeeper-cron start
chkconfig cloudkeeper-cron on
This service registers a cron job which will run <code>cloudkeeper</code> every 2 hours.


= Registration of services in GOCDB =
= Registration of services in GOCDB =
Line 715: Line 30:
Site cloud services must be registered in [https://goc.egi.eu EGI Configuration Management Database (GOCDB)]. If you are creating a new site for your cloud services, check the [[PROC09|PROC09 Resource Centre Registration and Certification]] procedure. Services can also coexist within an existing (grid) site.
Site cloud services must be registered in [https://goc.egi.eu EGI Configuration Management Database (GOCDB)]. If you are creating a new site for your cloud services, check the [[PROC09|PROC09 Resource Centre Registration and Certification]] procedure. Services can also coexist within an existing (grid) site.


If offering OCCI interface, sites should register the following services:
The [https://egi-federated-cloud-integration.readthedocs.io/en/latest/registration.html integration documentation] details how to register your services into GOCDB
* eu.egi.cloud.vm-management.occi for the OCCI endpoint offered by the site. Please note the special endpoint URL syntax described at [[Federated_Cloud_Technology#eu.egi.cloud.vm-management.occi|GOCDB usage in FedCloud]]
* eu.egi.cloud.accounting (host should be your OCCI machine)
* eu.egi.cloud.vm-metadata.vmcatcher (also host is your OCCI machine)
* Site should also declare the following properties using the ''Site Extension Properties'' feature:
*# Max number of virtual cores for VM with parameter name: <code>cloud_max_cores4VM</code>
*# Max amount of RAM for VM with parameter name: <code>cloud_max_RAM4VM</code> using the format: value+unit, e.g. "16GB".
*# Max amount of storage that could be mounted in a VM with parameter name: <code>cloud_max_storage4VM</code> using the format: value+unit, e.g. "16GB".


= Installation Validation  =
= Installation Validation  =


You can check your installation following these steps:
Check [https://egi-federated-cloud-integration.readthedocs.io/en/latest/validation.html validation documentation] for details.
 
*Check in [https://argo-mon2.egi.eu/nagios ARGO-Mon2] that your services are listed and are passing the tests. If all the tests are OK, your installation is already in good shape.
*Check that you are publishing cloud information in your site BDII:<br><code>ldapsearch -x -h &lt;site bdii host&gt; -p 2170 -b Glue2GroupID=cloud,Glue2DomainID=&lt;your site name&gt;,o=glue</code>
*Check that all the images listed in the [https://appdb.egi.eu/store/vo/fedcloud.egi.eu AppDB&nbsp;page for fedlcoud.egi.eu VO&nbsp; ]are listed in your BDII. This sample query will return all the template IDs registered in your BDII:<br><code>ldapsearch -x -h &lt;site bdii host&gt; -p 2170 -b Glue2GroupID=cloud,Glue2DomainID=&lt;your site name&gt;,o=glue objectClass=GLUE2ApplicationEnvironment GLUE2ApplicationEnvironmentRepository</code>
*Try to start one of those images in your cloud. You can do it with `onetemplate instantiate` or OCCI commands, the result should be the same.
*Execute the [[HOWTO04_Site_Certification_Manual_tests#Check_the_functionality_of_the_cloud_elements|site certification manual tests]] against your endpoints.
*Check in the [http://accounting-devel.egi.eu/cloud.php accounting portal] that your site is listed and the values reported look consistent with the usage of your site.


[[Category:Operations_Manuals]]
[[Category:Operations_Manuals]]

Revision as of 10:53, 10 September 2018

Main EGI.eu operations services Support Documentation Tools Activities Performance Technology Catch-all Services Resource Allocation Security


Documentation menu: Home Manuals Procedures Training Other Contact For: VO managers Administrators



Title Cloud Resource Centre Installation Manual
Document link https://wiki.egi.eu/wiki/MAN10
Last modified 19 May 2017
Policy Group Acronym OMB
Policy Group Name Operations Management Board
Contact Group operations-support@mailman.egi.eu
Document Status DRAFT
Approved Date
Procedure Statement This manual provides information on how to set up a Resource Centre providing cloud resources in the EGI infrastructure.
Owner Owner of procedure


Warning:
The installation manual is now available at https://egi-federated-cloud-integration.readthedocs.io/. Information below just points to the relevant sections of that manual


Common prerequirements and documentation

Requirements are described at the integration manual

Integration

Documentation is available at https://egi-federated-cloud-integration.readthedocs.io/

Registration of services in GOCDB

Site cloud services must be registered in EGI Configuration Management Database (GOCDB). If you are creating a new site for your cloud services, check the PROC09 Resource Centre Registration and Certification procedure. Services can also coexist within an existing (grid) site.

The integration documentation details how to register your services into GOCDB

Installation Validation

Check validation documentation for details.