Skip to content
Tutorials Center
My learning

Topics

Lesson 7 of 37 ยท Service Discovery

Service Tags, Metadata and Weights

Use Consul tags to filter instances, meta for descriptive data, and weights to steer DNS traffic. Covers canary and versioned lookups, enable_tag_override and limits.

A bare service name is a blunt tool. Real systems need finer questions: "give me only the v2 instances", "which team owns this?", "send most traffic to the big machines". Consul answers these with three optional fields on a service definition: tags, meta and weights.

The definitions are read-only on this site; the stand-ins model filtering and weighted selection so you can feel how they behave.

Tags

Tags are short string labels attached to a service instance:

HCL
service {
  name = "web"
  id   = "web-1"
  port = 8080
  tags = ["v2", "primary", "az-a"]
}

Tags are searchable. A DNS name can include a tag as a prefix:

TEXT
web.service.consul              # all healthy web instances
v2.web.service.consul           # only instances tagged v2
primary.web.service.consul      # only instances tagged primary

In the HTTP API, add tag:

Terminal
$ curl "http://127.0.0.1:8500/v1/health/service/web?passing&tag=v2"

Typical uses:

  • Versions: v1, v2, so a client can pin a version during a rollout.
  • Roles: primary and replica for a database; leader for a coordinator.
  • Placement: az-a, rack-12, useful together with the distance sorting you will see in prepared queries.
  • Canary: canary on a few new instances so a test client can target them.

Tag rules of thumb: keep them lowercase, DNS-safe and few. Tags are returned in every answer, so a hundred tags per instance is wasteful. The DNS prefix syntax does not work for tag values containing dots.

Meta

Metadata is for descriptive key-value pairs that are not used for DNS filtering:

HCL
service {
  name = "web"
  port = 8080
  meta = {
    version  = "2.4.1"
    owner    = "storefront-team"
    git_sha  = "a1b2c3d"
    runbook  = "https://wiki.example.com/web"
  }
}

Tools read meta from the API (for dashboards, ownership reports, deployment checks). Limits apply: a service may have a limited number of meta pairs (64 by default), keys up to 128 characters and values up to 512. Do not store secrets in meta; it is readable by anyone who can read the service.

Nodes also have meta (node_meta in the agent config), which is handy for facts about the machine such as instance_type or region.

Weights

DNS answers for a service can be steered with weights. In the definition:

HCL
service {
  name = "web"
  port = 8080
  weights {
    passing = 10    # weight while all checks pass
    warning = 1     # weight while a check is in warning state
  }
}

Defaults are passing = 1 and warning = 1. Weights are used in two places:

  • DNS SRV records carry the weight, so a client or load balancer that understands SRV weights can use it.
  • DNS A/AAAA answers are shuffled randomly by default, so they give no proportional guarantee, and clients may ignore weights. Treat weights as hints, not as a traffic splitter. Real percentage-based traffic splitting belongs to the service mesh, covered later in the course.

A common trick: give a larger machine passing = 20 and a small one passing = 5, and a failing-soft instance (warning) a weight of 1 so it receives less.

Overriding tags from outside: enable_tag_override

Normally the agent that owns a service also owns its tags, and any outside change to the catalog is reverted by anti-entropy. Setting enable_tag_override = true lets an external tool change the tags in the catalog and keeps the agent from undoing it. It is used for things like promoting a database replica to primary by a failover controller, without touching the instance's config file.

HCL
service {
  name = "db"
  port = 5432
  tags = ["replica"]
  enable_tag_override = true
}

Stand-in 1: filter by tags

A small model of the tag= filter, matching on all requested tags:

Python Stand-in: filter instances by tag

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Stand-in 2: weighted selection

This simulates 10,000 picks using the passing weights. The seed is fixed so the numbers repeat. It illustrates what a weight-aware client could do; Consul's own DNS does not promise this exact distribution.

Python Stand-in: weighted choice

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Putting it together

A well-described service:

HCL
service {
  name = "payments"
  id   = "payments-eu-1"
  port = 8443
  tags = ["v3", "eu"]
  meta = { version = "3.1.0", owner = "billing" }
  weights { passing = 10  warning = 1 }
}

Callers use v3.payments.service.consul; dashboards read meta; load balancers use the SRV weights.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which DNS name returns only healthy instances of web that are tagged v2?

    The tag is a prefix: <tag>.<service>.service.consul.
  2. 2. What is service meta used for?

    Meta carries information such as version and owner for tools; tags are the searchable labels.
  3. 3. What does enable_tag_override = true allow?

    The agent normally reverts outside changes; this flag lets an external controller own the tags.
  4. 4. Why should weights be treated as hints and not as a traffic splitter?

    SRV carries weights, but A/AAAA answers and client behavior give no proportional guarantee.

Summary

  • Tags are short searchable labels (v2.web.service.consul, ?tag=v2); meta is descriptive data.
  • Use tags for version, role, placement and canary; keep them few and DNS-safe.
  • weights set passing and warning weights, delivered through SRV records.
  • Never put secrets in tags or meta.
  • enable_tag_override lets an external tool own the catalog tags.

Next: The Consul DNS Interface