Deployment with Helm

This article describes how to install Smart ID Certificate Manager (CM) server components on Kubernetes using Helm and Helm charts.

Prerequisites

• Kubernetes version 1.33.8 or later.

• A supported database server must be installed/available. Access to the database itself and the type of deployment of the database is not part of the scope of this guide.

• License file must be available.

• Helm version 3.6.2 or later.

• Kubectl version 1.33.8 or later.

• Any supported Podman or Docker version, or other container image build tool, such as Buildah.

• Administrator's Workbench, Registration Authority, and Certificate Controller clients from CM distributable package.

• A Kubernetes namespace for the deployment exists and access to it is available, with both kubectl and helm commands configured to use it as the current namespace.

Differences between CM classic and Kubernetes deployments

There are some differences in how CM operates in Kubernetes when compared to a classic installation:

• CF shall run CIS internally, external CIS configuration is not supported.

• CIS will always write audit logs to the database unless disabled in cis.conf, file logging is not supported.

CM installation steps

These steps will instruct on how to set up a minimal Certificate Manager server deployment.

CM image archive files

The container images of Certificate Manager are stored in the images directory under the distributable. These image files may be uploaded to a local private container registry with controlled and limited access so that they can be reached by the target Kubernetes system. The images shall under no circumstances be distributed to any public container registry.

The images can be read with below commands.

Example using docker:

docker image load --input images/cf-server-image-<version>.tar
docker image load --input images/pgw-image-<version>.tar

Example using podman:

podman image load --input images/cf-server-image-<version>.tar
podman image load --input images/pgw-image-<version>.tar

Example using buildah:

buildah pull docker-archive:images/cf-server-image-<version>.tar
buildah pull docker-archive:images/pgw-image-<version>.tar

If images are stored in private container registries they could be pulled by updating the configuration file values.yaml:

# the image and tag references for the CF image. The image is required to be
# stored in a registry.
image:
  repository: <registry-url>/x-repo
  tag: <version-tag>
  pullPolicy: IfNotPresent

CM Helm charts

The distributable contains a helm directory where the Helm charts are stored. It contains the following charts:

• cf

• cf-example

• pgw

• pgw-example

The cf and pgw charts are the base charts. These charts contain the base templates for Certificate Manager and Protocol Gateway application deployment, but do not contain any configuration.

The cf-example and pgw-example charts are the parent charts. The parent charts are example charts with configuration for an initial example deployment, and can be renamed and modified by the customer as needed, with customer specific configuration, trust stores and key stores.

The cf-example and pgw-example charts have explicit dependencies to the cf and pgw base charts in their Chart.yaml files. The path to the base charts must match where the charts are stored on the file system.

Copy all these charts to a suitable location in a host which can reach the targeted Kubernetes-based system.

Once the charts are extracted from the deliverable, the initial configuration can be added to the parent charts.

Configuring CM

Once extracted from the deliverable, the cf-example chart will contain configuration files and certificates with initial configuration, for example:

├── Chart.yaml
├── files
│   ├── config
│   │   ├── cis.conf
│   │   ├── cm.conf
        ...etc.

│   ├── inputviews
│   │   ├── ac-iv.conf
│   │   ├── acme-account-reg-search.conf
│   │   ├── acme-prereg-search.conf
        ...etc.

│   ├── keystore
│   ├── license
│   ├── pinprocedures
│   │   ├── generate_puk.conf
        ...etc.

│   └── truststore
        ...etc.

Any configuration files below the subdirectories of the files directories may be customized or added, and any required key stores, trust stores and license files may be added to the above directories before deployment.

CM license file

Place the CM license files under the license folder cf-example/files/license.

Certificate Manager server will read from this directory to find all the licenses necessary for Certificate Manager operation.

CM database installation

Before continuing with the CM deployment on Kubernetes, follow the steps for the corresponding supported database from one of the following pages:

• MS SQL Server/Azure SQL

• Oracle database

• PostgreSQL

• MySQL

• MariaDB

Add the CM database connection

To add the CMDB connection to the CM configuration, a JDBC connection must be added. This is done by setting the appropriate values in values.yaml in the cf-example chart, for example:

• Change the Default Password

config:
  database:
    name: "jdbc:postgresql://cmdb:5432/cmdb"
    user: "lcmreq"
    password: "********"
    connections: "20"

Connection string examples for the supported databases:

jdbc:oracle:thin:@//<host>:<port/CMDB
jdbc:postgresql://<host>:<port>/cmdb
jdbc:sqlserver://<host>:<port>;databaseName=CMDB;encrypt=false;trustServerCertificate=true;useBulkCopyForBatchInsert=true
jdbc:mysql://<host>:<port>/CMDB?permitMysqlScheme=true&allowPublicKeyRetrieval=true&sessionVariables=transaction_isolation='READ-COMMITTED'
jdbc:mariadb://<host>:<port/CMDB?sessionVariables=tx_isolation='READ-COMMITTED'

Set CM deployment parameters

The values.yaml file inside the cf-example chart allows setting CM deployment parameters, such as how many CM instances (or Pods) of the CM application should run and how much memory and CPU resources each Pod should have.

Verify the values.yaml file in cf-example for correct parameters

• Database connection

• Image repository and tag

• Port and Persistent Volume

For more information, see the official Kubernetes documentation on resource management.

Some of the CM configuration parameters are available in values.yaml in the cf-example chart. Since the Helm templates will override these values in cm.conf, as a consequence they cannot be configured in cm.conf.

See the config section in values.yaml for a description.

PersistentVolumeClaim storage class

To be able to successfully deploy the cf-example chart, the storage class name of the mainpvc must refer to a CSI driver storage class which supports the ReadWriteMany access mode. Different Kubernetes service providers use different CSI drivers, and therefore the storage class names are almost always different and specific to each provider.

To set the storage class correctly to one used by your provider, set the following parameter in the cf-example chart values.yaml:

  pvc:
    cf:
      storageClassName: <enter-name-of-csi-storage-class-here>
      size: 200Mi
    cis:
      storageClassName: <enter-name-of-csi-storage-class-here>

Perform the CM initial deployment

Once all configuration is added to the cf-example chart it can be deployed. The cf-example chart will need to build the dependencies (the base chart) which should be located in the same parent directory where the cf-example chart is stored.

From within cf-example chart directory, run the below command:

helm dependency build

Deploy the CF chart

Now the chart is ready to be deployed. Make sure that a Kubernetes namespace is available or has been created, and that Helm can access this namespace. Change the placeholder name <your-namespace> with the name of your namespace in all commands from here onwards.

From within cf-example chart directory, run the below command:

helm install -n <your-namespace> cm .

Now the CM server application should be deploying in the Kubernetes namespace.

Use kubectl or other monitoring tools to monitor the status of the deployment, example for kubectl below:

kubectl get all -n <your-namespace>
kubectl describe statefulset/cm-cf -n <your-namespace>

If the above commands are showing errors or the pods are not becoming ready, check the CF logs in the pods with the below command:

kubectl logs <cf-pod> -n <your-namespace>

Post-configuration for CM

Accessing the CM containers using the CM clients

At this point the Certificate Manager server is ready to accept connections. To reach it, port 5009 from the cm service needs to be forwarded from the Kubernetes cluster.

To forward the port 5009, simply run the below command in a shell:

kubectl port-forward service/cm-cf 5009:5009

It is now possible to connect using Administrator's Workbench, Certificate Controller and Registration Agent clients. These clients can be installed from the CM distributable zip package.

Upgrade to apply changes

To update the image tag or configuration files, modify the Helm deployment files in cf-example as needed, then run the following command inside the cf-example directory to update the running deployment's configuration:

helm upgrade -n <your-namespace> cm .

After upgrade, wait for all pods to be in ready state and ensure that there are no errors by monitoring the logs of the pods:

kubectl logs <cf-pod> -n <your-namespace>

Protocol Gateway installation steps

Configuring the Protocol Gateway container

The pgw-example chart contains configuration files with an initial configuration, for example:

├── Chart.yaml
├── files
│   ├── certdir
│   │   ├── bootca.cer
│   │   └── trusted.jks
│   ├── conf
│   │   ├── CoapEstProxyMapping.properties
│   │   ├── acme.properties
│   │   ├── api.properties
│   │   ├── auth.properties
│   │   ├── boot_vro.p12
│   │   ├── c2x.properties
│   │   ├── cm-gateway.properties
        ...etc.
        
│   └── tomcat
│       ├── context.xml
│       ├── server.xml
│       ├── tomcat-users.xml
│       └── web.xml
        ...etc.

The Protocol Gateway deployment, here named pgw, is based on an Apache Tomcat version 10 image and contains a configuration for a minimal deployment.

The boot_vro.p12 token is included and preconfigured in cm-gateway.properties.

There is also an initial trust store file trusted.jks in the certdir directory, which is referred to from server.xml. It is delivered containing only the CM boot CA root certificate.

The configuration can be changed here in the pgw-example chart files to suit the desired use cases, as the Protocol Gateway servlets are deployed but none of them are started by default.

The readiness and liveness probes are by default configured to probe against HTTP port 8080.

Set Protocol Gateway deployment parameters

The values.yaml file inside the pgw-example chart allows setting deployment time parameters, such as how many PGW instances (or Pods) of the Protocol Gateway application should run and how much memory and CPU resources each Pod should have.

Ensure that the values.yaml file in pgw-example contains the correct parameters:

• cmhost: service host name of the CF deployment

• Image repository and tag

• Port and Persistent Volume

For more information, see the official Kubernetes documentation on resource management.

Perform the initial Protocol Gateway deployment

Once the configuration has been edited the Protocol Gateway application can be started.

From within pgw-example chart directory, run the below command:

helm install -n <your-namespace> pgw .

This is the required minimum configuration for setting up the Protocol Gateway. Additional configurations, such as configuration and HSM/other libraries for example, may be added if so required.

If the pods are showing errors or are not becoming ready, check the PGW logs in the pods with the below command:

kubectl logs <pgw-pod> -n <your-namespace>

Post-configuration of the Protocol Gateway deployment

Upgrade to apply changes

To update the image tag or configuration files, such as enabling additional protocols, modify the files in pgw-example as needed. Then run the following command from within the pgw-example directory to update running Protocol Gateway deployment:

helm upgrade -n <your-namespace> pgw .

After upgrade, wait for all pods to be in ready state and ensure that there are no errors by monitoring the logs of the pods:

kubectl logs <cf-pod> -n <your-namespace>

Accessing the PGW protocol interfaces

To access the Protocol Gateway ports for testing, forward them by running the below command in a shell:

kubectl port-forward service/pgw 8080:8080 8443:8443 8444:8444

Connecting to the Certificate Manager and Protocol Gateway applications running on Kubernetes

Setting up external connectivity to the CM and PGW cluster-internal services is not done in the example charts in order to not expose the services to internet. The type of connectivity to configure depends on the use case.

Refer to Kubernetes documentation related to services, load balancing and networking for more information.

Last updated: August 13, 2026