June 20-22 Announcing HashiConf Europe full schedule: keynotes, sessions, labs & more Register Now
  • Overview
    • Consul on Kubernetes
    • Control access with Consul API Gateway
    • Discover Services with Consul
    • Enforce Zero Trust Networking with Consul
    • Load Balancing with Consul
    • Manage Traffic with Consul
    • Multi-Platform Service Mesh with Consul
    • Network Infrastructure Automation with Consul
    • Observability with Consul
  • Enterprise
  • Tutorials
  • Docs
  • API
  • CLI
  • Community
GitHub
Download
Try HCP Consul
    • v1.12.x (latest)
    • v1.11.x
    • v1.10.x
    • v1.9.x
    • v1.8.x
    • Overview
      • Overview
      • What is a Service Mesh?
      • Overview
      • Chef, Puppet, etc.
      • Nagios
      • SkyDNS
      • SmartStack
      • Serf
      • Eureka
      • Istio
      • Envoy and Other Proxies
      • Custom Solutions
    • Overview
    • Manual Bootstrap
    • Consul Agent
    • Glossary
    • Required Ports
    • Bootstrapping a Datacenter
    • Cloud Auto-join
    • Server Performance
    • Kubernetes
  • API
  • Commands (CLI)
    • Register Services - Service Definitions
    • Find Services - DNS Interface
    • Monitor Services - Check Definitions
    • Overview
    • How Service Mesh Works
    • Configuration
      • Overview
      • Ingress Gateway
      • Mesh
      • Exported Services
      • Proxy Defaults
      • Service Defaults
      • Service Intentions
      • Service Resolver
      • Service Router
      • Service Splitter
      • Terminating Gateway
      • Overview
      • Envoy
      • Built-in Proxy
      • Proxy Integration
      • Managed (Deprecated)
      • Overview
      • Proxy Service Registration
      • Sidecar Service Registration
    • Service-to-service permissions - Intentions
    • Service-to-service permissions - Intentions (Legacy Mode)
    • Transparent Proxy
      • Overview
      • UI Visualization
      • Overview
      • Discovery Chain
    • Connectivity Tasks
    • Distributed Tracing
      • Overview
        • WAN Federation
        • Enabling Service-to-service Traffic Across Datacenters
        • Enabling Service-to-service Traffic Across Admin Partitions
      • Ingress Gateways
      • Terminating Gateways
    • Nomad
    • Kubernetes
      • Overview
      • Go Integration
      • Overview
      • Built-In CA
      • Vault
      • ACM Private CA
    • Develop and Debug
    • Security
    • Overview
    • Installation
    • Technical Specifications
    • Common Errors
    • Upgrades
    • Overview
    • Architecture
      • Installing Consul on Kubernetes
      • Installing Consul K8s CLI
        • Minikube
        • Kind
        • AKS (Azure)
        • EKS (AWS)
        • GKE (Google Cloud)
        • Red Hat OpenShift
        • Self Hosted Kubernetes
        • Consul Clients Outside Kubernetes
        • Consul Servers Outside Kubernetes
        • Single Consul Datacenter in Multiple Kubernetes Clusters
        • Consul Enterprise
        • Overview
        • Federation Between Kubernetes Clusters
        • Federation Between VMs and Kubernetes
        • Overview
        • Systems Integration
          • Overview
          • Bootstrap Token
          • Enterprise License
          • Gossip Encryption Key
          • Partition Token
          • Replication Token
          • Server TLS
          • Service Mesh Certificates
          • Snapshot Agent Config
        • WAN Federation
      • Compatibility Matrix
      • Overview
      • Transparent Proxy
      • Ingress Gateways
      • Terminating Gateways
      • Ingress Controllers
      • Configuring a Connect CA Provider
      • Health Checks
        • Metrics
    • Service Sync
      • Overview
      • Upgrade An Existing Cluster to CRDs
    • Annotations and Labels
    • Consul DNS
      • Upgrading Consul on Kubernetes
      • Upgrading Consul K8s CLI
      • Uninstall
      • Certificate Rotation
      • Gossip Encryption Key Rotation
      • Configure TLS on an Existing Cluster
      • Common Error Messages
      • FAQ
    • Helm Chart Configuration
    • Consul K8s CLI Reference
    • Overview
    • Requirements
    • Task Resource Usage
      • Installation
      • Secure Configuration
      • Migrate Existing Tasks
      • Installation
      • Secure Configuration
      • ACL Controller
    • Architecture
    • Consul Enterprise
    • Configuration Reference
    • Overview
      • Installation
      • Requirements
      • Configure
      • Run Consul-Terraform-Sync
    • Architecture
      • Overview
      • Status
      • Tasks
      • Overview
      • task
    • Configuration
    • Tasks
    • Terraform Modules
      • Overview
      • License
      • Terraform Cloud Driver
      • Overview
      • Terraform
      • Terraform Cloud
    • Compatibility
    • Consul KV
    • Sessions
    • Watches
    • Overview
      • General
      • CLI Reference
      • Configuration Reference
    • Configuration Entries
    • Telemetry
    • Sentinel
    • RPC
    • Overview
      • ACL System Overview
      • Tokens
      • Policies
      • Roles
      • Rules Reference
      • Legacy Mode
      • Token Migration
      • ACLs in Federated Datacenters
        • Overview
        • Kubernetes
        • JWT
        • OIDC
        • AWS IAM
    • Encryption
      • Overview
      • Core
      • Network Infrastructure Automation
    • Overview
    • Admin Partitions
    • Audit Logging
    • Automated Backups
    • Automated Upgrades
    • Enhanced Read Scalability
    • Single sign-on - OIDC
    • Redundancy Zones
    • Advanced Federation
    • Network Segments
    • Namespaces
    • NIA with TFE
    • Sentinel
      • Overview
      • FAQ
    • Overview
    • Improving Consul Resilience
    • Anti-Entropy
    • Consensus Protocol
    • Gossip Protocol
    • Jepsen Testing
    • Network Coordinates
    • Consul Integration Program
    • NIA Integration Program
    • Vault Integration
    • Proxy Integration
  • Consul Tools
    • Overview
    • Compatibility Promise
    • Specific Version Details
      • Overview
      • General Process
      • Upgrading to 1.2.4
      • Upgrading to 1.6.9
      • Upgrading to 1.8.13
      • Upgrading to 1.10.0
    • Common Error Messages
    • FAQ
    • Overview
      • v1.11.x
      • v1.10.x
      • v1.9.x
      • v0.1.x
      • v0.2.x
      • v0.4.x
      • v0.3.x
      • v0.2.x
      • v0.5.x
      • v0.6.0-beta
    • Overview
    • ACL
  • Guides
Type '/' to Search

»Annotations and Labels

»Overview

Consul on Kubernetes provides a few options for customizing how connect-inject behavior should be configured. This allows the user to configure natively configure Consul on select Kubernetes resources (i.e. pods, services).

  • Annotations
  • Labels

»Annotations

Resource annotations could be used on the Kubernetes pod to control connect-inject behavior.

  • consul.hashicorp.com/connect-inject - If this is "true" then injection is enabled. If this is "false" then injection is explicitly disabled. The default injector behavior requires pods to opt-in to injection by specifying this value as "true". This default can be changed in the injector's configuration if desired.

  • consul.hashicorp.com/transparent-proxy - If this is "true", this Pod will run with transparent proxy enabled. This means you can use Kubernetes DNS to access upstream services and all inbound and outbound traffic within the pod is redirected to go through the proxy.

  • consul.hashicorp.com/transparent-proxy-overwrite-probes - If this is "true" and transparent proxy is enabled, the Connect injector will overwrite Kubernetes HTTP probes to point to the Envoy proxy.

  • consul.hashicorp.com/transparent-proxy-exclude-inbound-ports - A comma-separated list of inbound ports to exclude from traffic redirection when running in transparent proxy mode.

  • consul.hashicorp.com/transparent-proxy-exclude-outbound-cidrs - A comma-separated list of outbound CIDRs to exclude from traffic redirection when running in transparent proxy mode.

  • consul.hashicorp.com/transparent-proxy-exclude-outbound-ports - A comma-separated list of outbound ports to exclude from traffic redirection when running in transparent proxy mode.

  • consul.hashicorp.com/transparent-proxy-exclude-uids - A comma-separated list of additional user IDs to exclude from traffic redirection when running in transparent proxy mode.

  • consul.hashicorp.com/connect-service - For pods that accept inbound connections, this specifies the name of the service that is being served. This defaults to the name of the Kubernetes service associated with the pod.

    If using ACLs, this must be the same name as the Pod's ServiceAccount.

  • consul.hashicorp.com/connect-service-port - For pods that accept inbound connections, this specifies the port to route inbound connections to. This is the port that the service is listening on. The service port defaults to the first exposed port on any container in the pod. If specified, the value can be the name of a configured port, such as "http" or it can be a direct port value such as "8080". This is the port of the service, the proxy public listener will listen on a dynamic port.

  • consul.hashicorp.com/connect-service-upstreams - The list of upstream services that this pod needs to connect to via Connect along with a static local port to listen for those connections. When transparent proxy is enabled, this annotation is optional.

    • Services

      The name of the service is the name of the service registered with Consul. You can optionally specify datacenters with this annotation.

      annotations:
        "consul.hashicorp.com/connect-service-upstreams":"[service-name]:[port]:[optional datacenter]"
      
      annotations:
        "consul.hashicorp.com/connect-service-upstreams":"[service-name]:[port]:[optional datacenter]"
      
    • Consul Enterprise Namespaces

      If running Consul Enterprise 1.7+, your upstream services may be running in different namespaces. The upstream namespace can be specified after the service name as [service-name].[namespace]. See Consul Enterprise Namespaces below for more details on configuring the injector.

      annotations:
        "consul.hashicorp.com/connect-service-upstreams":"[service-name].[service-namespace]:[port]:[optional datacenter]"
      
      annotations:
        "consul.hashicorp.com/connect-service-upstreams":"[service-name].[service-namespace]:[port]:[optional datacenter]"
      

      NOTE: If the namespace is not specified it will default to the namespace of the source service.

      WARNING: Setting a namespace when not using Consul Enterprise or using a version < 1.7 is not supported. It will be treated as part of the service name.

    • Prepared Query

      annotations:
        'consul.hashicorp.com/connect-service-upstreams': 'prepared_query:[query name]:[port]'
      
      annotations:
        'consul.hashicorp.com/connect-service-upstreams': 'prepared_query:[query name]:[port]'
      
    • Multiple Upstreams

      If you would like to specify multiple services or upstreams, delimit them with commas

      annotations:
        "consul.hashicorp.com/connect-service-upstreams":"[service-name]:[port]:[optional datacenter],[service-name]:[port]:[optional datacenter]"
      
      annotations:
        "consul.hashicorp.com/connect-service-upstreams":"[service-name]:[port]:[optional datacenter],[service-name]:[port]:[optional datacenter]"
      
      annotations:
        "consul.hashicorp.com/connect-service-upstreams":"[service-name]:[port]:[optional datacenter],prepared_query:[query name]:[port]"
      
      annotations:
        "consul.hashicorp.com/connect-service-upstreams":"[service-name]:[port]:[optional datacenter],prepared_query:[query name]:[port]"
      
  • consul.hashicorp.com/envoy-extra-args - A space-separated list of arguments to be passed to the injected envoy binary.

    annotations:
      consul.hashicorp.com/envoy-extra-args: '--log-level debug --disable-hot-restart'
    
    annotations:
      consul.hashicorp.com/envoy-extra-args: '--log-level debug --disable-hot-restart'
    
  • consul.hashicorp.com/kubernetes-service - Specifies the name of the Kubernetes service used for Consul service registration. This is useful when multiple Kubernetes services reference the same deployment. Any service that does not match the name specified in this annotation is ignored. When not specified no service is ignored.

    annotations:
      consul.hashicorp.com/kubernetes-service: 'service-name-to-use'
    
    annotations:
      consul.hashicorp.com/kubernetes-service: 'service-name-to-use'
    
  • consul.hashicorp.com/service-tags - A comma separated list of tags that will be applied to the Consul service and its sidecar.

    annotations:
      consul.hashicorp.com/service-tags: foo,bar,baz
    
    annotations:
      consul.hashicorp.com/service-tags: foo,bar,baz
    

    If you need your tag to have a comma in it you can escape the comma with \,. For example, consul.hashicorp.com/service-tags: foo\,bar\,baz will become the single tag foo,bar,baz.

  • consul.hashicorp.com/service-meta-<YOUR_KEY> - Set Consul meta key/value pairs that will be applied to the Consul service and its sidecar. The key will be what comes after consul.hashicorp.com/service-meta-, e.g. consul.hashicorp.com/service-meta-foo: bar will result in foo: bar.

    annotations:
      consul.hashicorp.com/service-meta-foo: baz
      consul.hashicorp.com/service-meta-bar: baz
    
    annotations:
      consul.hashicorp.com/service-meta-foo: baz
      consul.hashicorp.com/service-meta-bar: baz
    
  • consul.hashicorp.com/sidecar-proxy- - Override default resource settings for the sidecar proxy container. The defaults are set in Helm config via the connectInject.sidecarProxy.resources key.

    • consul.hashicorp.com/sidecar-proxy-cpu-limit - Override the default CPU limit.
    • consul.hashicorp.com/sidecar-proxy-cpu-request - Override the default CPU request.
    • consul.hashicorp.com/sidecar-proxy-memory-limit - Override the default memory limit.
    • consul.hashicorp.com/sidecar-proxy-memory-request - Override the default memory request.
  • consul.hashicorp.com/consul-sidecar- - Override default resource settings for the consul-sidecar container. The defaults are set in Helm config via the global.consulSidecarContainer.resources key.

    • consul.hashicorp.com/consul-sidecar-cpu-limit - Override the default CPU limit.
    • consul.hashicorp.com/consul-sidecar-cpu-request - Override the default CPU request.
    • consul.hashicorp.com/consul-sidecar-memory-limit - Override the default memory limit.
    • consul.hashicorp.com/consul-sidecar-memory-request - Override the default memory request.
  • consul.hashicorp.com/enable-metrics - Override the default Helm value connectInject.metrics.defaultEnabled.

  • consul.hashicorp.com/enable-metrics-merging - Override the default Helm value connectInject.metrics.defaultEnableMerging.

  • consul.hashicorp.com/merged-metrics-port - Override the default Helm value connectInject.metrics.defaultMergedMetricsPort.

  • consul.hashicorp.com/prometheus-scrape-port - Override the default Helm value connectInject.metrics.defaultPrometheusScrapePort.

  • consul.hashicorp.com/prometheus-scrape-path - Override the default Helm value connectInject.metrics.defaultPrometheusScrapePath.

  • consul.hashicorp.com/service-metrics-port - Set the port where the Connect service exposes metrics.

  • consul.hashicorp.com/service-metrics-path - Set the path where the Connect service exposes metrics.

  • consul.hashicorp.com/connect-inject-mount-volume - Comma separated list of container names to mount the connect-inject volume into. The volume will be mounted at /consul/connect-inject. The connect-inject volume contains Consul internals data needed by the other sidecar containers, for example the consul binary, and the Pod's Consul ACL token. This data can be valuable for advanced use-cases, such as making requests to the Consul API from within application containers.

»Labels

Resource labels could be used on a Kubernetes service to control connect-inject behavior.

  • consul.hashicorp.com/service-ignore - This label can be set on a Kubernetes Service. If set to "true", the service will not be used to register a Consul endpoint. This can be useful in cases where 2 or more services point to the same deployment. Consul cannot register multiple endpoints to the same deployment. This label can be used to tell the endpoint registration to ignore all services except for the one which should be used for routing requests using Consul.
github logoEdit this page
IntroGuidesDocsCommunityPrivacySecurityBrandConsent Manager