e8d53ea30b
This PR modifies references to the envoyproxy/envoy docker image to explicitly include the docker.io prefix. This does not affect existing users, but makes things easier for Podman users, who otherwise need to specify the full name because Podman does not default to docker.io
187 lines
5.5 KiB
Plaintext
187 lines
5.5 KiB
Plaintext
---
|
|
layout: docs
|
|
page_title: sidecar_task Block - Job Specification
|
|
description: |-
|
|
The "sidecar_task" block allows specifying options for configuring
|
|
the task of the sidecar proxies used in Consul Connect integration
|
|
---
|
|
|
|
# `sidecar_task` Block
|
|
|
|
<Placement groups={['job', 'group', 'service', 'connect', 'sidecar_task']} />
|
|
|
|
The `sidecar_task` block allows configuring various options for the proxy
|
|
sidecar or Connect gateway managed by Nomad for the [Consul
|
|
Connect](/nomad/docs/integrations/consul-connect) integration such as
|
|
resource requirements, kill timeouts and more as defined below. It is valid
|
|
only within the context of a [`connect`][connect] block.
|
|
|
|
```hcl
|
|
job "countdash" {
|
|
datacenters = ["dc1"]
|
|
|
|
group "api" {
|
|
network {
|
|
mode = "bridge"
|
|
}
|
|
|
|
service {
|
|
name = "count-api"
|
|
port = "9001"
|
|
|
|
connect {
|
|
sidecar_service {}
|
|
|
|
sidecar_task {
|
|
resources {
|
|
cpu = 500
|
|
memory = 1024
|
|
}
|
|
}
|
|
}
|
|
}
|
|
|
|
task "web" {
|
|
driver = "docker"
|
|
|
|
config {
|
|
image = "hashicorpdev/counter-api:v3"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
## Default Envoy configuration
|
|
|
|
Nomad automatically launches and manages an Envoy task for use as a proxy sidecar
|
|
or connect gateway, when [`sidecar_service`][sidecar_service] or [`gateway`][gateway]
|
|
are configured.
|
|
|
|
The default Envoy task is equivalent to:
|
|
|
|
```hcl
|
|
sidecar_task {
|
|
name = "connect-proxy-<service>"
|
|
# "connect-gateway-<service>" when used as a gateway
|
|
|
|
lifecycle { # absent when used as a gateway
|
|
hook = "prestart"
|
|
sidecar = true
|
|
}
|
|
|
|
driver = "docker"
|
|
|
|
config {
|
|
image = "${meta.connect.sidecar_image}"
|
|
# "${meta.connect.gateway_image}" when used as a gateway
|
|
|
|
args = [
|
|
"-c",
|
|
"${NOMAD_SECRETS_DIR}/envoy_bootstrap.json",
|
|
"-l",
|
|
"${meta.connect.log_level}",
|
|
"--concurrency",
|
|
"${meta.connect.proxy_concurrency}",
|
|
"--disable-hot-restart"
|
|
]
|
|
}
|
|
|
|
logs {
|
|
max_files = 2
|
|
max_file_size = 2 # MB
|
|
}
|
|
|
|
resources {
|
|
cpu = 250 # MHz
|
|
memory = 128 # MB
|
|
}
|
|
|
|
shutdown_delay = "5s"
|
|
}
|
|
```
|
|
|
|
The `meta.connect.sidecar_image`, `meta.connect.gateway_image`, `meta.connect.log_level`,
|
|
and `meta.connect.proxy_concurrency` variables are [client configurable][nodemeta]
|
|
variables with the following defaults:
|
|
|
|
- `sidecar_image` - `(string: "docker.io/envoyproxy/envoy:v${NOMAD_envoy_version}")` - The official
|
|
upstream Envoy Docker image, where `${NOMAD_envoy_version}` is resolved automatically
|
|
by a query to Consul.
|
|
- `gateway_image` - `(string: "docker.io/envoyproxy/envoy:v${NOMAD_envoy_version}")` - The official
|
|
upstream Envoy Docker image, where `${NOMAD_envoy_version}` is resolved automatically
|
|
by a query to Consul.
|
|
- `log_level` - `(string: "info")` - Envoy sidecar log level. "`debug`" is useful for
|
|
debugging Connect related issues.
|
|
- `proxy_concurrency` - `(string: "1")` - The number of [worker threads][worker_threads] the Envoy
|
|
sidecar will run.
|
|
|
|
Custom images can make use of Consul's preferred Envoy version by making use of
|
|
Nomad's version interpolation, e.g.
|
|
|
|
```hcl
|
|
meta.connect.sidecar_image = custom/envoy-${NOMAD_envoy_version}:latest
|
|
```
|
|
|
|
## `sidecar_task` Parameters
|
|
|
|
- `name` `(string: "connect-[proxy|gateway]-<service>")` - Name of the task. Defaults to
|
|
including the name of the service the proxy or gateway is providing.
|
|
|
|
- `driver` `(string: "docker")` - Driver used for the sidecar task.
|
|
|
|
- `user` `(string: nil)` - Determines which user is used to run the task, defaults
|
|
to the same user the Nomad client is being run as.
|
|
|
|
- `config` `(map: nil)` - Configuration provided to the driver for initialization.
|
|
Keys and values support [runtime variable interpolation][interpolation].
|
|
|
|
- `env` `(map: nil)` - Map of environment variables used by the driver.
|
|
|
|
- `resources` <code>([Resources][resources])</code> - Resources needed by the sidecar task.
|
|
|
|
- `meta` `(map: nil)` - Arbitrary metadata associated with this task that's opaque to Nomad.
|
|
|
|
- `logs` <code>([Logs][]: nil)</code> - Specifies logging configuration for the
|
|
`stdout` and `stderr` of the task.
|
|
|
|
- `kill_timeout` `(string: "5s")` - Time between signalling a task that will be
|
|
killed and killing it.
|
|
|
|
- `shutdown_delay` `(string: "5s")` - Delay between deregistering the task from
|
|
Consul and sending it a signal to shutdown.
|
|
|
|
- `kill_signal` `(string:SIGINT)` - Kill signal to use for the task, defaults to SIGINT.
|
|
|
|
## `sidecar_task` Examples
|
|
|
|
The following example configures resources for the sidecar task and other configuration.
|
|
|
|
```hcl
|
|
sidecar_task {
|
|
resources {
|
|
cpu = 500
|
|
memory = 1024
|
|
}
|
|
|
|
env {
|
|
FOO = "abc"
|
|
}
|
|
|
|
shutdown_delay = "5s"
|
|
}
|
|
|
|
```
|
|
|
|
[connect]: /nomad/docs/job-specification/connect 'Nomad connect Job Specification'
|
|
[gateway]: /nomad/docs/job-specification/gateway
|
|
[group]: /nomad/docs/job-specification/group 'Nomad group Job Specification'
|
|
[interpolation]: /nomad/docs/runtime/interpolation 'Nomad interpolation'
|
|
[job]: /nomad/docs/job-specification/job 'Nomad job Job Specification'
|
|
[logs]: /nomad/docs/job-specification/logs 'Nomad logs Job Specification'
|
|
[resources]: /nomad/docs/job-specification/resources 'Nomad resources Job Specification'
|
|
[sidecar_service]: /nomad/docs/job-specification/sidecar_service 'Nomad sidecar service Specification'
|
|
[task]: /nomad/docs/job-specification/task 'Nomad task Job Specification'
|
|
[nodemeta]: /nomad/docs/configuration/client#meta
|
|
[worker_threads]: https://www.envoyproxy.io/docs/envoy/latest/operations/cli#cmdoption-concurrency
|