From 62df6a751346e07bbae16dbe03739e37f767aa6f Mon Sep 17 00:00:00 2001 From: Paul Glass Date: Wed, 14 Dec 2022 14:28:25 -0600 Subject: [PATCH] Deprecate -join and -join-wan (#15598) --- .changelog/15598.txt | 4 ++ agent/auto-config/auto_config_test.go | 12 ++-- agent/auto-config/auto_encrypt.go | 6 +- agent/auto-config/auto_encrypt_test.go | 17 +++-- agent/config/builder.go | 14 ++--- agent/config/builder_test.go | 24 ++++--- agent/config/config.go | 2 - agent/config/deprecated.go | 16 +++++ agent/config/flags.go | 24 ++++++- agent/config/flags_test.go | 40 ++++++------ agent/config/merge_test.go | 12 ++-- agent/config/runtime.go | 16 ----- agent/config/runtime_test.go | 46 ++++++++++---- .../TestRuntimeConfig_Sanitize.golden | 4 +- agent/retry_join.go | 6 +- command/agent/agent.go | 44 ------------- .../content/docs/agent/config/cli-flags.mdx | 63 +++++++------------ .../docs/agent/config/config-files.mdx | 16 ++--- .../wan-federation-via-mesh-gateways.mdx | 3 +- .../content/docs/enterprise/license/faq.mdx | 6 +- .../docs/enterprise/license/overview.mdx | 8 +-- .../docs/enterprise/network-segments.mdx | 3 +- .../content/docs/install/bootstrapping.mdx | 6 +- 23 files changed, 189 insertions(+), 203 deletions(-) create mode 100644 .changelog/15598.txt diff --git a/.changelog/15598.txt b/.changelog/15598.txt new file mode 100644 index 000000000..87a085405 --- /dev/null +++ b/.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. +``` diff --git a/agent/auto-config/auto_config_test.go b/agent/auto-config/auto_config_test.go index ea23fa049..e5047e8ef 100644 --- a/agent/auto-config/auto_config_test.go +++ b/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{ - DataDir: &dataDir, - Datacenter: stringPointer("dc1"), - NodeName: stringPointer("autoconf"), - BindAddr: stringPointer("127.0.0.1"), + FlagValues: config.FlagValuesTarget{ + Config: config.Config{ + DataDir: &dataDir, + Datacenter: stringPointer("dc1"), + NodeName: stringPointer("autoconf"), + BindAddr: stringPointer("127.0.0.1"), + }, }, } return &configLoader{opts: opts} diff --git a/agent/auto-config/auto_encrypt.go b/agent/auto-config/auto_encrypt.go index d42e25d47..8118d1312 100644 --- a/agent/auto-config/auto_encrypt.go +++ b/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 - // addresses. These are for joining serf and therefore we cannot rely on the + // The addresses we use for auto-encrypt are the retry join addresses. + // 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") { diff --git a/agent/auto-config/auto_encrypt_test.go b/agent/auto-config/auto_encrypt_test.go index 1bcd6bf9a..2036d7f20 100644 --- a/agent/auto-config/auto_encrypt_test.go +++ b/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"}, - StartJoinAddrsLAN: []string{"192.168.1.2:4321"}, + RetryJoinLAN: []string{"127.0.0.1:9876", "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"}, - StartJoinAddrsLAN: []string{"192.168.1.1:5432", "start.local", "[::ffff:172.16.5.4]", "main.dev:6789"}, + RetryJoinLAN: []string{ + "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", }, diff --git a/agent/config/builder.go b/agent/config/builder.go index a28ddab2a..ad0b050ba 100644 --- a/agent/config/builder.go +++ b/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'") } diff --git a/agent/config/builder_test.go b/agent/config/builder_test.go index 9ee6a7af2..1258dd8a6 100644 --- a/agent/config/builder_test.go +++ b/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{ - NodeName: pString(tc.nodeName), - DataDir: pString("dir"), + FlagValues: FlagValuesTarget{ + Config: Config{ + 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{ - NodeName: pString("foo"), - DataDir: pString("dir"), + FlagValues: FlagValuesTarget{ + Config: Config{ + 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{ - ClientAddr: tc.clientAddr, - DataDir: pString("dir"), + FlagValues: FlagValuesTarget{ + Config: Config{ + ClientAddr: tc.clientAddr, + DataDir: pString("dir"), + }, }, } patchLoadOptsShims(&opts) diff --git a/agent/config/config.go b/agent/config/config.go index 186ebb10a..d28b4c518 100644 --- a/agent/config/config.go +++ b/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"` diff --git a/agent/config/deprecated.go b/agent/config/deprecated.go index ab4365708..13fada24b 100644 --- a/agent/config/deprecated.go +++ b/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 diff --git a/agent/config/flags.go b/agent/config/flags.go index 44554bd5e..f6cb131d7 100644 --- a/agent/config/flags.go +++ b/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.StartJoinAddrsWAN, "join-wan", "Address of an agent to join -wan 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", "(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) +} diff --git a/agent/config/flags_test.go b/agent/config/flags_test.go index 5e1009450..ebefa6806 100644 --- a/agent/config/flags_test.go +++ b/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{ - "foo.local", "bar.local", - }}}, + expected: LoadOpts{ + FlagValues: FlagValuesTarget{ + Config: Config{ + PrimaryGateways: []string{"foo.local", "bar.local"}, + }, + }, + }, }, } diff --git a/agent/config/merge_test.go b/agent/config/merge_test.go index f10499303..4de92a24f 100644 --- a/agent/config/merge_test.go +++ b/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"}}, - {StartJoinAddrsLAN: []string{"b"}}, + {RetryJoinLAN: []string{"a"}}, + {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"), - RaftProtocol: pInt(2), - ServerMode: pBool(true), - StartJoinAddrsLAN: []string{"a", "b"}, + AdvertiseAddrLAN: pString("b"), + RaftProtocol: pInt(2), + ServerMode: pBool(true), + RetryJoinLAN: []string{"a", "b"}, NodeMeta: map[string]string{ "a": "b", "c": "e", diff --git a/agent/config/runtime.go b/agent/config/runtime.go index 6d31f0543..8ac3db142 100644 --- a/agent/config/runtime.go +++ b/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). // diff --git a/agent/config/runtime_test.go b/agent/config/runtime_test.go index 842cf16a0..71b843acc 100644 --- a/agent/config/runtime_test.go +++ b/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...) diff --git a/agent/config/testdata/TestRuntimeConfig_Sanitize.golden b/agent/config/testdata/TestRuntimeConfig_Sanitize.golden index a568789c5..7e4aeb665 100644 --- a/agent/config/testdata/TestRuntimeConfig_Sanitize.golden +++ b/agent/config/testdata/TestRuntimeConfig_Sanitize.golden @@ -370,8 +370,6 @@ ], "SessionTTLMin": "0s", "SkipLeaveOnInt": false, - "StartJoinAddrsLAN": [], - "StartJoinAddrsWAN": [], "StaticRuntimeConfig": { "EncryptVerifyIncoming": false, "EncryptVerifyOutgoing": false @@ -488,4 +486,4 @@ "VersionPrerelease": "", "Watches": [], "XDSUpdateRateLimit": 0 -} \ No newline at end of file +} diff --git a/agent/retry_join.go b/agent/retry_join.go index b3ebcf2a9..61825db23 100644 --- a/agent/retry_join.go +++ b/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 - // be set if wanfed is enabled so we don't have to emit any warnings - // related to that here. - + // Elsewhere we enforce that retry-join-wan cannot be set if wanfed is + // enabled so we don't have to emit any warnings 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 diff --git a/command/agent/agent.go b/command/agent/agent.go index 8b49a1da8..5c22b7403 100644 --- a/command/agent/agent.go +++ b/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() diff --git a/website/content/docs/agent/config/cli-flags.mdx b/website/content/docs/agent/config/cli-flags.mdx index f904f2170..6cf4f213a 100644 --- a/website/content/docs/agent/config/cli-flags.mdx +++ b/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. - This can be specified multiple times to specify multiple agents 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 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 - a Consul cluster deployment. +- `-retry-join` ((#\_retry_join)) - Address of another agent to join upon starting up. Joining is + retried until success. Once the agent joins successfully as a member, it will not attempt to join + again. After joining, the agent solely maintains its membership via gossip. This option can be + specified multiple times to specify multiple agents to join. By default, the agent won't join any + 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 - [go-sockaddr] - template that is resolved at runtime. + This supports [Cloud Auto-Joining](#cloud-auto-joining). - If using Enterprise network segments, see [additional documentation on - 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. + 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 - starting up. This can be specified multiple times to specify multiple WAN agents - 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. +- `-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.** + This is an alias of [`-retry-join-wan`](#_retry_join_wan) - In Consul 1.1.0 and later this can be dynamically defined with a [go-sockaddr] - template that is resolved at runtime. +- `-retry-join-wan` ((#\_retry_join_wan)) - Address of another WAN agent to join upon starting up. + 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) - 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. + This supports [Cloud Auto-Joining](#cloud-auto-joining). - In Consul 1.1.0 and later this can be dynamically defined with a [go-sockaddr] - template that is resolved at runtime. + This can be dynamically defined with a [go-sockaddr] 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. diff --git a/website/content/docs/agent/config/config-files.mdx b/website/content/docs/agent/config/config-files.mdx index f562d1605..f11c7c3e9 100644 --- a/website/content/docs/agent/config/config-files.mdx +++ b/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 - of nodes to [`-join`](/docs/agent/config/cli-flags#_join) upon startup. Note that using - `retry_join` could be more appropriate to help mitigate - node startup race conditions when automating a Consul cluster deployment. +- `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.** + This field is an alias of `retry_join`. -- `start_join_wan` An array of strings specifying addresses - of WAN nodes to [`-join-wan`](/docs/agent/config/cli-flags#_join_wan) upon startup. +- `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.** + 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`. - - - -[go-sockaddr]: https://godoc.org/github.com/hashicorp/go-sockaddr/template diff --git a/website/content/docs/connect/gateways/mesh-gateway/wan-federation-via-mesh-gateways.mdx b/website/content/docs/connect/gateways/mesh-gateway/wan-federation-via-mesh-gateways.mdx index 21c68d23a..a1a25414f 100644 --- a/website/content/docs/connect/gateways/mesh-gateway/wan-federation-via-mesh-gateways.mdx +++ b/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 -[`retry_join_wan`](/docs/agent/config/config-files#retry_join_wan) are +The [`retry_join_wan`](/docs/agent/config/config-files#retry_join_wan) addresses 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. diff --git a/website/content/docs/enterprise/license/faq.mdx b/website/content/docs/enterprise/license/faq.mdx index d051006b9..480d696ca 100644 --- a/website/content/docs/enterprise/license/faq.mdx +++ b/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 start/retry join addresses are addresses of the Consul servers. +- The client agents configuration contains `retry_join` addresses. +- 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? diff --git a/website/content/docs/enterprise/license/overview.mdx b/website/content/docs/enterprise/license/overview.mdx index 2528c11c6..2cb75961e 100644 --- a/website/content/docs/enterprise/license/overview.mdx +++ b/website/content/docs/enterprise/license/overview.mdx @@ -48,9 +48,9 @@ Virtual agents do not need the license to run. Updating the license for an agent depends on the method you used to apply the license. - **If you used the `CONSUL_LICENSE` -environment variable**: After updating the environment variable, restart the affected agents. +environment variable**: After updating the environment variable, restart the affected agents. - **If you used the -`CONSUL_LICENSE_PATH` environment variable**: Update the license file first. Then, restart the affected agents. +`CONSUL_LICENSE_PATH` environment variable**: Update the license file first. Then, restart the affected agents. - **If you used the `license_path` configuration item**: Update the license file first. Then, run [`consul reload`](/commands/reload) for the affected agents. #### Client Agent License Retrieval @@ -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) -or [`retry_join`](/docs/agent/config/config-files#retry_join) configurations. If those are both unset or no +actually joins the cluster, where to make those RPC requests to is inferred from the +[`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 diff --git a/website/content/docs/enterprise/network-segments.mdx b/website/content/docs/enterprise/network-segments.mdx index 0ae655549..ce419a09b 100644 --- a/website/content/docs/enterprise/network-segments.mdx +++ b/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 - [`start_join`](/docs/agent/config/config-files#start_join): A list of agent addresses to join +- [`retry_join`](/docs/agent/config/config-files#retry_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). diff --git a/website/content/docs/install/bootstrapping.mdx b/website/content/docs/install/bootstrapping.mdx index 88713ffc4..5efe4ad93 100644 --- a/website/content/docs/install/bootstrapping.mdx +++ b/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.