Deployment on Kubernetes

1. Introduction

In the following section we will explain how to install the service in a Kubernetes environment.

2. Manual deployment

2.1 Introduction

The OCR service can be deployed in Kubernetes with kubectl:

kubectl apply -f manifest.yaml

Using a file manifest.yaml similar to this one:

apiVersion: v1
kind: Namespace
metadata:
  name: facephi-ocr-service
---

apiVersion: v1
kind: Secret
metadata:
  name: ocr-license-secret
  namespace: facephi-ocr-service
stringData:
  license.lic: |-
    {
      CONFIG_DIR=<provided by facephi>
      LICENSE_TYPE=<provided by facephi>
      LICENSE_BEHAVIOUR=<provided by facephi>
      LICENSE_ID=<provided by facephi>
      LICENSE_DATA=<provided by facephi>
      LICENSE_KEY=<provided by facephi>
    } 
---

apiVersion: apps/v1
kind: Deployment
metadata:
  name: ocr
  namespace: facephi-ocr-service
spec:
  replicas: 3
  selector:
    matchLabels:
      app: ocr
  template:
    metadata:
      labels:
        app: ocr
    spec:
      volumes:
        - name: license-volume
          secret:
            secretName: ocr-license-secret
            defaultMode: 420
      containers:
        - name: facephi-ocr-service
          image: facephicorp.jfrog.io/docker-pro-fphi/facephi-ocr-service:2.4.6
          imagePullPolicy: IfNotPresent
          ports:
            - containerPort: 6982
          env:
            # Optional JWT protection
            # - name: FACEPHI_OCR_REST_AUTH_ENABLED
            #   value: "true"
            # - name: FACEPHI_OCR_REST_AUTH_JWT_SECRET
            #   valueFrom:
            #     secretKeyRef:
            #       name: ocr-jwt-secret
            #       key: shared-secret
            # - name: FACEPHI_OCR_REST_AUTH_ACCEPT_AUTHORIZATION_HEADER
            #   value: "true"
            # - name: FACEPHI_OCR_REST_AUTH_ACCEPT_API_KEY_HEADER
            #   value: "false"
            # - name: FACEPHI_OCR_REST_AUTH_API_KEY_HEADER_NAME
            #   value: "x-api-key"
          volumeMounts:
            - name: license-volume
              readOnly: true
              mountPath: /service/license/license.lic
              subPath: license.lic
          resources:
            limits:
              cpu: 1024m
              memory: 2Gi
            requests:
              cpu: 512m
              memory: 1Gi
---

apiVersion: v1
kind: Service
metadata:
  name: ocr-service
  namespace: facephi-ocr-service
spec:
  ports:
    - name: http
      protocol: TCP
      port: 80
      targetPort: 6982
  selector:
    app: ocr
  type: ClusterIP
---

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: ocr-ingress
  namespace: facephi-ocr-service
  annotations:
    konghq.com/strip-path: "true"
spec:
  ingressClassName: kong
  rules:
    - host: <your own dns for this service>
      http:
        paths:
          - path: /ocr
            pathType: Prefix
            backend:
              service:
                name: ocr-service
                port:
                  number: 80
---

It is important to have previously logged in to Artifactory or obtain the image facephicorp.jfrog.io/docker-pro-fphi/facephi-ocr-service and store it in a Docker image repository from which the cluster can download it.

2.2 Secret

It is necessary to declare a Kubernetes secret where the license is passed to Kubernetes.

apiVersion: v1
kind: Secret
metadata:
  name: ocr-license-secret
  namespace: facephi-ocr-service
stringData:
  # Write here your license content. E.g:
  license.lic: |-
    {
       "key":"XXXXXX-XXXXXX-XXXXXX-XXXXXX-XXXXXX-XXXXXX",
       "type":"NODE_ONLINE"
    }

2.3 Deployment

Remember to log in to Artifactory or download the Docker image beforehand.

2.3.1 Volumes

It is necessary to add the volume with the client's license. By default, the path where the license file is stored is /service/license.

Once that secret has been created, the deployment will associate the volume at the corresponding path with the following lines:

...
spec:
  ...
  template:
    ...
    spec:
      volumes:
        - name: license-volume
          secret:
            secretName: ocr-license-secret
            defaultMode: 420
        ...
      containers:
        ...
        - volumeMounts:
            - name: license-volume
              readOnly: true
              mountPath: /service/license/license.lic
              subPath: license.lic

spec.volumes[0].secret.secretName searches the namespace for the previously generated secret and stores it in a volume with the name license-volume. When mounting the license-volume the associated Secret is looked up, and mountPath it is set to the path where the file is stored, and you can specify a specific object from the secret with subPath, in this case the key license.

2.3.2 Resources

After numerous load and stress tests, the following results have been obtained to ensure a response time of between 2700 and 3000 ms for identity documents.

Service	CPU	Memory	Average time
/api/v1/process/	512m	1Gi	5.4s
/api/v1/process/	1024m	2Gi	2.9s
/api/v1/process/	2048m	4Gi	2.8s

With these tests, the following configuration is established at the requests and limits level.

spec:
  ...
  template:
    ...
    spec:
      ...
      containers:
        ...
          resources:
            limits:
              cpu: 2048m
              memory: 4Gi
            requests:
              cpu: 1024m
              memory: 2Gi

2.4 Service

When JWT authentication is enabled, GET /api/v1/health and GET /api/v1/version remain public and protected endpoints require a valid JWT. JWT startup settings are not exposed through GET /api/v1/config nor can they be updated through POST /api/v1/config.

2.4.1 LoadBalancer

We note that we will configure a LoadBalancer with Kong in front to access the Facephi OCR Service. Please note that the service is exposed on port 80 and targets the Pod on 6982.

apiVersion: v1
kind: Service
metadata:
  name: ocr-service
  namespace: facephi-ocr-service
spec:
  ports:
    - name: http
      protocol: TCP
      port: 80
      targetPort: 6982
  selector:
    app: ocr
  type: ClusterIP

2.5 Ingress

We configure an Ingress in front to redirect requests from Kong to the service inside the Pod that we previously exposed on port 80.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: ocr-ingress
  namespace: facephi-ocr-service
  annotations:
    konghq.com/strip-path: "true"
spec:
  ingressClassName: kong
  rules:
    - host: <your own dns for this service>
      http:
        paths:
          - path: /ocr
            pathType: Prefix
            backend:
              service:
                name: ocr-service
                port:
                  number: 80

3. Instance types

If the cluster is going to make use of Kubernetes HPA resources to scale the number of pods, it is recommended to take into account the maximum number of pods supported by each instance. The maximum number of pods considered appropriate according to the tests is shown in the following table.

Instance type	CPU	Memory	OCR pod capacity
c5.xlarge	4	8	3
c5.2xlarge	8	16	6
c5.4xlarge	16	32	12

It is possible to add more OCR pods, but at the cost of response time.