Specs

connect(
  upstream_params :: [upstream :: atom() | String.t() | map()],
  template :: map(),
  proxy ::
    nil
    | {proxy_service_name :: String.t() | atom(),
       proxy_service_id :: String.t() | atom()}
) ::
  {:ok, []}
  | {:ok, [ok: addr :: address(), error: err :: term()]}
  | {:error, :invalid_state}
  | {:error, :service_not_owned}
  | term()

Prepares mesh upstream endpoint for new user upstream client connection.

Basic use

Basic use of connect/3 requires upstream_params argument to be a list of upstream names defined as strings or atoms:

iex(1)> MeshxConsul.connect(["service1", :service2])
{:ok,
[
 ok: {:tcp, {127, 0, 0, 1}, 65535},
 ok: {:tcp, {127, 0, 0, 1}, 65534}
]}

Function returns list of tuples (keyword list), one tuple result per each upstream_params element, preserved ordering. Tuple elements are {:ok, address()} if upstream addition was successful or {:error, reason} if operation failed for given upstream. If upstream is already registered with proxy, function will return {:ok, address()} with mesh upstream endpoint address() fetched from Consul proxy sidecar registration.

Customization

Customization of template function argument requires understanding of Consul upstream service configuration options.

If upstream_params list element is defined as upstream name (atom or string), it is used to create following Mustache hash:

# 1. Generate new mesh upstream endpoint address:
{:tcp, ip, port} = MeshxConsul.Service.GenTcpPort.new(:hi)
# 2. Build Mustache hash:
%{"name" => to_string(upstream_name), "address" => ip, "port" => port}
# Example Mustache hash:
%{"name" => "service1", "address" => "127.0.0.1", "port" => 65535}

If upstream_params element is defined by user as map(), keys "address" and "port" are used to inject automatically generated TCP port address similarly to code on snippet above. Automatic address injection can be cancelled by assigning both "address" and "port" keys some values, "address" must be not empty string and "port" any integer value, eg.: %{"address" => "undefined", "port" => -999_999}. If user provided values for both "address" and "port", they will be fetched from input map and used to build result {:ok, address()} tuple for given upstream.

If Mustache upstream template is not defined as function argument, :upstream_template option value defined in config/config.exs will be used. If both are undefined (nil, empty map or empty list), following built-in upstream Mustache template will be used:

%{
  "DestinationName" => "{{name}}",
  "LocalBindAddress" => "{{address}}",
  "LocalBindPort" => "{{$port$}}"
}

Using Mustache hash from previous snippet, above template would register with proxy sidecar service following upstream:

{
  "DestinationType":"service",
  "DestinationName":"service1",
  "LocalBindAddress":"127.0.0.1",
  "LocalBindPort":65535,
  "MeshGateway":{}
}

Note: fields required by Consul in upstream registration template: "DestinationName" (string) and "LocalBindPort" (int).

Last connect/3 function argument proxy specifies service registered with sidecar-proxy as a tuple {proxy_service_name, proxy_service_id}. Sidecar proxy service will be used as parent service for all upstreams in upstream_params. If proxy service name/id is not provided, it will be generated by concatenation of prefix "upstream-" with host name. If proxy service doesn't exist, new service will be started by running MeshxConsul.start({proxy_service_name, proxy_service_id}). If start/4 fails, generated error will cascade to connect/3 and upstreams will not be added to service mesh.

Running MeshxConsul.connect(["service1"]) on host h11 should register following services with Consul agent:

{
"upstream-h11": {
  "ID": "upstream-h11",
  "Service": "upstream-h11",
  "Tags": [],
  "Meta": {},
  "Port": 0,
  "Address": "",
  "Weights": {
    "Passing": 1,
    "Warning": 1
  },
  "EnableTagOverride": false,
  "Datacenter": "my-dc"
},
"upstream-h11-sidecar-proxy": {
  "Kind": "connect-proxy",
  "ID": "upstream-h11-sidecar-proxy",
  "Service": "upstream-h11-sidecar-proxy",
  "Tags": [],
  "Meta": {},
  "Port": 21001,
  "Address": "",
  "Weights": {
    "Passing": 1,
    "Warning": 1
  },
  "EnableTagOverride": false,
  "Proxy": {
    "DestinationServiceName": "upstream-h11",
    "DestinationServiceID": "upstream-h11",
    "LocalServiceAddress": "127.0.0.1",
    "LocalServicePort": 1024,
    "Upstreams": [
      {
        "DestinationType": "service",
        "DestinationName": "service1",
        "LocalBindAddress": "127.0.0.1",
        "LocalBindPort": 65535,
        "MeshGateway": {}
      }
    ],
    "MeshGateway": {},
    "Expose": {}
  },
  "Datacenter": "my-dc"
}
}

Specs

disconnect(
  upstreams :: [upstream :: atom() | String.t()],
  proxy_service_id :: nil | atom() | String.t(),
  restart_proxy? :: boolean()
) :: {:ok, []} | {:ok, [deleted_upstream_name :: String.t()]} | (err :: term())

Disconnects mesh upstreams endpoints created earlier with connect/3.

Function will deregister upstreams list from proxy_service_id parent sidecar proxy service:

iex(1)> MeshxConsul.connect(["service1", "service2"])
{:ok,
[
 ok: {:tcp, {127, 0, 0, 1}, 65535},
 ok: {:tcp, {127, 0, 0, 1}, 65534}
]}
iex(2)> MeshxConsul.list_upstream
["service1", "service2"]
iex(3)> MeshxConsul.disconnect(["service1", "service2", "service3"])
{:ok, ["service2", "service1"]}
iex(4)> MeshxConsul.list_upstream
[]

Function returns list of disconnected upstreams. If proxy_service_id is not provided as function argument, default proxy ID will be used: "upstream-" concatenated with host name.

Deregistering upstream from sidecar proxy service doesn't close established connections. Closing existing connections can be done by:

• cold proxy restart: set restart_proxy? function argument to true,
• hot proxy restart if supported by proxy, example script for Envoy: [github].

Specs

info(service_id :: String.t() | atom()) ::
  {:ok, info :: map()} | {:error, error :: term()} | term()

Consul configuration info for service_id.

Function returns result of Consul API GET query at path /agent/service/:service_id.

iex(1)> MeshxConsul.start({"service1", "service1-mynode-myhost"})
{:ok, "service1-mynode-myhost", {:tcp, {127, 0, 0, 1}, 1024}}
iex(2)> MeshxConsul.info("service1-mynode-myhost")
{:ok,
%{
 "Address" => "",
 "ContentHash" => "aaaaaa0000000000",
 "Datacenter" => "my-dc",
 "EnableTagOverride" => false,
 "ID" => "service1-mynode-myhost",
 "Meta" => %{},
 "Port" => 0,
 "Service" => "service1",
 "Tags" => [],
 "Weights" => %{"Passing" => 1, "Warning" => 1}
}}

Specs

list() :: [String.t()]

List services registered on current node.

iex(1)> MeshxConsul.start({"service1", "service1-mynode-myhost"})
{:ok, "service1-mynode-myhost", {:tcp, {127, 0, 0, 1}, 1024}}
iex(2)> MeshxConsul.list
["service1-mynode-myhost"]

Specs

list_upstream() :: [String.t()]

List upstreams registered with default proxy service.

Default proxy service ID: "upstream-" concatenated with host name.

Specs

list_upstream(service_id :: String.t() | atom()) :: [String.t()]

List upstreams registered with proxy service_id.

iex(1)> MeshxConsul.connect(["service1", :service2])
{:ok,
[
 ok: {:tcp, {127, 0, 0, 1}, 65535},
 ok: {:tcp, {127, 0, 0, 1}, 65534}
]}
iex(2)> MeshxConsul.list
["upstream-h11"]
iex(3)> MeshxConsul.list_upstream
["service1", "service2"]
iex(4)> MeshxConsul.list_upstream("upstream-h11")
["service1", "service2"]
iex(5)> MeshxConsul.list_upstream("not_existing")
{:error, :service_not_owned}

Specs

start(
  params ::
    (name :: atom() | String.t())
    | {name :: atom() | String.t(), id :: atom() | String.t()}
    | map(),
  template :: [
    registration: map(),
    ttl: nil | %{id: String.t(), status: String.t(), ttl: pos_integer()},
    proxy: nil | [String.t()]
  ],
  force_registration? :: boolean(),
  timeout :: non_neg_integer()
) ::
  {:ok, service_id :: String.t(), addr :: address()}
  | {:ok, :already_started}
  | {:error, :invalid_state}
  | {:error, :service_not_owned}
  | {:error, :service_alive_timeout}
  | term()

Prepares mesh service endpoint when starting new user service provider.

Basic use

iex(1)> MeshxConsul.start(:service1)
{:ok, "service1-h11", {:tcp, {127, 0, 0, 1}, 1024}}

If successful function returns tuple with registered service ID and mesh service endpoint address(). Service ID by default is service name concatenated with host name. User can start service providing both service name and service ID:

iex(1)> MeshxConsul.start({"service1", "service1-mynode-myhost"})
{:ok, "service1-mynode-myhost", {:tcp, {127, 0, 0, 1}, 1024}}

If service with same service ID was already registered by current node and service is healthy in Consul agent registry, function will return {:ok, :already_started}. If service with same service ID is registered with Consul agent but registration was not executed by current node function will return by default {:error, :service_not_owned}. User can force service re-registration with current node by setting force_registration? to true. If service was registered by current node but cannot be found in Consul agent registry function will return {:error, :invalid_state}.

If timeout is set greater than 0, start/4 will wait timeout milliseconds for service to have "passing" state in Consul agent after registration. If service is not healthy and alive after timeout function will return {:error, :service_alive_timeout}. If timeout is to 0 this check will be skipped.

Customization

Consul agent documentation suggested reading:

• service registration options,
• health checks,
• Connect commands.

If params function argument defines service as atom, string or {name, id} tuple following Mustache hash is created:

# 1. Generate new mesh service endpoint address:
{:tcp, ip, port} = MeshxConsul.Service.GenTcpPort.new(:lo)
# 2a. Build Mustache hash if name is given:
%{"name" => name, "id" => name <> "-" <> hostname, "address" => ip, "port" => port}
# 2b. Build Mustache hash if {name, id} is given:
%{"name" => name, "id" => id, "address" => ip, "port" => port}
# Example Mustache hash:
%{"name" => "service1", "id" => "service1-my-hostname", "address" => "127.0.0.1", "port" => 1024}

If params argument is defined by user as map(), keys "address" and "port" are used to inject automatically generated TCP port address similarly to code on snippet above. Automatic address injection can be cancelled by assigning both "address" and "port" keys some values, "address" must be not empty string and "port" any integer value, eg.: %{"address" => "undefined", "port" => -999_999}. If user provided values for both "address" and "port", they will be fetched from input map and used to build function result {:ok, service_id, address()} tuple.

If template is not defined as function argument, value of config/config.exs :service_template key will be used. If user template does not contain all required keys [:registration, :ttl, :proxy], missing keys will be taken from following built-in defaults:

  [
    registration: %{
      "ID" => "{{id}}",
      "Name" => "{{name}}",
      "Checks" => [
        %{
          "Name" => "TTL check",
          "CheckID" => "ttl:{{id}}",
          "TTL" => "10s"
        }
      ],
      "Connect" => %{
        "SidecarService" => %{
          "Proxy" => %{
            "LocalServiceAddress" => "{{address}}",
            "LocalServicePort" => "{{$port$}}"
          }
        }
      }
    },
    ttl: %{
      id: "ttl:{{id}}",
      status: "passing",
      ttl: 5_000
    },
    proxy: ["/bin/sh", "-c", "consul connect proxy -log-level err -sidecar-for {{id}}"]
  ]

Example:

# start service using Envoy Proxy instead of default Consul Connect Proxy:
iex(1)>  MeshxConsul.start("service1", proxy: ["/bin/sh", "-c", "consul connect envoy -sidecar-for {{id}} -- -l error"])
{:ok, "service1-h11", {:tcp, {127, 0, 0, 1}, 1024}}

Specs

stop(service_id :: String.t() | atom()) :: :ok | {:error, :service_not_owned}

Stops service service_id started with start/4. Function reverses actions performed by start/4:

• proxy binary command is terminated,
• TTL health check worker is stopped,
• service is deregistered with Consul agent.

If service was not started by current node function returns: {:error, :service_not_owned}.

iex(1)> MeshxConsul.start(:service1)
{:ok, "service1-h11", {:tcp, {127, 0, 0, 1}, 1024}}
iex(2)> MeshxConsul.stop("service1-h11")
:ok
iex(3)> MeshxConsul.stop("service1-h11")
{:error, :service_not_owned}