Documentation
¶
Overview ¶
Package certmanager exposes the generated constructors and the admissible sugar for cert-manager resources: Certificate, Issuer and ClusterIssuer. Each constructor returns a controller-runtime object carrying identity only; the upstream cert-manager struct is the construction API.
## Constructors
Create<Kind> is generated from the registered scheme and emits apiVersion, kind, metadata.name and, for a namespaced kind, metadata.namespace. Spec fields are the caller's own assignments:
cert := certmanager.CreateCertificate("my-cert", "default")
cert.Spec = certv1.CertificateSpec{
SecretName: "my-cert-tls",
IssuerRef: cmmeta.IssuerReference{Name: "letsencrypt", Kind: "ClusterIssuer"},
DNSNames: []string{"example.com"},
}
An issuer's one-of (ACME, CA, Vault, SelfSigned, Venafi) is the upstream IssuerConfig struct: set the arm you want, as a pointer.
issuer := certmanager.CreateClusterIssuer("letsencrypt")
certmanager.SetClusterIssuerACME(issuer, &cmacme.ACMEIssuer{
Server: "https://acme-v02.api.letsencrypt.org/directory",
Email: "admin@example.com",
})
## Update helpers
Functions prefixed with Set or Add write exactly the one field they name and fall into the builder contract's admitted classes: AddCertificateDNSName and AddACMEIssuerSolver append, the remaining Set* helpers assign a pointer-typed field. Labels and annotations use the generic kubernetes.AddLabel / kubernetes.AddAnnotation over metav1.Object; this package carries no per-kind metadata helpers.
The config-struct layer this package used to carry — Certificate, Issuer and ClusterIssuer taking a *Config, and the sealed IssuerVariant, ACMESolver and DNS01Provider sums — was retired by release 2 of the builder contract; see docs/builder-contract-release-2.md for the field-by-field mapping.
Example (AgentsSecretKeySelector) ¶
package main
import (
"fmt"
cmmeta "github.com/cert-manager/cert-manager/pkg/apis/meta/v1"
)
func main() {
key := cmmeta.SecretKeySelector{
LocalObjectReference: cmmeta.LocalObjectReference{Name: "secret-name"},
Key: "key-name",
}
fmt.Println(key.Name, key.Key)
}
Output: secret-name key-name
Example (ArchitectureCertificate) ¶
package main
import (
"fmt"
cmacme "github.com/cert-manager/cert-manager/pkg/apis/acme/v1"
cmmeta "github.com/cert-manager/cert-manager/pkg/apis/meta/v1"
"github.com/go-kure/kure/pkg/kubernetes/certmanager"
)
func main() {
// ACME challenge configuration. SetClusterIssuerACME assigns a pointer-typed
// field, which is what makes it admissible sugar — it takes the *ACMEIssuer,
// built here as an upstream struct literal, and writes it straight to the spec.
issuer := certmanager.CreateClusterIssuer("letsencrypt")
certmanager.SetClusterIssuerACME(issuer, &cmacme.ACMEIssuer{
Server: "https://acme-v02.api.letsencrypt.org/directory",
Email: "admin@example.com",
Solvers: []cmacme.ACMEChallengeSolver{{
DNS01: &cmacme.ACMEChallengeSolverDNS01{
Cloudflare: &cmacme.ACMEIssuerDNS01ProviderCloudflare{
APIToken: &cmmeta.SecretKeySelector{
LocalObjectReference: cmmeta.LocalObjectReference{Name: "cloudflare-api-token"},
Key: "token",
},
},
},
}},
})
// Certificate with DNS validation. IssuerRef is a plain field; DNSNames is a
// slice, so it keeps an appender.
cert := certmanager.CreateCertificate("api-tls", "default")
cert.Spec.IssuerRef = cmmeta.IssuerReference{
Name: "letsencrypt",
Kind: "ClusterIssuer",
}
certmanager.AddCertificateDNSName(cert, "api.example.com")
fmt.Println(issuer.Spec.ACME.Solvers[0].DNS01.Cloudflare.APIToken.Name, cert.Spec.IssuerRef.Kind, cert.Spec.DNSNames)
}
Output: cloudflare-api-token ClusterIssuer [api.example.com]
Example (ArchitectureSecretReference) ¶
package main
import (
"fmt"
certv1 "github.com/cert-manager/cert-manager/pkg/apis/certmanager/v1"
cmmeta "github.com/cert-manager/cert-manager/pkg/apis/meta/v1"
"github.com/go-kure/kure/pkg/kubernetes/certmanager"
)
func main() {
// Standard pattern for secret references
key := cmmeta.SecretKeySelector{
LocalObjectReference: cmmeta.LocalObjectReference{Name: "secret-name"},
Key: "key-name",
}
// The reference is a field on the upstream struct; there is no kure setter for it
issuer := certmanager.CreateIssuer("vault", "default")
issuer.Spec.Vault = &certv1.VaultIssuer{
Server: "https://vault.example.com:8200",
Path: "pki/sign/example",
Auth: certv1.VaultAuth{TokenSecretRef: &key},
}
fmt.Println(issuer.Spec.Vault.Auth.TokenSecretRef.Name, issuer.Spec.Vault.Auth.TokenSecretRef.Key)
}
Output: secret-name key-name
Example (ArchitectureSecrets) ¶
package main
import (
"fmt"
"github.com/go-kure/kure/pkg/kubernetes"
"github.com/go-kure/kure/pkg/kubernetes/certmanager"
)
func main() {
// NEVER do this - a literal secret in the program that generates the manifests
// is a literal secret in the Git repository those manifests are committed to.
secret := kubernetes.CreateSecret("db-credentials", "default")
secret.Data = map[string][]byte{"password": []byte("hunter2")} // WRONG
// CORRECT approach - name the secret, let the cluster hold the value
cert := certmanager.CreateCertificate("tls-cert", "default")
cert.Spec.SecretName = "tls-cert-secret" // where cert-manager writes the key
fmt.Println(len(secret.Data), cert.Spec.SecretName)
}
Output: 1 tls-cert-secret
Index ¶
- func AddACMEIssuerSolver(issuer *cmacme.ACMEIssuer, solver cmacme.ACMEChallengeSolver)
- func AddCertificateDNSName(obj *certv1.Certificate, dns string)
- func CreateCertificate(name, namespace string) *certmanagerv1.Certificate
- func CreateCertificateRequest(name, namespace string) *certmanagerv1.CertificateRequest
- func CreateChallenge(name, namespace string) *acmev1.Challenge
- func CreateClusterIssuer(name string) *certmanagerv1.ClusterIssuer
- func CreateIssuer(name, namespace string) *certmanagerv1.Issuer
- func CreateOrder(name, namespace string) *acmev1.Order
- func SetCertificateDuration(obj *certv1.Certificate, dur *metav1.Duration)
- func SetCertificateRenewBefore(obj *certv1.Certificate, dur *metav1.Duration)
- func SetClusterIssuerACME(obj *certv1.ClusterIssuer, acme *cmacme.ACMEIssuer)
- func SetClusterIssuerCA(obj *certv1.ClusterIssuer, ca *certv1.CAIssuer)
- func SetIssuerACME(obj *certv1.Issuer, acme *cmacme.ACMEIssuer)
- func SetIssuerCA(obj *certv1.Issuer, ca *certv1.CAIssuer)
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AddACMEIssuerSolver ¶
func AddACMEIssuerSolver(issuer *cmacme.ACMEIssuer, solver cmacme.ACMEChallengeSolver)
AddACMEIssuerSolver appends a challenge solver to the ACME issuer configuration, which is the value SetIssuerACME / SetClusterIssuerACME take.
Example ¶
package main
import (
"fmt"
cmacme "github.com/cert-manager/cert-manager/pkg/apis/acme/v1"
cmmeta "github.com/cert-manager/cert-manager/pkg/apis/meta/v1"
"github.com/go-kure/kure/pkg/kubernetes/certmanager"
)
func main() {
issuer := certmanager.CreateIssuer("letsencrypt", "default")
acme := &cmacme.ACMEIssuer{Server: "https://acme-v02.api.letsencrypt.org/directory", Email: "admin@example.com"}
certmanager.AddACMEIssuerSolver(acme, cmacme.ACMEChallengeSolver{
DNS01: &cmacme.ACMEChallengeSolverDNS01{
Cloudflare: &cmacme.ACMEIssuerDNS01ProviderCloudflare{
Email: "admin@example.com",
APIToken: &cmmeta.SecretKeySelector{
LocalObjectReference: cmmeta.LocalObjectReference{Name: "cf-api-token"},
Key: "api-token",
},
},
},
})
certmanager.SetIssuerACME(issuer, acme)
fmt.Println(issuer.Spec.ACME.Solvers[0].DNS01.Cloudflare.APIToken.Name)
}
Output: cf-api-token
func AddCertificateDNSName ¶
func AddCertificateDNSName(obj *certv1.Certificate, dns string)
AddCertificateDNSName appends a DNS name to the Certificate spec.
Example ¶
package main
import (
"fmt"
"time"
cmacme "github.com/cert-manager/cert-manager/pkg/apis/acme/v1"
certv1 "github.com/cert-manager/cert-manager/pkg/apis/certmanager/v1"
metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
"github.com/go-kure/kure/pkg/kubernetes"
"github.com/go-kure/kure/pkg/kubernetes/certmanager"
)
func main() {
cert := certmanager.CreateCertificate("my-cert", "default")
issuer := certmanager.CreateIssuer("letsencrypt", "default")
caIssuer := certmanager.CreateIssuer("internal-ca", "default")
clusterIssuer := certmanager.CreateClusterIssuer("letsencrypt-prod")
caClusterIssuer := certmanager.CreateClusterIssuer("internal-ca")
acmeConfig := &cmacme.ACMEIssuer{Server: "https://acme-v02.api.letsencrypt.org/directory"}
caConfig := &certv1.CAIssuer{SecretName: "ca-key-pair"}
// Replace the whole Certificate spec
cert.Spec = certv1.CertificateSpec{SecretName: "my-cert-tls", DNSNames: []string{"example.com"}}
// Append to the DNS names, set the pointer-typed durations
certmanager.AddCertificateDNSName(cert, "alt.example.com")
certmanager.SetCertificateDuration(cert, &metav1.Duration{Duration: 2160 * time.Hour})
certmanager.SetCertificateRenewBefore(cert, &metav1.Duration{Duration: 360 * time.Hour})
// Labels and annotations use the generic helpers, which work over any object
// with ObjectMeta -- this package carries no per-kind metadata helpers
kubernetes.AddLabel(cert, "app", "my-app")
kubernetes.AddAnnotation(issuer, "note", "production")
// Update issuer configuration: one arm per issuer
certmanager.SetIssuerACME(issuer, acmeConfig)
certmanager.SetIssuerCA(caIssuer, caConfig)
certmanager.SetClusterIssuerACME(clusterIssuer, acmeConfig)
certmanager.SetClusterIssuerCA(caClusterIssuer, caConfig)
fmt.Println(cert.Spec.DNSNames, cert.Spec.RenewBefore.Duration, caIssuer.Spec.CA.SecretName)
}
Output: [example.com alt.example.com] 360h0m0s ca-key-pair
func CreateCertificate ¶
func CreateCertificate(name, namespace string) *certmanagerv1.Certificate
CreateCertificate returns a cert-manager.io/v1 Certificate carrying TypeMeta and identity only.
Example ¶
package main
import (
"fmt"
"github.com/go-kure/kure/pkg/kubernetes/certmanager"
)
func main() {
obj := certmanager.CreateCertificate("my-cert", "default")
cl := certmanager.CreateClusterIssuer("letsencrypt-prod")
fmt.Println(obj.Kind, obj.Namespace+"/"+obj.Name, cl.Kind, cl.Name)
}
Output: Certificate default/my-cert ClusterIssuer letsencrypt-prod
Example (Spec) ¶
package main
import (
"fmt"
"time"
certv1 "github.com/cert-manager/cert-manager/pkg/apis/certmanager/v1"
cmmeta "github.com/cert-manager/cert-manager/pkg/apis/meta/v1"
metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
"github.com/go-kure/kure/pkg/kubernetes/certmanager"
)
func main() {
cert := certmanager.CreateCertificate("my-cert", "default")
cert.Spec = certv1.CertificateSpec{
SecretName: "my-cert-tls",
IssuerRef: cmmeta.IssuerReference{Name: "letsencrypt", Kind: "ClusterIssuer"},
DNSNames: []string{"example.com", "www.example.com"},
Duration: &metav1.Duration{Duration: 2160 * time.Hour},
}
fmt.Println(cert.Spec.SecretName, cert.Spec.DNSNames, cert.Spec.Duration.Duration)
}
Output: my-cert-tls [example.com www.example.com] 2160h0m0s
func CreateCertificateRequest ¶
func CreateCertificateRequest(name, namespace string) *certmanagerv1.CertificateRequest
CreateCertificateRequest returns a cert-manager.io/v1 CertificateRequest carrying TypeMeta and identity only.
func CreateChallenge ¶
CreateChallenge returns a acme.cert-manager.io/v1 Challenge carrying TypeMeta and identity only.
func CreateClusterIssuer ¶
func CreateClusterIssuer(name string) *certmanagerv1.ClusterIssuer
CreateClusterIssuer returns a cluster-scoped cert-manager.io/v1 ClusterIssuer carrying TypeMeta and identity only.
func CreateIssuer ¶
func CreateIssuer(name, namespace string) *certmanagerv1.Issuer
CreateIssuer returns a cert-manager.io/v1 Issuer carrying TypeMeta and identity only.
Example (OtherArms) ¶
package main
import (
"fmt"
certv1 "github.com/cert-manager/cert-manager/pkg/apis/certmanager/v1"
"github.com/go-kure/kure/pkg/kubernetes/certmanager"
)
func main() {
vault := certmanager.CreateIssuer("vault", "default")
vault.Spec.Vault = &certv1.VaultIssuer{Server: "https://vault.example.com", Path: "pki/sign/example"}
selfSigned := certmanager.CreateIssuer("self-signed", "default")
selfSigned.Spec.SelfSigned = &certv1.SelfSignedIssuer{}
fmt.Println(vault.Spec.Vault.Path, selfSigned.Spec.SelfSigned != nil)
}
Output: pki/sign/example true
func CreateOrder ¶
CreateOrder returns a acme.cert-manager.io/v1 Order carrying TypeMeta and identity only.
func SetCertificateDuration ¶
func SetCertificateDuration(obj *certv1.Certificate, dur *metav1.Duration)
SetCertificateDuration sets the desired certificate duration.
func SetCertificateRenewBefore ¶
func SetCertificateRenewBefore(obj *certv1.Certificate, dur *metav1.Duration)
SetCertificateRenewBefore sets the renewBefore field of the certificate spec.
func SetClusterIssuerACME ¶
func SetClusterIssuerACME(obj *certv1.ClusterIssuer, acme *cmacme.ACMEIssuer)
SetClusterIssuerACME sets the ACME config on the ClusterIssuer.
func SetClusterIssuerCA ¶
func SetClusterIssuerCA(obj *certv1.ClusterIssuer, ca *certv1.CAIssuer)
SetClusterIssuerCA sets the CA configuration on the ClusterIssuer spec.
Example ¶
package main
import (
"fmt"
certv1 "github.com/cert-manager/cert-manager/pkg/apis/certmanager/v1"
"github.com/go-kure/kure/pkg/kubernetes/certmanager"
)
func main() {
clusterIssuer := certmanager.CreateClusterIssuer("letsencrypt-prod")
certmanager.SetClusterIssuerCA(clusterIssuer, &certv1.CAIssuer{SecretName: "ca-key-pair"})
fmt.Println(clusterIssuer.Spec.CA.SecretName)
}
Output: ca-key-pair
func SetIssuerACME ¶
func SetIssuerACME(obj *certv1.Issuer, acme *cmacme.ACMEIssuer)
SetIssuerACME sets the ACME configuration on the issuer spec.
Example ¶
package main
import (
"fmt"
cmacme "github.com/cert-manager/cert-manager/pkg/apis/acme/v1"
cmmeta "github.com/cert-manager/cert-manager/pkg/apis/meta/v1"
"k8s.io/utils/ptr"
"github.com/go-kure/kure/pkg/kubernetes/certmanager"
)
func main() {
issuer := certmanager.CreateIssuer("letsencrypt", "default")
certmanager.SetIssuerACME(issuer, &cmacme.ACMEIssuer{
Server: "https://acme-v02.api.letsencrypt.org/directory",
Email: "admin@example.com",
PrivateKey: cmmeta.SecretKeySelector{
LocalObjectReference: cmmeta.LocalObjectReference{Name: "letsencrypt-account-key"},
},
Solvers: []cmacme.ACMEChallengeSolver{{
HTTP01: &cmacme.ACMEChallengeSolverHTTP01{
Ingress: &cmacme.ACMEChallengeSolverHTTP01Ingress{IngressClassName: ptr.To("nginx")},
},
}},
})
fmt.Println(issuer.Spec.ACME.Email, *issuer.Spec.ACME.Solvers[0].HTTP01.Ingress.IngressClassName)
}
Output: admin@example.com nginx
Types ¶
This section is empty.