Skip to main content
Version: Developer

Configure TLS certificates for Kasm on Kubernetes

Overview​

Kasm Workspaces requires Transport Layer Security (TLS) for secure communication between its components. A Kasm Workspaces deployment on Kubernetes functions correctly only when a certificate secret exists in the Kasm namespace. This guide creates that secret using one of three common methods, so your deployment encrypts traffic with a certificate that fits your environment. You choose cert-manager for automated lifecycle management, a self-signed certificate for testing, or a certificate from a Certificate Authority for production trust.

Prerequisites​

Before you begin, confirm the following:

  • Access to the Kubernetes cluster with permission to create secrets in the Kasm namespace.
  • The name of the Kubernetes namespace that your Kasm Workspaces deployment uses. This guide refers to it as {NAMESPACE}.
  • A decision on which method to use: cert-manager, a self-signed certificate, or a CA-issued certificate.
  • For the cert-manager method, cert-manager installed in the cluster, along with the name and kind of an existing issuer.
  • For the self-signed method, openssl available on your workstation.
  • The Kasm Workspaces Helm chart, as described in the Kubernetes installation guide.

Solution approach​

This guide progresses through the following phases:

  1. Choose a certificate method.
  2. Create the certificate with the chosen method.
  3. Add the generated TLS secret to Kubernetes.
  4. Match the secret to the Helm chart.
  5. Optionally, terminate TLS at a cloud-managed load balancer.

Detailed steps​

Choose a certificate method​

Select the method that matches your environment. The following options determine how you create and manage the TLS secret:

  1. Use cert-manager (recommended) to create and renew the secret automatically.
  2. Create a self-signed certificate manually for testing or internal use.
  3. Upload a certificate from a Certificate Authority when you already hold a CA-issued certificate.

When the cluster has cert-manager installed, cert-manager creates and manages the TLS secret for you. The Helm chart is already configured for this scenario. You provide the issuer name, the issuer kind, and a secret name.

  1. Open your values.yaml file and locate the certificate block. The block defines how cert-manager issues the certificate:

    certificate:
      secretName: {SECRET-NAME}
      certManager:
        enabled: true
        addWildCard: true
        issuerName: {ISSUER-NAME}
        issuerKind: ""
        issuerGroup: ""
        annotations: {}
        labels: {}

  2. Copy and paste the block into your my-values.yaml file.

  3. Apply any modifications you want to make.

  4. Deploy or update your Helm release as usual.

The following table describes the fields available for configuring the certificate:

FieldDescription
secretNameThe name of the Kubernetes secret where the certificate is stored. cert-manager creates and manages this secret automatically.
certManager.enabledSet to true to enable cert-manager integration.
certManager.addWildCardWhen true, adds a wildcard SAN (*.{publicAddr}) to the generated certificate.
certManager.issuerNameThe name of the cert-manager Issuer or ClusterIssuer to use for certificate issuance.
certManager.issuerKindThe kind of the cert-manager issuer. Leave empty to default to Issuer. Set to ClusterIssuer if using a cluster-wide issuer.
certManager.issuerGroupThe API group of the issuer. Leave empty to default to cert-manager.io.
certManager.annotationsAdditional annotations to add to the Certificate resource.
certManager.labelsAdditional labels to add to the Certificate resource.

For details on configuring Issuers and ClusterIssuers, see the cert-manager documentation.

note

If you have already deployed Kasm using the Helm chart, update your values file according to the instructions in the installation guide.

Create a self-signed certificate manually​

When you do not use cert-manager, generate a self-signed certificate and create a Kubernetes secret manually. Choose one of the following two options.

The first option uses the example script below. Copy, paste, and run it:

openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
  -keyout tls.key -out tls.crt \
  -subj "/CN=kasm.example.com/O=Kasm Self-Signed"

The second option follows the guide in the official Kubernetes documentation.

The chart requires the following filenames:

  • Certificate file: tls.crt
  • Key file: tls.key
  • CA certificate (optional, for custom CAs): ca.crt

After you generate the files, continue to Add the generated TLS secret to Kubernetes.

Upload a certificate from a Certificate Authority (CA)​

When you already hold a certificate from your organization's CA or a public CA, use the existing files:

  1. Obtain or export your certificate (tls.crt), key (tls.key), and optional CA certificate (ca.crt).
  2. Continue to the Add the generated TLS secret to Kubernetes section below.

Add the generated TLS secret to Kubernetes​

After you have the certificate files, create the secret in your namespace. Run the following commands, substituting your values:

# Set your secret and namespace names
SECRET_NAME="kasm-cert-secret"
NAMESPACE="kasm-ns"

# Create a TLS secret (cert + key only):
kubectl create secret tls $SECRET_NAME \
  --cert=tls.crt \
  --key=tls.key \
  --namespace $NAMESPACE

# If you need to include a CA certificate as well:
kubectl create secret generic $SECRET_NAME \
  --from-file=tls.crt=/path/to/tls.crt \
  --from-file=tls.key=/path/to/tls.key \
  --from-file=ca.crt=/path/to/ca.crt \
  --namespace $NAMESPACE

Match the secret to the Helm chart​

The Helm chart expects the certificate.secretName value in your my-values.yaml to match the secret you just created. Set this value at install or upgrade time by adding the following to your my-values.yaml:

certificate:
  secretName: {SECRET-NAME}
note

If you have already deployed Kasm using the Helm chart, update your values file according to the instructions in the installation guide.

Terminate TLS at a cloud-managed load balancer (optional)​

When you deploy on a managed Kubernetes platform such as GKE, EKS, or AKS, you may prefer to terminate TLS at a cloud-managed load balancer or gateway rather than at the Kubernetes Ingress. On GCP, for example, you can use a Gateway with Google-managed certificates to handle external TLS. You still use cert-manager or self-signed certificates for internal cluster traffic. This hybrid approach simplifies certificate lifecycle management and firewall configuration, because the cloud provider manages the external IP.

Common troubleshooting steps​

  • The deployment cannot find the certificate secret. Confirm that the secret exists in the same namespace as your Kasm Workspaces deployment. The secret name must match the certificate.secretName value in your my-values.yaml.
  • cert-manager does not issue a certificate. Confirm that cert-manager is installed and that the issuerName and issuerKind values reference an existing issuer. Check the cert-manager logs and the status of the Certificate resource for issuance errors.
  • The chart rejects the secret files. The chart requires the filenames tls.crt, tls.key, and the optional ca.crt. Confirm that you created the secret with these exact keys.
  • Browsers warn that the certificate is untrusted. Self-signed certificates are not trusted by default. Use a certificate from a public or internal CA, or distribute the CA certificate to client trust stores for production use.

Additional references​