Merge pull request #14626 from hashicorp/backport/docs/what-is-consul…

…-devdot-update/mutually-pleasing-insect

Backport of Docs/what is consul devdot update into release/1.11.x

website/content/docs/index.mdx

@@ -1,20 +1,15 @@
 ---
 layout: docs
-page_title: Documentation
+page_title: Consul Documentation
 description: >-
-  Welcome to the Consul documentation! This documentation is reference material
-  for all available features and options of Consul.
+  Consul documentation provides reference material for all features and options available in Consul.
 ---
 
 # Consul Documentation
 
-Welcome to the Consul documentation! The documentation is reference material
-for all available features and options of Consul
+The Consul documentation provides reference material for all features and options available in Consul. 
+Click the following links to access documentation and tutorials for common tasks:
 
-In the Quick Links below, you will find the most commonly used documentation
-and a link to our guides that walk you through common tasks. Note that the
-guides are located on the HashiCorp Learn site.
-
-- Follow [the documentation](/docs/install) to install Consul either with a precompiled binary or from source.
-- Read more about the [configuration options](/docs/agent/options) for Consul servers and clients.
-- Get started using Consul with our step-by-step guides at [HashiCorp Learn](https://learn.hashicorp.com/consul).
+- [Install Consul](/docs/install)
+- [Configuration options](/docs/agent/config)
+- [Step-by-step tutorials](https://learn.hashicorp.com/consul)

website/content/docs/intro/index.mdx

@@ -2,44 +2,44 @@
 layout: docs
 page_title: What is Consul?
 description: >-
-  Welcome to the intro guide to Consul! This guide is the best place to start
-  with Consul. We cover what Consul is, what problems it can solve, how it
-  compares to existing software, and how you can get started using it. If you
-  are familiar with the basics of Consul, the documentation provides a more
-  detailed reference of available features.
+  Consul is a service networking solution that delivers service discovery, service mesh, and network security capabilities. It supports multi-cloud infrastructure by automating connectivity between cloud providers. Learn how Consul can help you scale operations and provide high availability across your network.
 ---
 
-# Introduction to Consul
+# What is Consul?
 
+<<<<<<< HEAD
 Welcome to the intro guide to Consul! This guide is the best place to start
 with Consul. We cover what Consul is, what problems it can solve, how it compares
 to existing software, and how you can get started using it. If you are familiar
 with the basics of Consul, the [documentation](/docs) provides a more
 detailed reference of available features. If you're ready to get hands-on
 experience, deploy Consul locally with our
 [HashiCorp Learn tutorial](https://learn.hashicorp.com/tutorials/consul/get-started-install).
+=======
+HashiCorp Consul is a service networking solution that enables teams to manage secure network connectivity between services and across on-prem and multi-cloud environments and runtimes. Consul offers service discovery, service mesh, traffic management, and automated updates to network infrastructure device. You can use these features individually or together in a single Consul deployment.
+>>>>>>> 843d9cdaae (Merge pull request #14603 from hashicorp/docs/what-is-consul-devdot-update)
 
-## Why Consul?
+> **Hands-on**: Complete the Getting Started tutorials to learn how to deploy Consul:
+- [Get Started on Kubernetes](https://learn.hashicorp.com/collections/consul/gs-consul-service-mesh)
+- [Get Started on VMs](https://learn.hashicorp.com/collections/consul/getting-started)
+- [HashiCorp Cloud Platform (HCP) Consul](https://learn.hashicorp.com/collections/consul/cloud-get-started)
+
+## How does Consul work?
 
-Consul solves the challenges that organizations of all sizes encounter with microservices architectures. This ranges from operating in various distributed environments and geographical locations, to meeting the need of securing all application traffic.
-The world is rapidly changing and evolving, so is the computing networking layer.
+Consul provides a _control plane_ that enables you to register, query, and secure services deployed across your network. The control plane is the part of the network infrastructure that maintains a central registry to track services and their respective IP addresses. It is a distributed system that runs on clusters of nodes, such as physical servers, cloud instances, virtual machines, or containers. 
 
-Today's network must quickly adapt and ensure communication is encrypted at all times. Consul enables organizations to embrace a [zero trust](https://www.hashicorp.com/solutions/zero-trust-security) model while scaling up.
-Consul can achieve all this while reducing the burden on both operators and developers through automation of crucial networking tasks
+Consul interacts with the _data plane_ through proxies. The data plane is the part of the network infrastructure that processes data requests. Refer to [Consul Architecture](/docs/architecture) for details.
 
-![Diagram that explains why Consul](/img/intro_why_consul_diagram.svg)
+![Basic Consul workflow](/img/what-is-consul-overview-diagram.png)
 
-## What is Consul?
+The core Consul workflow consists of the following stages:
 
-Consul is a service mesh solution providing a full featured control plane
-with service discovery, configuration, and segmentation functionality. Each
-of these features can be used individually as needed, or they can be used
-together to build a full service mesh. Consul requires a data plane and
-supports both a proxy and native integration model. Consul ships with a
-simple built-in proxy so that everything works out of the box, but also
-supports 3rd party proxy integrations such as Envoy.
+- **Register**: Teams add services to the Consul catalog, which is a central registry that lets services automatically discover each other without requiring a human operator to modify application code, deploy additional load balancers, or hardcode IP addresses. It is the runtime source of truth for all services and their addresses. Teams can manually [define and register services](/docs/discovery/services) using the CLI or the API, or you can automate the process in Kubernetes with [service sync](/docs/k8s/service-sync). Services can also include health checks so that Consul can monitor for unhealthy services.
+- **Query**: Consul’s identity-based DNS lets you find healthy services in the Consul catalog. Services registered with Consul provide health information, access points, and other data that help you control the flow of data through your network. Your services only access other services through their local proxy according to the identity-based policies you define.
+- **Secure**: After services locate upstreams, Consul ensures that service-to-service communication is authenticated, authorized, and encrypted. Consul service mesh secures microservice architectures with mTLS and can allow or restrict access based on service identities, regardless of differences in compute environments and runtimes. 
 
-Review the video below to learn more about Consul from HashiCorp's co-founder Armon.
+## Why Consul?
+Consul increases application resilience, bolsters uptime, accelerates application deployment, and improves security across service-to-service communications. HashiCorp co-founder and CTO Armon Dadgar explains how Consul solves networking challenges.
 
 <iframe
   src="https://www.youtube.com/embed/mxeMdl0KvBI"
@@ -49,71 +49,52 @@ Review the video below to learn more about Consul from HashiCorp's co-founder Ar
   height="315"
 ></iframe>
 
-The key features of Consul are:
-
-- **Service Discovery**: Clients of Consul can register a service, such as
-  `api` or `mysql`, and other clients can use Consul to discover providers
-  of a given service. Using either DNS or HTTP, applications can easily find
-  the services they depend upon.
-
-- **Health Checking**: Consul clients can provide any number of health checks,
-  either associated with a given service ("is the webserver returning 200 OK"), or
-  with the local node ("is memory utilization below 90%"). This information can be
-  used by an operator to monitor cluster health, and it is used by the service
-  discovery components to route traffic away from unhealthy hosts.
-
-- **KV Store**: Applications can make use of Consul's hierarchical key/value
-  store for any number of purposes, including dynamic configuration, feature flagging,
-  coordination, leader election, and more. The simple HTTP API makes it easy to use.
-
-- **Secure Service Communication**: Consul can generate and distribute TLS
-  certificates for services to establish mutual TLS connections.
-  [Intentions](/docs/connect/intentions)
-  can be used to define which services are allowed to communicate.
-  Service segmentation can be easily managed with intentions that can
-  be changed in real time instead of using complex network topologies
-  and static firewall rules.
-
-- **Multi Datacenter**: Consul supports multiple datacenters out of the box. This
-  means users of Consul do not have to worry about building additional layers of
-  abstraction to grow to multiple regions.
-
-Consul is designed to be friendly to both the DevOps community and
-application developers, making it perfect for modern, elastic infrastructures.
-
-## Basic Architecture of Consul
-
-Consul is a distributed, highly available system. This section will cover the
-basics, purposely omitting some unnecessary detail, so you can get a quick
-understanding of how Consul works. For more detail, please refer to the
-[in-depth architecture overview](/docs/architecture).
-
-Every node that provides services to Consul runs a _Consul agent_. Running
-an agent is not required for discovering other services or getting/setting
-key/value data. The agent is responsible for health checking the services
-on the node as well as the node itself.
-
-The agents talk to one or more _Consul servers_. The Consul servers are
-where data is stored and replicated. The servers themselves elect a leader.
-While Consul can function with one server, 3 to 5 is recommended to avoid
-failure scenarios leading to data loss. A cluster of Consul servers is recommended
-for each datacenter.
-
-The servers maintain a _catalog_, which is formed by aggregating information
-submitted by the agents. The catalog maintains the high-level view of the cluster,
-including which services are available, which nodes run those services, health
-information, and more. How agents and the catalog interact can be found
-[here](/docs/architecture/anti-entropy#catalog).
-
-Components of your infrastructure that need to discover other services
-or nodes can query any of the Consul servers _or_ any of the Consul agents.
-The agents forward queries to the servers automatically.
-
-Each datacenter runs a cluster of Consul servers. When a cross-datacenter
-service discovery or configuration request is made, the local Consul servers
-forward the request to the remote datacenter and return the result.
-
-## Next Steps
-
-Continue onwards with [HashiCorp Learn](https://learn.hashicorp.com/tutorials/consul/get-started-install)
-to learn more about Consul and how to get Consul up and running.
+### Automate service discovery
+
+Adopting a microservices architecture on cloud infrastructure is a critical step toward delivering value at scale, but knowing where healthy services are running on your networks in real time becomes a challenge. Consul automates service discovery by replacing service connections usually handled with load balancers with an identity-based service catalog. The service catalog is a centralized source of truth that you can query through Consul’s DNS server or API. The catalog always knows which services are available, which have been removed, and which services are healthy.
+
+### Connect services across runtimes and cloud providers
+
+Modern organizations may deploy services to a combination of on-prem infrastructure environments and public cloud providers across multiple regions. Services may run on bare metal, virtual machines, or as containers across Kubernetes clusters. 
+
+Consul routes network traffic to any runtime or infrastructure environment your services need to reach. You can also use Consul API Gateway to route traffic into and out of the network. Consul service mesh provides additional capabilities, such as securing communication between services, traffic management, and observability, with no application code changes.
+
+Consul also has many integrations with Kubernetes that enable you to leverage Consul features in containerized environments. For example, Consul can automatically inject sidecar proxies into Kubernetes Pods and sync Kubernetes Services and non-Kubernetes services into the Consul service registry without manual changes to the application or changing the Pod definition. 
+
+You can also schedule Consul workloads with [HashiCorp Nomad](https://www.nomadproject.io/) to provide secure service-to-service communication between Nomad jobs and task groups. 
+
+### Enable zero-trust network security
+
+Microservice architectures are complex and difficult to secure against accidental discloser to malicious actors. Consul provides several mechanisms that enhance network security without any changes to your application code, including mutual transport layer security (mTLS) encryption on all traffic between services and  Consul intentions, which are service-to-service permissions that you can manage through the Consul UI, API, and CLI.
+
+When you deploy Consul to Kubernetes clusters, you can also integrate with [HashiCorp Vault](http://vaultproject.io) to manage sensitive data. By default, Consul on Kubernetes leverages Kubernetes secrets as the backend system. Kubernetes secrets are base64 encoded, unencrypted, and lack lease or time-to-live properties. By leveraging Vault as a secrets backend for Consul on Kubernetes, you can manage and store Consul related secrets within a centralized Vault cluster to use across one or many Consul on Kubernetes datacenters. Refer to [Vault as the Secrets Backend](/docs/k8s/installation/vault) for additional information.
+
+You can also secure your Consul deployment, itself, by defining security policies in access control lists (ACL) to control access to data and Consul APIs.
+
+### Protect your services against network failure
+
+Outages are unavoidable, but with distributed systems it is critical that a power failure in one datacenter doesn’t disrupt downstream service operations. You can enable automated backups, redundancy zones, read-replicas, and other features that prevent data loss and downtime after a catastrophic event. L7 observability features also deliver service traffic metrics in the Consul UI, which help you understand the state of a service and its connections within the mesh.
+
+### Dynamically update network infrastructure devices
+
+Change to your network, including day-to-day operational tasks such as updating network device endpoints and firewall or load balancer rules, can lead to problems that disrupt operations at critical moments. You can deploy the Consul-Terraform-Sync (CTS) add-on to dynamically update network infrastructure devices when a service changes. CTS monitors the service information stored in Consul and automatically launches an instance of HashiCorp Terraform to drive relevant changes to the network infrastructure when Consul registers a change, reducing the manual effort of configuring network infrastructure.
+
+### Optimize traffic routes for deployment and testing scenarios 
+
+Rolling out changes can be risky, especially in complex network environments. Updated services may not behave as expected when connected to other services, resulting in upstream or downstream issues. Consul service mesh supports layer 7 (L7) traffic management, which lets you divide L7 traffic into different subsets of service instances. This enables you to divide your pool of services for canary testing, A/B tests, blue/green deployments, and soft multi-tenancy (prod/qa/staging sharing compute resources) deployments. 
+
+## Consul Enterprise
+
+HashiCorp offers core Consul functionality for free in the open source version, which is ideal for smaller businesses and teams that want to pilot Consul within their organizations. As your business grows, you can upgrade to Consul Enterprise, which offers additional capabilities designed to address organizational complexities of collaboration, operations, scale, and governance.  
+
+### HCP Consul
+
+HashiCorp Cloud Platform (HCP) Consul is our SaaS that delivers Consul Enterprise capabilities and shifts the burden of managing the control plane to us. Create an HCP organization and leverage our expertise to simplify control plane maintenance and configuration. Learn more at [HashiCorp Cloud Platform](https://cloud.hashicorp.com/products/consul). 
+
+## Community
+
+We welcome questions, suggestions, and contributions from the community.
+
+- Ask questions in [HashiCorp Discuss](https://discuss.hashicorp.com/c/consul/29).
+- Read our [contributing guide](https://github.com/hashicorp/consul/blob/main/.github/CONTRIBUTING.md).
+- [Submit a Github issue](https://github.com/hashicorp/consul/issues/new/choose) for feature requests and bug reports.