Certificate Management

This page describes the certificate management options available in Kthena for SSL/TLS certificates.

Overview

Kthena provides three mutually exclusive certificate management modes controlled by a single configuration option:

1. auto (Default): Self-signed certificates automatically generated by webhook servers
2. cert-manager: Automated certificate lifecycle management using cert-manager
3. manual: User-provided certificates with custom CA bundle

Important: Only one mode can be active at a time. These modes are mutually exclusive and controlled by the global.certManagementMode setting.

The integration covers:

• Admission Webhooks: TLS certificates for workload and networking webhook servers
• Kthena Router: TLS certificates for external API access
• Internal Communication: Service-to-service encrypted communication

Centralized Certificate Management Configuration

Kthena uses a single enum-based configuration to control certificate management:

global:
  # Certificate management mode: auto, cert-manager, or manual
  certManagementMode: auto  # Default: auto

Available Modes

• auto: Self-signed certificates automatically generated by webhook servers (default)
• cert-manager: Automated certificate lifecycle management using cert-manager
• manual: User-provided certificates with custom CA bundle

Mode 1: Auto-Generated Certificates (Default)

Status: Enabled by default (certManagementMode: auto)

The simplest way to get started. When enabled, webhook servers automatically generate self-signed certificates on startup if they don't exist.

Features

• Zero Configuration: No external dependencies or manual certificate generation required
• Multi-Pod Support: First pod creates the certificate secret; subsequent pods reuse it
• Automatic Race Condition Handling: Safe for multiple replicas starting simultaneously
• 10-Year Validity: Long-lived certificates that don't require frequent rotation

Configuration

Auto-generated certificates are enabled by default. To use this mode explicitly:

global:
  certManagementMode: auto  # Default value, can be omitted

How It Works

1. On startup, the webhook server checks if the certificate secret exists
2. If the secret exists, it uses the existing certificates
3. If the secret doesn't exist, it generates:
   • A self-signed CA certificate
   • A server certificate signed by the CA
   • A private key
4. The certificates are stored in a Kubernetes secret with a fixed name
5. If multiple pods start simultaneously, the first one creates the secret; others detect the existing secret and use it

RBAC Requirements

The service account needs permissions to create and read secrets:

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
rules:
  - apiGroups: [ "" ]
    resources: [ "secrets" ]
    verbs: [ "create", "get", "list", "watch" ]

Mode 2: CertManager Integration (For Production)

Kthena supports integration with cert-manager for production-grade certificate management. cert-manager handles certificate lifecycle management including issuance, renewal, and rotation.

To use this mode: Set certManagementMode: cert-manager

Prerequisites

Before enabling cert-manager integration, ensure that:

1. cert-manager is installed in your Kubernetes cluster. Follow the official installation guide.
2. Sufficient RBAC permissions are available for cert-manager to create and manage certificates in your namespace.

Configuration

cert-manager integration is controlled through the global.certManagementMode setting:

global:
  certManagementMode: cert-manager

When enabled, Kthena will automatically create:

• Self-signed Issuer resources for each component
• Certificate resources with appropriate DNS names
• TLS secrets for storing certificates and private keys

Component-Specific Configuration

Kthena Router TLS

For external API access, configure the kthena router TLS settings:

networking:
  kthenaRouter:
    enabled: true
    tls:
      enabled: true
      # The DNS name for your external domain
      dnsName: "your-domain.com"
      # Secret name to store the TLS certificate
      secretName: "kthena-router-tls"

Webhook Certificates

Webhook certificates are automatically configured when cert-manager is enabled. Each subchart (workload, networking) creates its own webhook certificates with internal DNS names:

• <subchart-name>-webhook.<namespace>.svc
• <subchart-name>-webhook.<namespace>.svc.cluster.local

Mode 3: Manual Certificate Management

If you prefer to manage certificates manually (e.g., using your organization's PKI), use the manual mode and provide your own CA bundle.

To use this mode: Set certManagementMode: manual and provide the CA bundle.

global:
  certManagementMode: manual
  webhook:
    # Base64-encoded CA bundle for webhook certificates
    caBundle: "LS0tLS1CRUdJTi..."

To generate a CA bundle:

cat /path/to/your/ca.crt | base64 | tr -d '\n'

Note: When using manual mode, you are responsible for providing valid certificates and ensuring they are properly configured for all Kthena components.

Certificate Resources

When cert-manager integration is enabled, the following resources are created:

Issuers

• kthena-controller-manager-webhook-issuer (Workload)
• kthena-router-webhook-issuer (Networking)
• kthena-router-issuer (Networking - for Kthena Router)

Certificates

• kthena-controller-manager-webhook-cert (Workload)
• kthena-router-webhook-cert (Networking)
• kthena-router-cert (Networking - for Kthena Router)

Secrets

• kthena-controller-manager-webhook-certs (Workload - default)
• kthena-router-webhook-certs (Networking - default)
• kthena-router-tls (Networking - default for Kthena Router)

Troubleshooting

Common Issues

cert-manager Not Found

Error: failed to create certificate: cert-manager.io/v1, Kind=Certificate not found

Solution: Install cert-manager in your cluster before enabling the integration.

Certificate Not Ready

Certificate is not ready: certificate request has not been approved

Solution: Check cert-manager logs and ensure the issuer is properly configured:

kubectl describe certificate <certificate-name> -n <namespace>
kubectl logs -n cert-manager deployment/cert-manager

Webhook Connection Refused

Error: connection refused when calling webhook

Solution: Verify webhook certificates are properly mounted and the service is accessible:

kubectl get certificates -n <namespace>
kubectl describe secret <webhook-secret-name> -n <namespace>

DNS Resolution Issues

Error: certificate validation failed for DNS name

Solution: Ensure DNS names in your configuration are resolvable and match your actual service endpoints.

Debugging Commands

Check certificate status:

kubectl get certificates -n <namespace>
kubectl describe certificate <certificate-name> -n <namespace>

Verify issuer status:

kubectl get issuers -n <namespace>
kubectl describe issuer <issuer-name> -n <namespace>

Check cert-manager logs:

kubectl logs -n cert-manager deployment/cert-manager
kubectl logs -n cert-manager deployment/cert-manager-webhook

Getting Help

If you encounter issues not covered here:

1. Check the cert-manager documentation
2. Review Kthena logs for certificate-related errors
3. Consult the cert-manager troubleshooting guide

Comparison of Certificate Options

Feature	Auto-Generated	cert-manager	Manual
Setup Complexity	Low	Medium	High
External Dependencies	None	cert-manager required	Certificate generation tools
Certificate Rotation	Manual (10-year validity)	Automatic	Manual
Production Ready	Development/Testing	Yes	Yes
Multi-Pod Support	Yes	Yes	Yes
Custom CA Support	No (self-signed)	Yes	Yes
Certificate Monitoring	Basic	Advanced	Manual

Choosing the Right Option

• Development/Testing: Use auto-generated certificates for simplicity
• Production with cert-manager: Use cert-manager integration for automated lifecycle management
• Production without cert-manager: Use manual certificate provisioning with your organization's PKI
• Air-gapped environments: Use manual certificate provisioning or auto-generated certificates