Skip to content

Commit 83ff20b

Browse files
trujillo-adamtrujillo-adam
committed
added Define Services usage page
1 parent f5ec6d7 commit 83ff20b

File tree

2 files changed

+371
-1
lines changed

2 files changed

+371
-1
lines changed

‎website/content/docs/services/usage/define-services.mdx‎

Lines changed: 366 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,366 @@
1+
---
2+
layout: docs
3+
page_title: Define Services
4+
description: >-
5+
Learn how to define services so that they are discoverable in your network.
6+
---
7+
8+
# Define Services
9+
10+
This topic describes how to define services so that they can be discovered by other services. Refer to [Services Overview](/consul/docs/services/services) for additional information.
11+
12+
## Overview
13+
14+
You must tell Consul about the services deployed to your network if you want them to be discoverable. You can define services in a configuration file or send the service definition parameters as a payload to the `/agent/service/register` API endpoint. Refer to [Register Services and Health Checks](/consul/docs/discovery/usage/register-services-and-health-checks) for details about how to register services with Consul.
15+
16+
You can define multiple services individually using `service` blocks or group multiple services into the same `services` configuration block. Refer to [Define multiple services in a single file](#define-multiple-services-in-a-single-file) for additional information.
17+
18+
Consul applies default values for service definition parameters that you do not specify, but instead of manually setting common configurations individually, you can use the `service-defaults` configuration entry to specify default global values for services in the datacenter. Refer to [Define service defaults](#define-service-defaults) for additional information.
19+
20+
## Requirements
21+
22+
The core service discovery features are available in all versions of Consul.
23+
24+
### Service defaults
25+
To use the [service defaults configuration entry](#define-service-defaults), verify that your installation meets the following requirements:
26+
27+
- Consul 1.5.0+
28+
- Consul 1.8.4+ is required to use the `ServiceDefaults` custom resource on Kubernetes
29+
30+
### ACLs
31+
If ACLs are enabled, resources in your network must present a token with `service:read` access to read a service defaults configuration entry.
32+
33+
You must also present a token with `service:write` access to create, update, or delete a service defaults configuration entry.
34+
35+
Service configurations must also contain and present an ACL token to perform anti-entropy syncs and deregistration operations. Refer to [Tag override and anti-entropy](/consul/docs/discovery/overview#tag-override-and-anti-entropy) for additional information.
36+
37+
On Consul Enterprise, you can register services with specific namespaces if the services' ACL tokens are scoped to the namespace. Services registered with a service definition do not inherit the namespace associated with the ACL token specified in the `token` field. The `namespace` and the `token` parameters must be included in the service definition for the service to be registered to the namespace that the ACL token is scoped to.
38+
39+
## Define a service
40+
Create a file for your service configurations and add a `service` block. The `service` block contains the parameters that configure various aspects of the service, including how it is discovered by other services in the network. The only required parameter is `name`. Refer to [Service Definition Reference](/consul/docs/discovery/configuration/service-definition-reference) for details about the configuration options.
41+
42+
For Kubernetes environments, you can enable the [`connectInject`](/consul/docs/k8s/connect#installation-and-configuration) configuration in your Consul Helm chart so that Consul automatically adds a sidecar to each of your pods. Consul uses the Kubernetes `Service` definition as a reference.
43+
44+
The following example defines a service named `redis` that is available on port `80`. By default, the service has the IP address of the agent node.
45+
46+
<CodeTabs>
47+
<CodeBlockConfig heading="service.hcl">
48+
49+
```hcl
50+
service {
51+
name = "redis"
52+
id = "redis"
53+
port = 80
54+
tags = ["primary"]
55+
56+
meta = {
57+
custom_meta_key = "custom_meta_value"
58+
}
59+
60+
tagged_addresses = {
61+
lan = {
62+
address = "192.168.0.55"
63+
port = 8000
64+
}
65+
66+
wan = {
67+
address = "198.18.0.23"
68+
port = 80
69+
}
70+
}
71+
}
72+
```
73+
74+
</CodeBlockConfig>
75+
<CodeBlockConfig heading="service.json">
76+
77+
```json
78+
{
79+
"service": [
80+
{
81+
"id": "redis",
82+
"meta": [
83+
{
84+
"custom_meta_key": "custom_meta_value"
85+
}
86+
],
87+
"name": "redis",
88+
"port": 80,
89+
"tagged_addresses": [
90+
{
91+
"lan": [
92+
{
93+
"address": "192.168.0.55",
94+
"port": 8000
95+
}
96+
],
97+
"wan": [
98+
{
99+
"address": "198.18.0.23",
100+
"port": 80
101+
}
102+
]
103+
}
104+
],
105+
"tags": [
106+
"primary"
107+
]
108+
}
109+
]
110+
}
111+
```
112+
</CodeBlockConfig>
113+
<CodeBlockConfig heading="service.yaml">
114+
115+
```yaml
116+
service:
117+
- id: redis
118+
meta:
119+
- custom_meta_key: custom_meta_value
120+
name: redis
121+
port: 80
122+
tagged_addresses:
123+
- lan:
124+
- address: 192.168.0.55
125+
port: 8000
126+
wan:
127+
- address: 198.18.0.23
128+
port: 80
129+
tags:
130+
- primary
131+
```
132+
</CodeBlockConfig>
133+
</CodeTabs>
134+
135+
### Health checks
136+
137+
You can add a `check` or `checks` block to your service configuration to define one or more health checks that monitor the health of your services. Refer to [Define Health Checks](/consul/docs/services/usage/checks) for additional information.
138+
139+
### Register a service
140+
141+
You can register your service using the [`consul services` command](/consul/commands/services) or by calling the [`/agent/services` API endpoint](/consul/api-docs/agent/services). Refer to [Register Services and Health Checks](/consul/docs/discovery/usage/register) for details.
142+
143+
## Define service defaults
144+
You can define global default values for services by creating and applying a `service-defaults` configuration entry containing the values.
145+
146+
Create a file for the configuration entry and specify the required fields. If you are authoring `service-defaults` in HCL or JSON, the `Kind` and `Name` fields are required. On Kubernetes, the `apiVersion`, `kind`, and `metadata.name` fields are required. Refer to [Service Defaults Reference](/consul/docs/connect/config-entries/service-defaults) for details about the configuration options.
147+
148+
The following example instructs services named `counting` to send up to `512` concurrent requests to a mesh gateway:
149+
150+
<CodeTabs tabs={[ "HCL", "Kubernetes YAML", "JSON" ]}>
151+
152+
```hcl
153+
Kind = "service-defaults"
154+
Name = "counting"
155+
156+
UpstreamConfig = {
157+
Defaults = {
158+
MeshGateway = {
159+
Mode = "local"
160+
}
161+
Limits = {
162+
MaxConnections = 512
163+
MaxPendingRequests = 512
164+
MaxConcurrentRequests = 512
165+
}
166+
}
167+
168+
Overrides = [
169+
{
170+
Name = "dashboard"
171+
MeshGateway = {
172+
Mode = "remote"
173+
}
174+
}
175+
]
176+
}
177+
```
178+
```yaml
179+
apiVersion: consul.hashicorp.com/v1alpha1
180+
kind: ServiceDefaults
181+
metadata:
182+
name: counting
183+
spec:
184+
upstreamConfig:
185+
defaults:
186+
meshGateway:
187+
mode: local
188+
limits:
189+
maxConnections: 512
190+
maxPendingRequests: 512
191+
maxConcurrentRequests: 512
192+
overrides:
193+
- name: dashboard
194+
meshGateway:
195+
mode: remote
196+
```
197+
```json
198+
{
199+
"Kind": "service-defaults",
200+
"Name": "counting",
201+
"UpstreamConfig": {
202+
"Defaults": {
203+
"MeshGateway": {
204+
"Mode": "local"
205+
},
206+
"Limits": {
207+
"MaxConnections": 512,
208+
"MaxPendingRequests": 512,
209+
"MaxConcurrentRequests": 512
210+
}
211+
},
212+
"Overrides": [
213+
{
214+
"Name": "dashboard",
215+
"MeshGateway": {
216+
"Mode": "remote"
217+
}
218+
}
219+
]
220+
}
221+
}
222+
```
223+
</CodeTabs>
224+
225+
### Apply service defaults
226+
227+
You can apply your `service-defaults` configuration entry using the [`consul config` command](/consul/commands/config) or by calling the [`/config` API endpoint](/consul/api-docs/config). In Kubernetes environments, apply the `service-defaults` custom resource definitions (CRD) to implement and manage Consul configuration entries.
228+
229+
Refer to the following topics for details about applying configuration entries:
230+
- [How to Use Configuration Entries](/consul/docs/agent/config-entries)
231+
- [Custom Resource Definitions for Consul on Kubernetes](/consul/docs/k8s/crds)
232+
233+
## Define multiple services in a single file
234+
235+
The `services` block contains an array of `service` objects. It is a wrapper that enables you to define multiple services in the service definition and instruct Consul to expect more than just a single service configuration. As a result, you can register multiple services in a single `consul services register` command. Note that the `/agent/service/register` API endpoint does not support the `services` parameter.
236+
237+
In the following example, the service definition configures an instance of the `redis` service tagged as `primary` running on port `6000`. It also configures an instance of the service tagged as `secondary` running on port `7000`.
238+
239+
<CodeTabs heading="Multiple Service Definitions">
240+
241+
<CodeBlockConfig filename="redis-services.hcl">
242+
243+
```hcl
244+
services {
245+
id = "red0"
246+
name = "redis"
247+
tags = [
248+
"primary"
249+
]
250+
address = ""
251+
port = 6000
252+
checks = [
253+
{
254+
args = ["/bin/check_redis", "-p", "6000"]
255+
interval = "5s"
256+
timeout = "20s"
257+
}
258+
]
259+
}
260+
services {
261+
id = "red1"
262+
name = "redis"
263+
tags = [
264+
"delayed",
265+
"secondary"
266+
]
267+
address = ""
268+
port = 7000
269+
checks = [
270+
{
271+
args = ["/bin/check_redis", "-p", "7000"]
272+
interval = "30s"
273+
timeout = "60s"
274+
}
275+
]
276+
}
277+
278+
```
279+
280+
</CodeBlockConfig>
281+
282+
<CodeBlockConfig filename="redis-services.json">
283+
284+
```json
285+
{
286+
"services": [
287+
{
288+
"id": "red0",
289+
"name": "redis",
290+
"tags": [
291+
"primary"
292+
],
293+
"address": "",
294+
"port": 6000,
295+
"checks": [
296+
{
297+
"args": ["/bin/check_redis", "-p", "6000"],
298+
"interval": "5s",
299+
"timeout": "20s"
300+
}
301+
]
302+
},
303+
{
304+
"id": "red1",
305+
"name": "redis",
306+
"tags": [
307+
"delayed",
308+
"secondary"
309+
],
310+
"address": "",
311+
"port": 7000,
312+
"checks": [
313+
{
314+
"args": ["/bin/check_redis", "-p", "7000"],
315+
"interval": "30s",
316+
"timeout": "60s"
317+
}
318+
]
319+
},
320+
...
321+
]
322+
}
323+
```
324+
325+
</CodeBlockConfig>
326+
</CodeTabs>
327+
328+
## Modify anti-entropy synchronization
329+
330+
By default, the Consul agent uses anti-entropy mechanisms to maintain information about services and service health, and synchronize local states with the Consul catalog. You can enable the `enable_tag_override` option in the service configuration, which lets external agents change the tags for a service. This can be useful in situations where an external monitoring service needs to be the source of truth for tag information. Refer [Anti-entropy](/consul/docs/architecture/anti-entropy) for details.
331+
332+
Add the `enable_tag_override` option to the `service` block and set the value to `true`:
333+
334+
<CodeTabs tabs={[ "HCL","JSON" ]}>
335+
336+
337+
```hcl
338+
service {
339+
## ...
340+
enable_tag_override = true
341+
## ...
342+
}
343+
```
344+
345+
```json
346+
"service": {
347+
## ...
348+
"enable_tag_override": true,
349+
## ...
350+
}
351+
```
352+
353+
</CodeTabs>
354+
355+
This configuration only applies to the locally registered service. Nodes that register the same service apply the `enable_tag_override` and other service configurations independently. The tags for a service registered on one node update are not affected by operations performed on services with the same name registered on other nodes.
356+
357+
Refer to [`enable_tag_override`](/consul/docs/services/configuration/service-config-ref#enable-tag-override) for additional configuration information.
358+
359+
## Services in service mesh environments
360+
Defining services for service mesh environments on virtual machines and in Kubernetes requires a different workflow.
361+
362+
### Define service mesh proxies
363+
You can register services to function as service mesh or sidecar proxies so that they can facilitate communication between other services across your network. Refer to [Service Mesh Proxy Overview](/consul/docs/connect/registration) for additional information.
364+
365+
### Define services in Kubernetes
366+
You can enable the services running in Kubernetes and Consul to sync automatically. Doing so ensures that Kubernetes services are available to Consul agents and services in Consul can be available as first-class Kubernetes services. Refer to [Service Sync for Consul on Kubernetes](/consul/docs/k8s/service-sync) for details.

‎website/data/docs-nav-data.json‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -312,10 +312,14 @@
312312
{
313313
"title": "Define",
314314
"routes": [
315+
{
316+
"title": "Define Services",
317+
"path": "services/usage/define-services"
318+
},
315319
{
316320
"title": "Define Health Checks",
317321
"path": "services/usage/checks"
318-
}
322+
}
319323
]
320324
},
321325
{

0 commit comments

Comments
 (0)