From b0310364c65f36baa165115ff5fa236eaf2ca2b6 Mon Sep 17 00:00:00 2001 From: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> Date: Mon, 14 Oct 2019 10:40:35 -0500 Subject: [PATCH] [docs] Adding Links to Learn (#6611) * adding links to Learn * fixing a couple typos * adding utm paramaters * Update website/source/docs/connect/registration/sidecar-service.md * Update website/source/docs/connect/registration/sidecar-service.md * Update website/source/docs/acl/acl-system.html.md * Update website/source/docs/acl/acl-system.html.md * Update website/source/docs/agent/encryption.html.md Co-Authored-By: Judith Malnick * Update website/source/docs/connect/proxies/built-in.md Co-Authored-By: Judith Malnick * Update website/source/docs/connect/registration/sidecar-service.md Co-Authored-By: Judith Malnick * Update website/source/docs/install/index.html.md Co-Authored-By: Judith Malnick * Update website/source/docs/agent/kv.html.md * Update website/source/docs/connect/security.html.md * Update website/source/docs/connect/security.html.md * Update website/source/docs/internals/architecture.html.md --- website/source/docs/acl/acl-system.html.md | 6 +++-- website/source/docs/agent/basics.html.md | 4 +++- website/source/docs/agent/checks.html.md | 3 ++- website/source/docs/agent/dns.html.md | 3 ++- website/source/docs/agent/encryption.html.md | 5 ++++- website/source/docs/agent/kv.html.md | 13 +++++++---- website/source/docs/agent/options.html.md | 2 ++ website/source/docs/agent/services.html.md | 2 ++ website/source/docs/agent/telemetry.html.md | 9 ++++++-- .../source/docs/connect/mesh_gateway.html.md | 3 +++ .../source/docs/connect/observability.html.md | 6 +++-- .../source/docs/connect/proxies/built-in.md | 14 +++++++----- .../connect/registration/sidecar-service.md | 3 +++ website/source/docs/connect/security.html.md | 7 ++++-- website/source/docs/install/index.html.md | 3 +++ .../docs/internals/architecture.html.md | 1 + website/source/docs/platform/k8s/helm.html.md | 3 +++ .../source/docs/platform/k8s/index.html.md | 22 +++++++++++++++++-- website/source/docs/platform/k8s/run.html.md | 2 +- 19 files changed, 87 insertions(+), 24 deletions(-) diff --git a/website/source/docs/acl/acl-system.html.md b/website/source/docs/acl/acl-system.html.md index 119a3b75e9..9e9453b0bf 100644 --- a/website/source/docs/acl/acl-system.html.md +++ b/website/source/docs/acl/acl-system.html.md @@ -13,7 +13,9 @@ description: |- Consul provides an optional Access Control List (ACL) system which can be used to control access to data and APIs. The ACL is [Capability-based](https://en.wikipedia.org/wiki/Capability-based_security), relying on tokens which are associated with policies to determine which fine grained rules can be applied. Consul's capability based -ACL system is very similar to the design of [AWS IAM](https://aws.amazon.com/iam/). +ACL system is very similar to the design of [AWS IAM](https://aws.amazon.com/iam/). + +To learn how to setup the ACL system on an existing Consul datacenter, use the [Bootstrapping The ACL System guide](https://learn.hashicorp.com/consul/day-0/acl-guide?utm_source=consul.io&utm_medium=docs). ## ACL System Overview @@ -270,5 +272,5 @@ The `service_prefix` policy needs read access for any services that can be regis ## Next Steps -Setup ACLs with the [Bootstrapping the ACL System guide](https://learn.hashicorp.com/consul/advanced/day-1-operations/acl-guide) or continue reading about +Setup ACLs with the [Bootstrapping the ACL System guide](https://learn.hashicorp.com/consul/security-networking/production-acls?utm_source=consul.io&utm_medium=docs) or continue reading about [ACL rules](/docs/acl/acl-rules.html). diff --git a/website/source/docs/agent/basics.html.md b/website/source/docs/agent/basics.html.md index fadc73b85c..9ec16146f6 100644 --- a/website/source/docs/agent/basics.html.md +++ b/website/source/docs/agent/basics.html.md @@ -24,7 +24,9 @@ of their own. ## Running an Agent The agent is started with the [`consul agent`](/docs/commands/agent.html) command. This -command blocks, running forever or until told to quit. The agent command takes a variety +command blocks, running forever or until told to quit. You can test a local agent by following the [Getting Started guides](https://learn.hashicorp.com/consul/getting-started/install?utm_source=consul.io&utm_medium=docs). + +The agent command takes a variety of [`configuration options`](/docs/agent/options.html#command-line-options), but most have sane defaults. When running [`consul agent`](/docs/commands/agent.html), you should see output similar to this: diff --git a/website/source/docs/agent/checks.html.md b/website/source/docs/agent/checks.html.md index 1f928575be..34c5ac48db 100644 --- a/website/source/docs/agent/checks.html.md +++ b/website/source/docs/agent/checks.html.md @@ -10,7 +10,8 @@ description: |- One of the primary roles of the agent is management of system-level and application-level health checks. A health check is considered to be application-level if it is associated with a -service. If not associated with a service, the check monitors the health of the entire node. +service. Review the [Getting Started guide](https://learn.hashicorp.com/consul/getting-started/services?utm_source=consul.io&utm_medium=docs) for a complete example of a application-level health check. +If not associated with a service, the check monitors the health of the entire node. A check is defined in a configuration file or added at runtime over the HTTP interface. Checks created via the HTTP interface persist with that node. diff --git a/website/source/docs/agent/dns.html.md b/website/source/docs/agent/dns.html.md index 37d82965f6..e87563e36a 100644 --- a/website/source/docs/agent/dns.html.md +++ b/website/source/docs/agent/dns.html.md @@ -33,7 +33,8 @@ DNS resolver library and point it at Consul. Another option is to set Consul as the DNS server for a node and provide a [`recursors`](/docs/agent/options.html#recursors) configuration so that non-Consul queries can also be resolved. The last method is to forward all queries for the "consul." -domain to a Consul agent from the existing DNS server. +domain to a Consul agent from the existing DNS server. Review the +[DNS Forwarding guide](https://learn.hashicorp.com/consul/security-networking/forwarding?utm_source=consul.io&utm_medium=docs) for examples. You can experiment with Consul's DNS server on the command line using tools such as `dig`: diff --git a/website/source/docs/agent/encryption.html.md b/website/source/docs/agent/encryption.html.md index fbc35d7b3b..cad66a8957 100644 --- a/website/source/docs/agent/encryption.html.md +++ b/website/source/docs/agent/encryption.html.md @@ -11,7 +11,10 @@ description: |- The Consul agent supports encrypting all of its network traffic. The exact method of encryption is described on the [encryption internals page](/docs/internals/security.html). There are two separate encryption systems, one for gossip traffic and one for RPC. -If you are configuring encryption, review this [guide](https://learn.hashicorp.com/consul/security-networking/agent-encryption). + +To configure the encryption systems on a new cluster, review this following guides to +[enable gossip encryption](https://learn.hashicorp.com/consul/security-networking/agent-encryption?utm_source=consul.io&utm_medium=docs) and +[TLS encryption for agent communication](https://learn.hashicorp.com/consul/security-networking/certificates?utm_source=consul.io&utm_medium=docs). ## Gossip Encryption diff --git a/website/source/docs/agent/kv.html.md b/website/source/docs/agent/kv.html.md index a584b2bdfc..fd31518070 100644 --- a/website/source/docs/agent/kv.html.md +++ b/website/source/docs/agent/kv.html.md @@ -23,6 +23,10 @@ core design allows data to be replicated automatically across all the servers. Having a quorum of servers will decrease the risk of data loss if an outage occurs. +If you have not used Consul KV, check out this [Getting Started +guide](https://learn.hashicorp.com/consul/getting-started/kv?utm_source=consul.io&utm_medium=docs) on HashiCorp +Learn. + ## Accessing the KV store The KV store can be accessed by the [consul kv CLI @@ -41,6 +45,7 @@ directory](/docs/agent/options.html#_data_dir). To ensure data is not lost in the event of a complete outage, use the [`consul snapshot`](/docs/commands/snapshot/restore.html) feature to backup the data. + ## Using Consul KV Objects are opaque to Consul, meaning there are no restrictions on the type of @@ -59,9 +64,6 @@ and when recursively searching within the data store. We also recommend that you avoid the use of `*`, `?`, `'`, and `%` because they can cause issues when using the API and in shell scripts. -If you have not used Consul KV, check out this [Getting Started -guide](https://learn.hashicorp.com/consul/getting-started/kv) on HashiCorp -Learn. ## Extending Consul KV @@ -89,7 +91,10 @@ API supports an `acquire` and `release` operation. The `acquire` operation acts like a Check-And-Set operation. On success, there is a key update and an increment to the `LockIndex` and the session value is updated to reflect the session holding the lock. Review the session documentation for more information -on the [integration](/docs/internals/sessions.html#k-v-integration) +on the [integration](/docs/internals/sessions.html#k-v-integration). + +Review the following guides to learn how to use Consul sessions for [application leader election](https://learn.hashicorp.com/consul/developer-configuration/elections) and +to [build distributed semaphores](https://learn.hashicorp.com/consul/developer-configuration/semaphore). ### Vault diff --git a/website/source/docs/agent/options.html.md b/website/source/docs/agent/options.html.md index caeee1cd0f..dc7dd634c7 100644 --- a/website/source/docs/agent/options.html.md +++ b/website/source/docs/agent/options.html.md @@ -39,6 +39,8 @@ documented below in the [reload command](/docs/commands/reload.html) 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/consul/getting-started/install?utm_source=consul.io&utm_medium=docs) guides to install a local agent. + ## Command-line Options The options below are all specified on the command-line. diff --git a/website/source/docs/agent/services.html.md b/website/source/docs/agent/services.html.md index 9d588b7761..3d70398613 100644 --- a/website/source/docs/agent/services.html.md +++ b/website/source/docs/agent/services.html.md @@ -15,6 +15,8 @@ a health check. A health check is considered to be application level if it is associated with a service. A service is defined in a configuration file or added at runtime over the HTTP interface. +Use the [Getting Started guides](https://learn.hashicorp.com/consul/getting-started/services?utm_source=consul.io&utm_medium=docs) to get hands-on experience registering a simple service with a health check on your local machine. + ## Service Definition To configure a service, either provide the service definition as a diff --git a/website/source/docs/agent/telemetry.html.md b/website/source/docs/agent/telemetry.html.md index ff327d5d88..7c7158ef59 100644 --- a/website/source/docs/agent/telemetry.html.md +++ b/website/source/docs/agent/telemetry.html.md @@ -17,12 +17,17 @@ this is `USR1` while on Windows it is `BREAK`. Once Consul receives the signal, it will dump the current telemetry information to the agent's `stderr`. This telemetry information can be used for debugging or otherwise -getting a better view of what Consul is doing. +getting a better view of what Consul is doing. Review the [Monitoring and +Metrics guide](https://learn.hashicorp.com/consul/day-2-operations/monitoring?utm_source=consul.io&utm_medium=docs) to learn how collect and interpret Consul data. Additionally, if the [`telemetry` configuration options](/docs/agent/options.html#telemetry) are provided, the telemetry information will be streamed to a [statsite](http://github.com/armon/statsite) or [statsd](http://github.com/etsy/statsd) server where -it can be aggregated and flushed to Graphite or any other metrics store. This +it can be aggregated and flushed to Graphite or any other metrics store. +For a configuration example for Telegraf, review the [Monitoring with Telegraf guide](https://learn.hashicorp.com/consul/integrations/telegraf?utm_source=consul.io&utm_medium=docs). + + +This information can also be viewed with the [metrics endpoint](/api/agent.html#view-metrics) in JSON format or using [Prometheus](https://prometheus.io/) format. diff --git a/website/source/docs/connect/mesh_gateway.html.md b/website/source/docs/connect/mesh_gateway.html.md index f63b42ee80..b98d119e5c 100644 --- a/website/source/docs/connect/mesh_gateway.html.md +++ b/website/source/docs/connect/mesh_gateway.html.md @@ -18,6 +18,9 @@ within the Connect session is not decrypted by the Gateway. ![Mesh Gateway Architecture](/assets/images/mesh-gateways.png) +For a complete example of how to connect services across datacenters, +review the [mesh gateway guide](https://learn.hashicorp.com/consul/developer-mesh/connect-gateways). + ## Prerequisites Each mesh gateway needs three things: diff --git a/website/source/docs/connect/observability.html.md b/website/source/docs/connect/observability.html.md index db1fd34775..49fdb06761 100644 --- a/website/source/docs/connect/observability.html.md +++ b/website/source/docs/connect/observability.html.md @@ -22,8 +22,10 @@ If you are using Envoy as your sidecar proxy, you will need to [enable gRPC](/docs/agent/options.html#grpc_port) on your client agents. To define the metrics destination and service protocol you may want to enable [configuration entries](/docs/agent/options.html#config_entries) and [centralized service -configuration](/docs/agent/options.html#enable_central_service_config). If you -are using Kubernetes, the Helm chart can simpify much of the necessary +configuration](/docs/agent/options.html#enable_central_service_config). + +If you +are using Kubernetes, the Helm chart can simplify much of the necessary configuration, which you can learn about in the [observability guide](https://learn.hashicorp.com/consul/getting-started-k8s/l7-observability-k8s). diff --git a/website/source/docs/connect/proxies/built-in.md b/website/source/docs/connect/proxies/built-in.md index f92f360be5..a127ad9d28 100644 --- a/website/source/docs/connect/proxies/built-in.md +++ b/website/source/docs/connect/proxies/built-in.md @@ -11,13 +11,19 @@ description: |- Consul comes with a built-in L4 proxy for testing and development with Consul Connect. -Below is a complete example of all the configuration options available -for the built-in proxy. - ~> **Note:** Although you can configure the built-in proxy using configuration entries, it doesn't have the L7 capability necessary for the observability features released with Consul 1.5. +## Getting Started + +To get started with the built-in proxy and see a working example you can follow the [Getting Started](https://learn.hashicorp.com/consul/getting-started/connect) guide. + +## Proxy Config Key Reference + +Below is a complete example of all the configuration options available +for the built-in proxy. + ```javascript { "service": { @@ -48,8 +54,6 @@ features released with Consul 1.5. } ``` -## Proxy Config Key Reference - All fields are optional with a sane default. * `bind_address` - diff --git a/website/source/docs/connect/registration/sidecar-service.md b/website/source/docs/connect/registration/sidecar-service.md index 287b12ed9b..0e72c2a703 100644 --- a/website/source/docs/connect/registration/sidecar-service.md +++ b/website/source/docs/connect/registration/sidecar-service.md @@ -17,6 +17,9 @@ To simplify the configuration experience when deploying a sidecar for a service instance, Consul 1.3 introduced a new field in the Connect block of the [service definition](/docs/agent/services.html). +To deploy a service and sidecar proxy locally, complete the +[Getting Started guide](https://learn.hashicorp.com/consul/getting-started/connect?utm_source=consul.io&utm_medium=docs). + The `connect.sidecar_service` field is a complete nested service definition on which almost any regular service definition field can be set. The exceptions are [noted below](#limitations). If used, the service definition is treated diff --git a/website/source/docs/connect/security.html.md b/website/source/docs/connect/security.html.md index 24764cb0a6..de7b2d8189 100644 --- a/website/source/docs/connect/security.html.md +++ b/website/source/docs/connect/security.html.md @@ -12,8 +12,11 @@ description: |- Connect enables secure service-to-service communication over mutual TLS. This provides both in-transit data encryption as well as authorization. This page -will document how to secure Connect. For a full security model reference, -see the dedicated [Consul security model](/docs/internals/security.html) page. +will document how to secure Connect. To try Connect locally, complete the +[Getting Started guide](https://learn.hashicorp.com/consul/getting-started/connect?utm_source=consul.io&utm_medium=docs) or for a full security model reference, +see the dedicated [Consul security model](/docs/internals/security.html) page. When +setting up Connect in production, review this [guide](https://learn.hashicorp.com/consul/developer-mesh/connect-production?utm_source=consul.io&utm_medium=docs). + Connect will function in any Consul configuration. However, unless the checklist below is satisfied, Connect is not providing the security guarantees it was diff --git a/website/source/docs/install/index.html.md b/website/source/docs/install/index.html.md index c91c65d39a..73575ef6cb 100644 --- a/website/source/docs/install/index.html.md +++ b/website/source/docs/install/index.html.md @@ -19,6 +19,8 @@ Downloading a precompiled binary is easiest, and we provide downloads over TLS along with SHA256 sums to verify the binary. We also distribute a PGP signature with the SHA256 sums that can be verified. +The [Getting Started guides](https://learn.hashicorp.com/consul/getting-started/install?utm_source=consul.io&utm_medium=docs) provide a quick walkthrough of installing and using Consul on your local machine. + ## Precompiled Binaries To install the precompiled binary, [download](/downloads.html) the appropriate @@ -32,6 +34,7 @@ additional files, if any, aren't required to run Consul. Copy the binary to anywhere on your system. If you intend to access it from the command-line, make sure to place it somewhere on your `PATH`. + ## Compiling from Source To compile from source, you will need [Go](https://golang.org) installed and diff --git a/website/source/docs/internals/architecture.html.md b/website/source/docs/internals/architecture.html.md index 61c938f603..4e0be01407 100644 --- a/website/source/docs/internals/architecture.html.md +++ b/website/source/docs/internals/architecture.html.md @@ -16,6 +16,7 @@ page documents the system architecture. [glossary](/docs/glossary.html) of terms to help clarify what is being discussed. +The architecture concepts in this document can be used with the [Reference Architecture guide](https://learn.hashicorp.com/consul/datacenter-deploy/reference-architecture?utm_source=consul.io&utm_medium=docs) when deploying Consul in production. ## 10,000 foot view diff --git a/website/source/docs/platform/k8s/helm.html.md b/website/source/docs/platform/k8s/helm.html.md index 5126ea111c..4c0333cf24 100644 --- a/website/source/docs/platform/k8s/helm.html.md +++ b/website/source/docs/platform/k8s/helm.html.md @@ -14,6 +14,8 @@ In addition to running Consul itself, the Helm chart is the primary method for installing and configuring Consul integrations with Kubernetes such as catalog syncing, Connect injection, and more. +A step-by-step beginner tutorial and accompanying video can be found at the [Minikube with Consul guide](https://learn.hashicorp.com/consul/getting-started-k8s/minikube?utm_source=consul.io&utm_medium=docs). + This page assumes general knowledge of [Helm](https://helm.sh/) and how to use it. Using Helm to install Consul will require that Helm is properly installed and configured with your Kubernetes cluster. @@ -31,6 +33,7 @@ Consul, or that you understand and enable the Currently, some of these features are not supported in the Helm chart and require additional manual configuration. + ## Using the Helm Chart To install Consul using the Helm chart you must first install Helm onto diff --git a/website/source/docs/platform/k8s/index.html.md b/website/source/docs/platform/k8s/index.html.md index a848db7ba7..942b8df4e0 100644 --- a/website/source/docs/platform/k8s/index.html.md +++ b/website/source/docs/platform/k8s/index.html.md @@ -13,8 +13,6 @@ to Kubernetes using the Helm chart, sync services between Consul and Kubernetes, automatically secure Pod communication with Connect, and more. This section documents the official integrations between Consul and Kubernetes. --> A step-by-step beginner tutorial and accompanying video can be found at the [Minikube with Consul guide](https://learn.hashicorp.com/consul/getting-started-k8s/minikube) - ## Use Cases **Running a Consul server cluster:** The Consul server cluster can run directly @@ -45,6 +43,26 @@ vice versa) over a fully encrypted connection. native integrations provided by Consul itself, any other tool built for Kubernetes can choose to leverage Consul. +## Getting Started With Consul and Kubernetes + +There are several ways to try Consul with Kubernetes in different environments. + + - The [Consul and minikube guide](https://learn.hashicorp.com/consul/ + getting-started-k8s/minikube?utm_source=consul.io&utm_medium=docs) is a quick walk through of how to deploy Consul with the official Helm chart on a local instance of Minikube. + + - The [Deploying Consul with Kubernetes guide](https://learn.hashicorp.com/ + consul/getting-started-k8s/minikube?utm_source=consul.io&utm_medium=docs) + walks you through deploying Consul on Kubernetes with the official Helm chart and can be applied to any Kubernetes installation type. + + - The [Kubernetes on Azure guide](https://learn.hashicorp.com/consul/ + getting-started-k8s/azure-k8s?utm_source=consul.io&utm_medium=docs) is a complete walk through on how to deploy Consul on AKS. + + - The [Consul and Kubernetes Reference Architecture]( + https://learn.hashicorp.com/consul/day-1-operations/kubernetes-reference?utm_source=consul.io&utm_medium=docs) guide provides recommended practices for production. + + - The [Consul and Kubernetes Deployment]( + https://learn.hashicorp.com/consul/day-1-operations/kubernetes-deployment-guide?utm_source=consul.io&utm_medium=docs) guide covers the necssary steps to install and configure a new Consul cluster on Kubernetes in production. + ## "consul-k8s" Project The dedicated [consul-k8s project](https://github.com/hashicorp/consul-k8s) diff --git a/website/source/docs/platform/k8s/run.html.md b/website/source/docs/platform/k8s/run.html.md index 5398884903..db3b1b997e 100644 --- a/website/source/docs/platform/k8s/run.html.md +++ b/website/source/docs/platform/k8s/run.html.md @@ -15,7 +15,7 @@ a server running inside or outside of Kubernetes. This page starts with a large how-to section for various specific tasks. To learn more about the general architecture of Consul on Kubernetes, scroll -down to the [architecture](/docs/platform/k8s/run.html#architecture) section. +down to the [architecture](/docs/platform/k8s/run.html#architecture) section. If you would like to get hands-on experience testing Consul on Kubernetes, try the step-by-step beginner tutorial with an accompanying video in the [Minikube with Consul guide](https://learn.hashicorp.com/consul/getting-started-k8s/minikube?utm_source=consul.io&utm_medium=docs) ## Helm Chart