Update docs for tls commands (#16077)

command/tls/ca/create/tls_ca_create.go

@@ -4,11 +4,12 @@ import (
 	"flag"
 	"fmt"
 
+	"github.com/mitchellh/cli"
+
 	"github.com/hashicorp/consul/command/flags"
 	"github.com/hashicorp/consul/command/tls"
 	"github.com/hashicorp/consul/lib/file"
 	"github.com/hashicorp/consul/tlsutil"
-	"github.com/mitchellh/cli"
 )
 
 func New(ui cli.Ui) *cmd {
@@ -32,13 +33,14 @@ type cmd struct {
 func (c *cmd) init() {
 	c.flags = flag.NewFlagSet("", flag.ContinueOnError)
 	// TODO: perhaps add a -years arg to better capture user intent given that leap years are a thing
-	c.flags.IntVar(&c.days, "days", 1825, "Provide number of days the CA is valid for from now on. Defaults to 5 years.")
+	c.flags.IntVar(&c.days, "days", 1825, "Number of days the CA is valid for. Defaults to 1825 days (approximately 5 years).")
-	c.flags.BoolVar(&c.constraint, "name-constraint", false, "Add name constraints for the CA. Results in rejecting "+
+	c.flags.BoolVar(&c.constraint, "name-constraint", false, "Enables X.509 name constraints for the CA. "+
-		"certificates for other DNS than specified. If turned on localhost and -domain will be added to the allowed "+
+		"If used, the CA only signs certificates for localhost and the domains specified by -domain and -additional-name-constraint. "+
-		"DNS. If the UI is going to be served over HTTPS its DNS has to be added with -additional-constraint. It is not "+
+		"If Consul's UI is served over HTTPS in your deployment, add its DNS name with -additional-constraint. Defaults to false.")
-		"possible to add that after the fact! Defaults to false.")
+	c.flags.StringVar(&c.domain, "domain", "consul", "The DNS domain of the Consul cluster that agents are configured with. "+
-	c.flags.StringVar(&c.domain, "domain", "consul", "Domain of consul cluster. Only used in combination with -name-constraint. Defaults to consul.")
+		"Defaults to consul. Only used when -name-constraint is set. "+
-	c.flags.StringVar(&c.clusterID, "cluster-id", "", "ClusterID of the consul cluster, requires -domain to be set as well. When used will set URIs with spiffeid.")
+		"Additional domains can be passed with -additional-name-constraint.")
+	c.flags.StringVar(&c.clusterID, "cluster-id", "", "ID of the Consul cluster. Sets the CA's URI with the SPIFFEID composed of the cluster ID and domain  (specified by -domain or 'consul' by default).")
 	c.flags.StringVar(&c.commonName, "common-name", "", "Common Name of CA. Defaults to Consul Agent CA.")
 	c.flags.Var(&c.additionalConstraints, "additional-name-constraint", "Add name constraints for the CA. Results in rejecting certificates "+
 		"for other DNS than specified. Can be used multiple times. Only used in combination with -name-constraint.")

command/tls/ca/tls_ca.go

@@ -1,8 +1,9 @@
 package ca
 
 import (
-	"github.com/hashicorp/consul/command/flags"
 	"github.com/mitchellh/cli"
+
+	"github.com/hashicorp/consul/command/flags"
 )
 
 func New() *cmd {
@@ -25,7 +26,7 @@ func (c *cmd) Help() string {
 
 const synopsis = `Helpers for CAs`
 const help = `
-Usage: consul tls ca <subcommand> [options] filename-prefix
+Usage: consul tls ca <subcommand> [options]
 
   This command has subcommands for interacting with Certificate Authorities.
 

command/tls/cert/tls_cert.go

@@ -1,8 +1,9 @@
 package cert
 
 import (
-	"github.com/hashicorp/consul/command/flags"
 	"github.com/mitchellh/cli"
+
+	"github.com/hashicorp/consul/command/flags"
 )
 
 func New() *cmd {
@@ -25,7 +26,7 @@ func (c *cmd) Help() string {
 
 const synopsis = `Helpers for certificates`
 const help = `
-Usage: consul tls cert <subcommand> [options] [filename-prefix]
+Usage: consul tls cert <subcommand> [options]
 
   This command has subcommands for interacting with certificates
 

website/content/commands/tls/ca.mdx

@@ -9,11 +9,11 @@ description: |
 
 Command: `consul tls ca create`
 
-This command create a self signed CA to be used for Consul TLS setup.
+This command creates a self-signed CA to be used for Consul TLS setup.
 
-## Example
+## Examples
 
-Create CA:
+Create a CA:
 
 ```shell-session
 $ consul tls ca create
@@ -21,9 +21,17 @@ $ consul tls ca create
 ==> Saved consul-ca-key.pem
 ```
 
+Create a CA that signs certificates exclusively for the example.com domain:
+
+```shell-session
+$ consul tls ca create -name-constraint -domain example.com
+==> Saved example.com-ca.pem
+==> Saved example.com-ca-key.pem
+```
+
 ## Usage
 
-Usage: `consul tls ca create [filename-prefix] [options]`
+Usage: `consul tls ca create [options]`
 
 #### Command Options
 
@@ -31,18 +39,17 @@ Usage: `consul tls ca create [filename-prefix] [options]`
   Results in rejecting certificates for other DNS than specified. Can be used
   multiple times. Only used in combination with `-name-constraint`.
 
-- `-days=<int>` - Provide number of days the CA is valid for from now on, defaults to 5 years.
+- `-days=<int>` - Number of days the CA is valid for. Defaults to 1825 days (approximately 5 years).
 
-- `-domain=<string>` - Domain of consul cluster. Only used in combination with
+- `-domain=<string>` - The DNS domain of the Consul cluster that agents are [configured](/consul/docs/agent/config/cli-flags#_domain) with.
-  `-name-constraint`. Defaults to `consul`.
+  Defaults to `consul`. Only used when `-name-constraint` is set.
+  Additional domains can be passed with `-additional-name-constraint`.
 
-- `-name-constraint` - Add name constraints for the CA. Results in rejecting
+- `-name-constraint` - Enables [X.509 name constraints](https://www.rfc-editor.org/rfc/rfc5280#page-40) for the CA.
-  certificates for other DNS than specified. If turned on localhost and -domain
+  If used, the CA only signs certificates for localhost and the domains specified by `-domain` and `-additional-name-constraint`.
-  will be added to the allowed DNS. If the UI is going to be served over HTTPS
+  If Consul's UI is served over HTTPS in your deployment, add its DNS name with `-additional-constraint` as well. Defaults to `false`.
-  its DNS has to be added with `-additional-constraint`. It is not possible to
-  add that after the fact! Defaults to false.
 
-- `cluster-id` - ClusterID of the consul cluster, requires `-domain` to be set as well.
+- `cluster-id` - ID of the Consul cluster. Sets the CA's URI with the SPIFFEID composed of the cluster ID and domain
-   When used this will cause URIs to be set with spiffeid.
+  (specified by `-domain` or `consul` by default).
 
 - `common-name` - Common Name of CA. Defaults to Consul Agent CA.