Labels


Rancher uses labels on services/containers and hosts to help manage different features of Rancher.

Rancher Compose Labels for Services

Labels are used to help Rancher start up services and leverage the features of Rancher. This index of labels are used to help users create services using Rancher Compose. There are UI equivalents of these labels that should be used instead of adding labels to a service.

Key Value Description
io.rancher.sidekicks Service Names Used to define what services are sidekicks
io.rancher.loadbalancer.target.SERVICE_NAME REQUEST_HOST:SOURCE_PORT/REQUEST_PATH=TARGET_PORT Used to determine L7 Load Balancing
io.rancher.container.dns true Service is able to use Rancher DNS based service discovery to resolve other services and to be resolved by other services. This label is required if you require DNS, when networking is set to host.
io.rancher.container.hostname_override container_name Used to set the hostname of the container to the name of the container (e.g. StackName_ServiceName_CreateIndex)
io.rancher.container.start_once true Used to run a container once and have it remain in stopped state while the service remains in active state
io.rancher.container.pull_image always Used to always pull a new image before deploying container.
io.rancher.container.requested_ip As of v1.6.6, a comma separated list of IPs from the 10.42.0.0/16 address space. Prior to v1.6.6, only a single IP can be used. Allows you to pick a specific IP for a container. As of v1.6.6+, containers inside the service will use any available IPs from the list until they are exhausted. The format is comma-separated, e.g. 10.42.100.100, 10.42.100.101. Prior to v1.6.6, one of the containers in the service will use the IP. Note: If the IP is not available, the container will start with a random IP.
io.rancher.container.dns.priority service_last Use the DNS search path of the host before the service domain. This will place the *.rancher.internal search after the search from the hosts /etc/resolv.conf.
io.rancher.service.selector.container Selector Label Values Used on a service so that standalone containers can be selected to join the service DNS. Note: As standalone containers, none of the service actions will affect the standalone container (i.e. deactivate/delete/edit service, healthcheck, etc).
io.rancher.service.selector.link Selector Label Values Used on a service to allow services to be linked to the service based on service labels. Example: Service1 has a label io.rancher.service.selector.link: foo=bar. Any services that are added to Rancher that have a foo=bar label will automatically be linked to Service1.
io.rancher.scheduler.global true Used to set global services
io.rancher.scheduler.affinity:host_label Key Value Pair of Host Label Used to schedule containers on hosts based on host label
io.rancher.scheduler.affinity:container_label Key Value Pair of Any Container Label Used to schedule containers on hosts based on container label or service name
io.rancher.scheduler.affinity:container Name of Container Used to schedule containers on hosts based on container name
io.rancher.lb_service.target Target Service Label Values Used to configure load balancers so that traffic will be routed to containers that are on the same host as the load balancer.


Note: For the labels prefixed with io.rancher.scheduler.affinity, there are slight variations based on your how want to match (i.e. equal or not equal, hard or soft rules). More details can be found here.

Selector Labels

Using a selector label (i.e. io.rancher.service.selector.link, io.rancher.service.selector.container), Rancher can identify services/containers by their labels and have them automatically linked to the service. Selector labels are evaluated in two scenarios. Scenario 1 is when a selector label is added to a service. In Scenario 1, all existing labels are evaluated to see if they match the selector label. Scenario 2 is when a service already has a selector label. In Scenario 2, any new services/containers added to Rancher is checked to see if it qualifies to be linked. A selector label can be made of multiple requirements, which are comma separated. If there are multiple requirements, all requirements must be satisfied so the comma separator acts as an AND logical operator.

# One of the container labels must have a key equal to `foo1` and value equal to `bar1`
foo1 = bar1
# One of the container labels must have a key equal to `foo2` with a value not equal to `bar2`
foo2 != bar2
# One of the container labels must have a key equal to `foo3`, value of the label does not matter
foo3
# One of the container labels must have a key equal to `foo4` and value equal to `bar1` OR `bar2`
foo4 in (bar1, bar2)
# One of the container labels must have a key equal to `foo5` and value other than `bar3` OR `bar4`
foo5 notin (bar3, bar4)


Note: If there is a label with a value that contains a comma in it, the selector will not be able to match with the label as the selector label can match on any key with no associated value. Example: A label of io.rancher.service.selector.link: foo=bar1,bar2 would translate to any service that have one label must be key equals to foo and value equal to bar1 AND another label with key equal to bar2. It would NOT pick up a service that has a label with key equal to foo and value equal to bar1,bar2.

Example of a comma separated list

service1:
  labels:
    # Selector label added to pick up other services
    io.rancher.service.selector.link: hello != world, hello1 in (world1, world2), foo = bar

In this example, the service that would be linked to service1 would need to satisfy all of the following conditions:

  • A label with key equal to hello and value NOT equal to world
  • A label with key equal to hello1 can have either value equal to world1 or world2
  • A label with key equal to foo and value equal to bar

With the example below, service2 would automatically link to service1 when deployed.

service2:
   labels:
      hello: test
      hello1: world2
      foo: bar

System Labels on a Service

Besides labels that can be used by Rancher Compose, there are a series of system labels that Rancher creates when starting services.

Key Description
io.rancher.stack.name/io.rancher.project.name Created based on the stack name
io.rancher.stack_service.name/io.rancher.project_service.name Created based on the service name
io.rancher.service.deployment.unit Created based on the deployments for sidekicked services
io.rancher.service.launch.config Created based on the configurations for sidekicked services.
io.rancher.service.requested.host.id Created based on which host the service was scheduled on

Host Labels

Host labels can be added to a host during registration of a host or added later by Editing the host.

Key Value Description
io.rancher.host.external_dns_ip IP to be used for External DNS, e.g. a.b.c.d To be used for external DNS services and requiring the programming of the DNS records using an IP other than the host IP

Automatically Applied Host Labels

Rancher automatically creates host labels related to linux kernel version and Docker Engine version of the host. These labels can be used for scheduling.

Key Value Description
io.rancher.host.linux_kernel_version Linux Kernel Version on Host (e.g, 3.19) Version of the Linux kernel running on the host
io.rancher.host.docker_version Docker Version on the host (e.g. 1.10.3) Docker Engine Version on the host
io.rancher.host.provider Cloud provider info Cloud provider name (currently only applied for AWS)
io.rancher.host.region Cloud provider region Cloud provider region (currently only applied for AWS)
io.rancher.host.zone Cloud provider zone Cloud provider zone (currently only applied for AWS)

Native Docker Labels

io.rancher.container.network true Add this label to a docker run command to add Rancher networking to the container

Target Service Labels

A load balancer can be configured to prioritize traffic to containers of the target service that are located on the same host of the load balancer. Depending on the value of the label, the load balancer will be configured to either direct traffic to only those containers or to prioritize traffic to those containers. By default, a load balancer routes traffic to all containers of the target service in a round robin algorithm.

Key Value Description
io.rancher.lb_service.target only-local Only direct traffic to containers on the same host as the load balancer container. If there are no containers of the target service on the same host, then no traffic will be routed to the service.
io.rancher.lb_service.target prefer-local Prioritize traffic to containers on the same host as the load balancer container. If there are no containers of the target service on the same host, then traffic will be routed to other containers of the service, that reside on other hosts.