Skip to content

Custom Certificate Manager

Installing a Custom Cert-Manager on GKE Clusters

By default, the Rafay Controller installs a system-managed cert-manager during GKE cluster provisioning to support bootstrap and certificate management. However, for advanced use cases, such as using a specific version, custom issuer configurations, or managing the cert-manager lifecycle independently, users can bring their own cert-manager instance.

This guide outlines how to safely disable the system-managed cert-manager and install a custom one using add-ons and blueprints.

Disable the System-Managed Cert-Manager

To prevent conflicts, only one cert-manager instance should operate in a cluster. Running multiple instances can lead to:

  • CRD (Custom Resource Definition) conflicts
  • Race conditions between issuers
  • Erratic certificate behavior

To disable the default cert-manager, apply the following label to your custom cert-manager add-on:

rafay.user/cert-manager: "true"

Add the Label

  • Navigate to Infrastructure → Add-Ons
  • Select or create your cert-manager add-on
  • Click Manage Labels
  • Add the key rafay.user/cert-manager with the value "true"

Cluster Configuration

⚠️ Note: Without this label, Rafay will automatically provision the system-managed cert-manager, which may conflict with your custom installation.

Create the Custom Cert-Manager Add-On

You can create a custom cert-manager add-on using:

  • Helm 3
  • K8s YAML
  • Rafay Catalog charts

Cluster Configuration

Regardless of the method, it's essential to include the correct CRD management configuration.

Required CRD Values

crds:
  enabled: true
  keep: false
Value Purpose
enabled: true Ensures required CRDs are installed during add-on deployment
keep: false Allows CRDs to be removed during uninstall, avoiding leftovers/conflicts

⚠️ Important: Without these values, uninstalling your custom cert-manager could leave CRDs behind, preventing future installations or re-enabling the system-managed cert-manager.

These CRD values can be provided in one of the following ways:

  • Inside the values.yaml file (for Helm-based add-ons)
  • Embedded in the K8s YAML manifests
  • Via Cluster Overrides

Use Cluster Overrides (Optional)

If the CRD values are not defined directly in your Helm chart or YAML, they can be enforced via Cluster Overrides.

  • Navigate to Infrastructure → Cluster Overrides
  • Create or select an override group
  • Upload a file or link a Git repository containing:
crds:
  enabled: true
  keep: false

Cluster Configuration

✅ Note: Overrides take precedence over the chart’s values.yaml, ensuring consistent behavior during install and uninstall cycles.

Integrate with Blueprint and Deploy

Once the custom cert-manager add-on is created and properly labeled:

  • Add the add-on to a custom blueprint
  • Apply the blueprint during GKE cluster provisioning

This ensures:

  • The system-managed cert-manager is not installed
  • Your custom cert-manager is deployed with the correct configuration

This approach ensures a smooth and conflict-free deployment of a custom cert-manager while preserving cluster integrity and upgrade flexibility.