Skip to main content

Kubernetes and Helm

The Helm deployment runs one on-prem container per pod. Each pod holds the API, the processing workers, and the runtime models.

For a single host, see Docker Compose instead.

Prerequisites​

  • Kubernetes 1.19 or newer
  • kubectl configured for the target cluster
  • At least one Linux AMD64 worker node
  • Helm 3
  • A license key and application ID
  • The image tag for the release you're deploying

The reference chart is in the on-prem-ops repository:

git clone https://github.com/microblink/on-prem-ops.git

The chart is under deploy/helm/blinkid-verify/.

Inspect and validate it before installing:

helm show values ./deploy/helm/blinkid-verify
helm lint ./deploy/helm/blinkid-verify

Create the license secret​

license-secret.yaml
apiVersion: v1
kind: Secret
metadata:
  name: microblink-license
type: Opaque
stringData:
  LICENSE_KEY: <license-key>
  LICENSE_APPLICATION_ID: <application-id>

Apply it in the namespace where the chart will be installed:

kubectl apply -f license-secret.yaml

Configure the release​

values.yaml
auth:
  license:
    secretName: microblink-license
    createSecret: false

blinkIdVerify:
  replicaCount: 1

  image:
    repository: us-docker.pkg.dev/document-verification-public/on-prem/core
    tag: 4000.0.2

  resources:
    requests:
      cpu: "2"
      memory: 4Gi
    limits:
      cpu: "4"
      memory: 8Gi

  nodeSelector:
    kubernetes.io/arch: amd64

  env:
    DOCVER_WORKFLOW: ExtractAndVerify
    WORKER_COUNT: "2"
    MicroblinkInflightLimit: "2"
    MicroblinkQueueLimit: "1"

Set tag to the version for the release you're deploying. Keep DOCVER_WORKFLOW: ExtractAndVerify unless you're running an extraction-only deployment.

See Environment variables for every supported setting and its default.

The image default for MicroblinkQueueLimit is 0. The chart uses 1 to absorb one short Kubernetes routing burst per pod without creating a large internal backlog.

The chart values also configure the Service, Ingress, probes, scheduling, security contexts, writable temporary volumes, extra environment variables, and additional secret imports.

Security and writable storage​

The chart defaults run the container as non-root UID 65534, with a read-only root filesystem, all Linux capabilities dropped, privilege escalation disabled, and the runtime-default seccomp profile. The pod filesystem group lets that user write to the mounted temporary volumes. Kubernetes API token mounting is disabled, because the product doesn't call the Kubernetes API.

Writable emptyDir volumes are mounted at /tmp and /var/tmp. Optional size limits are available under blinkIdVerify.volumes, and file logging adds a bounded /var/log volume when enabled.

The chart's default pod termination grace period is 30 seconds. Keep it longer than MICROBLINK_SHUTDOWN_GRACE_SECONDS, which defaults to 10 seconds, so the container can stop all managed processes before Kubernetes sends SIGKILL. See Health and shutdown for the container-side behavior.

Install the chart​

helm install microblink-self-hosted ./deploy/helm/blinkid-verify --values values.yaml

Check the release and its pods:

helm status microblink-self-hosted
kubectl get pods --selector app.kubernetes.io/instance=microblink-self-hosted

The chart configures liveness and readiness checks using /health/live and /health/ready.

Access the API​

The chart creates a Service on port 8080. To test it directly:

kubectl port-forward service/microblink-self-hosted-blinkid-verify 8080:8080
curl --fail http://localhost:8080/health/ready

Then send a request:

curl --fail --location --output sample-front.jpg https://storage.googleapis.com/microblink-data-public/microblink-api/test-set/blinkid/SGP_ID_FRONT_new/SGP_ID_FRONT_sample.jpg
curl --fail --location --output sample-back.jpg https://storage.googleapis.com/microblink-data-public/microblink-api/test-set/blinkid/SGP_ID_BACK_new/SGP_ID_BACK_sample.jpg
curl --request POST --form "imageFirstSide=@sample-front.jpg" --form "imageSecondSide=@sample-back.jpg" http://localhost:8080/api/v3/verify

If the release overrides the generated resource names, find the Service by release label:

kubectl get service --selector app.kubernetes.io/instance=microblink-self-hosted

Connect the Service to your existing ingress or gateway when the API must be reachable outside the cluster. The chart can also create an Ingress when its Ingress values are enabled.

Logging​

Standard output and standard error are enabled by default, and should be collected by the cluster logging system.

Set the following only when files under /var/log are also required:

blinkIdVerify:
  logFiles:
    enabled: true

Enabling it mounts another emptyDir. Configure blinkIdVerify.volumes.varLog.sizeLimit to bound local disk use. See Logging for the generated filenames.

Update the release​

Set the intended image tag and apply the updated values:

helm upgrade microblink-self-hosted ./deploy/helm/blinkid-verify --values values.yaml

Review the changelog for configuration or API changes before updating.

To return to the previous revision:

helm history microblink-self-hosted
helm rollback microblink-self-hosted <revision>

Capacity​

Set blinkIdVerify.resources, blinkIdVerify.replicaCount, and WORKER_COUNT using the results of a representative load test. WORKER_COUNT is capacity, not a throughput guarantee: raising it gives each pod more simultaneous processing slots, but every worker also consumes CPU and memory.

Keep MicroblinkQueueLimit small, and add replicas for sustained load.

Last updated on