3. Deployment Instructions

3.1. Deployment Preparation

3.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.

3.1.2 Configuration

Configuration File	Description
./cfg/image-api.values.yaml	A configuration file of Image API instance deployment
./cfg/package.settings.cfg	A configuration file of dependencies for installation of Kubernetes cluster
./cfg/smc.settings.cfg	A configuration file of Kubernetes cluster

1. Open a deployment configuration file ./cfg/smc.settings.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.

2. Open a deployment configuration file ./cfg/image-api.values.yaml in a text editor and set values for the following variables:

• ingress.host is a domain name used in ingress to route requests to Kubernetes services.

IP address for domain name <ingress.host> should be configured at DNS server.

3.1.3 Install Dependencies

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

$ ./cli.sh package install

3.1.4 Upload Images

Upload docker-images image-api to local registry:

$ ./cli.sh image-api load-images

Upload the smc docker images to your local registry:

$ ./cli.sh smc load-images

Uploading can last for about 5 minutes.

3.1.5 Install and Configure a Cluster

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

$ ./cli.sh smc install

This command performs the following actions:

1. Setting of docker and host network
2. Cluster installation
3. Ingress-controller installation
4. Flannel installation

To use GPU, install nvidia-device-plugin using the command below:

$ ./cli.sh smc nvidia install

To use Horizontal Pod Autoscaler, install metric-server:

$ ./cli.sh smc metric-server install

To create image-api secrets in a cluster, run the command below:

$ ./cli.sh image-api install-secrets

3.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

3.2. Deployment

3.2.1 Configuration File Settings (optionally)

Optionally, before installing Image API to a cluster, you can set values for the following fields in the ./cfg/image-api.values.yaml configuration file:

Field Name	Functions
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.
processing.capturer_config	The field value indicates the name of the configuration file of the selected face detector. Image API uses face detectors from 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 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 configuration files, see the 3DiVi Face SDK documentation.
processing.recognizer_config	The field value indicates the name of the face recognizer configuration file. Image API uses a set of recognizers from Face SDK. Each recognizer uses a specific recognition method (algorithm). Generally, Face SDK provides several recognition methods that differ in recognition quality and operating time. For this version of Image API 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 3DiVi Face SDK documentation.
processing.enable_use_avx2	Using the AVX2 instructions allows to speed up the recognizers.
processing.services.[*].use_cuda	The field value indicates the graphics card usage by the service. This option is available for face-detector-template-extractor.
processing.services.[*].replicas	Value of service replicas.
processing.downscale_rawsamples	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.
processing.enable_ingress	This parameter enables proxying to image-api services via ingress.
processing.enable_resource_management	This parameter enables the use of pod resource management in the cluster.
processing.enable_hpa	This parameter enables Horizontal Pod Autoscaler for deployments. Needs metric-server to be installed.
processing.enable_node_selector	This parameter activates the use of designated nodeSelectors in pods. The labels must be assigned to cluster nodes using the command: kubectl label nodes <node_name> type=<type> "type": "processing" - node for calculations "type": "generic" - generic node

3.2.2 Installation

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

$ ./cli.sh image-api install

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-age-estimator-dep-5bf7889dcd-jm46h         1/1     Running        0      1h
image-api-body-detector-dep-6778495696-4zkpm         1/1     Running        0      1h
image-api-emotion-estimator-dep-7c8cdd7c6b-z4vlv     1/1     Running        0      1h
image-api-face-detector-face-fitter-dep-5fb48dcb5…   1/1     Running        0      1h
image-api-gateway-dep-65d4846c59-g2nfj               1/1     Running        0      1h
image-api-gender-estimator-dep-86b9457f9b-2464q      1/1     Running        0      1h
image-api-face-detector-liveness-estimator-dep-7bd…  1/1     Running        0      1h
image-api-mask-estimator-dep-76b958b84b-w7pss        1/1     Running        0      1h
image-api-quality-assessment-estimator-dep-fbf8bc4…  1/1     Running        0      1h
image-api-face-detector-template-extractor-dep-5758… 1/1     Running        0      1h
image-api-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-gateway-dep: reverse proxy, responsible for unified access to processing services;
• image-api-face-detector-face-fitter-dep: face detection and calculation of anthropometric points and head rotation angles (roll, pitch, yaw);
• image-api-body-detector-dep: body detection;
• image-api-emotion-estimator-dep: estimation of emotions;
• image-api-age-estimator-dep: age estimation;
• image-api-gender-estimator-dep: gender estimation;
• image-api-face-detector-liveness-estimator-dep: the service detects faces and checks if a person in the image is real or fake;
• image-api-mask-estimator-dep: the service checks if a person in the image is wearing a medical face mask;
• image-api-quality–assessment-estimator-dep: image quality assessment;
• image-api-verify-matcher-dep: the service compares two biometric templates to verify whether they belong to the same person;
• image-api-template-extractor-dep: the service detects faces and extracts a biometric template from a face image.

3.2.3 Setting Modules

Module is an implementation variant of Image API 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 processing.

To change the module, find a certain service config in processing.services in ./cfg/image-api.values.yaml and change the value for module field.

Example: config of quality-assessment-estimator:

quality-assessment-estimator:
      …………
      module: quality-assessment-estimator
      …………

List of available modules for each Image API service:

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	face-detector-liveness-estimator - standard module 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.
verify-matcher	verify-matcher - standard module
face-detector-template-extractor	face-detector-template-extractor - standard module
quality-assessment-estimator	quality-assessment-estimator - standard module

3.2.4 Scalability

When the load increases, for stable operation of Image API you can manually scale the deployments described in para. 3.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 processing.services in ./cfg/image-api.values.yaml file and restart the deployment using a command below:

$ ./cli.sh image-api install

3.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 ./cfg/smc.settings.cfg and ./cfg/image-api.values.yaml files filled in in para. 3.1.2. 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> <host> with the values of the corresponding variables to the end of this 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.

$ echo "<external_ip_address> <host>" | sudo tee -a /etc/hosts

3.2.6 Testing

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

$ ./cli.sh image-api test - http://<host>

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 ✓

3.2.7 Deletion

To delete Image API, run the command below:

$ ./cli.sh image-api uninstall

3.3 Licensing

3.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.

3.3.2 Update a license

1. Reinstall the secrets.

$ ./cli.sh image-api install-secrets

2. Delete Image API release from the cluster.

$ ./cli.sh image-api uninstall

3. Install Image API release into the cluster.

$ ./cli.sh image-api install