README
¶
pkg/certmanager
certmanager owns the TLS certificate lifecycle for Orkestra's webhook server. It generates self-signed certificates when the operator has not been given explicit TLS paths, stores them in a Kubernetes Secret, and cleans them up on graceful shutdown.
mgr := certmanager.New(kube.Clientset())
bundle, err := mgr.EnsureCertificate(ctx, certmanager.CertificateSpec{
ServiceName: kfg.Security().ServiceName,
Namespace: kfg.Cluster().Namespace,
SecretName: certmanager.DefaultTLSSecretName,
ValidFor: "1y",
BaseLabels: labels.OrkestraBaseLabels(),
})
Secret shape
The generated Secret is of type kubernetes.io/tls and carries three keys:
| Key | Content |
|---|---|
tls.crt |
PEM-encoded signed server certificate |
tls.key |
PEM-encoded server private key |
ca.crt |
PEM-encoded CA certificate (used as caBundle in webhook configurations) |
The Secret is labelled with orkestra.io/deletion-protection=true so that Orkestra's own admission webhook will reject accidental delete requests against it.
Idempotency
EnsureCertificate checks whether the Secret already exists before generating a new certificate. If the Secret is present and its certificate has not expired, the existing bundle is returned without any API mutations. This means the method is safe to call on every startup — it will not generate a new certificate on every restart.
Shutdown cleanup
When SecurityConfig.DeletionProtection.CleanupOnShutdown is true, the health server calls DeleteCertificateAndSecret during Shutdown(). A NotFound error is silently ignored, so cleanup is idempotent across restarts.
When Orkestra generates its own certificates
Without TLS_CERT / TLS_KEY ENV vars:
konfig.Init()leavesSecurity().Webhooks.TLSCertandTLSKeyempty.- The gateway calls
EnsureCertificate()at startup. EnsureCertificate()generates the bundle and stores it in the Kubernetes Secret.- The Katalog loader writes the cert and key paths back into
kfg.Security(). - The webhook server reads the populated paths from
kfg.Security().
No shared file system or init containers required.
Documentation
¶
Overview ¶
Package certmanager centralises the TLS certificate lifecycle for Orkestra.
Orkestra generates self-signed TLS certificates when security features (deletion protection, admission webhooks, conversion webhooks) are enabled and the operator has not been given explicit TLS_CERT/TLS_KEY paths. This package owns that lifecycle: generation, Secret storage, and optional deletion on graceful shutdown.
Architecture ¶
Manager is the public interface; k8sManager is its only production implementation. The separation lets tests inject a fake without importing client-go fakes into every caller.
Secret shape ¶
The generated Secret is of type kubernetes.io/tls and carries three keys:
tls.crt — PEM-encoded signed server certificate tls.key — PEM-encoded server private key ca.crt — PEM-encoded CA certificate (used as caBundle in webhook configs)
The Secret is labelled with the deletion-protection label so that Orkestra's own admission webhook will reject accidental delete requests against it.
Shutdown cleanup ¶
When DeletionProtection.CleanupOnShutdown is true, the HealthServer calls DeleteCertificateAndSecret during Shutdown(). A NotFound error is silently ignored — the operator may have been restarted without the Secret present.
Usage ¶
mgr := certmanager.New(kube.Clientset())
bundle, err := mgr.EnsureCertificate(ctx, certmanager.CertificateSpec{
ServiceName: "orkestra",
Namespace: "orkestra-system",
SecretName: certmanager.DefaultTLSSecretName,
ValidFor: "1y",
BaseLabels: kfg.OrkestraResourceLabels(),
})
Index ¶
Constants ¶
const (
// DefaultCertValidFor is the default certificate validity duration.
DefaultCertValidFor = "1y"
)
Variables ¶
var DefaultTLSSecretName = konfig.DefaultInternalTLSName()
DefaultTLSSecretName is the Secret name used for Orkestra's auto-generated TLS bundle.
Functions ¶
This section is empty.
Types ¶
type BundleOpts ¶ added in v0.4.9
type BundleOpts struct {
// ValidFor is the certificate validity duration ("1y", "90d", etc.).
// Default: "1y".
ValidFor string
}
BundleOpts configures optional parameters for GenerateClusterBundle. Zero value uses all defaults.
type CertificateSpec ¶
type CertificateSpec struct {
// ServiceName is the Kubernetes Service that will serve the certificate (e.g. "orkestra").
ServiceName string
// Namespace is the namespace where the Service and Secret live.
Namespace string
// SecretName is the name of the Secret to create or update.
SecretName string
// ValidFor is the certificate validity duration string ("1y", "90d", etc.).
ValidFor string
// BaseLabels are the labels to apply to the Secret in addition to the deletion-protection label.
BaseLabels map[string]string
}
CertificateSpec describes the TLS certificate Orkestra should generate and store.
type Manager ¶
type Manager interface {
// EnsureCertificate generates a TLS bundle and stores it in a Kubernetes Secret.
// If the Secret already exists it is updated in-place.
EnsureCertificate(ctx context.Context, spec CertificateSpec) (*TLSBundle, error)
// DeleteCertificateAndSecret removes the TLS Secret from the cluster.
// A NotFound error is silently ignored.
DeleteCertificateAndSecret(ctx context.Context, namespace, secretName string) error
}
Manager handles TLS certificate generation and Secret lifecycle.
func New ¶
func New(client kubernetes.Interface) Manager
New returns a Manager backed by the given Kubernetes client.
type TLSBundle ¶ added in v0.3.1
type TLSBundle struct {
CertPEM []byte // tls.crt — signed server certificate, PEM
KeyPEM []byte // tls.key — server private key, PEM
CACertPEM []byte // ca.crt — CA certificate, PEM (for caBundle in webhooks)
}
TLSBundle holds the generated certificate material.
func GenerateClusterBundle ¶ added in v0.4.9
func GenerateClusterBundle(svcName, namespace string, opts BundleOpts) (*TLSBundle, error)
GenerateClusterBundle generates a TLS bundle with the standard in-cluster SAN pattern for a Kubernetes Service. The CN and all DNS SANs are derived from svcName and namespace — no manual SAN list required.
Use this for all Orkestra-managed in-cluster certs. Use GenerateTLSBundle directly when custom SANs are needed (e.g. ingress, workload secrets).
func GenerateTLSBundle ¶ added in v0.3.1
GenerateTLSBundle generates a self-signed CA and a server certificate signed by it. The server certificate has the given common name and DNS SANs. validFor is the certificate validity duration ("1y", "90d", etc.).
Returns a TLSBundle containing PEM-encoded cert, key, and CA cert. All three are stored in the Secret so consumers have what they need:
- tls.crt + tls.key for the server
- ca.crt for clients that need to verify the server cert
Source Files