Deployment in Kubernetes

1. Introduction

Below, we specify everything needed to install Facephi Voice Service in a Kubernetes environment.

2. Manual deployment

2.1 Introduction

The Phivox 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-voice-service
---

apiVersion: v1
kind: Secret
metadata:
  name: voice-license-secret
  namespace: facephi-voice-service
stringData:
  stringData:
  config.cfg: |-
    {
      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: voice-service-deployment
  namespace: facephi-voice-service
spec:
  selector:
    matchLabels:
      name: facephi-voice-service
  template:
    metadata:
      labels:
        name: facephi-voice-service
    spec:
      volumes:
        - name: config-volume
          secret:
            secretName: voice-license-secret
            defaultMode: 420
      containers:
        - name: facephi-voice-service-container-name
          # Use the name and Version of your image
          image: >-
            facephicorp.jfrog.io/docker-pro-fphi/facephi-voice-service:$VERSION
          env:
            # Optional JWT protection
            # - name: FACEPHI_VOICE_REST_AUTH_ENABLED
            #   value: "true"
            # - name: FACEPHI_VOICE_REST_AUTH_JWT_SECRET
            #   value: "shared-secret"
            # - name: FACEPHI_VOICE_REST_AUTH_ACCEPT_AUTHORIZATION_HEADER
            #   value: "true"
            # - name: FACEPHI_VOICE_REST_AUTH_ACCEPT_API_KEY_HEADER
            #   value: "true"
            # - name: FACEPHI_VOICE_REST_AUTH_API_KEY_HEADER_NAME
            #   value: "x-api-key"
          ports:
            - name: http
              containerPort: 6982
              protocol: TCP
          resources:
            limits:
              cpu: '8'
              memory: 8Gi
            requests:
              cpu: 500m
              memory: 3Gi
          volumeMounts:
            - name: config-volume
              readOnly: true
              mountPath: /service/config/config.cfg
              subPath: config.cfg
          livenessProbe:
            httpGet:
              path: /api/v1/health
              port: 6982
              scheme: HTTP
            initialDelaySeconds: 10
            timeoutSeconds: 5
            periodSeconds: 10
            successThreshold: 1
            failureThreshold: 3
          readinessProbe:
            httpGet:
              path: /api/v1/health
              port: 6982
              scheme: HTTP
            initialDelaySeconds: 15
            timeoutSeconds: 5
            periodSeconds: 10
            successThreshold: 1
            failureThreshold: 3
          terminationMessagePath: /dev/termination-log
          terminationMessagePolicy: File
          imagePullPolicy: IfNotPresent
      restartPolicy: Always
      terminationGracePeriodSeconds: 60
---

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

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: voice-ingress
  namespace: facephi-voice-service
spec:
  ingressClassName: kong
  rules:
    - http:
        paths:
          - path: /api(/v1)?/(.*)
            pathType: Prefix
            backend:
              service:
                name: voice-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-voice-service and store it in a Docker image repository from which the cluster can download it.

2.2 Volumes

You must add the volume with the configuration file so that the service works correctly; this configuration file contains the license information and the service configuration. By default, the path where the configuration file is stored is /service/config/config.cfg.

apiVersion: v1
kind: Secret
metadata:
  name: config-secret
  namespace: facephi-voice-service
stringData:
  config.cfg: |-
    {
      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>
    }

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: config-volume
          secret:
            secretName: config-secret
            defaultMode: 420
        ...
      containers:
        ...
        - volumeMounts:
            - name: config-volume
              readOnly: true
              mountPath: /service/config/config.cfg
              subPath: config.cfg

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

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

2.3 Resources

After running the performance tests, the following results were obtained:

• For Enrollment with three audio files (/api/v1/enrollment/):

CPU	Memory	Average time
4096m	10Gi	2511 ms
8192m	10Gi	1407 ms

• For Authentication (/api/v1/authentication/):

CPU	Memory	Average time
4096m	10Gi	240 ms
8192m	10Gi	220 ms

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

spec:
  ...
  template:
    ...
    spec:
      ...
      containers:
        ...
        - resources
            limits:
              cpu: 4096m  # 4 cores
              memory: 8Gi
            requests:
              cpu: 500m # 0.5 cores
              memory: 3Gi

2.4 Service

2.4.1 LoadBalancer

Keep in mind that we will configure a LoadBalancer with Kong in front to access Facephi Voice Service. Note that the service is exposed on port 80 and points to the Pod on port 6982.

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

2.5 Ingress

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

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: facephi-voice-service
  namespace: facephi-voice-service
spec:
  ingressClassName: kong
  rules:
    - http:
        paths:
          - path: /api(/v1)?/(.*)
            pathType: Prefix
            backend:
              service:
                name: facephi-voice-service
                port:
                  number: 80

3 Instance Types

The recommended instance types for using Facephi Voice Service in production would be the following, where the Facephi Voice Service Pods that fit are shown according to the instance type used.

Instance type	CPU	Memory	Service Pod capacity
c5.xlarge	4	8	2
c5.2xlarge	8	16	4
c5.4xlarge	16	32	9