HashiConf 2025 Don't miss the live stream of HashiConf Day 2 happening now View live stream
Consul
Consul Home

You are viewing documentation for version v1.21.x. View latest version.

Service mesh parameters for Consul agent configuration files

The page provides reference information for service mesh parameters in a Consul agent configuration file.

Service Mesh Parameters

The noun connect is used throughout this documentation to refer to the connect subsystem that provides Consul's service mesh capabilities.

  • connect This object allows setting options for the Connect feature.

    The following sub-keys are available:

    • enabled (Defaults to true) Controls whether Connect features are enabled on this agent. Should be enabled on all servers in the cluster in order for service mesh to function properly. Will be set to true automatically if auto_config.enabled or auto_encrypt.allow_tls is true.

    • enable_mesh_gateway_wan_federation (Defaults to false) Controls whether cross-datacenter federation traffic between servers is funneled through mesh gateways. This was added in Consul 1.8.0.

    • ca_provider Controls which CA provider to use for the service mesh's CA. Currently only the aws-pca, consul, and vault providers are supported. This is only used when initially bootstrapping the cluster. For an existing cluster, use the Update CA Configuration Endpoint.

    • ca_config An object which allows setting different config options based on the CA provider chosen. This is only used when initially bootstrapping the cluster. For an existing cluster, use the Update CA Configuration Endpoint.

      The following providers are supported:

      AWS ACM Private CA Provider (ca_provider = "aws-pca")

      • existing_arn The Amazon Resource Name (ARN) of an existing private CA in your ACM account. If specified, Consul will attempt to use the existing CA to issue certificates.

      Consul CA Provider (ca_provider = "consul")

      • private_key The PEM contents of the private key to use for the CA.

      • root_cert The PEM contents of the root certificate to use for the CA.

      Vault CA Provider (ca_provider = "vault")

      • address The address of the Vault server to connect to.

      • token The Vault token to use. In Consul 1.8.5 and later, if the token has the renewable flag set, Consul will attempt to renew its lease periodically after half the duration has expired.

      • root_pki_path The path to use for the root CA pki backend in Vault. This can be an existing backend with a CA already configured, or a blank/unmounted backend in which case Consul will automatically mount/generate the CA. The Vault token given above must have sudo access to this backend, as well as permission to mount the backend at this path if it is not already mounted.

      • intermediate_pki_path The path to use for the temporary intermediate CA pki backend in Vault. Consul will overwrite any data at this path in order to generate a temporary intermediate CA. The Vault token given above must have write access to this backend, as well as permission to mount the backend at this path if it is not already mounted.

      • auth_method Vault auth method to use for logging in to Vault. Please see Vault Auth Methods for more information on how to configure individual auth methods. If auth method is provided, Consul will obtain a new token from Vault when the token can no longer be renewed.

        • type The type of Vault auth method.

        • mount_path The mount path of the auth method. If not provided the auth method type will be used as the mount path.

        • params The parameters to configure the auth method. Please see Vault Auth Methods for information on how to configure the auth method you wish to use. If using the Kubernetes auth method, Consul will read the service account token from the default mount path /var/run/secrets/kubernetes.io/serviceaccount/token if the jwt parameter is not provided.

      Common CA Config Options

      There are also a number of common configuration options supported by all providers:

      • csr_max_concurrent Sets a limit on the number of Certificate Signing Requests that can be processed concurrently. Defaults to 0 (disabled). This is useful when you want to limit the number of CPU cores available to the server for certificate signing operations. For example, on an 8 core server, setting this to 1 will ensure that no more than one CPU core will be consumed when generating or rotating certificates. Setting this is recommended instead of csr_max_per_second when you want to limit the number of cores consumed since it is simpler to reason about limiting CSR resources this way without artificially slowing down rotations. Added in 1.4.1.

      • csr_max_per_second Sets a rate limit on the maximum number of Certificate Signing Requests (CSRs) the servers will accept. This is used to prevent CA rotation from causing unbounded CPU usage on servers. It defaults to 50 which is conservative – a 2017 Macbook can process about 100 per second using only ~40% of one CPU core – but sufficient for deployments up to ~1500 service instances before the time it takes to rotate is impacted. For larger deployments we recommend increasing this based on the expected number of server instances and server resources, or use csr_max_concurrent instead if servers have more than one CPU core. Setting this to zero disables rate limiting. Added in 1.4.1.

      • leaf_cert_ttl Specifies the upper bound on the expiry of a leaf certificate issued for a service. In most cases a new leaf certificate will be requested by a proxy before this limit is reached. This is also the effective limit on how long a server outage can last (with no leader) before network connections will start being rejected. Defaults to 72h.

        You can specify a range from one hour (minimum) up to one year (maximum) using the following units: h, m, s, ms, us (or µs), ns, or a combination of those units, e.g. 1h5m.

        This value is also used when rotating out old root certificates from the cluster. When a root certificate has been inactive (rotated out) for more than twice the current leaf_cert_ttl, it will be removed from the trusted list.

      • intermediate_cert_ttl Specifies the expiry for the intermediate certificates. Defaults to 8760h (1 year). Must be at least 3 times leaf_cert_ttl.

      • root_cert_ttl Specifies the expiry for a root certificate. Defaults to 10 years as 87600h. This value, if provided, needs to be higher than the intermediate certificate TTL.

        This setting applies to all Consul CA providers.

        For the Vault provider, this value is only used if the backend is not initialized at first.

        This value is also applied on the ca set-config command.

      • private_key_type The type of key to generate for this CA. This is only used when the provider is generating a new key. If private_key is set for the Consul provider, or existing root or intermediate PKI paths given for Vault then this will be ignored. Currently supported options are ec or rsa. Default is ec.

        It is required that all servers in a datacenter have the same config for the CA. It is recommended that servers in different datacenters use the same key type and size, although the built-in CA and Vault provider will both allow mixed CA key types.

        Some CA providers (currently Vault) will not allow cross-signing a new CA certificate with a different key type. This means that if you migrate from an RSA-keyed Vault CA to an EC-keyed CA from any provider, you may have to proceed without cross-signing which risks temporary connection issues for workloads during the new certificate rollout. We highly recommend testing this outside of production to understand the impact and suggest sticking to same key type where possible.

        Note that this only affects CA keys generated by the provider. Leaf certificate keys are always EC 256 regardless of the CA configuration.

      • private_key_bits The length of key to generate for this CA. This is only used when the provider is generating a new key. If private_key is set for the Consul provider, or existing root or intermediate PKI paths given for Vault then this will be ignored.

        Currently supported values are:

  • locality Enterprise: Specifies a map of configurations that set the region and zone of the Consul agent. When specified on server agents, locality applies to all partitions on the server. When specified on clients, locality applies to all services registered to the client. Configure this field to enable Consul to route traffic to the nearest physical service instance. This field is intended for use primarily with VM and Nomad workloads. Refer to Route traffic to local upstreams for additional information.

    • region: String value that specifies the region where the Consul agent is running. Consul assigns this value to services registered to that agent. When service proxy regions match, Consul is able to prioritize routes between service instances in the same region over instances in other regions. You must specify values that are consistent with how regions are defined in your network, for example us-west-1 for networks in AWS.
    • zone: String value that specifies the availability zone where the Consul agent is running. Consul assigns this value to services registered to that agent. When service proxy regions match, Consul is able to prioritize routes between service instances in the same region and zone over instances in other regions and zones. When healthy service instances are available in multiple zones within the most-local region, Consul prioritizes instances that also match the downstream proxy's zone. You must specify values that are consistent with how zones are defined in your network, for example us-west-1a for networks in AWS.