update dns delegation, add details for log level

Author: Trevor Ackerman

content/docs/cli/cainjector.md

@@ -46,6 +46,6 @@ Flags:
       --metrics-tls-private-key-file string                  path to the file containing the TLS private key to serve metrics with
       --namespace string                                     If set, this limits the scope of cainjector to a single namespace. If set, cainjector will not update resources with certificates outside of the configured namespace.
       --profiler-address string                              The host and port that Go profiler should listen on, i.e localhost:6060. Ensure that profiler is not exposed on a public address. Profiler will be served at /debug/pprof. (default "localhost:6060")
-  -v, --v Level                                              number for the log level verbosity
+  -v, --v Level                                              number for the log level verbosity, 0 for Error, 1 for Warn, 2 for Info, 3 for Extended Info, 4 for Debug, 5 for Trace, default is 2
       --vmodule pattern=N,...                                comma-separated list of pattern=N settings for file-filtered logging (only works for text log format)
 ```

content/docs/cli/cmctl.md

@@ -26,7 +26,7 @@ Flags:
   -h, --help                           help for cmctl
       --log-flush-frequency duration   Maximum number of seconds between log flushes (default 5s)
       --logging-format string          Sets the log format. Permitted formats: "json" (gated by LoggingBetaOptions), "text". (default "text")
-  -v, --v Level[=2]                    number for the log level verbosity
+  -v, --v Level                        number for the log level verbosity, 0 for Error, 1 for Warn, 2 for Info, 3 for Extended Info, 4 for Debug, 5 for Trace, default is 2
       --vmodule pattern=N,...          comma-separated list of pattern=N settings for file-filtered logging (only works for text log format)
 
 Use "cmctl [command] --help" for more information about a command.

content/docs/cli/controller.md

@@ -78,6 +78,6 @@ Flags:
       --metrics-tls-private-key-file string                  path to the file containing the TLS private key to serve with
       --namespace string                                     If set, this limits the scope of cert-manager to a single namespace and ClusterIssuers are disabled. If not specified, all namespaces will be watched
       --profiler-address string                              The host and port that Go profiler should listen on, i.e localhost:6060. Ensure that profiler is not exposed on a public address. Profiler will be served at /debug/pprof. (default "localhost:6060")
-  -v, --v Level                                              number for the log level verbosity
+  -v, --v Level                                              number for the log level verbosity, 0 for Error, 1 for Warn, 2 for Info, 3 for Extended Info, 4 for Debug, 5 for Trace, default is 2
       --vmodule pattern=N,...                                comma-separated list of pattern=N settings for file-filtered logging (only works for text log format)
 ```

content/docs/cli/startupapicheck.md

@@ -17,7 +17,7 @@ Flags:
   -h, --help                           help for startupapicheck
       --log-flush-frequency duration   Maximum number of seconds between log flushes (default 5s)
       --logging-format string          Sets the log format. Permitted formats: "json" (gated by LoggingBetaOptions), "text". (default "text")
-  -v, --v Level[=2]                    number for the log level verbosity
+      -v, --v Level                    number for the log level verbosity, 0 for Error, 1 for Warn, 2 for Info, 3 for Extended Info, 4 for Debug, 5 for Trace, default is 2
       --vmodule pattern=N,...          comma-separated list of pattern=N settings for file-filtered logging (only works for text log format)
 
 Use "startupapicheck [command] --help" for more information about a command.

content/docs/cli/webhook.md

@@ -48,6 +48,6 @@ Flags:
       --tls-cipher-suites strings                            Comma-separated list of cipher suites for the server. If omitted, the default Go cipher suites will be used.  Possible values: TLS_AES_128_GCM_SHA256,TLS_AES_256_GCM_SHA384,TLS_CHACHA20_POLY1305_SHA256,TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA,TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256,TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA,TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256,TLS_ECDHE_ECDSA_WITH_RC4_128_SHA,TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA,TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA,TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256,TLS_ECDHE_RSA_WITH_RC4_128_SHA,TLS_RSA_WITH_3DES_EDE_CBC_SHA,TLS_RSA_WITH_AES_128_CBC_SHA,TLS_RSA_WITH_AES_128_CBC_SHA256,TLS_RSA_WITH_AES_128_GCM_SHA256,TLS_RSA_WITH_AES_256_CBC_SHA,TLS_RSA_WITH_AES_256_GCM_SHA384,TLS_RSA_WITH_RC4_128_SHA
       --tls-min-version string                               Minimum TLS version supported. If omitted, the default Go minimum version will be used. Possible values: VersionTLS10, VersionTLS11, VersionTLS12, VersionTLS13
       --tls-private-key-file string                          path to the file containing the TLS private key to serve with
-  -v, --v Level                                              number for the log level verbosity
+  -v, --v Level                                              number for the log level verbosity, 0 for Error, 1 for Warn, 2 for Info, 3 for Extended Info, 4 for Debug, 5 for Trace, default is 2
       --vmodule pattern=N,...                                comma-separated list of pattern=N settings for file-filtered logging (only works for text log format)
 ```

content/docs/configuration/acme/dns01/README.md

@@ -84,11 +84,19 @@ By default, cert-manager will not follow CNAME records pointing to subdomains.
 
 If granting cert-manager access to the root DNS zone is not desired, then the
 `_acme-challenge.example.com` subdomain can instead be delegated to some other,
-less privileged domain (`less-privileged.example.org`). This could be achieved in the following way. Say, one has two zones:
+less privileged domain.
+
+### Nonmatching Subdomains
+
+Delegation could be achieved in the following way. Say, one has two zones:
 
 * `example.com`
 * `less-privileged.example.org`
 
+Notice how the above two zones have different Top Level Domains (i.e. `.com` vs `.org`).
+This means cert-manager will be querying for expected `TXT` records against authoritative nameservers
+for `example.org` instead of authoritative nameservers for `example.com`.
+
 1. Create a CNAME record pointing to this less privileged domain:
 ```
 _acme-challenge.example.com	IN	CNAME	_acme-challenge.less-privileged.example.org.
@@ -124,6 +132,68 @@ spec:
             ...
 ```
 
+### Matching Subdomains and Multiple DNS Providers
+
+Be aware of hurdles that exist when the two zones share the same subdomain, for example:
+
+* `example.com`
+* `less-privileged.example.com`
+
+This is different than the previous example where we used `.org` for our delegated zone.
+
+When different providers manage each of the above domains you must take additional steps.
+
+The following illustrates how to delegate when Google CloudDNS manages the domain
+`less-privileged.example.com` and a separate DNS provider manages the domain `example.com`.
+
+1. Create a CNAME record pointing to this less privileged domain:
+Create this record in the DNS Provider that manages the `example.com.` domain.
+```
+_acme-challenge.example.com	IN	CNAME	_acme-challenge.less-privileged.example.com.
+```
+
+2. Create NS records pointing to Google CloudDNS for this less privileged domain:
+This is required in order for the DNS provider managing `example.com` to be able to
+delegate answers for `less-privileged.example.com` to Google CloudDNS. Otherwise
+DNS queries by cert-manager for TXT records will receive an `NXDOMAIN` response
+and fail.
+
+Create this record in the DNS Provider that manages the `example.com.` domain.
+```
+less-privileged.example.com.		3600	IN	NS	ns-cloud-a1.googledomains.com.
+less-privileged.example.com.		3600	IN	NS	ns-cloud-a2.googledomains.com.
+less-privileged.example.com.		3600	IN	NS	ns-cloud-a3.googledomains.com.
+less-privileged.example.com.		3600	IN	NS	ns-cloud-a4.googledomains.com.
+```
+
+3. Grant cert-manager rights to update less privileged `less-privileged.example.com` zone
+
+4. Provide configuration/credentials for updating this less privileged zone
+and add an additional field into the relevant `dns01` solver. Note that `selector`
+field is now pointing to the delegated zone `less-privileged.example.com`.
+
+```yaml
+apiVersion: cert-manager.io/v1
+kind: Issuer
+metadata:
+  ...
+spec:
+  acme:
+    ...
+    solvers:
+    - selector:
+        dnsZones:
+        - 'less-privileged.example.com'
+      dns01:
+        # Valid values are None and Follow
+        cnameStrategy: Follow
+        cloudDNS:
+          # The ID of the GCP project
+          project: $PROJECT_ID
+            ...
+```
+
+### Multiple Subdomains Requiring Separate Certificates
 If you have a multitude of (sub)domains requiring separate certificates,
 it is possible to share an aliased less-privileged domain. To achieve it one should
 create a CNAME record for each (sub)domain like this: