@ -32,7 +32,7 @@ The table below shows this endpoint's support for
### Link API vs. configuration-based linking
The Link API described here is an alternative method to accomplish the same thing as [configuration-based linking](/consul/docs/agent/config/config-files#self-managed-hcp-parameters). You should generally only choose one method or the other for linking your cluster, not both. If you do use both methods, they interract in the following ways:
The Link API described here is an alternative method to accomplish the same thing as [configuration-based linking](/consul/docs/agent/config/config-files#self-managed-hcp-parameters). You should generally only choose one method or the other for linking your cluster, not both. If you do use both methods, they interact in the following ways:
* When Consul is started, values set in the `cloud` configuration will take precedence over what was previously set by the API or CLI.
* Clusters can only be unlinked from HCP Consul Central by the API or CLI, regardless of if they were established via configuration, API, or CLI.
@ -11,9 +11,9 @@ This document will guide you recommendations for monitoring your Consul control
## Background
A Consul datacenter is the smallest unit of Consul infrastructure that can perform basic Consul operations like service discovery or service mesh. A datacenter contains at least one Consul server agent, but a real-world deployment contains three or five server agents and several Consul client agents.
A Consul datacenter is the smallest unit of Consul infrastructure that can perform basic Consul operations like service discovery or service mesh. A datacenter contains at least one Consul server agent, but a real-world deployment contains three or five server agents and several Consul client agents.
The Consul control plane consists of server agents that store all state information, including service and node IP addresses, health checks, and configuration. In addition, the control plane is responsible for securing the mesh, facilitating service discovery, health checking, policy enforcement, and other similar operational concerns. In addition, the control plane contains client agents that report node and service health status to the Consul cluster. In a typical deployment, you must run client agents on every compute node in your datacenter.
The Consul control plane consists of server agents that store all state information, including service and node IP addresses, health checks, and configuration. In addition, the control plane is responsible for securing the mesh, facilitating service discovery, health checking, policy enforcement, and other similar operational concerns. In addition, the control plane contains client agents that report node and service health status to the Consul cluster. In a typical deployment, you must run client agents on every compute node in your datacenter.
The Consul data plane consists of proxies deployed locally alongside each service instance. These proxies, called sidecar proxies, receive mesh configuration data from the control plane, and control network communication between their local service instance and other services in the network. The sidecar proxy handles inbound and outbound service connections, and ensures TLS connections between services are both verified and encrypted.
@ -44,13 +44,13 @@ It is important to have a highly performant network with low network latency. En
### Raft recommendations
Consul uses [Raft for consensus protocol](/consul/docs/architecture/consensus). High saturation of the Raft goroutines can lead to elevated latency in the rest of the system and may cause the Consul cluster to be unstable. As a result, it is important to monitor Raft to track your control plane health. We recommend the following actions to keep control plane healthy:
- Create an alert that notifies you when [Raft thread saturation](/consul/docs/agent/telemetry#raft-thread-saturation) exceeds 50%.
- Create an alert that notifies you when [Raft thread saturation](/consul/docs/agent/telemetry#raft-thread-saturation) exceeds 50%.
- Monitor [Raft replication capacity](/consul/docs/agent/telemetry#raft-replication-capacity-issues) when Consul is handling large amounts of data and high write throughput.
- Lower [`raft_multiplier`](/consul/docs/install/performance#production) to keep your Consul cluster stable. The value of `raft_multiplier` defines the scaling factor for Consul. Default value for raft_multiplier is 5.
A short multiplier minimizes failure detection and election time but may trigger frequently in high latency situations. This can cause constant leadership churn and associated unavailability. A high multiplier reduces the chances that spurious failures will cause leadership churn but it does this at the expense of taking longer to detect real failures and thus takes longer to restore Consul cluster availability.
Wide networks with higher latency will perform better with larger `raft_multipler` values.
Wide networks with higher latency will perform better with larger `raft_multiplier` values.
Raft uses BoltDB for storing data and maintaining its own state. Refer to the [Bolt DB performance metrics](/consul/docs/agent/telemetry#bolt-db-performance) when you are troubleshooting Raft performance issues.
Refer to the [Enable logging on Envoy sidecar pods](/consul/docs/k8s/annotations-and-labels#consul-hashicorp-com-envoy-extra-args) documention for more information.
Refer to the [Enable logging on Envoy sidecar pods](/consul/docs/k8s/annotations-and-labels#consul-hashicorp-com-envoy-extra-args) documentation for more information.
#### Envoy Admin Interface
@ -87,7 +87,7 @@ All endpoints exposed by Envoy are available at the node running Envoy on port `
The following Envoy admin interface endpoints are particularly useful:
- The `listeners` endpoint lists all listeners running on `localhost`. This allows you to confirm whether the upstream services are binding correctly to Envoy.
- The `listeners` endpoint lists all listeners running on `localhost`. This allows you to confirm whether the upstream services are binding correctly to Envoy.
@ -41,7 +41,7 @@ The v2 catalog API is available alongside the existing v1 catalog API, but the c
## Catalog structure
Consul v1.17 introduces a new version of the catalog API designed to bridge differences between the Consul and Kubernetes data models. The v2 catalog API continues to track services and nodes for Consul, but it replaces service instances with _workloads_ and _workload identites_.
Consul v1.17 introduces a new version of the catalog API designed to bridge differences between the Consul and Kubernetes data models. The v2 catalog API continues to track services and nodes for Consul, but it replaces service instances with _workloads_ and _workload identities_.
description: Learn about version 2 of Consul's internal architecture, which replaces services and service instances with workloads and workload identies.
description: Learn about version 2 of Consul's internal architecture, which replaces services and service instances with workloads and workload identities.
---
<Warning>
@ -12,7 +12,7 @@ The v2 catalog API and Traffic Permissions API are currently in beta. This docum
# Consul v2 architecture
This topic provides an overview of Consul's v2 architecture changes and their impact on Consul operations.
This topic provides an overview of Consul's v2 architecture changes and their impact on Consul operations.
In the v1.17.0 release, Consul introduced the option to enable the [v2 catalog API](/consul/docs/architecture/v2/catalog) for testing and development on Kubernetes deployments. The v2 catalog is one of several changes in development to simplify and streamline Consul's architecture.
@ -155,7 +155,7 @@ You can specify the following strings:
* `trace`
### mapPrivilegedContainerPorts
Specifies a value that Consul adds to privileged ports defined in the gateway. Privileged ports are port numbers less than 1024 and some platforms, such as Red Hat OpenShift, explicitly configure Kubernetes to avoid running containers on privileged ports. The total value of the configured port number and the `mapPriviledgedContainerPorts` value must not exceed 65535, which is the highest possible TCP port number allowed.
Specifies a value that Consul adds to privileged ports defined in the gateway. Privileged ports are port numbers less than 1024 and some platforms, such as Red Hat OpenShift, explicitly configure Kubernetes to avoid running containers on privileged ports. The total value of the configured port number and the `mapPrivilegedContainerPorts` value must not exceed 65535, which is the highest possible TCP port number allowed.
description: Learn about the configuration options for the GatewayPolicy configuration resource. GatewayPolicy resources define API gateway polcies for Consul service mesh on Kubernetes.
description: Learn about the configuration options for the GatewayPolicy configuration resource. GatewayPolicy resources define API gateway policies for Consul service mesh on Kubernetes.
---
# GatewayPolicy
@ -15,33 +15,33 @@ The following list outlines field hierarchy, data types, and requirements in a g
- [`apiVersion`](#apiversion): string | required | must be set to `consul.hashicorp.com/v1alpha1`
- [`kind`](#kind): string | required | must be set to `GatewayPolicy`
When every field is defined, a gateway policy has the following form:
When every field is defined, a gateway policy has the following form:
```yaml
apiVersion: consul.hashicorp.com/v1alpha1
@ -53,7 +53,7 @@ spec:
targetRef:
name: gateway
kind: Gateway
group: gateway.networking.kuberenetes.io
group: gateway.networking.kubernetes.io
sectionName: <name of a specific listener the policy applies>
override:
jwt:
@ -109,7 +109,7 @@ Map that contains an arbitrary name for the resource and the namespace it applie
### `metadata.name`
Specifies a name for the resource. The name is metadata that you can use to reference the resource when performing Consul operations, such as applying the resource to a specific cluster.
Specifies a name for the resource. The name is metadata that you can use to reference the resource when performing Consul operations, such as applying the resource to a specific cluster.
#### Values
@ -117,7 +117,7 @@ Specifies a name for the resource. The name is metadata that you can use to refe
- This field is required.
- Data type: String
### `metadata.namespace`
### `metadata.namespace`
Specifies the namespace that the configuration applies to. Refer to [namespaces](/consul/docs/enterprise/namespaces) for more information.
@ -138,7 +138,7 @@ Map that contains the details about the gateway policy. The `apiVersion`, `kind`
### `targetRef`
Map that contains references to the gateway that the policy applies to.
Map that contains references to the gateway that the policy applies to.
#### Values
@ -153,7 +153,7 @@ The following table describes the members of the `targetRef` map:
| `namespace` | Specifies the namespace that the target reference is a member of. | String | `default` |
| `name` | Specifies the name of the API gateway that the policy attaches to. | String | None |
| `kind` | Specifies the type of resource that the policy attaches to. Must be set to `Gateway`. | String | None |
| `group` | Specifies the resource group. Must be set to `gateway.networking.kuberenetes.io`. | String | None |
| `group` | Specifies the resource group. Must be set to `gateway.networking.kubernetes.io`. | String | None |
| `sectionName` | Specifies a part of the gateway that the policy applies to. | String | None |
### `spec.override`
@ -192,7 +192,7 @@ The following table describes the parameters you can specify in a member of the
### `spec.default`
Map that contains default configurations to apply to listeners when the policy is attached to the gateway. All routes attached to the gateway listener inherit the default configurations. You can specify override configurations that have precedence over default configurations. Refer to [`spec.override`](#spec-override) for details.
Map that contains default configurations to apply to listeners when the policy is attached to the gateway. All routes attached to the gateway listener inherit the default configurations. You can specify override configurations that have precedence over default configurations. Refer to [`spec.override`](#spec-override) for details.
#### Values
@ -226,7 +226,7 @@ The following table describes the parameters you can specify in a member of the
## Example configuration
In the following example, all requests through the gateway must have the `api.apps.organization.com` audience claim. Additionally, requests through the gateway must have a `user` role by default.
In the following example, all requests through the gateway must have the `api.apps.organization.com` audience claim. Additionally, requests through the gateway must have a `user` role by default.
page_title: Define API gateway routes on Kubernetes
description: Learn how to define and attach HTTP and TCP routes to Consul API gateway listeners in Kubernetes-orchestrated networks.
description: Learn how to define and attach HTTP and TCP routes to Consul API gateway listeners in Kubernetes-orchestrated networks.
---
# Define API gateway routes on Kubernetes
This topic describes how to configure HTTP and TCP routes and attach them to Consul API gateway listeners in Kubernetes-orchestrated networks. Routes are rule-based configurations that allow external clients to send requests to services in the mesh. For information
This topic describes how to configure HTTP and TCP routes and attach them to Consul API gateway listeners in Kubernetes-orchestrated networks. Routes are rule-based configurations that allow external clients to send requests to services in the mesh. For information
## Overview
The following steps describe the general workflow for defining and deploying routes:
1. Define a route configuration that specifies the protocol type, name of the gateway to attach to, and rules for routing requests.
1. Define a route configuration that specifies the protocol type, name of the gateway to attach to, and rules for routing requests.
1. Deploy the configuration to create the routes and attach them to the gateway.
Routes and the gateways they are attached to are eventually-consistent objects. They provide feedback about their current state through a series of status conditions. As a result, you must manually check the route status to determine if the route successfully bound to the gateway.
@ -23,7 +23,7 @@ Verify that your environment meets the requirements specified in [Technical spec
### OpenShift
If your Kubernetes-orchestrated network runs on OpenShift, verify that OpenShift is enabled for your Consul installation. Refer to [OpenShift requirements](/consul/docs/connect/gateways/api-gateway/tech-specs#openshift-requirements) for additional information.
If your Kubernetes-orchestrated network runs on OpenShift, verify that OpenShift is enabled for your Consul installation. Refer to [OpenShift requirements](/consul/docs/connect/gateways/api-gateway/tech-specs#openshift-requirements) for additional information.
## Define routes
@ -31,12 +31,12 @@ Define route configurations and bind them to listeners configured on the gateway
1. Create a configuration file and specify the following fields:
- `apiVersion`: Specifies the Kuberenetes API gateway version. This must be set to `gateway.networking.k8s.io/v1beta1`
- `apiVersion`: Specifies the Kubernetes API gateway version. This must be set to `gateway.networking.k8s.io/v1beta1`
- `kind`: Set to `HTTPRoute` or `TCPRoute`.
- `metadata.name`: Specify a name for the route. The name is metadata that you can use to reference the configuration when performing Consul operations.
- `spec.parentRefs.name`: Specifies a list of API gateways that the route binds to.
- `spec.parentRefs.name`: Specifies a list of API gateways that the route binds to.
- `spec. rules`: Specifies a list of routing rules for constructing a routing table that maps listeners to services.
Refer to the [`Routes` configuration reference](/consul/docs/connect/gateways/api-gateway/configuration/routes) for details about configuring route rules.
1. Configure any additional fields necessary for your use case, such as the namespace or admin partition.
@ -41,7 +41,7 @@ Create a `GatewayPolicy` values file and configure the following fields to defin
- `metadata.name`: Specifies a name for the policy.
- `spec.targetRef.name`: Specifies the name of the API gateway to attach the policy to.
- `spec.targetRef.kind`: Specifies the kind of resource to attach to the policy to. Must be set to `Gateway`.
- `spec.targetRef.group`: Specifies the resource group. Unless you have created a custom group, this should be set to `gateway.networking.kuberenetes.io`.
- `spec.targetRef.group`: Specifies the resource group. Unless you have created a custom group, this should be set to `gateway.networking.kubernetes.io`.
- `spec.targetRef.sectionName`: Specifies a part of the gateway that the policy applies to.
- `spec.targetRef.override.jwt.providers`: Specifies a list of providers and claims used to verify requests to the gateway. The override settings take precedence over the default and route-specific JWT verification settings.
- `spec.targetRef.default.jwt.providers`: Specifies a list of default providers and claims used to verify requests to the gateway.
@ -60,7 +60,7 @@ Create an `RouteAuthFilter` values file and configure the following fields. Refe
In the `filters` field of your HTTP route configuration, add the following fields. Refer to the [`extensionRef` configuration reference](/consul/docs/connect/gateways/api-gateway/configuration/routes#rules-filters-extensionref) for details:
- `type: extensionRef`: Declare list of extension references.
- `extensionRef.group`: Specifies the resource group. Unless you have created a custom group, this should be set to `gateway.networking.kuberenetes.io`.
- `extensionRef.group`: Specifies the resource group. Unless you have created a custom group, this should be set to `gateway.networking.kubernetes.io`.
- `extensionRef.kind`: Specifies the type of extension reference to attach to the route. Must be `RouteAuthFilter`
- `extensionRef.name`: Specifies the name of the auth filter.
@ -40,7 +40,7 @@ Refer to the following topics for additional information:
### Security context constraints
OpenShift requires a security context constraint (SCC) configuration, which restricts pods to specific groups. You can create a custom SCC or use one of the default constraints. Refer to the [OpenShift documentation](https://docs.openshift.com/container-platform/4.13/authentication/managing-security-context-constraints.html) for additional information.
OpenShift requires a security context constraint (SCC) configuration, which restricts pods to specific groups. You can create a custom SCC or use one of the default constraints. Refer to the [OpenShift documentation](https://docs.openshift.com/container-platform/4.13/authentication/managing-security-context-constraints.html) for additional information.
By default, the SCC is set to `restricted-v2` for the `managedGatewayClass` that Consul automatically creates. The `restricted-v2` SCC is one of OpenShifts default SCCs, but you can specify a different SCC in the `openshiftSCCName` parameter:
@ -52,12 +52,12 @@ connectInject:
```
### Privileged container ports
Containers cannot use privileged ports when OpenShift is enabled. Privileged ports are 1 through 1024, and serving applications from that range is a security risk.
To allow gateway listeners to use privileged port numbers, specify an integer value in the `mapPrivilegedContainerPorts` field of your Consul values configuration. Consul adds the value to listener port numbers that are set to a number in the privileged container range. Consul maps the configured port number to the total port number so that traffic sent to the configured port number is correctly forwarded to the service.
For example, if a gateway listener is configured to port `80` and the `mapPrivilegedContainerPorts` field is configured to `2000`, then the actual port number on the underlying container is `2080`.
For example, if a gateway listener is configured to port `80` and the `mapPrivilegedContainerPorts` field is configured to `2000`, then the actual port number on the underlying container is `2080`.
You can set the `mapPrivilegedContainerPorts` parameter in the following map in your Consul values file:
@ -74,29 +74,29 @@ Refer to the [release notes](/consul/docs/release-notes) for your version of Con
## Supported Kubernetes gateway specification features
Consul API gateways for Kuberentes support a subset of the Kubernetes Gateway API specification. For a complete list of features, including the list of gateway and route statuses and an explanation on how they
are used, refer to the [documentation in our GitHub repo](https://github.com/hashicorp/consul-api-gateway/blob/main/dev/docs/supported-features.md):
Consul API gateways for Kubernetes support a subset of the Kubernetes Gateway API specification. For a complete list of features, including the list of gateway and route statuses and an explanation on how they
are used, refer to the [documentation in our GitHub repo](https://github.com/hashicorp/consul-api-gateway/blob/main/dev/docs/supported-features.md):
### `GatewayClass`
The `GatewayClass` resource describes a class of gateway configurations to use a template for creating `Gateway` resources. You can also specify custom API gateway configurations in a `GatewayClassConfig` CRD and attach them to resource to the `GatewayClass` using the `parametersRef` field.
The `GatewayClass` resource describes a class of gateway configurations to use a template for creating `Gateway` resources. You can also specify custom API gateway configurations in a `GatewayClassConfig` CRD and attach them to resource to the `GatewayClass` using the `parametersRef` field.
You must specify the `"hashicorp.com/consul-api-gateway-controller"` controller so that Consul can manage gateways generated by the `GatewayClass`. Refer to the [Kubernetes `GatewayClass` documentation](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.GatewayClass) for additional information.
### `Gateway`
### `Gateway`
The `Gateway` resource is the core API gateway component. Gateways have one or more listeners that can route `HTTP`, `HTTPS`, or `TCP` traffic. You can define header-based hostname matching for listeners, but SNI is not supported.
The `Gateway` resource is the core API gateway component. Gateways have one or more listeners that can route `HTTP`, `HTTPS`, or `TCP` traffic. You can define header-based hostname matching for listeners, but SNI is not supported.
You can apply filters to add, remove, and set header values on incoming requests. Gateways support the `terminate` TLS mode and `core/v1/Secret` TLS certificates. Extended option support includes TLS version and cipher constraints. Refer to the [Kubernetes `Gateway` documentation](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.Gateway) for additional information.
### `HTTPRoute`
`HTTPRoute` configurations determine HTTP paths between listeners defined on the gateway and services in the mesh. You can specify weights to load balance traffic, as well as define rules for matching request paths, headers, queries, and methods to ensure that traffic is routed appropriately. You can apply filters to add, remove, and set header values on requests sent through th route.
`HTTPRoute` configurations determine HTTP paths between listeners defined on the gateway and services in the mesh. You can specify weights to load balance traffic, as well as define rules for matching request paths, headers, queries, and methods to ensure that traffic is routed appropriately. You can apply filters to add, remove, and set header values on requests sent through th route.
Routes support the following backend types:
- `core/v1/Service` backend types when the route maps to service registered with Consul.
Refer to [Kubernetes `HTTPRoute` documentation](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.HTTPRoute) for additional information.
@ -104,8 +104,8 @@ Refer to [Kubernetes `HTTPRoute` documentation](https://gateway-api.sigs.k8s.io/
`TCPRoute` configurations determine TCP paths between listeners defined on the gateway and services in the mesh. Routes support the following backend types:
- `core/v1/Service` backend types when the route maps to service registered with Consul.
Refer to [Kubernetes `TCPRoute` documentation](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.TCPRoute) for additional information.
@ -6,13 +6,13 @@ description: You can configure sameness groups so that when a service instance f
# Failover with sameness groups
This page describes how to use sameness groups to automatically redirect service traffic to healthy instances in failover scenarios. Sameness groups are a user-defined set of Consul admin partitions with identical registered services. These admin paritions typically belong to Consul datacenters in different cloud regions, which enables sameness groups to participate in several service failover configuration strategies.
This page describes how to use sameness groups to automatically redirect service traffic to healthy instances in failover scenarios. Sameness groups are a user-defined set of Consul admin partitions with identical registered services. These admin partitions typically belong to Consul datacenters in different cloud regions, which enables sameness groups to participate in several service failover configuration strategies.
To create a sameness group and configure each Consul datacenter to allow traffic from other members of the group, refer to [create sameness groups](/consul/docs/connect/cluster-peering/usage/create-sameness-groups).
## Failover strategies
You can edit a sameness group configuration entry so that all services failover to healthy instances on other members of a sameness group by default. You can also reference the sameness group in other configuration entries to enact other failover strategies for your network.
You can edit a sameness group configuration entry so that all services failover to healthy instances on other members of a sameness group by default. You can also reference the sameness group in other configuration entries to enact other failover strategies for your network.
You can establish a failover strategy by configuring sameness group behavior in the following locations:
@ -33,9 +33,9 @@ In the following example configuration entry, datacenter `dc1` has two partition
@ -32,17 +32,17 @@ For networks deployed to virtual machines, complete the following steps to route
If you deployed Consul to a Kubernetes or ECS environment using `consul-k8s` or `consul-ecs`, service instance locality information is inherited from the host machine. As a result, you do not need to specify the regions and zones on containerized platforms unless you are implementing a custom deployment.
On Kubernetes, Consul automatically populates geographic information about service instances using the `topology.kubernetes.io/region` and `topology.kubernetes.io/zone` labels from the Kubernetes nodes. On AWS ECS, Consul uses the `AWS_REGION` environment variable and `AvailabilityZone` attribute of the ECS task meta.
On Kubernetes, Consul automatically populates geographic information about service instances using the `topology.kubernetes.io/region` and `topology.kubernetes.io/zone` labels from the Kubernetes nodes. On AWS ECS, Consul uses the `AWS_REGION` environment variable and `AvailabilityZone` attribute of the ECS task meta.
### Requirements
You should only enable locality-aware routing when each set of external upstream instances within the same zone and region have enough capacity to handle requests from downstream service instances in their respective zones. Locality-aware routing is an advanced feature that may adversely impact service capacity if used incorrectly. When enabled, Consul routes all traffic to the nearest set of service instances and only fails over when no healthy instances are available in the nearest set.
You should only enable locality-aware routing when each set of external upstream instances within the same zone and region have enough capacity to handle requests from downstream service instances in their respective zones. Locality-aware routing is an advanced feature that may adversely impact service capacity if used incorrectly. When enabled, Consul routes all traffic to the nearest set of service instances and only fails over when no healthy instances are available in the nearest set.
## Specify the locality of your Consul agents
The `locality` configuration on a Consul client applies to all services registered to the client.
1. Configure the `locality` block in your Consul client agent configuration files. The `locality` block is a map containing the `region` and `zone` parameters.
1. Configure the `locality` block in your Consul client agent configuration files. The `locality` block is a map containing the `region` and `zone` parameters.
The parameters should match the values for regions and zones defined in your network. Refer to [`locality`](/consul/docs/agent/config/config-files#locality) in the agent configuration reference for additional information.
@ -59,7 +59,7 @@ locality = {
## Specify the localities of your service instances (optional)
This step is optional in most scenarios. Refer to [Workflow](#workflow) for additional information.
This step is optional in most scenarios. Refer to [Workflow](#workflow) for additional information.
1. Configure the `locality` block in your service definition for both downstream (client) and upstream services. The `locality` block is a map containing the `region` and `zone` parameters. When you start a proxy for the service, Consul passes the locality to the proxy so that it can route traffic accordingly.
@ -70,7 +70,7 @@ Register or re-register the service to apply the configuration. Refer to [Regist
In the following example, the `web` service is available in the `us-west-1` region and `us-west-1a` zone on AWS:
```hcl
```hcl
service {
id = "web"
locality = {
@ -172,7 +172,7 @@ Apply the configuration by either running the [`consul config write` CLI command
<Tabs>
<Tab heading="HCL" group="hcl">
<CodeBlockConfig filename="api-resolver.hcl">
```hcl
Kind = "service-resolver"
Name = "api"
@ -182,10 +182,10 @@ Apply the configuration by either running the [`consul config write` CLI command
```
</CodeBlockConfig>
</Tab>
<Tab heading="JSON" group="json">
<CodeBlockConfig filename="api-resolver.json">
```json
{
"kind": "service-resolver",
@ -199,7 +199,7 @@ Apply the configuration by either running the [`consul config write` CLI command
</Tab>
<Tab heading="Kubernetes" group="kubernetes">
<CodeBlockConfig filename="api-resolver.yaml">
```yaml
apiversion: consul.hashicorp.com/v1alpha1
kind: ServiceResolver
@ -209,7 +209,7 @@ Apply the configuration by either running the [`consul config write` CLI command
prioritizeByLocality:
mode: failover
```
</CodeBlockConfig>
</Tab>
</Tabs>
@ -218,32 +218,32 @@ Apply the configuration by either running the [`consul config write` CLI command
<Tabs>
<Tab heading="Consul CLI" group="cli">
```shell-session
$ consul config write api-resolver.hcl
```
</Tab>
<Tab heading="Kubernetes" group="k8s">
```shell-session
$ kubectl apply -f api-resolver.yaml
```
</Tab>
<Tab heading="HTTP API" group="api">
```shell-session
$ curl --request PUT --data @api-resolver.hcl http://127.0.0.1:8500/v1/config
```
</Tab>
</Tabs>
### Configure locality on Kubernetes test clusters explicitly
You can explicitly configure locality for each Kubernetes node so that you can test locality-aware routing with a local Kubernetes cluster or in an environment where `topology.kubernetes.io` labels are not set.
You can explicitly configure locality for each Kubernetes node so that you can test locality-aware routing with a local Kubernetes cluster or in an environment where `topology.kubernetes.io` labels are not set.
Run the `kubectl label node` command and specify the locality as arguments. The following example specifies the `us-east-1` region and `us-east-1a` zone for the node:
@ -261,7 +261,7 @@ Consul configures Envoy's built-in [`overprovisioning_factor`](https://www.envoy
To verify that locality-aware routing and failover configurations, you can inspect Envoy's xDS configuration dump for a downstream proxy. Refer to the [consul-k8s CLI docs](https://developer.hashicorp.com/consul/docs/k8s/k8s-cli#proxy-read) for details on how to obtain the xDS configuration dump on Kubernetes. For other workloads, use the Envoy [admin interface](https://www.envoyproxy.io/docs/envoy/latest/operations/admin) and ensure that you [include EDS](https://www.envoyproxy.io/docs/envoy/latest/operations/admin#get--config_dump?include_eds).
Inspect the [priority](https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/upstream/load_balancing/priority#arch-overview-load-balancing-priority-levels) on each set of endpoints under the upstream `ClusterLoadAssignment` in the `EndpointsConfigDump`. Alternatively, the same priorities should be visibile within the output of the [`/clusters?format=json`](https://www.envoyproxy.io/docs/envoy/latest/operations/admin#get--clusters?format=json) admin endpoint.
Inspect the [priority](https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/upstream/load_balancing/priority#arch-overview-load-balancing-priority-levels) on each set of endpoints under the upstream `ClusterLoadAssignment` in the `EndpointsConfigDump`. Alternatively, the same priorities should be visible within the output of the [`/clusters?format=json`](https://www.envoyproxy.io/docs/envoy/latest/operations/admin#get--clusters?format=json) admin endpoint.
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.
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 deploying proxies as sidecars for service instances, refer to [Deploy sidecar proxy services](/consul/docs/connect/proxies/deploy-sidecar-services).
@ -15,7 +15,7 @@ For information about deploying proxies as sidecars for service instances, refer
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. 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. Proxies appear in the list of services registered to Consul, but they must be started before they begin to route traffic in your service mesh.
@ -31,29 +31,29 @@ If you want to define global passthrough settings for all Envoy proxies, create
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. 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 configuration entry.
1. Apply the configuration by either calling the [`/config` HTTP 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
## 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. 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
## 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.
@ -68,7 +68,7 @@ $ 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.
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:
@ -76,4 +76,4 @@ The following example command starts an Envoy proxy for the `web-proxy` service:
$ 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).
For details about operating an Envoy proxy in Consul, refer to the [Envoy proxy reference](/consul/docs/connect/proxies/envoy).
@ -11,15 +11,15 @@ This topic describes how to create, register, and start sidecar proxy services i
## 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.
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. 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.
1. Start the sidecar proxy service.
## Requirements
@ -32,21 +32,21 @@ If you want to define global passthrough settings for all Envoy proxies, create
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. 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 configuration 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
## Define service mesh proxy
Create a service definition and configure the following fields:
Create a service definition and configure the following fields:
1. `name`: 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. `name`: 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. `port`: 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. `connect`: 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.
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:
@ -60,7 +60,7 @@ service = {
port = 8080
connect = { sidecar_service = {} }
}
```
```
</Tab>
@ -89,7 +89,7 @@ When Consul processes the service definition, it generates the following configu
<Tab heading="HCL" group="hcl">
```hcl
services = [
services = [
{
name = "web"
port = 8080
@ -114,7 +114,7 @@ services = [
}
]
```
```
</Tab>
@ -156,12 +156,12 @@ services = [
</Tab>
</Tabs>
</Tabs>
## Register the service
## 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.
@ -176,7 +176,7 @@ $ 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.
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:
@ -184,11 +184,11 @@ The following example command starts an Envoy sidecar proxy for the `web` servic
$ consul connect envoy -sidecar-for=web
```
For details about operating an Envoy proxy in Consul, refer to [](/consul/docs/connect/proxies/envoy)
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.
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.
@ -224,7 +224,7 @@ proxy.
In the following example, the `sidecar_service` macro sets baselines configurations for the proxy, but the [proxy
@ -18,24 +18,24 @@ You should have some familiarity with AWS ECS. Refer to [What is Amazon Elastic
You must meet the following requirements and prerequisites to enable security features in Consul service mesh:
- Enable [TLS encryption](https://developer.hashicorp.com/consul/docs/security/encryption#rpc-encryption-with-tls) on your Consul servers so that they can communicate security with Consul dataplane containers over gRPC.
- Enable [access control lists (ACLs)](/consul/docs/security/acl) on your Consul servers. ALCs provide authentication and authorization for access to Consul servers on the mesh.
- Enable [access control lists (ACLs)](/consul/docs/security/acl) on your Consul servers. ACLs provide authentication and authorization for access to Consul servers on the mesh.
- You should be familiar with specifying sensitive data on ECS. Refer to [Passing sensitive data to a container](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/specifying-sensitive-data.html) in the AWS documentation for additional information.
You should be familiar with configuring Consul's secure features, including how to create ACL tokens and policies. Refer to the following resources:
- [Create a service token](/consul/docs/security/acl/tokens/create/create-a-service-token)
- [Day 1: Security tutorial](https://developer.hashicorp.com/consul/tutorials/security) for additional information.
Consul requires a unique IAM role for each ECS task family. Task IAM roles cannot be shared by different task families because the task family is unique to each Consul service.
Consul requires a unique IAM role for each ECS task family. Task IAM roles cannot be shared by different task families because the task family is unique to each Consul service.
## Configure ECS task definition file
Create a JSON file for the task definition. The task definition is the ECS blueprint for your software services on AWS. Refer to the [ECS task definitions in the AWS documentation](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definitions.html) for additional information.
Create a JSON file for the task definition. The task definition is the ECS blueprint for your software services on AWS. Refer to the [ECS task definitions in the AWS documentation](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definitions.html) for additional information.
In addition to your application container, add configurations to your task definition that creates the following Consul containers:
- Dataplane container
- Control-plane container
- ECS controller container
- ECS controller container
## Top-level fields
@ -46,7 +46,7 @@ The following table describes the top-level fields you must include in the task
| `family` | The task family name. This is used as the Consul service name by default. | string |
| `networkMode` | Must be `awsvpc`, which is the only network mode supported by Consul on ECS. | string |
| `volumes` | Volumes on the host for sharing configuration between containers for initial task setup. You must define a `consul_data` and `consul_binary` bind mount. Bind mounts can be mounted into one or more containers in order to share files among containers. For Consul on ECS, certain binaries and configuration are shared among containers during task startup. | list |
| `containerDefinitions` | Defines the application container that runs in the task. Refer to [Define your application container](#define-your-application-container). | list |
| `containerDefinitions` | Defines the application container that runs in the task. Refer to [Define your application container](#define-your-application-container). | list |
The following example shows the top-level fields:
@ -81,7 +81,7 @@ The following example shows the top-level fields:
The `tags` list must include the following tags if you are using the ECS controller in a [secure configuration](/consul/docs/ecs/deploy/manual#secure-configuration-requirements).
Without these tags, the ACL controller is unable to provision a service token for the task.
| Tag | Description | Type | Default |
| Tag | Description | Type | Default |
| --- | --- | --- | --- |
| `consul.hashicorp.com/mesh` | Enables the ECS controller. Set to `false` to disable the ECS controller. | String | `true` |
| `consul.hashicorp.com/service-name` | Specifies the name of the Consul service associated with this task. Required if the service name is different than the task `family`. | String | None |
@ -96,7 +96,7 @@ Specify your application container configurations in the `containerDefinitions`
| --- | --- | --- |
| `name` | The name of your application container. | string |
| `image` | The container image used to run your application. | string |
| `essential` | Must be `true` to ensure the health of your application container affects the health status of the task. | boolean |
| `essential` | Must be `true` to ensure the health of your application container affects the health status of the task. | boolean |
| `dependsOn` | Specifies container dependencies that ensure your application container starts after service mesh setup is complete. Refer to [Application container dependency configuration](#application-container-dependency-configuration) for details. | list |
Refer to the [ECS Task Definition](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definition_parameters.html) documentation for a complete reference.
@ -120,7 +120,7 @@ The `dependsOn` list must include the following maps:
}
```
## Configure the dataplane container
## Configure the dataplane container
The dataplane container runs Envoy proxy for Consul service mesh. Specify the fields described in the following table to declare a dataplane container:
@ -174,7 +174,7 @@ Specify the fields described in the following table to declare the control-plane
| --- | --- | --- |
| `name` | Specifies the name of the container. This must be `control-plane`. | string |
| `image` | Specifies the `consul-ecs` image. Specify the following public AWS registry to avoid rate limits: `public.ecr.aws/hashicorp/consul-ecs` | string |
| `mountPoints` | Specifies a shared volume to store the Envoy bootstrap configuration file that the dataplane container can access and consume. The keys and values in this configuration must be defined as described in [Control-plane shared volume configuration](#control-plane-shared-volume-configuration). | list |
| `mountPoints` | Specifies a shared volume to store the Envoy bootstrap configuration file that the dataplane container can access and consume. The keys and values in this configuration must be defined as described in [Control-plane shared volume configuration](#control-plane-shared-volume-configuration). | list |
| `command` | Set to `["control-plane"]` so that the container runs the `control-plane` command. | list |
| `environment` | Specifies the `CONSUL_ECS_CONFIG_JSON` environment variable, which configures the container to connect to the Consul servers. Refer to [Control-plane to Consul servers configuration](#control-plane-to-Consul-servers-configuration) for details. | list |
@ -199,7 +199,7 @@ The `mountPoints` configuration defines a volume and path where the control-plan
### Control-plane to Consul servers configuration
Provide Consul server connection settings to the mesh task module so that the module can configure the control-plane and ECS controller containers to connect to the servers.
Provide Consul server connection settings to the mesh task module so that the module can configure the control-plane and ECS controller containers to connect to the servers.
1. In your `variables.tf` file, define variables for the host URL and TLS settings for gRPC and HTTP traffic. Refer to the [mesh task module reference](https://registry.terraform.io/modules/hashicorp/consul-ecs/aws/latest/submodules/mesh-task?tab=inputs) for information about the variables you can define. In the following example, the Consul server address is defined in the `consul_server_hosts` variable:
@ -210,7 +210,7 @@ Provide Consul server connection settings to the mesh task module so that the mo
}
```
1. Add an `environment` block to the control-plane and ECS controller containers definition
1. Add an `environment` block to the control-plane and ECS controller containers definition.
1. Set the `environment.name` field to the `CONSUL_ECS_CONFIG_JSON` environment variable and the value to `local.encoded_config`.
```hcl
@ -223,7 +223,7 @@ Provide Consul server connection settings to the mesh task module so that the mo
```
When you apply the configuration, the mesh task module interpolates the server configuration variables, builds a `config.tf` file, and injects the settings into the appropriate containers.
For additional information about the `config.tf` file, refer to the [JSON schema reference documentation](/consul/docs/ecs/reference/config-json-schema).
For additional information about the `config.tf` file, refer to the [JSON schema reference documentation](/consul/docs/ecs/reference/config-json-schema).
## Register the task definition configuration
@ -245,8 +245,8 @@ Verify that you have completed the prerequisites described in [Secure configurat
On the Consul server, create a policy that grants the following access for the controller:
- `acl:write`
- `operator:write`
- `acl:write`
- `operator:write`
- `node:write`
- `service:write`
@ -260,7 +260,7 @@ The policy allows Consul to generate a token linked to the policy. Refer to [Cre
### Configure the auth method for service tokens
Run the `consul acl auth-method create` command on a Consul server to create an instance of the auth method for service tokens.
Run the `consul acl auth-method create` command on a Consul server to create an instance of the auth method for service tokens.
The following example command configures the auth method to associate a service identity
to each token created during login to this auth method instance.
@ -303,9 +303,9 @@ You must specify the following configuration in the `-config` flag:
Refer to the [auth method configuration parameters documentation](/consul/docs/security/acl/auth-methods/aws-iam#config-parameters) for additional information.
### Create the binding rule
### Create the binding rule
Run the `consul acl binding-rule create` command on a Consul server to create a binding rule. The rule associates a service identity with each token created on successful login to this instance of the auth method.
Run the `consul acl binding-rule create` command on a Consul server to create a binding rule. The rule associates a service identity with each token created on successful login to this instance of the auth method.
In the following example, Consul takes the service identity name from the `consul.hashicorp.com.service-name` tag specified for authenticating IAM role identity.
@ -336,7 +336,7 @@ You can reference stored secrets using their ARN. The examples show ARNs for sec
You can configure Consul servers connected to your ECS workloads to capture a log of authenticated events. Refer to [Audit Logging](/consul/docs/enterprise/audit-logging) for details.
## Next steps
After deploying the Consul service mesh infrastructure, you must still define routes between service instances as well as configure the bind address for your applications so that they only receive traffic through the mesh. Refer to the following topics:
- [Configure routes between ECS tasks](/consul/docs/ecs/deploy/configure-routes)
You can migrate tasks in existing Amazon Web Services ECS deployments to a service mesh deployed with Terraform. Learn how to convert a task specified as an ECS task definition into a `mesh-task` Terraform module.
---
# Migrate existing tasks to Consul on ECS with Terraform
# Migrate existing tasks to Consul on ECS with Terraform
To migrate existing tasks to Consul, rewrite the existing Terraform code for your tasks so that the container definitions include the [`mesh-task` Terraform module](https://registry.terraform.io/modules/hashicorp/consul-ecs/aws/latest/submodules/mesh-task).
To migrate existing tasks to Consul, rewrite the existing Terraform code for your tasks so that the container definitions include the [`mesh-task` Terraform module](https://registry.terraform.io/modules/hashicorp/consul-ecs/aws/latest/submodules/mesh-task).
Your tasks must already be defined in Terraform using the `ecs_task_definition` resource so that they can then be converted to use the `mesh-task` module.
## Example
## Example
The following example shows an existing task definition configured in Terraform:
@ -93,7 +93,7 @@ module "my_task" {
Note the following differences:
- The `execution_role_arn` and `task_role_arn` fields are removed. The `mesh-task` module creates the task and execution roles by default. If you need to use existing IAM roles, set the `task_role` and `execution_role` fields to pass in existing roles.
- The `port` field specifes the port that your application listens on. If your application has no listening port, set `outbound_only = true` and remove the `port` field.
- The `port` field specifies the port that your application listens on. If your application has no listening port, set `outbound_only = true` and remove the `port` field.
- The `jsonencode()` function is removed from the `container_definitions` field.
The `mesh-task` module creates a new version of your task definition with the necessary dataplane containers so you can delete your existing `aws_ecs_task_definition` resource.
The `mesh-task` module creates a new version of your task definition with the necessary dataplane containers so you can delete your existing `aws_ecs_task_definition` resource.
@ -11,17 +11,17 @@ This topic describes how to create a Terraform configuration that deploys Consul
## Overview
Create a Terraform configuration file that includes the ECS task definition and Terraform modules that build the Consul service mesh components. The task definition is the ECS blueprint for your software services on AWS. Refer to the [ECS task definitions documentation](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definitions.html) for additional information.
Create a Terraform configuration file that includes the ECS task definition and Terraform modules that build the Consul service mesh components. The task definition is the ECS blueprint for your software services on AWS. Refer to the [ECS task definitions documentation](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definitions.html) for additional information.
You can add the following modules and resources to your Terraform configuration:
- `mesh-task` module: Adds the Consul ECS control-plane and Consul dataplane containers to the task definition along with your application container. Envoy runs as a subprocess within the Consul dataplane container.
- `mesh-task` module: Adds the Consul ECS control-plane and Consul dataplane containers to the task definition along with your application container. Envoy runs as a subprocess within the Consul dataplane container.
- `aws_ecs_service` resource: Adds an ECS service to run and maintain your task instance.
- `gateway-task` module: Adds mesh gateway containers to the cluster. Mesh gateways enable service-to-service communication across different types of network areas.
To enable Consul security features for your production workloads, you must also deploy the `controller` module, which provisions ACL tokens for service mesh tasks.
To enable Consul security features for your production workloads, you must also deploy the `controller` module, which provisions ACL tokens for service mesh tasks.
After defining your Terraform configuration, use `terraform apply` to deploy Consul to your ECS cluster.
After defining your Terraform configuration, use `terraform apply` to deploy Consul to your ECS cluster.
## Requirements
@ -34,10 +34,10 @@ After defining your Terraform configuration, use `terraform apply` to deploy Con
You must meet the following requirements and prerequisites to enable security features in Consul service mesh:
- Enable [TLS encryption](/consul/docs/security/encryption#rpc-encryption-with-tls) on your Consul servers so that they can communicate securely with Consul containers over gRPC.
- Enable [access control lists (ACLs)](/consul/docs/security/acl) on your Consul servers. ALCs provide authentication and authorization for access to Consul servers on the mesh.
- Enable [access control lists (ACLs)](/consul/docs/security/acl) on your Consul servers. ACLs provide authentication and authorization for access to Consul servers on the mesh.
- You should be familiar with specifying sensitive data on ECS. Refer to [Passing sensitive data to a container](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/specifying-sensitive-data.html) in the AWS documentation for additional information.
Additionally, Consul requires a unique IAM role for each ECS task family. Task IAM roles cannot be shared by different task families because the task family is unique to each Consul service.
Additionally, Consul requires a unique IAM role for each ECS task family. Task IAM roles cannot be shared by different task families because the task family is unique to each Consul service.
You should be familiar with configuring Consul's secure features, including how to create ACL tokens and policies. Refer to the following resources for additional information:
@ -53,7 +53,7 @@ Create a Terraform configuration file and add your ECS task definition. The task
Add a `module` block to your Terraform configuration and specify the following fields:
- `source`: Specifies the location of the `mesh-task` module. This field must be set to `hashicorp/consul-ecs/aws//modules/mesh-task`. The `mesh-task` module automatically adds the Consul service mesh infrastructure when you apply the Terraform configuration.
- `version`: Specifies the version of the `mesh-task` module to use.
- `version`: Specifies the version of the `mesh-task` module to use.
- `family`: Specifies the [ECS task definition family](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definition_parameters.html#family). Consul also uses the `family` value as the Consul service name by default.
- `container_definitions`: Specifies a list of [container definitions](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definition_parameters.html#container_definitions) for the task definition. This field is where you include your application containers.
@ -99,7 +99,7 @@ The following fields are required. Refer to the [module reference documentation]
## Configure Consul server settings
Provide Consul server connection settings to the mesh task module so that the module can configure the control-plane and ECS controller containers to connect to the servers.
Provide Consul server connection settings to the mesh task module so that the module can configure the control-plane and ECS controller containers to connect to the servers.
1. In your `variables.tf` file, define variables for the host URL and the TLS settings for gRPC and HTTP traffic. Refer to the [mesh task module reference](https://registry.terraform.io/modules/hashicorp/consul-ecs/aws/latest/submodules/gateway-task?tab=inputs) for information about the variables you can define. In the following example, the Consul server address is defined in the `consul_server_hosts` variable:
@ -121,13 +121,13 @@ Provide Consul server connection settings to the mesh task module so that the mo
]
```
When you apply the configuration, the mesh task module interpolates the server configuration variables, builds a `config.tf` file, and injects the settings into the appropriate containers. For additional information about the `config.tf` file, refer to the [JSON schema reference documentation](/consul/docs/ecs/reference/consul-server-json).
When you apply the configuration, the mesh task module interpolates the server configuration variables, builds a `config.tf` file, and injects the settings into the appropriate containers. For additional information about the `config.tf` file, refer to the [JSON schema reference documentation](/consul/docs/ecs/reference/consul-server-json).
## Configure an ECS service to run your task instances
To start a task using the task definition, add the `aws_ecs_service` resource to your configuration to create an ECS service. [ECS services](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs_services.html) are one of the most common ways to start tasks using a task definition.
Reference the `mesh-task` module's `task_definition_arn` output value in your `aws_ecs_service` resource. The following example adds an ECS service for a task definition referenced in as `module.my_task.task_defintion_arn`:
Reference the `mesh-task` module's `task_definition_arn` output value in your `aws_ecs_service` resource. The following example adds an ECS service for a task definition referenced in as `module.my_task.task_definition_arn`:
@ -154,7 +154,7 @@ If you are deploying a test instance of your ECS application, you can apply your
If you intend to leverage multi-datacenter Consul features, such as WAN federation and cluster peering, then you must add the `gateway-task` module for each Consul datacenter in your network. Refer to [Configure the gateway task module](#configure-the-gateway-task-module) for instructions.
## Configure the gateway task module
## Configure the gateway task module
The `gateway-task` module deploys a mesh gateway, which enables service-to-service communication across network areas. Mesh gateways detect the server name indication (SNI) header from the service mesh session and route the connection to the appropriate destination.
@ -163,12 +163,12 @@ Refer to the following documentation for additional information:
- [WAN Federation via Mesh Gateways](/consul/docs/connect/gateways/mesh-gateway/wan-federation-via-mesh-gateways)
- [Service-to-service Traffic Across Datacenters](/consul/docs/connect/gateways/mesh-gateway/service-to-service-traffic-wan-datacenters)
To use mesh gateways, TLS must be enabled in your cluster. Refer to the [requirements section](#requirements) for additional information.
To use mesh gateways, TLS must be enabled in your cluster. Refer to the [requirements section](#requirements) for additional information.
1. Add a `module` block to your Terraform configuration file and specify a label. The label is a unique identifier for the gateway.
1. Add a `source` to the `module` and specify the location of the `gateway-task`. The value must be `hashicorp/consul-ecs/aws//modules/gateway-task`.
1. Specify the following required inputs:
- `ecs_cluster_arn`: The ARN of the ECS cluster for the gateway.
- `ecs_cluster_arn`: The ARN of the ECS cluster for the gateway.
- `family`: Specifies a name for multiple versions of the task. Refer to the [AWS documentation](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definition_parameters.html#family) for details.
- `kind`: Set to `mesh-gateway`
- `subnets`: Specifies a list of subnet IDs where the gateway task should be deployed.
@ -200,9 +200,9 @@ Refer to [gateway-task module in the Terraform registry](https://registry.terraf
Refer to the [gateway task configuration examples](#gateway-task-configuration-examples) for additional example configurations.
## Configure the ECS controller
## Configure the ECS controller
Deploy the ECS controller container to its own ECS task in the cluster. Refer to [ECS controller container](/consul/docs/ecs/reference/architecture#ecs-controller) for details about the container.
Deploy the ECS controller container to its own ECS task in the cluster. Refer to [ECS controller container](/consul/docs/ecs/reference/architecture#ecs-controller) for details about the container.
Verify that you have completed the prerequisites described in [Secure configuration requirements](#secure-configuration-requirements) and complete the following steps to configure the controller container.
@ -211,16 +211,16 @@ Verify that you have completed the prerequisites described in [Secure configurat
1. On the Consul server, create a policy that grants the following access for the controller:
- `acl:write`
- `operator:write`
- `operator:write`
- `node:write`
- `service:write`
The policy allows Consul to generate a token linked to the policy. Refer to [Create a service token](/consul/docs/security/acl/tokens/create/create-a-service-token) for instructions.
1. Create a token and link it to the ACL controller policy. Refer to the [ACL tokens documentation](/consul/docs/security/acl/tokens) for instructions.
### Configure an AWS secrets manager secret
Add the `aws_secretsmanager_secret` resource to your Terraform configuration and specify values for retrieving the CA and TLS certificates. The resource enables services to communicate over TLS and present ACL tokens. The ECS controller also uses the secret manager to retrieve the value of the bootstrap token.
Add the `aws_secretsmanager_secret` resource to your Terraform configuration and specify values for retrieving the CA and TLS certificates. The resource enables services to communicate over TLS and present ACL tokens. The ECS controller also uses the secret manager to retrieve the value of the bootstrap token.
In the following example, Terraform creates the CA certificates for gRPC and HTTPS in the secrets manager. Consul retrieves the CA certificate PEM file from the secret manager so that the mesh task can use TLS for HTTP and gRPC traffic:
@ -375,7 +375,7 @@ Terraform reads all files in the current directory that have a `.tf` file extens
Refer to the [Terraform documentation](/terraform/docs) for more information and Terraform best practices.
## Next steps
After deploying the Consul service mesh infrastructure, you must still define routes between service instances as well as configure the bind address for your applications so that they only receive traffic through the mesh. Refer to the following topics:
- [Configure routes between ECS tasks](/consul/docs/ecs/deploy/configure-routes)
@ -6,25 +6,25 @@ description: Learn about the fields available in the JSON scheme for configuring
# Consul server configuration JSON schema reference
This topic provides reference information about the JSON schema used to build the `config.tf` file. Refer to [Configure Consul server settings](/consul/docs/ecs/deploy/terraform#configure-consul-server-settings) for information about how Consul on ECS uses the JSON schema.
This topic provides reference information about the JSON schema used to build the `config.tf` file. Refer to [Configure Consul server settings](/consul/docs/ecs/deploy/terraform#configure-consul-server-settings) for information about how Consul on ECS uses the JSON schema.
## Configuration model
The following list describes the attributes, data types, and default values, if any, in the `config.tf` file. Click on a value to learn more about the attribute.
@ -33,11 +33,11 @@ The following list describes the attributes, data types, and default values, if
## Specification
This section provides details about the attribes in the `config.tf` file.
This section provides details about the attributes in the `config.tf` file.
### `consulServers`
Parent-level attribute containing all of the server configurations. All other configuraitons in the file are children of the `consulServers` attribute.
Parent-level attribute containing all of the server configurations. All other configurations in the file are children of the `consulServers` attribute.
#### Values
@ -47,7 +47,7 @@ Parent-level attribute containing all of the server configurations. All other co
### `consulServers.hosts`
Map that contains the `skipServerWatch` configuration for Consul server hosts.
Map that contains the `skipServerWatch` configuration for Consul server hosts.
#### Values
@ -56,7 +56,7 @@ Map that contains the `skipServerWatch` configuration for Consul server hosts.
### `consulServers.hosts.skipServerWatch`
Boolean that disables watches on the Consul server. Set to `true` if the Consul server is already behind a load balancer.
Boolean that disables watches on the Consul server. Set to `true` if the Consul server is already behind a load balancer.
#### Values
@ -65,7 +65,7 @@ Boolean that disables watches on the Consul server. Set to `true` if the Consul
### `consulServers.defaults`
Map of default server configurations. Defaults apply to gRPC and HTTP traffic.
Map of default server configurations. Defaults apply to gRPC and HTTP traffic.
#### Values
@ -83,7 +83,7 @@ The following table describes the attributes available in the `defaults` configu
### `consulServers.grpc`
Map of server configuration for gRPC traffic that override attributes defined in `consulServers.defaults`.
Map of server configuration for gRPC traffic that override attributes defined in `consulServers.defaults`.
#### Values
@ -101,7 +101,7 @@ The following table describes the attributes available in the `grpc` configurati
### `consulServers.http`
Map of server configuration for HTTP traffic that override attributes defined in `consulServers.defaults`.
Map of server configuration for HTTP traffic that override attributes defined in `consulServers.defaults`.
@ -47,7 +47,7 @@ The server's DNS port does not need to be open when DNS queries are sent to Cons
If you configure recursors in Consul to upstream DNS servers, then you need outbound access to those servers on port `53`.
To resolve Consul DNS requests when using HCP Consul Dedicated, we recommend running Consul clients and resolving DNS against the clients. If your use case cannot accomodate this recommendation, open a support ticket.
To resolve Consul DNS requests when using HCP Consul Dedicated, we recommend running Consul clients and resolving DNS against the clients. If your use case cannot accommodate this recommendation, open a support ticket.
@ -465,4 +465,4 @@ Use of this method maps to Datadog as described in [Mapping Prometheus Metrics t
The integration, by default, uses a wildcard (`".*"`) to collect **_all_** metrics emitted from the `/v1/agent/metrics` endpoint.
Please refer to the [Agent Telemetry](https://developer.hashicorp.com/consul/docs/agent/telemetry) documentation for a full list and desription of the metrics data collected.
Please refer to the [Agent Telemetry](https://developer.hashicorp.com/consul/docs/agent/telemetry) documentation for a full list and description of the metrics data collected.
| `group` | Specifies a group for the resource type within the Kubernetes cluster. To reference a service in the Consul catalog, set this parameter to `catalog`. | String | None |
| `groupVersion` | Specifies a groupVersion for the resource type within the Kubenretes cluster. To reference a service in the Consul catalog, set this parameter to `v2beta1`. | String | None |
| `groupVersion` | Specifies a groupVersion for the resource type within the Kubernetes cluster. To reference a service in the Consul catalog, set this parameter to `v2beta1`. | String | None |
| `kind` | Specifies the kind of the Kubernetes object the resource applies to. To reference a service in the Consul catalog, set this parameter to `Service`. | String | None |
### `spec.rules`
@ -353,7 +353,7 @@ Specifies the type of resource that the configuration routes traffic to. To refe
| Parameter | Description | Data type | Default |
| --- | --- | --- | --- |
| `group` | Specifies a group for the resource type within the Kubernetes cluster. To reference a service in the Consul catalog, set this parameter to `catalog`. | String | None |
| `groupVersion` | Specifies a groupVersion for the resource type within the Kubenretes cluster. To reference a service in the Consul catalog, set this parameter to `v2beta1`. | String | None |
| `groupVersion` | Specifies a groupVersion for the resource type within the Kubernetes cluster. To reference a service in the Consul catalog, set this parameter to `v2beta1`. | String | None |
| `kind` | Specifies the kind of the Kubernetes object for the resource. To reference a service in the Consul catalog, set this parameter to `Service`. | String | None |
### `spec.rules.backendRefs.filters`
@ -428,9 +428,9 @@ Specifies a path to modify the URL with when a request is forwarded.
### `spec.rules.backendRefs.weight`
Specifies the proportion of requests routed to the specified service.
Specifies the proportion of requests routed to the specified service.
This proportion is relative to the sum of all weights in the [`spec.rules.backendRefs`](#spec-rules-backendrefs) block. As a result, weights do not need to add up to 100. When only one backend is specified and the weight is greater then 0, Consul forwards 100% of traffic to the backend.
This proportion is relative to the sum of all weights in the [`spec.rules.backendRefs`](#spec-rules-backendrefs) block. As a result, weights do not need to add up to 100. When only one backend is specified and the weight is greater then 0, Consul forwards 100% of traffic to the backend.
When this parameter is not specified, Consul defaults to `1`.
@ -634,7 +634,7 @@ Specifies Envoy conditions that cause an automatic retry attempt.
- Default: None
- Data type: Map of strings
### `spec.rules.retries.onConnnectFailure`
### `spec.rules.retries.onConnectFailure`
Enables an automatic retry attempt when a connection failure error occurs.
@ -700,7 +700,7 @@ metadata:
spec:
parentRefs:
- ref:
type:
type:
group: catalog
groupVersion: v2beta1
kind: Service
@ -710,7 +710,7 @@ spec:
rules:
- backendRefs:
- backendRef:
ref:
ref:
type:
group: catalog
groupVersion: v2beta1
@ -720,7 +720,7 @@ spec:
port: "80"
weight: 50
- backendRef:
ref:
ref:
type:
group: catalog
groupVersion: v2beta1
@ -749,7 +749,7 @@ metadata:
spec:
parentRefs:
- ref:
type:
type:
group: catalog
groupVersion: v2beta1
kind: Service
@ -805,4 +805,4 @@ spec:
name: api-admin
# The virtual port number for the "admin-workload" target port.
| `group` | Specifies a group for the resource type within the Kubernetes cluster. To reference a service in the Consul catalog, set this parameter to `catalog`. | String | None |
| `groupVersion` | Specifies a groupVersion for the resource type within the Kubenretes cluster. To reference a service in the Consul catalog, set this parameter to `v2beta1`. | String | None |
| `groupVersion` | Specifies a groupVersion for the resource type within the Kubernetes cluster. To reference a service in the Consul catalog, set this parameter to `v2beta1`. | String | None |
| `kind` | Specifies the kind of the Kubernetes object the resource applies to. To reference a service in the Consul catalog, set this parameter to `Service`. | String | None |
### `spec.rules`
@ -360,7 +360,7 @@ Specifies the type of resource that the configuration routes traffic to. To refe
| Parameter | Description | Data type | Default |
| `group` | Specifies a group for the resource type within the Kubernetes cluster. To reference a service in the Consul catalog, set this parameter to `catalog`. | String | None |
| `groupVersion` | Specifies a groupVersion for the resource type within the Kubenretes cluster. To reference a service in the Consul catalog, set this parameter to `v2beta1`. | String | None |
| `groupVersion` | Specifies a groupVersion for the resource type within the Kubernetes cluster. To reference a service in the Consul catalog, set this parameter to `v2beta1`. | String | None |
| `kind` | Specifies the kind of the Kubernetes object for the resource. To reference a service in the Consul catalog, set this parameter to `Service`. | String | None |
### `spec.rules.backendRefs.filters`
@ -435,9 +435,9 @@ Specifies a path to modify the URL with when a request is forwarded.
### `spec.rules.backendRefs.weight`
Specifies the proportion of requests routed to the specified service.
Specifies the proportion of requests routed to the specified service.
This proportion is relative to the sum of all weights in the [`spec.rules.backendRefs`](#spec-rules-backendrefs) block. As a result, weights do not need to add up to 100. When only one backend is specified and the weight is greater then 0, Consul forwards 100% of traffic to the backend.
This proportion is relative to the sum of all weights in the [`spec.rules.backendRefs`](#spec-rules-backendrefs) block. As a result, weights do not need to add up to 100. When only one backend is specified and the weight is greater then 0, Consul forwards 100% of traffic to the backend.
When this parameter is not specified, Consul defaults to `1`.
@ -687,7 +687,7 @@ Specifies Envoy conditions that cause an automatic retry attempt.
- Default: None
- Data type: Map of strings
### `spec.rules.retries.onConnnectFailure`
### `spec.rules.retries.onConnectFailure`
Enables an automatic retry attempt when a connection failure error occurs.
@ -753,7 +753,7 @@ metadata:
spec:
parentRefs:
- ref:
type:
type:
group: catalog
groupVersion: v2beta1
kind: Service
@ -763,7 +763,7 @@ spec:
rules:
- backendRefs:
- backendRef:
ref:
ref:
type:
group: catalog
groupVersion: v2beta1
@ -773,7 +773,7 @@ spec:
port: "80"
weight: 50
- backendRef:
ref:
ref:
type:
group: catalog
groupVersion: v2beta1
@ -802,7 +802,7 @@ metadata:
spec:
parentRefs:
- ref:
type:
type:
group: catalog
groupVersion: v2beta1
kind: Service
@ -876,7 +876,7 @@ metadata:
spec:
parentRefs:
- ref:
type:
type:
group: catalog
groupVersion: v2beta1
kind: Service
@ -922,4 +922,4 @@ spec:
name: api-admin
# The virtual port number for the "admin-workload" target port.
| `group` | Specifies a group for the resource type within the Kubernetes cluster. To reference a service in the Consul catalog, set this parameter to `catalog`. | String | None |
| `groupVersion` | Specifies a groupVersion for the resource type within the Kubenretes cluster. To reference a service in the Consul catalog, set this parameter to `v2beta1`. | String | None |
| `groupVersion` | Specifies a groupVersion for the resource type within the Kubernetes cluster. To reference a service in the Consul catalog, set this parameter to `v2beta1`. | String | None |
| `kind` | Specifies the kind of the Kubernetes object the resource applies to. To reference a service in the Consul catalog, set this parameter to `Service`. | String | None |
### `spec.rules`
@ -280,14 +280,14 @@ Specifies the type of resource that the configuration routes traffic to. To refe
| `group` | Specifies a group for the resource type within the Kubernetes cluster. To reference a service in the Consul catalog, set this parameter to `catalog`. | String | None |
| `groupVersion` | Specifies a groupVersion for the resource type within the Kubenretes cluster. To reference a service in the Consul catalog, set this parameter to `v2beta1`. | String | None |
| `groupVersion` | Specifies a groupVersion for the resource type within the Kubernetes cluster. To reference a service in the Consul catalog, set this parameter to `v2beta1`. | String | None |
| `kind` | Specifies the kind of the Kubernetes object for the resource. To reference a service in the Consul catalog, set this parameter to `Service`. | String | None |
### `spec.rules.backendRefs.weight`
Specifies the proportion of requests routed to the specified service.
Specifies the proportion of requests routed to the specified service.
This proportion is relative to the sum of all weights in the [`spec.rules.backendRefs`](#spec-rules-backendrefs) block. As a result, weights do not need to add up to 100. When only one backend is specified and the weight is greater then 0, Consul forwards 100% of traffic to the backend.
This proportion is relative to the sum of all weights in the [`spec.rules.backendRefs`](#spec-rules-backendrefs) block. As a result, weights do not need to add up to 100. When only one backend is specified and the weight is greater then 0, Consul forwards 100% of traffic to the backend.
When this parameter is not specified, Consul defaults to `1`.
@ -313,7 +313,7 @@ metadata:
spec:
parentRefs:
- ref:
type:
type:
group: catalog
groupVersion: v2beta1
kind: Service
@ -323,7 +323,7 @@ spec:
rules:
- backendRefs:
- backendRef:
ref:
ref:
type:
group: catalog
groupVersion: v2beta1
@ -333,7 +333,7 @@ spec:
port: "80"
weight: 50
- backendRef:
ref:
ref:
type:
group: catalog
groupVersion: v2beta1
@ -342,4 +342,4 @@ spec:
# The virtual port number for the "admin-workload" target port.
@ -11,11 +11,11 @@ We are pleased to announce the following Consul updates.
## Release highlights
- **Consul v2 Catalog API and Traffic Permission API updates:** Additional improvements were made to the v2 catalog API, which enables support for [multi-port services on Kubernetes](/consul/docs/k8s/multiport). End user facing changes include the ability to use a service's ports in xRoute configurations as opposed to the workload port for reference in the parentRef stanza of the xRoute configuration. In addition, the Traffic Permissions API was changed to only allow `ACTION_DENY` for Consul Enterprise as it will enable future governance related workflows.
- **Consul v2 Catalog API and Traffic Permission API updates:** Additional improvements were made to the v2 catalog API, which enables support for [multi-port services on Kubernetes](/consul/docs/k8s/multiport). End user facing changes include the ability to use a service's ports in xRoute configurations as opposed to the workload port for reference in the parentRef stanza of the xRoute configuration. In addition, the Traffic Permissions API was changed to only allow `ACTION_DENY` for Consul Enterprise as it will enable future governance related workflows.
The v2 Catalog API is currently available for Consul on Kubernetes deployments only. Refer to [Consul v2 architecture](/consul/docs/architecture/v2) for more information.
<Note> The v2 Catalog API and the Traffic Permssions API are in beta and under active development, so we do not recommend using them in production. </Note>
<Note> The v2 Catalog API and the Traffic Permissions API are in beta and under active development, so we do not recommend using them in production. </Note>
- **Consul Long Term Support (LTS) (Enterprise):** Consul Enterprise users can now receive Long Term Support for approximately 2 years on some Consul releases, starting with Consul Enterprise v1.15. During the LTS window, eligible fixes are provided through a new minor release on the affected LTS release branch.
@ -37,7 +37,7 @@ We are pleased to announce the following Consul updates.
Refer to [transparent proxy overview](/consul/docs/k8s/connect/transparent-proxy) and [Consul on ECS overview](/consul/docs/ecs) for more information.
- **Downgrade from Consul Enterprise to Consul Community Edition**: Consul now provides the ability for enterprise users to migrate their deployments to Community edition and disable enterprise features for business continuity. Refer to [Downgrade from Consul Enterprise to the community edition](/consul/docs/enterprise/ent-to-ce-downgrades) for more information.
- **Downgrade from Consul Enterprise to Consul Community Edition**: Consul now provides the ability for enterprise users to migrate their deployments to Community edition and disable enterprise features for business continuity. Refer to [Downgrade from Consul Enterprise to the community edition](/consul/docs/enterprise/ent-to-ce-downgrades) for more information.
- **Consul Snapshot Agent support for multiple destinations (Enterprise):** Consul Enterprise users can now specify [multiple local and remote destinations](/consul/commands/snapshot/agent) for Consul snapshot backups.
@ -62,7 +62,7 @@ Roles may contain the following attributes:
- `Name`: A unique meaningful name for the role. You can specify the role `Name` when linking it to tokens.
- `Description`: (Optional) A human-readable description of the role.
- `Policies`: Specifies a the list of policies that are applicable for the role. The object can reference the policy `ID` or `Name` attribute.
- `TemplatedPolicies`: Specifies a list of templated polcicies that are applicable for the role. See [Templated Policies](#templated-policies) for details.
- `TemplatedPolicies`: Specifies a list of templated policies that are applicable for the role. See [Templated Policies](#templated-policies) for details.
- `ServiceIdentities`: Specifies a list of services that are applicable for the role. See [Service Identities](#service-identities) for details.
- `NodeIdentities`: Specifies a list of nodes that are applicable for the role. See [Node Identities](#node-identities) for details.
- `Namespace`: <EnterpriseAlert inline /> The namespace that the policy resides in. Roles can only be linked to policies that are defined in the same namespace. See [Namespaces](/consul/docs/enterprise/namespaces) for additional information. Requires Consul Enterprise 1.7.0+
@ -72,7 +72,7 @@ Roles may contain the following attributes:
You can specify a templated policy when configuring roles or linking tokens to policies. Templated policies enable you to quickly construct policies for common Consul use cases, rather than creating identical policies for each use cases.
Consul uses templated policies during the authorization process to automatically generate a policy for the use case specified. Consul links the generated policy to the role or token so that it will have permission for the specific use case.
Consul uses templated policies during the authorization process to automatically generate a policy for the use case specified. Consul links the generated policy to the role or token so that it will have permission for the specific use case.
@ -638,7 +638,7 @@ Read access to all imported nodes is granted when either of the following rule s
- `service:write` is granted to any service.
- `node:read` is granted to all nodes.
For Consul Enterprise, either set of rules must be scoped to the requesting services's partition and at least one namespace.
For Consul Enterprise, either set of rules must be scoped to the requesting service's partition and at least one namespace.
You may need similarly scoped [Service Rules](#reading-imported-services) to read Consul data, depending on the endpoint (e.g. `/v1/health/service/:name`).
These permissions are satisfied when using a [service identity](/consul/docs/security/acl/acl-roles#service-identities).
@ -877,7 +877,7 @@ Read access to all imported services is granted when either of the following rul
- `service:write` is granted to any service.
- `service:read` is granted to all services.
For Consul Enterprise, either set of rules must be scoped to the requesting services's partition and at least one namespace.
For Consul Enterprise, either set of rules must be scoped to the requesting service's partition and at least one namespace.
You may need similarly scoped [Node Rules](#reading-imported-nodes) to read Consul data, depending on the endpoint (e.g. `/v1/health/service/:name`).
These permissions are satisfied when using a [service identity](/consul/docs/security/acl/acl-roles#service-identities).
Blake Covarrubias
6 months ago
committed by