Backport of Reformat proxy docs refresh into release/1.16.x

website/content/docs/connect/proxies/deploy-service-mesh-proxies.mdx

@@ -0,0 +1,77 @@
+--- 
+layout: docs
+page_title: Deploy service mesh proxies
+description: >- 
+   Envoy and other proxies in Consul service mesh enable service-to-service communication across your network. Learn how to deploy service mesh proxies in this topic.
+---
+
+# Deploy service mesh proxies services
+
+This topic describes how to create, register, and start service mesh proxies in Consul. Refer to [Service mesh proxies overview](/consul/docs/connect/proxies) for additional information about how proxies enable Consul functionalities. For information about deployed sidecar proxies, refer to [Deploy sidecar proxy services](/consul/docs/connect/proxies/deploy-sidecar-services).
+
+## Overview
+
+Complete the following steps to deploy a service mesh proxy:
+
+1. It is not required, but you can create a proxy defaults configuration entry that contains global passthrough settings for all Envoy proxies. 
+1. Create a service definition file and specify the proxy configurations in the `proxy` block.
+1. Register the service using the API or CLI.
+1. Start the proxy service. 
+
+## Requirements
+
+If [ACLs](/consul/docs/security/acl) are enabled and you want to configure global Envoy settings in the [proxy defaults configuration entry](/consul/docs/connect/config-entries/proxy-defaults), you must present a token with `operator:write` permissions. Refer to [Create a service token](/consul/docs/security/acl/tokens/create/create-a-service-token) for additional information.
+
+## Configure global Envoy passthrough settings
+
+If you want to define global passthrough settings for all Envoy proxies, create a proxy defaults configuration entry and specify default settings, such as access log configuration. [Service defaults configuration entries](/consul/docs/connect/config-entries/service-defaults) override proxy defaults and individual service configurations override both configuration entries.
+
+1. Create a proxy defaults configuration entry and specify the following parameters:
+   - `Kind`: Must be set to `proxy-defaults`
+   - `Name`: Must be set to `global`
+1. Configure any additional settings you want to apply to all proxies. Refer to [Proxy defaults configuration entry reference](/consul/docs/connect/config-entries/proxy-defaults) for details about all settings available in the configuraiton entry. 
+1. Apply the configuration by either calling the [`/config` API endpoint](/consul/api-docs/config) or running the [`consul config write` CLI command](/consul/commands/config/write). The following example writes a proxy defaults configuration entry from a local HCL file using the CLI:
+
+```shell-session
+$ consul config write proxy-defaults.hcl
+```
+
+## Define service mesh proxy 
+
+Create a service definition file and configure the following fields to define a service mesh proxy:
+
+1. Set the `kind` field to `connect-proxy`. Refer to the [services configuration reference](/consul/docs/services/configuration/services-configuration-reference#kind) for information about other kinds of proxies you can declare.
+1. Specify a name for the proxy service in the `name` field. Consul applies the configurations to any proxies you bootstrap with the same name.
+1. In the `proxy.destination_service_name` field, specify the name of the service that the proxy represents. 
+1. Configure any additional proxy behaviors that you want to implement in the `proxy` block. Refer to the [Service mesh proxy configuration reference](/consul/docs/connect/proxies/proxy-config-reference) for information about all parameters. 
+1. Specify a port number where other services registered with Consul can discover and connect to the proxies service in the `port` field. To ensure that services only allow external connections established through the service mesh protocol, you should configure all services to only accept connections on a loopback address.
+
+Refer to the [Service mesh proxy configuration reference](/consul/docs/connect/proxies/proxy-config-reference) for example configurations.
+
+ ## Register the service 
+
+Provide the service definition to the Consul agent to register your proxy service. You can use the same methods for registering proxy services as you do for registering application services:
+
+- Place the service definition in a Consul agent's configuration directory and start, restart, or reload the agent. Use this method when implementing changes to an existing proxy service.
+- Use the `consul services register` command to register the proxy service with a running Consul agent.
+- Call the `/agent/service/register` HTTP API endpoint to register the proxy service with a running Consul agent.
+
+Refer to [Register services and health checks](/consul/docs/services/usage/register-services-checks) for instructions.
+
+In the following example, the `consul services register` command registers a proxy service stored in `proxy.hcl`:
+
+```shell-session
+$ consul services register proxy.hcl
+```
+
+## Start the proxy
+
+Envoy requires a bootstrap configuration file before it can start. Use the [`consul connect envoy` command](/consul/commands/connect/envoy) to create the Envoy bootstrap configuration and start the proxy service. Specify the ID of the proxy you want to start with the `-proxy-id` option.  
+
+The following example command starts an Envoy proxy for the `web-proxy` service:
+
+```shell-session
+$ consul connect envoy -proxy-id=web-proxy
+```
+
+For details about operating an Envoy proxy in Consul, refer to the [Envoy proxy reference](/consul/docs/connect/proxies/envoy).  

website/content/docs/connect/proxies/deploy-sidecar-services.mdx

@@ -0,0 +1,286 @@
+---
+layout: docs
+page_title: Deploy proxies as sidecar services
+description: >-
+  You can register a service instance and its sidecar proxy at the same time. Learn about default settings, customizable parameters, limitations, and lifecycle behaviors of the sidecar proxy.
+---
+
+# Deploy sidecar services
+
+This topic describes how to create, register, and start sidecar proxy services in Consul. Refer to [Service mesh proxies overview](/consul/docs/connect/proxies) for additional information about how proxies enable Consul functionalities. For information about deploying service mesh proxies, refer to [Deploy service mesh proxies](/consul/docs/connect/proxies/deploy-service-mesh-proxies).
+
+## Overview
+
+Sidecar proxies run on the same node as the single service instance that they handle traffic for. 
+They may be on the same VM or running as a separate container in the same network namespace. 
+
+You can attach a sidecar proxy to a service you want to deploy to your mesh:
+
+1. It is not required, but you can create a proxy defaults configuration entry that contains global  passthrough settings for all Envoy proxies. 
+1. Create the service definition and include the `connect` block. The `connect` block contains the sidecar proxy configurations that allow the service to interact with other services in the mesh.
+1. Register the service using either the API or CLI.
+1. Start the sidecar proxy service. 
+
+## Requirements
+
+If [ACLs](/consul/docs/security/acl) are enabled and you want to configure global Envoy settings in the [proxy defaults configuration entry](/consul/docs/connect/config-entries/proxy-defaults), you must present a token with `operator:write` permissions. Refer to [Create a service token](/consul/docs/security/acl/tokens/create/create-a-service-token) for additional information.
+
+## Configure global Envoy passthrough settings
+
+If you want to define global passthrough settings for all Envoy proxies, create a proxy defaults configuration entry and specify default settings, such as access log configuration. [Service defaults configuration entries](/consul/docs/connect/config-entries/service-defaults) override proxy defaults and individual service configurations override both configuration entries.
+
+1. Create a proxy defaults configuration entry and specify the following parameters:
+   - `Kind`: Must be set to `proxy-defaults`
+   - `Name`: Must be set to `global`
+1. Configure any additional settings you want to apply to all proxies. Refer to [Proxy defaults configuration entry reference](/consul/docs/connect/config-entries/proxy-defaults) for details about all settings available in the configuraiton entry. 
+1. Apply the configuration by either calling the [`/config` API endpoint](/consul/api-docs/config) or running the [`consul config write` CLI command](/consul/commands/config/write). The following example writes a proxy defaults configuration entry from a local HCL file using the CLI:
+
+```shell-session
+$ consul config write proxy-defaults.hcl
+```
+
+## Define service mesh proxy 
+
+Create a service definition and configure the following fields: 
+
+1. Specify a name for the service you want to attach a sidecar proxy to in the `name` field. This field is required for all services you want to register in Consul.  
+1. Specify a port number where other services registered with Consul can discover and connect to the service in the `port` field. This field is required for all services you want to register in Consul.
+1. Set the `connect` field to `{ sidecar_service: {} }`. The `{ sidecar_service: {} }` value is a macro that applies a set of default configurations that enable you to quickly implement a sidecar. Refer to [Sidecar service defaults](#sidecar-service-defaults) for additional information.
+1. Configure any additional options for your service. Refer to [Services configuration reference](/consul/docs/services/configuration/services-configuration-reference) for details. 
+
+In the following example, a service named `web` is configured with a sidecar proxy:
+
+<Tabs>
+
+<Tab heading="HCL" group="hcl">
+
+```hcl
+service = {
+  name = "web"
+  port = 8080
+  connect = { sidecar_service = {} }
+}
+```  
+
+</Tab>
+
+<Tab heading="JSON" group="json">
+
+```json
+
+{
+  "service": {
+    "name": "web",
+    "port": 8080,
+    "connect": { "sidecar_service": {} }
+  }
+}
+
+```
+
+</Tab>
+
+</Tabs>
+
+When Consul processes the service definition, it generates the following configuration in place of the `sidecar_service` macro. Note that sidecar proxies services are based on the `connect-proxy` type:
+
+<Tabs>
+
+<Tab heading="HCL" group="hcl">
+
+```hcl
+services = [ 
+  {
+    name = "web"
+    port = 8080
+  }
+    checks = {
+      Interval = "10s"
+      Name = "Connect Sidecar Listening"
+      TCP = "127.0.0.1:20000"
+    }
+    checks = {
+      alias_service = "web"
+      name = "Connect Sidecar Aliasing web"
+    }
+    kind = "connect-proxy"
+    name = "web-sidecar-proxy"
+    port = 20000
+    proxy = {
+      destination_service_id = "web"
+      destination_service_name = "web"
+      local_service_address = "127.0.0.1"
+      local_service_port = 8080
+    }
+]
+
+```  
+
+</Tab>
+
+<Tab heading="JSON" group="json">
+
+```json
+{
+  "services": [
+    {
+      "name": "web",
+      "port": 8080
+    },
+    {
+      "name": "web-sidecar-proxy",
+      "port": 20000,
+      "kind": "connect-proxy",
+      "checks": [
+        {
+          "Name": "Connect Sidecar Listening",
+          "TCP": "127.0.0.1:20000",
+          "Interval": "10s"
+        },
+        {
+          "name": "Connect Sidecar Aliasing web",
+          "alias_service": "web"
+        }
+      ],
+      "proxy": {
+        "destination_service_name": "web",
+        "destination_service_id": "web",
+        "local_service_address": "127.0.0.1",
+        "local_service_port": 8080
+      }
+    }
+  ]
+}
+
+```
+
+</Tab>
+
+</Tabs>    
+
+## Register the service 
+
+Provide the service definition to the Consul agent to register your proxy service. You can use the same methods for registering proxy services as you do for registering application services:
+
+- Place the service definition in a Consul agent's configuration directory and start, restart, or reload the agent. Use this method when implementing changes to an existing proxy service.
+- Use the `consul services register` command to register the proxy service with a running Consul agent.
+- Call the `/agent/service/register` HTTP API endpoint to register the proxy service with a running Consul agent.
+
+Refer to [Register services and health checks](/consul/docs/services/usage/register-services-checks) for instructions.
+
+In the following example, the `consul services register` command registers a proxy service stored in `proxy.hcl`:
+
+```shell-session
+$ consul services register proxy.hcl
+```
+
+## Start the proxy
+
+Envoy requires a bootstrap configuration file before it can start. Use the [`consul connect envoy` command](/consul/commands/connect/envoy) to create the Envoy bootstrap configuration and start the proxy service. Specify the name of the service with the attached proxy with the `-sidecar-for` option.  
+
+The following example command starts an Envoy sidecar proxy for the `web` service:
+
+```shell-session
+$ consul connect envoy -sidecar-for=web
+```
+
+For details about operating an Envoy proxy in Consul, refer to [](/consul/docs/connect/proxies/envoy)  
+
+## Configuration reference
+
+The `sidecar_service` block is a service definition that can contain most regular service definition fields. Refer to [Limitations](#limitations) for information about unsupported service definition fields for sidecar proxies. 
+
+Consul treats sidecar proxy service definitions as a root-level service definition. All fields are optional in nested definitions, which default to opinionated settings that are intended to reduce burden of setting up a sidecar proxy.
+
+## Sidecar service defaults
+
+The following fields are set by default on a sidecar service registration. With
+[the exceptions noted](#limitations) any field may be overridden explicitly in
+the `connect.sidecar_service` definition to customize the proxy registration.
+The "parent" service refers to the service definition that embeds the sidecar
+proxy.
+
+- `id` - ID defaults to being `<parent-service-id>-sidecar-proxy`. This can't
+  be overridden as it is used to [manage the lifecycle](#lifecycle) of the
+  registration.
+- `name` - Defaults to being `<parent-service-name>-sidecar-proxy`.
+- `tags` - Defaults to the tags of the parent service.
+- `meta` - Defaults to the service metadata of the parent service.
+- `port` - Defaults to being auto-assigned from a configurable
+  range specified by [`sidecar_min_port`](/consul/docs/agent/config/config-files#sidecar_min_port)
+  and [`sidecar_max_port`](/consul/docs/agent/config/config-files#sidecar_max_port).
+- `kind` - Defaults to `connect-proxy`. This can't be overridden currently.
+- `check`, `checks` - By default we add a TCP check on the local address and
+  port for the proxy, and a [service alias
+  check](/consul/docs/services/usage/checks#alias-checks) for the parent service. If either
+  `check` or `checks` fields are set, only the provided checks are registered.
+- `proxy.destination_service_name` - Defaults to the parent service name.
+- `proxy.destination_service_id` - Defaults to the parent service ID.
+- `proxy.local_service_address` - Defaults to `127.0.0.1`.
+- `proxy.local_service_port` - Defaults to the parent service port.
+
+### Example with overwritten configurations
+
+In the following example, but the `sidecar_service` macro sets baselines configurations for the proxy, but the [proxy
+upstreams](/consul/docs/connect/proxies/proxy-config-reference#upstream-configuration-reference)
+and [built-in proxy
+configuration](/consul/docs/connect/proxies/built-in) fields contain custom values:  
+
+```json
+{
+  "name": "web",
+  "port": 8080,
+  "connect": {
+    "sidecar_service": {
+      "proxy": {
+        "upstreams": [
+          {
+            "destination_name": "db",
+            "local_bind_port": 9191
+          }
+        ],
+        "config": {
+          "handshake_timeout_ms": 1000
+        }
+      }
+    }
+  }
+}
+```
+
+## Limitations
+
+The following fields are not supported in the `connect.sidecar_service` block:
+
+- `id` - Sidecar services get an ID assigned and it is an error to override
+  this. This ensures the agent can correctly deregister the sidecar service
+  later when the parent service is removed.
+- `kind` - Kind defaults to `connect-proxy` and there is currently no way to
+  unset this to make the registration be for a regular non-connect-proxy
+  service.
+- `connect.sidecar_service` - Service definitions can't be nested recursively.
+- `connect.native` - Currently the `kind` is fixed to `connect-proxy` and it's
+  an error to register a `connect-proxy` that is also service mesh-native.
+
+## Lifecycle
+
+Sidecar service registration is mostly a configuration syntax helper to avoid
+adding lots of boiler plate for basic sidecar options, however the agent does
+have some specific behavior around their lifecycle that makes them easier to
+work with.
+
+The agent fixes the ID of the sidecar service to be based on the parent
+service's ID. This enables the following behavior.
+
+- A service instance can _only ever have one_ sidecar service registered.
+- When re-registering via API or reloading from configuration file:
+  - If something changes in the nested sidecar service definition, the change
+    will _update_ the current sidecar registration instead of creating a new
+    one.
+  - If a service registration removes the nested `sidecar_service` then the
+    previously registered sidecar for that service will be deregistered
+    automatically.
+- When reloading the configuration files, if a service definition changes its
+  ID, then a new service instance _and_ a new sidecar instance will be
+  registered. The old ones will be removed since they are no longer found in
+  the config files.