From aacaaa2cd854331510b226d953a7aa0f93bf4308 Mon Sep 17 00:00:00 2001 From: James Munnelly Date: Wed, 24 Jun 2020 12:10:25 +0100 Subject: [PATCH 01/12] Update API type documentation for 'certmanager' and 'meta' API groups Signed-off-by: James Munnelly --- pkg/apis/acme/v1alpha2/types.go | 5 - pkg/apis/certmanager/v1alpha2/types.go | 49 +++++++-- .../certmanager/v1alpha2/types_certificate.go | 75 +++++++++---- .../v1alpha2/types_certificaterequest.go | 32 ++++-- pkg/apis/certmanager/v1alpha2/types_issuer.go | 91 +++++++++++---- pkg/apis/certmanager/v1alpha3/types.go | 36 ++++-- .../certmanager/v1alpha3/types_certificate.go | 71 ++++++++---- .../v1alpha3/types_certificaterequest.go | 38 +++++-- pkg/apis/certmanager/v1alpha3/types_issuer.go | 91 +++++++++++---- pkg/apis/meta/v1/types.go | 12 +- pkg/internal/apis/certmanager/types.go | 102 +++++++++++++++-- .../apis/certmanager/types_certificate.go | 98 ++++++++++++----- .../certmanager/types_certificaterequest.go | 32 ++++-- pkg/internal/apis/certmanager/types_issuer.go | 104 ++++++++++++------ pkg/internal/apis/meta/types.go | 16 ++- 15 files changed, 637 insertions(+), 215 deletions(-) diff --git a/pkg/apis/acme/v1alpha2/types.go b/pkg/apis/acme/v1alpha2/types.go index edf94b29c..518ec5a79 100644 --- a/pkg/apis/acme/v1alpha2/types.go +++ b/pkg/apis/acme/v1alpha2/types.go @@ -36,8 +36,3 @@ const ( // of ingress on the created Certificate resource IngressEditInPlaceAnnotationKey = "acme.cert-manager.io/http01-edit-in-place" ) - -const ( - OrderKind = "Order" - ChallengeKind = "Challenge" -) diff --git a/pkg/apis/certmanager/v1alpha2/types.go b/pkg/apis/certmanager/v1alpha2/types.go index 5612f43dd..91459d51a 100644 --- a/pkg/apis/certmanager/v1alpha2/types.go +++ b/pkg/apis/certmanager/v1alpha2/types.go @@ -16,20 +16,39 @@ limitations under the License. package v1alpha2 -// Annotation names for Secrets +// Common annotation keys added to resources const ( - AltNamesAnnotationKey = "cert-manager.io/alt-names" - IPSANAnnotationKey = "cert-manager.io/ip-sans" - URISANAnnotationKey = "cert-manager.io/uri-sans" - CommonNameAnnotationKey = "cert-manager.io/common-name" - IssuerNameAnnotationKey = "cert-manager.io/issuer-name" - IssuerKindAnnotationKey = "cert-manager.io/issuer-kind" - IssuerGroupAnnotationKey = "cert-manager.io/issuer-group" - CertificateNameKey = "cert-manager.io/certificate-name" + // Annotation key for DNS subjectAltNames + AltNamesAnnotationKey = "cert-manager.io/alt-names" + + // Annotation key for IP subjectAltNames + IPSANAnnotationKey = "cert-manager.io/ip-sans" + + // Annotation key for URI subjectAltNames + URISANAnnotationKey = "cert-manager.io/uri-sans" + + // Annotation key for certificate common name + CommonNameAnnotationKey = "cert-manager.io/common-name" + + // Annotation key the 'name' of the Issuer resource + IssuerNameAnnotationKey = "cert-manager.io/issuer-name" + + // Annotation key the 'kind' of the Issuer resource + IssuerKindAnnotationKey = "cert-manager.io/issuer-kind" + + // Annotation key the 'group' of the Issuer resource + IssuerGroupAnnotationKey = "cert-manager.io/issuer-group" + + // Annotation key the name of the certificate that a resource is related to + CertificateNameKey = "cert-manager.io/certificate-name" + + // Annotation key used to denote whether a Secret is named on a Certificate + // as a 'next private key' Secret resource IsNextPrivateKeySecretLabelKey = "cert-manager.io/next-private-key" ) // Deprecated annotation names for Secrets +// These will be removed in a future release. const ( DeprecatedIssuerNameAnnotationKey = "certmanager.k8s.io/issuer-name" DeprecatedIssuerKindAnnotationKey = "certmanager.k8s.io/issuer-kind" @@ -55,7 +74,12 @@ const ( // Annotation names for CertificateRequests const ( - CRPrivateKeyAnnotationKey = "cert-manager.io/private-key-secret-name" + // Annotation added to CertificateRequest resources to denote the name of + // a Secret resource containing the private key used to sign the CSR stored + // on the resource. + // This annotation *may* not be present, and is used by the 'self signing' + // issuer type to self-sign certificates. + CertificateRequestPrivateKeyAnnotationKey = "cert-manager.io/private-key-secret-name" // Annotation to declare the CertificateRequest "revision", beloning to a Certificate Resource CertificateRequestRevisionAnnotationKey = "cert-manager.io/certificate-revision" @@ -70,6 +94,7 @@ const ( IssueTemporaryCertificateAnnotation = "cert-manager.io/issue-temporary-certificate" ) +// Common/known resource kinds const ( ClusterIssuerKind = "ClusterIssuer" IssuerKind = "Issuer" @@ -80,7 +105,7 @@ const ( const ( // WantInjectAnnotation is the annotation that specifies that a particular // object wants injection of CAs. It takes the form of a reference to a certificate - // as namespace/name. The certificate is expected to have the is-serving-for annotations. + // as namespace/name. WantInjectAnnotation = "cert-manager.io/inject-ca-from" // WantInjectAPIServerCAAnnotation, if set to "true", will make the cainjector @@ -90,7 +115,7 @@ const ( WantInjectAPIServerCAAnnotation = "cert-manager.io/inject-apiserver-ca" // WantInjectFromSecretAnnotation is the annotation that specifies that a particular - // object wants injection of CAs. It takes the form of a reference to a Secret + // object wants injection of CAs. It takes the form of a reference to a Secret // as namespace/name. WantInjectFromSecretAnnotation = "cert-manager.io/inject-ca-from-secret" diff --git a/pkg/apis/certmanager/v1alpha2/types_certificate.go b/pkg/apis/certmanager/v1alpha2/types_certificate.go index dd9d62f19..79a1088c3 100644 --- a/pkg/apis/certmanager/v1alpha2/types_certificate.go +++ b/pkg/apis/certmanager/v1alpha2/types_certificate.go @@ -38,7 +38,10 @@ type Certificate struct { metav1.TypeMeta `json:",inline"` metav1.ObjectMeta `json:"metadata,omitempty"` - Spec CertificateSpec `json:"spec,omitempty"` + // Desired state of the Certificate resource. + Spec CertificateSpec `json:"spec,omitempty"` + + // Status of the Certificate, set and managed automatically. Status CertificateStatus `json:"status,omitempty"` } @@ -56,7 +59,10 @@ type CertificateList struct { type KeyAlgorithm string const ( - RSAKeyAlgorithm KeyAlgorithm = "rsa" + // Denotes the RSA private key type + RSAKeyAlgorithm KeyAlgorithm = "rsa" + + // Denotes the ECDSA private key type ECDSAKeyAlgorithm KeyAlgorithm = "ecdsa" ) @@ -64,13 +70,19 @@ const ( type KeyEncoding string const ( + // PKCS1 key encoding will produce PEM files that include the type of + // private key as part of the PEM header, e.g. "BEGIN RSA PRIVATE KEY". + // If the keyAlgorithm is set to 'ECDSA', this will produce private keys + // that use the "BEGIN EC PRIVATE KEY" header. PKCS1 KeyEncoding = "pkcs1" + + // PKCS8 key encoding will produce PEM files with the "BEGIN PRIVATE KEY" + // header. It encodes the keyAlgorithm of the private key as part of the + // DER encoded PEM block. PKCS8 KeyEncoding = "pkcs8" ) // CertificateSpec defines the desired state of Certificate. -// A valid Certificate requires at least one of a CommonName, DNSName, or -// URISAN to be valid. type CertificateSpec struct { // Full X509 name specification (https://golang.org/pkg/crypto/x509/pkix/#Name). // +optional @@ -84,37 +96,46 @@ type CertificateSpec struct { // +optional CommonName string `json:"commonName,omitempty"` - // Organization is the organization to be used on the Certificate + // Organization is the organization to be used on the Certificate. // +optional Organization []string `json:"organization,omitempty"` - // Certificate default Duration + // The requested 'duration' (i.e. lifetime) of the Certificate. + // This option may be ignored/overridden by some issuer types. + // If overridden and `renewBefore` is greater than the actual certificate + // duration, the certificate will be automatically renewed 2/3rds of the + // way through the certificate's duration. // +optional Duration *metav1.Duration `json:"duration,omitempty"` - // Certificate renew before expiration duration + // The amount of time before the currently issued certificate's `notAfter` + // time that cert-manager will begin to attempt to renew the certificate. + // If this value is greater than the total duration of the certificate + // (i.e. notAfter - notBefore), it will be automatically renewed 2/3rds of + // the way through the certificate's duration. // +optional RenewBefore *metav1.Duration `json:"renewBefore,omitempty"` - // DNSNames is a list of subject alt names to be used on the Certificate. + // DNSNames is a list of DNS subjectAltNames to be set on the Certificate. // +optional DNSNames []string `json:"dnsNames,omitempty"` - // IPAddresses is a list of IP addresses to be used on the Certificate + // IPAddresses is a list of IP address subjectAltNames to be set on the Certificate. // +optional IPAddresses []string `json:"ipAddresses,omitempty"` - // URISANs is a list of URI Subject Alternative Names to be set on this - // Certificate. + // URISANs is a list of URI subjectAltNames to be set on the Certificate. // +optional URISANs []string `json:"uriSANs,omitempty"` - // EmailSANs is a list of Email Subject Alternative Names to be set on this - // Certificate. + // EmailSANs is a list of email subjectAltNames to be set on the Certificate. // +optional EmailSANs []string `json:"emailSANs,omitempty"` - // SecretName is the name of the secret resource to store this secret in + // SecretName is the name of the secret resource that will be automatically + // created and managed by this Certificate resource. + // It will be populated with a private key and certificate, signed by the + // denoted issuer. SecretName string `json:"secretName"` // Keystores configures additional keystore output formats stored in the @@ -131,18 +152,21 @@ type CertificateSpec struct { IssuerRef cmmeta.ObjectReference `json:"issuerRef"` // IsCA will mark this Certificate as valid for signing. - // This implies that the 'cert sign' usage is set + // This will automatically add the `cert sign` usage to the list of `usages`. // +optional IsCA bool `json:"isCA,omitempty"` - // Usages is the set of x509 actions that are enabled for a given key. Defaults are ('digital signature', 'key encipherment') if empty + // Usages is the set of x509 usages that are requested for the certificate. + // Defaults to `digital signature` and `key encipherment` if not specified. // +optional Usages []KeyUsage `json:"usages,omitempty"` // KeySize is the key bit size of the corresponding private key for this certificate. - // If provided, value must be between 2048 and 8192 inclusive when KeyAlgorithm is - // empty or is set to "rsa", and value must be one of (256, 384, 521) when - // KeyAlgorithm is set to "ecdsa". + // If `keyAlgorithm` is set to `RSA`, valid values are `2048`, `4096` or `8192`, + // and will default to `2048` if not specified. + // If `keyAlgorithm` is set to `ECDSA`, valid values are `256`, `384` or `521`, + // and will default to `256` if not specified. + // No other values are allowed. // +kubebuilder:validation:ExclusiveMaximum=false // +kubebuilder:validation:Maximum=8192 // +kubebuilder:validation:ExclusiveMinimum=false @@ -152,7 +176,7 @@ type CertificateSpec struct { // KeyAlgorithm is the private key algorithm of the corresponding private key // for this certificate. If provided, allowed values are either "rsa" or "ecdsa" - // If KeyAlgorithm is specified and KeySize is not provided, + // If `keyAlgorithm` is specified and `keySize` is not provided, // key size of 256 will be used for "ecdsa" key algorithm and // key size of 2048 will be used for "rsa" key algorithm. // +optional @@ -271,9 +295,16 @@ type PKCS12Keystore struct { // CertificateStatus defines the observed state of Certificate type CertificateStatus struct { + // List of status conditions to indicate the status of certificates. + // Known condition types are `Ready` and `Issuing`. // +optional Conditions []CertificateCondition `json:"conditions,omitempty"` + // LastFailureTime is the time as recorded by the Certificate controller + // of the most recently failure to complete a CertificateRequest for this + // certificate resource. + // If set, cert-manager will not re-request another Certificate until + // 1 hour has elapsed from this time. // +optional LastFailureTime *metav1.Time `json:"lastFailureTime,omitempty"` @@ -283,7 +314,7 @@ type CertificateStatus struct { NotBefore *metav1.Time `json:"notBefore,omitempty"` // The expiration time of the certificate stored in the secret named - // by this resource in spec.secretName. + // by this resource in `spec.secretName`. // +optional NotAfter *metav1.Time `json:"notAfter,omitempty"` @@ -322,7 +353,7 @@ type CertificateStatus struct { // CertificateCondition contains condition information for an Certificate. type CertificateCondition struct { - // Type of the condition, currently ('Ready'). + // Type of the condition, known values are ('Ready', `Issuing`). Type CertificateConditionType `json:"type"` // Status of the condition, one of ('True', 'False', 'Unknown'). diff --git a/pkg/apis/certmanager/v1alpha2/types_certificaterequest.go b/pkg/apis/certmanager/v1alpha2/types_certificaterequest.go index ad46598c6..7489f45b3 100644 --- a/pkg/apis/certmanager/v1alpha2/types_certificaterequest.go +++ b/pkg/apis/certmanager/v1alpha2/types_certificaterequest.go @@ -23,9 +23,16 @@ import ( ) const ( + // Pending indicates that a CertificateRequest is still in progress. CertificateRequestReasonPending = "Pending" - CertificateRequestReasonFailed = "Failed" - CertificateRequestReasonIssued = "Issued" + + // Failed indicates that a CertificateRequest has failed, either due to + // timing out or some other critical failure. + CertificateRequestReasonFailed = "Failed" + + // Issued indicates that a CertificateRequest has been completed, and that + // the `status.certificate` field is set. + CertificateRequestReasonIssued = "Issued" ) // +genclient @@ -43,7 +50,10 @@ type CertificateRequest struct { metav1.TypeMeta `json:",inline"` metav1.ObjectMeta `json:"metadata,omitempty"` - Spec CertificateRequestSpec `json:"spec,omitempty"` + // Desired state of the CertificateRequest resource. + Spec CertificateRequestSpec `json:"spec,omitempty"` + + // Status of the CertificateRequest, set and managed automatically. Status CertificateRequestStatus `json:"status,omitempty"` } @@ -59,7 +69,8 @@ type CertificateRequestList struct { // CertificateRequestSpec defines the desired state of CertificateRequest type CertificateRequestSpec struct { - // Requested certificate default Duration + // The requested 'duration' (i.e. lifetime) of the Certificate. + // This option may be ignored/overridden by some issuer types. // +optional Duration *metav1.Duration `json:"duration,omitempty"` @@ -75,13 +86,13 @@ type CertificateRequestSpec struct { // Byte slice containing the PEM encoded CertificateSigningRequest CSRPEM []byte `json:"csr"` - // IsCA will mark the resulting certificate as valid for signing. This - // implies that the 'cert sign' usage is set + // IsCA will mark this Certificate as valid for signing. + // This will automatically add the `cert sign` usage to the list of `usages`. // +optional IsCA bool `json:"isCA,omitempty"` - // Usages is the set of x509 actions that are enabled for a given key. - // Defaults are ('digital signature', 'key encipherment') if empty + // Usages is the set of x509 usages that are requested for the certificate. + // Defaults to `digital signature` and `key encipherment` if not specified. // +optional Usages []KeyUsage `json:"usages,omitempty"` } @@ -89,6 +100,8 @@ type CertificateRequestSpec struct { // CertificateStatus defines the observed state of CertificateRequest and // resulting signed certificate. type CertificateRequestStatus struct { + // List of status conditions to indicate the status of a CertificateRequest. + // Known condition types are `Ready` and `InvalidRequest`. // +optional Conditions []CertificateRequestCondition `json:"conditions,omitempty"` @@ -99,6 +112,7 @@ type CertificateRequestStatus struct { // Byte slice containing the PEM encoded certificate authority of the signed // certificate. + // If not specified, the CA is assumed to be unknown/not available. // +optional CA []byte `json:"ca,omitempty"` @@ -110,7 +124,7 @@ type CertificateRequestStatus struct { // CertificateRequestCondition contains condition information for a CertificateRequest. type CertificateRequestCondition struct { - // Type of the condition, currently ('Ready', 'InvalidRequest'). + // Type of the condition, known values are ('Ready', 'InvalidRequest'). Type CertificateRequestConditionType `json:"type"` // Status of the condition, one of ('True', 'False', 'Unknown'). diff --git a/pkg/apis/certmanager/v1alpha2/types_issuer.go b/pkg/apis/certmanager/v1alpha2/types_issuer.go index 371b9659a..050cb1a83 100644 --- a/pkg/apis/certmanager/v1alpha2/types_issuer.go +++ b/pkg/apis/certmanager/v1alpha2/types_issuer.go @@ -28,13 +28,21 @@ import ( // +k8s:openapi-gen=true // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object +// A ClusterIssuer represents a certificate issuing authority which can be +// referenced as part of `issuerRef` fields. +// It is similar to an Issuer, however it is cluster-scoped and therefore can +// be referenced by resources that exist in *any* namespace, not just the same +// namespace as the referent. // +kubebuilder:subresource:status // +kubebuilder:resource:path=clusterissuers,scope=Cluster type ClusterIssuer struct { metav1.TypeMeta `json:",inline"` metav1.ObjectMeta `json:"metadata,omitempty"` - Spec IssuerSpec `json:"spec,omitempty"` + // Desired state of the ClusterIssuer resource. + Spec IssuerSpec `json:"spec,omitempty"` + + // Status of the ClusterIssuer, set and managed automatically. Status IssuerStatus `json:"status,omitempty"` } @@ -52,6 +60,10 @@ type ClusterIssuerList struct { // +k8s:openapi-gen=true // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object +// An Issuer represents a certificate issuing authority which can be +// referenced as part of `issuerRef` fields. +// It is scoped to a single namespace and can therefore only be referenced by +// resources within the same namespace. // +kubebuilder:printcolumn:name="Ready",type="string",JSONPath=".status.conditions[?(@.type==\"Ready\")].status",description="" // +kubebuilder:printcolumn:name="Status",type="string",JSONPath=".status.conditions[?(@.type==\"Ready\")].message",description="" // +kubebuilder:printcolumn:name="Age",type="date",JSONPath=".metadata.creationTimestamp",description="CreationTimestamp is a timestamp representing the server time when this object was created. It is not guaranteed to be set in happens-before order across separate operations. Clients may not set this value. It is represented in RFC3339 form and is in UTC." @@ -61,7 +73,10 @@ type Issuer struct { metav1.TypeMeta `json:",inline"` metav1.ObjectMeta `json:"metadata,omitempty"` - Spec IssuerSpec `json:"spec,omitempty"` + // Desired state of the Issuer resource. + Spec IssuerSpec `json:"spec,omitempty"` + + // Status of the Issuer, set and managed automatically. Status IssuerStatus `json:"status,omitempty"` } @@ -82,23 +97,35 @@ type IssuerSpec struct { } type IssuerConfig struct { + // ACME configures this issuer to communicate with a RFC8555 (ACME) server + // to obtain signed x509 certificates. // +optional ACME *cmacme.ACMEIssuer `json:"acme,omitempty"` + // CA configures this issuer to sign certificates using a signing CA keypair + // stored in a Secret resource. + // This is used to build internal PKIs that are managed by cert-manager. // +optional CA *CAIssuer `json:"ca,omitempty"` + // Vault configures this issuer to sign certificates using a HashiCorp Vault + // PKI backend. // +optional Vault *VaultIssuer `json:"vault,omitempty"` + // SelfSigned configures this issuer to 'self sign' certificates using the + // private key used to create the CertificateRequest object. // +optional SelfSigned *SelfSignedIssuer `json:"selfSigned,omitempty"` + // Venafi configures this issuer to sign certificates using a Venafi TPP + // or Cloud policy zone. // +optional Venafi *VenafiIssuer `json:"venafi,omitempty"` } -// VenafiIssuer describes issuer configuration details for Venafi Cloud. +// Venafi configures this issuer to sign certificates using a Venafi TPP +// or Cloud policy zone. type VenafiIssuer struct { // Zone is the Venafi Policy Zone to use for this issuer. // All requests made to the Venafi platform will be restricted by the named @@ -119,7 +146,8 @@ type VenafiIssuer struct { // VenafiTPP defines connection configuration details for a Venafi TPP instance type VenafiTPP struct { - // URL is the base URL for the Venafi TPP instance + // URL is the base URL for the Venafi TPP instance, for example: + // "https://tpp.example.com/vedsdk". URL string `json:"url"` // CredentialsRef is a reference to a Secret containing the username and @@ -139,7 +167,7 @@ type VenafiTPP struct { // VenafiCloud defines connection configuration details for Venafi Cloud type VenafiCloud struct { - // URL is the base URL for Venafi Cloud + // URL is the base URL for Venafi Cloud, usually: "https://api.venafi.cloud/v1". // +optional URL string `json:"url,omitempty"` @@ -147,6 +175,8 @@ type VenafiCloud struct { APITokenSecretRef cmmeta.SecretKeySelector `json:"apiTokenSecretRef"` } +// SelfSigned configures this issuer to 'self sign' certificates using the +// private key used to create the CertificateRequest object. type SelfSignedIssuer struct { // The CRL distribution points is an X.509 v3 certificate extension which identifies // the location of the CRL from which the revocation of this certificate can be checked. @@ -155,17 +185,20 @@ type SelfSignedIssuer struct { CRLDistributionPoints []string `json:"crlDistributionPoints,omitempty"` } +// Vault configures this issuer to sign certificates using a HashiCorp Vault +// PKI backend. type VaultIssuer struct { - // Vault authentication + // Auth configures how cert-manager authenticates with the Vault server. Auth VaultAuth `json:"auth"` - // Server is the vault connection address + // Server is the connection address for the Vault server, e.g: "https://vault.example.com:8200". Server string `json:"server"` - // Vault URL path to the certificate role + // Path is the mount path of the Vault PKI backend's `sign` endpoint, e.g: + // "my_pki_mount/sign/my-role-name". Path string `json:"path"` - // Base64 encoded CA bundle to validate Vault server certificate. Only used + // PEM encoded CA bundle used to validate Vault server certificate. Only used // if the Server URL is using HTTPS protocol. This parameter is ignored for // plain HTTP protocol connection. If not set the system root certificates // are used to validate the TLS connection. @@ -173,30 +206,37 @@ type VaultIssuer struct { CABundle []byte `json:"caBundle,omitempty"` } -// Vault authentication can be configured: -// - With a secret containing a token. Cert-manager is using this token as-is. -// - With a secret containing a AppRole. This AppRole is used to authenticate to -// Vault and retrieve a token. +// Configuration used to authenticate with a Vault server. +// Only one of `tokenSecretRef`, `appRole` or `kubernetes` may be specified. type VaultAuth struct { - // This Secret contains the Vault token key + // TokenSecretRef authenticates with Vault by presenting a token. // +optional TokenSecretRef *cmmeta.SecretKeySelector `json:"tokenSecretRef,omitempty"` - // This Secret contains a AppRole and Secret + // AppRole authenticates with Vault using the App Role auth mechanism, + // with the role and secret stored in a Kubernetes Secret resource. // +optional AppRole *VaultAppRole `json:"appRole,omitempty"` - // This contains a Role and Secret with a ServiceAccount token to - // authenticate with vault. + // Kubernetes authenticates with Vault by passing the ServiceAccount + // token stored in the named Secret resource to the Vault server. // +optional Kubernetes *VaultKubernetesAuth `json:"kubernetes,omitempty"` } +// AppRole authenticates with Vault using the App Role auth mechanism, +// with the role and secret stored in a Kubernetes Secret resource. type VaultAppRole struct { - // Where the authentication path is mounted in Vault. + // Path where the App Role authentication backend is mounted in Vault, e.g: + // "approle" Path string `json:"path"` - RoleId string `json:"roleId"` + // RoleID configures in the App Role authentication backend when setting + // up the App Role backend. + RoleId string `json:"roleId"` + + // Reference to a key in a Secret that contains the App Role secret used + // to authenticate with Vault. SecretRef cmmeta.SecretKeySelector `json:"secretRef"` } @@ -227,23 +267,28 @@ type CAIssuer struct { // The CRL distribution points is an X.509 v3 certificate extension which identifies // the location of the CRL from which the revocation of this certificate can be checked. - // If not set certificate will be issued without CDP. Values are strings. + // If not set, certificates will be issued without distribution points set. // +optional CRLDistributionPoints []string `json:"crlDistributionPoints,omitempty"` } // IssuerStatus contains status information about an Issuer type IssuerStatus struct { + // List of status conditions to indicate the status of a CertificateRequest. + // Known condition types are `Ready`. // +optional Conditions []IssuerCondition `json:"conditions,omitempty"` + // ACME specific status options. + // This field should only be set if the Issuer is configured to use an ACME + // server to issue certificates. // +optional ACME *cmacme.ACMEIssuerStatus `json:"acme,omitempty"` } // IssuerCondition contains condition information for an Issuer. type IssuerCondition struct { - // Type of the condition, currently ('Ready'). + // Type of the condition, known values are ('Ready'). Type IssuerConditionType `json:"type"` // Status of the condition, one of ('True', 'False', 'Unknown'). @@ -270,6 +315,8 @@ type IssuerConditionType string const ( // IssuerConditionReady represents the fact that a given Issuer condition - // is in ready state. + // is in ready state and able to issue certificates. + // If the `status` of this condition is `False`, CertificateRequest controllers + // should prevent attempts to sign certificates. IssuerConditionReady IssuerConditionType = "Ready" ) diff --git a/pkg/apis/certmanager/v1alpha3/types.go b/pkg/apis/certmanager/v1alpha3/types.go index 2cfff63c2..0e51e2cf6 100644 --- a/pkg/apis/certmanager/v1alpha3/types.go +++ b/pkg/apis/certmanager/v1alpha3/types.go @@ -16,19 +16,39 @@ limitations under the License. package v1alpha3 -// Annotation names for Secrets +// Common annotation keys added to resources const ( - AltNamesAnnotationKey = "cert-manager.io/alt-names" - IPSANAnnotationKey = "cert-manager.io/ip-sans" - URISANAnnotationKey = "cert-manager.io/uri-sans" - CommonNameAnnotationKey = "cert-manager.io/common-name" - IssuerNameAnnotationKey = "cert-manager.io/issuer-name" - IssuerKindAnnotationKey = "cert-manager.io/issuer-kind" + // Annotation key for DNS subjectAltNames + AltNamesAnnotationKey = "cert-manager.io/alt-names" + + // Annotation key for IP subjectAltNames + IPSANAnnotationKey = "cert-manager.io/ip-sans" + + // Annotation key for URI subjectAltNames + URISANAnnotationKey = "cert-manager.io/uri-sans" + + // Annotation key for certificate common name + CommonNameAnnotationKey = "cert-manager.io/common-name" + + // Annotation key the 'name' of the Issuer resource + IssuerNameAnnotationKey = "cert-manager.io/issuer-name" + + // Annotation key the 'kind' of the Issuer resource + IssuerKindAnnotationKey = "cert-manager.io/issuer-kind" + + // Annotation key the 'group' of the Issuer resource IssuerGroupAnnotationKey = "cert-manager.io/issuer-group" - CertificateNameKey = "cert-manager.io/certificate-name" + + // Annotation key the name of the certificate that a resource is related to + CertificateNameKey = "cert-manager.io/certificate-name" + + // Annotation key used to denote whether a Secret is named on a Certificate + // as a 'next private key' Secret resource + IsNextPrivateKeySecretLabelKey = "cert-manager.io/next-private-key" ) // Deprecated annotation names for Secrets +// These will be removed in a future release. const ( DeprecatedIssuerNameAnnotationKey = "certmanager.k8s.io/issuer-name" DeprecatedIssuerKindAnnotationKey = "certmanager.k8s.io/issuer-kind" diff --git a/pkg/apis/certmanager/v1alpha3/types_certificate.go b/pkg/apis/certmanager/v1alpha3/types_certificate.go index 54b3717dd..b5dd61c9f 100644 --- a/pkg/apis/certmanager/v1alpha3/types_certificate.go +++ b/pkg/apis/certmanager/v1alpha3/types_certificate.go @@ -38,7 +38,10 @@ type Certificate struct { metav1.TypeMeta `json:",inline"` metav1.ObjectMeta `json:"metadata,omitempty"` - Spec CertificateSpec `json:"spec,omitempty"` + // Desired state of the Certificate resource. + Spec CertificateSpec `json:"spec,omitempty"` + + // Status of the Certificate, set and managed automatically. Status CertificateStatus `json:"status,omitempty"` } @@ -56,7 +59,10 @@ type CertificateList struct { type KeyAlgorithm string const ( - RSAKeyAlgorithm KeyAlgorithm = "rsa" + // Denotes the RSA private key type + RSAKeyAlgorithm KeyAlgorithm = "rsa" + + // Denotes the ECDSA private key type ECDSAKeyAlgorithm KeyAlgorithm = "ecdsa" ) @@ -64,7 +70,15 @@ const ( type KeyEncoding string const ( + // PKCS1 key encoding will produce PEM files that include the type of + // private key as part of the PEM header, e.g. "BEGIN RSA PRIVATE KEY". + // If the keyAlgorithm is set to 'ECDSA', this will produce private keys + // that use the "BEGIN EC PRIVATE KEY" header. PKCS1 KeyEncoding = "pkcs1" + + // PKCS8 key encoding will produce PEM files with the "BEGIN PRIVATE KEY" + // header. It encodes the keyAlgorithm of the private key as part of the + // DER encoded PEM block. PKCS8 KeyEncoding = "pkcs8" ) @@ -84,33 +98,42 @@ type CertificateSpec struct { // +optional CommonName string `json:"commonName,omitempty"` - // Certificate default Duration + // The requested 'duration' (i.e. lifetime) of the Certificate. + // This option may be ignored/overridden by some issuer types. + // If overridden and `renewBefore` is greater than the actual certificate + // duration, the certificate will be automatically renewed 2/3rds of the + // way through the certificate's duration. // +optional Duration *metav1.Duration `json:"duration,omitempty"` - // Certificate renew before expiration duration + // The amount of time before the currently issued certificate's `notAfter` + // time that cert-manager will begin to attempt to renew the certificate. + // If this value is greater than the total duration of the certificate + // (i.e. notAfter - notBefore), it will be automatically renewed 2/3rds of + // the way through the certificate's duration. // +optional RenewBefore *metav1.Duration `json:"renewBefore,omitempty"` - // DNSNames is a list of subject alt names to be used on the Certificate. + // DNSNames is a list of DNS subjectAltNames to be set on the Certificate. // +optional DNSNames []string `json:"dnsNames,omitempty"` - // IPAddresses is a list of IP addresses to be used on the Certificate + // IPAddresses is a list of IP address subjectAltNames to be set on the Certificate. // +optional IPAddresses []string `json:"ipAddresses,omitempty"` - // URISANs is a list of URI Subject Alternative Names to be set on this - // Certificate. + // URISANs is a list of URI subjectAltNames to be set on the Certificate. // +optional URISANs []string `json:"uriSANs,omitempty"` - // EmailSANs is a list of Email Subject Alternative Names to be set on this - // Certificate. + // EmailSANs is a list of email subjectAltNames to be set on the Certificate. // +optional EmailSANs []string `json:"emailSANs,omitempty"` - // SecretName is the name of the secret resource to store this secret in + // SecretName is the name of the secret resource that will be automatically + // created and managed by this Certificate resource. + // It will be populated with a private key and certificate, signed by the + // denoted issuer. SecretName string `json:"secretName"` // Keystores configures additional keystore output formats stored in the @@ -127,18 +150,21 @@ type CertificateSpec struct { IssuerRef cmmeta.ObjectReference `json:"issuerRef"` // IsCA will mark this Certificate as valid for signing. - // This implies that the 'cert sign' usage is set + // This will automatically add the `cert sign` usage to the list of `usages`. // +optional IsCA bool `json:"isCA,omitempty"` - // Usages is the set of x509 actions that are enabled for a given key. Defaults are ('digital signature', 'key encipherment') if empty + // Usages is the set of x509 usages that are requested for the certificate. + // Defaults to `digital signature` and `key encipherment` if not specified. // +optional Usages []KeyUsage `json:"usages,omitempty"` // KeySize is the key bit size of the corresponding private key for this certificate. - // If provided, value must be between 2048 and 8192 inclusive when KeyAlgorithm is - // empty or is set to "rsa", and value must be one of (256, 384, 521) when - // KeyAlgorithm is set to "ecdsa". + // If `keyAlgorithm` is set to `RSA`, valid values are `2048`, `4096` or `8192`, + // and will default to `2048` if not specified. + // If `keyAlgorithm` is set to `ECDSA`, valid values are `256`, `384` or `521`, + // and will default to `256` if not specified. + // No other values are allowed. // +kubebuilder:validation:ExclusiveMaximum=false // +kubebuilder:validation:Maximum=8192 // +kubebuilder:validation:ExclusiveMinimum=false @@ -148,7 +174,7 @@ type CertificateSpec struct { // KeyAlgorithm is the private key algorithm of the corresponding private key // for this certificate. If provided, allowed values are either "rsa" or "ecdsa" - // If KeyAlgorithm is specified and KeySize is not provided, + // If `keyAlgorithm` is specified and `keySize` is not provided, // key size of 256 will be used for "ecdsa" key algorithm and // key size of 2048 will be used for "rsa" key algorithm. // +optional @@ -270,9 +296,16 @@ type PKCS12Keystore struct { // CertificateStatus defines the observed state of Certificate type CertificateStatus struct { + // List of status conditions to indicate the status of certificates. + // Known condition types are `Ready` and `Issuing`. // +optional Conditions []CertificateCondition `json:"conditions,omitempty"` + // LastFailureTime is the time as recorded by the Certificate controller + // of the most recently failure to complete a CertificateRequest for this + // certificate resource. + // If set, cert-manager will not re-request another Certificate until + // 1 hour has elapsed from this time. // +optional LastFailureTime *metav1.Time `json:"lastFailureTime,omitempty"` @@ -282,7 +315,7 @@ type CertificateStatus struct { NotBefore *metav1.Time `json:"notBefore,omitempty"` // The expiration time of the certificate stored in the secret named - // by this resource in spec.secretName. + // by this resource in `spec.secretName`. // +optional NotAfter *metav1.Time `json:"notAfter,omitempty"` @@ -321,7 +354,7 @@ type CertificateStatus struct { // CertificateCondition contains condition information for an Certificate. type CertificateCondition struct { - // Type of the condition, currently ('Ready'). + // Type of the condition, known values are ('Ready', `Issuing`). Type CertificateConditionType `json:"type"` // Status of the condition, one of ('True', 'False', 'Unknown'). diff --git a/pkg/apis/certmanager/v1alpha3/types_certificaterequest.go b/pkg/apis/certmanager/v1alpha3/types_certificaterequest.go index 69e94e8dc..c58e4081b 100644 --- a/pkg/apis/certmanager/v1alpha3/types_certificaterequest.go +++ b/pkg/apis/certmanager/v1alpha3/types_certificaterequest.go @@ -23,9 +23,16 @@ import ( ) const ( + // Pending indicates that a CertificateRequest is still in progress. CertificateRequestReasonPending = "Pending" - CertificateRequestReasonFailed = "Failed" - CertificateRequestReasonIssued = "Issued" + + // Failed indicates that a CertificateRequest has failed, either due to + // timing out or some other critical failure. + CertificateRequestReasonFailed = "Failed" + + // Issued indicates that a CertificateRequest has been completed, and that + // the `status.certificate` field is set. + CertificateRequestReasonIssued = "Issued" ) // +genclient @@ -43,7 +50,10 @@ type CertificateRequest struct { metav1.TypeMeta `json:",inline"` metav1.ObjectMeta `json:"metadata,omitempty"` - Spec CertificateRequestSpec `json:"spec,omitempty"` + // Desired state of the CertificateRequest resource. + Spec CertificateRequestSpec `json:"spec,omitempty"` + + // Status of the CertificateRequest, set and managed automatically. Status CertificateRequestStatus `json:"status,omitempty"` } @@ -59,7 +69,8 @@ type CertificateRequestList struct { // CertificateRequestSpec defines the desired state of CertificateRequest type CertificateRequestSpec struct { - // Requested certificate default Duration + // The requested 'duration' (i.e. lifetime) of the Certificate. + // This option may be ignored/overridden by some issuer types. // +optional Duration *metav1.Duration `json:"duration,omitempty"` @@ -75,13 +86,13 @@ type CertificateRequestSpec struct { // Byte slice containing the PEM encoded CertificateSigningRequest CSRPEM []byte `json:"csr"` - // IsCA will mark the resulting certificate as valid for signing. This - // implies that the 'cert sign' usage is set + // IsCA will mark this Certificate as valid for signing. + // This will automatically add the `cert sign` usage to the list of `usages`. // +optional IsCA bool `json:"isCA,omitempty"` - // Usages is the set of x509 actions that are enabled for a given key. - // Defaults are ('digital signature', 'key encipherment') if empty + // Usages is the set of x509 usages that are requested for the certificate. + // Defaults to `digital signature` and `key encipherment` if not specified. // +optional Usages []KeyUsage `json:"usages,omitempty"` } @@ -89,6 +100,8 @@ type CertificateRequestSpec struct { // CertificateStatus defines the observed state of CertificateRequest and // resulting signed certificate. type CertificateRequestStatus struct { + // List of status conditions to indicate the status of a CertificateRequest. + // Known condition types are `Ready` and `InvalidRequest`. // +optional Conditions []CertificateRequestCondition `json:"conditions,omitempty"` @@ -99,6 +112,7 @@ type CertificateRequestStatus struct { // Byte slice containing the PEM encoded certificate authority of the signed // certificate. + // If not specified, the CA is assumed to be unknown/not available. // +optional CA []byte `json:"ca,omitempty"` @@ -110,7 +124,7 @@ type CertificateRequestStatus struct { // CertificateRequestCondition contains condition information for a CertificateRequest. type CertificateRequestCondition struct { - // Type of the condition, currently ('Ready', 'InvalidRequest'). + // Type of the condition, known values are ('Ready', 'InvalidRequest'). Type CertificateRequestConditionType `json:"type"` // Status of the condition, one of ('True', 'False', 'Unknown'). @@ -140,4 +154,10 @@ const ( // This is defined as: // - The target certificate exists in CertificateRequest.Status CertificateRequestConditionReady CertificateRequestConditionType = "Ready" + + // CertificateRequestConditionInvalidRequest indicates that a certificate + // signer has refused to sign the request due to at least one of the input + // parameters being invalid. Additional information about why the request + // was rejected can be found in the `reason` and `message` fields. + CertificateRequestConditionInvalidRequest CertificateRequestConditionType = "InvalidRequest" ) diff --git a/pkg/apis/certmanager/v1alpha3/types_issuer.go b/pkg/apis/certmanager/v1alpha3/types_issuer.go index 8b5b4db40..480a4a960 100644 --- a/pkg/apis/certmanager/v1alpha3/types_issuer.go +++ b/pkg/apis/certmanager/v1alpha3/types_issuer.go @@ -28,13 +28,21 @@ import ( // +k8s:openapi-gen=true // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object +// A ClusterIssuer represents a certificate issuing authority which can be +// referenced as part of `issuerRef` fields. +// It is similar to an Issuer, however it is cluster-scoped and therefore can +// be referenced by resources that exist in *any* namespace, not just the same +// namespace as the referent. // +kubebuilder:subresource:status // +kubebuilder:resource:path=clusterissuers,scope=Cluster type ClusterIssuer struct { metav1.TypeMeta `json:",inline"` metav1.ObjectMeta `json:"metadata,omitempty"` - Spec IssuerSpec `json:"spec,omitempty"` + // Desired state of the ClusterIssuer resource. + Spec IssuerSpec `json:"spec,omitempty"` + + // Status of the ClusterIssuer, set and managed automatically. Status IssuerStatus `json:"status,omitempty"` } @@ -52,6 +60,10 @@ type ClusterIssuerList struct { // +k8s:openapi-gen=true // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object +// An Issuer represents a certificate issuing authority which can be +// referenced as part of `issuerRef` fields. +// It is scoped to a single namespace and can therefore only be referenced by +// resources within the same namespace. // +kubebuilder:printcolumn:name="Ready",type="string",JSONPath=".status.conditions[?(@.type==\"Ready\")].status",description="" // +kubebuilder:printcolumn:name="Status",type="string",JSONPath=".status.conditions[?(@.type==\"Ready\")].message",description="" // +kubebuilder:printcolumn:name="Age",type="date",JSONPath=".metadata.creationTimestamp",description="CreationTimestamp is a timestamp representing the server time when this object was created. It is not guaranteed to be set in happens-before order across separate operations. Clients may not set this value. It is represented in RFC3339 form and is in UTC." @@ -61,7 +73,10 @@ type Issuer struct { metav1.TypeMeta `json:",inline"` metav1.ObjectMeta `json:"metadata,omitempty"` - Spec IssuerSpec `json:"spec,omitempty"` + // Desired state of the Issuer resource. + Spec IssuerSpec `json:"spec,omitempty"` + + // Status of the Issuer, set and managed automatically. Status IssuerStatus `json:"status,omitempty"` } @@ -82,23 +97,35 @@ type IssuerSpec struct { } type IssuerConfig struct { + // ACME configures this issuer to communicate with a RFC8555 (ACME) server + // to obtain signed x509 certificates. // +optional ACME *cmacme.ACMEIssuer `json:"acme,omitempty"` + // CA configures this issuer to sign certificates using a signing CA keypair + // stored in a Secret resource. + // This is used to build internal PKIs that are managed by cert-manager. // +optional CA *CAIssuer `json:"ca,omitempty"` + // Vault configures this issuer to sign certificates using a HashiCorp Vault + // PKI backend. // +optional Vault *VaultIssuer `json:"vault,omitempty"` + // SelfSigned configures this issuer to 'self sign' certificates using the + // private key used to create the CertificateRequest object. // +optional SelfSigned *SelfSignedIssuer `json:"selfSigned,omitempty"` + // Venafi configures this issuer to sign certificates using a Venafi TPP + // or Cloud policy zone. // +optional Venafi *VenafiIssuer `json:"venafi,omitempty"` } -// VenafiIssuer describes issuer configuration details for Venafi Cloud. +// Venafi configures this issuer to sign certificates using a Venafi TPP +// or Cloud policy zone. type VenafiIssuer struct { // Zone is the Venafi Policy Zone to use for this issuer. // All requests made to the Venafi platform will be restricted by the named @@ -119,7 +146,8 @@ type VenafiIssuer struct { // VenafiTPP defines connection configuration details for a Venafi TPP instance type VenafiTPP struct { - // URL is the base URL for the Venafi TPP instance + // URL is the base URL for the Venafi TPP instance, for example: + // "https://tpp.example.com/vedsdk". URL string `json:"url"` // CredentialsRef is a reference to a Secret containing the username and @@ -139,7 +167,7 @@ type VenafiTPP struct { // VenafiCloud defines connection configuration details for Venafi Cloud type VenafiCloud struct { - // URL is the base URL for Venafi Cloud + // URL is the base URL for Venafi Cloud, usually: "https://api.venafi.cloud/v1". // +optional URL string `json:"url,omitempty"` @@ -147,6 +175,8 @@ type VenafiCloud struct { APITokenSecretRef cmmeta.SecretKeySelector `json:"apiTokenSecretRef"` } +// SelfSigned configures this issuer to 'self sign' certificates using the +// private key used to create the CertificateRequest object. type SelfSignedIssuer struct { // The CRL distribution points is an X.509 v3 certificate extension which identifies // the location of the CRL from which the revocation of this certificate can be checked. @@ -155,17 +185,20 @@ type SelfSignedIssuer struct { CRLDistributionPoints []string `json:"crlDistributionPoints,omitempty"` } +// Vault configures this issuer to sign certificates using a HashiCorp Vault +// PKI backend. type VaultIssuer struct { - // Vault authentication + // Auth configures how cert-manager authenticates with the Vault server. Auth VaultAuth `json:"auth"` - // Server is the vault connection address + // Server is the connection address for the Vault server, e.g: "https://vault.example.com:8200". Server string `json:"server"` - // Vault URL path to the certificate role + // Path is the mount path of the Vault PKI backend's `sign` endpoint, e.g: + // "my_pki_mount/sign/my-role-name". Path string `json:"path"` - // Base64 encoded CA bundle to validate Vault server certificate. Only used + // PEM encoded CA bundle used to validate Vault server certificate. Only used // if the Server URL is using HTTPS protocol. This parameter is ignored for // plain HTTP protocol connection. If not set the system root certificates // are used to validate the TLS connection. @@ -173,30 +206,37 @@ type VaultIssuer struct { CABundle []byte `json:"caBundle,omitempty"` } -// Vault authentication can be configured: -// - With a secret containing a token. Cert-manager is using this token as-is. -// - With a secret containing a AppRole. This AppRole is used to authenticate to -// Vault and retrieve a token. +// Configuration used to authenticate with a Vault server. +// Only one of `tokenSecretRef`, `appRole` or `kubernetes` may be specified. type VaultAuth struct { - // This Secret contains the Vault token key + // TokenSecretRef authenticates with Vault by presenting a token. // +optional TokenSecretRef *cmmeta.SecretKeySelector `json:"tokenSecretRef,omitempty"` - // This Secret contains a AppRole and Secret + // AppRole authenticates with Vault using the App Role auth mechanism, + // with the role and secret stored in a Kubernetes Secret resource. // +optional AppRole *VaultAppRole `json:"appRole,omitempty"` - // This contains a Role and Secret with a ServiceAccount token to - // authenticate with vault. + // Kubernetes authenticates with Vault by passing the ServiceAccount + // token stored in the named Secret resource to the Vault server. // +optional Kubernetes *VaultKubernetesAuth `json:"kubernetes,omitempty"` } +// AppRole authenticates with Vault using the App Role auth mechanism, +// with the role and secret stored in a Kubernetes Secret resource. type VaultAppRole struct { - // Where the authentication path is mounted in Vault. + // Path where the App Role authentication backend is mounted in Vault, e.g: + // "approle" Path string `json:"path"` - RoleId string `json:"roleId"` + // RoleID configures in the App Role authentication backend when setting + // up the App Role backend. + RoleId string `json:"roleId"` + + // Reference to a key in a Secret that contains the App Role secret used + // to authenticate with Vault. SecretRef cmmeta.SecretKeySelector `json:"secretRef"` } @@ -227,23 +267,28 @@ type CAIssuer struct { // The CRL distribution points is an X.509 v3 certificate extension which identifies // the location of the CRL from which the revocation of this certificate can be checked. - // If not set certificate will be issued without CDP. Values are strings. + // If not set, certificates will be issued without distribution points set. // +optional CRLDistributionPoints []string `json:"crlDistributionPoints,omitempty"` } // IssuerStatus contains status information about an Issuer type IssuerStatus struct { + // List of status conditions to indicate the status of a CertificateRequest. + // Known condition types are `Ready`. // +optional Conditions []IssuerCondition `json:"conditions,omitempty"` + // ACME specific status options. + // This field should only be set if the Issuer is configured to use an ACME + // server to issue certificates. // +optional ACME *cmacme.ACMEIssuerStatus `json:"acme,omitempty"` } // IssuerCondition contains condition information for an Issuer. type IssuerCondition struct { - // Type of the condition, currently ('Ready'). + // Type of the condition, known values are ('Ready'). Type IssuerConditionType `json:"type"` // Status of the condition, one of ('True', 'False', 'Unknown'). @@ -270,6 +315,8 @@ type IssuerConditionType string const ( // IssuerConditionReady represents the fact that a given Issuer condition - // is in ready state. + // is in ready state and able to issue certificates. + // If the `status` of this condition is `False`, CertificateRequest controllers + // should prevent attempts to sign certificates. IssuerConditionReady IssuerConditionType = "Ready" ) diff --git a/pkg/apis/meta/v1/types.go b/pkg/apis/meta/v1/types.go index aa02067a8..7954b327e 100644 --- a/pkg/apis/meta/v1/types.go +++ b/pkg/apis/meta/v1/types.go @@ -37,29 +37,33 @@ const ( ) type LocalObjectReference struct { - // Name of the referent. + // Name of the resource being referred to. // More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names - // TODO: Add other useful fields. apiVersion, kind, uid? Name string `json:"name"` } // ObjectReference is a reference to an object with a given name, kind and group. type ObjectReference struct { + // Name of the resource being referred to. Name string `json:"name"` + // Kind of the resource being referred to. // +optional Kind string `json:"kind,omitempty"` + // Group of the resource being referred to. // +optional Group string `json:"group,omitempty"` } type SecretKeySelector struct { - // The name of the secret in the pod's namespace to select from. + // The name of the Secret resource being referred to. LocalObjectReference `json:",inline"` - // The key of the secret to select from. Must be a valid secret key. + + // The key of the entry in the Secret resource's `data` field to be used. // +optional Key string `json:"key,omitempty"` } const ( + // Used as a data key in Secret resources to store a CA certificate. TLSCAKey = "ca.crt" ) diff --git a/pkg/internal/apis/certmanager/types.go b/pkg/internal/apis/certmanager/types.go index ce779c64d..206d35ab8 100644 --- a/pkg/internal/apis/certmanager/types.go +++ b/pkg/internal/apis/certmanager/types.go @@ -16,25 +16,78 @@ limitations under the License. package certmanager -// Annotation names for Secrets +// Common annotation keys added to resources const ( - AltNamesAnnotationKey = "cert-manager.io/alt-names" - IPSANAnnotationKey = "cert-manager.io/ip-sans" - CommonNameAnnotationKey = "cert-manager.io/common-name" - IssuerNameAnnotationKey = "cert-manager.io/issuer-name" - IssuerKindAnnotationKey = "cert-manager.io/issuer-kind" + // Annotation key for DNS subjectAltNames + AltNamesAnnotationKey = "cert-manager.io/alt-names" + + // Annotation key for IP subjectAltNames + IPSANAnnotationKey = "cert-manager.io/ip-sans" + + // Annotation key for URI subjectAltNames + URISANAnnotationKey = "cert-manager.io/uri-sans" + + // Annotation key for certificate common name + CommonNameAnnotationKey = "cert-manager.io/common-name" + + // Annotation key the 'name' of the Issuer resource + IssuerNameAnnotationKey = "cert-manager.io/issuer-name" + + // Annotation key the 'kind' of the Issuer resource + IssuerKindAnnotationKey = "cert-manager.io/issuer-kind" + + // Annotation key the 'group' of the Issuer resource IssuerGroupAnnotationKey = "cert-manager.io/issuer-group" - CertificateNameKey = "cert-manager.io/certificate-name" + + // Annotation key the name of the certificate that a resource is related to + CertificateNameKey = "cert-manager.io/certificate-name" + + // Annotation key used to denote whether a Secret is named on a Certificate + // as a 'next private key' Secret resource + IsNextPrivateKeySecretLabelKey = "cert-manager.io/next-private-key" +) + +// Deprecated annotation names for Secrets +// These will be removed in a future release. +const ( + DeprecatedIssuerNameAnnotationKey = "certmanager.k8s.io/issuer-name" + DeprecatedIssuerKindAnnotationKey = "certmanager.k8s.io/issuer-kind" +) + +const ( + // issuerNameAnnotation can be used to override the issuer specified on the + // created Certificate resource. + IngressIssuerNameAnnotationKey = "cert-manager.io/issuer" + // clusterIssuerNameAnnotation can be used to override the issuer specified on the + // created Certificate resource. The Certificate will reference the + // specified *ClusterIssuer* instead of normal issuer. + IngressClusterIssuerNameAnnotationKey = "cert-manager.io/cluster-issuer" + // acmeIssuerHTTP01IngressClassAnnotation can be used to override the http01 ingressClass + // if the challenge type is set to http01 + IngressACMEIssuerHTTP01IngressClassAnnotationKey = "acme.cert-manager.io/http01-ingress-class" + + // IngressClassAnnotationKey picks a specific "class" for the Ingress. The + // controller only processes Ingresses with this annotation either unset, or + // set to either the configured value or the empty string. + IngressClassAnnotationKey = "kubernetes.io/ingress.class" ) // Annotation names for CertificateRequests const ( CRPrivateKeyAnnotationKey = "cert-manager.io/private-key-secret-name" - // Annotation to declare the CertificateRequest "revision", beloning to a Certificate Resource CertificateRequestRevisionAnnotationKey = "cert-manager.io/certificate-revision" ) +const ( + // IssueTemporaryCertificateAnnotation is an annotation that can be added to + // Certificate resources. + // If it is present, a temporary internally signed certificate will be + // stored in the target Secret resource whilst the real Issuer is processing + // the certificate request. + IssueTemporaryCertificateAnnotation = "cert-manager.io/issue-temporary-certificate" +) + const ( ClusterIssuerKind = "ClusterIssuer" IssuerKind = "Issuer" @@ -67,9 +120,42 @@ const ( AllowsInjectionFromSecretAnnotation = "cert-manager.io/allow-direct-injection" ) +// Issuer specific Annotations +const ( + // VenafiCustomFieldsAnnotationKey is the annotation that passes on JSON encoded custom fields to the Venafi issuer + // This will only work with Venafi TPP v19.3 and higher + // The value is an array with objects containing the name and value keys + // for example: `[{"name": "custom-field", "value": "custom-value"}]` + VenafiCustomFieldsAnnotationKey = "venafi.cert-manager.io/custom-fields" +) + // KeyUsage specifies valid usage contexts for keys. // See: https://tools.ietf.org/html/rfc5280#section-4.2.1.3 // https://tools.ietf.org/html/rfc5280#section-4.2.1.12 +// Valid KeyUsage values are as follows: +// "signing", +// "digital signature", +// "content commitment", +// "key encipherment", +// "key agreement", +// "data encipherment", +// "cert sign", +// "crl sign", +// "encipher only", +// "decipher only", +// "any", +// "server auth", +// "client auth", +// "code signing", +// "email protection", +// "s/mime", +// "ipsec end system", +// "ipsec tunnel", +// "ipsec user", +// "timestamping", +// "ocsp signing", +// "microsoft sgc", +// "netscape sgc" type KeyUsage string const ( diff --git a/pkg/internal/apis/certmanager/types_certificate.go b/pkg/internal/apis/certmanager/types_certificate.go index 39189c3d9..01f5dc9e1 100644 --- a/pkg/internal/apis/certmanager/types_certificate.go +++ b/pkg/internal/apis/certmanager/types_certificate.go @@ -29,7 +29,10 @@ type Certificate struct { metav1.TypeMeta metav1.ObjectMeta - Spec CertificateSpec + // Desired state of the Certificate resource. + Spec CertificateSpec + + // Status of the Certificate, set and managed automatically. Status CertificateStatus } @@ -46,56 +49,76 @@ type CertificateList struct { type KeyAlgorithm string const ( - RSAKeyAlgorithm KeyAlgorithm = "rsa" + // Denotes the RSA private key type + RSAKeyAlgorithm KeyAlgorithm = "rsa" + + // Denotes the ECDSA private key type ECDSAKeyAlgorithm KeyAlgorithm = "ecdsa" ) type KeyEncoding string const ( + // PKCS1 key encoding will produce PEM files that include the type of + // private key as part of the PEM header, e.g. "BEGIN RSA PRIVATE KEY". + // If the keyAlgorithm is set to 'ECDSA', this will produce private keys + // that use the "BEGIN EC PRIVATE KEY" header. PKCS1 KeyEncoding = "pkcs1" + + // PKCS8 key encoding will produce PEM files with the "BEGIN PRIVATE KEY" + // header. It encodes the keyAlgorithm of the private key as part of the + // DER encoded PEM block. PKCS8 KeyEncoding = "pkcs8" ) -// CertificateSpec defines the desired state of Certificate +// CertificateSpec defines the desired state of Certificate. +// A valid Certificate requires at least one of a CommonName, DNSName, or +// URISAN to be valid. type CertificateSpec struct { // Full X509 name specification (https://golang.org/pkg/crypto/x509/pkix/#Name). Subject *X509Subject - // A valid Certificate requires at least one of a CommonName, DNSName, or - // URISAN to be valid. - // CommonName is a common name to be used on the Certificate. // The CommonName should have a length of 64 characters or fewer to avoid // generating invalid CSRs. + // This value is ignored by TLS clients when any subject alt name is set. + // This is x509 behaviour: https://tools.ietf.org/html/rfc6125#section-6.4.4 CommonName string - // Certificate default Duration + // The requested 'duration' (i.e. lifetime) of the Certificate. + // This option may be ignored/overridden by some issuer types. + // If overridden and `renewBefore` is greater than the actual certificate + // duration, the certificate will be automatically renewed 2/3rds of the + // way through the certificate's duration. Duration *metav1.Duration - // Certificate renew before expiration duration + // The amount of time before the currently issued certificate's `notAfter` + // time that cert-manager will begin to attempt to renew the certificate. + // If this value is greater than the total duration of the certificate + // (i.e. notAfter - notBefore), it will be automatically renewed 2/3rds of + // the way through the certificate's duration. RenewBefore *metav1.Duration - // DNSNames is a list of subject alt names to be used on the Certificate. + // DNSNames is a list of DNS subjectAltNames to be set on the Certificate. DNSNames []string - // IPAddresses is a list of IP addresses to be used on the Certificate + // IPAddresses is a list of IP address subjectAltNames to be set on the Certificate. IPAddresses []string - // URISANs is a list of URI Subject Alternative Names to be set on this - // Certificate. + // URISANs is a list of URI subjectAltNames to be set on the Certificate. URISANs []string - // EmailSANs is a list of Email Subject Alternative Names to be set on this - // Certificate. + // EmailSANs is a list of email subjectAltNames to be set on the Certificate. EmailSANs []string - // SecretName is the name of the secret resource to store this secret in + // SecretName is the name of the secret resource that will be automatically + // created and managed by this Certificate resource. + // It will be populated with a private key and certificate, signed by the + // denoted issuer. SecretName string // Keystores configures additional keystore output formats stored in the // `secretName` Secret resource. - // +optional Keystores *CertificateKeystores // IssuerRef is a reference to the issuer for this certificate. @@ -107,21 +130,24 @@ type CertificateSpec struct { IssuerRef cmmeta.ObjectReference // IsCA will mark this Certificate as valid for signing. - // This implies that the 'cert sign' usage is set + // This will automatically add the `cert sign` usage to the list of `usages`. IsCA bool - // Usages is the set of x509 actions that are enabled for a given key. Defaults are ('digital signature', 'key encipherment') if empty + // Usages is the set of x509 usages that are requested for the certificate. + // Defaults to `digital signature` and `key encipherment` if not specified. Usages []KeyUsage // KeySize is the key bit size of the corresponding private key for this certificate. - // If provided, value must be between 2048 and 8192 inclusive when KeyAlgorithm is - // empty or is set to "rsa", and value must be one of (256, 384, 521) when - // KeyAlgorithm is set to "ecdsa". + // If `keyAlgorithm` is set to `RSA`, valid values are `2048`, `4096` or `8192`, + // and will default to `2048` if not specified. + // If `keyAlgorithm` is set to `ECDSA`, valid values are `256`, `384` or `521`, + // and will default to `256` if not specified. + // No other values are allowed. KeySize int // KeyAlgorithm is the private key algorithm of the corresponding private key // for this certificate. If provided, allowed values are either "rsa" or "ecdsa" - // If KeyAlgorithm is specified and KeySize is not provided, + // If `keyAlgorithm` is specified and `keySize` is not provided, // key size of 256 will be used for "ecdsa" key algorithm and // key size of 2048 will be used for "rsa" key algorithm. KeyAlgorithm KeyAlgorithm @@ -133,7 +159,6 @@ type CertificateSpec struct { KeyEncoding KeyEncoding // Options to control private keys used for the Certificate. - // +optional PrivateKey *CertificatePrivateKey } @@ -150,7 +175,6 @@ type CertificatePrivateKey struct { // If set to Always, a private key matching the specified requirements // will be generated whenever a re-issuance occurs. // Default is 'Never' for backward compatibility. - // +optional RotationPolicy PrivateKeyRotationPolicy } @@ -158,6 +182,18 @@ type CertificatePrivateKey struct { // is being issued. type PrivateKeyRotationPolicy string +var ( + // RotationPolicyNever means a private key will only be generated if one + // does not already exist in the target `spec.secretName`. + // If one does exists but it does not have the correct algorithm or size, + // a warning will be raised to await user intervention. + RotationPolicyNever PrivateKeyRotationPolicy = "Never" + + // RotationPolicyAlways means a private key matching the specified + // requirements will be generated whenever a re-issuance occurs. + RotationPolicyAlways PrivateKeyRotationPolicy = "Always" +) + // X509Subject Full X509 name specification type X509Subject struct { // Organizations to be used on the Certificate. @@ -222,8 +258,15 @@ type PKCS12Keystore struct { // CertificateStatus defines the observed state of Certificate type CertificateStatus struct { + // List of status conditions to indicate the status of certificates. + // Known condition types are `Ready` and `Issuing`. Conditions []CertificateCondition + // LastFailureTime is the time as recorded by the Certificate controller + // of the most recently failure to complete a CertificateRequest for this + // certificate resource. + // If set, cert-manager will not re-request another Certificate until + // 1 hour has elapsed from this time. LastFailureTime *metav1.Time // The time after which the certificate stored in the secret named @@ -232,8 +275,7 @@ type CertificateStatus struct { NotBefore *metav1.Time // The expiration time of the certificate stored in the secret named - // by this resource in spec.secretName. - // +optional + // by this resource in `spec.secretName`. NotAfter *metav1.Time // RenewalTime is the time at which the certificate will be next @@ -256,7 +298,6 @@ type CertificateStatus struct { // issuance or if it is part of the ongoing revision's issuance by // checking if the revision value in the annotation is greater than this // field. - // +optional Revision *int // The name of the Secret resource containing the private key to be used @@ -265,13 +306,12 @@ type CertificateStatus struct { // `Issuing` condition is set to `True`. // It will automatically unset this field when the Issuing condition is // not set or False. - // +optional NextPrivateKeySecretName *string } // CertificateCondition contains condition information for an Certificate. type CertificateCondition struct { - // Type of the condition, currently ('Ready'). + // Type of the condition, known values are ('Ready', `Issuing`). Type CertificateConditionType // Status of the condition, one of ('True', 'False', 'Unknown'). diff --git a/pkg/internal/apis/certmanager/types_certificaterequest.go b/pkg/internal/apis/certmanager/types_certificaterequest.go index c6b5e1385..7adcf72d6 100644 --- a/pkg/internal/apis/certmanager/types_certificaterequest.go +++ b/pkg/internal/apis/certmanager/types_certificaterequest.go @@ -23,9 +23,16 @@ import ( ) const ( + // Pending indicates that a CertificateRequest is still in progress. CertificateRequestReasonPending = "Pending" - CertificateRequestReasonFailed = "Failed" - CertificateRequestReasonIssued = "Issued" + + // Failed indicates that a CertificateRequest has failed, either due to + // timing out or some other critical failure. + CertificateRequestReasonFailed = "Failed" + + // Issued indicates that a CertificateRequest has been completed, and that + // the `status.certificate` field is set. + CertificateRequestReasonIssued = "Issued" ) // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object @@ -35,7 +42,10 @@ type CertificateRequest struct { metav1.TypeMeta metav1.ObjectMeta - Spec CertificateRequestSpec + // Desired state of the CertificateRequest resource. + Spec CertificateRequestSpec + + // Status of the CertificateRequest, set and managed automatically. Status CertificateRequestStatus } @@ -51,7 +61,8 @@ type CertificateRequestList struct { // CertificateRequestSpec defines the desired state of CertificateRequest type CertificateRequestSpec struct { - // Requested certificate default Duration + // The requested 'duration' (i.e. lifetime) of the Certificate. + // This option may be ignored/overridden by some issuer types. Duration *metav1.Duration // IssuerRef is a reference to the issuer for this CertificateRequest. If @@ -66,18 +77,20 @@ type CertificateRequestSpec struct { // Byte slice containing the PEM encoded CertificateSigningRequest CSRPEM []byte - // IsCA will mark the resulting certificate as valid for signing. This - // implies that the 'signing' usage is set + // IsCA will mark this Certificate as valid for signing. + // This will automatically add the `cert sign` usage to the list of `usages`. IsCA bool - // Usages is the set of x509 actions that are enabled for a given key. - // Defaults are ('digital signature', 'key encipherment') if empty + // Usages is the set of x509 usages that are requested for the certificate. + // Defaults to `digital signature` and `key encipherment` if not specified. Usages []KeyUsage } // CertificateStatus defines the observed state of CertificateRequest and // resulting signed certificate. type CertificateRequestStatus struct { + // List of status conditions to indicate the status of a CertificateRequest. + // Known condition types are `Ready` and `InvalidRequest`. Conditions []CertificateRequestCondition // Byte slice containing a PEM encoded signed certificate resulting from the @@ -86,6 +99,7 @@ type CertificateRequestStatus struct { // Byte slice containing the PEM encoded certificate authority of the signed // certificate. + // If not specified, the CA is assumed to be unknown/not available. CA []byte // FailureTime stores the time that this CertificateRequest failed. This is @@ -95,7 +109,7 @@ type CertificateRequestStatus struct { // CertificateRequestCondition contains condition information for a CertificateRequest. type CertificateRequestCondition struct { - // Type of the condition, currently ('Ready', 'InvalidRequest'). + // Type of the condition, known values are ('Ready', 'InvalidRequest'). Type CertificateRequestConditionType // Status of the condition, one of ('True', 'False', 'Unknown'). diff --git a/pkg/internal/apis/certmanager/types_issuer.go b/pkg/internal/apis/certmanager/types_issuer.go index 7fb513931..e7f21d6d2 100644 --- a/pkg/internal/apis/certmanager/types_issuer.go +++ b/pkg/internal/apis/certmanager/types_issuer.go @@ -25,11 +25,19 @@ import ( // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object +// A ClusterIssuer represents a certificate issuing authority which can be +// referenced as part of `issuerRef` fields. +// It is similar to an Issuer, however it is cluster-scoped and therefore can +// be referenced by resources that exist in *any* namespace, not just the same +// namespace as the referent. type ClusterIssuer struct { metav1.TypeMeta metav1.ObjectMeta - Spec IssuerSpec + // Desired state of the ClusterIssuer resource. + Spec IssuerSpec + + // Status of the ClusterIssuer, set and managed automatically. Status IssuerStatus } @@ -45,11 +53,18 @@ type ClusterIssuerList struct { // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object +// An Issuer represents a certificate issuing authority which can be +// referenced as part of `issuerRef` fields. +// It is scoped to a single namespace and can therefore only be referenced by +// resources within the same namespace. type Issuer struct { metav1.TypeMeta metav1.ObjectMeta - Spec IssuerSpec + // Desired state of the Issuer resource. + Spec IssuerSpec + + // Status of the Issuer, set and managed automatically. Status IssuerStatus } @@ -70,18 +85,30 @@ type IssuerSpec struct { } type IssuerConfig struct { + // ACME configures this issuer to communicate with a RFC8555 (ACME) server + // to obtain signed x509 certificates. ACME *cmacme.ACMEIssuer + // CA configures this issuer to sign certificates using a signing CA keypair + // stored in a Secret resource. + // This is used to build internal PKIs that are managed by cert-manager. CA *CAIssuer + // Vault configures this issuer to sign certificates using a HashiCorp Vault + // PKI backend. Vault *VaultIssuer + // SelfSigned configures this issuer to 'self sign' certificates using the + // private key used to create the CertificateRequest object. SelfSigned *SelfSignedIssuer + // Venafi configures this issuer to sign certificates using a Venafi TPP + // or Cloud policy zone. Venafi *VenafiIssuer } -// VenafiIssuer describes issuer configuration details for Venafi Cloud. +// Venafi configures this issuer to sign certificates using a Venafi TPP +// or Cloud policy zone. type VenafiIssuer struct { // Zone is the Venafi Policy Zone to use for this issuer. // All requests made to the Venafi platform will be restricted by the named @@ -100,7 +127,8 @@ type VenafiIssuer struct { // VenafiTPP defines connection configuration details for a Venafi TPP instance type VenafiTPP struct { - // URL is the base URL for the Venafi TPP instance + // URL is the base URL for the Venafi TPP instance, for example: + // "https://tpp.example.com/vedsdk". URL string // CredentialsRef is a reference to a Secret containing the username and @@ -119,72 +147,80 @@ type VenafiTPP struct { // VenafiCloud defines connection configuration details for Venafi Cloud type VenafiCloud struct { - // URL is the base URL for Venafi Cloud + // URL is the base URL for Venafi Cloud, usually: "https://api.venafi.cloud/v1". URL string // APITokenSecretRef is a secret key selector for the Venafi Cloud API token. APITokenSecretRef cmmeta.SecretKeySelector } +// SelfSigned configures this issuer to 'self sign' certificates using the +// private key used to create the CertificateRequest object. type SelfSignedIssuer struct { // The CRL distribution points is an X.509 v3 certificate extension which identifies // the location of the CRL from which the revocation of this certificate can be checked. // If not set certificate will be issued without CDP. Values are strings. - // +optional CRLDistributionPoints []string } +// Vault configures this issuer to sign certificates using a HashiCorp Vault +// PKI backend. type VaultIssuer struct { - // Vault authentication + // Auth configures how cert-manager authenticates with the Vault server. Auth VaultAuth - // Server is the vault connection address + // Server is the connection address for the Vault server, e.g: "https://vault.example.com:8200". Server string - // Vault URL path to the certificate role + // Path is the mount path of the Vault PKI backend's `sign` endpoint, e.g: + // "my_pki_mount/sign/my-role-name". Path string - // Base64 encoded CA bundle to validate Vault server certificate. Only used + // PEM encoded CA bundle used to validate Vault server certificate. Only used // if the Server URL is using HTTPS protocol. This parameter is ignored for // plain HTTP protocol connection. If not set the system root certificates // are used to validate the TLS connection. CABundle []byte } -// Vault authentication can be configured: -// - With a secret containing a token. Cert-manager is using this token as-is. -// - With a secret containing a AppRole. This AppRole is used to authenticate to -// Vault and retrieve a token. -// - With a secret containing a Kubernetes ServiceAccount JWT. This JWT is used -// to authenticate with Vault and retrieve a token. +// Configuration used to authenticate with a Vault server. +// Only one of `tokenSecretRef`, `appRole` or `kubernetes` may be specified. type VaultAuth struct { - // This Secret contains the Vault token key + // TokenSecretRef authenticates with Vault by presenting a token. TokenSecretRef *cmmeta.SecretKeySelector - // This Secret contains a AppRole and Secret + // AppRole authenticates with Vault using the App Role auth mechanism, + // with the role and secret stored in a Kubernetes Secret resource. AppRole *VaultAppRole - // This contains a Role and Secret with a ServiceAccount token to - // authenticate with vault. + // Kubernetes authenticates with Vault by passing the ServiceAccount + // token stored in the named Secret resource to the Vault server. Kubernetes *VaultKubernetesAuth } -// Authenticate against Vault using an AppRole that is stored in a Secret. +// AppRole authenticates with Vault using the App Role auth mechanism, +// with the role and secret stored in a Kubernetes Secret resource. type VaultAppRole struct { - // Where the authentication path is mounted in Vault. + // Path where the App Role authentication backend is mounted in Vault, e.g: + // "approle" Path string - RoleId string + // RoleID configures in the App Role authentication backend when setting + // up the App Role backend. + RoleId string + + // Reference to a key in a Secret that contains the App Role secret used + // to authenticate with Vault. SecretRef cmmeta.SecretKeySelector } // Authenticate against Vault using a Kubernetes ServiceAccount token stored in // a Secret. type VaultKubernetesAuth struct { - // The value here will be used as part of the path used when authenticating - // with vault, for example if you set a value of "foo", the path used will be - // `/v1/auth/foo/login`. If unspecified, the default value "kubernetes" will - // be used. + // The Vault mountPath here is the mount path to use when authenticating with + // Vault. For example, setting a value to `/v1/auth/foo`, will use the path + // `/v1/auth/foo/login` to authenticate with Vault. If unspecified, the + // default value "/v1/auth/kubernetes" will be used. Path string // The required Secret field containing a Kubernetes ServiceAccount JWT used @@ -204,21 +240,25 @@ type CAIssuer struct { // The CRL distribution points is an X.509 v3 certificate extension which identifies // the location of the CRL from which the revocation of this certificate can be checked. - // If not set certificate will be issued without CDP. Values are strings. - // +optional + // If not set, certificates will be issued without distribution points set. CRLDistributionPoints []string } // IssuerStatus contains status information about an Issuer type IssuerStatus struct { + // List of status conditions to indicate the status of a CertificateRequest. + // Known condition types are `Ready`. Conditions []IssuerCondition + // ACME specific status options. + // This field should only be set if the Issuer is configured to use an ACME + // server to issue certificates. ACME *cmacme.ACMEIssuerStatus } // IssuerCondition contains condition information for an Issuer. type IssuerCondition struct { - // Type of the condition, currently ('Ready'). + // Type of the condition, known values are ('Ready'). Type IssuerConditionType // Status of the condition, one of ('True', 'False', 'Unknown'). @@ -242,6 +282,8 @@ type IssuerConditionType string const ( // IssuerConditionReady represents the fact that a given Issuer condition - // is in ready state. + // is in ready state and able to issue certificates. + // If the `status` of this condition is `False`, CertificateRequest controllers + // should prevent attempts to sign certificates. IssuerConditionReady IssuerConditionType = "Ready" ) diff --git a/pkg/internal/apis/meta/types.go b/pkg/internal/apis/meta/types.go index 0c1a70adf..791d92208 100644 --- a/pkg/internal/apis/meta/types.go +++ b/pkg/internal/apis/meta/types.go @@ -36,26 +36,30 @@ const ( ) type LocalObjectReference struct { - // Name of the referent. + // Name of the resource being referred to. // More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names - // TODO: Add other useful fields. apiVersion, kind, uid? Name string } // ObjectReference is a reference to an object with a given name, kind and group. type ObjectReference struct { - Name string - Kind string + // Name of the resource being referred to. + Name string + // Kind of the resource being referred to. + Kind string + // Group of the resource being referred to. Group string } type SecretKeySelector struct { - // The name of the secret in the pod's namespace to select from. + // The name of the Secret resource being referred to. LocalObjectReference - // The key of the secret to select from. Must be a valid secret key. + + // The key of the entry in the Secret resource's `data` field to be used. Key string } const ( + // Used as a data key in Secret resources to store a CA certificate. TLSCAKey = "ca.crt" ) From a818975c36ce2d5ed08ea5d96f6b41893402ac27 Mon Sep 17 00:00:00 2001 From: James Munnelly Date: Wed, 24 Jun 2020 12:10:47 +0100 Subject: [PATCH 02/12] Update generated files Signed-off-by: James Munnelly --- deploy/crds/crd-certificaterequests.yaml | 29 +-- deploy/crds/crd-certificates.yaml | 178 ++++++++++------- deploy/crds/crd-challenges.yaml | 91 ++++----- deploy/crds/crd-clusterissuers.yaml | 239 ++++++++++++----------- deploy/crds/crd-issuers.yaml | 238 +++++++++++----------- deploy/crds/crd-orders.yaml | 3 + 6 files changed, 422 insertions(+), 356 deletions(-) diff --git a/deploy/crds/crd-certificaterequests.yaml b/deploy/crds/crd-certificaterequests.yaml index 51af11739..ebf7ab56e 100644 --- a/deploy/crds/crd-certificaterequests.yaml +++ b/deploy/crds/crd-certificaterequests.yaml @@ -78,7 +78,7 @@ spec: metadata: type: object spec: - description: CertificateRequestSpec defines the desired state of CertificateRequest + description: Desired state of the CertificateRequest resource. type: object required: - csr @@ -89,11 +89,12 @@ spec: type: string format: byte duration: - description: Requested certificate default Duration + description: The requested 'duration' (i.e. lifetime) of the Certificate. + This option may be ignored/overridden by some issuer types. type: string isCA: - description: IsCA will mark the resulting certificate as valid for signing. - This implies that the 'cert sign' usage is set + description: IsCA will mark this Certificate as valid for signing. This + will automatically add the `cert sign` usage to the list of `usages`. type: boolean issuerRef: description: IssuerRef is a reference to the issuer for this CertificateRequest. If @@ -108,15 +109,18 @@ spec: - name properties: group: + description: Group of the resource being referred to. type: string kind: + description: Kind of the resource being referred to. type: string name: + description: Name of the resource being referred to. type: string usages: - description: Usages is the set of x509 actions that are enabled for - a given key. Defaults are ('digital signature', 'key encipherment') - if empty + description: Usages is the set of x509 usages that are requested for + the certificate. Defaults to `digital signature` and `key encipherment` + if not specified. type: array items: description: 'KeyUsage specifies valid usage contexts for keys. See: @@ -154,13 +158,13 @@ spec: - microsoft sgc - netscape sgc status: - description: CertificateStatus defines the observed state of CertificateRequest - and resulting signed certificate. + description: Status of the CertificateRequest, set and managed automatically. type: object properties: ca: description: Byte slice containing the PEM encoded certificate authority - of the signed certificate. + of the signed certificate. If not specified, the CA is assumed to + be unknown/not available. type: string format: byte certificate: @@ -169,6 +173,8 @@ spec: type: string format: byte conditions: + description: List of status conditions to indicate the status of a CertificateRequest. + Known condition types are `Ready` and `InvalidRequest`. type: array items: description: CertificateRequestCondition contains condition information @@ -200,7 +206,8 @@ spec: - "False" - Unknown type: - description: Type of the condition, currently ('Ready', 'InvalidRequest'). + description: Type of the condition, known values are ('Ready', + 'InvalidRequest'). type: string failureTime: description: FailureTime stores the time that this CertificateRequest diff --git a/deploy/crds/crd-certificates.yaml b/deploy/crds/crd-certificates.yaml index 37fcf439a..fe5bcd373 100644 --- a/deploy/crds/crd-certificates.yaml +++ b/deploy/crds/crd-certificates.yaml @@ -77,9 +77,7 @@ spec: metadata: type: object spec: - description: CertificateSpec defines the desired state of Certificate. - A valid Certificate requires at least one of a CommonName, DNSName, - or URISAN to be valid. + description: Desired state of the Certificate resource. type: object required: - issuerRef @@ -92,29 +90,34 @@ spec: when any subject alt name is set. This is x509 behaviour: https://tools.ietf.org/html/rfc6125#section-6.4.4' type: string dnsNames: - description: DNSNames is a list of subject alt names to be used on + description: DNSNames is a list of DNS subjectAltNames to be set on the Certificate. type: array items: type: string duration: - description: Certificate default Duration + description: The requested 'duration' (i.e. lifetime) of the Certificate. + This option may be ignored/overridden by some issuer types. If overridden + and `renewBefore` is greater than the actual certificate duration, + the certificate will be automatically renewed 2/3rds of the way + through the certificate's duration. type: string emailSANs: - description: EmailSANs is a list of Email Subject Alternative Names - to be set on this Certificate. + description: EmailSANs is a list of email subjectAltNames to be set + on the Certificate. type: array items: type: string ipAddresses: - description: IPAddresses is a list of IP addresses to be used on the - Certificate + description: IPAddresses is a list of IP address subjectAltNames to + be set on the Certificate. type: array items: type: string isCA: description: IsCA will mark this Certificate as valid for signing. - This implies that the 'cert sign' usage is set + This will automatically add the `cert sign` usage to the list of + `usages`. type: boolean issuerRef: description: IssuerRef is a reference to the issuer for this certificate. @@ -128,15 +131,18 @@ spec: - name properties: group: + description: Group of the resource being referred to. type: string kind: + description: Kind of the resource being referred to. type: string name: + description: Name of the resource being referred to. type: string keyAlgorithm: description: KeyAlgorithm is the private key algorithm of the corresponding private key for this certificate. If provided, allowed values are - either "rsa" or "ecdsa" If KeyAlgorithm is specified and KeySize + either "rsa" or "ecdsa" If `keyAlgorithm` is specified and `keySize` is not provided, key size of 256 will be used for "ecdsa" key algorithm and key size of 2048 will be used for "rsa" key algorithm. type: string @@ -155,10 +161,11 @@ spec: - pkcs8 keySize: description: KeySize is the key bit size of the corresponding private - key for this certificate. If provided, value must be between 2048 - and 8192 inclusive when KeyAlgorithm is empty or is set to "rsa", - and value must be one of (256, 384, 521) when KeyAlgorithm is set - to "ecdsa". + key for this certificate. If `keyAlgorithm` is set to `RSA`, valid + values are `2048`, `4096` or `8192`, and will default to `2048` + if not specified. If `keyAlgorithm` is set to `ECDSA`, valid values + are `256`, `384` or `521`, and will default to `256` if not specified. + No other values are allowed. type: integer maximum: 8192 minimum: 0 @@ -191,12 +198,12 @@ spec: - name properties: key: - description: The key of the secret to select from. Must - be a valid secret key. + description: The key of the entry in the Secret resource's + `data` field to be used. type: string name: - description: 'Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names - TODO: Add other useful fields. apiVersion, kind, uid?' + description: 'Name of the resource being referred to. + More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names' type: string pkcs12: description: PKCS12 configures options for storing a PKCS12 keystore @@ -222,15 +229,15 @@ spec: - name properties: key: - description: The key of the secret to select from. Must - be a valid secret key. + description: The key of the entry in the Secret resource's + `data` field to be used. type: string name: - description: 'Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names - TODO: Add other useful fields. apiVersion, kind, uid?' + description: 'Name of the resource being referred to. + More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names' type: string organization: - description: Organization is the organization to be used on the Certificate + description: Organization is the organization to be used on the Certificate. type: array items: type: string @@ -250,11 +257,17 @@ spec: compatibility. type: string renewBefore: - description: Certificate renew before expiration duration + description: The amount of time before the currently issued certificate's + `notAfter` time that cert-manager will begin to attempt to renew + the certificate. If this value is greater than the total duration + of the certificate (i.e. notAfter - notBefore), it will be automatically + renewed 2/3rds of the way through the certificate's duration. type: string secretName: - description: SecretName is the name of the secret resource to store - this secret in + description: SecretName is the name of the secret resource that will + be automatically created and managed by this Certificate resource. + It will be populated with a private key and certificate, signed + by the denoted issuer. type: string subject: description: Full X509 name specification (https://golang.org/pkg/crypto/x509/pkix/#Name). @@ -294,15 +307,15 @@ spec: items: type: string uriSANs: - description: URISANs is a list of URI Subject Alternative Names to - be set on this Certificate. + description: URISANs is a list of URI subjectAltNames to be set on + the Certificate. type: array items: type: string usages: - description: Usages is the set of x509 actions that are enabled for - a given key. Defaults are ('digital signature', 'key encipherment') - if empty + description: Usages is the set of x509 usages that are requested for + the certificate. Defaults to `digital signature` and `key encipherment` + if not specified. type: array items: description: 'KeyUsage specifies valid usage contexts for keys. @@ -340,10 +353,12 @@ spec: - microsoft sgc - netscape sgc status: - description: CertificateStatus defines the observed state of Certificate + description: Status of the Certificate, set and managed automatically. type: object properties: conditions: + description: List of status conditions to indicate the status of certificates. + Known condition types are `Ready` and `Issuing`. type: array items: description: CertificateCondition contains condition information @@ -375,9 +390,14 @@ spec: - "False" - Unknown type: - description: Type of the condition, currently ('Ready'). + description: Type of the condition, known values are ('Ready', + `Issuing`). type: string lastFailureTime: + description: LastFailureTime is the time as recorded by the Certificate + controller of the most recently failure to complete a CertificateRequest + for this certificate resource. If set, cert-manager will not re-request + another Certificate until 1 hour has elapsed from this time. type: string format: date-time nextPrivateKeySecretName: @@ -389,7 +409,7 @@ spec: type: string notAfter: description: The expiration time of the certificate stored in the - secret named by this resource in spec.secretName. + secret named by this resource in `spec.secretName`. type: string format: date-time notBefore: @@ -435,9 +455,7 @@ spec: metadata: type: object spec: - description: CertificateSpec defines the desired state of Certificate. - A valid Certificate requires at least one of a CommonName, DNSName, - or URISAN to be valid. + description: Desired state of the Certificate resource. type: object required: - issuerRef @@ -450,29 +468,34 @@ spec: when any subject alt name is set. This is x509 behaviour: https://tools.ietf.org/html/rfc6125#section-6.4.4' type: string dnsNames: - description: DNSNames is a list of subject alt names to be used on + description: DNSNames is a list of DNS subjectAltNames to be set on the Certificate. type: array items: type: string duration: - description: Certificate default Duration + description: The requested 'duration' (i.e. lifetime) of the Certificate. + This option may be ignored/overridden by some issuer types. If overridden + and `renewBefore` is greater than the actual certificate duration, + the certificate will be automatically renewed 2/3rds of the way + through the certificate's duration. type: string emailSANs: - description: EmailSANs is a list of Email Subject Alternative Names - to be set on this Certificate. + description: EmailSANs is a list of email subjectAltNames to be set + on the Certificate. type: array items: type: string ipAddresses: - description: IPAddresses is a list of IP addresses to be used on the - Certificate + description: IPAddresses is a list of IP address subjectAltNames to + be set on the Certificate. type: array items: type: string isCA: description: IsCA will mark this Certificate as valid for signing. - This implies that the 'cert sign' usage is set + This will automatically add the `cert sign` usage to the list of + `usages`. type: boolean issuerRef: description: IssuerRef is a reference to the issuer for this certificate. @@ -486,15 +509,18 @@ spec: - name properties: group: + description: Group of the resource being referred to. type: string kind: + description: Kind of the resource being referred to. type: string name: + description: Name of the resource being referred to. type: string keyAlgorithm: description: KeyAlgorithm is the private key algorithm of the corresponding private key for this certificate. If provided, allowed values are - either "rsa" or "ecdsa" If KeyAlgorithm is specified and KeySize + either "rsa" or "ecdsa" If `keyAlgorithm` is specified and `keySize` is not provided, key size of 256 will be used for "ecdsa" key algorithm and key size of 2048 will be used for "rsa" key algorithm. type: string @@ -513,10 +539,11 @@ spec: - pkcs8 keySize: description: KeySize is the key bit size of the corresponding private - key for this certificate. If provided, value must be between 2048 - and 8192 inclusive when KeyAlgorithm is empty or is set to "rsa", - and value must be one of (256, 384, 521) when KeyAlgorithm is set - to "ecdsa". + key for this certificate. If `keyAlgorithm` is set to `RSA`, valid + values are `2048`, `4096` or `8192`, and will default to `2048` + if not specified. If `keyAlgorithm` is set to `ECDSA`, valid values + are `256`, `384` or `521`, and will default to `256` if not specified. + No other values are allowed. type: integer maximum: 8192 minimum: 0 @@ -549,12 +576,12 @@ spec: - name properties: key: - description: The key of the secret to select from. Must - be a valid secret key. + description: The key of the entry in the Secret resource's + `data` field to be used. type: string name: - description: 'Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names - TODO: Add other useful fields. apiVersion, kind, uid?' + description: 'Name of the resource being referred to. + More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names' type: string pkcs12: description: PKCS12 configures options for storing a PKCS12 keystore @@ -580,12 +607,12 @@ spec: - name properties: key: - description: The key of the secret to select from. Must - be a valid secret key. + description: The key of the entry in the Secret resource's + `data` field to be used. type: string name: - description: 'Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names - TODO: Add other useful fields. apiVersion, kind, uid?' + description: 'Name of the resource being referred to. + More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names' type: string privateKey: description: Options to control private keys used for the Certificate. @@ -603,11 +630,17 @@ spec: compatibility. type: string renewBefore: - description: Certificate renew before expiration duration + description: The amount of time before the currently issued certificate's + `notAfter` time that cert-manager will begin to attempt to renew + the certificate. If this value is greater than the total duration + of the certificate (i.e. notAfter - notBefore), it will be automatically + renewed 2/3rds of the way through the certificate's duration. type: string secretName: - description: SecretName is the name of the secret resource to store - this secret in + description: SecretName is the name of the secret resource that will + be automatically created and managed by this Certificate resource. + It will be populated with a private key and certificate, signed + by the denoted issuer. type: string subject: description: Full X509 name specification (https://golang.org/pkg/crypto/x509/pkix/#Name). @@ -652,15 +685,15 @@ spec: items: type: string uriSANs: - description: URISANs is a list of URI Subject Alternative Names to - be set on this Certificate. + description: URISANs is a list of URI subjectAltNames to be set on + the Certificate. type: array items: type: string usages: - description: Usages is the set of x509 actions that are enabled for - a given key. Defaults are ('digital signature', 'key encipherment') - if empty + description: Usages is the set of x509 usages that are requested for + the certificate. Defaults to `digital signature` and `key encipherment` + if not specified. type: array items: description: 'KeyUsage specifies valid usage contexts for keys. @@ -698,10 +731,12 @@ spec: - microsoft sgc - netscape sgc status: - description: CertificateStatus defines the observed state of Certificate + description: Status of the Certificate, set and managed automatically. type: object properties: conditions: + description: List of status conditions to indicate the status of certificates. + Known condition types are `Ready` and `Issuing`. type: array items: description: CertificateCondition contains condition information @@ -733,9 +768,14 @@ spec: - "False" - Unknown type: - description: Type of the condition, currently ('Ready'). + description: Type of the condition, known values are ('Ready', + `Issuing`). type: string lastFailureTime: + description: LastFailureTime is the time as recorded by the Certificate + controller of the most recently failure to complete a CertificateRequest + for this certificate resource. If set, cert-manager will not re-request + another Certificate until 1 hour has elapsed from this time. type: string format: date-time nextPrivateKeySecretName: @@ -747,7 +787,7 @@ spec: type: string notAfter: description: The expiration time of the certificate stored in the - secret named by this resource in spec.secretName. + secret named by this resource in `spec.secretName`. type: string format: date-time notBefore: diff --git a/deploy/crds/crd-challenges.yaml b/deploy/crds/crd-challenges.yaml index cc315d971..4a16fa671 100644 --- a/deploy/crds/crd-challenges.yaml +++ b/deploy/crds/crd-challenges.yaml @@ -108,10 +108,13 @@ spec: - name properties: group: + description: Group of the resource being referred to. type: string kind: + description: Kind of the resource being referred to. type: string name: + description: Name of the resource being referred to. type: string key: description: 'Key is the ACME challenge key for this challenge For HTTP01 @@ -144,12 +147,12 @@ spec: - name properties: key: - description: The key of the secret to select from. Must - be a valid secret key. + description: The key of the entry in the Secret resource's + `data` field to be used. type: string name: - description: 'Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names - TODO: Add other useful fields. apiVersion, kind, uid?' + description: 'Name of the resource being referred to. + More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names' type: string host: type: string @@ -170,12 +173,12 @@ spec: - name properties: key: - description: The key of the secret to select from. Must - be a valid secret key. + description: The key of the entry in the Secret resource's + `data` field to be used. type: string name: - description: 'Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names - TODO: Add other useful fields. apiVersion, kind, uid?' + description: 'Name of the resource being referred to. + More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names' type: string clientSecretSecretRef: type: object @@ -183,12 +186,12 @@ spec: - name properties: key: - description: The key of the secret to select from. Must - be a valid secret key. + description: The key of the entry in the Secret resource's + `data` field to be used. type: string name: - description: 'Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names - TODO: Add other useful fields. apiVersion, kind, uid?' + description: 'Name of the resource being referred to. + More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names' type: string clientTokenSecretRef: type: object @@ -196,12 +199,12 @@ spec: - name properties: key: - description: The key of the secret to select from. Must - be a valid secret key. + description: The key of the entry in the Secret resource's + `data` field to be used. type: string name: - description: 'Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names - TODO: Add other useful fields. apiVersion, kind, uid?' + description: 'Name of the resource being referred to. + More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names' type: string serviceConsumerDomain: type: string @@ -225,12 +228,12 @@ spec: - name properties: key: - description: The key of the secret to select from. Must - be a valid secret key. + description: The key of the entry in the Secret resource's + `data` field to be used. type: string name: - description: 'Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names - TODO: Add other useful fields. apiVersion, kind, uid?' + description: 'Name of the resource being referred to. + More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names' type: string environment: type: string @@ -264,12 +267,12 @@ spec: - name properties: key: - description: The key of the secret to select from. Must - be a valid secret key. + description: The key of the entry in the Secret resource's + `data` field to be used. type: string name: - description: 'Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names - TODO: Add other useful fields. apiVersion, kind, uid?' + description: 'Name of the resource being referred to. + More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names' type: string cloudflare: description: ACMEIssuerDNS01ProviderCloudflare is a structure @@ -282,12 +285,12 @@ spec: - name properties: key: - description: The key of the secret to select from. Must - be a valid secret key. + description: The key of the entry in the Secret resource's + `data` field to be used. type: string name: - description: 'Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names - TODO: Add other useful fields. apiVersion, kind, uid?' + description: 'Name of the resource being referred to. + More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names' type: string apiTokenSecretRef: type: object @@ -295,12 +298,12 @@ spec: - name properties: key: - description: The key of the secret to select from. Must - be a valid secret key. + description: The key of the entry in the Secret resource's + `data` field to be used. type: string name: - description: 'Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names - TODO: Add other useful fields. apiVersion, kind, uid?' + description: 'Name of the resource being referred to. + More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names' type: string email: type: string @@ -324,12 +327,12 @@ spec: - name properties: key: - description: The key of the secret to select from. Must - be a valid secret key. + description: The key of the entry in the Secret resource's + `data` field to be used. type: string name: - description: 'Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names - TODO: Add other useful fields. apiVersion, kind, uid?' + description: 'Name of the resource being referred to. + More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names' type: string rfc2136: description: ACMEIssuerDNS01ProviderRFC2136 is a structure containing @@ -364,12 +367,12 @@ spec: - name properties: key: - description: The key of the secret to select from. Must - be a valid secret key. + description: The key of the entry in the Secret resource's + `data` field to be used. type: string name: - description: 'Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names - TODO: Add other useful fields. apiVersion, kind, uid?' + description: 'Name of the resource being referred to. + More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names' type: string route53: description: ACMEIssuerDNS01ProviderRoute53 is a structure containing @@ -407,12 +410,12 @@ spec: - name properties: key: - description: The key of the secret to select from. Must - be a valid secret key. + description: The key of the entry in the Secret resource's + `data` field to be used. type: string name: - description: 'Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names - TODO: Add other useful fields. apiVersion, kind, uid?' + description: 'Name of the resource being referred to. + More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names' type: string webhook: description: ACMEIssuerDNS01ProviderWebhook specifies configuration diff --git a/deploy/crds/crd-clusterissuers.yaml b/deploy/crds/crd-clusterissuers.yaml index 381261a3d..56aa2393e 100644 --- a/deploy/crds/crd-clusterissuers.yaml +++ b/deploy/crds/crd-clusterissuers.yaml @@ -54,6 +54,10 @@ spec: storage: false "validation": "openAPIV3Schema": + description: A ClusterIssuer represents a certificate issuing authority which + can be referenced as part of `issuerRef` fields. It is similar to an Issuer, + however it is cluster-scoped and therefore can be referenced by resources + that exist in *any* namespace, not just the same namespace as the referent. type: object properties: apiVersion: @@ -69,12 +73,12 @@ spec: metadata: type: object spec: - description: IssuerSpec is the specification of an Issuer. This includes - any configuration required for the issuer. + description: Desired state of the ClusterIssuer resource. type: object properties: acme: - description: ACMEIssuer contains the specification for an ACME issuer + description: ACME configures this issuer to communicate with a RFC8555 + (ACME) server to obtain signed x509 certificates. type: object required: - privateKeySecretRef @@ -118,12 +122,12 @@ spec: - name properties: key: - description: The key of the secret to select from. Must - be a valid secret key. + description: The key of the entry in the Secret resource's + `data` field to be used. type: string name: - description: 'Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names - TODO: Add other useful fields. apiVersion, kind, uid?' + description: 'Name of the resource being referred to. More + info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names' type: string privateKeySecretRef: description: PrivateKey is the name of a secret containing the private @@ -133,12 +137,12 @@ spec: - name properties: key: - description: The key of the secret to select from. Must be a - valid secret key. + description: The key of the entry in the Secret resource's `data` + field to be used. type: string name: - description: 'Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names - TODO: Add other useful fields. apiVersion, kind, uid?' + description: 'Name of the resource being referred to. More info: + https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names' type: string server: description: Server is the ACME server URL @@ -170,14 +174,12 @@ spec: - name properties: key: - description: The key of the secret to select from. - Must be a valid secret key. + description: The key of the entry in the Secret + resource's `data` field to be used. type: string name: - description: 'Name of the referent. More info: - https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names - TODO: Add other useful fields. apiVersion, kind, - uid?' + description: 'Name of the resource being referred + to. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names' type: string host: type: string @@ -198,14 +200,12 @@ spec: - name properties: key: - description: The key of the secret to select from. - Must be a valid secret key. + description: The key of the entry in the Secret + resource's `data` field to be used. type: string name: - description: 'Name of the referent. More info: - https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names - TODO: Add other useful fields. apiVersion, kind, - uid?' + description: 'Name of the resource being referred + to. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names' type: string clientSecretSecretRef: type: object @@ -213,14 +213,12 @@ spec: - name properties: key: - description: The key of the secret to select from. - Must be a valid secret key. + description: The key of the entry in the Secret + resource's `data` field to be used. type: string name: - description: 'Name of the referent. More info: - https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names - TODO: Add other useful fields. apiVersion, kind, - uid?' + description: 'Name of the resource being referred + to. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names' type: string clientTokenSecretRef: type: object @@ -228,14 +226,12 @@ spec: - name properties: key: - description: The key of the secret to select from. - Must be a valid secret key. + description: The key of the entry in the Secret + resource's `data` field to be used. type: string name: - description: 'Name of the referent. More info: - https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names - TODO: Add other useful fields. apiVersion, kind, - uid?' + description: 'Name of the resource being referred + to. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names' type: string serviceConsumerDomain: type: string @@ -259,14 +255,12 @@ spec: - name properties: key: - description: The key of the secret to select from. - Must be a valid secret key. + description: The key of the entry in the Secret + resource's `data` field to be used. type: string name: - description: 'Name of the referent. More info: - https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names - TODO: Add other useful fields. apiVersion, kind, - uid?' + description: 'Name of the resource being referred + to. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names' type: string environment: type: string @@ -300,14 +294,12 @@ spec: - name properties: key: - description: The key of the secret to select from. - Must be a valid secret key. + description: The key of the entry in the Secret + resource's `data` field to be used. type: string name: - description: 'Name of the referent. More info: - https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names - TODO: Add other useful fields. apiVersion, kind, - uid?' + description: 'Name of the resource being referred + to. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names' type: string cloudflare: description: ACMEIssuerDNS01ProviderCloudflare is a structure @@ -320,14 +312,12 @@ spec: - name properties: key: - description: The key of the secret to select from. - Must be a valid secret key. + description: The key of the entry in the Secret + resource's `data` field to be used. type: string name: - description: 'Name of the referent. More info: - https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names - TODO: Add other useful fields. apiVersion, kind, - uid?' + description: 'Name of the resource being referred + to. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names' type: string apiTokenSecretRef: type: object @@ -335,14 +325,12 @@ spec: - name properties: key: - description: The key of the secret to select from. - Must be a valid secret key. + description: The key of the entry in the Secret + resource's `data` field to be used. type: string name: - description: 'Name of the referent. More info: - https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names - TODO: Add other useful fields. apiVersion, kind, - uid?' + description: 'Name of the resource being referred + to. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names' type: string email: type: string @@ -367,14 +355,12 @@ spec: - name properties: key: - description: The key of the secret to select from. - Must be a valid secret key. + description: The key of the entry in the Secret + resource's `data` field to be used. type: string name: - description: 'Name of the referent. More info: - https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names - TODO: Add other useful fields. apiVersion, kind, - uid?' + description: 'Name of the resource being referred + to. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names' type: string rfc2136: description: ACMEIssuerDNS01ProviderRFC2136 is a structure @@ -411,14 +397,12 @@ spec: - name properties: key: - description: The key of the secret to select from. - Must be a valid secret key. + description: The key of the entry in the Secret + resource's `data` field to be used. type: string name: - description: 'Name of the referent. More info: - https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names - TODO: Add other useful fields. apiVersion, kind, - uid?' + description: 'Name of the resource being referred + to. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names' type: string route53: description: ACMEIssuerDNS01ProviderRoute53 is a structure @@ -457,14 +441,12 @@ spec: - name properties: key: - description: The key of the secret to select from. - Must be a valid secret key. + description: The key of the entry in the Secret + resource's `data` field to be used. type: string name: - description: 'Name of the referent. More info: - https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names - TODO: Add other useful fields. apiVersion, kind, - uid?' + description: 'Name of the resource being referred + to. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names' type: string webhook: description: ACMEIssuerDNS01ProviderWebhook specifies @@ -1554,6 +1536,9 @@ spec: additionalProperties: type: string ca: + description: CA configures this issuer to sign certificates using a + signing CA keypair stored in a Secret resource. This is used to build + internal PKIs that are managed by cert-manager. type: object required: - secretName @@ -1561,8 +1546,8 @@ spec: crlDistributionPoints: description: The CRL distribution points is an X.509 v3 certificate extension which identifies the location of the CRL from which - the revocation of this certificate can be checked. If not set - certificate will be issued without CDP. Values are strings. + the revocation of this certificate can be checked. If not set, + certificates will be issued without distribution points set. type: array items: type: string @@ -1571,6 +1556,8 @@ spec: issued by this Issuer. type: string selfSigned: + description: SelfSigned configures this issuer to 'self sign' certificates + using the private key used to create the CertificateRequest object. type: object properties: crlDistributionPoints: @@ -1582,6 +1569,8 @@ spec: items: type: string vault: + description: Vault configures this issuer to sign certificates using + a HashiCorp Vault PKI backend. type: object required: - auth @@ -1589,11 +1578,14 @@ spec: - server properties: auth: - description: Vault authentication + description: Auth configures how cert-manager authenticates with + the Vault server. type: object properties: appRole: - description: This Secret contains a AppRole and Secret + description: AppRole authenticates with Vault using the App + Role auth mechanism, with the role and secret stored in a + Kubernetes Secret resource. type: object required: - path @@ -1601,27 +1593,32 @@ spec: - secretRef properties: path: - description: Where the authentication path is mounted in - Vault. + description: 'Path where the App Role authentication backend + is mounted in Vault, e.g: "approle"' type: string roleId: + description: RoleID configures in the App Role authentication + backend when setting up the App Role backend. type: string secretRef: + description: Reference to a key in a Secret that contains + the App Role secret used to authenticate with Vault. type: object required: - name properties: key: - description: The key of the secret to select from. Must - be a valid secret key. + description: The key of the entry in the Secret resource's + `data` field to be used. type: string name: - description: 'Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names - TODO: Add other useful fields. apiVersion, kind, uid?' + description: 'Name of the resource being referred to. + More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names' type: string kubernetes: - description: This contains a Role and Secret with a ServiceAccount - token to authenticate with vault. + description: Kubernetes authenticates with Vault by passing + the ServiceAccount token stored in the named Secret resource + to the Vault server. type: object required: - role @@ -1648,43 +1645,47 @@ spec: - name properties: key: - description: The key of the secret to select from. Must - be a valid secret key. + description: The key of the entry in the Secret resource's + `data` field to be used. type: string name: - description: 'Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names - TODO: Add other useful fields. apiVersion, kind, uid?' + description: 'Name of the resource being referred to. + More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names' type: string tokenSecretRef: - description: This Secret contains the Vault token key + description: TokenSecretRef authenticates with Vault by presenting + a token. type: object required: - name properties: key: - description: The key of the secret to select from. Must - be a valid secret key. + description: The key of the entry in the Secret resource's + `data` field to be used. type: string name: - description: 'Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names - TODO: Add other useful fields. apiVersion, kind, uid?' + description: 'Name of the resource being referred to. More + info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names' type: string caBundle: - description: Base64 encoded CA bundle to validate Vault server certificate. - Only used if the Server URL is using HTTPS protocol. This parameter - is ignored for plain HTTP protocol connection. If not set the - system root certificates are used to validate the TLS connection. + description: PEM encoded CA bundle used to validate Vault server + certificate. Only used if the Server URL is using HTTPS protocol. + This parameter is ignored for plain HTTP protocol connection. + If not set the system root certificates are used to validate the + TLS connection. type: string format: byte path: - description: Vault URL path to the certificate role + description: 'Path is the mount path of the Vault PKI backend''s + `sign` endpoint, e.g: "my_pki_mount/sign/my-role-name".' type: string server: - description: Server is the vault connection address + description: 'Server is the connection address for the Vault server, + e.g: "https://vault.example.com:8200".' type: string venafi: - description: VenafiIssuer describes issuer configuration details for - Venafi Cloud. + description: Venafi configures this issuer to sign certificates using + a Venafi TPP or Cloud policy zone. type: object required: - zone @@ -1704,15 +1705,16 @@ spec: - name properties: key: - description: The key of the secret to select from. Must - be a valid secret key. + description: The key of the entry in the Secret resource's + `data` field to be used. type: string name: - description: 'Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names - TODO: Add other useful fields. apiVersion, kind, uid?' + description: 'Name of the resource being referred to. More + info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names' type: string url: - description: URL is the base URL for Venafi Cloud + description: 'URL is the base URL for Venafi Cloud, usually: + "https://api.venafi.cloud/v1".' type: string tpp: description: TPP specifies Trust Protection Platform configuration @@ -1740,11 +1742,12 @@ spec: - name properties: name: - description: 'Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names - TODO: Add other useful fields. apiVersion, kind, uid?' + description: 'Name of the resource being referred to. More + info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names' type: string url: - description: URL is the base URL for the Venafi TPP instance + description: 'URL is the base URL for the Venafi TPP instance, + for example: "https://tpp.example.com/vedsdk".' type: string zone: description: Zone is the Venafi Policy Zone to use for this issuer. @@ -1752,10 +1755,12 @@ spec: the named zone policy. This field is required. type: string status: - description: IssuerStatus contains status information about an Issuer + description: Status of the ClusterIssuer, set and managed automatically. type: object properties: acme: + description: ACME specific status options. This field should only be + set if the Issuer is configured to use an ACME server to issue certificates. type: object properties: lastRegisteredEmail: @@ -1768,6 +1773,8 @@ spec: be used to retrieve account details from the CA type: string conditions: + description: List of status conditions to indicate the status of a CertificateRequest. + Known condition types are `Ready`. type: array items: description: IssuerCondition contains condition information for an @@ -1799,5 +1806,5 @@ spec: - "False" - Unknown type: - description: Type of the condition, currently ('Ready'). + description: Type of the condition, known values are ('Ready'). type: string diff --git a/deploy/crds/crd-issuers.yaml b/deploy/crds/crd-issuers.yaml index cb1198b71..060b4e05b 100644 --- a/deploy/crds/crd-issuers.yaml +++ b/deploy/crds/crd-issuers.yaml @@ -54,6 +54,9 @@ spec: storage: false "validation": "openAPIV3Schema": + description: An Issuer represents a certificate issuing authority which can + be referenced as part of `issuerRef` fields. It is scoped to a single namespace + and can therefore only be referenced by resources within the same namespace. type: object properties: apiVersion: @@ -69,12 +72,12 @@ spec: metadata: type: object spec: - description: IssuerSpec is the specification of an Issuer. This includes - any configuration required for the issuer. + description: Desired state of the Issuer resource. type: object properties: acme: - description: ACMEIssuer contains the specification for an ACME issuer + description: ACME configures this issuer to communicate with a RFC8555 + (ACME) server to obtain signed x509 certificates. type: object required: - privateKeySecretRef @@ -118,12 +121,12 @@ spec: - name properties: key: - description: The key of the secret to select from. Must - be a valid secret key. + description: The key of the entry in the Secret resource's + `data` field to be used. type: string name: - description: 'Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names - TODO: Add other useful fields. apiVersion, kind, uid?' + description: 'Name of the resource being referred to. More + info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names' type: string privateKeySecretRef: description: PrivateKey is the name of a secret containing the private @@ -133,12 +136,12 @@ spec: - name properties: key: - description: The key of the secret to select from. Must be a - valid secret key. + description: The key of the entry in the Secret resource's `data` + field to be used. type: string name: - description: 'Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names - TODO: Add other useful fields. apiVersion, kind, uid?' + description: 'Name of the resource being referred to. More info: + https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names' type: string server: description: Server is the ACME server URL @@ -170,14 +173,12 @@ spec: - name properties: key: - description: The key of the secret to select from. - Must be a valid secret key. + description: The key of the entry in the Secret + resource's `data` field to be used. type: string name: - description: 'Name of the referent. More info: - https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names - TODO: Add other useful fields. apiVersion, kind, - uid?' + description: 'Name of the resource being referred + to. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names' type: string host: type: string @@ -198,14 +199,12 @@ spec: - name properties: key: - description: The key of the secret to select from. - Must be a valid secret key. + description: The key of the entry in the Secret + resource's `data` field to be used. type: string name: - description: 'Name of the referent. More info: - https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names - TODO: Add other useful fields. apiVersion, kind, - uid?' + description: 'Name of the resource being referred + to. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names' type: string clientSecretSecretRef: type: object @@ -213,14 +212,12 @@ spec: - name properties: key: - description: The key of the secret to select from. - Must be a valid secret key. + description: The key of the entry in the Secret + resource's `data` field to be used. type: string name: - description: 'Name of the referent. More info: - https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names - TODO: Add other useful fields. apiVersion, kind, - uid?' + description: 'Name of the resource being referred + to. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names' type: string clientTokenSecretRef: type: object @@ -228,14 +225,12 @@ spec: - name properties: key: - description: The key of the secret to select from. - Must be a valid secret key. + description: The key of the entry in the Secret + resource's `data` field to be used. type: string name: - description: 'Name of the referent. More info: - https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names - TODO: Add other useful fields. apiVersion, kind, - uid?' + description: 'Name of the resource being referred + to. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names' type: string serviceConsumerDomain: type: string @@ -259,14 +254,12 @@ spec: - name properties: key: - description: The key of the secret to select from. - Must be a valid secret key. + description: The key of the entry in the Secret + resource's `data` field to be used. type: string name: - description: 'Name of the referent. More info: - https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names - TODO: Add other useful fields. apiVersion, kind, - uid?' + description: 'Name of the resource being referred + to. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names' type: string environment: type: string @@ -300,14 +293,12 @@ spec: - name properties: key: - description: The key of the secret to select from. - Must be a valid secret key. + description: The key of the entry in the Secret + resource's `data` field to be used. type: string name: - description: 'Name of the referent. More info: - https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names - TODO: Add other useful fields. apiVersion, kind, - uid?' + description: 'Name of the resource being referred + to. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names' type: string cloudflare: description: ACMEIssuerDNS01ProviderCloudflare is a structure @@ -320,14 +311,12 @@ spec: - name properties: key: - description: The key of the secret to select from. - Must be a valid secret key. + description: The key of the entry in the Secret + resource's `data` field to be used. type: string name: - description: 'Name of the referent. More info: - https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names - TODO: Add other useful fields. apiVersion, kind, - uid?' + description: 'Name of the resource being referred + to. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names' type: string apiTokenSecretRef: type: object @@ -335,14 +324,12 @@ spec: - name properties: key: - description: The key of the secret to select from. - Must be a valid secret key. + description: The key of the entry in the Secret + resource's `data` field to be used. type: string name: - description: 'Name of the referent. More info: - https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names - TODO: Add other useful fields. apiVersion, kind, - uid?' + description: 'Name of the resource being referred + to. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names' type: string email: type: string @@ -367,14 +354,12 @@ spec: - name properties: key: - description: The key of the secret to select from. - Must be a valid secret key. + description: The key of the entry in the Secret + resource's `data` field to be used. type: string name: - description: 'Name of the referent. More info: - https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names - TODO: Add other useful fields. apiVersion, kind, - uid?' + description: 'Name of the resource being referred + to. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names' type: string rfc2136: description: ACMEIssuerDNS01ProviderRFC2136 is a structure @@ -411,14 +396,12 @@ spec: - name properties: key: - description: The key of the secret to select from. - Must be a valid secret key. + description: The key of the entry in the Secret + resource's `data` field to be used. type: string name: - description: 'Name of the referent. More info: - https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names - TODO: Add other useful fields. apiVersion, kind, - uid?' + description: 'Name of the resource being referred + to. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names' type: string route53: description: ACMEIssuerDNS01ProviderRoute53 is a structure @@ -457,14 +440,12 @@ spec: - name properties: key: - description: The key of the secret to select from. - Must be a valid secret key. + description: The key of the entry in the Secret + resource's `data` field to be used. type: string name: - description: 'Name of the referent. More info: - https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names - TODO: Add other useful fields. apiVersion, kind, - uid?' + description: 'Name of the resource being referred + to. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names' type: string webhook: description: ACMEIssuerDNS01ProviderWebhook specifies @@ -1554,6 +1535,9 @@ spec: additionalProperties: type: string ca: + description: CA configures this issuer to sign certificates using a + signing CA keypair stored in a Secret resource. This is used to build + internal PKIs that are managed by cert-manager. type: object required: - secretName @@ -1561,8 +1545,8 @@ spec: crlDistributionPoints: description: The CRL distribution points is an X.509 v3 certificate extension which identifies the location of the CRL from which - the revocation of this certificate can be checked. If not set - certificate will be issued without CDP. Values are strings. + the revocation of this certificate can be checked. If not set, + certificates will be issued without distribution points set. type: array items: type: string @@ -1571,6 +1555,8 @@ spec: issued by this Issuer. type: string selfSigned: + description: SelfSigned configures this issuer to 'self sign' certificates + using the private key used to create the CertificateRequest object. type: object properties: crlDistributionPoints: @@ -1582,6 +1568,8 @@ spec: items: type: string vault: + description: Vault configures this issuer to sign certificates using + a HashiCorp Vault PKI backend. type: object required: - auth @@ -1589,11 +1577,14 @@ spec: - server properties: auth: - description: Vault authentication + description: Auth configures how cert-manager authenticates with + the Vault server. type: object properties: appRole: - description: This Secret contains a AppRole and Secret + description: AppRole authenticates with Vault using the App + Role auth mechanism, with the role and secret stored in a + Kubernetes Secret resource. type: object required: - path @@ -1601,27 +1592,32 @@ spec: - secretRef properties: path: - description: Where the authentication path is mounted in - Vault. + description: 'Path where the App Role authentication backend + is mounted in Vault, e.g: "approle"' type: string roleId: + description: RoleID configures in the App Role authentication + backend when setting up the App Role backend. type: string secretRef: + description: Reference to a key in a Secret that contains + the App Role secret used to authenticate with Vault. type: object required: - name properties: key: - description: The key of the secret to select from. Must - be a valid secret key. + description: The key of the entry in the Secret resource's + `data` field to be used. type: string name: - description: 'Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names - TODO: Add other useful fields. apiVersion, kind, uid?' + description: 'Name of the resource being referred to. + More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names' type: string kubernetes: - description: This contains a Role and Secret with a ServiceAccount - token to authenticate with vault. + description: Kubernetes authenticates with Vault by passing + the ServiceAccount token stored in the named Secret resource + to the Vault server. type: object required: - role @@ -1648,43 +1644,47 @@ spec: - name properties: key: - description: The key of the secret to select from. Must - be a valid secret key. + description: The key of the entry in the Secret resource's + `data` field to be used. type: string name: - description: 'Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names - TODO: Add other useful fields. apiVersion, kind, uid?' + description: 'Name of the resource being referred to. + More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names' type: string tokenSecretRef: - description: This Secret contains the Vault token key + description: TokenSecretRef authenticates with Vault by presenting + a token. type: object required: - name properties: key: - description: The key of the secret to select from. Must - be a valid secret key. + description: The key of the entry in the Secret resource's + `data` field to be used. type: string name: - description: 'Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names - TODO: Add other useful fields. apiVersion, kind, uid?' + description: 'Name of the resource being referred to. More + info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names' type: string caBundle: - description: Base64 encoded CA bundle to validate Vault server certificate. - Only used if the Server URL is using HTTPS protocol. This parameter - is ignored for plain HTTP protocol connection. If not set the - system root certificates are used to validate the TLS connection. + description: PEM encoded CA bundle used to validate Vault server + certificate. Only used if the Server URL is using HTTPS protocol. + This parameter is ignored for plain HTTP protocol connection. + If not set the system root certificates are used to validate the + TLS connection. type: string format: byte path: - description: Vault URL path to the certificate role + description: 'Path is the mount path of the Vault PKI backend''s + `sign` endpoint, e.g: "my_pki_mount/sign/my-role-name".' type: string server: - description: Server is the vault connection address + description: 'Server is the connection address for the Vault server, + e.g: "https://vault.example.com:8200".' type: string venafi: - description: VenafiIssuer describes issuer configuration details for - Venafi Cloud. + description: Venafi configures this issuer to sign certificates using + a Venafi TPP or Cloud policy zone. type: object required: - zone @@ -1704,15 +1704,16 @@ spec: - name properties: key: - description: The key of the secret to select from. Must - be a valid secret key. + description: The key of the entry in the Secret resource's + `data` field to be used. type: string name: - description: 'Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names - TODO: Add other useful fields. apiVersion, kind, uid?' + description: 'Name of the resource being referred to. More + info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names' type: string url: - description: URL is the base URL for Venafi Cloud + description: 'URL is the base URL for Venafi Cloud, usually: + "https://api.venafi.cloud/v1".' type: string tpp: description: TPP specifies Trust Protection Platform configuration @@ -1740,11 +1741,12 @@ spec: - name properties: name: - description: 'Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names - TODO: Add other useful fields. apiVersion, kind, uid?' + description: 'Name of the resource being referred to. More + info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names' type: string url: - description: URL is the base URL for the Venafi TPP instance + description: 'URL is the base URL for the Venafi TPP instance, + for example: "https://tpp.example.com/vedsdk".' type: string zone: description: Zone is the Venafi Policy Zone to use for this issuer. @@ -1752,10 +1754,12 @@ spec: the named zone policy. This field is required. type: string status: - description: IssuerStatus contains status information about an Issuer + description: Status of the Issuer, set and managed automatically. type: object properties: acme: + description: ACME specific status options. This field should only be + set if the Issuer is configured to use an ACME server to issue certificates. type: object properties: lastRegisteredEmail: @@ -1768,6 +1772,8 @@ spec: be used to retrieve account details from the CA type: string conditions: + description: List of status conditions to indicate the status of a CertificateRequest. + Known condition types are `Ready`. type: array items: description: IssuerCondition contains condition information for an @@ -1799,5 +1805,5 @@ spec: - "False" - Unknown type: - description: Type of the condition, currently ('Ready'). + description: Type of the condition, known values are ('Ready'). type: string diff --git a/deploy/crds/crd-orders.yaml b/deploy/crds/crd-orders.yaml index e27f5b529..180fa2686 100644 --- a/deploy/crds/crd-orders.yaml +++ b/deploy/crds/crd-orders.yaml @@ -114,10 +114,13 @@ spec: - name properties: group: + description: Group of the resource being referred to. type: string kind: + description: Kind of the resource being referred to. type: string name: + description: Name of the resource being referred to. type: string status: type: object From 6caa4c451db3443706c7d23b2487016d07928598 Mon Sep 17 00:00:00 2001 From: James Munnelly Date: Wed, 24 Jun 2020 12:11:22 +0100 Subject: [PATCH 03/12] Rename CRPrivateKeyAnnotationKey -> CertificateRequestPrivateKeyAnnotationKey Signed-off-by: James Munnelly --- .../selfsigned/selfsigned.go | 6 +- .../selfsigned/selfsigned_test.go | 14 +-- pkg/controller/certificates/sync.go | 2 +- pkg/controller/certificates/sync_test.go | 6 +- .../expcertificates/internal/test/test.go | 2 +- .../requestmanager_controller.go | 2 +- .../requestmanager_controller_test.go | 96 +++++++++---------- .../requestmanager/util_test.go | 4 +- .../issuers/selfsigned/certificaterequest.go | 2 +- 9 files changed, 67 insertions(+), 67 deletions(-) diff --git a/pkg/controller/certificaterequests/selfsigned/selfsigned.go b/pkg/controller/certificaterequests/selfsigned/selfsigned.go index 7adc925be..5264316de 100644 --- a/pkg/controller/certificaterequests/selfsigned/selfsigned.go +++ b/pkg/controller/certificaterequests/selfsigned/selfsigned.go @@ -77,10 +77,10 @@ func (s *SelfSigned) Sign(ctx context.Context, cr *cmapi.CertificateRequest, iss resourceNamespace := s.issuerOptions.ResourceNamespace(issuerObj) - secretName, ok := cr.ObjectMeta.Annotations[cmapi.CRPrivateKeyAnnotationKey] + secretName, ok := cr.ObjectMeta.Annotations[cmapi.CertificateRequestPrivateKeyAnnotationKey] if !ok || secretName == "" { message := fmt.Sprintf("Annotation %q missing or reference empty", - cmapi.CRPrivateKeyAnnotationKey) + cmapi.CertificateRequestPrivateKeyAnnotationKey) err := errors.New("secret name missing") s.reporter.Failed(cr, err, "MissingAnnotation", message) @@ -101,7 +101,7 @@ func (s *SelfSigned) Sign(ctx context.Context, cr *cmapi.CertificateRequest, iss if cmerrors.IsInvalidData(err) { message := fmt.Sprintf("Failed to get key %q referenced in annotation %q", - secretName, cmapi.CRPrivateKeyAnnotationKey) + secretName, cmapi.CertificateRequestPrivateKeyAnnotationKey) s.reporter.Pending(cr, err, "ErrorParsingKey", message) log.Error(err, message) diff --git a/pkg/controller/certificaterequests/selfsigned/selfsigned_test.go b/pkg/controller/certificaterequests/selfsigned/selfsigned_test.go index 2f44559d0..c28c61611 100644 --- a/pkg/controller/certificaterequests/selfsigned/selfsigned_test.go +++ b/pkg/controller/certificaterequests/selfsigned/selfsigned_test.go @@ -132,7 +132,7 @@ func TestSign(t *testing.T) { baseCR := gen.CertificateRequest("test-cr", gen.SetCertificateRequestAnnotations( map[string]string{ - cmapi.CRPrivateKeyAnnotationKey: rsaKeySecret.Name, + cmapi.CertificateRequestPrivateKeyAnnotationKey: rsaKeySecret.Name, }, ), gen.SetCertificateRequestCSR(csrRSAPEM), @@ -172,13 +172,13 @@ func TestSign(t *testing.T) { "a CertificateRequest with no cert-manager.io/selfsigned-private-key annotation should fail": { certificateRequest: gen.CertificateRequestFrom(baseCR, // no annotation - gen.DeleteCertificateRequestAnnotation(cmapi.CRPrivateKeyAnnotationKey), + gen.DeleteCertificateRequestAnnotation(cmapi.CertificateRequestPrivateKeyAnnotationKey), ), builder: &testpkg.Builder{ KubeObjects: []runtime.Object{}, CertManagerObjects: []runtime.Object{gen.CertificateRequestFrom(baseCR, // no annotation - gen.DeleteCertificateRequestAnnotation(cmapi.CRPrivateKeyAnnotationKey), + gen.DeleteCertificateRequestAnnotation(cmapi.CertificateRequestPrivateKeyAnnotationKey), ), baseIssuer}, ExpectedEvents: []string{ `Warning MissingAnnotation Annotation "cert-manager.io/private-key-secret-name" missing or reference empty: secret name missing`, @@ -189,7 +189,7 @@ func TestSign(t *testing.T) { "status", gen.DefaultTestNamespace, gen.CertificateRequestFrom(baseCR, - gen.DeleteCertificateRequestAnnotation(cmapi.CRPrivateKeyAnnotationKey), + gen.DeleteCertificateRequestAnnotation(cmapi.CertificateRequestPrivateKeyAnnotationKey), gen.SetCertificateRequestStatusCondition(cmapi.CertificateRequestCondition{ Type: cmapi.CertificateRequestConditionReady, Status: cmmeta.ConditionFalse, @@ -206,13 +206,13 @@ func TestSign(t *testing.T) { "a CertificateRequest with a cert-manager.io/private-key-secret-name annotation but empty string should fail": { certificateRequest: gen.CertificateRequestFrom(baseCR, // no data in annotation - gen.SetCertificateRequestAnnotations(map[string]string{cmapi.CRPrivateKeyAnnotationKey: ""}), + gen.SetCertificateRequestAnnotations(map[string]string{cmapi.CertificateRequestPrivateKeyAnnotationKey: ""}), ), builder: &testpkg.Builder{ KubeObjects: []runtime.Object{}, CertManagerObjects: []runtime.Object{gen.CertificateRequestFrom(baseCR, // no data in annotation - gen.SetCertificateRequestAnnotations(map[string]string{cmapi.CRPrivateKeyAnnotationKey: ""}), + gen.SetCertificateRequestAnnotations(map[string]string{cmapi.CertificateRequestPrivateKeyAnnotationKey: ""}), ), baseIssuer}, ExpectedEvents: []string{ `Warning MissingAnnotation Annotation "cert-manager.io/private-key-secret-name" missing or reference empty: secret name missing`, @@ -223,7 +223,7 @@ func TestSign(t *testing.T) { "status", gen.DefaultTestNamespace, gen.CertificateRequestFrom(baseCR, - gen.SetCertificateRequestAnnotations(map[string]string{cmapi.CRPrivateKeyAnnotationKey: ""}), + gen.SetCertificateRequestAnnotations(map[string]string{cmapi.CertificateRequestPrivateKeyAnnotationKey: ""}), gen.SetCertificateRequestStatusCondition(cmapi.CertificateRequestCondition{ Type: cmapi.CertificateRequestConditionReady, Status: cmmeta.ConditionFalse, diff --git a/pkg/controller/certificates/sync.go b/pkg/controller/certificates/sync.go index 7fbadd347..ea155da65 100644 --- a/pkg/controller/certificates/sync.go +++ b/pkg/controller/certificates/sync.go @@ -649,7 +649,7 @@ func (c *certificateRequestManager) buildCertificateRequest(log logr.Logger, crt for k, v := range crt.Annotations { annotations[k] = v } - annotations[cmapi.CRPrivateKeyAnnotationKey] = crt.Spec.SecretName + annotations[cmapi.CertificateRequestPrivateKeyAnnotationKey] = crt.Spec.SecretName annotations[cmapi.CertificateNameKey] = crt.Name cr := &cmapi.CertificateRequest{ diff --git a/pkg/controller/certificates/sync_test.go b/pkg/controller/certificates/sync_test.go index 5e4f1b364..46046c435 100644 --- a/pkg/controller/certificates/sync_test.go +++ b/pkg/controller/certificates/sync_test.go @@ -113,7 +113,7 @@ func createCryptoBundle(crt *cmapi.Certificate) (*cryptoBundle, error) { for k, v := range crt.Annotations { annotations[k] = v } - annotations[cmapi.CRPrivateKeyAnnotationKey] = crt.Spec.SecretName + annotations[cmapi.CertificateRequestPrivateKeyAnnotationKey] = crt.Spec.SecretName annotations[cmapi.CertificateNameKey] = crt.Name certificateRequest := &cmapi.CertificateRequest{ ObjectMeta: metav1.ObjectMeta{ @@ -350,8 +350,8 @@ func TestBuildCertificateRequest(t *testing.T) { expectedErr: false, expectedCertificateRequestAnnotations: map[string]string{ - cmapi.CRPrivateKeyAnnotationKey: baseCert.Spec.SecretName, - cmapi.CertificateNameKey: baseCert.Name, + cmapi.CertificateRequestPrivateKeyAnnotationKey: baseCert.Spec.SecretName, + cmapi.CertificateNameKey: baseCert.Name, }, }, } diff --git a/pkg/controller/expcertificates/internal/test/test.go b/pkg/controller/expcertificates/internal/test/test.go index 7608d4dbf..dc446b5fa 100644 --- a/pkg/controller/expcertificates/internal/test/test.go +++ b/pkg/controller/expcertificates/internal/test/test.go @@ -113,7 +113,7 @@ func createCryptoBundle(crt *cmapi.Certificate, fixedClock *fakeclock.FakeClock) annotations[cmapi.CertificateRequestRevisionAnnotationKey] = fmt.Sprintf("%d", crt.Status.Revision) } - annotations[cmapi.CRPrivateKeyAnnotationKey] = crt.Spec.SecretName + annotations[cmapi.CertificateRequestPrivateKeyAnnotationKey] = crt.Spec.SecretName annotations[cmapi.CertificateNameKey] = crt.Name certificateRequest := &cmapi.CertificateRequest{ ObjectMeta: metav1.ObjectMeta{ diff --git a/pkg/controller/expcertificates/requestmanager/requestmanager_controller.go b/pkg/controller/expcertificates/requestmanager/requestmanager_controller.go index 2d2190231..2a6bfcbba 100644 --- a/pkg/controller/expcertificates/requestmanager/requestmanager_controller.go +++ b/pkg/controller/expcertificates/requestmanager/requestmanager_controller.go @@ -316,7 +316,7 @@ func (c *controller) createNewCertificateRequest(ctx context.Context, crt *cmapi annotations[k] = v } annotations[cmapi.CertificateRequestRevisionAnnotationKey] = strconv.Itoa(nextRevision) - annotations[cmapi.CRPrivateKeyAnnotationKey] = nextPrivateKeySecretName + annotations[cmapi.CertificateRequestPrivateKeyAnnotationKey] = nextPrivateKeySecretName annotations[cmapi.CertificateNameKey] = crt.Name cr := &cmapi.CertificateRequest{ diff --git a/pkg/controller/expcertificates/requestmanager/requestmanager_controller_test.go b/pkg/controller/expcertificates/requestmanager/requestmanager_controller_test.go index 254ff89cb..23c8466d1 100644 --- a/pkg/controller/expcertificates/requestmanager/requestmanager_controller_test.go +++ b/pkg/controller/expcertificates/requestmanager/requestmanager_controller_test.go @@ -163,8 +163,8 @@ func TestProcessItem(t *testing.T) { testpkg.NewCustomMatch(coretesting.NewCreateAction(cmapi.SchemeGroupVersion.WithResource("certificaterequests"), "testns", gen.CertificateRequestFrom(bundle1.certificateRequest, gen.SetCertificateRequestAnnotations(map[string]string{ - cmapi.CRPrivateKeyAnnotationKey: "exists", - cmapi.CertificateRequestRevisionAnnotationKey: "1", + cmapi.CertificateRequestPrivateKeyAnnotationKey: "exists", + cmapi.CertificateRequestRevisionAnnotationKey: "1", }), )), relaxedCertificateRequestMatcher), }, @@ -183,8 +183,8 @@ func TestProcessItem(t *testing.T) { requests: []runtime.Object{ gen.CertificateRequestFrom(bundle1.certificateRequest, gen.SetCertificateRequestAnnotations(map[string]string{ - cmapi.CRPrivateKeyAnnotationKey: "exists", - cmapi.CertificateRequestRevisionAnnotationKey: "", + cmapi.CertificateRequestPrivateKeyAnnotationKey: "exists", + cmapi.CertificateRequestRevisionAnnotationKey: "", }), ), }, @@ -194,8 +194,8 @@ func TestProcessItem(t *testing.T) { testpkg.NewCustomMatch(coretesting.NewCreateAction(cmapi.SchemeGroupVersion.WithResource("certificaterequests"), "testns", gen.CertificateRequestFrom(bundle1.certificateRequest, gen.SetCertificateRequestAnnotations(map[string]string{ - cmapi.CRPrivateKeyAnnotationKey: "exists", - cmapi.CertificateRequestRevisionAnnotationKey: "1", + cmapi.CertificateRequestPrivateKeyAnnotationKey: "exists", + cmapi.CertificateRequestRevisionAnnotationKey: "1", }), )), relaxedCertificateRequestMatcher), }, @@ -214,8 +214,8 @@ func TestProcessItem(t *testing.T) { requests: []runtime.Object{ gen.CertificateRequestFrom(bundle1.certificateRequest, gen.SetCertificateRequestAnnotations(map[string]string{ - cmapi.CRPrivateKeyAnnotationKey: "exists", - cmapi.CertificateRequestRevisionAnnotationKey: "invalid", + cmapi.CertificateRequestPrivateKeyAnnotationKey: "exists", + cmapi.CertificateRequestRevisionAnnotationKey: "invalid", }), ), }, @@ -225,8 +225,8 @@ func TestProcessItem(t *testing.T) { testpkg.NewCustomMatch(coretesting.NewCreateAction(cmapi.SchemeGroupVersion.WithResource("certificaterequests"), "testns", gen.CertificateRequestFrom(bundle1.certificateRequest, gen.SetCertificateRequestAnnotations(map[string]string{ - cmapi.CRPrivateKeyAnnotationKey: "exists", - cmapi.CertificateRequestRevisionAnnotationKey: "1", + cmapi.CertificateRequestPrivateKeyAnnotationKey: "exists", + cmapi.CertificateRequestRevisionAnnotationKey: "1", }), )), relaxedCertificateRequestMatcher), }, @@ -245,8 +245,8 @@ func TestProcessItem(t *testing.T) { requests: []runtime.Object{ gen.CertificateRequestFrom(bundle1.certificateRequest, gen.SetCertificateRequestAnnotations(map[string]string{ - cmapi.CRPrivateKeyAnnotationKey: "exists", - cmapi.CertificateRequestRevisionAnnotationKey: "1", + cmapi.CertificateRequestPrivateKeyAnnotationKey: "exists", + cmapi.CertificateRequestRevisionAnnotationKey: "1", }), ), }, @@ -265,8 +265,8 @@ func TestProcessItem(t *testing.T) { requests: []runtime.Object{ gen.CertificateRequestFrom(bundle1.certificateRequest, gen.SetCertificateRequestAnnotations(map[string]string{ - cmapi.CRPrivateKeyAnnotationKey: "exists", - cmapi.CertificateRequestRevisionAnnotationKey: "1", + cmapi.CertificateRequestPrivateKeyAnnotationKey: "exists", + cmapi.CertificateRequestRevisionAnnotationKey: "1", }), gen.SetCertificateRequestCSR([]byte("invalid")), ), @@ -277,8 +277,8 @@ func TestProcessItem(t *testing.T) { testpkg.NewCustomMatch(coretesting.NewCreateAction(cmapi.SchemeGroupVersion.WithResource("certificaterequests"), "testns", gen.CertificateRequestFrom(bundle1.certificateRequest, gen.SetCertificateRequestAnnotations(map[string]string{ - cmapi.CRPrivateKeyAnnotationKey: "exists", - cmapi.CertificateRequestRevisionAnnotationKey: "1", + cmapi.CertificateRequestPrivateKeyAnnotationKey: "exists", + cmapi.CertificateRequestRevisionAnnotationKey: "1", }), )), relaxedCertificateRequestMatcher), }, @@ -297,15 +297,15 @@ func TestProcessItem(t *testing.T) { requests: []runtime.Object{ gen.CertificateRequestFrom(bundle1.certificateRequest, gen.SetCertificateRequestAnnotations(map[string]string{ - cmapi.CRPrivateKeyAnnotationKey: "exists", - cmapi.CertificateRequestRevisionAnnotationKey: "3", + cmapi.CertificateRequestPrivateKeyAnnotationKey: "exists", + cmapi.CertificateRequestRevisionAnnotationKey: "3", }), ), gen.CertificateRequestFrom(bundle1.certificateRequest, gen.SetCertificateRequestName("testing-number-2"), gen.SetCertificateRequestAnnotations(map[string]string{ - cmapi.CRPrivateKeyAnnotationKey: "exists", - cmapi.CertificateRequestRevisionAnnotationKey: "4", + cmapi.CertificateRequestPrivateKeyAnnotationKey: "exists", + cmapi.CertificateRequestRevisionAnnotationKey: "4", }), ), }, @@ -314,8 +314,8 @@ func TestProcessItem(t *testing.T) { testpkg.NewCustomMatch(coretesting.NewCreateAction(cmapi.SchemeGroupVersion.WithResource("certificaterequests"), "testns", gen.CertificateRequestFrom(bundle1.certificateRequest, gen.SetCertificateRequestAnnotations(map[string]string{ - cmapi.CRPrivateKeyAnnotationKey: "exists", - cmapi.CertificateRequestRevisionAnnotationKey: "1", + cmapi.CertificateRequestPrivateKeyAnnotationKey: "exists", + cmapi.CertificateRequestRevisionAnnotationKey: "1", }), )), relaxedCertificateRequestMatcher), }, @@ -334,8 +334,8 @@ func TestProcessItem(t *testing.T) { requests: []runtime.Object{ gen.CertificateRequestFrom(bundle1.certificateRequest, gen.SetCertificateRequestAnnotations(map[string]string{ - cmapi.CRPrivateKeyAnnotationKey: "exists", - cmapi.CertificateRequestRevisionAnnotationKey: "1", + cmapi.CertificateRequestPrivateKeyAnnotationKey: "exists", + cmapi.CertificateRequestRevisionAnnotationKey: "1", }), ), // included here just to ensure it does not get deleted as it is not for the @@ -343,8 +343,8 @@ func TestProcessItem(t *testing.T) { gen.CertificateRequestFrom(bundle1.certificateRequest, gen.SetCertificateRequestName("testing-number-2"), gen.SetCertificateRequestAnnotations(map[string]string{ - cmapi.CRPrivateKeyAnnotationKey: "exists", - cmapi.CertificateRequestRevisionAnnotationKey: "4", + cmapi.CertificateRequestPrivateKeyAnnotationKey: "exists", + cmapi.CertificateRequestRevisionAnnotationKey: "4", }), ), }, @@ -354,8 +354,8 @@ func TestProcessItem(t *testing.T) { testpkg.NewCustomMatch(coretesting.NewCreateAction(cmapi.SchemeGroupVersion.WithResource("certificaterequests"), "testns", gen.CertificateRequestFrom(bundle1.certificateRequest, gen.SetCertificateRequestAnnotations(map[string]string{ - cmapi.CRPrivateKeyAnnotationKey: "exists", - cmapi.CertificateRequestRevisionAnnotationKey: "1", + cmapi.CertificateRequestPrivateKeyAnnotationKey: "exists", + cmapi.CertificateRequestRevisionAnnotationKey: "1", }), )), relaxedCertificateRequestMatcher), }, @@ -375,8 +375,8 @@ func TestProcessItem(t *testing.T) { requests: []runtime.Object{ gen.CertificateRequestFrom(bundle1.certificateRequest, gen.SetCertificateRequestAnnotations(map[string]string{ - cmapi.CRPrivateKeyAnnotationKey: "exists", - cmapi.CertificateRequestRevisionAnnotationKey: "6", + cmapi.CertificateRequestPrivateKeyAnnotationKey: "exists", + cmapi.CertificateRequestRevisionAnnotationKey: "6", }), ), // included here just to ensure it does not get deleted as it is not for the @@ -384,8 +384,8 @@ func TestProcessItem(t *testing.T) { gen.CertificateRequestFrom(bundle1.certificateRequest, gen.SetCertificateRequestName("testing-number-2"), gen.SetCertificateRequestAnnotations(map[string]string{ - cmapi.CRPrivateKeyAnnotationKey: "exists", - cmapi.CertificateRequestRevisionAnnotationKey: "5", + cmapi.CertificateRequestPrivateKeyAnnotationKey: "exists", + cmapi.CertificateRequestRevisionAnnotationKey: "5", }), ), }, @@ -395,8 +395,8 @@ func TestProcessItem(t *testing.T) { testpkg.NewCustomMatch(coretesting.NewCreateAction(cmapi.SchemeGroupVersion.WithResource("certificaterequests"), "testns", gen.CertificateRequestFrom(bundle2.certificateRequest, gen.SetCertificateRequestAnnotations(map[string]string{ - cmapi.CRPrivateKeyAnnotationKey: "exists", - cmapi.CertificateRequestRevisionAnnotationKey: "6", + cmapi.CertificateRequestPrivateKeyAnnotationKey: "exists", + cmapi.CertificateRequestRevisionAnnotationKey: "6", }), )), relaxedCertificateRequestMatcher), }, @@ -416,8 +416,8 @@ func TestProcessItem(t *testing.T) { requests: []runtime.Object{ gen.CertificateRequestFrom(bundle1.certificateRequest, gen.SetCertificateRequestAnnotations(map[string]string{ - cmapi.CRPrivateKeyAnnotationKey: "exists", - cmapi.CertificateRequestRevisionAnnotationKey: "6", + cmapi.CertificateRequestPrivateKeyAnnotationKey: "exists", + cmapi.CertificateRequestRevisionAnnotationKey: "6", }), ), }, @@ -427,8 +427,8 @@ func TestProcessItem(t *testing.T) { testpkg.NewCustomMatch(coretesting.NewCreateAction(cmapi.SchemeGroupVersion.WithResource("certificaterequests"), "testns", gen.CertificateRequestFrom(bundle1.certificateRequest, gen.SetCertificateRequestAnnotations(map[string]string{ - cmapi.CRPrivateKeyAnnotationKey: "exists", - cmapi.CertificateRequestRevisionAnnotationKey: "6", + cmapi.CertificateRequestPrivateKeyAnnotationKey: "exists", + cmapi.CertificateRequestRevisionAnnotationKey: "6", }), )), relaxedCertificateRequestMatcher), }, @@ -449,8 +449,8 @@ func TestProcessItem(t *testing.T) { requests: []runtime.Object{ gen.CertificateRequestFrom(bundle1.certificateRequest, gen.SetCertificateRequestAnnotations(map[string]string{ - cmapi.CRPrivateKeyAnnotationKey: "exists", - cmapi.CertificateRequestRevisionAnnotationKey: "6", + cmapi.CertificateRequestPrivateKeyAnnotationKey: "exists", + cmapi.CertificateRequestRevisionAnnotationKey: "6", }), ), }, @@ -460,8 +460,8 @@ func TestProcessItem(t *testing.T) { testpkg.NewCustomMatch(coretesting.NewCreateAction(cmapi.SchemeGroupVersion.WithResource("certificaterequests"), "testns", gen.CertificateRequestFrom(bundle1.certificateRequest, gen.SetCertificateRequestAnnotations(map[string]string{ - cmapi.CRPrivateKeyAnnotationKey: "exists", - cmapi.CertificateRequestRevisionAnnotationKey: "6", + cmapi.CertificateRequestPrivateKeyAnnotationKey: "exists", + cmapi.CertificateRequestRevisionAnnotationKey: "6", }), )), relaxedCertificateRequestMatcher), }, @@ -481,8 +481,8 @@ func TestProcessItem(t *testing.T) { requests: []runtime.Object{ gen.CertificateRequestFrom(bundle1.certificateRequest, gen.SetCertificateRequestAnnotations(map[string]string{ - cmapi.CRPrivateKeyAnnotationKey: "exists", - cmapi.CertificateRequestRevisionAnnotationKey: "6", + cmapi.CertificateRequestPrivateKeyAnnotationKey: "exists", + cmapi.CertificateRequestRevisionAnnotationKey: "6", }), ), }, @@ -502,15 +502,15 @@ func TestProcessItem(t *testing.T) { requests: []runtime.Object{ gen.CertificateRequestFrom(bundle1.certificateRequest, gen.SetCertificateRequestAnnotations(map[string]string{ - cmapi.CRPrivateKeyAnnotationKey: "exists", - cmapi.CertificateRequestRevisionAnnotationKey: "6", + cmapi.CertificateRequestPrivateKeyAnnotationKey: "exists", + cmapi.CertificateRequestRevisionAnnotationKey: "6", }), ), gen.CertificateRequestFrom(bundle1.certificateRequest, gen.SetCertificateRequestName("another-name-2"), gen.SetCertificateRequestAnnotations(map[string]string{ - cmapi.CRPrivateKeyAnnotationKey: "exists", - cmapi.CertificateRequestRevisionAnnotationKey: "6", + cmapi.CertificateRequestPrivateKeyAnnotationKey: "exists", + cmapi.CertificateRequestRevisionAnnotationKey: "6", }), ), }, diff --git a/pkg/controller/expcertificates/requestmanager/util_test.go b/pkg/controller/expcertificates/requestmanager/util_test.go index b4e6d70fa..faef6dc29 100644 --- a/pkg/controller/expcertificates/requestmanager/util_test.go +++ b/pkg/controller/expcertificates/requestmanager/util_test.go @@ -104,10 +104,10 @@ func createCryptoBundle(crt *cmapi.Certificate) (*cryptoBundle, error) { annotations[cmapi.CertificateRequestRevisionAnnotationKey] = "1" } - annotations[cmapi.CRPrivateKeyAnnotationKey] = crt.Spec.SecretName + annotations[cmapi.CertificateRequestPrivateKeyAnnotationKey] = crt.Spec.SecretName annotations[cmapi.CertificateNameKey] = crt.Name if crt.Status.NextPrivateKeySecretName != nil { - annotations[cmapi.CRPrivateKeyAnnotationKey] = *crt.Status.NextPrivateKeySecretName + annotations[cmapi.CertificateRequestPrivateKeyAnnotationKey] = *crt.Status.NextPrivateKeySecretName } certificateRequest := &cmapi.CertificateRequest{ ObjectMeta: metav1.ObjectMeta{ diff --git a/test/e2e/suite/issuers/selfsigned/certificaterequest.go b/test/e2e/suite/issuers/selfsigned/certificaterequest.go index 2f7575e6c..4aaa82e9e 100644 --- a/test/e2e/suite/issuers/selfsigned/certificaterequest.go +++ b/test/e2e/suite/issuers/selfsigned/certificaterequest.go @@ -64,7 +64,7 @@ var _ = framework.CertManagerDescribe("SelfSigned CertificateRequest", func() { Kind: "Issuer", }), gen.AddCertificateRequestAnnotations(map[string]string{ - v1alpha2.CRPrivateKeyAnnotationKey: certificateRequestSecretName, + v1alpha2.CertificateRequestPrivateKeyAnnotationKey: certificateRequestSecretName, }), ) }) From 463e08a4670dd5b081ebd83b42f3bd60dcd5d50a Mon Sep 17 00:00:00 2001 From: James Munnelly Date: Thu, 25 Jun 2020 14:50:00 +0100 Subject: [PATCH 04/12] Address review feedback Signed-off-by: James Munnelly --- .../certmanager/v1alpha2/types_certificate.go | 2 +- .../v1alpha2/types_certificaterequest.go | 17 +++++++++++------ pkg/apis/certmanager/v1alpha2/types_issuer.go | 7 ++++--- .../certmanager/v1alpha3/types_certificate.go | 2 +- .../v1alpha3/types_certificaterequest.go | 17 +++++++++++------ pkg/apis/certmanager/v1alpha3/types_issuer.go | 7 ++++--- .../apis/certmanager/types_certificate.go | 2 +- .../certmanager/types_certificaterequest.go | 17 +++++++++++------ pkg/internal/apis/certmanager/types_issuer.go | 7 ++++--- 9 files changed, 48 insertions(+), 30 deletions(-) diff --git a/pkg/apis/certmanager/v1alpha2/types_certificate.go b/pkg/apis/certmanager/v1alpha2/types_certificate.go index 79a1088c3..a35d5115d 100644 --- a/pkg/apis/certmanager/v1alpha2/types_certificate.go +++ b/pkg/apis/certmanager/v1alpha2/types_certificate.go @@ -151,7 +151,7 @@ type CertificateSpec struct { // The 'name' field in this stanza is required at all times. IssuerRef cmmeta.ObjectReference `json:"issuerRef"` - // IsCA will mark this Certificate as valid for signing. + // IsCA will mark this Certificate as valid for certificate signing. // This will automatically add the `cert sign` usage to the list of `usages`. // +optional IsCA bool `json:"isCA,omitempty"` diff --git a/pkg/apis/certmanager/v1alpha2/types_certificaterequest.go b/pkg/apis/certmanager/v1alpha2/types_certificaterequest.go index 7489f45b3..460454536 100644 --- a/pkg/apis/certmanager/v1alpha2/types_certificaterequest.go +++ b/pkg/apis/certmanager/v1alpha2/types_certificaterequest.go @@ -86,7 +86,8 @@ type CertificateRequestSpec struct { // Byte slice containing the PEM encoded CertificateSigningRequest CSRPEM []byte `json:"csr"` - // IsCA will mark this Certificate as valid for signing. + // IsCA will request to mark the certificate as valid for certificate signing + // when submitting to the issuer. // This will automatically add the `cert sign` usage to the list of `usages`. // +optional IsCA bool `json:"isCA,omitempty"` @@ -105,14 +106,18 @@ type CertificateRequestStatus struct { // +optional Conditions []CertificateRequestCondition `json:"conditions,omitempty"` - // Byte slice containing a PEM encoded signed certificate resulting from the - // given certificate signing request. + // The PEM encoded x509 certificate resulting from the certificate + // signing request. + // If not set, the CertificateRequest has either not been completed or has + // failed. More information on failure can be found by checking the + // `conditions` field. // +optional Certificate []byte `json:"certificate,omitempty"` - // Byte slice containing the PEM encoded certificate authority of the signed - // certificate. - // If not specified, the CA is assumed to be unknown/not available. + // The PEM encoded x509 certificate of the signer, also known as the CA + // (Certificate Authority). + // This is set on a best-effort basis by different issuers. + // If not set, the CA is assumed to be unknown/not available. // +optional CA []byte `json:"ca,omitempty"` diff --git a/pkg/apis/certmanager/v1alpha2/types_issuer.go b/pkg/apis/certmanager/v1alpha2/types_issuer.go index 050cb1a83..052843f21 100644 --- a/pkg/apis/certmanager/v1alpha2/types_issuer.go +++ b/pkg/apis/certmanager/v1alpha2/types_issuer.go @@ -146,8 +146,8 @@ type VenafiIssuer struct { // VenafiTPP defines connection configuration details for a Venafi TPP instance type VenafiTPP struct { - // URL is the base URL for the Venafi TPP instance, for example: - // "https://tpp.example.com/vedsdk". + // URL is the base URL for the vedsdk endpoint of the Venafi TPP instance, + // for example: "https://tpp.example.com/vedsdk". URL string `json:"url"` // CredentialsRef is a reference to a Secret containing the username and @@ -167,7 +167,8 @@ type VenafiTPP struct { // VenafiCloud defines connection configuration details for Venafi Cloud type VenafiCloud struct { - // URL is the base URL for Venafi Cloud, usually: "https://api.venafi.cloud/v1". + // URL is the base URL for Venafi Cloud. + // Defaults to "https://api.venafi.cloud/v1". // +optional URL string `json:"url,omitempty"` diff --git a/pkg/apis/certmanager/v1alpha3/types_certificate.go b/pkg/apis/certmanager/v1alpha3/types_certificate.go index b5dd61c9f..abb9d3f14 100644 --- a/pkg/apis/certmanager/v1alpha3/types_certificate.go +++ b/pkg/apis/certmanager/v1alpha3/types_certificate.go @@ -149,7 +149,7 @@ type CertificateSpec struct { // The 'name' field in this stanza is required at all times. IssuerRef cmmeta.ObjectReference `json:"issuerRef"` - // IsCA will mark this Certificate as valid for signing. + // IsCA will mark this Certificate as valid for certificate signing. // This will automatically add the `cert sign` usage to the list of `usages`. // +optional IsCA bool `json:"isCA,omitempty"` diff --git a/pkg/apis/certmanager/v1alpha3/types_certificaterequest.go b/pkg/apis/certmanager/v1alpha3/types_certificaterequest.go index c58e4081b..7b6fcc2e6 100644 --- a/pkg/apis/certmanager/v1alpha3/types_certificaterequest.go +++ b/pkg/apis/certmanager/v1alpha3/types_certificaterequest.go @@ -86,7 +86,8 @@ type CertificateRequestSpec struct { // Byte slice containing the PEM encoded CertificateSigningRequest CSRPEM []byte `json:"csr"` - // IsCA will mark this Certificate as valid for signing. + // IsCA will request to mark the certificate as valid for certificate signing + // when submitting to the issuer. // This will automatically add the `cert sign` usage to the list of `usages`. // +optional IsCA bool `json:"isCA,omitempty"` @@ -105,14 +106,18 @@ type CertificateRequestStatus struct { // +optional Conditions []CertificateRequestCondition `json:"conditions,omitempty"` - // Byte slice containing a PEM encoded signed certificate resulting from the - // given certificate signing request. + // The PEM encoded x509 certificate resulting from the certificate + // signing request. + // If not set, the CertificateRequest has either not been completed or has + // failed. More information on failure can be found by checking the + // `conditions` field. // +optional Certificate []byte `json:"certificate,omitempty"` - // Byte slice containing the PEM encoded certificate authority of the signed - // certificate. - // If not specified, the CA is assumed to be unknown/not available. + // The PEM encoded x509 certificate of the signer, also known as the CA + // (Certificate Authority). + // This is set on a best-effort basis by different issuers. + // If not set, the CA is assumed to be unknown/not available. // +optional CA []byte `json:"ca,omitempty"` diff --git a/pkg/apis/certmanager/v1alpha3/types_issuer.go b/pkg/apis/certmanager/v1alpha3/types_issuer.go index 480a4a960..19a9f8e25 100644 --- a/pkg/apis/certmanager/v1alpha3/types_issuer.go +++ b/pkg/apis/certmanager/v1alpha3/types_issuer.go @@ -146,8 +146,8 @@ type VenafiIssuer struct { // VenafiTPP defines connection configuration details for a Venafi TPP instance type VenafiTPP struct { - // URL is the base URL for the Venafi TPP instance, for example: - // "https://tpp.example.com/vedsdk". + // URL is the base URL for the vedsdk endpoint of the Venafi TPP instance, + // for example: "https://tpp.example.com/vedsdk". URL string `json:"url"` // CredentialsRef is a reference to a Secret containing the username and @@ -167,7 +167,8 @@ type VenafiTPP struct { // VenafiCloud defines connection configuration details for Venafi Cloud type VenafiCloud struct { - // URL is the base URL for Venafi Cloud, usually: "https://api.venafi.cloud/v1". + // URL is the base URL for Venafi Cloud. + // Defaults to "https://api.venafi.cloud/v1". // +optional URL string `json:"url,omitempty"` diff --git a/pkg/internal/apis/certmanager/types_certificate.go b/pkg/internal/apis/certmanager/types_certificate.go index 01f5dc9e1..64008abb9 100644 --- a/pkg/internal/apis/certmanager/types_certificate.go +++ b/pkg/internal/apis/certmanager/types_certificate.go @@ -129,7 +129,7 @@ type CertificateSpec struct { // The 'name' field in this stanza is required at all times. IssuerRef cmmeta.ObjectReference - // IsCA will mark this Certificate as valid for signing. + // IsCA will mark this Certificate as valid for certificate signing. // This will automatically add the `cert sign` usage to the list of `usages`. IsCA bool diff --git a/pkg/internal/apis/certmanager/types_certificaterequest.go b/pkg/internal/apis/certmanager/types_certificaterequest.go index 7adcf72d6..89865e02f 100644 --- a/pkg/internal/apis/certmanager/types_certificaterequest.go +++ b/pkg/internal/apis/certmanager/types_certificaterequest.go @@ -77,7 +77,8 @@ type CertificateRequestSpec struct { // Byte slice containing the PEM encoded CertificateSigningRequest CSRPEM []byte - // IsCA will mark this Certificate as valid for signing. + // IsCA will request to mark the certificate as valid for certificate signing + // when submitting to the issuer. // This will automatically add the `cert sign` usage to the list of `usages`. IsCA bool @@ -93,13 +94,17 @@ type CertificateRequestStatus struct { // Known condition types are `Ready` and `InvalidRequest`. Conditions []CertificateRequestCondition - // Byte slice containing a PEM encoded signed certificate resulting from the - // given certificate signing request. + // The PEM encoded x509 certificate resulting from the certificate + // signing request. + // If not set, the CertificateRequest has either not been completed or has + // failed. More information on failure can be found by checking the + // `conditions` field. Certificate []byte - // Byte slice containing the PEM encoded certificate authority of the signed - // certificate. - // If not specified, the CA is assumed to be unknown/not available. + // The PEM encoded x509 certificate of the signer, also known as the CA + // (Certificate Authority). + // This is set on a best-effort basis by different issuers. + // If not set, the CA is assumed to be unknown/not available. CA []byte // FailureTime stores the time that this CertificateRequest failed. This is diff --git a/pkg/internal/apis/certmanager/types_issuer.go b/pkg/internal/apis/certmanager/types_issuer.go index e7f21d6d2..a8234d244 100644 --- a/pkg/internal/apis/certmanager/types_issuer.go +++ b/pkg/internal/apis/certmanager/types_issuer.go @@ -127,8 +127,8 @@ type VenafiIssuer struct { // VenafiTPP defines connection configuration details for a Venafi TPP instance type VenafiTPP struct { - // URL is the base URL for the Venafi TPP instance, for example: - // "https://tpp.example.com/vedsdk". + // URL is the base URL for the vedsdk endpoint of the Venafi TPP instance, + // for example: "https://tpp.example.com/vedsdk". URL string // CredentialsRef is a reference to a Secret containing the username and @@ -147,7 +147,8 @@ type VenafiTPP struct { // VenafiCloud defines connection configuration details for Venafi Cloud type VenafiCloud struct { - // URL is the base URL for Venafi Cloud, usually: "https://api.venafi.cloud/v1". + // URL is the base URL for Venafi Cloud. + // Defaults to "https://api.venafi.cloud/v1". URL string // APITokenSecretRef is a secret key selector for the Venafi Cloud API token. From 0fbb31b10ea0b22e910891e864692763c073a535 Mon Sep 17 00:00:00 2001 From: James Munnelly Date: Thu, 25 Jun 2020 15:00:57 +0100 Subject: [PATCH 05/12] generated files Signed-off-by: James Munnelly --- deploy/crds/crd-certificaterequests.yaml | 18 +++++++++++------- deploy/crds/crd-certificates.yaml | 12 ++++++------ deploy/crds/crd-clusterissuers.yaml | 8 ++++---- deploy/crds/crd-issuers.yaml | 8 ++++---- 4 files changed, 25 insertions(+), 21 deletions(-) diff --git a/deploy/crds/crd-certificaterequests.yaml b/deploy/crds/crd-certificaterequests.yaml index ebf7ab56e..b6b1f04e9 100644 --- a/deploy/crds/crd-certificaterequests.yaml +++ b/deploy/crds/crd-certificaterequests.yaml @@ -93,8 +93,9 @@ spec: This option may be ignored/overridden by some issuer types. type: string isCA: - description: IsCA will mark this Certificate as valid for signing. This - will automatically add the `cert sign` usage to the list of `usages`. + description: IsCA will request to mark the certificate as valid for + certificate signing when submitting to the issuer. This will automatically + add the `cert sign` usage to the list of `usages`. type: boolean issuerRef: description: IssuerRef is a reference to the issuer for this CertificateRequest. If @@ -162,14 +163,17 @@ spec: type: object properties: ca: - description: Byte slice containing the PEM encoded certificate authority - of the signed certificate. If not specified, the CA is assumed to - be unknown/not available. + description: The PEM encoded x509 certificate of the signer, also known + as the CA (Certificate Authority). This is set on a best-effort basis + by different issuers. If not set, the CA is assumed to be unknown/not + available. type: string format: byte certificate: - description: Byte slice containing a PEM encoded signed certificate - resulting from the given certificate signing request. + description: The PEM encoded x509 certificate resulting from the certificate + signing request. If not set, the CertificateRequest has either not + been completed or has failed. More information on failure can be found + by checking the `conditions` field. type: string format: byte conditions: diff --git a/deploy/crds/crd-certificates.yaml b/deploy/crds/crd-certificates.yaml index fe5bcd373..b8b0d9c00 100644 --- a/deploy/crds/crd-certificates.yaml +++ b/deploy/crds/crd-certificates.yaml @@ -115,9 +115,9 @@ spec: items: type: string isCA: - description: IsCA will mark this Certificate as valid for signing. - This will automatically add the `cert sign` usage to the list of - `usages`. + description: IsCA will mark this Certificate as valid for certificate + signing. This will automatically add the `cert sign` usage to the + list of `usages`. type: boolean issuerRef: description: IssuerRef is a reference to the issuer for this certificate. @@ -493,9 +493,9 @@ spec: items: type: string isCA: - description: IsCA will mark this Certificate as valid for signing. - This will automatically add the `cert sign` usage to the list of - `usages`. + description: IsCA will mark this Certificate as valid for certificate + signing. This will automatically add the `cert sign` usage to the + list of `usages`. type: boolean issuerRef: description: IssuerRef is a reference to the issuer for this certificate. diff --git a/deploy/crds/crd-clusterissuers.yaml b/deploy/crds/crd-clusterissuers.yaml index 56aa2393e..046ca6a2a 100644 --- a/deploy/crds/crd-clusterissuers.yaml +++ b/deploy/crds/crd-clusterissuers.yaml @@ -1713,8 +1713,8 @@ spec: info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names' type: string url: - description: 'URL is the base URL for Venafi Cloud, usually: - "https://api.venafi.cloud/v1".' + description: URL is the base URL for Venafi Cloud. Defaults + to "https://api.venafi.cloud/v1". type: string tpp: description: TPP specifies Trust Protection Platform configuration @@ -1746,8 +1746,8 @@ spec: info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names' type: string url: - description: 'URL is the base URL for the Venafi TPP instance, - for example: "https://tpp.example.com/vedsdk".' + description: 'URL is the base URL for the vedsdk endpoint of + the Venafi TPP instance, for example: "https://tpp.example.com/vedsdk".' type: string zone: description: Zone is the Venafi Policy Zone to use for this issuer. diff --git a/deploy/crds/crd-issuers.yaml b/deploy/crds/crd-issuers.yaml index 060b4e05b..e3edcb615 100644 --- a/deploy/crds/crd-issuers.yaml +++ b/deploy/crds/crd-issuers.yaml @@ -1712,8 +1712,8 @@ spec: info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names' type: string url: - description: 'URL is the base URL for Venafi Cloud, usually: - "https://api.venafi.cloud/v1".' + description: URL is the base URL for Venafi Cloud. Defaults + to "https://api.venafi.cloud/v1". type: string tpp: description: TPP specifies Trust Protection Platform configuration @@ -1745,8 +1745,8 @@ spec: info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names' type: string url: - description: 'URL is the base URL for the Venafi TPP instance, - for example: "https://tpp.example.com/vedsdk".' + description: 'URL is the base URL for the vedsdk endpoint of + the Venafi TPP instance, for example: "https://tpp.example.com/vedsdk".' type: string zone: description: Zone is the Venafi Policy Zone to use for this issuer. From b8d1f294b999f5a8a21d8f6291a8b416b8b7bfee Mon Sep 17 00:00:00 2001 From: James Munnelly Date: Thu, 25 Jun 2020 16:30:16 +0100 Subject: [PATCH 06/12] Update acme API group doc comments Signed-off-by: James Munnelly --- pkg/apis/acme/v1alpha2/types_issuer.go | 78 +++++++++++++++++++---- pkg/apis/acme/v1alpha2/types_order.go | 10 +-- pkg/apis/acme/v1alpha3/types_issuer.go | 78 +++++++++++++++++++---- pkg/apis/acme/v1alpha3/types_order.go | 10 +-- pkg/internal/apis/acme/types_issuer.go | 85 ++++++++++++++++++++++---- pkg/internal/apis/acme/types_order.go | 7 +-- 6 files changed, 210 insertions(+), 58 deletions(-) diff --git a/pkg/apis/acme/v1alpha2/types_issuer.go b/pkg/apis/acme/v1alpha2/types_issuer.go index 986753c3c..94f0ecf96 100644 --- a/pkg/apis/acme/v1alpha2/types_issuer.go +++ b/pkg/apis/acme/v1alpha2/types_issuer.go @@ -23,30 +23,51 @@ import ( cmmeta "github.com/jetstack/cert-manager/pkg/apis/meta/v1" ) -// ACMEIssuer contains the specification for an ACME issuer +// ACMEIssuer contains the specification for an ACME issuer. +// This uses the RFC8555 specification to obtain certificates by completing +// 'challenges' to prove ownership of domain identifiers. +// Earlier draft versions of the ACME specification are not supported. type ACMEIssuer struct { - // Email is the email for this account + // Email is the email address to be associated with the ACME account. + // This field is optional, but it is strongly recommended to be set. + // It will be used to contact you in case of issues with your account or + // certificates, including expiry notification emails. + // This field may be updated after the account is initially registered. // +optional Email string `json:"email,omitempty"` - // Server is the ACME server URL + // Server is the URL used to access the ACME server's 'directory' endpoint. + // For examples, for Let's Encrypt's staging endpoint, you would use: + // "https://acme-staging-v02.api.letsencrypt.org/directory". + // Only ACME v2 endpoints (i.e. RFC 8555) are supported. Server string `json:"server"` - // If true, skip verifying the ACME server TLS certificate + // If true, requests to the ACME server will not have their TLS certificate + // validated (i.e. insecure connections will be allowed). + // Only enable this option in development environments. + // The cert-manager system installed roots will be used to verify connections + // to the ACME server if this is false. + // Defaults to false. // +optional SkipTLSVerify bool `json:"skipTLSVerify,omitempty"` // ExternalAccountBinding is a reference to a CA external account of the ACME // server. + // If set, upon registration cert-manager will attempt to associate the given + // external account credentials with the registered ACME account. // +optional ExternalAccountBinding *ACMEExternalAccountBinding `json:"externalAccountBinding,omitempty"` - // PrivateKey is the name of a secret containing the private key for this - // user account. + // PrivateKey is the name of a Secret resource that will be used to store the + // automatically generated ACME account private key. + // If `key` is not specified, a default of `tls.key` will be used. PrivateKey cmmeta.SecretKeySelector `json:"privateKeySecretRef"` // Solvers is a list of challenge solvers that will be used to solve // ACME challenges for the matching domains. + // Solver configurations must be provided in order to obtain certificates + // from an ACME server. + // For more information, see: https://cert-manager.io/docs/configuration/acme/ // +optional Solvers []ACMEChallengeSolver `json:"solvers,omitempty"` } @@ -66,8 +87,8 @@ type ACMEExternalAccountBinding struct { // encoded data. Key cmmeta.SecretKeySelector `json:"keySecretRef"` - // keyAlgorithm is the MAC key algorithm that the key is used for. Valid - // values are "HS256", "HS384" and "HS512". + // keyAlgorithm is the MAC key algorithm that the key is used for. + // Valid values are "HS256", "HS384" and "HS512". KeyAlgorithm HMACKeyAlgorithm `json:"keyAlgorithm"` } @@ -81,14 +102,25 @@ const ( HS512 HMACKeyAlgorithm = "HS512" ) +// Configures an issuer to solve challenges using the specified options. +// Only one of HTTP01 or DNS01 may be provided. type ACMEChallengeSolver struct { // Selector selects a set of DNSNames on the Certificate resource that // should be solved using this challenge solver. + // If not specified, the solver will be treated as the 'default' solver + // with the lowest priority, i.e. if any other solver has a more specific + // match, it will be used instead. Selector *CertificateDNSNameSelector `json:"selector,omitempty"` + // Configures cert-manager to attempt to complete authorizations by + // performing the HTTP01 challenge flow. + // It is not possible to obtain certificates for wildcard domain names + // (e.g. `*.example.com`) using the HTTP01 challenge mechanism. // +optional HTTP01 *ACMEChallengeSolverHTTP01 `json:"http01,omitempty"` + // Configures cert-manager to attempt to complete authorizations by + // performing the DNS01 challenge flow. // +optional DNS01 *ACMEChallengeSolverDNS01 `json:"dns01,omitempty"` } @@ -230,36 +262,51 @@ type ACMEChallengeSolverHTTP01IngressObjectMeta struct { Labels map[string]string `json:"labels,omitempty"` } +// Used to configure a DNS01 challenge provider to be used when solving DNS01 +// challenges. +// Only one DNS provider may be configured per solver. type ACMEChallengeSolverDNS01 struct { // CNAMEStrategy configures how the DNS01 provider should handle CNAME // records when found in DNS zones. // +optional CNAMEStrategy CNAMEStrategy `json:"cnameStrategy,omitempty"` + // Use the Akamai DNS zone management API to manage DNS01 challenge records. // +optional Akamai *ACMEIssuerDNS01ProviderAkamai `json:"akamai,omitempty"` + // Use the Google Cloud DNS API to manage DNS01 challenge records. // +optional CloudDNS *ACMEIssuerDNS01ProviderCloudDNS `json:"clouddns,omitempty"` + // Use the Cloudflare API to manage DNS01 challenge records. // +optional Cloudflare *ACMEIssuerDNS01ProviderCloudflare `json:"cloudflare,omitempty"` + // Use the AWS Route53 API to manage DNS01 challenge records. // +optional Route53 *ACMEIssuerDNS01ProviderRoute53 `json:"route53,omitempty"` + // Use the Microsoft Azure DNS API to manage DNS01 challenge records. // +optional AzureDNS *ACMEIssuerDNS01ProviderAzureDNS `json:"azuredns,omitempty"` + // Use the DigitalOcean DNS API to manage DNS01 challenge records. // +optional DigitalOcean *ACMEIssuerDNS01ProviderDigitalOcean `json:"digitalocean,omitempty"` + // Use the 'ACME DNS' (https://github.com/joohoi/acme-dns) API to manage + // DNS01 challenge records. // +optional AcmeDNS *ACMEIssuerDNS01ProviderAcmeDNS `json:"acmedns,omitempty"` + // Use RFC2136 ("Dynamic Updates in the Domain Name System") (https://datatracker.ietf.org/doc/rfc2136/) + // to manage DNS01 challenge records. // +optional RFC2136 *ACMEIssuerDNS01ProviderRFC2136 `json:"rfc2136,omitempty"` + // Configure an external webhook based DNS01 challenge solver to manage + // DNS01 challenge records. // +optional Webhook *ACMEIssuerDNS01ProviderWebhook `json:"webhook,omitempty"` } @@ -301,11 +348,19 @@ type ACMEIssuerDNS01ProviderCloudDNS struct { } // ACMEIssuerDNS01ProviderCloudflare is a structure containing the DNS -// configuration for Cloudflare +// configuration for Cloudflare. +// One of `apiKeySecretRef` or `apiTokenSecretRef` must be provided. type ACMEIssuerDNS01ProviderCloudflare struct { + // Email of the account, only required when using API key based authentication. // +optional - Email string `json:"email"` - APIKey *cmmeta.SecretKeySelector `json:"apiKeySecretRef,omitempty"` + Email string `json:"email"` + + // API key to use to authenticate with Cloudflare. + // Note: using an API token to authenticate is now the recommended method + // as it allows greater control of permissions. + APIKey *cmmeta.SecretKeySelector `json:"apiKeySecretRef,omitempty"` + + // API token used to authenticate with Cloudflare. APIToken *cmmeta.SecretKeySelector `json:"apiTokenSecretRef,omitempty"` } @@ -344,7 +399,6 @@ type ACMEIssuerDNS01ProviderRoute53 struct { // ACMEIssuerDNS01ProviderAzureDNS is a structure containing the // configuration for Azure DNS type ACMEIssuerDNS01ProviderAzureDNS struct { - // if both this and ClientSecret are left unset MSI will be used // +optional ClientID string `json:"clientID,omitempty"` diff --git a/pkg/apis/acme/v1alpha2/types_order.go b/pkg/apis/acme/v1alpha2/types_order.go index 9a30c331a..945affed0 100644 --- a/pkg/apis/acme/v1alpha2/types_order.go +++ b/pkg/apis/acme/v1alpha2/types_order.go @@ -65,21 +65,15 @@ type OrderSpec struct { IssuerRef cmmeta.ObjectReference `json:"issuerRef"` // CommonName is the common name as specified on the DER encoded CSR. - // If CommonName is not specified, the first DNSName specified will be used - // as the CommonName. - // At least one of CommonName or a DNSNames must be set. + // If specified, this value must also be present in `dnsNames`. // This field must match the corresponding field on the DER encoded CSR. // +optional CommonName string `json:"commonName,omitempty"` // DNSNames is a list of DNS names that should be included as part of the Order // validation process. - // If CommonName is not specified, the first DNSName specified will be used - // as the CommonName. - // At least one of CommonName or a DNSNames must be set. // This field must match the corresponding field on the DER encoded CSR. - // +optional - DNSNames []string `json:"dnsNames,omitempty"` + DNSNames []string `json:"dnsNames"` } type OrderStatus struct { diff --git a/pkg/apis/acme/v1alpha3/types_issuer.go b/pkg/apis/acme/v1alpha3/types_issuer.go index 00a29518a..04f06eddb 100644 --- a/pkg/apis/acme/v1alpha3/types_issuer.go +++ b/pkg/apis/acme/v1alpha3/types_issuer.go @@ -23,30 +23,51 @@ import ( cmmeta "github.com/jetstack/cert-manager/pkg/apis/meta/v1" ) -// ACMEIssuer contains the specification for an ACME issuer +// ACMEIssuer contains the specification for an ACME issuer. +// This uses the RFC8555 specification to obtain certificates by completing +// 'challenges' to prove ownership of domain identifiers. +// Earlier draft versions of the ACME specification are not supported. type ACMEIssuer struct { - // Email is the email for this account + // Email is the email address to be associated with the ACME account. + // This field is optional, but it is strongly recommended to be set. + // It will be used to contact you in case of issues with your account or + // certificates, including expiry notification emails. + // This field may be updated after the account is initially registered. // +optional Email string `json:"email,omitempty"` - // Server is the ACME server URL + // Server is the URL used to access the ACME server's 'directory' endpoint. + // For examples, for Let's Encrypt's staging endpoint, you would use: + // "https://acme-staging-v02.api.letsencrypt.org/directory". + // Only ACME v2 endpoints (i.e. RFC 8555) are supported. Server string `json:"server"` - // If true, skip verifying the ACME server TLS certificate + // If true, requests to the ACME server will not have their TLS certificate + // validated (i.e. insecure connections will be allowed). + // Only enable this option in development environments. + // The cert-manager system installed roots will be used to verify connections + // to the ACME server if this is false. + // Defaults to false. // +optional SkipTLSVerify bool `json:"skipTLSVerify,omitempty"` // ExternalAccountBinding is a reference to a CA external account of the ACME // server. + // If set, upon registration cert-manager will attempt to associate the given + // external account credentials with the registered ACME account. // +optional ExternalAccountBinding *ACMEExternalAccountBinding `json:"externalAccountBinding,omitempty"` - // PrivateKey is the name of a secret containing the private key for this - // user account. + // PrivateKey is the name of a Secret resource that will be used to store the + // automatically generated ACME account private key. + // If `key` is not specified, a default of `tls.key` will be used. PrivateKey cmmeta.SecretKeySelector `json:"privateKeySecretRef"` // Solvers is a list of challenge solvers that will be used to solve // ACME challenges for the matching domains. + // Solver configurations must be provided in order to obtain certificates + // from an ACME server. + // For more information, see: https://cert-manager.io/docs/configuration/acme/ // +optional Solvers []ACMEChallengeSolver `json:"solvers,omitempty"` } @@ -66,8 +87,8 @@ type ACMEExternalAccountBinding struct { // encoded data. Key cmmeta.SecretKeySelector `json:"keySecretRef"` - // keyAlgorithm is the MAC key algorithm that the key is used for. Valid - // values are "HS256", "HS384" and "HS512". + // keyAlgorithm is the MAC key algorithm that the key is used for. + // Valid values are "HS256", "HS384" and "HS512". KeyAlgorithm HMACKeyAlgorithm `json:"keyAlgorithm"` } @@ -81,14 +102,25 @@ const ( HS512 HMACKeyAlgorithm = "HS512" ) +// Configures an issuer to solve challenges using the specified options. +// Only one of HTTP01 or DNS01 may be provided. type ACMEChallengeSolver struct { // Selector selects a set of DNSNames on the Certificate resource that // should be solved using this challenge solver. + // If not specified, the solver will be treated as the 'default' solver + // with the lowest priority, i.e. if any other solver has a more specific + // match, it will be used instead. Selector *CertificateDNSNameSelector `json:"selector,omitempty"` + // Configures cert-manager to attempt to complete authorizations by + // performing the HTTP01 challenge flow. + // It is not possible to obtain certificates for wildcard domain names + // (e.g. `*.example.com`) using the HTTP01 challenge mechanism. // +optional HTTP01 *ACMEChallengeSolverHTTP01 `json:"http01,omitempty"` + // Configures cert-manager to attempt to complete authorizations by + // performing the DNS01 challenge flow. // +optional DNS01 *ACMEChallengeSolverDNS01 `json:"dns01,omitempty"` } @@ -230,36 +262,51 @@ type ACMEChallengeSolverHTTP01IngressObjectMeta struct { Labels map[string]string `json:"labels,omitempty"` } +// Used to configure a DNS01 challenge provider to be used when solving DNS01 +// challenges. +// Only one DNS provider may be configured per solver. type ACMEChallengeSolverDNS01 struct { // CNAMEStrategy configures how the DNS01 provider should handle CNAME // records when found in DNS zones. // +optional CNAMEStrategy CNAMEStrategy `json:"cnameStrategy,omitempty"` + // Use the Akamai DNS zone management API to manage DNS01 challenge records. // +optional Akamai *ACMEIssuerDNS01ProviderAkamai `json:"akamai,omitempty"` + // Use the Google Cloud DNS API to manage DNS01 challenge records. // +optional CloudDNS *ACMEIssuerDNS01ProviderCloudDNS `json:"clouddns,omitempty"` + // Use the Cloudflare API to manage DNS01 challenge records. // +optional Cloudflare *ACMEIssuerDNS01ProviderCloudflare `json:"cloudflare,omitempty"` + // Use the AWS Route53 API to manage DNS01 challenge records. // +optional Route53 *ACMEIssuerDNS01ProviderRoute53 `json:"route53,omitempty"` + // Use the Microsoft Azure DNS API to manage DNS01 challenge records. // +optional AzureDNS *ACMEIssuerDNS01ProviderAzureDNS `json:"azuredns,omitempty"` + // Use the DigitalOcean DNS API to manage DNS01 challenge records. // +optional DigitalOcean *ACMEIssuerDNS01ProviderDigitalOcean `json:"digitalocean,omitempty"` + // Use the 'ACME DNS' (https://github.com/joohoi/acme-dns) API to manage + // DNS01 challenge records. // +optional AcmeDNS *ACMEIssuerDNS01ProviderAcmeDNS `json:"acmedns,omitempty"` + // Use RFC2136 ("Dynamic Updates in the Domain Name System") (https://datatracker.ietf.org/doc/rfc2136/) + // to manage DNS01 challenge records. // +optional RFC2136 *ACMEIssuerDNS01ProviderRFC2136 `json:"rfc2136,omitempty"` + // Configure an external webhook based DNS01 challenge solver to manage + // DNS01 challenge records. // +optional Webhook *ACMEIssuerDNS01ProviderWebhook `json:"webhook,omitempty"` } @@ -301,11 +348,19 @@ type ACMEIssuerDNS01ProviderCloudDNS struct { } // ACMEIssuerDNS01ProviderCloudflare is a structure containing the DNS -// configuration for Cloudflare +// configuration for Cloudflare. +// One of `apiKeySecretRef` or `apiTokenSecretRef` must be provided. type ACMEIssuerDNS01ProviderCloudflare struct { + // Email of the account, only required when using API key based authentication. // +optional - Email string `json:"email"` - APIKey *cmmeta.SecretKeySelector `json:"apiKeySecretRef,omitempty"` + Email string `json:"email"` + + // API key to use to authenticate with Cloudflare. + // Note: using an API token to authenticate is now the recommended method + // as it allows greater control of permissions. + APIKey *cmmeta.SecretKeySelector `json:"apiKeySecretRef,omitempty"` + + // API token used to authenticate with Cloudflare. APIToken *cmmeta.SecretKeySelector `json:"apiTokenSecretRef,omitempty"` } @@ -344,7 +399,6 @@ type ACMEIssuerDNS01ProviderRoute53 struct { // ACMEIssuerDNS01ProviderAzureDNS is a structure containing the // configuration for Azure DNS type ACMEIssuerDNS01ProviderAzureDNS struct { - // if both this and ClientSecret are left unset MSI will be used // +optional ClientID string `json:"clientID,omitempty"` diff --git a/pkg/apis/acme/v1alpha3/types_order.go b/pkg/apis/acme/v1alpha3/types_order.go index 4681c6dff..76549dfc9 100644 --- a/pkg/apis/acme/v1alpha3/types_order.go +++ b/pkg/apis/acme/v1alpha3/types_order.go @@ -65,21 +65,15 @@ type OrderSpec struct { IssuerRef cmmeta.ObjectReference `json:"issuerRef"` // CommonName is the common name as specified on the DER encoded CSR. - // If CommonName is not specified, the first DNSName specified will be used - // as the CommonName. - // At least one of CommonName or a DNSNames must be set. + // If specified, this value must also be present in `dnsNames`. // This field must match the corresponding field on the DER encoded CSR. // +optional CommonName string `json:"commonName,omitempty"` // DNSNames is a list of DNS names that should be included as part of the Order // validation process. - // If CommonName is not specified, the first DNSName specified will be used - // as the CommonName. - // At least one of CommonName or a DNSNames must be set. // This field must match the corresponding field on the DER encoded CSR. - // +optional - DNSNames []string `json:"dnsNames,omitempty"` + DNSNames []string `json:"dnsNames"` } type OrderStatus struct { diff --git a/pkg/internal/apis/acme/types_issuer.go b/pkg/internal/apis/acme/types_issuer.go index 65b04a3b4..7beedc8d5 100644 --- a/pkg/internal/apis/acme/types_issuer.go +++ b/pkg/internal/apis/acme/types_issuer.go @@ -23,27 +23,49 @@ import ( cmmeta "github.com/jetstack/cert-manager/pkg/internal/apis/meta" ) -// ACMEIssuer contains the specification for an ACME issuer + +// ACMEIssuer contains the specification for an ACME issuer. +// This uses the RFC8555 specification to obtain certificates by completing +// 'challenges' to prove ownership of domain identifiers. +// Earlier draft versions of the ACME specification are not supported. type ACMEIssuer struct { - // Email is the email for this account + // Email is the email address to be associated with the ACME account. + // This field is optional, but it is strongly recommended to be set. + // It will be used to contact you in case of issues with your account or + // certificates, including expiry notification emails. + // This field may be updated after the account is initially registered. Email string - // Server is the ACME server URL + // Server is the URL used to access the ACME server's 'directory' endpoint. + // For examples, for Let's Encrypt's staging endpoint, you would use: + // "https://acme-staging-v02.api.letsencrypt.org/directory". + // Only ACME v2 endpoints (i.e. RFC 8555) are supported. Server string - // If true, skip verifying the ACME server TLS certificate + // If true, requests to the ACME server will not have their TLS certificate + // validated (i.e. insecure connections will be allowed). + // Only enable this option in development environments. + // The cert-manager system installed roots will be used to verify connections + // to the ACME server if this is false. + // Defaults to false. SkipTLSVerify bool // ExternalAccountBinding is a reference to a CA external account of the ACME // server. + // If set, upon registration cert-manager will attempt to associate the given + // external account credentials with the registered ACME account. ExternalAccountBinding *ACMEExternalAccountBinding - // PrivateKey is the name of a secret containing the private key for this - // user account. + // PrivateKey is the name of a Secret resource that will be used to store the + // automatically generated ACME account private key. + // If `key` is not specified, a default of `tls.key` will be used. PrivateKey cmmeta.SecretKeySelector // Solvers is a list of challenge solvers that will be used to solve // ACME challenges for the matching domains. + // Solver configurations must be provided in order to obtain certificates + // from an ACME server. + // For more information, see: https://cert-manager.io/docs/configuration/acme/ Solvers []ACMEChallengeSolver } @@ -58,10 +80,12 @@ type ACMEExternalAccountBinding struct { // The `key` is the index string that is paired with the key data in the // Secret and should not be confused with the key data itself, or indeed with // the External Account Binding keyID above. + // The secret key stored in the Secret **must** be un-padded, base64 URL + // encoded data. Key cmmeta.SecretKeySelector - // keyAlgorithm is the MAC key algorithm that the key is used for. Valid - // values are "HS256", "HS384" and "HS512". + // keyAlgorithm is the MAC key algorithm that the key is used for. + // Valid values are "HS256", "HS384" and "HS512". KeyAlgorithm HMACKeyAlgorithm } @@ -74,13 +98,24 @@ const ( HS512 HMACKeyAlgorithm = "HS512" ) +// Configures an issuer to solve challenges using the specified options. +// Only one of HTTP01 or DNS01 may be provided. type ACMEChallengeSolver struct { // Selector selects a set of DNSNames on the Certificate resource that // should be solved using this challenge solver. + // If not specified, the solver will be treated as the 'default' solver + // with the lowest priority, i.e. if any other solver has a more specific + // match, it will be used instead. Selector *CertificateDNSNameSelector + // Configures cert-manager to attempt to complete authorizations by + // performing the HTTP01 challenge flow. + // It is not possible to obtain certificates for wildcard domain names + // (e.g. `*.example.com`) using the HTTP01 challenge mechanism. HTTP01 *ACMEChallengeSolverHTTP01 + // Configures cert-manager to attempt to complete authorizations by + // performing the DNS01 challenge flow. DNS01 *ACMEChallengeSolverDNS01 } @@ -202,27 +237,42 @@ type ACMEChallengeSolverHTTP01IngressObjectMeta struct { Labels map[string]string } +// Used to configure a DNS01 challenge provider to be used when solving DNS01 +// challenges. +// Only one DNS provider may be configured per solver. type ACMEChallengeSolverDNS01 struct { // CNAMEStrategy configures how the DNS01 provider should handle CNAME // records when found in DNS zones. CNAMEStrategy CNAMEStrategy + // Use the Akamai DNS zone management API to manage DNS01 challenge records. Akamai *ACMEIssuerDNS01ProviderAkamai + // Use the Google Cloud DNS API to manage DNS01 challenge records. CloudDNS *ACMEIssuerDNS01ProviderCloudDNS + // Use the Cloudflare API to manage DNS01 challenge records. Cloudflare *ACMEIssuerDNS01ProviderCloudflare + // Use the AWS Route53 API to manage DNS01 challenge records. Route53 *ACMEIssuerDNS01ProviderRoute53 + // Use the Microsoft Azure DNS API to manage DNS01 challenge records. AzureDNS *ACMEIssuerDNS01ProviderAzureDNS + // Use the DigitalOcean DNS API to manage DNS01 challenge records. DigitalOcean *ACMEIssuerDNS01ProviderDigitalOcean + // Use the 'ACME DNS' (https://github.com/joohoi/acme-dns) API to manage + // DNS01 challenge records. AcmeDNS *ACMEIssuerDNS01ProviderAcmeDNS + // Use RFC2136 ("Dynamic Updates in the Domain Name System") (https://datatracker.ietf.org/doc/rfc2136/) + // to manage DNS01 challenge records. RFC2136 *ACMEIssuerDNS01ProviderRFC2136 + // Configure an external webhook based DNS01 challenge solver to manage + // DNS01 challenge records. Webhook *ACMEIssuerDNS01ProviderWebhook } @@ -261,10 +311,18 @@ type ACMEIssuerDNS01ProviderCloudDNS struct { } // ACMEIssuerDNS01ProviderCloudflare is a structure containing the DNS -// configuration for Cloudflare +// configuration for Cloudflare. +// One of `apiKeySecretRef` or `apiTokenSecretRef` must be provided. type ACMEIssuerDNS01ProviderCloudflare struct { - Email string - APIKey *cmmeta.SecretKeySelector + // Email of the account, only required when using API key based authentication. + Email string + + // API key to use to authenticate with Cloudflare. + // Note: using an API token to authenticate is now the recommended method + // as it allows greater control of permissions. + APIKey *cmmeta.SecretKeySelector + + // API token used to authenticate with Cloudflare. APIToken *cmmeta.SecretKeySelector } @@ -299,12 +357,15 @@ type ACMEIssuerDNS01ProviderRoute53 struct { // ACMEIssuerDNS01ProviderAzureDNS is a structure containing the // configuration for Azure DNS type ACMEIssuerDNS01ProviderAzureDNS struct { + // if both this and ClientSecret are left unset MSI will be used ClientID string + // if both this and ClientID are left unset MSI will be used ClientSecret *cmmeta.SecretKeySelector SubscriptionID string + // when specifying ClientID and ClientSecret then this field is also needed TenantID string ResourceGroupName string @@ -374,7 +435,7 @@ type ACMEIssuerDNS01ProviderWebhook struct { // This can contain arbitrary JSON data. // Secret values should not be specified in this stanza. // If secret values are needed (e.g. credentials for a DNS service), you - // should use a cmmeta.SecretKeySelector to reference a Secret resource. + // should use a SecretKeySelector to reference a Secret resource. // For details on the schema of this field, consult the webhook provider // implementation's documentation. Config *apiext.JSON diff --git a/pkg/internal/apis/acme/types_order.go b/pkg/internal/apis/acme/types_order.go index d018ea706..dfe7b22d7 100644 --- a/pkg/internal/apis/acme/types_order.go +++ b/pkg/internal/apis/acme/types_order.go @@ -57,17 +57,12 @@ type OrderSpec struct { IssuerRef cmmeta.ObjectReference // CommonName is the common name as specified on the DER encoded CSR. - // If CommonName is not specified, the first DNSName specified will be used - // as the CommonName. - // At least one of CommonName or a DNSNames must be set. + // If specified, this value must also be present in `dnsNames`. // This field must match the corresponding field on the DER encoded CSR. CommonName string // DNSNames is a list of DNS names that should be included as part of the Order // validation process. - // If CommonName is not specified, the first DNSName specified will be used - // as the CommonName. - // At least one of CommonName or a DNSNames must be set. // This field must match the corresponding field on the DER encoded CSR. DNSNames []string } From 565210f0df8f66f06d84571a4d27bc30f3b7137a Mon Sep 17 00:00:00 2001 From: James Munnelly Date: Thu, 25 Jun 2020 16:30:54 +0100 Subject: [PATCH 07/12] generated files Signed-off-by: James Munnelly --- deploy/crds/crd-challenges.yaml | 62 ++++++++++-------- deploy/crds/crd-clusterissuers.yaml | 98 ++++++++++++++++++----------- deploy/crds/crd-issuers.yaml | 98 ++++++++++++++++++----------- deploy/crds/crd-orders.yaml | 13 ++-- 4 files changed, 166 insertions(+), 105 deletions(-) diff --git a/deploy/crds/crd-challenges.yaml b/deploy/crds/crd-challenges.yaml index 4a16fa671..23a7b0072 100644 --- a/deploy/crds/crd-challenges.yaml +++ b/deploy/crds/crd-challenges.yaml @@ -131,11 +131,13 @@ spec: type: object properties: dns01: + description: Configures cert-manager to attempt to complete authorizations + by performing the DNS01 challenge flow. type: object properties: acmedns: - description: ACMEIssuerDNS01ProviderAcmeDNS is a structure containing - the configuration for ACME-DNS servers + description: Use the 'ACME DNS' (https://github.com/joohoi/acme-dns) + API to manage DNS01 challenge records. type: object required: - accountSecretRef @@ -157,9 +159,8 @@ spec: host: type: string akamai: - description: ACMEIssuerDNS01ProviderAkamai is a structure containing - the DNS configuration for Akamai DNS—Zone Record Management - API + description: Use the Akamai DNS zone management API to manage + DNS01 challenge records. type: object required: - accessTokenSecretRef @@ -209,8 +210,8 @@ spec: serviceConsumerDomain: type: string azuredns: - description: ACMEIssuerDNS01ProviderAzureDNS is a structure - containing the configuration for Azure DNS + description: Use the Microsoft Azure DNS API to manage DNS01 + challenge records. type: object required: - resourceGroupName @@ -253,8 +254,8 @@ spec: this field is also needed type: string clouddns: - description: ACMEIssuerDNS01ProviderCloudDNS is a structure - containing the DNS configuration for Google Cloud DNS + description: Use the Google Cloud DNS API to manage DNS01 challenge + records. type: object required: - project @@ -275,11 +276,14 @@ spec: More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names' type: string cloudflare: - description: ACMEIssuerDNS01ProviderCloudflare is a structure - containing the DNS configuration for Cloudflare + description: Use the Cloudflare API to manage DNS01 challenge + records. type: object properties: apiKeySecretRef: + description: 'API key to use to authenticate with Cloudflare. + Note: using an API token to authenticate is now the recommended + method as it allows greater control of permissions.' type: object required: - name @@ -293,6 +297,7 @@ spec: More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names' type: string apiTokenSecretRef: + description: API token used to authenticate with Cloudflare. type: object required: - name @@ -306,6 +311,8 @@ spec: More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names' type: string email: + description: Email of the account, only required when using + API key based authentication. type: string cnameStrategy: description: CNAMEStrategy configures how the DNS01 provider @@ -315,8 +322,8 @@ spec: - None - Follow digitalocean: - description: ACMEIssuerDNS01ProviderDigitalOcean is a structure - containing the DNS configuration for DigitalOcean Domains + description: Use the DigitalOcean DNS API to manage DNS01 challenge + records. type: object required: - tokenSecretRef @@ -335,8 +342,9 @@ spec: More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names' type: string rfc2136: - description: ACMEIssuerDNS01ProviderRFC2136 is a structure containing - the configuration for RFC2136 DNS + description: Use RFC2136 ("Dynamic Updates in the Domain Name + System") (https://datatracker.ietf.org/doc/rfc2136/) to manage + DNS01 challenge records. type: object required: - nameserver @@ -375,8 +383,8 @@ spec: More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names' type: string route53: - description: ACMEIssuerDNS01ProviderRoute53 is a structure containing - the Route 53 configuration for AWS + description: Use the AWS Route53 API to manage DNS01 challenge + records. type: object required: - region @@ -418,9 +426,8 @@ spec: More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names' type: string webhook: - description: ACMEIssuerDNS01ProviderWebhook specifies configuration - for a webhook DNS01 provider, including where to POST ChallengePayload - resources. + description: Configure an external webhook based DNS01 challenge + solver to manage DNS01 challenge records. type: object required: - groupName @@ -448,12 +455,10 @@ spec: be the name of the provider, e.g. 'cloudflare'. type: string http01: - description: ACMEChallengeSolverHTTP01 contains configuration detailing - how to solve HTTP01 challenges within a Kubernetes cluster. Typically - this is accomplished through creating 'routes' of some description - that configure ingress controllers to direct traffic to 'solver - pods', which are responsible for responding to the ACME server's - HTTP requests. + description: Configures cert-manager to attempt to complete authorizations + by performing the HTTP01 challenge flow. It is not possible to + obtain certificates for wildcard domain names (e.g. `*.example.com`) + using the HTTP01 challenge mechanism. type: object properties: ingress: @@ -1366,7 +1371,10 @@ spec: type: string selector: description: Selector selects a set of DNSNames on the Certificate - resource that should be solved using this challenge solver. + resource that should be solved using this challenge solver. If + not specified, the solver will be treated as the 'default' solver + with the lowest priority, i.e. if any other solver has a more + specific match, it will be used instead. type: object properties: dnsNames: diff --git a/deploy/crds/crd-clusterissuers.yaml b/deploy/crds/crd-clusterissuers.yaml index 046ca6a2a..f604ae404 100644 --- a/deploy/crds/crd-clusterissuers.yaml +++ b/deploy/crds/crd-clusterissuers.yaml @@ -85,11 +85,17 @@ spec: - server properties: email: - description: Email is the email for this account + description: Email is the email address to be associated with the + ACME account. This field is optional, but it is strongly recommended + to be set. It will be used to contact you in case of issues with + your account or certificates, including expiry notification emails. + This field may be updated after the account is initially registered. type: string externalAccountBinding: description: ExternalAccountBinding is a reference to a CA external - account of the ACME server. + account of the ACME server. If set, upon registration cert-manager + will attempt to associate the given external account credentials + with the registered ACME account. type: object required: - keyAlgorithm @@ -130,8 +136,10 @@ spec: info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names' type: string privateKeySecretRef: - description: PrivateKey is the name of a secret containing the private - key for this user account. + description: PrivateKey is the name of a Secret resource that will + be used to store the automatically generated ACME account private + key. If `key` is not specified, a default of `tls.key` will be + used. type: object required: - name @@ -145,24 +153,37 @@ spec: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names' type: string server: - description: Server is the ACME server URL + description: 'Server is the URL used to access the ACME server''s + ''directory'' endpoint. For examples, for Let''s Encrypt''s staging + endpoint, you would use: "https://acme-staging-v02.api.letsencrypt.org/directory". + Only ACME v2 endpoints (i.e. RFC 8555) are supported.' type: string skipTLSVerify: - description: If true, skip verifying the ACME server TLS certificate + description: If true, requests to the ACME server will not have + their TLS certificate validated (i.e. insecure connections will + be allowed). Only enable this option in development environments. + The cert-manager system installed roots will be used to verify + connections to the ACME server if this is false. Defaults to false. type: boolean solvers: - description: Solvers is a list of challenge solvers that will be - used to solve ACME challenges for the matching domains. + description: 'Solvers is a list of challenge solvers that will be + used to solve ACME challenges for the matching domains. Solver + configurations must be provided in order to obtain certificates + from an ACME server. For more information, see: https://cert-manager.io/docs/configuration/acme/' type: array items: + description: Configures an issuer to solve challenges using the + specified options. Only one of HTTP01 or DNS01 may be provided. type: object properties: dns01: + description: Configures cert-manager to attempt to complete + authorizations by performing the DNS01 challenge flow. type: object properties: acmedns: - description: ACMEIssuerDNS01ProviderAcmeDNS is a structure - containing the configuration for ACME-DNS servers + description: Use the 'ACME DNS' (https://github.com/joohoi/acme-dns) + API to manage DNS01 challenge records. type: object required: - accountSecretRef @@ -184,9 +205,8 @@ spec: host: type: string akamai: - description: ACMEIssuerDNS01ProviderAkamai is a structure - containing the DNS configuration for Akamai DNS—Zone - Record Management API + description: Use the Akamai DNS zone management API to + manage DNS01 challenge records. type: object required: - accessTokenSecretRef @@ -236,8 +256,8 @@ spec: serviceConsumerDomain: type: string azuredns: - description: ACMEIssuerDNS01ProviderAzureDNS is a structure - containing the configuration for Azure DNS + description: Use the Microsoft Azure DNS API to manage + DNS01 challenge records. type: object required: - resourceGroupName @@ -280,8 +300,8 @@ spec: then this field is also needed type: string clouddns: - description: ACMEIssuerDNS01ProviderCloudDNS is a structure - containing the DNS configuration for Google Cloud DNS + description: Use the Google Cloud DNS API to manage DNS01 + challenge records. type: object required: - project @@ -302,11 +322,15 @@ spec: to. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names' type: string cloudflare: - description: ACMEIssuerDNS01ProviderCloudflare is a structure - containing the DNS configuration for Cloudflare + description: Use the Cloudflare API to manage DNS01 challenge + records. type: object properties: apiKeySecretRef: + description: 'API key to use to authenticate with + Cloudflare. Note: using an API token to authenticate + is now the recommended method as it allows greater + control of permissions.' type: object required: - name @@ -320,6 +344,7 @@ spec: to. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names' type: string apiTokenSecretRef: + description: API token used to authenticate with Cloudflare. type: object required: - name @@ -333,6 +358,8 @@ spec: to. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names' type: string email: + description: Email of the account, only required when + using API key based authentication. type: string cnameStrategy: description: CNAMEStrategy configures how the DNS01 provider @@ -342,9 +369,8 @@ spec: - None - Follow digitalocean: - description: ACMEIssuerDNS01ProviderDigitalOcean is a - structure containing the DNS configuration for DigitalOcean - Domains + description: Use the DigitalOcean DNS API to manage DNS01 + challenge records. type: object required: - tokenSecretRef @@ -363,8 +389,9 @@ spec: to. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names' type: string rfc2136: - description: ACMEIssuerDNS01ProviderRFC2136 is a structure - containing the configuration for RFC2136 DNS + description: Use RFC2136 ("Dynamic Updates in the Domain + Name System") (https://datatracker.ietf.org/doc/rfc2136/) + to manage DNS01 challenge records. type: object required: - nameserver @@ -405,8 +432,8 @@ spec: to. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names' type: string route53: - description: ACMEIssuerDNS01ProviderRoute53 is a structure - containing the Route 53 configuration for AWS + description: Use the AWS Route53 API to manage DNS01 challenge + records. type: object required: - region @@ -449,9 +476,8 @@ spec: to. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names' type: string webhook: - description: ACMEIssuerDNS01ProviderWebhook specifies - configuration for a webhook DNS01 provider, including - where to POST ChallengePayload resources. + description: Configure an external webhook based DNS01 + challenge solver to manage DNS01 challenge records. type: object required: - groupName @@ -480,12 +506,11 @@ spec: typically be the name of the provider, e.g. 'cloudflare'. type: string http01: - description: ACMEChallengeSolverHTTP01 contains configuration - detailing how to solve HTTP01 challenges within a Kubernetes - cluster. Typically this is accomplished through creating - 'routes' of some description that configure ingress controllers - to direct traffic to 'solver pods', which are responsible - for responding to the ACME server's HTTP requests. + description: Configures cert-manager to attempt to complete + authorizations by performing the HTTP01 challenge flow. + It is not possible to obtain certificates for wildcard domain + names (e.g. `*.example.com`) using the HTTP01 challenge + mechanism. type: object properties: ingress: @@ -1502,6 +1527,9 @@ spec: selector: description: Selector selects a set of DNSNames on the Certificate resource that should be solved using this challenge solver. + If not specified, the solver will be treated as the 'default' + solver with the lowest priority, i.e. if any other solver + has a more specific match, it will be used instead. type: object properties: dnsNames: diff --git a/deploy/crds/crd-issuers.yaml b/deploy/crds/crd-issuers.yaml index e3edcb615..74c122010 100644 --- a/deploy/crds/crd-issuers.yaml +++ b/deploy/crds/crd-issuers.yaml @@ -84,11 +84,17 @@ spec: - server properties: email: - description: Email is the email for this account + description: Email is the email address to be associated with the + ACME account. This field is optional, but it is strongly recommended + to be set. It will be used to contact you in case of issues with + your account or certificates, including expiry notification emails. + This field may be updated after the account is initially registered. type: string externalAccountBinding: description: ExternalAccountBinding is a reference to a CA external - account of the ACME server. + account of the ACME server. If set, upon registration cert-manager + will attempt to associate the given external account credentials + with the registered ACME account. type: object required: - keyAlgorithm @@ -129,8 +135,10 @@ spec: info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names' type: string privateKeySecretRef: - description: PrivateKey is the name of a secret containing the private - key for this user account. + description: PrivateKey is the name of a Secret resource that will + be used to store the automatically generated ACME account private + key. If `key` is not specified, a default of `tls.key` will be + used. type: object required: - name @@ -144,24 +152,37 @@ spec: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names' type: string server: - description: Server is the ACME server URL + description: 'Server is the URL used to access the ACME server''s + ''directory'' endpoint. For examples, for Let''s Encrypt''s staging + endpoint, you would use: "https://acme-staging-v02.api.letsencrypt.org/directory". + Only ACME v2 endpoints (i.e. RFC 8555) are supported.' type: string skipTLSVerify: - description: If true, skip verifying the ACME server TLS certificate + description: If true, requests to the ACME server will not have + their TLS certificate validated (i.e. insecure connections will + be allowed). Only enable this option in development environments. + The cert-manager system installed roots will be used to verify + connections to the ACME server if this is false. Defaults to false. type: boolean solvers: - description: Solvers is a list of challenge solvers that will be - used to solve ACME challenges for the matching domains. + description: 'Solvers is a list of challenge solvers that will be + used to solve ACME challenges for the matching domains. Solver + configurations must be provided in order to obtain certificates + from an ACME server. For more information, see: https://cert-manager.io/docs/configuration/acme/' type: array items: + description: Configures an issuer to solve challenges using the + specified options. Only one of HTTP01 or DNS01 may be provided. type: object properties: dns01: + description: Configures cert-manager to attempt to complete + authorizations by performing the DNS01 challenge flow. type: object properties: acmedns: - description: ACMEIssuerDNS01ProviderAcmeDNS is a structure - containing the configuration for ACME-DNS servers + description: Use the 'ACME DNS' (https://github.com/joohoi/acme-dns) + API to manage DNS01 challenge records. type: object required: - accountSecretRef @@ -183,9 +204,8 @@ spec: host: type: string akamai: - description: ACMEIssuerDNS01ProviderAkamai is a structure - containing the DNS configuration for Akamai DNS—Zone - Record Management API + description: Use the Akamai DNS zone management API to + manage DNS01 challenge records. type: object required: - accessTokenSecretRef @@ -235,8 +255,8 @@ spec: serviceConsumerDomain: type: string azuredns: - description: ACMEIssuerDNS01ProviderAzureDNS is a structure - containing the configuration for Azure DNS + description: Use the Microsoft Azure DNS API to manage + DNS01 challenge records. type: object required: - resourceGroupName @@ -279,8 +299,8 @@ spec: then this field is also needed type: string clouddns: - description: ACMEIssuerDNS01ProviderCloudDNS is a structure - containing the DNS configuration for Google Cloud DNS + description: Use the Google Cloud DNS API to manage DNS01 + challenge records. type: object required: - project @@ -301,11 +321,15 @@ spec: to. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names' type: string cloudflare: - description: ACMEIssuerDNS01ProviderCloudflare is a structure - containing the DNS configuration for Cloudflare + description: Use the Cloudflare API to manage DNS01 challenge + records. type: object properties: apiKeySecretRef: + description: 'API key to use to authenticate with + Cloudflare. Note: using an API token to authenticate + is now the recommended method as it allows greater + control of permissions.' type: object required: - name @@ -319,6 +343,7 @@ spec: to. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names' type: string apiTokenSecretRef: + description: API token used to authenticate with Cloudflare. type: object required: - name @@ -332,6 +357,8 @@ spec: to. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names' type: string email: + description: Email of the account, only required when + using API key based authentication. type: string cnameStrategy: description: CNAMEStrategy configures how the DNS01 provider @@ -341,9 +368,8 @@ spec: - None - Follow digitalocean: - description: ACMEIssuerDNS01ProviderDigitalOcean is a - structure containing the DNS configuration for DigitalOcean - Domains + description: Use the DigitalOcean DNS API to manage DNS01 + challenge records. type: object required: - tokenSecretRef @@ -362,8 +388,9 @@ spec: to. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names' type: string rfc2136: - description: ACMEIssuerDNS01ProviderRFC2136 is a structure - containing the configuration for RFC2136 DNS + description: Use RFC2136 ("Dynamic Updates in the Domain + Name System") (https://datatracker.ietf.org/doc/rfc2136/) + to manage DNS01 challenge records. type: object required: - nameserver @@ -404,8 +431,8 @@ spec: to. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names' type: string route53: - description: ACMEIssuerDNS01ProviderRoute53 is a structure - containing the Route 53 configuration for AWS + description: Use the AWS Route53 API to manage DNS01 challenge + records. type: object required: - region @@ -448,9 +475,8 @@ spec: to. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names' type: string webhook: - description: ACMEIssuerDNS01ProviderWebhook specifies - configuration for a webhook DNS01 provider, including - where to POST ChallengePayload resources. + description: Configure an external webhook based DNS01 + challenge solver to manage DNS01 challenge records. type: object required: - groupName @@ -479,12 +505,11 @@ spec: typically be the name of the provider, e.g. 'cloudflare'. type: string http01: - description: ACMEChallengeSolverHTTP01 contains configuration - detailing how to solve HTTP01 challenges within a Kubernetes - cluster. Typically this is accomplished through creating - 'routes' of some description that configure ingress controllers - to direct traffic to 'solver pods', which are responsible - for responding to the ACME server's HTTP requests. + description: Configures cert-manager to attempt to complete + authorizations by performing the HTTP01 challenge flow. + It is not possible to obtain certificates for wildcard domain + names (e.g. `*.example.com`) using the HTTP01 challenge + mechanism. type: object properties: ingress: @@ -1501,6 +1526,9 @@ spec: selector: description: Selector selects a set of DNSNames on the Certificate resource that should be solved using this challenge solver. + If not specified, the solver will be treated as the 'default' + solver with the lowest priority, i.e. if any other solver + has a more specific match, it will be used instead. type: object properties: dnsNames: diff --git a/deploy/crds/crd-orders.yaml b/deploy/crds/crd-orders.yaml index 180fa2686..af1846be2 100644 --- a/deploy/crds/crd-orders.yaml +++ b/deploy/crds/crd-orders.yaml @@ -79,14 +79,13 @@ spec: type: object required: - csr + - dnsNames - issuerRef properties: commonName: description: CommonName is the common name as specified on the DER encoded - CSR. If CommonName is not specified, the first DNSName specified will - be used as the CommonName. At least one of CommonName or a DNSNames - must be set. This field must match the corresponding field on the - DER encoded CSR. + CSR. If specified, this value must also be present in `dnsNames`. + This field must match the corresponding field on the DER encoded CSR. type: string csr: description: Certificate signing request bytes in DER encoding. This @@ -96,10 +95,8 @@ spec: format: byte dnsNames: description: DNSNames is a list of DNS names that should be included - as part of the Order validation process. If CommonName is not specified, - the first DNSName specified will be used as the CommonName. At least - one of CommonName or a DNSNames must be set. This field must match - the corresponding field on the DER encoded CSR. + as part of the Order validation process. This field must match the + corresponding field on the DER encoded CSR. type: array items: type: string From 8f0b81490d124e5919988a28cb9cb22a81eb5423 Mon Sep 17 00:00:00 2001 From: James Munnelly Date: Fri, 26 Jun 2020 10:21:17 +0100 Subject: [PATCH 08/12] address review feedback Signed-off-by: James Munnelly --- pkg/apis/certmanager/v1alpha2/types.go | 22 +++++++++---------- .../certmanager/v1alpha2/types_certificate.go | 12 +++++----- .../v1alpha2/types_certificaterequest.go | 7 +++--- pkg/apis/certmanager/v1alpha2/types_issuer.go | 16 +++++++------- pkg/apis/certmanager/v1alpha3/types.go | 21 +++++++++--------- .../certmanager/v1alpha3/types_certificate.go | 10 ++++----- .../v1alpha3/types_certificaterequest.go | 7 +++--- pkg/apis/certmanager/v1alpha3/types_issuer.go | 16 +++++++------- pkg/apis/meta/v1/types.go | 10 +++++++++ pkg/internal/apis/certmanager/types.go | 21 +++++++++--------- .../apis/certmanager/types_certificate.go | 10 ++++----- .../certmanager/types_certificaterequest.go | 7 +++--- pkg/internal/apis/certmanager/types_issuer.go | 16 +++++++------- pkg/internal/apis/meta/types.go | 10 +++++++++ 14 files changed, 105 insertions(+), 80 deletions(-) diff --git a/pkg/apis/certmanager/v1alpha2/types.go b/pkg/apis/certmanager/v1alpha2/types.go index 91459d51a..37a585f76 100644 --- a/pkg/apis/certmanager/v1alpha2/types.go +++ b/pkg/apis/certmanager/v1alpha2/types.go @@ -16,34 +16,34 @@ limitations under the License. package v1alpha2 -// Common annotation keys added to resources +// Common annotation keys added to resources. const ( - // Annotation key for DNS subjectAltNames + // Annotation key for DNS subjectAltNames. AltNamesAnnotationKey = "cert-manager.io/alt-names" - // Annotation key for IP subjectAltNames + // Annotation key for IP subjectAltNames. IPSANAnnotationKey = "cert-manager.io/ip-sans" - // Annotation key for URI subjectAltNames + // Annotation key for URI subjectAltNames. URISANAnnotationKey = "cert-manager.io/uri-sans" - // Annotation key for certificate common name + // Annotation key for certificate common name. CommonNameAnnotationKey = "cert-manager.io/common-name" - // Annotation key the 'name' of the Issuer resource + // Annotation key the 'name' of the Issuer resource. IssuerNameAnnotationKey = "cert-manager.io/issuer-name" - // Annotation key the 'kind' of the Issuer resource + // Annotation key for the 'kind' of the Issuer resource. IssuerKindAnnotationKey = "cert-manager.io/issuer-kind" - // Annotation key the 'group' of the Issuer resource + // Annotation key for the 'group' of the Issuer resource. IssuerGroupAnnotationKey = "cert-manager.io/issuer-group" - // Annotation key the name of the certificate that a resource is related to + // Annotation key for the name of the certificate that a resource is related to. CertificateNameKey = "cert-manager.io/certificate-name" // Annotation key used to denote whether a Secret is named on a Certificate - // as a 'next private key' Secret resource + // as a 'next private key' Secret resource. IsNextPrivateKeySecretLabelKey = "cert-manager.io/next-private-key" ) @@ -94,7 +94,7 @@ const ( IssueTemporaryCertificateAnnotation = "cert-manager.io/issue-temporary-certificate" ) -// Common/known resource kinds +// Common/known resource kinds. const ( ClusterIssuerKind = "ClusterIssuer" IssuerKind = "Issuer" diff --git a/pkg/apis/certmanager/v1alpha2/types_certificate.go b/pkg/apis/certmanager/v1alpha2/types_certificate.go index a35d5115d..08f69d43b 100644 --- a/pkg/apis/certmanager/v1alpha2/types_certificate.go +++ b/pkg/apis/certmanager/v1alpha2/types_certificate.go @@ -41,7 +41,7 @@ type Certificate struct { // Desired state of the Certificate resource. Spec CertificateSpec `json:"spec,omitempty"` - // Status of the Certificate, set and managed automatically. + // Status of the Certificate. This is set and managed automatically. Status CertificateStatus `json:"status,omitempty"` } @@ -59,10 +59,10 @@ type CertificateList struct { type KeyAlgorithm string const ( - // Denotes the RSA private key type + // Denotes the RSA private key type. RSAKeyAlgorithm KeyAlgorithm = "rsa" - // Denotes the ECDSA private key type + // Denotes the ECDSA private key type. ECDSAKeyAlgorithm KeyAlgorithm = "ecdsa" ) @@ -96,7 +96,7 @@ type CertificateSpec struct { // +optional CommonName string `json:"commonName,omitempty"` - // Organization is the organization to be used on the Certificate. + // Organization is a list of organizations to be used on the Certificate. // +optional Organization []string `json:"organization,omitempty"` @@ -301,8 +301,8 @@ type CertificateStatus struct { Conditions []CertificateCondition `json:"conditions,omitempty"` // LastFailureTime is the time as recorded by the Certificate controller - // of the most recently failure to complete a CertificateRequest for this - // certificate resource. + // of the most recent failure to complete a CertificateRequest for this + // Certificate resource. // If set, cert-manager will not re-request another Certificate until // 1 hour has elapsed from this time. // +optional diff --git a/pkg/apis/certmanager/v1alpha2/types_certificaterequest.go b/pkg/apis/certmanager/v1alpha2/types_certificaterequest.go index 460454536..88c56c9a4 100644 --- a/pkg/apis/certmanager/v1alpha2/types_certificaterequest.go +++ b/pkg/apis/certmanager/v1alpha2/types_certificaterequest.go @@ -53,7 +53,7 @@ type CertificateRequest struct { // Desired state of the CertificateRequest resource. Spec CertificateRequestSpec `json:"spec,omitempty"` - // Status of the CertificateRequest, set and managed automatically. + // Status of the CertificateRequest. This is set and managed automatically. Status CertificateRequestStatus `json:"status,omitempty"` } @@ -83,7 +83,8 @@ type CertificateRequestSpec struct { // issuer which defaults to 'cert-manager.io' if empty. IssuerRef cmmeta.ObjectReference `json:"issuerRef"` - // Byte slice containing the PEM encoded CertificateSigningRequest + // The PEM-encoded x509 certificate signing request to be submitted to the + // CA for signing. CSRPEM []byte `json:"csr"` // IsCA will request to mark the certificate as valid for certificate signing @@ -98,7 +99,7 @@ type CertificateRequestSpec struct { Usages []KeyUsage `json:"usages,omitempty"` } -// CertificateStatus defines the observed state of CertificateRequest and +// CertificateRequestStatus defines the observed state of CertificateRequest and // resulting signed certificate. type CertificateRequestStatus struct { // List of status conditions to indicate the status of a CertificateRequest. diff --git a/pkg/apis/certmanager/v1alpha2/types_issuer.go b/pkg/apis/certmanager/v1alpha2/types_issuer.go index 052843f21..8549da8d0 100644 --- a/pkg/apis/certmanager/v1alpha2/types_issuer.go +++ b/pkg/apis/certmanager/v1alpha2/types_issuer.go @@ -42,7 +42,7 @@ type ClusterIssuer struct { // Desired state of the ClusterIssuer resource. Spec IssuerSpec `json:"spec,omitempty"` - // Status of the ClusterIssuer, set and managed automatically. + // Status of the ClusterIssuer. This is set and managed automatically. Status IssuerStatus `json:"status,omitempty"` } @@ -76,7 +76,7 @@ type Issuer struct { // Desired state of the Issuer resource. Spec IssuerSpec `json:"spec,omitempty"` - // Status of the Issuer, set and managed automatically. + // Status of the Issuer. This is set and managed automatically. Status IssuerStatus `json:"status,omitempty"` } @@ -119,12 +119,12 @@ type IssuerConfig struct { SelfSigned *SelfSignedIssuer `json:"selfSigned,omitempty"` // Venafi configures this issuer to sign certificates using a Venafi TPP - // or Cloud policy zone. + // or Venafi Cloud policy zone. // +optional Venafi *VenafiIssuer `json:"venafi,omitempty"` } -// Venafi configures this issuer to sign certificates using a Venafi TPP +// Configures an issuer to sign certificates using a Venafi TPP // or Cloud policy zone. type VenafiIssuer struct { // Zone is the Venafi Policy Zone to use for this issuer. @@ -176,7 +176,7 @@ type VenafiCloud struct { APITokenSecretRef cmmeta.SecretKeySelector `json:"apiTokenSecretRef"` } -// SelfSigned configures this issuer to 'self sign' certificates using the +// Configures an issuer to 'self sign' certificates using the // private key used to create the CertificateRequest object. type SelfSignedIssuer struct { // The CRL distribution points is an X.509 v3 certificate extension which identifies @@ -186,7 +186,7 @@ type SelfSignedIssuer struct { CRLDistributionPoints []string `json:"crlDistributionPoints,omitempty"` } -// Vault configures this issuer to sign certificates using a HashiCorp Vault +// Configures an issuer to sign certificates using a HashiCorp Vault // PKI backend. type VaultIssuer struct { // Auth configures how cert-manager authenticates with the Vault server. @@ -232,8 +232,8 @@ type VaultAppRole struct { // "approle" Path string `json:"path"` - // RoleID configures in the App Role authentication backend when setting - // up the App Role backend. + // RoleID configured in the App Role authentication backend when setting + // up the authentication backend in Vault. RoleId string `json:"roleId"` // Reference to a key in a Secret that contains the App Role secret used diff --git a/pkg/apis/certmanager/v1alpha3/types.go b/pkg/apis/certmanager/v1alpha3/types.go index 0e51e2cf6..c578027c1 100644 --- a/pkg/apis/certmanager/v1alpha3/types.go +++ b/pkg/apis/certmanager/v1alpha3/types.go @@ -16,34 +16,34 @@ limitations under the License. package v1alpha3 -// Common annotation keys added to resources +// Common annotation keys added to resources. const ( - // Annotation key for DNS subjectAltNames + // Annotation key for DNS subjectAltNames. AltNamesAnnotationKey = "cert-manager.io/alt-names" - // Annotation key for IP subjectAltNames + // Annotation key for IP subjectAltNames. IPSANAnnotationKey = "cert-manager.io/ip-sans" - // Annotation key for URI subjectAltNames + // Annotation key for URI subjectAltNames. URISANAnnotationKey = "cert-manager.io/uri-sans" - // Annotation key for certificate common name + // Annotation key for certificate common name. CommonNameAnnotationKey = "cert-manager.io/common-name" - // Annotation key the 'name' of the Issuer resource + // Annotation key the 'name' of the Issuer resource. IssuerNameAnnotationKey = "cert-manager.io/issuer-name" - // Annotation key the 'kind' of the Issuer resource + // Annotation key for the 'kind' of the Issuer resource. IssuerKindAnnotationKey = "cert-manager.io/issuer-kind" - // Annotation key the 'group' of the Issuer resource + // Annotation key for the 'group' of the Issuer resource. IssuerGroupAnnotationKey = "cert-manager.io/issuer-group" - // Annotation key the name of the certificate that a resource is related to + // Annotation key for the name of the certificate that a resource is related to. CertificateNameKey = "cert-manager.io/certificate-name" // Annotation key used to denote whether a Secret is named on a Certificate - // as a 'next private key' Secret resource + // as a 'next private key' Secret resource. IsNextPrivateKeySecretLabelKey = "cert-manager.io/next-private-key" ) @@ -88,6 +88,7 @@ const ( IssueTemporaryCertificateAnnotation = "cert-manager.io/issue-temporary-certificate" ) +// Common/known resource kinds. const ( ClusterIssuerKind = "ClusterIssuer" IssuerKind = "Issuer" diff --git a/pkg/apis/certmanager/v1alpha3/types_certificate.go b/pkg/apis/certmanager/v1alpha3/types_certificate.go index abb9d3f14..e6e88a67f 100644 --- a/pkg/apis/certmanager/v1alpha3/types_certificate.go +++ b/pkg/apis/certmanager/v1alpha3/types_certificate.go @@ -41,7 +41,7 @@ type Certificate struct { // Desired state of the Certificate resource. Spec CertificateSpec `json:"spec,omitempty"` - // Status of the Certificate, set and managed automatically. + // Status of the Certificate. This is set and managed automatically. Status CertificateStatus `json:"status,omitempty"` } @@ -59,10 +59,10 @@ type CertificateList struct { type KeyAlgorithm string const ( - // Denotes the RSA private key type + // Denotes the RSA private key type. RSAKeyAlgorithm KeyAlgorithm = "rsa" - // Denotes the ECDSA private key type + // Denotes the ECDSA private key type. ECDSAKeyAlgorithm KeyAlgorithm = "ecdsa" ) @@ -302,8 +302,8 @@ type CertificateStatus struct { Conditions []CertificateCondition `json:"conditions,omitempty"` // LastFailureTime is the time as recorded by the Certificate controller - // of the most recently failure to complete a CertificateRequest for this - // certificate resource. + // of the most recent failure to complete a CertificateRequest for this + // Certificate resource. // If set, cert-manager will not re-request another Certificate until // 1 hour has elapsed from this time. // +optional diff --git a/pkg/apis/certmanager/v1alpha3/types_certificaterequest.go b/pkg/apis/certmanager/v1alpha3/types_certificaterequest.go index 7b6fcc2e6..e728aed8a 100644 --- a/pkg/apis/certmanager/v1alpha3/types_certificaterequest.go +++ b/pkg/apis/certmanager/v1alpha3/types_certificaterequest.go @@ -53,7 +53,7 @@ type CertificateRequest struct { // Desired state of the CertificateRequest resource. Spec CertificateRequestSpec `json:"spec,omitempty"` - // Status of the CertificateRequest, set and managed automatically. + // Status of the CertificateRequest. This is set and managed automatically. Status CertificateRequestStatus `json:"status,omitempty"` } @@ -83,7 +83,8 @@ type CertificateRequestSpec struct { // issuer which defaults to 'cert-manager.io' if empty. IssuerRef cmmeta.ObjectReference `json:"issuerRef"` - // Byte slice containing the PEM encoded CertificateSigningRequest + // The PEM-encoded x509 certificate signing request to be submitted to the + // CA for signing. CSRPEM []byte `json:"csr"` // IsCA will request to mark the certificate as valid for certificate signing @@ -98,7 +99,7 @@ type CertificateRequestSpec struct { Usages []KeyUsage `json:"usages,omitempty"` } -// CertificateStatus defines the observed state of CertificateRequest and +// CertificateRequestStatus defines the observed state of CertificateRequest and // resulting signed certificate. type CertificateRequestStatus struct { // List of status conditions to indicate the status of a CertificateRequest. diff --git a/pkg/apis/certmanager/v1alpha3/types_issuer.go b/pkg/apis/certmanager/v1alpha3/types_issuer.go index 19a9f8e25..d7040b931 100644 --- a/pkg/apis/certmanager/v1alpha3/types_issuer.go +++ b/pkg/apis/certmanager/v1alpha3/types_issuer.go @@ -42,7 +42,7 @@ type ClusterIssuer struct { // Desired state of the ClusterIssuer resource. Spec IssuerSpec `json:"spec,omitempty"` - // Status of the ClusterIssuer, set and managed automatically. + // Status of the ClusterIssuer. This is set and managed automatically. Status IssuerStatus `json:"status,omitempty"` } @@ -76,7 +76,7 @@ type Issuer struct { // Desired state of the Issuer resource. Spec IssuerSpec `json:"spec,omitempty"` - // Status of the Issuer, set and managed automatically. + // Status of the Issuer. This is set and managed automatically. Status IssuerStatus `json:"status,omitempty"` } @@ -119,12 +119,12 @@ type IssuerConfig struct { SelfSigned *SelfSignedIssuer `json:"selfSigned,omitempty"` // Venafi configures this issuer to sign certificates using a Venafi TPP - // or Cloud policy zone. + // or Venafi Cloud policy zone. // +optional Venafi *VenafiIssuer `json:"venafi,omitempty"` } -// Venafi configures this issuer to sign certificates using a Venafi TPP +// Configures an issuer to sign certificates using a Venafi TPP // or Cloud policy zone. type VenafiIssuer struct { // Zone is the Venafi Policy Zone to use for this issuer. @@ -176,7 +176,7 @@ type VenafiCloud struct { APITokenSecretRef cmmeta.SecretKeySelector `json:"apiTokenSecretRef"` } -// SelfSigned configures this issuer to 'self sign' certificates using the +// Configures an issuer to 'self sign' certificates using the // private key used to create the CertificateRequest object. type SelfSignedIssuer struct { // The CRL distribution points is an X.509 v3 certificate extension which identifies @@ -186,7 +186,7 @@ type SelfSignedIssuer struct { CRLDistributionPoints []string `json:"crlDistributionPoints,omitempty"` } -// Vault configures this issuer to sign certificates using a HashiCorp Vault +// Configures an issuer to sign certificates using a HashiCorp Vault // PKI backend. type VaultIssuer struct { // Auth configures how cert-manager authenticates with the Vault server. @@ -232,8 +232,8 @@ type VaultAppRole struct { // "approle" Path string `json:"path"` - // RoleID configures in the App Role authentication backend when setting - // up the App Role backend. + // RoleID configured in the App Role authentication backend when setting + // up the authentication backend in Vault. RoleId string `json:"roleId"` // Reference to a key in a Secret that contains the App Role secret used diff --git a/pkg/apis/meta/v1/types.go b/pkg/apis/meta/v1/types.go index 7954b327e..a0aa406d3 100644 --- a/pkg/apis/meta/v1/types.go +++ b/pkg/apis/meta/v1/types.go @@ -36,6 +36,12 @@ const ( ConditionUnknown ConditionStatus = "Unknown" ) +// A reference to an object in the same namespace as the referent. +// If the referent is a cluster-scoped resource (e.g. a ClusterIssuer), +// the reference instead refers to the resource with the given name in the +// configured 'cluster resource namespace', which is set as a flag on the +// controller component (and defaults to the namespace that cert-manager +// runs in). type LocalObjectReference struct { // Name of the resource being referred to. // More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names @@ -54,11 +60,15 @@ type ObjectReference struct { Group string `json:"group,omitempty"` } +// A reference to a specific 'key' within a Secret resource. +// In some instances, `key` is a required field. type SecretKeySelector struct { // The name of the Secret resource being referred to. LocalObjectReference `json:",inline"` // The key of the entry in the Secret resource's `data` field to be used. + // Some instances of this field may be defaulted, in others it may be + // required. // +optional Key string `json:"key,omitempty"` } diff --git a/pkg/internal/apis/certmanager/types.go b/pkg/internal/apis/certmanager/types.go index 206d35ab8..76e577b8b 100644 --- a/pkg/internal/apis/certmanager/types.go +++ b/pkg/internal/apis/certmanager/types.go @@ -16,34 +16,34 @@ limitations under the License. package certmanager -// Common annotation keys added to resources +// Common annotation keys added to resources. const ( - // Annotation key for DNS subjectAltNames + // Annotation key for DNS subjectAltNames. AltNamesAnnotationKey = "cert-manager.io/alt-names" - // Annotation key for IP subjectAltNames + // Annotation key for IP subjectAltNames. IPSANAnnotationKey = "cert-manager.io/ip-sans" - // Annotation key for URI subjectAltNames + // Annotation key for URI subjectAltNames. URISANAnnotationKey = "cert-manager.io/uri-sans" - // Annotation key for certificate common name + // Annotation key for certificate common name. CommonNameAnnotationKey = "cert-manager.io/common-name" - // Annotation key the 'name' of the Issuer resource + // Annotation key the 'name' of the Issuer resource. IssuerNameAnnotationKey = "cert-manager.io/issuer-name" - // Annotation key the 'kind' of the Issuer resource + // Annotation key for the 'kind' of the Issuer resource. IssuerKindAnnotationKey = "cert-manager.io/issuer-kind" - // Annotation key the 'group' of the Issuer resource + // Annotation key for the 'group' of the Issuer resource. IssuerGroupAnnotationKey = "cert-manager.io/issuer-group" - // Annotation key the name of the certificate that a resource is related to + // Annotation key for the name of the certificate that a resource is related to. CertificateNameKey = "cert-manager.io/certificate-name" // Annotation key used to denote whether a Secret is named on a Certificate - // as a 'next private key' Secret resource + // as a 'next private key' Secret resource. IsNextPrivateKeySecretLabelKey = "cert-manager.io/next-private-key" ) @@ -88,6 +88,7 @@ const ( IssueTemporaryCertificateAnnotation = "cert-manager.io/issue-temporary-certificate" ) +// Common/known resource kinds. const ( ClusterIssuerKind = "ClusterIssuer" IssuerKind = "Issuer" diff --git a/pkg/internal/apis/certmanager/types_certificate.go b/pkg/internal/apis/certmanager/types_certificate.go index 64008abb9..e6aed0f93 100644 --- a/pkg/internal/apis/certmanager/types_certificate.go +++ b/pkg/internal/apis/certmanager/types_certificate.go @@ -32,7 +32,7 @@ type Certificate struct { // Desired state of the Certificate resource. Spec CertificateSpec - // Status of the Certificate, set and managed automatically. + // Status of the Certificate. This is set and managed automatically. Status CertificateStatus } @@ -49,10 +49,10 @@ type CertificateList struct { type KeyAlgorithm string const ( - // Denotes the RSA private key type + // Denotes the RSA private key type. RSAKeyAlgorithm KeyAlgorithm = "rsa" - // Denotes the ECDSA private key type + // Denotes the ECDSA private key type. ECDSAKeyAlgorithm KeyAlgorithm = "ecdsa" ) @@ -263,8 +263,8 @@ type CertificateStatus struct { Conditions []CertificateCondition // LastFailureTime is the time as recorded by the Certificate controller - // of the most recently failure to complete a CertificateRequest for this - // certificate resource. + // of the most recent failure to complete a CertificateRequest for this + // Certificate resource. // If set, cert-manager will not re-request another Certificate until // 1 hour has elapsed from this time. LastFailureTime *metav1.Time diff --git a/pkg/internal/apis/certmanager/types_certificaterequest.go b/pkg/internal/apis/certmanager/types_certificaterequest.go index 89865e02f..950d68182 100644 --- a/pkg/internal/apis/certmanager/types_certificaterequest.go +++ b/pkg/internal/apis/certmanager/types_certificaterequest.go @@ -45,7 +45,7 @@ type CertificateRequest struct { // Desired state of the CertificateRequest resource. Spec CertificateRequestSpec - // Status of the CertificateRequest, set and managed automatically. + // Status of the CertificateRequest. This is set and managed automatically. Status CertificateRequestStatus } @@ -74,7 +74,8 @@ type CertificateRequestSpec struct { // issuer which defaults to 'cert-manager.io' if empty. IssuerRef cmmeta.ObjectReference - // Byte slice containing the PEM encoded CertificateSigningRequest + // The PEM-encoded x509 certificate signing request to be submitted to the + // CA for signing. CSRPEM []byte // IsCA will request to mark the certificate as valid for certificate signing @@ -87,7 +88,7 @@ type CertificateRequestSpec struct { Usages []KeyUsage } -// CertificateStatus defines the observed state of CertificateRequest and +// CertificateRequestStatus defines the observed state of CertificateRequest and // resulting signed certificate. type CertificateRequestStatus struct { // List of status conditions to indicate the status of a CertificateRequest. diff --git a/pkg/internal/apis/certmanager/types_issuer.go b/pkg/internal/apis/certmanager/types_issuer.go index a8234d244..45ca892dc 100644 --- a/pkg/internal/apis/certmanager/types_issuer.go +++ b/pkg/internal/apis/certmanager/types_issuer.go @@ -37,7 +37,7 @@ type ClusterIssuer struct { // Desired state of the ClusterIssuer resource. Spec IssuerSpec - // Status of the ClusterIssuer, set and managed automatically. + // Status of the ClusterIssuer. This is set and managed automatically. Status IssuerStatus } @@ -64,7 +64,7 @@ type Issuer struct { // Desired state of the Issuer resource. Spec IssuerSpec - // Status of the Issuer, set and managed automatically. + // Status of the Issuer. This is set and managed automatically. Status IssuerStatus } @@ -103,11 +103,11 @@ type IssuerConfig struct { SelfSigned *SelfSignedIssuer // Venafi configures this issuer to sign certificates using a Venafi TPP - // or Cloud policy zone. + // or Venafi Cloud policy zone. Venafi *VenafiIssuer } -// Venafi configures this issuer to sign certificates using a Venafi TPP +// Configures an issuer to sign certificates using a Venafi TPP // or Cloud policy zone. type VenafiIssuer struct { // Zone is the Venafi Policy Zone to use for this issuer. @@ -155,7 +155,7 @@ type VenafiCloud struct { APITokenSecretRef cmmeta.SecretKeySelector } -// SelfSigned configures this issuer to 'self sign' certificates using the +// Configures an issuer to 'self sign' certificates using the // private key used to create the CertificateRequest object. type SelfSignedIssuer struct { // The CRL distribution points is an X.509 v3 certificate extension which identifies @@ -164,7 +164,7 @@ type SelfSignedIssuer struct { CRLDistributionPoints []string } -// Vault configures this issuer to sign certificates using a HashiCorp Vault +// Configures an issuer to sign certificates using a HashiCorp Vault // PKI backend. type VaultIssuer struct { // Auth configures how cert-manager authenticates with the Vault server. @@ -206,8 +206,8 @@ type VaultAppRole struct { // "approle" Path string - // RoleID configures in the App Role authentication backend when setting - // up the App Role backend. + // RoleID configured in the App Role authentication backend when setting + // up the authentication backend in Vault. RoleId string // Reference to a key in a Secret that contains the App Role secret used diff --git a/pkg/internal/apis/meta/types.go b/pkg/internal/apis/meta/types.go index 791d92208..869301994 100644 --- a/pkg/internal/apis/meta/types.go +++ b/pkg/internal/apis/meta/types.go @@ -35,6 +35,12 @@ const ( ConditionUnknown ConditionStatus = "Unknown" ) +// A reference to an object in the same namespace as the referent. +// If the referent is a cluster-scoped resource (e.g. a ClusterIssuer), +// the reference instead refers to the resource with the given name in the +// configured 'cluster resource namespace', which is set as a flag on the +// controller component (and defaults to the namespace that cert-manager +// runs in). type LocalObjectReference struct { // Name of the resource being referred to. // More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names @@ -51,11 +57,15 @@ type ObjectReference struct { Group string } +// A reference to a specific 'key' within a Secret resource. +// In some instances, `key` is a required field. type SecretKeySelector struct { // The name of the Secret resource being referred to. LocalObjectReference // The key of the entry in the Secret resource's `data` field to be used. + // Some instances of this field may be defaulted, in others it may be + // required. Key string } From d01d921a71b191675fca211d84e18ec29d78c12b Mon Sep 17 00:00:00 2001 From: James Munnelly Date: Fri, 26 Jun 2020 10:26:01 +0100 Subject: [PATCH 09/12] generated files Signed-off-by: James Munnelly --- deploy/crds/crd-certificaterequests.yaml | 5 +- deploy/crds/crd-certificates.yaml | 27 ++++--- deploy/crds/crd-challenges.yaml | 45 +++++++++--- deploy/crds/crd-clusterissuers.yaml | 89 ++++++++++++++++++------ deploy/crds/crd-issuers.yaml | 89 ++++++++++++++++++------ pkg/internal/apis/acme/types_issuer.go | 1 - 6 files changed, 189 insertions(+), 67 deletions(-) diff --git a/deploy/crds/crd-certificaterequests.yaml b/deploy/crds/crd-certificaterequests.yaml index b6b1f04e9..ef793b1b9 100644 --- a/deploy/crds/crd-certificaterequests.yaml +++ b/deploy/crds/crd-certificaterequests.yaml @@ -85,7 +85,8 @@ spec: - issuerRef properties: csr: - description: Byte slice containing the PEM encoded CertificateSigningRequest + description: The PEM-encoded x509 certificate signing request to be + submitted to the CA for signing. type: string format: byte duration: @@ -159,7 +160,7 @@ spec: - microsoft sgc - netscape sgc status: - description: Status of the CertificateRequest, set and managed automatically. + description: Status of the CertificateRequest. This is set and managed automatically. type: object properties: ca: diff --git a/deploy/crds/crd-certificates.yaml b/deploy/crds/crd-certificates.yaml index b8b0d9c00..575e997b9 100644 --- a/deploy/crds/crd-certificates.yaml +++ b/deploy/crds/crd-certificates.yaml @@ -199,7 +199,8 @@ spec: properties: key: description: The key of the entry in the Secret resource's - `data` field to be used. + `data` field to be used. Some instances of this field + may be defaulted, in others it may be required. type: string name: description: 'Name of the resource being referred to. @@ -230,14 +231,16 @@ spec: properties: key: description: The key of the entry in the Secret resource's - `data` field to be used. + `data` field to be used. Some instances of this field + may be defaulted, in others it may be required. type: string name: description: 'Name of the resource being referred to. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names' type: string organization: - description: Organization is the organization to be used on the Certificate. + description: Organization is a list of organizations to be used on + the Certificate. type: array items: type: string @@ -353,7 +356,7 @@ spec: - microsoft sgc - netscape sgc status: - description: Status of the Certificate, set and managed automatically. + description: Status of the Certificate. This is set and managed automatically. type: object properties: conditions: @@ -395,8 +398,8 @@ spec: type: string lastFailureTime: description: LastFailureTime is the time as recorded by the Certificate - controller of the most recently failure to complete a CertificateRequest - for this certificate resource. If set, cert-manager will not re-request + controller of the most recent failure to complete a CertificateRequest + for this Certificate resource. If set, cert-manager will not re-request another Certificate until 1 hour has elapsed from this time. type: string format: date-time @@ -577,7 +580,8 @@ spec: properties: key: description: The key of the entry in the Secret resource's - `data` field to be used. + `data` field to be used. Some instances of this field + may be defaulted, in others it may be required. type: string name: description: 'Name of the resource being referred to. @@ -608,7 +612,8 @@ spec: properties: key: description: The key of the entry in the Secret resource's - `data` field to be used. + `data` field to be used. Some instances of this field + may be defaulted, in others it may be required. type: string name: description: 'Name of the resource being referred to. @@ -731,7 +736,7 @@ spec: - microsoft sgc - netscape sgc status: - description: Status of the Certificate, set and managed automatically. + description: Status of the Certificate. This is set and managed automatically. type: object properties: conditions: @@ -773,8 +778,8 @@ spec: type: string lastFailureTime: description: LastFailureTime is the time as recorded by the Certificate - controller of the most recently failure to complete a CertificateRequest - for this certificate resource. If set, cert-manager will not re-request + controller of the most recent failure to complete a CertificateRequest + for this Certificate resource. If set, cert-manager will not re-request another Certificate until 1 hour has elapsed from this time. type: string format: date-time diff --git a/deploy/crds/crd-challenges.yaml b/deploy/crds/crd-challenges.yaml index 23a7b0072..4cb0915b4 100644 --- a/deploy/crds/crd-challenges.yaml +++ b/deploy/crds/crd-challenges.yaml @@ -144,13 +144,16 @@ spec: - host properties: accountSecretRef: + description: A reference to a specific 'key' within a Secret + resource. In some instances, `key` is a required field. type: object required: - name properties: key: description: The key of the entry in the Secret resource's - `data` field to be used. + `data` field to be used. Some instances of this field + may be defaulted, in others it may be required. type: string name: description: 'Name of the resource being referred to. @@ -169,39 +172,48 @@ spec: - serviceConsumerDomain properties: accessTokenSecretRef: + description: A reference to a specific 'key' within a Secret + resource. In some instances, `key` is a required field. type: object required: - name properties: key: description: The key of the entry in the Secret resource's - `data` field to be used. + `data` field to be used. Some instances of this field + may be defaulted, in others it may be required. type: string name: description: 'Name of the resource being referred to. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names' type: string clientSecretSecretRef: + description: A reference to a specific 'key' within a Secret + resource. In some instances, `key` is a required field. type: object required: - name properties: key: description: The key of the entry in the Secret resource's - `data` field to be used. + `data` field to be used. Some instances of this field + may be defaulted, in others it may be required. type: string name: description: 'Name of the resource being referred to. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names' type: string clientTokenSecretRef: + description: A reference to a specific 'key' within a Secret + resource. In some instances, `key` is a required field. type: object required: - name properties: key: description: The key of the entry in the Secret resource's - `data` field to be used. + `data` field to be used. Some instances of this field + may be defaulted, in others it may be required. type: string name: description: 'Name of the resource being referred to. @@ -230,7 +242,8 @@ spec: properties: key: description: The key of the entry in the Secret resource's - `data` field to be used. + `data` field to be used. Some instances of this field + may be defaulted, in others it may be required. type: string name: description: 'Name of the resource being referred to. @@ -263,13 +276,16 @@ spec: project: type: string serviceAccountSecretRef: + description: A reference to a specific 'key' within a Secret + resource. In some instances, `key` is a required field. type: object required: - name properties: key: description: The key of the entry in the Secret resource's - `data` field to be used. + `data` field to be used. Some instances of this field + may be defaulted, in others it may be required. type: string name: description: 'Name of the resource being referred to. @@ -290,7 +306,8 @@ spec: properties: key: description: The key of the entry in the Secret resource's - `data` field to be used. + `data` field to be used. Some instances of this field + may be defaulted, in others it may be required. type: string name: description: 'Name of the resource being referred to. @@ -304,7 +321,8 @@ spec: properties: key: description: The key of the entry in the Secret resource's - `data` field to be used. + `data` field to be used. Some instances of this field + may be defaulted, in others it may be required. type: string name: description: 'Name of the resource being referred to. @@ -329,13 +347,16 @@ spec: - tokenSecretRef properties: tokenSecretRef: + description: A reference to a specific 'key' within a Secret + resource. In some instances, `key` is a required field. type: object required: - name properties: key: description: The key of the entry in the Secret resource's - `data` field to be used. + `data` field to be used. Some instances of this field + may be defaulted, in others it may be required. type: string name: description: 'Name of the resource being referred to. @@ -376,7 +397,8 @@ spec: properties: key: description: The key of the entry in the Secret resource's - `data` field to be used. + `data` field to be used. Some instances of this field + may be defaulted, in others it may be required. type: string name: description: 'Name of the resource being referred to. @@ -419,7 +441,8 @@ spec: properties: key: description: The key of the entry in the Secret resource's - `data` field to be used. + `data` field to be used. Some instances of this field + may be defaulted, in others it may be required. type: string name: description: 'Name of the resource being referred to. diff --git a/deploy/crds/crd-clusterissuers.yaml b/deploy/crds/crd-clusterissuers.yaml index f604ae404..60bdf095f 100644 --- a/deploy/crds/crd-clusterissuers.yaml +++ b/deploy/crds/crd-clusterissuers.yaml @@ -129,7 +129,8 @@ spec: properties: key: description: The key of the entry in the Secret resource's - `data` field to be used. + `data` field to be used. Some instances of this field + may be defaulted, in others it may be required. type: string name: description: 'Name of the resource being referred to. More @@ -146,7 +147,8 @@ spec: properties: key: description: The key of the entry in the Secret resource's `data` - field to be used. + field to be used. Some instances of this field may be defaulted, + in others it may be required. type: string name: description: 'Name of the resource being referred to. More info: @@ -190,13 +192,18 @@ spec: - host properties: accountSecretRef: + description: A reference to a specific 'key' within + a Secret resource. In some instances, `key` is a + required field. type: object required: - name properties: key: description: The key of the entry in the Secret - resource's `data` field to be used. + resource's `data` field to be used. Some instances + of this field may be defaulted, in others it + may be required. type: string name: description: 'Name of the resource being referred @@ -215,39 +222,54 @@ spec: - serviceConsumerDomain properties: accessTokenSecretRef: + description: A reference to a specific 'key' within + a Secret resource. In some instances, `key` is a + required field. type: object required: - name properties: key: description: The key of the entry in the Secret - resource's `data` field to be used. + resource's `data` field to be used. Some instances + of this field may be defaulted, in others it + may be required. type: string name: description: 'Name of the resource being referred to. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names' type: string clientSecretSecretRef: + description: A reference to a specific 'key' within + a Secret resource. In some instances, `key` is a + required field. type: object required: - name properties: key: description: The key of the entry in the Secret - resource's `data` field to be used. + resource's `data` field to be used. Some instances + of this field may be defaulted, in others it + may be required. type: string name: description: 'Name of the resource being referred to. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names' type: string clientTokenSecretRef: + description: A reference to a specific 'key' within + a Secret resource. In some instances, `key` is a + required field. type: object required: - name properties: key: description: The key of the entry in the Secret - resource's `data` field to be used. + resource's `data` field to be used. Some instances + of this field may be defaulted, in others it + may be required. type: string name: description: 'Name of the resource being referred @@ -276,7 +298,9 @@ spec: properties: key: description: The key of the entry in the Secret - resource's `data` field to be used. + resource's `data` field to be used. Some instances + of this field may be defaulted, in others it + may be required. type: string name: description: 'Name of the resource being referred @@ -309,13 +333,18 @@ spec: project: type: string serviceAccountSecretRef: + description: A reference to a specific 'key' within + a Secret resource. In some instances, `key` is a + required field. type: object required: - name properties: key: description: The key of the entry in the Secret - resource's `data` field to be used. + resource's `data` field to be used. Some instances + of this field may be defaulted, in others it + may be required. type: string name: description: 'Name of the resource being referred @@ -337,7 +366,9 @@ spec: properties: key: description: The key of the entry in the Secret - resource's `data` field to be used. + resource's `data` field to be used. Some instances + of this field may be defaulted, in others it + may be required. type: string name: description: 'Name of the resource being referred @@ -351,7 +382,9 @@ spec: properties: key: description: The key of the entry in the Secret - resource's `data` field to be used. + resource's `data` field to be used. Some instances + of this field may be defaulted, in others it + may be required. type: string name: description: 'Name of the resource being referred @@ -376,13 +409,18 @@ spec: - tokenSecretRef properties: tokenSecretRef: + description: A reference to a specific 'key' within + a Secret resource. In some instances, `key` is a + required field. type: object required: - name properties: key: description: The key of the entry in the Secret - resource's `data` field to be used. + resource's `data` field to be used. Some instances + of this field may be defaulted, in others it + may be required. type: string name: description: 'Name of the resource being referred @@ -425,7 +463,9 @@ spec: properties: key: description: The key of the entry in the Secret - resource's `data` field to be used. + resource's `data` field to be used. Some instances + of this field may be defaulted, in others it + may be required. type: string name: description: 'Name of the resource being referred @@ -469,7 +509,9 @@ spec: properties: key: description: The key of the entry in the Secret - resource's `data` field to be used. + resource's `data` field to be used. Some instances + of this field may be defaulted, in others it + may be required. type: string name: description: 'Name of the resource being referred @@ -1625,8 +1667,9 @@ spec: is mounted in Vault, e.g: "approle"' type: string roleId: - description: RoleID configures in the App Role authentication - backend when setting up the App Role backend. + description: RoleID configured in the App Role authentication + backend when setting up the authentication backend in + Vault. type: string secretRef: description: Reference to a key in a Secret that contains @@ -1637,7 +1680,8 @@ spec: properties: key: description: The key of the entry in the Secret resource's - `data` field to be used. + `data` field to be used. Some instances of this field + may be defaulted, in others it may be required. type: string name: description: 'Name of the resource being referred to. @@ -1674,7 +1718,8 @@ spec: properties: key: description: The key of the entry in the Secret resource's - `data` field to be used. + `data` field to be used. Some instances of this field + may be defaulted, in others it may be required. type: string name: description: 'Name of the resource being referred to. @@ -1689,7 +1734,8 @@ spec: properties: key: description: The key of the entry in the Secret resource's - `data` field to be used. + `data` field to be used. Some instances of this field + may be defaulted, in others it may be required. type: string name: description: 'Name of the resource being referred to. More @@ -1713,7 +1759,7 @@ spec: type: string venafi: description: Venafi configures this issuer to sign certificates using - a Venafi TPP or Cloud policy zone. + a Venafi TPP or Venafi Cloud policy zone. type: object required: - zone @@ -1734,7 +1780,8 @@ spec: properties: key: description: The key of the entry in the Secret resource's - `data` field to be used. + `data` field to be used. Some instances of this field + may be defaulted, in others it may be required. type: string name: description: 'Name of the resource being referred to. More @@ -1783,7 +1830,7 @@ spec: the named zone policy. This field is required. type: string status: - description: Status of the ClusterIssuer, set and managed automatically. + description: Status of the ClusterIssuer. This is set and managed automatically. type: object properties: acme: diff --git a/deploy/crds/crd-issuers.yaml b/deploy/crds/crd-issuers.yaml index 74c122010..620545e35 100644 --- a/deploy/crds/crd-issuers.yaml +++ b/deploy/crds/crd-issuers.yaml @@ -128,7 +128,8 @@ spec: properties: key: description: The key of the entry in the Secret resource's - `data` field to be used. + `data` field to be used. Some instances of this field + may be defaulted, in others it may be required. type: string name: description: 'Name of the resource being referred to. More @@ -145,7 +146,8 @@ spec: properties: key: description: The key of the entry in the Secret resource's `data` - field to be used. + field to be used. Some instances of this field may be defaulted, + in others it may be required. type: string name: description: 'Name of the resource being referred to. More info: @@ -189,13 +191,18 @@ spec: - host properties: accountSecretRef: + description: A reference to a specific 'key' within + a Secret resource. In some instances, `key` is a + required field. type: object required: - name properties: key: description: The key of the entry in the Secret - resource's `data` field to be used. + resource's `data` field to be used. Some instances + of this field may be defaulted, in others it + may be required. type: string name: description: 'Name of the resource being referred @@ -214,39 +221,54 @@ spec: - serviceConsumerDomain properties: accessTokenSecretRef: + description: A reference to a specific 'key' within + a Secret resource. In some instances, `key` is a + required field. type: object required: - name properties: key: description: The key of the entry in the Secret - resource's `data` field to be used. + resource's `data` field to be used. Some instances + of this field may be defaulted, in others it + may be required. type: string name: description: 'Name of the resource being referred to. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names' type: string clientSecretSecretRef: + description: A reference to a specific 'key' within + a Secret resource. In some instances, `key` is a + required field. type: object required: - name properties: key: description: The key of the entry in the Secret - resource's `data` field to be used. + resource's `data` field to be used. Some instances + of this field may be defaulted, in others it + may be required. type: string name: description: 'Name of the resource being referred to. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names' type: string clientTokenSecretRef: + description: A reference to a specific 'key' within + a Secret resource. In some instances, `key` is a + required field. type: object required: - name properties: key: description: The key of the entry in the Secret - resource's `data` field to be used. + resource's `data` field to be used. Some instances + of this field may be defaulted, in others it + may be required. type: string name: description: 'Name of the resource being referred @@ -275,7 +297,9 @@ spec: properties: key: description: The key of the entry in the Secret - resource's `data` field to be used. + resource's `data` field to be used. Some instances + of this field may be defaulted, in others it + may be required. type: string name: description: 'Name of the resource being referred @@ -308,13 +332,18 @@ spec: project: type: string serviceAccountSecretRef: + description: A reference to a specific 'key' within + a Secret resource. In some instances, `key` is a + required field. type: object required: - name properties: key: description: The key of the entry in the Secret - resource's `data` field to be used. + resource's `data` field to be used. Some instances + of this field may be defaulted, in others it + may be required. type: string name: description: 'Name of the resource being referred @@ -336,7 +365,9 @@ spec: properties: key: description: The key of the entry in the Secret - resource's `data` field to be used. + resource's `data` field to be used. Some instances + of this field may be defaulted, in others it + may be required. type: string name: description: 'Name of the resource being referred @@ -350,7 +381,9 @@ spec: properties: key: description: The key of the entry in the Secret - resource's `data` field to be used. + resource's `data` field to be used. Some instances + of this field may be defaulted, in others it + may be required. type: string name: description: 'Name of the resource being referred @@ -375,13 +408,18 @@ spec: - tokenSecretRef properties: tokenSecretRef: + description: A reference to a specific 'key' within + a Secret resource. In some instances, `key` is a + required field. type: object required: - name properties: key: description: The key of the entry in the Secret - resource's `data` field to be used. + resource's `data` field to be used. Some instances + of this field may be defaulted, in others it + may be required. type: string name: description: 'Name of the resource being referred @@ -424,7 +462,9 @@ spec: properties: key: description: The key of the entry in the Secret - resource's `data` field to be used. + resource's `data` field to be used. Some instances + of this field may be defaulted, in others it + may be required. type: string name: description: 'Name of the resource being referred @@ -468,7 +508,9 @@ spec: properties: key: description: The key of the entry in the Secret - resource's `data` field to be used. + resource's `data` field to be used. Some instances + of this field may be defaulted, in others it + may be required. type: string name: description: 'Name of the resource being referred @@ -1624,8 +1666,9 @@ spec: is mounted in Vault, e.g: "approle"' type: string roleId: - description: RoleID configures in the App Role authentication - backend when setting up the App Role backend. + description: RoleID configured in the App Role authentication + backend when setting up the authentication backend in + Vault. type: string secretRef: description: Reference to a key in a Secret that contains @@ -1636,7 +1679,8 @@ spec: properties: key: description: The key of the entry in the Secret resource's - `data` field to be used. + `data` field to be used. Some instances of this field + may be defaulted, in others it may be required. type: string name: description: 'Name of the resource being referred to. @@ -1673,7 +1717,8 @@ spec: properties: key: description: The key of the entry in the Secret resource's - `data` field to be used. + `data` field to be used. Some instances of this field + may be defaulted, in others it may be required. type: string name: description: 'Name of the resource being referred to. @@ -1688,7 +1733,8 @@ spec: properties: key: description: The key of the entry in the Secret resource's - `data` field to be used. + `data` field to be used. Some instances of this field + may be defaulted, in others it may be required. type: string name: description: 'Name of the resource being referred to. More @@ -1712,7 +1758,7 @@ spec: type: string venafi: description: Venafi configures this issuer to sign certificates using - a Venafi TPP or Cloud policy zone. + a Venafi TPP or Venafi Cloud policy zone. type: object required: - zone @@ -1733,7 +1779,8 @@ spec: properties: key: description: The key of the entry in the Secret resource's - `data` field to be used. + `data` field to be used. Some instances of this field + may be defaulted, in others it may be required. type: string name: description: 'Name of the resource being referred to. More @@ -1782,7 +1829,7 @@ spec: the named zone policy. This field is required. type: string status: - description: Status of the Issuer, set and managed automatically. + description: Status of the Issuer. This is set and managed automatically. type: object properties: acme: diff --git a/pkg/internal/apis/acme/types_issuer.go b/pkg/internal/apis/acme/types_issuer.go index 7beedc8d5..eff6afbac 100644 --- a/pkg/internal/apis/acme/types_issuer.go +++ b/pkg/internal/apis/acme/types_issuer.go @@ -23,7 +23,6 @@ import ( cmmeta "github.com/jetstack/cert-manager/pkg/internal/apis/meta" ) - // ACMEIssuer contains the specification for an ACME issuer. // This uses the RFC8555 specification to obtain certificates by completing // 'challenges' to prove ownership of domain identifiers. From bfe3dd2c2bd605f2feaf4460a470df8af588e453 Mon Sep 17 00:00:00 2001 From: James Munnelly Date: Fri, 26 Jun 2020 14:46:07 +0100 Subject: [PATCH 10/12] review feedback Signed-off-by: James Munnelly --- pkg/apis/acme/v1alpha2/types_issuer.go | 9 ++++++--- pkg/apis/acme/v1alpha3/types_issuer.go | 9 ++++++--- pkg/apis/certmanager/v1alpha2/types_issuer.go | 4 +++- pkg/apis/certmanager/v1alpha3/types_issuer.go | 4 +++- pkg/internal/apis/acme/types_issuer.go | 9 ++++++--- pkg/internal/apis/certmanager/types_issuer.go | 4 +++- 6 files changed, 27 insertions(+), 12 deletions(-) diff --git a/pkg/apis/acme/v1alpha2/types_issuer.go b/pkg/apis/acme/v1alpha2/types_issuer.go index 94f0ecf96..3dd332e3a 100644 --- a/pkg/apis/acme/v1alpha2/types_issuer.go +++ b/pkg/apis/acme/v1alpha2/types_issuer.go @@ -37,11 +37,12 @@ type ACMEIssuer struct { Email string `json:"email,omitempty"` // Server is the URL used to access the ACME server's 'directory' endpoint. - // For examples, for Let's Encrypt's staging endpoint, you would use: + // For example, for Let's Encrypt's staging endpoint, you would use: // "https://acme-staging-v02.api.letsencrypt.org/directory". // Only ACME v2 endpoints (i.e. RFC 8555) are supported. Server string `json:"server"` + // Enables or disables validation of the ACME server TLS certificate. // If true, requests to the ACME server will not have their TLS certificate // validated (i.e. insecure connections will be allowed). // Only enable this option in development environments. @@ -58,8 +59,10 @@ type ACMEIssuer struct { // +optional ExternalAccountBinding *ACMEExternalAccountBinding `json:"externalAccountBinding,omitempty"` - // PrivateKey is the name of a Secret resource that will be used to store the - // automatically generated ACME account private key. + // PrivateKey is the name of a Kubernetes Secret resource that will be used to + // store the automatically generated ACME account private key. + // Optionally, a `key` may be specified to select a specific entry within + // the named Secret resource. // If `key` is not specified, a default of `tls.key` will be used. PrivateKey cmmeta.SecretKeySelector `json:"privateKeySecretRef"` diff --git a/pkg/apis/acme/v1alpha3/types_issuer.go b/pkg/apis/acme/v1alpha3/types_issuer.go index 04f06eddb..d369f3bc1 100644 --- a/pkg/apis/acme/v1alpha3/types_issuer.go +++ b/pkg/apis/acme/v1alpha3/types_issuer.go @@ -37,11 +37,12 @@ type ACMEIssuer struct { Email string `json:"email,omitempty"` // Server is the URL used to access the ACME server's 'directory' endpoint. - // For examples, for Let's Encrypt's staging endpoint, you would use: + // For example, for Let's Encrypt's staging endpoint, you would use: // "https://acme-staging-v02.api.letsencrypt.org/directory". // Only ACME v2 endpoints (i.e. RFC 8555) are supported. Server string `json:"server"` + // Enables or disables validation of the ACME server TLS certificate. // If true, requests to the ACME server will not have their TLS certificate // validated (i.e. insecure connections will be allowed). // Only enable this option in development environments. @@ -58,8 +59,10 @@ type ACMEIssuer struct { // +optional ExternalAccountBinding *ACMEExternalAccountBinding `json:"externalAccountBinding,omitempty"` - // PrivateKey is the name of a Secret resource that will be used to store the - // automatically generated ACME account private key. + // PrivateKey is the name of a Kubernetes Secret resource that will be used to + // store the automatically generated ACME account private key. + // Optionally, a `key` may be specified to select a specific entry within + // the named Secret resource. // If `key` is not specified, a default of `tls.key` will be used. PrivateKey cmmeta.SecretKeySelector `json:"privateKeySecretRef"` diff --git a/pkg/apis/certmanager/v1alpha2/types_issuer.go b/pkg/apis/certmanager/v1alpha2/types_issuer.go index 8549da8d0..bddb73e6c 100644 --- a/pkg/apis/certmanager/v1alpha2/types_issuer.go +++ b/pkg/apis/certmanager/v1alpha2/types_issuer.go @@ -225,7 +225,7 @@ type VaultAuth struct { Kubernetes *VaultKubernetesAuth `json:"kubernetes,omitempty"` } -// AppRole authenticates with Vault using the App Role auth mechanism, +// VaultAppRole authenticates with Vault using the App Role auth mechanism, // with the role and secret stored in a Kubernetes Secret resource. type VaultAppRole struct { // Path where the App Role authentication backend is mounted in Vault, e.g: @@ -238,6 +238,8 @@ type VaultAppRole struct { // Reference to a key in a Secret that contains the App Role secret used // to authenticate with Vault. + // The `key` field must be specified and denotes which entry within the Secret + // resource is used as the app role secret. SecretRef cmmeta.SecretKeySelector `json:"secretRef"` } diff --git a/pkg/apis/certmanager/v1alpha3/types_issuer.go b/pkg/apis/certmanager/v1alpha3/types_issuer.go index d7040b931..eb4515f73 100644 --- a/pkg/apis/certmanager/v1alpha3/types_issuer.go +++ b/pkg/apis/certmanager/v1alpha3/types_issuer.go @@ -225,7 +225,7 @@ type VaultAuth struct { Kubernetes *VaultKubernetesAuth `json:"kubernetes,omitempty"` } -// AppRole authenticates with Vault using the App Role auth mechanism, +// VaultAppRole authenticates with Vault using the App Role auth mechanism, // with the role and secret stored in a Kubernetes Secret resource. type VaultAppRole struct { // Path where the App Role authentication backend is mounted in Vault, e.g: @@ -238,6 +238,8 @@ type VaultAppRole struct { // Reference to a key in a Secret that contains the App Role secret used // to authenticate with Vault. + // The `key` field must be specified and denotes which entry within the Secret + // resource is used as the app role secret. SecretRef cmmeta.SecretKeySelector `json:"secretRef"` } diff --git a/pkg/internal/apis/acme/types_issuer.go b/pkg/internal/apis/acme/types_issuer.go index eff6afbac..8515d1ba6 100644 --- a/pkg/internal/apis/acme/types_issuer.go +++ b/pkg/internal/apis/acme/types_issuer.go @@ -36,11 +36,12 @@ type ACMEIssuer struct { Email string // Server is the URL used to access the ACME server's 'directory' endpoint. - // For examples, for Let's Encrypt's staging endpoint, you would use: + // For example, for Let's Encrypt's staging endpoint, you would use: // "https://acme-staging-v02.api.letsencrypt.org/directory". // Only ACME v2 endpoints (i.e. RFC 8555) are supported. Server string + // Enables or disables validation of the ACME server TLS certificate. // If true, requests to the ACME server will not have their TLS certificate // validated (i.e. insecure connections will be allowed). // Only enable this option in development environments. @@ -55,8 +56,10 @@ type ACMEIssuer struct { // external account credentials with the registered ACME account. ExternalAccountBinding *ACMEExternalAccountBinding - // PrivateKey is the name of a Secret resource that will be used to store the - // automatically generated ACME account private key. + // PrivateKey is the name of a Kubernetes Secret resource that will be used to + // store the automatically generated ACME account private key. + // Optionally, a `key` may be specified to select a specific entry within + // the named Secret resource. // If `key` is not specified, a default of `tls.key` will be used. PrivateKey cmmeta.SecretKeySelector diff --git a/pkg/internal/apis/certmanager/types_issuer.go b/pkg/internal/apis/certmanager/types_issuer.go index 45ca892dc..f956da599 100644 --- a/pkg/internal/apis/certmanager/types_issuer.go +++ b/pkg/internal/apis/certmanager/types_issuer.go @@ -199,7 +199,7 @@ type VaultAuth struct { Kubernetes *VaultKubernetesAuth } -// AppRole authenticates with Vault using the App Role auth mechanism, +// VaultAppRole authenticates with Vault using the App Role auth mechanism, // with the role and secret stored in a Kubernetes Secret resource. type VaultAppRole struct { // Path where the App Role authentication backend is mounted in Vault, e.g: @@ -212,6 +212,8 @@ type VaultAppRole struct { // Reference to a key in a Secret that contains the App Role secret used // to authenticate with Vault. + // The `key` field must be specified and denotes which entry within the Secret + // resource is used as the app role secret. SecretRef cmmeta.SecretKeySelector } From 7d1ba9e2aec0ea4633a08fda87b92df67e1b9eef Mon Sep 17 00:00:00 2001 From: James Munnelly Date: Fri, 26 Jun 2020 14:46:49 +0100 Subject: [PATCH 11/12] generated files Signed-off-by: James Munnelly --- deploy/crds/crd-clusterissuers.yaml | 18 +++++++++++------- deploy/crds/crd-issuers.yaml | 18 +++++++++++------- 2 files changed, 22 insertions(+), 14 deletions(-) diff --git a/deploy/crds/crd-clusterissuers.yaml b/deploy/crds/crd-clusterissuers.yaml index 60bdf095f..8c336f3bf 100644 --- a/deploy/crds/crd-clusterissuers.yaml +++ b/deploy/crds/crd-clusterissuers.yaml @@ -137,10 +137,11 @@ spec: info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names' type: string privateKeySecretRef: - description: PrivateKey is the name of a Secret resource that will - be used to store the automatically generated ACME account private - key. If `key` is not specified, a default of `tls.key` will be - used. + description: PrivateKey is the name of a Kubernetes Secret resource + that will be used to store the automatically generated ACME account + private key. Optionally, a `key` may be specified to select a + specific entry within the named Secret resource. If `key` is not + specified, a default of `tls.key` will be used. type: object required: - name @@ -156,12 +157,13 @@ spec: type: string server: description: 'Server is the URL used to access the ACME server''s - ''directory'' endpoint. For examples, for Let''s Encrypt''s staging + ''directory'' endpoint. For example, for Let''s Encrypt''s staging endpoint, you would use: "https://acme-staging-v02.api.letsencrypt.org/directory". Only ACME v2 endpoints (i.e. RFC 8555) are supported.' type: string skipTLSVerify: - description: If true, requests to the ACME server will not have + description: Enables or disables validation of the ACME server TLS + certificate. If true, requests to the ACME server will not have their TLS certificate validated (i.e. insecure connections will be allowed). Only enable this option in development environments. The cert-manager system installed roots will be used to verify @@ -1673,7 +1675,9 @@ spec: type: string secretRef: description: Reference to a key in a Secret that contains - the App Role secret used to authenticate with Vault. + the App Role secret used to authenticate with Vault. The + `key` field must be specified and denotes which entry + within the Secret resource is used as the app role secret. type: object required: - name diff --git a/deploy/crds/crd-issuers.yaml b/deploy/crds/crd-issuers.yaml index 620545e35..f4867c3dd 100644 --- a/deploy/crds/crd-issuers.yaml +++ b/deploy/crds/crd-issuers.yaml @@ -136,10 +136,11 @@ spec: info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names' type: string privateKeySecretRef: - description: PrivateKey is the name of a Secret resource that will - be used to store the automatically generated ACME account private - key. If `key` is not specified, a default of `tls.key` will be - used. + description: PrivateKey is the name of a Kubernetes Secret resource + that will be used to store the automatically generated ACME account + private key. Optionally, a `key` may be specified to select a + specific entry within the named Secret resource. If `key` is not + specified, a default of `tls.key` will be used. type: object required: - name @@ -155,12 +156,13 @@ spec: type: string server: description: 'Server is the URL used to access the ACME server''s - ''directory'' endpoint. For examples, for Let''s Encrypt''s staging + ''directory'' endpoint. For example, for Let''s Encrypt''s staging endpoint, you would use: "https://acme-staging-v02.api.letsencrypt.org/directory". Only ACME v2 endpoints (i.e. RFC 8555) are supported.' type: string skipTLSVerify: - description: If true, requests to the ACME server will not have + description: Enables or disables validation of the ACME server TLS + certificate. If true, requests to the ACME server will not have their TLS certificate validated (i.e. insecure connections will be allowed). Only enable this option in development environments. The cert-manager system installed roots will be used to verify @@ -1672,7 +1674,9 @@ spec: type: string secretRef: description: Reference to a key in a Secret that contains - the App Role secret used to authenticate with Vault. + the App Role secret used to authenticate with Vault. The + `key` field must be specified and denotes which entry + within the Secret resource is used as the app role secret. type: object required: - name From 636083f8e95621b904f93a57983971a666e6ab95 Mon Sep 17 00:00:00 2001 From: James Munnelly Date: Fri, 26 Jun 2020 14:49:55 +0100 Subject: [PATCH 12/12] Fix up use of omitempty and optional in Cloudflare config struct Signed-off-by: James Munnelly --- pkg/apis/acme/v1alpha2/types_issuer.go | 4 +++- pkg/apis/acme/v1alpha3/types_issuer.go | 4 +++- 2 files changed, 6 insertions(+), 2 deletions(-) diff --git a/pkg/apis/acme/v1alpha2/types_issuer.go b/pkg/apis/acme/v1alpha2/types_issuer.go index 3dd332e3a..438945c51 100644 --- a/pkg/apis/acme/v1alpha2/types_issuer.go +++ b/pkg/apis/acme/v1alpha2/types_issuer.go @@ -356,14 +356,16 @@ type ACMEIssuerDNS01ProviderCloudDNS struct { type ACMEIssuerDNS01ProviderCloudflare struct { // Email of the account, only required when using API key based authentication. // +optional - Email string `json:"email"` + Email string `json:"email,omitempty"` // API key to use to authenticate with Cloudflare. // Note: using an API token to authenticate is now the recommended method // as it allows greater control of permissions. + // +optional APIKey *cmmeta.SecretKeySelector `json:"apiKeySecretRef,omitempty"` // API token used to authenticate with Cloudflare. + // +optional APIToken *cmmeta.SecretKeySelector `json:"apiTokenSecretRef,omitempty"` } diff --git a/pkg/apis/acme/v1alpha3/types_issuer.go b/pkg/apis/acme/v1alpha3/types_issuer.go index d369f3bc1..d01603fc8 100644 --- a/pkg/apis/acme/v1alpha3/types_issuer.go +++ b/pkg/apis/acme/v1alpha3/types_issuer.go @@ -356,14 +356,16 @@ type ACMEIssuerDNS01ProviderCloudDNS struct { type ACMEIssuerDNS01ProviderCloudflare struct { // Email of the account, only required when using API key based authentication. // +optional - Email string `json:"email"` + Email string `json:"email,omitempty"` // API key to use to authenticate with Cloudflare. // Note: using an API token to authenticate is now the recommended method // as it allows greater control of permissions. + // +optional APIKey *cmmeta.SecretKeySelector `json:"apiKeySecretRef,omitempty"` // API token used to authenticate with Cloudflare. + // +optional APIToken *cmmeta.SecretKeySelector `json:"apiTokenSecretRef,omitempty"` }