Certificate Management

How automatic HTTPS certificates work

Siovos provides automatic HTTPS certificates for all your services using a private certificate authority. Here's how it works.

The Certificate Chain#

Three components work together to provide seamless certificate management:

Certificate chain

Step CA - Your private Certificate Authority. Issues trusted certificates for any *.internal domain (or your configured suffix).

cert-manager - Kubernetes operator that automates certificate requests. Watches for Ingress resources and Certificate CRDs, then requests certificates from Step CA.

Reflector - Copies certificate secrets across namespaces. Allows a certificate issued in one namespace to be used by services in other namespaces.

How It Works#

  1. You create an Ingress with a TLS section
  2. cert-manager detects the Ingress and creates a Certificate request
  3. cert-manager contacts Step CA to issue the certificate
  4. The certificate is stored as a Kubernetes Secret
  5. Traefik uses the secret to serve HTTPS
  6. Reflector copies the secret to other namespaces if configured

Requesting a Certificate#

Add the cert-manager annotation to your Ingress:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: my-app
  annotations:
    cert-manager.io/cluster-issuer: step-ca-issuer
spec:
  ingressClassName: traefik
  tls:
    - hosts:
        - my-app.internal
      secretName: my-app-tls
  rules:
    - host: my-app.internal
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: my-app
                port:
                  number: 80

cert-manager will automatically:

  1. Create a Certificate resource
  2. Request a certificate from Step CA
  3. Store it in the my-app-tls secret

Via Certificate Resource (Manual)#

For more control, create a Certificate resource directly:

apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: my-app-cert
  namespace: my-namespace
spec:
  secretName: my-app-tls
  duration: 720h # 30 days
  renewBefore: 168h # 7 days
  issuerRef:
    name: step-ca-issuer
    kind: ClusterIssuer
  dnsNames:
    - my-app.internal
    - api.my-app.internal

Certificate Renewal#

Certificates are automatically renewed before expiration. By default:

  • Certificate duration: 30 days
  • Renewal: automatic before expiration

You can check certificate status:

kubectl get certificates -A
kubectl describe certificate my-app-cert -n my-namespace

Sharing Certificates Across Namespaces#

Use Reflector annotations to copy a certificate secret to other namespaces:

apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: shared-cert
  namespace: cert-manager
spec:
  secretName: shared-tls
  secretTemplate:
    annotations:
      reflector.v1.k8s.emberstack.com/reflection-allowed: "true"
      reflector.v1.k8s.emberstack.com/reflection-allowed-namespaces: "app1,app2,app3"
      reflector.v1.k8s.emberstack.com/reflection-auto-enabled: "true"
  issuerRef:
    name: step-ca-issuer
    kind: ClusterIssuer
  dnsNames:
    - "*.internal"

The secret will be automatically copied to app1, app2, and app3 namespaces.

Wildcard Certificates#

For multiple subdomains, use a wildcard certificate:

apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: wildcard-cert
spec:
  secretName: wildcard-tls
  issuerRef:
    name: step-ca-issuer
    kind: ClusterIssuer
  dnsNames:
    - "*.internal"
    - "internal"

Wildcard certificates cover *.internal but not internal itself. Include both if needed.

Trusting the Certificates#

Certificates issued by Step CA are only trusted by machines that have the root CA certificate installed. See Certificate Installation for instructions.

Checking Certificate Status#

View all certificates:

kubectl get certificates -A

Check a specific certificate:

kubectl describe certificate my-app-cert -n my-namespace

View the actual secret:

kubectl get secret my-app-tls -n my-namespace -o yaml

Troubleshooting#

Certificate not issued#

  1. Check cert-manager logs:

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

  2. Check the Certificate status:

    kubectl describe certificate my-app-cert

  3. Look for CertificateRequest resources:

    kubectl get certificaterequests -A

Certificate shows "Not Ready"#

Common causes:

  • Step CA is not running
  • ClusterIssuer is misconfigured
  • DNS name is not allowed by the issuer policy

Secret not copied by Reflector#

  1. Verify Reflector annotations are correct
  2. Check Reflector logs: 
    kubectl logs -n reflector deployment/reflector

Next Steps#

Was this page helpful?