cert-manager Integration

​

Overview

​

How It Works

• Certificates - Certificate requests created in the virtual cluster are synced to the host
• Issuers - Namespace-scoped issuers are synced to the host cluster

• ClusterIssuers - Cluster-wide issuers from the host are available in the virtual cluster

​

Prerequisites

1. cert-manager must be installed on the host cluster
   # Install cert-manager on the host cluster
   kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.14.0/cert-manager.yaml
   
2. Verify cert-manager is running
   kubectl get pods -n cert-manager
   
3. Ensure cert-manager CRDs are installed
   kubectl get crd | grep cert-manager
   

​

Setup Instructions

​

Basic Configuration

integrations:
  certManager:
    enabled: true

vcluster create my-vcluster -n team-x -f values.yaml

​

Advanced Configuration

integrations:
  certManager:
    enabled: true
    sync:
      toHost:
        # Sync certificates from virtual to host cluster
        certificates:
          enabled: true
        # Sync issuers from virtual to host cluster
        issuers:
          enabled: true
      fromHost:
        # Sync cluster issuers from host to virtual cluster
        clusterIssuers:
          enabled: true
          # Optional: Filter which ClusterIssuers to sync
          selector:
            labels:
              environment: production

​

Selective ClusterIssuer Syncing

integrations:
  certManager:
    enabled: true
    sync:
      fromHost:
        clusterIssuers:
          enabled: true
          selector:
            labels:
              vcluster-accessible: "true"

kubectl label clusterissuer letsencrypt-prod vcluster-accessible=true

​

Usage Examples

​

Using a ClusterIssuer from the Host

# List available ClusterIssuers in the virtual cluster
kubectl get clusterissuers

apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: my-app-tls
  namespace: default
spec:
  secretName: my-app-tls-secret
  issuerRef:
    name: letsencrypt-prod  # ClusterIssuer from host
    kind: ClusterIssuer
  dnsNames:
    - my-app.example.com

kubectl apply -f certificate.yaml

​

Creating a Virtual Cluster Issuer

apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
  name: ca-issuer
  namespace: default
spec:
  ca:
    secretName: ca-key-pair

kubectl apply -f issuer.yaml

​

Using Certificates with Ingress

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: my-app
  namespace: default
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-prod
spec:
  tls:
  - hosts:
    - my-app.example.com
    secretName: my-app-tls
  rules:
  - host: my-app.example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: my-app
            port:
              number: 80

​

Validation

​

1. Check Certificate Status

# In the virtual cluster
kubectl get certificates
kubectl describe certificate my-app-tls

Status:
  Conditions:
    Type:   Ready
    Status: True
  Renewal Time: 2026-05-05T12:00:00Z

​

2. Verify Secret Creation

# Check if the TLS secret was created
kubectl get secret my-app-tls-secret
kubectl describe secret my-app-tls-secret

​

3. Check Host Cluster Resources

# Switch to host cluster context
vcluster disconnect

# Check synced resources in the host namespace
kubectl get certificates -n team-x
kubectl get issuers -n team-x

​

Common Issues and Solutions

​

Issue: Certificates Not Being Issued

1. Check cert-manager logs on the host cluster:
   kubectl logs -n cert-manager deploy/cert-manager -f
   
2. Verify the ClusterIssuer exists and is ready:
   kubectl get clusterissuer letsencrypt-prod -o yaml
   
3. Check Certificate events:
   kubectl describe certificate my-app-tls
   

​

Issue: ClusterIssuers Not Visible in Virtual Cluster

1. Verify the integration is enabled:
   vcluster list
   # Check the values used for the vCluster
   
2. Check if label selectors are too restrictive:
   integrations:
     certManager:
       sync:
         fromHost:
           clusterIssuers:
             selector:
               labels: {}  # Remove filters temporarily
   
3. Restart the vCluster control plane:
   kubectl rollout restart statefulset -n team-x
   

​

Issue: Duplicate Resources on Host

<resource-name>-x-<namespace>-x-<vcluster-name>

​

Issue: Integration Conflicts with Custom Resources

# ❌ Don't do this when integration is enabled
sync:
  toHost:
    customResources:
      certificates.cert-manager.io:
        enabled: true

# ✅ Use integration instead
integrations:
  certManager:
    enabled: true

​

Configuration Reference

integrations:
  certManager:
    # Enable/disable the cert-manager integration
    enabled: false
    
    # Configure resource syncing
    sync:
      # Resources synced from virtual to host cluster
      toHost:
        # Certificate resources
        certificates:
          enabled: true
        # Issuer resources (namespace-scoped)
        issuers:
          enabled: true
      
      # Resources synced from host to virtual cluster
      fromHost:
        # ClusterIssuer resources (cluster-scoped)
        clusterIssuers:
          enabled: true
          # Filter which ClusterIssuers to sync
          selector:
            labels: {}

​

Best Practices

1. Use ClusterIssuers for Shared Infrastructure
   • Create ClusterIssuers on the host cluster for common certificate authorities
   • Let multiple virtual clusters reuse the same issuers
2. Implement Label-Based Filtering
   • Use label selectors to control which ClusterIssuers are visible to virtual clusters
   • Prevent access to sensitive or internal-only issuers
3. Monitor Certificate Renewal
   • Set up monitoring for certificate expiration
   • Use cert-manager’s Prometheus metrics on the host cluster
4. Test in Development First
   • Enable the integration in a development virtual cluster first
   • Verify certificate issuance before promoting to production
5. Avoid Manual Sync Configuration
   • Don’t manually configure cert-manager CRDs in sync.toHost.customResources
   • Use the integration’s built-in sync logic instead

​

Related Resources

• cert-manager Documentation
• vCluster Syncing Overview
• Custom Resource Syncing
• Integration Source Code