consul v1.0.0 Release Notes

Release Date: 2017-10-16 // over 6 years ago
  • ๐Ÿ”’ SECURITY:

    • ๐Ÿ’ป ui: Fixed an XSS issue with Consul's built-in web UI where node names were not being properly escaped. [GH-3578]

    ๐Ÿ’ฅ BREAKING CHANGES:

    • 0๏ธโƒฃ Raft Protocol Now Defaults to 3: The -raft-protocol default has been changed from 2 to 3, enabling all Autopilot features by default. Version 3 requires Consul running 0.8.0 or newer on all servers in order to work, so if you are upgrading with older servers in a cluster then you will need to set this back to 2 in order to upgrade. See Raft Protocol Version Compatibility for more details. Also the format of peers.json used for outage recovery is different when running with the lastest Raft protocol. See Manual Recovery Using peers.json for a description of the required format. [GH-3477]
    • Config Files Require an Extension: As part of supporting the HCL format for Consul's config files, an .hcl or .json extension is required for all config files loaded by Consul, even when using the -config-file argument to specify a file directly. [GH-3480]
    • ๐Ÿšš Deprecated Options Have Been Removed: All of Consul's previously deprecated command line flags and config options have been removed, so these will need to be mapped to their equivalents before upgrading. [GH-3480]

      Detailed List of Removed Options and their Equivalents

      Removed Option Equivalent
      -atlas None, Atlas is no longer supported.
      -atlas-token None, Atlas is no longer supported.
      -atlas-join None, Atlas is no longer supported.
      -atlas-endpoint None, Atlas is no longer supported.
      -dc -datacenter
      -retry-join-azure-tag-name -retry-join
      -retry-join-azure-tag-value -retry-join
      -retry-join-ec2-region -retry-join
      -retry-join-ec2-tag-key -retry-join
      -retry-join-ec2-tag-value -retry-join
      -retry-join-gce-credentials-file -retry-join
      -retry-join-gce-project-name -retry-join
      -retry-join-gce-tag-name -retry-join
      -retry-join-gce-zone-pattern -retry-join
      addresses.rpc None, the RPC server for CLI commands is no longer supported.
      advertise_addrs ports with advertise_addr and/or advertise_addr_wan
      atlas_infrastructure None, Atlas is no longer supported.
      atlas_token None, Atlas is no longer supported.
      atlas_acl_token None, Atlas is no longer supported.
      atlas_join None, Atlas is no longer supported.
      atlas_endpoint None, Atlas is no longer supported.
      dogstatsd_addr telemetry.dogstatsd_addr
      dogstatsd_tags telemetry.dogstatsd_tags
      http_api_response_headers http_config.response_headers
      ports.rpc None, the RPC server for CLI commands is no longer supported.
      recursor recursors
      retry_join_azure -retry-join
      retry_join_ec2 -retry-join
      retry_join_gce -retry-join
      statsd_addr telemetry.statsd_address
      statsite_addr telemetry.statsite_address
      statsite_prefix telemetry.metrics_prefix
      telemetry.statsite_prefix telemetry.metrics_prefix
      (service definitions) serviceid service_id
      (service definitions) dockercontainerid docker_container_id
      (service definitions) tlsskipverify tls_skip_verify
      (service definitions) deregistercriticalserviceafter deregister_critical_service_after
    • statsite_prefix Renamed to metrics_prefix: Since the statsite_prefix configuration option applied to all telemetry providers, statsite_prefix was renamed to metrics_prefix. Configuration files will need to be updated when upgrading to this version of Consul. [GH-3498]

    • advertise_addrs Removed: This configuration option was removed since it was redundant with advertise_addr and advertise_addr_wan in combination with ports and also wrongly stated that you could configure both host and port. [GH-3516]

    • Escaping Behavior Changed for go-discover Configs: The format for -retry-join and -retry-join-wan values that use go-discover Cloud auto joining has changed. Values in key=val sequences must no longer be URL encoded and can be provided as literals as long as they do not contain spaces, backslashes \ or double quotes ". If values contain these characters then use double quotes as in "some key"="some value". Special characters within a double quoted string can be escaped with a backslash \. [GH-3417]

    • HTTP Verbs are Enforced in Many HTTP APIs: Many endpoints in the HTTP API that previously took any HTTP verb now check for specific HTTP verbs and enforce them. This may break clients relying on the old behavior. [GH-3405]

      Detailed List of Updated Endpoints and Required HTTP Verbs

      Endpoint Required HTTP Verb
      /v1/acl/info GET
      /v1/acl/list GET
      /v1/acl/replication GET
      /v1/agent/check/deregister PUT
      /v1/agent/check/fail PUT
      /v1/agent/check/pass PUT
      /v1/agent/check/register PUT
      /v1/agent/check/warn PUT
      /v1/agent/checks GET
      /v1/agent/force-leave PUT
      /v1/agent/join PUT
      /v1/agent/members GET
      /v1/agent/metrics GET
      /v1/agent/self GET
      /v1/agent/service/register PUT
      /v1/agent/service/deregister PUT
      /v1/agent/services GET
      /v1/catalog/datacenters GET
      /v1/catalog/deregister PUT
      /v1/catalog/node GET
      /v1/catalog/nodes GET
      /v1/catalog/register PUT
      /v1/catalog/service GET
      /v1/catalog/services GET
      /v1/coordinate/datacenters GET
      /v1/coordinate/nodes GET
      /v1/health/checks GET
      /v1/health/node GET
      /v1/health/service GET
      /v1/health/state GET
      /v1/internal/ui/node GET
      /v1/internal/ui/nodes GET
      /v1/internal/ui/services GET
      /v1/session/info GET
      /v1/session/list GET
      /v1/session/node GET
      /v1/status/leader GET
      /v1/status/peers GET
      /v1/operator/area/:uuid/members GET
      /v1/operator/area/:uuid/join PUT
    • Unauthorized KV Requests Return 403: When ACLs are enabled, reading a key with an unauthorized token returns a 403. This previously returned a 404 response.

    • Config Section of Agent Self Endpoint has Changed: The /v1/agent/self endpoint's Config section has often been in flux as it was directly returning one of Consul's internal data structures. This configuration structure has been moved under DebugConfig, and is documents as for debugging use and subject to change, and a small set of elements of Config have been maintained and documented. See Read Configuration endpoint documentation for details. [GH-3532]

    • ๐Ÿšš Deprecated configtest Command Removed: The configtest command was deprecated and has been superseded by the validate command.

    • ๐Ÿšš Undocumented Flags in validate Command Removed: The validate command supported the -config-file and -config-dir command line flags but did not document them. This support has been removed since the flags are not required.

    • โšก๏ธ Metric Names Updated: Metric names no longer start with consul.consul. To help with transitioning dashboards and other metric consumers, the field enable_deprecated_names has been added to the telemetry section of the config, which will enable metrics with the old naming scheme to be sent alongside the new ones. [GH-3535]

      Detailed List of Affected Metrics by Prefix

      Prefix
      consul.consul.acl
      consul.consul.autopilot
      consul.consul.catalog
      consul.consul.fsm
      consul.consul.health
      consul.consul.http
      consul.consul.kvs
      consul.consul.leader
      consul.consul.prepared-query
      consul.consul.rpc
      consul.consul.session
      consul.consul.session_ttl
      consul.consul.txn
    • Checks Validated On Agent Startup: Consul agents now validate health check definitions in their configuration and will fail at startup if any checks are invalid. In previous versions of Consul, invalid health checks would get skipped. [GH-3559]

    ๐Ÿ”‹ FEATURES:

    • ๐Ÿ‘Œ Support for HCL Config Files: Consul now supports HashiCorp's HCL format for config files. This is easier to work with than JSON and supports comments. As part of this change, all config files will need to have either an .hcl or .json extension in order to specify their format. [GH-3480]
    • ๐Ÿ‘Œ Support for Binding to Multiple Addresses: Consul now supports binding to multiple addresses for its HTTP, HTTPS, and DNS services. You can provide a space-separated list of addresses to -client and addresses configurations, or specify a go-sockaddr template that resolves to multiple addresses. [GH-3480]
    • ๐Ÿ‘Œ Support for RFC1464 DNS TXT records: Consul DNS responses now contain the node meta data encoded according to RFC1464 as TXT records. [GH-3343]
    • ๐Ÿ‘Œ Support for Running Subproccesses Directly Without a Shell: Consul agent checks and watches now support an args configuration which is a list of arguments to run for the subprocess, which runs the subprocess directly without a shell. The old script and handler configurations are now deprecated (specify a shell explicitly if you require one). A -shell=false option is also available on consul lock, consul watch, and consul exec to run the subprocesses associated with those without a shell. [GH-3509]
    • Sentinel Integration: (Consul Enterprise) Consul's ACL system integrates with Sentinel to enable code policies that apply to KV writes.

    ๐Ÿ‘Œ IMPROVEMENTS:

    • ๐Ÿ‘ agent: Added support to detect public IPv4 and IPv6 addresses on AWS. [GH-3471]
    • ๐Ÿ”ง agent: Improved /v1/operator/raft/configuration endpoint which allows Consul to avoid an extra agent RPC call for the consul operator raft list-peers command. [GH-3449]
    • ๐Ÿ‘€ agent: Improved ACL system for the KV store to support list permissions. This behavior can be opted in. For more information, see the ACL Guide. [GH-3511]
    • โšก๏ธ agent: Updates miekg/dns library to later version to pick up bug fixes and improvements. [GH-3547]
    • ๐ŸŽ agent: Added automatic retries to the RPC path, and a brief RPC drain time when servers leave. These changes make Consul more robust during graceful leaves of Consul servers, such as during upgrades, and help shield applications from "no leader" errors. These are configured with new performance options. [GH-3514]
    • agent: Added a new discard_check_output agent-level configuration option that can be used to trade off write load to the Consul servers vs. visibility of health check output. This is reloadable so it can be toggled without fully restarting the agent. [GH-3562]
    • โšก๏ธ api: Updated the API client to ride out network errors when monitoring locks and semaphores. [GH-3553]
    • โšก๏ธ build: Updated Go toolchain to version 1.9.1. [GH-3537]
    • ๐Ÿ”’ cli: consul lock and consul watch commands will forward TERM and KILL signals to their child subprocess. [GH-3509]
    • ๐Ÿ“„ cli: Added support for autocompletion. [GH-3412]
    • โšก๏ธ server: Updated BoltDB to final version 1.3.1. [GH-3502]
    • server: Improved dead member reap algorithm to fix edge cases where servers could get left behind. [GH-3452]

    ๐Ÿ› BUG FIXES:

    • ๐Ÿ›  agent: Fixed an issue where disabling both the http and https interfaces would cause a watch-related error on agent startup, even when no watches were defined. [GH-3425]
    • ๐Ÿ agent: Added an additional step to kill health check scripts that timeout on all platforms except Windows, and added a wait so that it's not possible to run multiple instances of the same health check script at the same time. [GH-3565]
    • cli: If the consul operator raft list-peers command encounters an error it will now exit with a non-zero exit code. [GH-3513]
    • cli: CLI commands will now show help for all of their arguments. [GH-3536]
    • ๐Ÿ›  server: Fixed an issue where the leader server could get into a state where it was no longer performing the periodic leader loop duties and unable to serve consistent reads after a barrier timeout error. [GH-3545]