Skip to main content

Certifcate 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.

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

    2. 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.

    3. 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

Config reference​