Implementing TLS certificates v1.4.2 (LTS)

Certificate architecture overview

Hybrid Manager (HM) uses TLS certificates to secure the portal, internal service communication, and database connections. By default, the system generates self-signed certificates at install time. You can replace these with your own certificates, use a cert-manager issuer, or bring your own private Certificate Authority (CA).

cert-manager is a core dependency of HM. It manages the lifecycle of TLS certificates across the platform.

Prerequisite for Helm installs on OpenShift

On OpenShift, cert-manager must be pre-installed before running the HM Helm installation.

On other platforms (EKS, AKS, GKE, RKE2), the bootstrap process installs cert-manager automatically as part of the upm-cert-manager component.

Set up a custom x.509 certificate for the Hybrid Manager Portal

You can change the self-signed x.509 certificate used by the Hybrid Manager (HM) Portal with your own.

To import your own certificate you need to create a Kubernetes secret containing the server certificate and the private key.

Generate the certificate

Generate the base64 encoded string of your certificate (example: my-certificate.crt) and private key (example: my-certificate.key).

cat my-certificate.crt | base64
cat my-certificate.key | base64

Create the yaml file

Create a file (example: my-secret.yaml) with the following content and replace <base64 encoded string> with the values generated in the previous step.

apiVersion: v1
data:
  tls.crt: <base64 encoded string>
  tls.key: <base64 encoded string>
kind: Secret
metadata:
  name: my-portal-certificate
  namespace: default
  annotations:
    replicator.v1.mittwald.de/replicate-to: 'istio-system'
type: kubernetes.io/tls

Apply the secret in your Kubernetes cluster

kubectl apply -n default -f ./my-secret.yaml

Configure HM to use the new certificate

Edit your HybridControlPlane CR to add the portal_certificate_secret parameter under spec.globalParameters:

apiVersion: edbpgai.edb.com/v1alpha1
kind: HybridControlPlane
metadata:
  name: edbpgai
spec:
  globalParameters:
    portal_certificate_secret: "my-portal-certificate"
    # ... your other globalParameters

Apply the updated CR:

kubectl apply -f hybridmanager.yaml

The operator reconciles the change and updates the portal certificate configuration.

For more information on how the secret can be formatted, consult Istio documentation.

Set up a custom cert-manager issuer for the HM Portal

The HM Portal's certificate can also be generated and managed using one of the x.509 issuers supported by HM's internal cert-manager, e.g. The ACME Issuer for Let's Encrypt certificates.

You can follow the documentation of the issuer of your choice directly from the cert-manager website to set it up.

Once the ClusterIssuer is configured, pass its name to HM.

Edit your HybridControlPlane CR to add the issuer parameters under spec.globalParameters:

apiVersion: edbpgai.edb.com/v1alpha1
kind: HybridControlPlane
metadata:
  name: edbpgai
spec:
  globalParameters:
    portal_certificate_issuer_kind: "ClusterIssuer"  # Valid values are Issuer and ClusterIssuer
    portal_certificate_issuer_name: "my-issuer"       # Your Issuer name
    # ... your other globalParameters

Apply the updated CR:

kubectl apply -f hybridmanager.yaml

The operator reconciles the change and configures the portal to use the specified issuer.

Gateway certificate source priority

If more than one certificate source is configured, HM selects the gateway certificate in this order:

1. cert-manager issuer (if portal_certificate_issuer_name is set) — cert-manager creates and rotates the certificate automatically.
2. Static TLS secret (if portal_certificate_secret is set) — You manage certificate renewal manually.
3. Self-signed certificate (default) — Generated at install time.

Bring your own private certificate authority

By default, all the certificates used by HM are signed by an internal certificate authority (CA) powered by cert-manager. The CA is created at install time.

If you prefer to use your own Private CA, follow the steps in this section. Otherwise, you can skip this section.

Create one CA secret if it doesn't exist.

apiVersion: v1
data:
  ca.crt: <base64 encoded string> # real ca crt provided by customers
  tls.crt: <base64 encoded string> # real tls crt provided by customers
  tls.key: <base64 encoded string> # real tls key provided by customers
kind: Secret
metadata:
  name: my-custom-ca
  namespace: default
  annotations:
    replicator.v1.mittwald.de/replicate-to: 'cert-manager'
type: kubernetes.io/tls

Edit your HybridControlPlane CR to add the ca_secret_name parameter under spec.globalParameters:

apiVersion: edbpgai.edb.com/v1alpha1
kind: HybridControlPlane
metadata:
  name: edbpgai
spec:
  globalParameters:
    ca_secret_name: "my-custom-ca"
    # ... your other globalParameters

Apply the updated CR:

kubectl apply -f hybridmanager.yaml

The operator reconciles the change and configures HM to use your private CA.

Certificate rotation

cert-manager issuer

When using a cert-manager issuer, certificates are rotated automatically before expiry. By default, cert-manager renews certificates when they reach two-thirds of their lifetime.

To check the certificate status:

kubectl get certificate -n istio-system

To force an immediate renewal, delete the certificate secret. cert-manager detects the missing secret and issues a new certificate:

kubectl delete secret -n istio-system <certificate-secret-name>

Static certificate

When using a static TLS secret, you must manually rotate the certificate before it expires.

Generate new certificate data

Obtain a renewed certificate from your CA.

Update the Kubernetes secret

kubectl create secret tls my-portal-certificate \
  --cert=new-certificate.crt \
  --key=new-certificate.key \
  --namespace=default \
  --dry-run=client -o yaml | kubectl apply -f -

Verify the update propagated

The secret replicator copies the updated secret to istio-system. Verify:

kubectl get secret -n istio-system my-portal-certificate -o jsonpath='{.data.tls\.crt}' | base64 -d | openssl x509 -dates -noout

Restart the Istio gateway (if needed)

In most cases, Istio detects the secret change automatically. If not:

kubectl rollout restart deployment/istio-ingressgateway -n istio-system