diff --git a/deploy/crds/crd-certificaterequests.yaml b/deploy/crds/crd-certificaterequests.yaml index 51af11739..ef793b1b9 100644 --- a/deploy/crds/crd-certificaterequests.yaml +++ b/deploy/crds/crd-certificaterequests.yaml @@ -78,22 +78,25 @@ spec: metadata: type: object spec: - description: CertificateRequestSpec defines the desired state of CertificateRequest + description: Desired state of the CertificateRequest resource. type: object required: - csr - 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: - 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 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 @@ -108,15 +111,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,21 +160,26 @@ spec: - microsoft sgc - netscape sgc status: - description: CertificateStatus defines the observed state of CertificateRequest - and resulting signed certificate. + description: Status of the CertificateRequest. This is set and managed automatically. type: object properties: ca: - description: Byte slice containing the PEM encoded certificate authority - of the signed certificate. + 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: + 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 +211,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..575e997b9 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 + 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. @@ -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,13 @@ 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. Some instances of this field + may be defaulted, in others it may be required. 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 +230,17 @@ 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. Some instances of this field + may be defaulted, in others it may be required. 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 a list of organizations to be used on + the Certificate. type: array items: type: string @@ -250,11 +260,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 +310,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 +356,12 @@ spec: - microsoft sgc - netscape sgc status: - description: CertificateStatus defines the observed state of Certificate + description: Status of the Certificate. This is 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 +393,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 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 nextPrivateKeySecretName: @@ -389,7 +412,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 +458,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 +471,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 + 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. @@ -486,15 +512,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 +542,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 +579,13 @@ 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. Some instances of this field + may be defaulted, in others it may be required. 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 +611,13 @@ 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. Some instances of this field + may be defaulted, in others it may be required. 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 +635,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 +690,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 +736,12 @@ spec: - microsoft sgc - netscape sgc status: - description: CertificateStatus defines the observed state of Certificate + description: Status of the Certificate. This is 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 +773,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 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 nextPrivateKeySecretName: @@ -747,7 +792,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..4cb0915b4 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 @@ -128,35 +131,39 @@ 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 - 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 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. Some instances of this field + may be defaulted, in others it may be required. 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 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 @@ -165,49 +172,58 @@ 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 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. Some instances of this field + may be defaulted, in others it may be required. 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: + 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 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. Some instances of this field + may be defaulted, in others it may be required. 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: + 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 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. Some instances of this field + may be defaulted, in others it may be required. 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 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 @@ -225,12 +241,13 @@ 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. Some instances of this field + may be defaulted, in others it may be required. 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 @@ -250,8 +267,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 @@ -259,50 +276,61 @@ 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 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. Some instances of this field + may be defaulted, in others it may be required. 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 - 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 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. Some instances of this field + may be defaulted, in others it may be required. 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: + description: API token used to authenticate with Cloudflare. 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. Some instances of this field + may be defaulted, in others it may be required. 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: + description: Email of the account, only required when using + API key based authentication. type: string cnameStrategy: description: CNAMEStrategy configures how the DNS01 provider @@ -312,28 +340,32 @@ 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 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 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. Some instances of this field + may be defaulted, in others it may be required. 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 - 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 @@ -364,16 +396,17 @@ 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. Some instances of this field + may be defaulted, in others it may be required. 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 - the Route 53 configuration for AWS + description: Use the AWS Route53 API to manage DNS01 challenge + records. type: object required: - region @@ -407,17 +440,17 @@ 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. Some instances of this field + may be defaulted, in others it may be required. 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 - 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 @@ -445,12 +478,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: @@ -1363,7 +1394,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 381261a3d..8c336f3bf 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,23 +73,29 @@ 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 - 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 @@ -118,73 +128,94 @@ 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. Some instances of this field + may be defaulted, in others it may be required. 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 - key for this user account. + 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 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. Some instances of this field may be defaulted, + in others it may be required. 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 + description: 'Server is the URL used to access the ACME server''s + ''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, skip verifying the ACME server TLS certificate + 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 + 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 - 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 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. Some instances + of this field may be defaulted, in others it + may be required. 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 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 @@ -193,55 +224,64 @@ 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 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. Some instances + of this field may be defaulted, in others it + may be required. 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: + 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 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. Some instances + of this field may be defaulted, in others it + may be required. 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: + 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 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. Some instances + of this field may be defaulted, in others it + may be required. 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 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 @@ -259,14 +299,14 @@ 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. Some instances + of this field may be defaulted, in others it + may be required. 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 @@ -286,8 +326,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 @@ -295,56 +335,66 @@ 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 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. Some instances + of this field may be defaulted, in others it + may be required. 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 - 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 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. Some instances + of this field may be defaulted, in others it + may be required. 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: + description: API token used to authenticate with Cloudflare. 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. Some instances + of this field may be defaulted, in others it + may be required. 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: + description: Email of the account, only required when + using API key based authentication. type: string cnameStrategy: description: CNAMEStrategy configures how the DNS01 provider @@ -354,31 +404,34 @@ 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 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 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. Some instances + of this field may be defaulted, in others it + may be required. 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 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 @@ -411,18 +464,18 @@ 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. Some instances + of this field may be defaulted, in others it + may be required. 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 the Route 53 configuration for AWS + description: Use the AWS Route53 API to manage DNS01 challenge + records. type: object required: - region @@ -457,19 +510,18 @@ 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. Some instances + of this field may be defaulted, in others it + may be required. 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 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 @@ -498,12 +550,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: @@ -1520,6 +1571,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: @@ -1554,6 +1608,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 +1618,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 +1628,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 +1641,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 +1650,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 +1665,36 @@ 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 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 + 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 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. Some instances of this field + may be defaulted, in others it may be required. 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 +1721,49 @@ 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. Some instances of this field + may be defaulted, in others it may be required. 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. Some instances of this field + may be defaulted, in others it may be required. 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 Venafi Cloud policy zone. type: object required: - zone @@ -1704,15 +1783,17 @@ 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. Some instances of this field + may be defaulted, in others it may be required. 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. Defaults + to "https://api.venafi.cloud/v1". type: string tpp: description: TPP specifies Trust Protection Platform configuration @@ -1740,11 +1821,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 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. @@ -1752,10 +1834,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. This is 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 +1852,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 +1885,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..f4867c3dd 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,23 +72,29 @@ 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 - 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 @@ -118,73 +127,94 @@ 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. Some instances of this field + may be defaulted, in others it may be required. 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 - key for this user account. + 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 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. Some instances of this field may be defaulted, + in others it may be required. 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 + description: 'Server is the URL used to access the ACME server''s + ''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, skip verifying the ACME server TLS certificate + 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 + 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 - 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 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. Some instances + of this field may be defaulted, in others it + may be required. 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 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 @@ -193,55 +223,64 @@ 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 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. Some instances + of this field may be defaulted, in others it + may be required. 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: + 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 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. Some instances + of this field may be defaulted, in others it + may be required. 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: + 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 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. Some instances + of this field may be defaulted, in others it + may be required. 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 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 @@ -259,14 +298,14 @@ 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. Some instances + of this field may be defaulted, in others it + may be required. 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 @@ -286,8 +325,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 @@ -295,56 +334,66 @@ 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 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. Some instances + of this field may be defaulted, in others it + may be required. 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 - 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 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. Some instances + of this field may be defaulted, in others it + may be required. 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: + description: API token used to authenticate with Cloudflare. 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. Some instances + of this field may be defaulted, in others it + may be required. 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: + description: Email of the account, only required when + using API key based authentication. type: string cnameStrategy: description: CNAMEStrategy configures how the DNS01 provider @@ -354,31 +403,34 @@ 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 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 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. Some instances + of this field may be defaulted, in others it + may be required. 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 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 @@ -411,18 +463,18 @@ 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. Some instances + of this field may be defaulted, in others it + may be required. 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 the Route 53 configuration for AWS + description: Use the AWS Route53 API to manage DNS01 challenge + records. type: object required: - region @@ -457,19 +509,18 @@ 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. Some instances + of this field may be defaulted, in others it + may be required. 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 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 @@ -498,12 +549,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: @@ -1520,6 +1570,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: @@ -1554,6 +1607,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 +1617,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 +1627,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 +1640,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 +1649,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 +1664,36 @@ 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 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 + 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 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. Some instances of this field + may be defaulted, in others it may be required. 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 +1720,49 @@ 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. Some instances of this field + may be defaulted, in others it may be required. 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. Some instances of this field + may be defaulted, in others it may be required. 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 Venafi Cloud policy zone. type: object required: - zone @@ -1704,15 +1782,17 @@ 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. Some instances of this field + may be defaulted, in others it may be required. 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. Defaults + to "https://api.venafi.cloud/v1". type: string tpp: description: TPP specifies Trust Protection Platform configuration @@ -1740,11 +1820,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 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. @@ -1752,10 +1833,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. This is 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 +1851,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 +1884,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..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 @@ -114,10 +111,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 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/acme/v1alpha2/types_issuer.go b/pkg/apis/acme/v1alpha2/types_issuer.go index 986753c3c..438945c51 100644 --- a/pkg/apis/acme/v1alpha2/types_issuer.go +++ b/pkg/apis/acme/v1alpha2/types_issuer.go @@ -23,30 +23,54 @@ 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 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"` - // If true, skip verifying the ACME server TLS certificate + // 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 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 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"` // 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 +90,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 +105,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 +265,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 +351,21 @@ 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,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 - Email string `json:"email"` - APIKey *cmmeta.SecretKeySelector `json:"apiKeySecretRef,omitempty"` APIToken *cmmeta.SecretKeySelector `json:"apiTokenSecretRef,omitempty"` } @@ -344,7 +404,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..d01603fc8 100644 --- a/pkg/apis/acme/v1alpha3/types_issuer.go +++ b/pkg/apis/acme/v1alpha3/types_issuer.go @@ -23,30 +23,54 @@ 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 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"` - // If true, skip verifying the ACME server TLS certificate + // 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 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 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"` // 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 +90,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 +105,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 +265,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 +351,21 @@ 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,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 - Email string `json:"email"` - APIKey *cmmeta.SecretKeySelector `json:"apiKeySecretRef,omitempty"` APIToken *cmmeta.SecretKeySelector `json:"apiTokenSecretRef,omitempty"` } @@ -344,7 +404,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/apis/certmanager/v1alpha2/types.go b/pkg/apis/certmanager/v1alpha2/types.go index 5612f43dd..37a585f76 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 for the 'kind' of the Issuer resource. + IssuerKindAnnotationKey = "cert-manager.io/issuer-kind" + + // Annotation key for the 'group' of the Issuer resource. + IssuerGroupAnnotationKey = "cert-manager.io/issuer-group" + + // 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. 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..08f69d43b 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. This is 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 a list of organizations 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 @@ -130,19 +151,22 @@ 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. - // This implies that the 'cert sign' usage is set + // 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"` - // 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 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 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..88c56c9a4 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. This is 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"` @@ -72,33 +83,42 @@ 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 mark the resulting certificate as valid for signing. This - // implies that the 'cert sign' usage is set + // 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"` - // 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"` } -// 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. + // Known condition types are `Ready` and `InvalidRequest`. // +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. + // 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"` @@ -110,7 +130,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..bddb73e6c 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. This is 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. This is 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 Venafi Cloud policy zone. // +optional Venafi *VenafiIssuer `json:"venafi,omitempty"` } -// VenafiIssuer describes issuer configuration details for Venafi Cloud. +// 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. // 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 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 @@ -139,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 + // URL is the base URL for Venafi Cloud. + // Defaults to "https://api.venafi.cloud/v1". // +optional URL string `json:"url,omitempty"` @@ -147,6 +176,8 @@ type VenafiCloud struct { APITokenSecretRef cmmeta.SecretKeySelector `json:"apiTokenSecretRef"` } +// 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 // the location of the CRL from which the revocation of this certificate can be checked. @@ -155,17 +186,20 @@ type SelfSignedIssuer struct { CRLDistributionPoints []string `json:"crlDistributionPoints,omitempty"` } +// Configures an 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 +207,39 @@ 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"` } +// VaultAppRole 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 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 + // 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"` } @@ -227,23 +270,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 +318,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..c578027c1 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 for the 'kind' of the Issuer resource. + IssuerKindAnnotationKey = "cert-manager.io/issuer-kind" + + // Annotation key for the 'group' of the Issuer resource. IssuerGroupAnnotationKey = "cert-manager.io/issuer-group" - CertificateNameKey = "cert-manager.io/certificate-name" + + // 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. + 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" @@ -68,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 54b3717dd..e6e88a67f 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. This is 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 @@ -126,19 +149,22 @@ 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. - // This implies that the 'cert sign' usage is set + // 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"` - // 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 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 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..e728aed8a 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. This is 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"` @@ -72,33 +83,42 @@ 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 mark the resulting certificate as valid for signing. This - // implies that the 'cert sign' usage is set + // 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"` - // 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"` } -// 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. + // Known condition types are `Ready` and `InvalidRequest`. // +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. + // 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"` @@ -110,7 +130,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 +160,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..eb4515f73 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. This is 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. This is 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 Venafi Cloud policy zone. // +optional Venafi *VenafiIssuer `json:"venafi,omitempty"` } -// VenafiIssuer describes issuer configuration details for Venafi Cloud. +// 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. // 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 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 @@ -139,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 + // URL is the base URL for Venafi Cloud. + // Defaults to "https://api.venafi.cloud/v1". // +optional URL string `json:"url,omitempty"` @@ -147,6 +176,8 @@ type VenafiCloud struct { APITokenSecretRef cmmeta.SecretKeySelector `json:"apiTokenSecretRef"` } +// 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 // the location of the CRL from which the revocation of this certificate can be checked. @@ -155,17 +186,20 @@ type SelfSignedIssuer struct { CRLDistributionPoints []string `json:"crlDistributionPoints,omitempty"` } +// Configures an 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 +207,39 @@ 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"` } +// VaultAppRole 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 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 + // 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"` } @@ -227,23 +270,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 +318,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..a0aa406d3 100644 --- a/pkg/apis/meta/v1/types.go +++ b/pkg/apis/meta/v1/types.go @@ -36,30 +36,44 @@ 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 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"` } +// 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 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. + // Some instances of this field may be defaulted, in others it may be + // required. // +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/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/pkg/internal/apis/acme/types_issuer.go b/pkg/internal/apis/acme/types_issuer.go index 65b04a3b4..8515d1ba6 100644 --- a/pkg/internal/apis/acme/types_issuer.go +++ b/pkg/internal/apis/acme/types_issuer.go @@ -23,27 +23,51 @@ 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 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 - // If true, skip verifying the ACME server TLS certificate + // 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 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 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 // 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 +82,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 +100,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 +239,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 +313,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 +359,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 +437,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 } diff --git a/pkg/internal/apis/certmanager/types.go b/pkg/internal/apis/certmanager/types.go index ce779c64d..76e577b8b 100644 --- a/pkg/internal/apis/certmanager/types.go +++ b/pkg/internal/apis/certmanager/types.go @@ -16,25 +16,79 @@ 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 for the 'kind' of the Issuer resource. + IssuerKindAnnotationKey = "cert-manager.io/issuer-kind" + + // Annotation key for the 'group' of the Issuer resource. IssuerGroupAnnotationKey = "cert-manager.io/issuer-group" - CertificateNameKey = "cert-manager.io/certificate-name" + + // 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. + 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" +) + +// Common/known resource kinds. const ( ClusterIssuerKind = "ClusterIssuer" IssuerKind = "Issuer" @@ -67,9 +121,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..e6aed0f93 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. This is 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. @@ -106,22 +129,25 @@ 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. - // This implies that the 'cert sign' usage is set + // 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 - // 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 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 // 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..950d68182 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. This is 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 @@ -63,29 +74,38 @@ 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 mark the resulting certificate as valid for signing. This - // implies that the 'signing' usage is set + // 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 - // 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 +// 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. + // 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. + // 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 @@ -95,7 +115,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..f956da599 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. This is 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. This is 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 Venafi Cloud policy zone. Venafi *VenafiIssuer } -// VenafiIssuer describes issuer configuration details for Venafi Cloud. +// 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. // 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 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 @@ -119,72 +147,83 @@ 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. + // Defaults to "https://api.venafi.cloud/v1". URL string // APITokenSecretRef is a secret key selector for the Venafi Cloud API token. APITokenSecretRef cmmeta.SecretKeySelector } +// 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 // 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 } +// Configures an 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. +// VaultAppRole 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 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 + // 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 } // 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 +243,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 +285,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..869301994 100644 --- a/pkg/internal/apis/meta/types.go +++ b/pkg/internal/apis/meta/types.go @@ -35,27 +35,41 @@ 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 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 } +// 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 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. + // Some instances of this field may be defaulted, in others it may be + // required. Key string } const ( + // Used as a data key in Secret resources to store a CA certificate. TLSCAKey = "ca.crt" ) 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, }), ) })