Implantação no Kubernetes

1. Introdução

Na seção seguinte, explicaremos como instalar o serviço em um ambiente Kubernetes.

2. Implantação manual

2.1 Introdução

O serviço OCR pode ser implantado no Kubernetes com kubectl:

kubectl apply -f manifest.yaml

Usando um arquivo manifest.yaml semelhante a este:

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:
            # Proteção JWT opcional
            # - 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
---

É importante ter feito login previamente no Artifactory ou obter a imagem facephicorp.jfrog.io/docker-pro-fphi/facephi-ocr-service e armazená-la em um repositório de imagens Docker a partir do qual o cluster possa baixá-la.

2.2 Secret

É necessário declarar um secret do Kubernetes onde a licença é passada para o Kubernetes.

apiVersion: v1
kind: Secret
metadata:
  name: ocr-license-secret
  namespace: facephi-ocr-service
stringData:
  # Escreva aqui o conteúdo da sua licença. Ex.:
  license.lic: |-
    {
       "key":"XXXXXX-XXXXXX-XXXXXX-XXXXXX-XXXXXX-XXXXXX",
       "type":"NODE_ONLINE"
    }

2.3 Deployment

Lembre-se de fazer login no Artifactory ou baixar previamente a imagem Docker.

2.3.1 Volumes

É necessário adicionar o volume com a licença do cliente. Por padrão, o caminho onde o arquivo de licença é armazenado é /service/license.

Depois que esse secret for criado, o deployment associará o volume no caminho correspondente com as seguintes linhas:

...
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 busca no namespace o secret gerado previamente e o armazena em um volume com o nome license-volume. Ao montar o volume license-volume o Secret associado é buscado, e mountPath é definido no caminho onde o arquivo é armazenado, podendo especificar um objeto específico do secret com subPath, neste caso a chave license.

2.3.2 Recursos

Após numerosos testes de carga e estresse, foram obtidos os seguintes resultados para garantir um tempo de resposta entre 2700 e 3000 ms para documentos de identidade.

Serviço	CPU	Memória	Tempo médio
/api/v1/process/	512m	1Gi	5.4s
/api/v1/process/	1024m	2Gi	2.9s
/api/v1/process/	2048m	4Gi	2.8s

Com estes testes, estabelece-se a seguinte configuração em nível de requests e limits.

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

2.4 Service

Quando a autenticação JWT está habilitada, GET /api/v1/health e GET /api/v1/version permanecem públicos e os endpoints protegidos exigem um JWT válido. As configurações de inicialização do JWT não são expostas por meio de GET /api/v1/config nem podem ser atualizadas por meio de POST /api/v1/config.

2.4.1 LoadBalancer

Levamos em conta que configuraremos um LoadBalancer com Kong à frente para acessar o serviço Facephi OCR Service. Observe que o serviço é exposto na porta 80 e ataca o Pod na 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

Configuramos um Ingress à frente para redirecionar as requisições do Kong para o serviço dentro do Pod que expusemos anteriormente na porta 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. Tipos de instâncias

Se o cluster for usar recursos HPA do Kubernetes para escalar o número de pods, recomenda-se levar em conta o número máximo de pods suportado por cada instância. O número máximo de pods considerado adequado segundo os testes é mostrado na tabela a seguir.

Tipo de instância	CPU	Memória	Capacidade de pods OCR
c5.xlarge	4	8	3
c5.2xlarge	8	16	6
c5.4xlarge	16	32	12

É possível adicionar mais pods de OCR, mas sacrificando o tempo de resposta.