Kubernetes Deployment Guide

CERTInext OnPremise v2.8 - Kubernetes Deployment Guide

Product: CERTInext Certificate Lifecycle Management Version: 2.8 (OnPremise) Deployment: Kubernetes (kubeadm + containerd) Date: February 2026

---

Table of Contents

• Introduction

• Architecture Overview

• Prerequisites

• Database Setup

• Property Files

• Docker Images

• Kubernetes Secrets

• Application Deployment

• Post-Deployment Configuration

• Verification & Health Checks

• Troubleshooting

• Appendices

---

1. Introduction

This document describes how to deploy CERTInext OnPremise v2.8 on a Kubernetes cluster using pre-built Docker images. It covers infrastructure prerequisites, database setup, application configuration, deployment procedures, and post-deployment validation.

---

2. Architecture Overview

CERTInext consists of four microservices with distinct roles and database requirements:

Service	Image	Role	Database
CERTInext Backend API	certinextbackendapiv2.8	Core business logic, certificate operations	certinext
CERTInext	certinextv2.8	Main portal - UI, OAuth2 login	certinext_discovery
CERTInext Backoffice	certinextbackofficev2.8	Admin panel for internal management	certinext
CERTInext Discovery API	certinextdiscoveryapiv2.8	Certificate discovery, bot management	certinext_discovery

Deployment Order

The CERTInext Backend API must be deployed and healthy before other services:

1. CERTInext Backend API (first) - other services depend on it

2. CERTInext (second) - calls Backend API during startup

3. Backoffice and Discovery API (third) - can be deployed in parallel

---

3. Prerequisites

3.1 Kubernetes Cluster

• Kubernetes cluster installed using kubeadm

• containerd configured as the container runtime

• Control plane and worker nodes joined and in Ready state

• CNI plugin installed (Calico recommended)

Verify cluster readiness:

kubectl get nodes -o wide
kubectl get pods -A

3.2 MetalLB Load Balancer

On-premise clusters need MetalLB to provide load balancing capability.

• Layer2 mode with dedicated IP address pool

• Assigns external IPs to LoadBalancer type services

Verify MetalLB:

kubectl -n metallb-system get pods
kubectl get svc -A | grep LoadBalancer

3.3 NGINX Ingress Controller

• NGINX Ingress Controller deployed and exposed via MetalLB

• Provides host-based routing, TLS termination, centralized traffic management

Verify Ingress Controller:

kubectl -n ingress-nginx get pods
kubectl -n ingress-nginx get svc

3.4 DNS Entries

Each CERTInext service requires a DNS record pointing to the Ingress Controller external IP.

Service	Example Hostname
CERTInext Backend API	api.certinext.example.com
CERTInext	certinext.example.com
CERTInext Backoffice	bo.certinext.example.com
CERTInext Discovery API	discovery.certinext.example.com

Replace example.com with your organization's domain.

3.5 TLS Certificates

• Wildcard certificate (*.certinext.example.com) or per-service certificates

• Certificate and private key files available on Kubernetes nodes

3.6 External MySQL 8.0

• MySQL 8.0 server accessible from all worker nodes

• Character set: utf8mb4

• Collation: utf8mb4_0900_ai_ci

• ONLY_FULL_GROUP_BY mode disabled

---

4. Database Setup (External MySQL)

4.1 Create MySQL User

CREATE USER 'certinext_app'@'%' IDENTIFIED BY '<STRONG_PASSWORD>';

Replace <STRONG_PASSWORD> with a secure password.

4.2 Create Databases

CREATE DATABASE IF NOT EXISTS `certinext`
DEFAULT CHARACTER SET utf8mb4
COLLATE utf8mb4_0900_ai_ci;

CREATE DATABASE IF NOT EXISTS `certinext_discovery`
DEFAULT CHARACTER SET utf8mb4
COLLATE utf8mb4_0900_ai_ci;

4.3 Grant Permissions

GRANT ALL PRIVILEGES ON `certinext`.* TO 'certinext_app'@'%';
GRANT ALL PRIVILEGES ON `certinext_discovery`.* TO 'certinext_app'@'%';
FLUSH PRIVILEGES;

4.4 Execute SQL Scripts

Three SQL scripts must be executed in strict order:

Order	Script	Database	Purpose
1	01_CERTInext_Database_Setup.sql	certinext	Creates tables and seed data
2	02_CERTInextDiscovery_Database_Setup.sql	certinext_discovery	Creates discovery database
3	03_CERTInext_Post_Deployment_Configuration.sql	both	Environment-specific configuration

Execute in order:

mysql -h <MYSQL_HOST> -u certinext_app -p < "01_CERTInext_Database_Setup.sql"
mysql -h <MYSQL_HOST> -u certinext_app -p < "02_CERTInextDiscovery_Database_Setup.sql"
mysql -h <MYSQL_HOST> -u certinext_app -p < "03_CERTInext_Post_Deployment_Configuration.sql"

4.5 Disable ONLY_FULL_GROUP_BY

CERTInext requires ONLY_FULL_GROUP_BY to be disabled. Add to MySQL configuration:

[mysqld]
sql_mode = "STRICT_TRANS_TABLES,NO_ZERO_IN_DATE,NO_ZERO_DATE,ERROR_FOR_DIVISION_BY_ZERO,NO_ENGINE_SUBSTITUTION"

Then restart MySQL or apply dynamically:

SET GLOBAL sql_mode = 'STRICT_TRANS_TABLES,NO_ZERO_IN_DATE,NO_ZERO_DATE,ERROR_FOR_DIVISION_BY_ZERO,NO_ENGINE_SUBSTITUTION';

---

5. Prepare Property Files

Each service requires a property file with database connection details and configuration.

5.1 CERTInext Backend API Configuration

MYSQL_DB_USERNAME=<ENCRYPTED_USERNAME>
MYSQL_DB_PASSWORD=<ENCRYPTED_PASSWORD>
MYSQL_DB_HOST=<MYSQL_HOST>
MYSQL_DB_PORT=3306
MYSQL_DB_NAME=certinext
LOGFOLDER=/data/certinext-backend-api/Logs/
FILE_DIRECTORY=/data/certinext-backend-api/Temp/
ONPREM=1

5.2 CERTInext - certHub.properties

WRAPPER_API_URL=http://certinext-backend-api/
WRAPPER_API_APPCODE=emSign@123
WRAPPER_API_AUTHKEY=emSign@123
MYSQL_DB_USERNAME=<ENCRYPTED_USERNAME>
MYSQL_DB_PASSWORD=<ENCRYPTED_PASSWORD>
MYSQL_DB_HOST=<MYSQL_HOST>
MYSQL_DB_PORT=3306
MYSQL_DB_NAME=certinext_discovery
FILE_DIRECTORY=/data/certinext-hub/Temp/
LOGFOLDER=/data/certinext-hub/Logs/
ONPREM=1

5.3 CERTInext Backoffice - DB.properties

MYSQL_DB_USERNAME=<ENCRYPTED_USERNAME>
MYSQL_DB_PASSWORD=<ENCRYPTED_PASSWORD>
MYSQL_DB_HOST=<MYSQL_HOST>
MYSQL_DB_PORT=3306
MYSQL_DB_NAME=certinext
LOGFOLDER=/data/certinext-backoffice/Logs/
FILE_DIRECTORY=/data/certinext-backoffice/Temp/
ONPREM=1

5.4 CERTInext Discovery API - DB.properties

MYSQL_DB_USERNAME=<ENCRYPTED_USERNAME>
MYSQL_DB_PASSWORD=<ENCRYPTED_PASSWORD>
MYSQL_DB_HOST=<MYSQL_HOST>
MYSQL_DB_PORT=3306
MYSQL_DB_NAME=certinext_discovery
WRAPPER_API_URL=http://certinext-backend-api/
WRAPPER_API_APPCODE=emSign@123
WRAPPER_API_AUTHKEY=emSign@123
FILE_DIRECTORY=/data/certinext-discovery-api/Temp/
LOGFOLDER=/data/certinext-discovery-api/Logs/
ONPREM=1

Key Configuration Notes

• ONPREM=1 must be set on all four services

• Database credentials must be encrypted using Base64 wrapping

• File directories must point to container-internal writable paths

• Service URLs use internal Kubernetes DNS names

---

6. Import Docker Images

Docker images must be imported into containerd on every worker node. These are not pulled from a registry.

6.1 Copy Image Files to Worker Nodes

scp DockerImages/*.tar <user>@<worker-node>:/tmp/certinext-images/

6.2 Import Images on Each Worker Node

ctr -n k8s.io images import /tmp/certinext-images/certinextbackendapiv2.8.tar
ctr -n k8s.io images import /tmp/certinext-images/certinextv2.8.tar
ctr -n k8s.io images import /tmp/certinext-images/certinextbackofficev2.8.tar
ctr -n k8s.io images import /tmp/certinext-images/certinextdiscoveryapiv2.8.tar

6.3 Verify Imported Images

ctr -n k8s.io images ls | grep certinext

---

7. Namespace Strategy

Option A - Single Shared Namespace (Recommended)

A single certinext namespace is recommended for on-premise deployments. It simplifies service communication and secret management.

kubectl create namespace certinext

Option B - Separate Namespaces Per Service

For stricter isolation, create separate namespaces. Service URLs require fully qualified names:

kubectl create namespace certinext-backend-api
kubectl create namespace certinext-hub
kubectl create namespace certinext-backoffice
kubectl create namespace certinext-discovery-api

---

8. Create Kubernetes Secrets

8.1 TLS Certificate Secret

kubectl -n certinext create secret tls certinext-tls \
  --cert=/path/to/certificate.crt \
  --key=/path/to/private.key

8.2 Database Property Secrets

Create a secret for each service from its property file:

kubectl -n certinext create secret generic certinext-backend-api-db \
  --from-file=db.properties=/path/to/db.properties

kubectl -n certinext create secret generic certinext-hub-db \
  --from-file=certHub.properties=/path/to/certHub.properties

kubectl -n certinext create secret generic certinext-backoffice-db \
  --from-file=DB.properties=/path/to/backoffice-DB.properties

kubectl -n certinext create secret generic certinext-discovery-api-db \
  --from-file=DB.properties=/path/to/discoveryapi-DB.properties

---

9. Deploy Applications

YAML manifests are in Deployment/yaml/. Each contains a Deployment, Service, and Ingress.

Deployment Order

• Backend API must be healthy before other services

• CERTInext depends on Backend API

• Backoffice and Discovery API can deploy in parallel

Step 1: Deploy Backend API

kubectl apply -f Deployment/yaml/certinext-backend-api.yaml
kubectl -n certinext rollout status deploy/certinext-backend-api

Step 2: Deploy CERTInext

kubectl apply -f Deployment/yaml/certinext-hub.yaml

Step 3: Deploy Backoffice and Discovery API

kubectl apply -f Deployment/yaml/certinext-backoffice.yaml
kubectl apply -f Deployment/yaml/certinext-discovery-api.yaml

---

10. Post-Deployment Configuration

10.1 Update Database Settings

USE certinext;
UPDATE mas_hub_wrapper_creds SET apiBaseURL = 'https://certinext.example.com' WHERE ID = 1;

---

11. Verification & Health Checks

11.1 Check Pod Status

kubectl -n certinext get pods -o wide

All pods should show Running with 1/1 Ready.

11.2 Review Application Logs

kubectl -n certinext logs deploy/certinext-backend-api --tail=200

Look for successful database connections and Spring Boot startup messages.

11.3 HTTP Health Checks

curl -k https://api.certinext.example.com/
curl -k https://certinext.example.com/
curl -k https://bo.certinext.example.com/
curl -k https://discovery.certinext.example.com/

---

12. Troubleshooting

Pod in CrashLoopBackOff

Symptoms: Pod continuously restarts.

Resolution:

• Check pod logs for error messages

• Verify property file secret is mounted correctly

• Verify database is reachable from pod network

Backend API Not Reachable

Symptoms: Connection errors to WRAPPER_API_URL.

Resolution:

• Verify Backend API pod is Running

• Test DNS from within cluster

• Verify WRAPPER_API_URL in config files

Database Connection Failures

Symptoms: Connection link failures or access denied errors.

Resolution:

• Verify MySQL accessibility from worker nodes

• Verify secret contents and encryption

• Check MySQL user grants

Image Pull Errors

Symptoms: Pod stuck in ErrImagePull.

Resolution:

• Verify images imported on scheduled worker node

• Confirm imagePullPolicy is IfNotPresent

• Import images on all worker nodes

---

Appendix A: YAML Manifest Summary

YAML File	Resources	Service Port	Ingress Host
certinext-backend-api.yaml	Deployment + Service + Ingress	80 → 8080	api.certinext.example.com
certinext-hub.yaml	Deployment + Service + Ingress	80 → 8080	certinext.example.com
certinext-backoffice.yaml	Deployment + Service + Ingress	80 → 8080	bo.certinext.example.com
certinext-discovery-api.yaml	Deployment + Service + Ingress	80 → 8080	discovery.certinext.example.com

Common Deployment Patterns

• Init container creates log and temp directories

• imagePullPolicy set to IfNotPresent for offline environments

• Readiness probe: HTTP GET / with 30s initial delay

• Liveness probe: HTTP GET / with 60s initial delay

• Volumes: Secrets for config, hostPath for logs and temp

• Ingress: NGINX with TLS termination enabled

Quick Reference Checklist

• Verify Kubernetes cluster meets all prerequisites

• Set up external MySQL database

• Prepare and encrypt property files

• Import Docker images on all worker nodes

• Create Kubernetes namespace and secrets

• Deploy services in correct order

• Run post-deployment configuration

• Execute health checks and verification

---

Document Version: 2.8.1 Last Updated: February 2026