Deprecate -join and -join-wan (#15598)

.changelog/15598.txt

@@ -0,0 +1,4 @@
+```release-note:breaking-change
+config: Deprecate `-join`, `-join-wan`, `start_join`, and `start_join_wan`.
+These options are now aliases of `-retry-join`, `-retry-join-wan`, `retry_join`, and `retry_join_wan`, respectively.
+```

agent/auto-config/auto_config_test.go

@@ -201,11 +201,13 @@ func setupRuntimeConfig(t *testing.T) *configLoader {
 	dataDir := testutil.TempDir(t, "auto-config")
 
 	opts := config.LoadOpts{
-		FlagValues: config.Config{
+		FlagValues: config.FlagValuesTarget{
-			DataDir:    &dataDir,
+			Config: config.Config{
-			Datacenter: stringPointer("dc1"),
+				DataDir:    &dataDir,
-			NodeName:   stringPointer("autoconf"),
+				Datacenter: stringPointer("dc1"),
-			BindAddr:   stringPointer("127.0.0.1"),
+				NodeName:   stringPointer("autoconf"),
+				BindAddr:   stringPointer("127.0.0.1"),
+			},
 		},
 	}
 	return &configLoader{opts: opts}

agent/auto-config/auto_encrypt.go

@@ -84,11 +84,11 @@ func (ac *AutoConfig) joinHosts() ([]string, error) {
 
 	var addrs []string
 
-	// The addresses we use for auto-encrypt are the retry join and start join
+	// The addresses we use for auto-encrypt are the retry join addresses.
-	// addresses. These are for joining serf and therefore we cannot rely on the
+	// These are for joining serf and therefore we cannot rely on the
 	// ports for these. This loop strips any port that may have been specified and
 	// will let subsequent resolveAddr calls add on the default RPC port.
-	for _, addr := range append(ac.config.StartJoinAddrsLAN, hosts...) {
+	for _, addr := range hosts {
 		host, _, err := net.SplitHostPort(addr)
 		if err != nil {
 			if strings.Contains(err.Error(), "missing port in address") {

agent/auto-config/auto_encrypt_test.go

@@ -122,16 +122,23 @@ func TestAutoEncrypt_hosts(t *testing.T) {
 		"router-override": {
 			serverProvider: providerWithServer,
 			config: &config.RuntimeConfig{
-				RetryJoinLAN:      []string{"127.0.0.1:9876"},
+				RetryJoinLAN: []string{"127.0.0.1:9876", "192.168.1.2:4321"},
-				StartJoinAddrsLAN: []string{"192.168.1.2:4321"},
 			},
 			hosts: []string{"198.18.0.1:1234"},
 		},
 		"various-addresses": {
 			serverProvider: providerNone,
 			config: &config.RuntimeConfig{
-				RetryJoinLAN:      []string{"198.18.0.1", "foo.com", "[2001:db8::1234]:1234", "abc.local:9876"},
+				RetryJoinLAN: []string{
-				StartJoinAddrsLAN: []string{"192.168.1.1:5432", "start.local", "[::ffff:172.16.5.4]", "main.dev:6789"},
+					"192.168.1.1:5432",
+					"start.local",
+					"[::ffff:172.16.5.4]",
+					"main.dev:6789",
+					"198.18.0.1",
+					"foo.com",
+					"[2001:db8::1234]:1234",
+					"abc.local:9876",
+				},
 			},
 			hosts: []string{
 				"192.168.1.1",
@@ -147,7 +154,7 @@ func TestAutoEncrypt_hosts(t *testing.T) {
 		"split-host-port-error": {
 			serverProvider: providerNone,
 			config: &config.RuntimeConfig{
-				StartJoinAddrsLAN: []string{"this-is-not:a:ip:and_port"},
+				RetryJoinLAN: []string{"this-is-not:a:ip:and_port"},
 			},
 			err: "no auto-encrypt server addresses available for use",
 		},

agent/config/builder.go

@@ -46,11 +46,13 @@ import (
 	"github.com/hashicorp/consul/types"
 )
 
+type FlagValuesTarget = decodeTarget
+
 // LoadOpts used by Load to construct and validate a RuntimeConfig.
 type LoadOpts struct {
 	// FlagValues contains the command line arguments that can also be set
 	// in a config file.
-	FlagValues Config
+	FlagValues FlagValuesTarget
 
 	// ConfigFiles is a slice of paths to config files and directories that will
 	// be loaded.
@@ -169,12 +171,15 @@ func newBuilder(opts LoadOpts) (*builder, error) {
 		b.Head = append(b.Head, DevSource())
 	}
 
+	cfg, warns := applyDeprecatedFlags(&opts.FlagValues)
+	b.Warnings = append(b.Warnings, warns...)
+
 	// Since the merge logic is to overwrite all fields with later
 	// values except slices which are merged by appending later values
 	// we need to merge all slice values defined in flags before we
 	// merge the config files since the flag values for slices are
 	// otherwise appended instead of prepended.
-	slices, values := splitSlicesAndValues(opts.FlagValues)
+	slices, values := splitSlicesAndValues(cfg)
 	b.Head = append(b.Head, LiteralSource{Name: "flags.slices", Config: slices})
 	if opts.DefaultConfig != nil {
 		b.Head = append(b.Head, opts.DefaultConfig)
@@ -1072,8 +1077,6 @@ func (b *builder) build() (rt RuntimeConfig, err error) {
 		Services:                          services,
 		SessionTTLMin:                     b.durationVal("session_ttl_min", c.SessionTTLMin),
 		SkipLeaveOnInt:                    skipLeaveOnInt,
-		StartJoinAddrsLAN:                 b.expandAllOptionalAddrs("start_join", c.StartJoinAddrsLAN),
-		StartJoinAddrsWAN:                 b.expandAllOptionalAddrs("start_join_wan", c.StartJoinAddrsWAN),
 		TaggedAddresses:                   c.TaggedAddresses,
 		TranslateWANAddrs:                 boolVal(c.TranslateWANAddrs),
 		TxnMaxReqLen:                      uint64Val(c.Limits.TxnMaxReqLen),
@@ -1348,9 +1351,6 @@ func (b *builder) validate(rt RuntimeConfig) error {
 		return fmt.Errorf("'connect.enable_mesh_gateway_wan_federation = true' requires that 'node_name' not contain '/' characters")
 	}
 	if rt.ConnectMeshGatewayWANFederationEnabled {
-		if len(rt.StartJoinAddrsWAN) > 0 {
-			return fmt.Errorf("'start_join_wan' is incompatible with 'connect.enable_mesh_gateway_wan_federation = true'")
-		}
 		if len(rt.RetryJoinWAN) > 0 {
 			return fmt.Errorf("'retry_join_wan' is incompatible with 'connect.enable_mesh_gateway_wan_federation = true'")
 		}

agent/config/builder_test.go

@@ -138,9 +138,11 @@ func TestLoad_NodeName(t *testing.T) {
 
 	fn := func(t *testing.T, tc testCase) {
 		opts := LoadOpts{
-			FlagValues: Config{
+			FlagValues: FlagValuesTarget{
-				NodeName: pString(tc.nodeName),
+				Config: Config{
-				DataDir:  pString("dir"),
+					NodeName: pString(tc.nodeName),
+					DataDir:  pString("dir"),
+				},
 			},
 		}
 		patchLoadOptsShims(&opts)
@@ -178,9 +180,11 @@ func TestLoad_NodeName(t *testing.T) {
 func TestBuilder_unixPermissionsVal(t *testing.T) {
 
 	b, _ := newBuilder(LoadOpts{
-		FlagValues: Config{
+		FlagValues: FlagValuesTarget{
-			NodeName: pString("foo"),
+			Config: Config{
-			DataDir:  pString("dir"),
+				NodeName: pString("foo"),
+				DataDir:  pString("dir"),
+			},
 		},
 	})
 
@@ -259,9 +263,11 @@ func TestLoad_EmptyClientAddr(t *testing.T) {
 
 	fn := func(t *testing.T, tc testCase) {
 		opts := LoadOpts{
-			FlagValues: Config{
+			FlagValues: FlagValuesTarget{
-				ClientAddr: tc.clientAddr,
+				Config: Config{
-				DataDir:    pString("dir"),
+					ClientAddr: tc.clientAddr,
+					DataDir:    pString("dir"),
+				},
 			},
 		}
 		patchLoadOptsShims(&opts)

agent/config/config.go

@@ -230,8 +230,6 @@ type Config struct {
 	Services                         []ServiceDefinition `mapstructure:"services" json:"-"`
 	SessionTTLMin                    *string             `mapstructure:"session_ttl_min" json:"session_ttl_min,omitempty"`
 	SkipLeaveOnInt                   *bool               `mapstructure:"skip_leave_on_interrupt" json:"skip_leave_on_interrupt,omitempty"`
-	StartJoinAddrsLAN                []string            `mapstructure:"start_join" json:"start_join,omitempty"`
-	StartJoinAddrsWAN                []string            `mapstructure:"start_join_wan" json:"start_join_wan,omitempty"`
 	SyslogFacility                   *string             `mapstructure:"syslog_facility" json:"syslog_facility,omitempty"`
 	TLS                              TLS                 `mapstructure:"tls" json:"tls,omitempty"`
 	TaggedAddresses                  map[string]string   `mapstructure:"tagged_addresses" json:"tagged_addresses,omitempty"`

agent/config/deprecated.go

@@ -68,6 +68,12 @@ type DeprecatedConfig struct {
 
 	// DEPRECATED(TLS) - this isn't honored by crypto/tls anymore.
 	TLSPreferServerCipherSuites *bool `mapstructure:"tls_prefer_server_cipher_suites"`
+
+	// DEPRECATED(JOIN) - replaced by retry_join
+	StartJoinAddrsLAN []string `mapstructure:"start_join"`
+
+	// DEPRECATED(JOIN) - replaced by retry_join_wan
+	StartJoinAddrsWAN []string `mapstructure:"start_join_wan"`
 }
 
 func applyDeprecatedConfig(d *decodeTarget) (Config, []string) {
@@ -172,6 +178,16 @@ func applyDeprecatedConfig(d *decodeTarget) (Config, []string) {
 		warns = append(warns, deprecationWarning("acl_enable_key_list_policy", "acl.enable_key_list_policy"))
 	}
 
+	if len(dep.StartJoinAddrsLAN) > 0 {
+		d.Config.RetryJoinLAN = append(d.Config.RetryJoinLAN, dep.StartJoinAddrsLAN...)
+		warns = append(warns, deprecationWarning("start_join", "retry_join"))
+	}
+
+	if len(dep.StartJoinAddrsWAN) > 0 {
+		d.Config.RetryJoinWAN = append(d.Config.RetryJoinWAN, dep.StartJoinAddrsWAN...)
+		warns = append(warns, deprecationWarning("start_join_wan", "retry_join_wan"))
+	}
+
 	warns = append(warns, applyDeprecatedTLSConfig(dep, &d.Config)...)
 
 	return d.Config, warns

agent/config/flags.go

@@ -57,8 +57,8 @@ func AddFlags(fs *flag.FlagSet, f *LoadOpts) {
 	add(&f.FlagValues.Ports.GRPCTLS, "grpc-tls-port", "Sets the gRPC-TLS API port to listen on.")
 	add(&f.FlagValues.Ports.HTTP, "http-port", "Sets the HTTP API port to listen on.")
 	add(&f.FlagValues.Ports.HTTPS, "https-port", "Sets the HTTPS API port to listen on.")
-	add(&f.FlagValues.StartJoinAddrsLAN, "join", "Address of an agent to join at start time. Can be specified multiple times.")
+	add(&f.FlagValues.StartJoinAddrsLAN, "join", "(deprecated) An alias for -retry-join. The -join flag will be removed in a future release.")
-	add(&f.FlagValues.StartJoinAddrsWAN, "join-wan", "Address of an agent to join -wan at start time. Can be specified multiple times.")
+	add(&f.FlagValues.StartJoinAddrsWAN, "join-wan", "(deprecated) An alias for -retry-join-wan. The -join-wan flag will be removed in a future release.")
 	add(&f.FlagValues.LogLevel, "log-level", "Log level of the agent.")
 	add(&f.FlagValues.LogJSON, "log-json", "Output logs in JSON format.")
 	add(&f.FlagValues.LogFile, "log-file", "Path to the file the logs get written to")
@@ -98,3 +98,23 @@ func AddFlags(fs *flag.FlagSet, f *LoadOpts) {
 	add(&f.FlagValues.UIConfig.Dir, "ui-dir", "Path to directory containing the web UI resources.")
 	add(&f.HCL, "hcl", "hcl config fragment. Can be specified multiple times.")
 }
+
+func applyDeprecatedFlags(d *FlagValuesTarget) (Config, []string) {
+	dep := d.DeprecatedConfig
+
+	var warns []string
+	if len(dep.StartJoinAddrsLAN) > 0 {
+		d.Config.RetryJoinLAN = append(d.Config.RetryJoinLAN, dep.StartJoinAddrsLAN...)
+		warns = append(warns, deprecatedFlagWarning("-join", "-retry-join"))
+	}
+
+	if len(dep.StartJoinAddrsWAN) > 0 {
+		d.Config.RetryJoinWAN = append(d.Config.RetryJoinWAN, dep.StartJoinAddrsWAN...)
+		warns = append(warns, deprecatedFlagWarning("-join-wan", "-retry-join-wan"))
+	}
+	return d.Config, warns
+}
+
+func deprecatedFlagWarning(old, new string) string {
+	return fmt.Sprintf("The flag '%v' is deprecated. Use the '%v' flag instead.", old, new)
+}

agent/config/flags_test.go

@@ -21,19 +21,19 @@ func TestAddFlags_WithParse(t *testing.T) {
 		{},
 		{
 			args:     []string{`-bind`, `a`},
-			expected: LoadOpts{FlagValues: Config{BindAddr: pString("a")}},
+			expected: LoadOpts{FlagValues: FlagValuesTarget{Config: Config{BindAddr: pString("a")}}},
 		},
 		{
 			args:     []string{`-bootstrap`},
-			expected: LoadOpts{FlagValues: Config{Bootstrap: pBool(true)}},
+			expected: LoadOpts{FlagValues: FlagValuesTarget{Config: Config{Bootstrap: pBool(true)}}},
 		},
 		{
 			args:     []string{`-bootstrap=true`},
-			expected: LoadOpts{FlagValues: Config{Bootstrap: pBool(true)}},
+			expected: LoadOpts{FlagValues: FlagValuesTarget{Config: Config{Bootstrap: pBool(true)}}},
 		},
 		{
 			args:     []string{`-bootstrap=false`},
-			expected: LoadOpts{FlagValues: Config{Bootstrap: pBool(false)}},
+			expected: LoadOpts{FlagValues: FlagValuesTarget{Config: Config{Bootstrap: pBool(false)}}},
 		},
 		{
 			args:     []string{`-config-file`, `a`, `-config-dir`, `b`, `-config-file`, `c`, `-config-dir`, `d`},
@@ -41,54 +41,58 @@ func TestAddFlags_WithParse(t *testing.T) {
 		},
 		{
 			args:     []string{`-datacenter`, `a`},
-			expected: LoadOpts{FlagValues: Config{Datacenter: pString("a")}},
+			expected: LoadOpts{FlagValues: FlagValuesTarget{Config: Config{Datacenter: pString("a")}}},
 		},
 		{
 			args:     []string{`-dns-port`, `1`},
-			expected: LoadOpts{FlagValues: Config{Ports: Ports{DNS: pInt(1)}}},
+			expected: LoadOpts{FlagValues: FlagValuesTarget{Config: Config{Ports: Ports{DNS: pInt(1)}}}},
 		},
 		{
 			args:     []string{`-grpc-port`, `1`},
-			expected: LoadOpts{FlagValues: Config{Ports: Ports{GRPC: pInt(1)}}},
+			expected: LoadOpts{FlagValues: FlagValuesTarget{Config: Config{Ports: Ports{GRPC: pInt(1)}}}},
 		},
 		{
 			args:     []string{`-http-port`, `1`},
-			expected: LoadOpts{FlagValues: Config{Ports: Ports{HTTP: pInt(1)}}},
+			expected: LoadOpts{FlagValues: FlagValuesTarget{Config: Config{Ports: Ports{HTTP: pInt(1)}}}},
 		},
 		{
 			args:     []string{`-https-port`, `1`},
-			expected: LoadOpts{FlagValues: Config{Ports: Ports{HTTPS: pInt(1)}}},
+			expected: LoadOpts{FlagValues: FlagValuesTarget{Config: Config{Ports: Ports{HTTPS: pInt(1)}}}},
 		},
 		{
 			args:     []string{`-serf-lan-port`, `1`},
-			expected: LoadOpts{FlagValues: Config{Ports: Ports{SerfLAN: pInt(1)}}},
+			expected: LoadOpts{FlagValues: FlagValuesTarget{Config: Config{Ports: Ports{SerfLAN: pInt(1)}}}},
 		},
 		{
 			args:     []string{`-serf-wan-port`, `1`},
-			expected: LoadOpts{FlagValues: Config{Ports: Ports{SerfWAN: pInt(1)}}},
+			expected: LoadOpts{FlagValues: FlagValuesTarget{Config: Config{Ports: Ports{SerfWAN: pInt(1)}}}},
 		},
 		{
 			args:     []string{`-server-port`, `1`},
-			expected: LoadOpts{FlagValues: Config{Ports: Ports{Server: pInt(1)}}},
+			expected: LoadOpts{FlagValues: FlagValuesTarget{Config: Config{Ports: Ports{Server: pInt(1)}}}},
 		},
 		{
 			args:     []string{`-join`, `a`, `-join`, `b`},
-			expected: LoadOpts{FlagValues: Config{StartJoinAddrsLAN: []string{"a", "b"}}},
+			expected: LoadOpts{FlagValues: FlagValuesTarget{DeprecatedConfig: DeprecatedConfig{StartJoinAddrsLAN: []string{"a", "b"}}}},
 		},
 		{
 			args:     []string{`-node-meta`, `a:b`, `-node-meta`, `c:d`},
-			expected: LoadOpts{FlagValues: Config{NodeMeta: map[string]string{"a": "b", "c": "d"}}},
+			expected: LoadOpts{FlagValues: FlagValuesTarget{Config: Config{NodeMeta: map[string]string{"a": "b", "c": "d"}}}},
 		},
 		{
 			args:     []string{`-bootstrap`, `true`},
-			expected: LoadOpts{FlagValues: Config{Bootstrap: pBool(true)}},
+			expected: LoadOpts{FlagValues: FlagValuesTarget{Config: Config{Bootstrap: pBool(true)}}},
 			extra:    []string{"true"},
 		},
 		{
 			args: []string{`-primary-gateway`, `foo.local`, `-primary-gateway`, `bar.local`},
-			expected: LoadOpts{FlagValues: Config{PrimaryGateways: []string{
+			expected: LoadOpts{
-				"foo.local", "bar.local",
+				FlagValues: FlagValuesTarget{
-			}}},
+					Config: Config{
+						PrimaryGateways: []string{"foo.local", "bar.local"},
+					},
+				},
+			},
 		},
 	}
 

agent/config/merge_test.go

@@ -22,8 +22,8 @@ func TestMerge(t *testing.T) {
 				{RaftProtocol: pInt(2)},
 				{ServerMode: pBool(false)},
 				{ServerMode: pBool(true)},
-				{StartJoinAddrsLAN: []string{"a"}},
+				{RetryJoinLAN: []string{"a"}},
-				{StartJoinAddrsLAN: []string{"b"}},
+				{RetryJoinLAN: []string{"b"}},
 				{NodeMeta: map[string]string{"a": "b"}},
 				{NodeMeta: map[string]string{"c": "d"}},
 				{NodeMeta: map[string]string{"c": "e"}},
@@ -31,10 +31,10 @@ func TestMerge(t *testing.T) {
 				{Ports: Ports{DNS: pInt(2), HTTP: pInt(3)}},
 			},
 			Config{
-				AdvertiseAddrLAN:  pString("b"),
+				AdvertiseAddrLAN: pString("b"),
-				RaftProtocol:      pInt(2),
+				RaftProtocol:     pInt(2),
-				ServerMode:        pBool(true),
+				ServerMode:       pBool(true),
-				StartJoinAddrsLAN: []string{"a", "b"},
+				RetryJoinLAN:     []string{"a", "b"},
 				NodeMeta: map[string]string{
 					"a": "b",
 					"c": "e",

agent/config/runtime.go

@@ -1387,22 +1387,6 @@ type RuntimeConfig struct {
 	// hcl: auto_reload_config = (true|false)
 	AutoReloadConfig bool
 
-	// StartJoinAddrsLAN is a list of addresses to attempt to join -lan when the
-	// agent starts. If Serf is unable to communicate with any of these
-	// addresses, then the agent will error and exit.
-	//
-	// hcl: start_join = []string
-	// flag: -join string -join string
-	StartJoinAddrsLAN []string
-
-	// StartJoinWAN is a list of addresses to attempt to join -wan when the
-	// agent starts. If Serf is unable to communicate with any of these
-	// addresses, then the agent will error and exit.
-	//
-	// hcl: start_join_wan = []string
-	// flag: -join-wan string -join-wan string
-	StartJoinAddrsWAN []string
-
 	// TLS configures certificates, CA, cipher suites, and other TLS settings
 	// on Consul's listeners (i.e. Internal multiplexed RPC, HTTPS and gRPC).
 	//

agent/config/runtime_test.go

@@ -548,9 +548,12 @@ func TestLoad_IntegrationWithFlags(t *testing.T) {
 			`-data-dir=` + dataDir,
 		},
 		expected: func(rt *RuntimeConfig) {
-			rt.StartJoinAddrsLAN = []string{"a", "b"}
+			rt.RetryJoinLAN = []string{"a", "b"}
 			rt.DataDir = dataDir
 		},
+		expectedWarnings: []string{
+			deprecatedFlagWarning("-join", "-retry-join"),
+		},
 	})
 	run(t, testCase{
 		desc: "-join-wan",
@@ -560,9 +563,12 @@ func TestLoad_IntegrationWithFlags(t *testing.T) {
 			`-data-dir=` + dataDir,
 		},
 		expected: func(rt *RuntimeConfig) {
-			rt.StartJoinAddrsWAN = []string{"a", "b"}
+			rt.RetryJoinWAN = []string{"a", "b"}
 			rt.DataDir = dataDir
 		},
+		expectedWarnings: []string{
+			deprecatedFlagWarning("-join-wan", "-retry-join-wan"),
+		},
 	})
 	run(t, testCase{
 		desc: "-log-level",
@@ -1405,9 +1411,12 @@ func TestLoad_IntegrationWithFlags(t *testing.T) {
 		json: []string{`{ "start_join": ["{{ printf \"1.2.3.4 4.3.2.1\" }}"] }`},
 		hcl:  []string{`start_join = ["{{ printf \"1.2.3.4 4.3.2.1\" }}"]`},
 		expected: func(rt *RuntimeConfig) {
-			rt.StartJoinAddrsLAN = []string{"1.2.3.4", "4.3.2.1"}
+			rt.RetryJoinLAN = []string{"1.2.3.4", "4.3.2.1"}
 			rt.DataDir = dataDir
 		},
+		expectedWarnings: []string{
+			deprecationWarning("start_join", "retry_join"),
+		},
 	})
 	run(t, testCase{
 		desc: "start_join_wan address template",
@@ -1415,9 +1424,12 @@ func TestLoad_IntegrationWithFlags(t *testing.T) {
 		json: []string{`{ "start_join_wan": ["{{ printf \"1.2.3.4 4.3.2.1\" }}"] }`},
 		hcl:  []string{`start_join_wan = ["{{ printf \"1.2.3.4 4.3.2.1\" }}"]`},
 		expected: func(rt *RuntimeConfig) {
-			rt.StartJoinAddrsWAN = []string{"1.2.3.4", "4.3.2.1"}
+			rt.RetryJoinWAN = []string{"1.2.3.4", "4.3.2.1"}
 			rt.DataDir = dataDir
 		},
+		expectedWarnings: []string{
+			deprecationWarning("start_join_wan", "retry_join_wan"),
+		},
 	})
 	run(t, testCase{
 		desc: "retry_join address template",
@@ -1514,10 +1526,15 @@ func TestLoad_IntegrationWithFlags(t *testing.T) {
 			rt.BootstrapExpect = 0
 			rt.Datacenter = "b"
 			rt.PrimaryDatacenter = "b"
-			rt.StartJoinAddrsLAN = []string{"a", "b", "c", "d"}
+			rt.RetryJoinLAN = []string{"a", "b", "c", "d"}
 			rt.NodeMeta = map[string]string{"a": "c"}
 			rt.DataDir = dataDir
 		},
+		expectedWarnings: []string{
+			// TODO: deduplicate warnings?
+			deprecationWarning("start_join", "retry_join"),
+			deprecationWarning("start_join", "retry_join"),
+		},
 	})
 	run(t, testCase{
 		desc: "precedence: flag before file",
@@ -1573,7 +1590,7 @@ func TestLoad_IntegrationWithFlags(t *testing.T) {
 			rt.NodeMeta = map[string]string{"a": "c"}
 			rt.SerfBindAddrLAN = tcpAddr("3.3.3.3:8301")
 			rt.SerfBindAddrWAN = tcpAddr("4.4.4.4:8302")
-			rt.StartJoinAddrsLAN = []string{"c", "d", "a", "b"}
+			rt.RetryJoinLAN = []string{"c", "d", "a", "b"}
 			rt.TaggedAddresses = map[string]string{
 				"lan":      "1.1.1.1",
 				"lan_ipv4": "1.1.1.1",
@@ -1582,6 +1599,10 @@ func TestLoad_IntegrationWithFlags(t *testing.T) {
 			}
 			rt.DataDir = dataDir
 		},
+		expectedWarnings: []string{
+			deprecatedFlagWarning("-join", "-retry-join"),
+			deprecationWarning("start_join", "retry_join"),
+		},
 	})
 
 	// ------------------------------------------------------------
@@ -3544,7 +3565,10 @@ func TestLoad_IntegrationWithFlags(t *testing.T) {
 			    enable_mesh_gateway_wan_federation = true
 			  }
 			`},
-		expectedErr: "'start_join_wan' is incompatible with 'connect.enable_mesh_gateway_wan_federation = true'",
+		expectedErr: "'retry_join_wan' is incompatible with 'connect.enable_mesh_gateway_wan_federation = true'",
+		expectedWarnings: []string{
+			deprecatedFlagWarning("-join-wan", "-retry-join-wan"),
+		},
 	})
 	run(t, testCase{
 		desc: "connect.enable_mesh_gateway_wan_federation cannot use -retry-join-wan",
@@ -6174,10 +6198,10 @@ func TestLoad_FullConfig(t *testing.T) {
 		RejoinAfterLeave:        true,
 		RetryJoinIntervalLAN:    8067 * time.Second,
 		RetryJoinIntervalWAN:    28866 * time.Second,
-		RetryJoinLAN:            []string{"pbsSFY7U", "l0qLtWij"},
+		RetryJoinLAN:            []string{"pbsSFY7U", "l0qLtWij", "LR3hGDoG", "MwVpZ4Up"},
 		RetryJoinMaxAttemptsLAN: 913,
 		RetryJoinMaxAttemptsWAN: 23160,
-		RetryJoinWAN:            []string{"PFsR02Ye", "rJdQIhER"},
+		RetryJoinWAN:            []string{"PFsR02Ye", "rJdQIhER", "EbFSc3nA", "kwXTh623"},
 		RPCConfig:               consul.RPCConfig{EnableStreaming: true},
 		SegmentLimit:            123,
 		SerfPortLAN:             8301,
@@ -6491,8 +6515,6 @@ func TestLoad_FullConfig(t *testing.T) {
 		SerfAllowedCIDRsWAN:  []net.IPNet{},
 		SessionTTLMin:        26627 * time.Second,
 		SkipLeaveOnInt:       true,
-		StartJoinAddrsLAN:    []string{"LR3hGDoG", "MwVpZ4Up"},
-		StartJoinAddrsWAN:    []string{"EbFSc3nA", "kwXTh623"},
 		Telemetry: lib.TelemetryConfig{
 			CirconusAPIApp:                     "p4QOTe9j",
 			CirconusAPIToken:                   "E3j35V23",
@@ -6638,6 +6660,8 @@ func TestLoad_FullConfig(t *testing.T) {
 		deprecationWarning("verify_outgoing", "tls.defaults.verify_outgoing"),
 		deprecationWarning("verify_server_hostname", "tls.internal_rpc.verify_server_hostname"),
 		"The 'tls_prefer_server_cipher_suites' field is deprecated and will be ignored.",
+		deprecationWarning("start_join", "retry_join"),
+		deprecationWarning("start_join_wan", "retry_join_wan"),
 	}
 	expectedWarns = append(expectedWarns, enterpriseConfigKeyWarnings...)
 

agent/config/testdata/TestRuntimeConfig_Sanitize.golden

@@ -370,8 +370,6 @@
     ],
     "SessionTTLMin": "0s",
     "SkipLeaveOnInt": false,
-    "StartJoinAddrsLAN": [],
-    "StartJoinAddrsWAN": [],
     "StaticRuntimeConfig": {
         "EncryptVerifyIncoming": false,
         "EncryptVerifyOutgoing": false

agent/retry_join.go

@@ -47,10 +47,8 @@ func (a *Agent) retryJoinWAN() {
 		// completely hijack whatever the user configured to correctly
 		// implement the star-join.
 		//
-		// Elsewhere we enforce that start-join-wan and retry-join-wan cannot
+		// Elsewhere we enforce that retry-join-wan cannot be set if wanfed is
-		// be set if wanfed is enabled so we don't have to emit any warnings
+		// enabled so we don't have to emit any warnings related to that here.
-		// related to that here.
-
 		if isPrimary {
 			// Wanfed requires that secondaries join TO the primary and the
 			// primary doesn't explicitly join down to the secondaries, so as

command/agent/agent.go

@@ -116,40 +116,6 @@ func (c *cmd) startupUpdateCheck(config *config.RuntimeConfig) {
 	}()
 }
 
-// startupJoin is invoked to handle any joins specified to take place at start time
-func (c *cmd) startupJoin(agent *agent.Agent, cfg *config.RuntimeConfig) error {
-	if len(cfg.StartJoinAddrsLAN) == 0 {
-		return nil
-	}
-
-	c.logger.Info("Joining cluster")
-	// NOTE: For partitioned servers you are only capable of using start join
-	// to join nodes in the default partition.
-	n, err := agent.JoinLAN(cfg.StartJoinAddrsLAN, agent.AgentEnterpriseMeta())
-	if err != nil {
-		return err
-	}
-
-	c.logger.Info("Join completed. Initial agents synced with", "agent_count", n)
-	return nil
-}
-
-// startupJoinWan is invoked to handle any joins -wan specified to take place at start time
-func (c *cmd) startupJoinWan(agent *agent.Agent, cfg *config.RuntimeConfig) error {
-	if len(cfg.StartJoinAddrsWAN) == 0 {
-		return nil
-	}
-
-	c.logger.Info("Joining wan cluster")
-	n, err := agent.JoinWAN(cfg.StartJoinAddrsWAN)
-	if err != nil {
-		return err
-	}
-
-	c.logger.Info("Join wan completed. Initial agents synced with", "agent_count", n)
-	return nil
-}
-
 func (c *cmd) run(args []string) int {
 	ui := &mcli.PrefixedUi{
 		OutputPrefix: "==> ",
@@ -273,16 +239,6 @@ func (c *cmd) run(args []string) int {
 		c.startupUpdateCheck(config)
 	}
 
-	if err := c.startupJoin(agent, config); err != nil {
-		c.logger.Error(err.Error())
-		return 1
-	}
-
-	if err := c.startupJoinWan(agent, config); err != nil {
-		c.logger.Error(err.Error())
-		return 1
-	}
-
 	// Let the agent know we've finished registration
 	agent.StartSync()
 

website/content/docs/agent/config/cli-flags.mdx

@@ -306,34 +306,20 @@ information.
   server. This option may be provided multiple times, and is functionally equivalent
   to the [`recursors` configuration option](/docs/agent/config/config-files#recursors).
 
-## Join Options
+- `-join` ((#\_join)) - **Deprecated in Consul 1.15. This flag will be removed in a future version of Consul. Use the `-retry-join` flag instead.**
+  This is an alias of [`-retry-join`](#_retry_join).
 
-- `-join` ((#\_join)) - Address of another agent to join upon starting up.
+- `-retry-join` ((#\_retry_join)) - Address of another agent to join upon starting up. Joining is
-  This can be specified multiple times to specify multiple agents to join. If Consul
+  retried until success. Once the agent joins successfully as a member, it will not attempt to join
-  is unable to join with any of the specified addresses, agent startup will fail.
+  again. After joining, the agent solely maintains its membership via gossip. This option can be
-  By default, the agent won't join any nodes when it starts up. Note that using [`-retry-join`](#_retry_join) could be more appropriate to help mitigate node startup race conditions when automating
+  specified multiple times to specify multiple agents to join. By default, the agent won't join any
-  a Consul cluster deployment.
+  nodes when it starts up. The value can contain IPv4, IPv6, or DNS addresses. Literal IPv6
+  addresses must be enclosed in square brackets. If multiple values are given, they are tried and
+  retried in the order listed until the first succeeds.
 
-  In Consul 1.1.0 and later this can be dynamically defined with a
+  This supports [Cloud Auto-Joining](#cloud-auto-joining).
-  [go-sockaddr]
-  template that is resolved at runtime.
 
-  If using Enterprise network segments, see [additional documentation on
+  This can be dynamically defined with a [go-sockaddr] template that is resolved at runtime.
-  joining a client to a segment](/docs/enterprise/network-segments#join_a_client_to_a_segment).
-
-- `-retry-join` ((#\_retry_join)) - Similar to [`-join`](#_join) but allows retrying a join until
-  it is successful. Once it joins successfully to a member in a list of members
-  it will never attempt to join again. Agents will then solely maintain their
-  membership via gossip. This is useful for cases where you know the address will
-  eventually be available. This option can be specified multiple times to
-  specify multiple agents to join. The value can contain IPv4, IPv6, or DNS
-  addresses. IPv6 must use the "bracketed" syntax. If multiple values
-  are given, they are tried and retried in the order listed until the first
-  succeeds.
-
-  In Consul 1.1.0 and later this can be dynamically defined with a
-  [go-sockaddr]
-  template that is resolved at runtime.
 
   If Consul is running on the non-default Serf LAN port, the port must
   be specified in the join address, or configured as the agent's default Serf port
@@ -387,7 +373,7 @@ information.
 
   ### Cloud Auto-Joining
 
-  As of Consul 0.9.1, `retry-join` accepts a unified interface using the
+  The `-retry-join` option accepts a unified interface using the
   [go-discover](https://github.com/hashicorp/go-discover) library for doing
   automatic cluster joining using cloud metadata. For more information, see
   the [Cloud Auto-join page](/docs/install/cloud-auto-join).
@@ -407,22 +393,17 @@ information.
   [`-retry-join`](#_retry_join) before exiting with return code 1. By default, this is set
   to 0 which is interpreted as infinite retries.
 
-- `-join-wan` ((#\_join_wan)) - Address of another wan agent to join upon
+- `-join-wan` ((#\_join_wan)) - **Deprecated in Consul 1.15. This flag will be removed in a future version of Consul. Use the `-retry-join-wan` flag instead.**
-  starting up. This can be specified multiple times to specify multiple WAN agents
+  This is an alias of [`-retry-join-wan`](#_retry_join_wan)
-  to join. If Consul is unable to join with any of the specified addresses, agent
-  startup will fail. By default, the agent won't [`-join-wan`](#_join_wan) any nodes
-  when it starts up.
 
-  In Consul 1.1.0 and later this can be dynamically defined with a [go-sockaddr]
+- `-retry-join-wan` ((#\_retry_join_wan)) - Address of another WAN agent to join upon starting up.
-  template that is resolved at runtime.
+  WAN joining is retried until success. This can be specified multiple times to specify multiple WAN
+  agents to join. If multiple values are given, they are tried and retried in the order listed
+  until the first succeeds. By default, the agent won't WAN join any nodes when it starts up.
 
-- `-retry-join-wan` ((#\_retry_join_wan)) - Similar to [`-retry-join`](#_retry_join)
+  This supports [Cloud Auto-Joining](#cloud-auto-joining).
-  but allows retrying a wan join if the first attempt fails. This is useful for cases
-  where we know the address will become available eventually. As of Consul 0.9.3
-  [Cloud Auto-Joining](#cloud-auto-joining) is supported as well.
 
-  In Consul 1.1.0 and later this can be dynamically defined with a [go-sockaddr]
+  This can be dynamically defined with a [go-sockaddr] template that is resolved at runtime.
-  template that is resolved at runtime.
 
 - `-primary-gateway` ((#\_primary_gateway)) - Similar to [`-retry-join-wan`](#_retry_join_wan)
   but allows retrying discovery of fallback addresses for the mesh gateways in the
@@ -432,9 +413,9 @@ information.
   templates. This was added in Consul 1.8.0.
 
 - `-retry-interval-wan` ((#\_retry_interval_wan)) - Time to wait between
-  [`-join-wan`](#_join_wan) attempts. Defaults to 30s.
+  [`-retry-join-wan`](#_retry_join_wan) attempts. Defaults to 30s.
 
-- `-retry-max-wan` ((#\_retry_max_wan)) - The maximum number of [`-join-wan`](#_join_wan)
+- `-retry-max-wan` ((#\_retry_max_wan)) - The maximum number of [`-retry-join-wan`](#_join_wan)
   attempts to be made before exiting with return code 1. By default, this is set
   to 0 which is interpreted as infinite retries.
 

website/content/docs/agent/config/config-files.mdx

@@ -1369,7 +1369,7 @@ Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'."
 
   - `tls` (Defaults to `false`) Allows the client to request the
     Connect CA and certificates from the servers, for encrypting RPC communication.
-    The client will make the request to any servers listed in the `-join` or `-retry-join`
+    The client will make the request to any servers listed in the `-retry-join`
     option. This requires that every server to have `auto_encrypt.allow_tls` enabled.
     When both `auto_encrypt` options are used, it allows clients to receive certificates
     that are generated on the servers. If the `-server-port` is not the default one,
@@ -1508,13 +1508,11 @@ Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'."
 
 - `retry_interval_wan` Equivalent to the [`-retry-interval-wan` command-line flag](/docs/agent/config/cli-flags#_retry_interval_wan).
 
-- `start_join` An array of strings specifying addresses
+- `start_join` **Deprecated in Consul 1.15. Use the [`retry_join`](/docs/agent/config/config-files#retry_join) field instead. This field will be removed in a future version of Consul.**
-  of nodes to [`-join`](/docs/agent/config/cli-flags#_join) upon startup. Note that using
+  This field is an alias of `retry_join`.
-  `retry_join` could be more appropriate to help mitigate
-  node startup race conditions when automating a Consul cluster deployment.
 
-- `start_join_wan` An array of strings specifying addresses
+- `start_join_wan` **Deprecated in Consul 1.15. Use the [`retry_join_wan`](/docs/agent/config/config-files#retry_join_wan) field instead. This field will be removed in a future version of Consul.**
-  of WAN nodes to [`-join-wan`](/docs/agent/config/cli-flags#_join_wan) upon startup.
+  This field is an alias of `retry_join_wan`.
 
 ## Log Parameters
 
@@ -2219,7 +2217,3 @@ server.
     The default value is `250`. It is based on a load test of 5,000 streams connected to a single server with two CPU cores.
 
     If necessary, you can lower or increase the limit without a rolling restart by using the `consul reload` command or by sending the server a `SIGHUP`.
-
-<!-- list of reference-style links -->
-
-[go-sockaddr]: https://godoc.org/github.com/hashicorp/go-sockaddr/template

website/content/docs/connect/gateways/mesh-gateway/wan-federation-via-mesh-gateways.mdx

@@ -126,8 +126,7 @@ connect {
 }
 ```
 
-The [`start_join_wan`](/docs/agent/config/config-files#start_join_wan) or
+The [`retry_join_wan`](/docs/agent/config/config-files#retry_join_wan) addresses are
-[`retry_join_wan`](/docs/agent/config/config-files#retry_join_wan) are
 only used for the [traditional federation process](/docs/k8s/deployment-configurations/multi-cluster#traditional-wan-federation).
 They must be omitted when federating Consul servers via gateways.
 

website/content/docs/enterprise/license/faq.mdx

@@ -92,10 +92,10 @@ Consul client agents will attempt to retrieve the license from servers if certai
 
 - ACLs are enabled.
 - An ACL token is provided to the client agent.
-- The client agents configuration contains `start_join/retry_join` addresses.
+- The client agents configuration contains `retry_join` addresses.
-- The start/retry join addresses are addresses of the Consul servers.
+- The retry join addresses are addresses of the Consul servers.
 
-Consul snapshot agents will attempt to retrieve the license from servers if certain conditions are met: ACLs are enabled, a ACL token is provided to the client agent, the client agents configuration contains `start_join/retry_join` addresses, the start/retry join addresses are addresses of the Consul servers.
+Consul snapshot agents will attempt to retrieve the license from servers if certain conditions are met: ACLs are enabled, a ACL token is provided to the client agent, the client agents configuration contains `retry_join` addresses, the retry join addresses are addresses of the Consul servers.
 
 ## Q: Where can users get a trial license for Consul Enterprise?
 

website/content/docs/enterprise/license/overview.mdx

@@ -58,8 +58,8 @@ environment variable**: After updating the environment variable, restart the aff
 When a client agent starts without a license in its configuration or environment, it will try to retrieve the
 license from the servers via RPCs. That RPC always requires a valid non-anonymous ACL token to authorize the
 request but the token doesn't need any particular permissions. As the license is required before the client
-actually joins the cluster, where to make those RPC requests to is inferred from the [`start_join`](/docs/agent/config/config-files#start_join)
+actually joins the cluster, where to make those RPC requests to is inferred from the
-or [`retry_join`](/docs/agent/config/config-files#retry_join) configurations. If those are both unset or no
+[`retry_join`](/docs/agent/config/config-files#retry_join) configuration. If `retry_join` is unset or no
 [`agent` token](/docs/agent/config/config-files#acl_tokens_agent) is set then the client agent will immediately shut itself down.
 
 If all preliminary checks pass the client agent will attempt to reach out to any server on its RPC port to

website/content/docs/enterprise/network-segments.mdx

@@ -230,7 +230,6 @@ segments are:
 - [`ports.serf_lan`](/docs/agent/config/config-files#serf_lan_port):
   Serf LAN port for the above segment on this client. This is not required
   to match the configured Serf LAN port for other agents on this segment.
-- [`retry_join`](/docs/agent/config/config-files#retry_join) or
+- [`retry_join`](/docs/agent/config/config-files#retry_join): A list of agent addresses to join
-  [`start_join`](/docs/agent/config/config-files#start_join): A list of agent addresses to join
   when starting. Ensure the correct Serf LAN port for this segment is used when joining
   the LAN gossip pool using one of the [available configuration methods](#join_a_client_to_a_segment).

website/content/docs/install/bootstrapping.mdx

@@ -54,12 +54,8 @@ You can trigger leader election by joining the servers together, to create a clu
 
 ### Automatically Join the Servers
 
-There are multiple options for joining the servers. Choose the method which best suits your environment and specific use case.
+There are two options for joining the servers. Choose the method which best suits your environment and specific use case.
 
-- Specify a list of servers with
-  [-join](/docs/agent/config/cli-flags#_join) and
-  [start_join](/docs/agent/config/config-files#start_join)
-  options.
 - Specify a list of servers with [-retry-join](/docs/agent/config/cli-flags#_retry_join) option.
 - Use automatic joining by tag for supported cloud environments with the [-retry-join](/docs/agent/config/cli-flags#_retry_join) option.