Cert Manager

Pro Feature

This feature is available in the vCluster Pro tier. Contact us for more details and to start a trial.

Cert manager integration

This guide shows how to set up cert-manager integration with your virtual cluster.

Prerequisites

• Administrator access to a Kubernetes cluster: See Accessing Clusters with kubectl for more information. Your current kube-context must have administrative privileges, which you can verify with kubectl auth can-i create clusterrole -A

  info

  To obtain a kube-context with admin access, ensure you have the necessary credentials and permissions for your Kubernetes cluster. This typically involves using kubectl config commands or authenticating through your cloud provider's CLI tools.

• helm installed: Helm v3.10 is required for deploying the platform. Refer to the Helm Installation Guide if you need to install it.

• kubectl installed: Kubernetes command-line tool for interacting with the cluster. See Install and Set Up kubectl for installation instructions.

• cert-manager operator installed on your host cluster, see cert-manager installation guide.

Enable the integration

Enable the cert-manager integration in your virtual cluster configuration:

Enable cert-manager integration

integrations:
  certManager:
    enabled: true

This configuration:

• Enables the integration.
• Imports cluster-scoped ClusterIssuers from your host cluster into the virtual cluster.
• Exports namespaced Issuers and Certificates from the virtual cluster to the host cluster.

create virtual cluster

Create or update a virtual Cluster following the vCluster quick start guide.

Set up cluster contexts

Setting up the host and virtual cluster contexts makes it easier to switch between them.

export HOST_CTX="your-host-context"
export VCLUSTER_CTX="vcluster-ctx"

tip

You can find your contexts by running kubectl config get-contexts

Setup the integration

If you don't have cert-manager configured yet, follow these steps:

1. Virtual Cluster Create the ClusterIssuer.

   tip

   This should create a corresponding Issuer in the host cluster.

   Create a file named issuer.yaml:

   Create ClusterIssuer

   cat <<EOF > issuer.yaml
   apiVersion: cert-manager.io/v1
   kind: ClusterIssuer
   metadata:
     name: letsencrypt-staging
   spec:
     acme:
       # Replace this email address with your own
       # Let's Encrypt will use this to contact you about expiring
       # certificates, and issues related to your account
       email: user@example.com
       server: https://acme-staging-v02.api.letsencrypt.org/directory
       privateKeySecretRef:
         name: example-issuer-account-key
       solvers:
       - http01:
           ingress:
             ingressClassName: nginx
   EOF

   Apply to the host cluster:

   Apply ClusterIssuer to host cluster

   kubectl --context=$HOST_CTX apply -f issuer.yaml

Create a certificate

With the ClusterIssuers configured, create a certificate within the virtual cluster.

2. Virtual Cluster Create the Certificate

   Create a file named certificate.yaml:

   Create Certificate

   cat <<EOF > certificate.yaml
   apiVersion: cert-manager.io/v1
   kind: Certificate
   metadata:
     name: quickstart-example-tls
     namespace: default
   spec:
     dnsNames:
     - example.example.com
     issuerRef:
       group: cert-manager.io
       kind: Issuer
       name: letsencrypt-staging
     secretName: quickstart-example-tls
     usages:
     - digital signature
     - key encipherment
   EOF
   Apply Certificate in virtual cluster

   kubectl --context=$VCLUSTER_CTX apply -f certificate.yaml
   tip

   Once that certificate is created in the virtual cluster, the integration syncs the created secret back to the virtual cluster after the cert-manager operator creates it in the host cluster, and the certificate is ready to use.

Verify the setup

3. Host Cluster Check the ClusterIssuer

   Check ClusterIssuer in host cluster

   kubectl --context=$HOST_CTX describe clusterissuer letsencrypt-staging

4. Virtual Cluster Check resources

   Check Issuer and Certificate in virtual cluster

   kubectl --context=$VCLUSTER_CTX describe issuer letsencrypt-staging -n default
   
   kubectl --context=$VCLUSTER_CTX describe certificate quickstart-example-tls -n default
   
   kubectl --context=$VCLUSTER_CTX get secret quickstart-example-tls -n default

Using the certificate

To use your certificate in an application, reference it in your Ingress resource:

ingress.yaml

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: example-ingress
  annotations:
    kubernetes.io/ingress.class: nginx
spec:
  tls:
    - hosts:
        - example.example.com
      secretName: quickstart-example-tls
  rules:
    - host: example.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: example-service
                port:
                  number: 80

Troubleshooting

Host Cluster

• Verify cert-manager is running

kubectl --context=$HOST_CTX -n cert-manager get pods

• Check cert-manager logs for errors - Ensure proper RBAC permissions are configured

Virtual Cluster

• Verify the integration is enabled in your vcluster configuration
• Check that secrets are syncing correctly between clusters
• Ensure your Issuer and Certificate configurations are correct

For detailed troubleshooting steps, see the cert-manager troubleshooting guide.

Config reference

certManager required object pro

CertManager reuses a host cert-manager and makes its CRDs from it available inside the vCluster.

• Certificates and Issuers will be synced from the virtual cluster to the host cluster.
• ClusterIssuers will be synced from the host cluster to the virtual cluster.

enabled required boolean false pro

Enabled defines if this option should be enabled.

sync required object pro

Sync contains advanced configuration for syncing cert-manager resources.

toHost required object pro

certificates required object pro

Certificates defines if certificates should get synced from the virtual cluster to the host cluster.

enabled required boolean true pro

Enabled defines if this option should be enabled.

issuers required object pro

Issuers defines if issuers should get synced from the virtual cluster to the host cluster.

enabled required boolean true pro

Enabled defines if this option should be enabled.

fromHost required object pro

clusterIssuers required object pro

ClusterIssuers defines if (and which) cluster issuers should get synced from the host cluster to the virtual cluster.

enabled required boolean true pro

Enabled defines if this option should be enabled.

selector required object pro

Selector defines what cluster issuers should be imported.

labels required object {} pro

Labels defines what labels should be looked for