Rancher Docs: Labels

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`	An IP from the 10.42.0.0/16 address space	Allows you to pick a specific IP for a container. Note: If the IP is not available on any host, 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 traffit 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

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.