HashiCorp Developer AI Private beta now available Sign up today
Consul
Consul Home

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

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 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.

Overview

Complete the following steps to deploy a service mesh proxy:

  1. It is not required, but you can create a proxy defaults configuration entry that contains global passthrough settings for all Envoy proxies.
  2. Create a service definition file and specify the proxy configurations in the proxy block.
  3. Register the service using the API or CLI.
  4. 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.

Requirements

If ACLs are enabled and you want to configure global Envoy settings using the proxy defaults configuration entry, you must present a token with operator:write permissions. Refer to Create a service token for additional information.

Configure global Envoy passthrough settings

If you want to define global passthrough settings for all Envoy proxies, create a proxy defaults configuration entry and specify default settings, such as access log configuration. Note that service defaults configuration entries override proxy defaults and individual service configurations override both configuration entries.

  1. Create a proxy defaults configuration entry and specify the following parameters:
    • Kind: Must be set to proxy-defaults
    • Name: Must be set to global
  2. Configure any additional settings you want to apply to all proxies. Refer to Proxy defaults configuration entry reference for details about all settings available in the configuraiton entry.
  3. Apply the configuration by either calling the /config HTTP API endpoint or running the consul config write CLI command. The following example writes a proxy defaults configuration entry from a local HCL file using the CLI:
$ consul config write proxy-defaults.hcl

Define service mesh proxy

Create a service definition file and configure the following fields to define a service mesh proxy:

  1. Set the kind field to connect-proxy. Refer to the services configuration reference for information about other kinds of proxies you can declare.
  2. Specify a name for the proxy service in the name field. Consul applies the configurations to any proxies you bootstrap with the same name.
  3. In the proxy.destination_service_name field, specify the name of the service that the proxy represents.
  4. Configure any additional proxy behaviors that you want to implement in the proxy block. Refer to the Service mesh proxy configuration reference for information about all parameters.
  5. 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 for example configurations.

Register the service

Provide the service definition to the Consul agent to register your proxy service. You can use the same methods for registering proxy services as you do for registering application services:

  • Place the service definition in a Consul agent's configuration directory and start, restart, or reload the agent. Use this method when implementing changes to an existing proxy service.
  • Use the consul services register command to register the proxy service with a running Consul agent.
  • Call the /agent/service/register HTTP API endpoint to register the proxy service with a running Consul agent.

Refer to Register services and health checks for instructions.

In the following example, the consul services register command registers a proxy service stored in proxy.hcl:

$ consul services register proxy.hcl

Start the proxy

Envoy requires a bootstrap configuration file before it can start. Use the consul connect envoy command 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:

$ consul connect envoy -proxy-id=web-proxy

For details about operating an Envoy proxy in Consul, refer to the Envoy proxy reference.