Rancher uses labels on services/containers and hosts to help manage different features of Rancher.
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
REQUEST_HOST:SOURCE_PORT/REQUEST_PATH=TARGET_PORT |Used to determine L7 Load Balancing
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
container_name | Used to set the hostname of the container to the name of the container (e.g. StackName_ServiceName_CreateIndex)
true | Used to run a container once and have it remain in stopped state while the service remains in
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.
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
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.
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.
Using a selector label (i.e.
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,bar2would translate to any service that have one label must be key equals to
fooand value equal to
bar1AND another label with key equal to
bar2. It would NOT pick up a service that has a label with key equal to
fooand value equal to
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:
helloand value NOT equal to
hello1can have either value equal to
fooand value equal to
With the example below,
service2 would automatically link to
service1 when deployed.
service2: labels: hello: test hello1: world2 foo: bar
Besides labels that can be used by Rancher Compose, there are a series of system labels that Rancher creates when starting services.
||Created based on the stack name|
||Created based on the service name|
||Created based on the deployments for sidekicked services|
||Created based on the configurations for sidekicked services.|
||Created based on which host the service was scheduled on|
Host labels can be added to a host during registration of a host or added later by Editing the host.
||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|
Rancher automatically creates host labels related to linux kernel version and Docker Engine version of the host. These labels can be used for scheduling.
||Linux Kernel Version on Host (e.g,
||Version of the Linux kernel running on the host|
||Docker Version on the host (e.g.
||Docker Engine Version on the host|
||Add this label to a
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.
||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.|
||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.|