Deploying with External cert-manager
By default, the Fuzzball operator installs and manages its own cert-manager instance. If your cluster already has cert-manager (and optionally trust-manager) installed, you can configure Fuzzball to use those existing installations instead.
Before deploying the FuzzballOrchestrate CR, ensure the cluster has:
- cert-manager installed and running
- At least one ClusterIssuer for internal service-to-service TLS
- At least one ClusterIssuer for external-facing ingress TLS (can be the same issuer)
- trust-manager installed and running, or omit it to have the operator deploy it
You can list available ClusterIssuers with:
$ kubectl get clusterissuerThe key difference from a standard deployment is in the tls section of your fuzzball.yaml.
Omit certManager.create and reference your existing ClusterIssuers using issuerName.
This is the default configuration, shown here for comparison:
tls:
certManager:
create: {}
trustManager:
create: {}
ingressIssuer:
create:
letsEncrypt:
email: admin@example.com
issuer: letsencrypt-prod
tls:
# Omit certManager entirely -- the operator uses the cluster's existing installation.
# If trust-manager is also pre-installed, omit trustManager too.
# If trust-manager is NOT installed, keep this to have the operator deploy it:
trustManager:
create: {}
internalIssuer:
external:
issuerName: fuzzball-ca-issuer # ClusterIssuer for internal service TLS
ingressIssuer:
external:
issuerName: letsencrypt-prod # ClusterIssuer for external ingress TLS
The internal issuer handles service-to-service communication (gRPC between Fuzzball components, JetStream TLS, etc.) and must be a CA issuer. The ingress issuer handles external-facing endpoints (API, UI, OpenAPI) and can be Let’s Encrypt or another public CA.
cert-manager reads the secrets a ClusterIssuer references from its cluster resource namespace. That is
the namespace cert-manager is installed in, unless its --cluster-resource-namespace flag sets another
one. If that namespace is not cert-manager (for example, cozy-cert-manager on Cozystack), set
certManager.clusterResourceNamespace to it:
tls:
certManager:
clusterResourceNamespace: cozy-cert-manager
internalIssuer:
external:
issuerName: fuzzball-ca-issuer
ingressIssuer:
external:
issuerName: fuzzball-ca-issuer
The operator reads the CA secrets of external issuers from this namespace. It also creates the CA
secrets for issuers it manages there, so the setting applies when you omit internalIssuer.external
too. If the operator deploys trust-manager (trustManager.create), it uses this namespace as
trust-manager’s trust namespace. Do not combine it with certManager.create: the operator always installs its own cert-manager
into cert-manager and rejects the configuration.
To find the namespace, check where the cert-manager controller runs and whether it sets the flag:
$ kubectl get deployments --all-namespaces -l app.kubernetes.io/name=cert-manager,app.kubernetes.io/component=controller
$ kubectl get deployment <name> -n <namespace> -o jsonpath='{.spec.template.spec.containers[0].args}'When external issuers are configured, the operator:
- Skips cert-manager deployment and uses the cluster’s existing installation
- Deploys trust-manager if
trustManager.createis set, otherwise assumes it is running - Fetches each ClusterIssuer to extract its CA certificate
- Adds the CA to the trust bundle so all Fuzzball services trust issued certificates
- Annotates ingress and service resources with
cert-manager.io/cluster-issuerso cert-manager issues certificates automatically
CA bundle extraction and distribution happen automatically. You do not need to manually create atrusted-ca-certs-bundleConfigMap.
For development or air-gapped environments without Let’s Encrypt access, you can create a
self-signed CA issuer. Create the root CA certificate in cert-manager’s cluster resource namespace,
shown here as cert-manager:
# Bootstrap a self-signed issuer
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
name: selfsigned-issuer
spec:
selfSigned: {}
---
# Create a root CA certificate
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
name: root-ca-cert
namespace: cert-manager
spec:
isCA: true
commonName: "Fuzzball Root CA"
secretName: root-ca-cert
duration: 87600h
issuerRef:
name: selfsigned-issuer
kind: ClusterIssuer
privateKey:
algorithm: ECDSA
size: 256
---
# CA issuer that Fuzzball will reference
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
name: fuzzball-ca-issuer
spec:
ca:
secretName: root-ca-cert
Then reference it in both issuer fields:
tls:
internalIssuer:
external:
issuerName: fuzzball-ca-issuer
ingressIssuer:
external:
issuerName: fuzzball-ca-issuer
If you have an existing deployment using the deprecated internalCAIssuerName field, update your
configuration to use issuerName instead. Both fields work, but issuerName is preferred:
# Deprecated -- still works but should be updated
internalIssuer:
external:
internalCAIssuerName: my-issuer
# Preferred
internalIssuer:
external:
issuerName: my-issuer
For more details on TLS configuration parameters, see the CRD reference.
For how certificates are renewed after deployment and how to monitor their expiry, see Certificate Renewal and Monitoring.