Federation Service Deployment

High-Level Architecture

On the scheme below you can find the deployment scheme of the Federation service and its database for two regions, for example, UK and Spain.

The Federation service deployment requires:

Operations and Billing in the source and target regions
Branding node in the source region only
Hardware nodes in the target region only

Note that nodes should be attached to the correct locations in the target region. Location names in the source and target regions should not be the same. The attribute and location names should be in capital letters. Make sure that the location limit is set to 1 in the service templates.
The Instance Manager in the source and target regions
Federation service and Nginx (used as VNC proxy) in the source and target regions
Federation databases in both regions containing region mapping as in the following table:

Region	Location
UK	England
UK	Scotland
Spain	Valencia

The deployment procedure is the following:

Deploy the Federation database.
Deploy the VNC Proxy (Nginx).
Deploy the Federation service.
Configure the Cloud Infrastructure Automation CI Endpoint.
Configure Location to Region mapping.
Configure branding to route the VNC traffic.
Configure security settings.

Step 1. Federation Database Deployment

The Federation database can be deployed on the same node as the Federation service or on a different one.

To create the Federation database, do the following:

Register the Federation service and Federation DB nodes in CloudBlue Commerce as Generic Linux Node.
On the Federation DB node, install PostgreSQL 9.6 (or later).

Create a user and a database:

sudo -u postgres psql
create user federation;
create database federation with owner federation;
alter user federation with password '<PASSWORD>';
\q
exit

Configure the database access by password for the federation user:

# vim /var/lib/pgsql/9.6/data/pg_hba.conf

host federation federation 127.0.0.1/32 password
host federation federation <Federation_service_node_IP>/32 password

Edit postgres server config file /var/lib/pgsql/9.6/data/postgresql.conf to allow access from the remote node (row 59):
```
listen_addresses = '*'
```
Restart postgres service to apply the changes:
```
systemctl restart postgresql-9.6
```

Step 2. VNC Proxy (Nginx) Deployment

Nginx must be installed on the same node as the Federation service.

To install Nginx, follow the instructions in the official guide.

Step 3. Federation Service Deployment

Deploy the Federation service in both regions.

Install Java SDK.
```
yum install -y java-1.8.0-openjdk
```

Copy the Federation distributive to the Federation service node:

wget http://download.automation.odin.com/oaci/federation/1.0/latest.tar.gz

Unpack the Federation service distribution.

tar -C /usr/local/ -xzvf federation-service.tar.gz

Create a user.

groupadd federation
useradd -g federation -d /usr/local/federation -s /sbin/nologin federation
usermod -a -G federation nginx

Configure the Federation service.

cd /usr/local/federation
cp example.env .env
cp example.application.yaml application.yaml
cp nginx/example.nginx.conf nginx/nginx.conf

Edit the application.yaml file by adding the IP addresses of the Federation service node, Federation DB node, IM, and Endpoint node. You should also define different IDs for regions. Open /usr/local/share/PACI-aps/paci-config.xml file on the Endpoint node and find the passwords for admin-aps and amq logins.
```
vim application.yaml
```
Define the location for the Federation service log.
```
ln -s /usr/local/federation/logs /var/log/federation
chown -R federation:federation /usr/local/federation
```
The Federation service log will be stored in the federation-<region_id>.log.

Replace the default Nginx configuration file with the correct one.

cp /usr/local/federation/nginx/example.nginx.conf /etc/nginx/nginx.conf
systemctl enable nginx.service
systemctl restart nginx.service

To allow restarting or reloading nginx, add the following line to /etc/sudoers
```
federation ALL=(ALL)    NOPASSWD: /usr/bin/systemctl * nginx
```

Configure systemd and start the Federation service.

ln -s /usr/local/federation/federation.service /usr/lib/systemd/system/federation.service
systemctl daemon-reload
systemctl enable federation.service
systemctl start federation.service

Step 4. Cloud Infrastructure Automation CI Endpoint Configuration

In the /usr/local/share/PACI-aps/paci-config.xml file on the Endpoint Node in the source region, replace the IM url with the Federation service url:

Find the IM root key

<im>
    <root>http://<IM_IP>:4465/paci/v1.0</root>

Replace with the following

<im>
    <root>http://<Federation_service_IP>:8880/im-api-proxy/paci/v1.0</root>
    <rootOriginal>http://<IM_IP>:4465/paci/v1.0</rootOriginal>

Replace the <jms><topic> section:

Find the following
```
<jms>
    <topic>PACI.IM</topic>
```
Replace with the following
```
<jms>
    <topic>PACI.IM.PROXY</topic>
```

Step 5. Branding Node Configuration to Route VNC Traffic

Copy the file scripts/configure-branding-for-vnc.py from the Federation service distribution package on the Federation service node to the Management Node.
Execute the following script on the MN in both regions:
```
python configure-branding-for-vnc.py --region-id <id> --nginx-host-port "<nginx_IP>:<nginx_port>"
```
where

<id> – id of the opposite region.

<nginx_IP>:<nginx_port> – IP address and port of the Federation service node located in the opposite region.

For example, if you launch the script in the source region, then you should use the target region ID and IP address of the Federation service node located in the target region.

Step 6. Configuring "Location to Region" Mapping

Now you should define locations on the Federation Service nodes in both regions. The location values must be exactly the same as in PCP. All locations must be entered in every region.

Connect to the Federation DB using psql.
```
su - postgres
psql federation
```

Add "location to region" mappings and region settings. The example of configuration with the local region UK and remote region Spain:

insert into location values ('DEFAULT');
insert into location values ('SPAIN');
insert into region (name) values ('UK');
insert into region (name) values ('SPAIN');
INSERT INTO region_location (region_id, location_id) VALUES (1, 'DEFAULT');
INSERT INTO region_location (region_id, location_id) VALUES (2, 'SPAIN');
INSERT INTO region_config (region_id, host, port, nginx_host, nginx_port)
VALUES (
2,
'<federation_service_ip>',
8890,
'<federation_service_ip>',
8840
);
\q
exit

Make sure that nginx_port defined in the Branding Node Configuration step is the same as in the instruction above.

Example

federation=# select * from location;
id
---------
DEFAULT
SPAIN
(2 rows)

federation=# select * from region;
  id |  name
----+--------
   1 | UK
   2 | SPAIN
(2 rows)

federation=# select * from region_location;
region_id | location_id
  -----------+-------------
                1 | DEFAULT
                2 | SPAIN
(2 rows)

federation=# select * from region_config;
region_id |        host            | port   |    nginx_host   | nginx_port
  -----------+------------------+-------+------------------+---------------
                2 | 10.31.24.245 | 8890 | 10.31.24.245 |       8840
(1 row)

After any manual changes of the Federation DB, you need to restart the Federation service:
```
systemctl restart federation
```

Step 7. Configuring Security Settings

The Federation service supports TLS to protect traffic between regions. To enable protection, change in the application.yaml file > app section > grpc section > secure parameter to true and put certificates to the tls folder. To simplify configuration, use the hostname instead of the IP address in the region_config table.

Let's consider the example of security configuration:

Generate the CA certificate and key. This should be done once.

sh scripts/tls-generate-ca.sh '*.mydomain.com'
# output is ca.crt and ca.key
# copy ca.crt file to /usr/local/federation/tls/ folder of each region

Generate the Server certificate and key. Perform this operation for each region.

sh scripts/tls-generate-server.sh 'region1.mydomain.com'
# output is server.crt and server.pem
# copy both files to /usr/local/federation/tls/ folder of the region