2. Deployment Instructions

2.1. Deployment Preparation

2.1.1 Preparation

Replace a license file face_sdk.lic to the setup folder of the unpacked distribution kit. Further commands should be performed relative to the setup directory.

2.1.2 Configuration

The distribution kit contains the following configuration files:

• ./deployment.cfg is a configuration file of Image API instance deployment.
• ./dependencies.cfg is a configuration file of dependencies for installation of Kubernetes cluster.
• ./cluster.cfg is a configuration file of Kubernetes cluster.

Open a deployment configuration file ./cluster.cfg in a text editor and set values for the following variables:

• apiserver_advertise_address is the internal IP address of the machine for deployment.
• external_ip_address is the public IP address of the machine which DNS will be configured to.

Note: if there is no public IP address, use the internal IP address.

Open a deployment configuration file ./deployment.cfg in a text editor and set values for the following variables:

• domain is a domain name.

IP address for domain name <domain> should be configured at DNS server (For more details see section 2.2.5).

2.1.3 Install Dependencies

If the system has no Docker, Kubernetes or Helm, run the command below:

$ ./cli/dependencies/install.sh

2.1.4 Upload Images

Upload docker-images to the local registry:

$ ./cli/load-images.sh

Uploading can last for about 5 minutes.

2.1.5 Install and Configure a Cluster

To create and configure the cluster, run the following command:

$ ./cli/cluster/install.sh

This command initializes a node for cluster deployment, configures the network, installs an ingress-controller and creates Kubernetes secrets.

2.1.6 Cluster Health Check

After initializing the master node, make sure that all nodes are ready for operation. You can check this by running the command below:

$ kubectl get nodes

As a result, the following output will be displayed in the terminal:

NAME          STATUS      ROLES                  AGE     VERSION
master-node   Ready       control-plane,master    1d     v1.23.8

2.2. Deployment

2.2.1 Configuration File Settings (optionally)

Optionally, before installing Image API to a cluster, you can set values for the following fields in the deployment.cfg configuration file:

image_pull_policy: the parameter affects pulling (downloading) container images from registry to deploy an Image API deployment instance. The following field values are available:

• Always - kubelet (node agent in Kubernetes) pulls an image from registry;
• Never - image pulling from registry is not applicable. If the image is already present locally, kubelet attempts to launch a container, otherwise, startup fails;
• IfNotPresent - image is pulled only if it isn’t present locally.

capturer_config: the field value indicates the name of the configuration file of the selected face detector.

Image API uses face detectors from 3DiVi Face SDK - a set of code libraries for development of face recognition solutions. This version of Image API works with two detectors: ULD and REFA. ULD detector allows you to detect faces of different sizes, including masked faces (detection speed is higher than that of REFA). REFA detector provides higher coverage of head rotation angles and maximum quality, including detection of masked faces (detection quality is higher than that of ULD).

The following detector configuration files can be specified as values for the capturer_config field:

• common_capturer_uld_fda.xml (Configuration file for ULD detector)
• common_capturer_refa_fda_a.xml (Configuration file for REFA detector)

For more information about face detector configuration files, see the documentation of 3DiVi Face SDK.

recognizer_config: the field value indicates the name of the face recognizer configuration file.

Image API uses a set of recognizers from 3DiVi Face SDK. Each recognizer uses a specific identification method (algorithm). Generally, 3DiVi Face SDK provides several identification methods that differ in identification quality and operating time.

For Image API 1.0.0, you can specify the following recognizer configuration files:

• method11v1000_recognizer.xml
• method12v30_recognizer.xml
• method12v50_recognizer.xml
• method12v100_recognizer.xml
• method12v1000_recognizer.xml

For more information about recognizers, identification methods and recognizer configuration files, see the documentation of 3DiVi Face SDK.

enable_use_avx2: using the AVX2 instructions allows to speed up the recognizers. To enable/disable AVX2, specify the following values for the field: “1” (enabled) or “0” (disabled).

downscale_rawsamples: field values: “1” (enabled) or “0” (disabled). By default the value is “0”. When field is enabled, each sample is downscaled to the suitable size to reduce memory consumption. However, the system performance decreases. It is recommended to leave this field disabled.

2.2.2 Installation

Launch the script below to install Image API to the cluster:

$ ./cli/deployment/install.sh

Then run the following command to get the deployment status:

$ kubectl get pods

As a result, the console will display a list of pods (deployment instances), their statuses, the number of restarts, and the pod age. The example of console output:

NAME                                                      READY     STATUS     RESTARTS  AGE
image-api-v1-0-0-age-estimator-dep-5bf7889dcd-jm46h         1/1     Running        0      1h
image-api-v1-0-0-body-detector-dep-6778495696-4zkpm         1/1     Running        0      1h
image-api-v1-0-0-emotion-estimator-dep-7c8cdd7c6b-z4vlv     1/1     Running        0      1h
image-api-v1-0-0-face-detector-face-fitter-dep-5fb48dcb5…   1/1     Running        0      1h
image-api-v1-0-0-gateway-dep-65d4846c59-g2nfj               1/1     Running        0      1h
image-api-v1-0-0-gender-estimator-dep-86b9457f9b-2464q      1/1     Running        0      1h
image-api-v1-0-0-face-detector-liveness-estimator-dep-7bd…  1/1     Running        0      1h
image-api-v1-0-0-mask-estimator-dep-76b958b84b-w7pss        1/1     Running        0      1h
image-api-v1-0-0-quality-assessment-estimator-dep-fbf8bc4…  1/1     Running        0      1h
image-api-v1-0-0-face-detector-template-extractor-dep-5758… 1/1     Running        0      1h
image-api-v1-0-0-verify-matcher-dep-6d66dc4948-lx8j7        1/1     Running        0      1h

Note: Status Running for all pods means that all containers are successfully launched.

Overview of the deployments is given below:

• image-api-v1-0-0-gateway-dep: reverse proxy, responsible for unified access to processing services;
• image-api-v1-0-0-face-detector-face-fitter-dep: face detection and calculation of anthropometric points and head rotation angles (roll, pitch, yaw);
• image-api-v1-0-0-body-detector-dep: body detection;
• image-api-v1-0-0-emotion-estimator-dep: estimation of emotions;
• image-api-v1-0-0-age-estimator-dep: age estimation;
• image-api-v1-0-0-gender-estimator-dep: gender estimation;
• image-api-v1-0-0-face-detector-liveness-estimator-dep: the service detects faces and checks if a person in the image is real or fake;
• image-api-v1-0-0-mask-estimator-dep: the service checks if a person in the image is wearing a medical face mask;
• image-api-v1-0-0-quality–assessment-estimator-dep: image quality assessment;
• image-api-v1-0-0-verify-matcher-dep: the service compares two biometric templates to verify whether they belong to the same person;
• image-api-v1-0-0-template-extractor-dep: the service detects faces and extracts a biometric template from a face image.

2.2.3 Setting Modules

Module is an implementation variant of a specific service. For example, face-detector-liveness-estimator has three modules available for selection: liveness-anti-spoofing, quality-liveness-anti-spoofing, face-detector-liveness-estimator. Modules liveness-anti-spoofing and face-detector-liveness-estimator use different liveness algorithms. In quality-liveness-anti-spoofing module, before calculating the liveliness, the image quality is additionally estimated, while the quality threshold (default value is 30) allows excluding images with insufficient quality from the processing pipeline.

To change the module, find a certain service config in setup/chart/processing-services.json and change the value for module field.

Example: config of quality-assessment-estimator:

"quality-assessment-estimator": {
   "replicas": 1,
   "module": "quality-assessment-estimator"
}

The list of available service modules:

• face-detector-face-fitter:
  • face-detector-face-fitter: standard module.
• body-detector:
  • body-detector : standard module.
• age-estimator:
  • age-estimator: standard module.
• emotion-estimator:
  • emotion-estimator: standard module.
• gender-estimator:
  • gender-estimator: standard module.
• mask-estimator:
  • mask-estimator: standard module.
• face-detector-liveness-estimator:
  • liveness-anti-spoofing: module with lower speed but higher accuracy in comparison with a standard module.
  • quality-liveness-anti-spoofing: liveness-anti-spoofing module with additional quality check before calculating liveness.
  • face-detector-liveness-estimator: standard module.
• verify-matcher:
  • verify-matcher: standard module.
• face-detector-template-extractor:
  • face-detector-template-extractor: standard module.
• face-detector-template-extractor:
  • face-detector-template-extractor: standard module.
• quality-assessment-estimator:
  • quality-assessment-estimator: standard module.

Note: quality-liveness-anti-spoofing and liveness-anti-spoofing require the deployment of additional antispoofing pod. Make sure that the pod is included into the pod list with Running status:

NAME                                                          READY   STATUS    RESTARTS    AGE
image-api-v1-1-0-antispoofing-dep-785c4599b7-7tcf2             1/1     Running        0      1h

2.2.4 Scalability

When the load increases, for stable operation of Image API you can manually scale the deployments described in section 2.2.2.

To scale the installed release, run the command below:

$ kubectl scale deployment <deployment_name> --replicas <count>

where <deployment_name> is a deployment name (for example, face-detector-dep), and <count> is a number of deployment replicas (pods).

To save the scaling state, set the value for replicas key in setup/chart/processing-services.json file and restart the deployment using a command below:

$ ./cli/deployment/install.sh

2.2.5 Configure DNS

To allow DNS access, your network server should contain a record that <domain> is available at <external_ip_address>. Variable values can be obtained from the ./dependencies.cfg and ./cluster.cfg files filled in in section 2.1.3. To perform this configuration, contact your network administrator.

For testing you can specify the IP address and domain in the /etc/hosts file on Linux or C:\Windows\System32\drivers\etc\hosts on Windows. To do this, add a new line <external_ip_address> <domain> with the values of the corresponding variables to the end of this file and save the file. Please note that you must have administrator rights to edit the hosts file.

To use Image API at the same machine where it is deployed, you can use a script that will automatically add the necessary record to the /etc/hosts file.

$ ./cli/add-dns.sh

2.2.6 Testing

To make sure that the system works properly, use the command below:

$ ./cli/test.sh

Test output should be the following:

face-detector-face-fitter ✓
age-estimator ✓
emotion-estimator ✓
gender-estimator ✓
face-detector-liveness-estimator ✓
mask-estimator ✓
quality-assessment-estimator ✓
face-detector-template-extractor ✓
body-detector ✓
face-detector-template-extractor ✓
face-detector-template-extractor ✓
verify-matcher ✓

2.2.7 Deletion

To delete Image API, run the command below:

$ ./cli/deployment/delete.sh

2.3 Licensing

2.3.1 Install a license

Unpack Image API distribution kit and move a license file face_sdk.lic (the file is attached to the e-mail) to setup directory.

2.3.2 Update a license

1. Delete an object of secret type, that contains a license file, from Kubernetes cluster.

$ kubectl delete secret face-sdk 

2. Install a secret into the cluster, where ./face_sdk.lic is a path to the license file.

$ face_sdk_lic_path=./face_sdk.lic ./cli/cluster/install/secrets.sh

3. Delete Image API release from the cluster.

$ ./cli/deployment/delete.sh

4. Install Image API release into the cluster.

$ ./cli/deployment/install.sh