Backport of docs: Search Description Refresh into release/1.11.x (#14648

) * no-op commit due to failed cherry-picking * Merge pull request #14643 from hashicorp/docs/search-metadata-headers Cherrypick merge docs: Search Description Refresh Co-authored-by: temp <[email protected]> Co-authored-by: Jeff Boruszak <[email protected]>
hashicorp · Sep 15, 2022 · 3583279 · 3583279
1 parent 5bb87c0
commit 3583279
Show file tree

Hide file tree

Showing 137 changed files with 1,969 additions and 516 deletions.
diff --git a/website/content/docs/agent/config-entries.mdx b/website/content/docs/agent/config-entries.mdx
@@ -1,12 +1,11 @@
 ---
 layout: docs
-page_title: Configuration Entries
+page_title: How to Use Configuration Entries
 description: >-
-  Consul allows storing configuration entries centrally to be used as defaults
-  for configuring other aspects of Consul.
+Configuration entries define the behavior of Consul service mesh components. Learn how to use the `consul config` command to create, manage, and delete configuration entries.
 ---
 
-# Configuration Entries
+# How to Use Configuration Entries
 
 Configuration entries can be created to provide cluster-wide defaults for
 various aspects of Consul.

diff --git a/website/content/docs/agent/config/cli-flags.mdx b/website/content/docs/agent/config/cli-flags.mdx
diff --git a/website/content/docs/agent/config/index.mdx b/website/content/docs/agent/config/index.mdx
@@ -0,0 +1,91 @@
+---
+layout: docs
+page_title: Agents: Configuration Explained
+description: >-
+Agent configuration is the process of defining server and client agent properties with CLI flags and configuration files. Learn what properties can be configured on reload and how Consul sets precedence for configuration settings.
+---
+
+# Agent Configuration
+
+The agent has various configuration options that can be specified via
+the command-line or via configuration files. All of the configuration
+options are completely optional. Defaults are specified with their
+descriptions.
+
+Configuration precedence is evaluated in the following order:
+
+1. [Command line arguments](/docs/agent/config/cli-flags)
+2. [Configuration files](/docs/agent/config/config-files)
+
+When loading configuration, the Consul agent loads the configuration from files and
+directories in lexical order. For example, configuration file
+`basic_config.json` will be processed before `extra_config.json`. Configuration
+can be in either [HCL](https://github.com/hashicorp/hcl#syntax) or JSON format.
+Available in Consul 1.0 and later, the HCL support now requires an `.hcl` or
+`.json` extension on all configuration files in order to specify their format.
+
+Configuration specified later will be merged into configuration specified
+earlier. In most cases, "merge" means that the later version will override the
+earlier. In some cases, such as event handlers, merging appends the handlers to
+the existing configuration. The exact merging behavior is specified for each
+option below.
+
+The Consul agent also supports reloading configuration when it receives the
+SIGHUP signal. Not all changes are respected, but those that are
+documented below in the
+[Reloadable Configuration](#reloadable-configuration) section. The
+[reload command](/commands/reload) can also be used to trigger a
+configuration reload.
+
+You can test the following configuration options by following the
+[Getting Started](https://learn.hashicorp.com/tutorials/consul/get-started-install?utm_source=docs)
+tutorials to install a local agent.
+
+## Ports Used
+
+Consul requires up to 6 different ports to work properly, some on
+TCP, UDP, or both protocols.
+
+Review the [required ports](/docs/install/ports) table for a list of
+required ports and their default settings.
+
+## Reloadable Configuration
+
+Reloading configuration does not reload all configuration items. The
+items which are reloaded include:
+
+- ACL Tokens
+- [Configuration Entry Bootstrap](/docs/agent/config/config-files#config_entries_bootstrap)
+- Checks
+- [Discard Check Output](/docs/agent/config/config-files#discard_check_output)
+- HTTP Client Address
+- Log level
+- [Metric Prefix Filter](/docs/agent/config/config-files#telemetry-prefix_filter)
+- [Node Metadata](/docs/agent/config/config-files#node_meta)
+- Some Raft options (since Consul 1.10.0)
+  - [`raft_snapshot_threshold`](/docs/agent/config/config-files#_raft_snapshot_threshold)
+  - [`raft_snapshot_interval`](/docs/agent/config/config-files#_raft_snapshot_interval)
+  - [`raft_trailing_logs`](/docs/agent/config/config-files#_raft_trailing_logs)
+  - These can be important in certain outage situations so being able to control
+    them without a restart provides a recovery path that doesn't involve
+    downtime. They generally shouldn't be changed otherwise.
+- [RPC rate limiting](/docs/agent/config/config-files#limits)
+- [HTTP Maximum Connections per Client](/docs/agent/config/config-files#http_max_conns_per_client)
+- Services
+- TLS Configuration
+  - Please be aware that this is currently limited to reload a configuration that is already TLS enabled. You cannot enable or disable TLS only with reloading.
+  - To avoid a potential security issue, the following TLS configuration parameters do not automatically reload when [-auto-reload-config](/docs/agent/config/cli-flags#_auto_reload_config) is enabled:
+    - [encrypt_verify_incoming](/docs/agent/config/config-files#encrypt_verify_incoming)
+    - [verify_incoming](/docs/agent/config/config-files#verify_incoming)
+    - [verify_incoming_rpc](/docs/agent/config/config-files#verify_incoming_rpc)
+    - [verify_incoming_https](/docs/agent/config/config-files#verify_incoming_https)
+    - [verify_outgoing](/docs/agent/config/config-files#verify_outgoing)
+    - [verify_server_hostname](/docs/agent/config/config-files#verify_server_hostname)
+    - [ca_file](/docs/agent/config/config-files#ca_file)
+    - [ca_path](/docs/agent/config/config-files#ca_path)
+
+    If any of those configurations are changed while [-auto-reload-config](/docs/agent/config/cli-flags#_auto_reload_config) is enabled,
+    Consul will issue the following warning, `Static Runtime config has changed and need a manual config reload to be applied`.
+    You must manually issue the `consul reload` command or send a `SIGHUP` to the Consul process to reload the new values.
+- Watches
+- [License](/docs/enterprise/license/overview)
diff --git a/website/content/docs/agent/index.mdx b/website/content/docs/agent/index.mdx
@@ -1,13 +1,11 @@
 ---
 layout: docs
-page_title: Agent
+page_title: Agents Overview
 description: >-
-  The Consul agent is the core process of Consul. The agent maintains membership
-  information, registers services, runs checks, responds to queries, and more.
-  The agent must run on every node that is part of a Consul cluster.
+Agents maintain register services, respond to queries, maintain datacenter membership information, and make most of Consul’s functions possible. Learn how to start, stop, and configure agents, as well as their requirements and lifecycle.
 ---
 
-# Consul Agent
+# Agents Overview
 
 This topic provides an overview of the Consul agent, which is the core process of Consul.
 The agent maintains membership information, registers services, runs checks, responds to queries, and more.

diff --git a/website/content/docs/agent/options.mdx b/website/content/docs/agent/options.mdx
@@ -1,10 +1,8 @@
 ---
 layout: docs
-page_title: Configuration
+page_title: Agents: Configuration File Reference
 description: >-
-  The agent has various configuration options that can be specified via the
-  command-line or via configuration files. All of the configuration options are
-  completely optional. Defaults are specified with their descriptions.
+Use agent configuration files to assign attributes to agents and configure multiple agents at once. Learn about agent configuration file parameters and formatting with this reference page and sample code.
 ---
 
 # Configuration
@@ -588,8 +586,6 @@ The agent configuration options below are all specified on the command-line.
   `-`, and `_` are allowed in a custom path.`/v1/` is not allowed as it would overwrite
   the API endpoint.
 
-## Configuration Files ((#configuration_files))
-
 In addition to the command-line options, configuration for the Consul agent can be put into
 files. This may be easier in certain situations, for example when Consul is
 being configured using a configuration management system.

diff --git a/website/content/docs/agent/rpc.mdx b/website/content/docs/agent/rpc.mdx
@@ -1,11 +1,8 @@
 ---
 layout: docs
-page_title: RPC
+page_title: Legacy RPC Protocol
 description: >-
-  The Consul agent provides a complete RPC mechanism that can be used to control
-  the agent programmatically. This RPC mechanism is the same one used by the CLI
-  but can be used by other applications to easily leverage the power of Consul
-  without directly embedding.
+Consul agents originally could be controlled through the RPC protocol. This feature was deprecated in version 0.8 in favor of the HTTP API. Learn about agent RPC interactions and how they worked.
 ---
 
 # RPC Protocol

diff --git a/website/content/docs/agent/sentinel.mdx b/website/content/docs/agent/sentinel.mdx
@@ -1,13 +1,11 @@
 ---
 layout: docs
-page_title: Sentinel in Consul
+page_title: Sentinel ACL Policies (Enterprise)
 description: >-
-  Consul Enterprise uses Sentinel to augment the built-in ACL system to provide
-  advanced policy enforcement. Sentinel policies can currently execute on KV
-  modify and service registration.
+Sentinel allows you to include conditional logic in access control policies. Learn how Consul can use Sentinel policies to extend the ACL system's capabilities for controlling key-value (KV) write access.
 ---
 
-# Sentinel Overview
+# Sentinel for KV ACL Policy Enforcement
 
 <EnterpriseAlert />
 

diff --git a/website/content/docs/agent/telemetry.mdx b/website/content/docs/agent/telemetry.mdx
@@ -1,13 +1,11 @@
 ---
 layout: docs
-page_title: Telemetry
+page_title: Agents: Enable Metrics
 description: >-
-  The Consul agent collects various runtime metrics about the performance of
-  different libraries and subsystems. These metrics are aggregated on a ten
-  second interval and are retained for one minute.
+Configure agent telemetry to collect operations metrics you can use to debug and observe Consul behavior and performance. Learn about configuration options, the metrics you can collect, and why they're important.
 ---
 
-# Telemetry
+# Agent Telemetry
 
 The Consul agent collects various runtime metrics about the performance of
 different libraries and subsystems. These metrics are aggregated on a ten

diff --git a/website/content/docs/architecture/anti-entropy.mdx b/website/content/docs/architecture/anti-entropy.mdx
@@ -1,11 +1,11 @@
 ---
 layout: docs
-page_title: Anti-Entropy
-description: |
-  This section details the process and use of anti-entropy in Consul.
+page_title: Anti-Entropy Enforcement
+description: >-
+Anti-entropy keeps distributed systems consistent. Learn how Consul uses an anti-entropy mechanism to periodically sync agent states with the service catalog to prevent the catalog from becoming stale.
 ---
 
-# Anti-Entropy
+# Anti-Entropy Enforcement
 
 Consul uses an advanced method of maintaining service and health information.
 This page details how services and checks are registered, how the catalog is

diff --git a/website/content/docs/architecture/consensus.mdx b/website/content/docs/architecture/consensus.mdx
@@ -1,10 +1,8 @@
 ---
 layout: docs
-page_title: Consensus Protocol
+page_title: Consensus Protocol | Raft
 description: >-
-  Consul uses a consensus protocol to provide Consistency as defined by CAP. The
-  consensus protocol is based on Raft: In search of an Understandable Consensus
-  Algorithm. For a visual explanation of Raft, see The Secret Lives of Data.
+Consul ensures a consistent state using the Raft protocol. A quorum, or a majority of server agents with one leader, agree to state changes before committing to the state log. Learn how Raft works in Consul to ensure state consistency and how that state can be read with different consistency modes to balance read latency and consistency.
 ---
 
 # Consensus Protocol

diff --git a/website/content/docs/architecture/coordinates.mdx b/website/content/docs/architecture/coordinates.mdx
@@ -1,7 +1,8 @@
 ---
 layout: docs
 page_title: Network Coordinates
-description: A Decentralized Network Coordinate System, with several improvements based on several follow-on papers.
+description: >-
+Network coordinates are node locations in network tomography used to estimate round trip time (RTT). Learn how network coordinates manifest in Consul, how it calculates RTT, and how to work with coordinates to sort catalog information by nearness to a given node.
 ---
 
 # Network Coordinates

diff --git a/website/content/docs/architecture/gossip.mdx b/website/content/docs/architecture/gossip.mdx
@@ -1,12 +1,8 @@
 ---
 layout: docs
-page_title: Gossip Protocol
+page_title: Gossip Protocol | Serf
 description: >-
-  Consul uses a gossip protocol to manage membership and broadcast messages to
-  the cluster. All of this is provided through the use of the Serf library. The
-  gossip protocol used by Serf is based on SWIM: Scalable Weakly-consistent
-  Infection-style Process Group Membership Protocol, with a few minor
-  adaptations.
+Consul agents manage membership in datacenters and WAN federations using the Serf protocol. Learn about the differences between LAN and WAN gossip pools and how `serfHealth` affects health checks.
 ---
 
 # Gossip Protocol

diff --git a/website/content/docs/architecture/improving-consul-resilience.mdx b/website/content/docs/architecture/improving-consul-resilience.mdx
@@ -1,16 +1,11 @@
 ---
 layout: docs
-page_title: Improving Consul Resilience
+page_title: Fault Tolerance in Consul
 description: >-
-  Fault tolerance is the ability of a system to continue operating without interruption
-  despite the failure of one or more components. Consul's resilience, or fault tolerance,
-  is determined by the configuring of its voting server agents. Recommended strategies for
-  increasing Consul's fault tolerance include using 3 or 5 voting server agents, spreading
-  server agents across infrastructure availability zones, and using Consul Enterprise
-  redundancy zones to enable backup voting servers to automatically replace lost voters.
+Fault tolerance is a system's ability to operate without interruption despite component failure. Learn how a set of Consul servers provide fault tolerance through use of a quorum, and how to further improve control plane resilience through use of infrastructure zones and Enterprise redundancy zones.
 ---
 
-# Improving Consul Resilience
+# Fault Tolerance
 
 Fault tolerance is the ability of a system to continue operating without interruption
 despite the failure of one or more components.

diff --git a/website/content/docs/architecture/index.mdx b/website/content/docs/architecture/index.mdx
@@ -2,12 +2,10 @@
 layout: docs
 page_title: Consul Architecture
 description: >-
-  Consul is a complex system that has many different moving parts. To help users
-  and developers of Consul form a mental model of how it works, this page
-  documents the system architecture.
+Consul datacenters consist of clusters of server agents (control plane) and client agents deployed alongside service instances (dataplane). Learn how these components and their different communication methods make Consul possible.
 ---
 
-# Consul Architecture
+# Consul Internals Overview
 
 Consul is a complex system that has many different moving parts. To help
 users and developers of Consul form a mental model of how it works, this

diff --git a/website/content/docs/architecture/jepsen.mdx b/website/content/docs/architecture/jepsen.mdx
@@ -1,14 +1,11 @@
 ---
 layout: docs
-page_title: Jepsen Testing
+page_title: Consistency Verification | Jepsen Testing Results
 description: >-
-  Jepsen is a tool, written by Kyle Kingsbury, designed to test the partition
-  tolerance of distributed systems. It creates network partitions while fuzzing
-  the system with random operations. The results are analyzed to see if the
-  system violates any of the consistency properties it claims to have.
+Jepsen is a tool to measure the reliability and consistency of distributed systems across network partitions. Learn about the Jepsen testing performed on Consul to ensure it gracefully recovers from partitions and maintains consistent state.
 ---
 
-# Jepsen Testing
+# Jepsen Testing Results
 
 [Jepsen](http://aphyr.com/posts/281-call-me-maybe-carly-rae-jepsen-and-the-perils-of-network-partitions)
 is a tool, written by Kyle Kingsbury, designed to test the partition

diff --git a/website/content/docs/connect/ca/aws.mdx b/website/content/docs/connect/ca/aws.mdx
@@ -1,12 +1,11 @@
 ---
 layout: docs
-page_title: Connect - Certificate Management
+page_title: Service Mesh Certificate Authority: AWS Certificate Manager
 description: >-
-  Consul can be used with AWS Certificate Manager Private CA to manage and sign
-  certificates.
+You can use the AWS Certificate Manager Private Certificate Authority as the Consul service mesh's certificate authority  to secure your service mesh. Learn how to configure the AWS ACM Private CA, its limitations in Consul, and cost planning considerations.
 ---
 
-# AWS Certificate Manager Private CA as a Connect CA
+# AWS Certificate Manager as a Service Mesh Certificate Authority
 
 Consul can be used with [AWS Certificate Manager (ACM) Private Certificate
 Authority

diff --git a/website/content/docs/connect/ca/consul.mdx b/website/content/docs/connect/ca/consul.mdx
@@ -1,14 +1,11 @@
 ---
 layout: docs
-page_title: Connect - Certificate Management
+page_title: Certificate Authority: Built-in Service Mesh CA
 description: >-
-  Consul ships with a built-in CA system so that Connect can be easily enabled
-  out of the box. The built-in CA generates and stores the root certificate and
-  private key on Consul servers. It can also be configured with a custom
-  certificate and private key if needed.
+Consul has a built-in service mesh certificate authority that can be used to secure your service mesh without needing a separate CA system. Learn how to configure the built-in service mesh CA as a root CA or an intermediate CA connected to an existing PKI system.
 ---
 
-# Built-In CA
+# Built-In Certificate Authority for Service Mesh
 
 Consul ships with a built-in CA system so that Connect can be
 easily enabled out of the box. The built-in CA generates and stores the

diff --git a/website/content/docs/connect/ca/index.mdx b/website/content/docs/connect/ca/index.mdx
@@ -1,10 +1,11 @@
 ---
 layout: docs
-page_title: Connect - Certificate Management
-description: An overview of the Connect Certificate Authority mechanisms.
+page_title: Service Mesh Certificate Authority: Overview
+description: >-
+Consul uses a certificate authority (CA) to generate, use, manage, sign, and store certificates for your service mesh. Learn about certificate management, including configuration, root cert rotation, cross-signing, and regenerating the CA.
 ---
 
-# Connect Certificate Management
+# Service Mesh Certificate Authority Overview
 
 Certificate management in Connect is done centrally through the Consul
 servers using the configured CA (Certificate Authority) provider. A CA provider

diff --git a/website/content/docs/connect/ca/vault.mdx b/website/content/docs/connect/ca/vault.mdx
@@ -1,12 +1,11 @@
 ---
 layout: docs
-page_title: Connect - Certificate Management
+page_title: Service Mesh Certificate Authority: Vault
 description: >-
-  Consul can be used with Vault to manage and sign certificates. The Vault CA
-  provider uses the Vault PKI secrets engine to generate and sign certificates.
+You can use a Vault PKI secrets engine as the Consul service mesh's certificate authority to secure your service mesh. Learn how to configure the Vault CA as a root CA or an intermediate CA connected to an existing PKI system, and how to manage PKI paths with either Vault or Consul.
 ---
 
-# Vault as a Connect CA
+# Vault as a Service Mesh Certificate Authority
 
 Consul can be used with [Vault](https://www.vaultproject.io) to
 manage and sign certificates.