June 20-22 Announcing HashiConf Europe full schedule: keynotes, sessions, labs & more Register Now
  • Overview
    • Batch Processing Workloads
    • Edge Workload Management
    • Non-Containerized Application Orchestration
    • Simple Container Orchestration
  • Enterprise
  • Tutorials
  • Docs
  • API
  • Plugins
  • Tools
  • Community
GitHub—Stars on GitHub
Download
    • v1.3.x (latest)
    • v1.2.x
    • v1.1.x
    • v1.0.x
    • v0.12.x
    • v0.11.x
    • Overview
    • Quickstart
      • Overview
      • Requirements
      • Reference Architecture
      • Deployment Guide
    • Windows Service
    • Overview
    • Specific Version Details
    • Overview
    • Consul
    • Consul Service Mesh
    • Vault Integration

    • Overview
    • Architecture
      • Overview
      • Base
      • Task Drivers
      • Devices
      • Storage
      • Overview
      • Internals
      • Preemption
    • Consensus Protocol
    • Filesystem
    • Gossip Protocol
    • Security Model
    • Overview
    • acl
    • audit
    • autopilot
    • client
    • consul
    • plugin
    • sentinel
    • search
    • server
    • server_join
    • telemetry
    • tls
    • ui
    • vault
    • Overview
      • Overview
      • bootstrap
      • policy apply
      • policy delete
      • policy info
      • policy list
      • token create
      • token delete
      • token info
      • token list
      • token self
      • token update
    • agent
    • agent-info
      • Overview
      • exec
      • fs
      • logs
      • restart
      • signal
      • status
      • stop
      • Overview
      • validate
      • Overview
      • fail
      • list
      • pause
      • promote
      • resume
      • status
      • unblock
      • Overview
      • list
      • status
      • Overview
      • allocs
      • deployments
      • dispatch
      • eval
      • history
      • init
      • inspect
      • plan
      • periodic force
      • promote
      • revert
      • run
      • scale
      • scaling-events
      • status
      • stop
      • validate
      • Overview
      • get
    • monitor
      • Overview
      • apply
      • delete
      • inspect
      • list
      • status
      • Overview
      • config
      • drain
      • eligibility
      • status
      • Overview
      • api
      • autopilot get-config
      • autopilot set-config
      • debug
      • keygen
      • keyring
      • metrics
      • raft info
      • raft list-peers
      • raft logs
      • raft remove-peer
      • raft state
      • snapshot agent
      • snapshot inspect
      • snapshot restore
      • snapshot save
      • snapshot state
      • Overview
      • status
      • Overview
      • apply
      • delete
      • init
      • inspect
      • list
      • status
      • Overview
      • apply
      • dismiss
      • info
      • list
      • Overview
      • policy info
      • policy list
      • Overview
      • apply
      • delete
      • list
      • read
      • Overview
      • force-leave
      • join
      • members
      • Overview
      • service delete
      • service info
      • service list
    • status
      • Overview
      • gc
      • reconcile summaries
    • ui
    • version
      • Overview
      • create
      • delete
      • deregister
      • detach
      • init
      • register
      • snapshot create
      • snapshot delete
      • snapshot list
      • status

    • Overview
      • Overview
      • Expressions
        • Overview
          • chunklist
          • coalesce
          • coalescelist
          • compact
          • concat
          • contains
          • distinct
          • element
          • flatten
          • index
          • keys
          • length
          • lookup
          • merge
          • range
          • reverse
          • setintersection
          • setproduct
          • setunion
          • slice
          • sort
          • values
          • zipmap
          • can
          • convert
          • try
          • bcrypt
          • md5
          • rsadecrypt
          • sha1
          • sha256
          • sha512
          • formatdate
          • timeadd
          • base64decode
          • base64encode
          • csvdecode
          • jsondecode
          • jsonencode
          • urlencode
          • yamldecode
          • yamlencode
          • abspath
          • basename
          • dirname
          • file
          • fileexists
          • fileset
          • pathexpand
          • cidrhost
          • cidrnetmask
          • cidrsubnet
          • cidrsubnets
          • abs
          • ceil
          • floor
          • log
          • max
          • min
          • parseint
          • pow
          • signum
          • chomp
          • format
          • formatlist
          • indent
          • join
          • lower
          • regex_replace
          • replace
          • split
          • strrev
          • substr
          • title
          • trim
          • trimprefix
          • trimspace
          • trimsuffix
          • upper
          • uuidv4
          • uuidv5
      • Locals
      • Syntax
      • Variables
    • artifact
    • affinity
    • check_restart
    • connect
    • constraint
    • csi_plugin
    • device
    • dispatch_payload
    • env
    • ephemeral_disk
    • expose
    • gateway
    • group
    • job
    • lifecycle
    • logs
    • meta
    • migrate
    • multiregion
    • network
    • parameterized
    • periodic
    • proxy
    • reschedule
    • resources
    • restart
    • scaling
    • service
    • sidecar_service
    • sidecar_task
    • spread
    • task
    • template
    • update
    • upstreams
    • vault
    • volume
    • volume_mount
    • Overview
    • Docker
    • Isolated Fork/Exec
    • Java
    • Podman
    • QEMU
    • Raw Fork/Exec
      • Overview
      • containerd
      • Firecracker driver
      • Jailtask driver
      • Lightrun
      • LXC
      • Pot
      • Rkt Deprecated
      • Rookout
      • Singularity
      • systemd-nspawn
      • Windows IIS
      • Overview
      • ECS
    • Overview
      • Overview
      • Nvidia
      • USB Beta
  • Schedulers
    • Overview
    • Runtime Environment
    • Variable Interpolation
    • Overview
      • Overview
      • apm
      • dynamic_application_sizing
      • http
      • nomad
      • policy
      • policy_eval
      • source
      • strategy
      • target
      • telemetry
    • API
    • CLI
    • Policy
    • Telemetry
      • Overview
        • Overview
        • Datadog
        • Nomad API
        • Prometheus
        • Overview
        • Dynamic Application Sizing Average
        • Dynamic Application Sizing Max
        • Dynamic Application Sizing Percentile
        • Fixed Value
        • Pass-Through
        • Target Value
        • Threshold
        • Overview
        • Amazon Web Services Autoscaling Group
        • Azure Virtual Machine Scale Set
        • Dynamic Application Sizing
        • Google Cloud Engine Managed Instance Group
        • Nomad Task Group
      • Community
      • Overview
      • Checks
      • Node Selector Strategy
        • Overview
        • Base
        • APM
        • Strategy
        • Target
    • Overview
    • Operating Nomad Agents
    • Monitoring Nomad
    • Metrics Reference
    • Cluster Management
    • Transport Security
    • Access Control

    • Overview
    • Alternative to Kubernetes
    • Supplement to Kubernetes
  • Nomad Ecosystem
  • Nomad Partnerships
  • Who Uses Nomad
    • Overview
      • Overview
      • FAQ
  • FAQ
Type '/' to Search

»sidecar_task Stanza

Placementjob -> group -> service -> connect -> sidecar_task

The sidecar_task stanza allows configuring various options for the proxy sidecar or Connect gateway managed by Nomad for the Consul Connect integration such as resource requirements, kill timeouts and more as defined below. It is valid only within the context of a connect stanza.

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 = "hashicorpnomad/counter-api:v3"
      }
    }
  }
}
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 = "hashicorpnomad/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 or gateway are configured.

The default Envoy task is equivalent to:

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"
}
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 variables with the following defaults:

  • sidecar_image - (string: "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: "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 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.

meta.connect.sidecar_image = custom/envoy-${NOMAD_envoy_version}:latest
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.

  • env (map: nil) - Map of environment variables used by the driver.

  • resources (Resources) - Resources needed by the sidecar task.

  • meta (map: nil) - Arbitrary metadata associated with this task that's opaque to Nomad.

  • logs (Logs: nil) - 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.

   sidecar_task {
     resources {
       cpu = 500
       memory = 1024
     }

     env {
       FOO = "abc"
     }

     shutdown_delay = "5s"
   }

   sidecar_task {
     resources {
       cpu = 500
       memory = 1024
     }

     env {
       FOO = "abc"
     }

     shutdown_delay = "5s"
   }

github logoEdit this page
DocsAPIResourcesPrivacySecurityPress KitConsent Manager