Skip to content

Commit

Permalink
[Docs] Connect Sidecar Proxies: Fixes 'must may' typo and adds format…
Browse files Browse the repository at this point in the history
…ting to follow other docs (#5397)

* Fixes 'must may' typo and adds formatting to follow other docs

* Reverts local_service_port docs to state its optional
  • Loading branch information
johncowen authored and judithpatudith committed Mar 18, 2019
1 parent c5bd1a7 commit 69ac5d0
Showing 1 changed file with 27 additions and 27 deletions.
54 changes: 27 additions & 27 deletions website/source/docs/connect/proxies.html.md
Original file line number Diff line number Diff line change
Expand Up @@ -39,15 +39,15 @@ provide information about the service they represent.
To declare a service as a proxy, the service definition must contain
the following fields:

* `kind` (string) must be set to `connect-proxy`. This declares that the
* `kind` `(string)` must be set to `connect-proxy`. This declares that the
service is a proxy type.

* `proxy.destination_service_name` (string) must be set to the service that
* `proxy.destination_service_name` `(string)` must be set to the service that
this proxy is representing. Note that this replaces `proxy_destination` in
versions 1.2.0 to 1.3.0.

* `port` must be set so that other Connect services can discover the exact
address for connections. `address` is optional if the service is being
* `port` `(int)` must be set so that other Connect services can discover the
exact address for connections. `address` is optional if the service is being
registered against an agent, since it'll inherit the node address.

Minimal Example:
Expand All @@ -70,18 +70,18 @@ Connect-capable endpoint for "redis" will find this proxy.

Most Connect proxies are deployed as "sidecars" which means they are co-located
with a single service instance which they represent and proxy all inbound
traffic to. In this case the following fields must may also be set:
traffic to. In this case the following fields should also be set:

* `proxy.destination_service_id` (string) is set to the _id_ (and not the
_name_ if they are different) of the specific service instance that is being
proxied. The proxied service is assumed to be registered on the same agent
although it's not strictly validated to allow for un-coordinated
registrations.
* `proxy.destination_service_id` `(string: <required>)` is set to the _id_
(and not the _name_ if they are different) of the specific service instance
that is being proxied. The proxied service is assumed to be registered on
the same agent although it's not strictly validated to allow for
un-coordinated registrations.

* `proxy.local_service_port` (string) must specify the port the proxy should use
to connect to the _local_ service instance.
* `proxy.local_service_port` `(int: <required>)` must specify the port the
proxy should use to connect to the _local_ service instance.

* `proxy.local_service_address` (string) can be set to override the IP or
* `proxy.local_service_address` `(string: "")` can be set to override the IP or
hostname the proxy should use to connect to the _local_ service. Defaults to
`127.0.0.1`.

Expand Down Expand Up @@ -113,33 +113,33 @@ until at least 1.5.0 but it's highly recommended to switch to using

#### Proxy Parameters

- `destination_service_name` `string: <required>` - Specifies the _name_ of the
- `destination_service_name` `(string: <required>)` - Specifies the _name_ of the
service this instance is proxying. Both side-car and centralized
load-balancing proxies must specify this. It is used during service
discovery to find the correct proxy instances to route to for a given service
name.

- `destination_service_id` `string: <optional>` - Specifies the _ID_ of a single
- `destination_service_id` `(string: "")` - Specifies the _ID_ of a single
specific service instance that this proxy is representing. This is only valid
for side-car style proxies that run on the same node. It is assumed that the
service instance is registered via the same Consul agent so the ID is unique
and has no node qualifier. This is useful to show in tooling which proxy
instance is a side-car for which application instance and will enable
fine-grained analysis of the metrics coming from the proxy.

- `local_service_address` `string: <optional>` - Specifies the address a side-car
- `local_service_address` `(string: "")` - Specifies the address a side-car
proxy should attempt to connect to the local application instance on.
Defaults to 127.0.0.1.

- `local_service_port` `int: <optional>` - Specifies the port a side-car
- `local_service_port` `(int: <optional>)` - Specifies the port a side-car
proxy should attempt to connect to the local application instance on.
Defaults to the port advertised by the service instance identified by
`destination_service_id` if it exists otherwise it may be empty in responses.

- `config` `object: <optional>` - Specifies opaque config JSON that will be
- `config` `(object: {})` - Specifies opaque config JSON that will be
stored and returned along with the service instance from future API calls.

- `upstreams` `array<Upstream>: <optional>` - Specifies the upstream services
- `upstreams` `(array<Upstream>: [])` - Specifies the upstream services
this proxy should create listeners for. The format is defined in
[Upstream Configuration Reference](#upstream-configuration-reference).

Expand Down Expand Up @@ -189,20 +189,20 @@ followed by documentation for each attribute.
},
```

* `destination_name` `string: <required>` - Specifies the name of the service or
prepared query to route connect to. The prepared query should be the name
* `destination_name` `(string: <required>)` - Specifies the name of the service
or prepared query to route connect to. The prepared query should be the name
or the ID of the prepared query.
* `local_bind_port` `int: <required>` - Specifies the port to bind a local
* `local_bind_port` `(int: <required>)` - Specifies the port to bind a local
listener to for the application to make outbound connections to this upstream.
* `local_bind_address` `string: <optional>` - Specifies the address to bind a
* `local_bind_address` `(string: "")` - Specifies the address to bind a
local listener to for the application to make outbound connections to this
upstream. Defaults to `127.0.0.1`.
* `destination_type` `string: <optional>` - Speficied the type of discovery
* `destination_type` `(string: "")` - Speficied the type of discovery
query to use to find an instance to connect to. Valid values are `service` or
`prepared_query`. Defaults to `service`.
* `datacenter` `string: <optional>` - Specifies the datacenter to issue the
* `datacenter` `(string: "")` - Specifies the datacenter to issue the
discovery query too. Defaults to the local datacenter.
* `config` `object: <optional>` - Specifies opaque configuration options that
* `config` `(object: {})` - Specifies opaque configuration options that
will be provided to the proxy instance for this specific upstream. Can contain
any valid JSON object. This might be used to configure proxy-specific features
like timeouts or retries for the given upstream. See the [built-in proxy
Expand All @@ -219,4 +219,4 @@ If an application requires dynamic dependencies that are only available
at runtime, it must currently [natively integrate](/docs/connect/native.html)
with Connect. After natively integrating, the HTTP API or
[DNS interface](/docs/agent/dns.html#connect-capable-service-lookups)
can be used.
can be used.

0 comments on commit 69ac5d0

Please sign in to comment.