IBM Streams 4.3.0

Using tags to restrict resources

You can use tags to restrict resources for a specific application purpose by creating a tag restriction between the resource and a tag or between an instance and a tag. This tag restriction instructs the scheduler to place on the resource only the processing elements (PEs) that refer to a host pool that specifies that tag.

About this task

In an IBM® Streams domain, you have some resources that you want to restrict for a special purpose where only certain PEs can be scheduled to run. The special purpose resources can be shared across multiple jobs. A tag restriction provides the capability to restrict the use of a resource at the PE level for multiple jobs.

The tag restriction can be applied to the resource in a few ways. For an IBM Streams host, the streamtool restrictdomainhost command establishes the restricted relationship between the host and the tag. For externally managed resources, the tags and restrictions are applied to the resource after it has been created and returned to the instance. Resources can be acquired by an instance either statically or dynamically.

For static resources, the --hosts, --hfile or --numresources resource specification options can be used. For resource specifications (--numresources), the tags that are to be restricted are indicated by placing an asterisk after the tag name. In order for an IBM Streams host to match a specification that has restricted tags, the host must have the required tags and the restricted values must also match.
For dynamic allocation for an instance, the streamtool restrictinstance command is used to indicate which tags are to be restricted. For an IBM Streams host to be eligible for a request, it must have the required tags, and the restricted values must also match that of the instance. For externally managed resources, the tags and restrictions are applied the resource after it has been created and returned to the instance.

Tag restrictions are subject to the following parameters:

A TagRestriction object is a relationship between a tag and a resource. It is not a new type of tag or attribute.
Only user-defined (custom) tags can be used to restrict resources.
Multiple tags can be used to restrict a resource. In this case, the PEs that are allowed to run on the resource are the PEs that refer to a host pool that contains the multiple tags.
A tag restriction can be created and removed with active instances. However when you create the tag restriction, any PEs that are running on the resource must reference the host pool that contains the tag.

Procedure

You can create tag restrictions on static and dynamic IBM Streams resources and externally managed resources. To restrict resources by using tags, the following general steps are required:

The creation of a tag restriction between the tag and the resource.
In the SPL application, the existence of an operator with a placement clause that refers to a host pool that contains the tag.

For more information about the streamtool commands that are used to restrict static resources, enter streamtool man command-name.

Create the tag, for example:
```
streamtool mktag -d Domain1 SpecialPurpose --description
 "Special purpose tag used as an example to create a tag restriction"
```
Tip: You can use the Management Dashboard in the Streams Console to create a tag restriction. Select Manage Resources and Tags to choose the resources and tags that you want to restrict.
Associate the tag with the resource or instance. You can have both static and dynamic allocation in the same instance.
1. For static resource allocation (that is, the resource is allocated when the instance is started), associate the tag with one or more static resources by using one of the following methods:
  - For IBM Streams hosts, create a tag restriction on a specific host:
```
streamtool restrictdomainhost --allow-active-instances
 -d Domain1 --tags SpecialPurpose HostA
```
    Notes:
    - If --allow-active-instances is not specified, instances must be stopped when you run the command. Otherwise, the command returns an error.
    - Specifying --allow-active-instances skips the check for running instances. The tag restriction is created only if all running PEs reference the host pool that contains the tag. If PEs are running that do not reference a host pool that contains the tag, these PEs must be stopped before the tag restriction can be created.
    - If you already have a resource specification that includes the tag but not the tag restriction, the asterisk (*) is added to the end of the tag.
  - For IBM Streams hosts or externally managed resources, add a resource specification that includes the tag restriction, for example:
```
streamtool addresourcespec -d Domain1 -i Instance1
 --numresources 1,SpecialPurpose*
```
    Tips:
    - When the instance is started, a static resource with a tag restriction is created.
    - If you already have a resource specification that includes the tag but not the tag restriction, the asterisk (*) is added to the end of the tag.
    - When you create an instance, you can specify a resource specification with a tag restriction by using the streamtool mkinstance command.
2. For dynamic resource allocation (that is, resources are allocated depending on the needs of the job), perform the following steps:
  1. For IBM Streams hosts (as opposed to externally managed resources), restrict the resource with the tag. For example, the following command restricts the HostA host in the Domain1 domain to jobs that request resources that are tagged with the SpecialPurpose tag:
```
streamtool restrictdomainhost --allow-active-instances
 -d Domain1 --tags SpecialPurpose HostA
```
  2. Associate the tag with an instance. For example, the following command restricts the Instance1 instance in the Domain1 domain to resources that are tagged with the SpecialPurpose tag:
```
streamtool restrictinstance -d Domain1 -i Instance1 SpecialPurpose
```
Submit a job that specifies the tag, in this case, SpecialPurpose.

Results

With the tag restriction in place, in this example, the scheduler allows placements of PEs only if the PEs refer to a host pool that specifies the SpecialPurpose tag.

What to do next

To view the results:
- To see which tags are restricted on the resources in a domain, use streamtool lsavailablehosts or streamtool getdomainstate commands, for example:
```
streamtool lsavailablehosts -d Domain1
```
```
streamtool getdomainstate -d Domain1
```
  In the command output, an asterisk (*) indicates that a tag is restricted.
- To see which tags are restricted on the resources in an instance, use the streamtool lshosts or streamtool getinstancestate commands, for example:
```
streamtool lshosts -d Domain1 -i Instance1 -l
```
```
streamtool getinstancestate -d Domain1 -i Instance1
```
  In the command output, an asterisk (*) indicates that a tag is restricted.
- To see the tag restrictions that have been placed on an instance, use the streamtool lsinstance command, for example:
```
streamtool lsinstance -d Domain1 -i Instance1 -l
```
To remove a tag restriction:
- To remove a tag restriction for IBM Streams static resources, use the streamtool unrestrictdomainhost command, for example:
```
streamtool unrestrictdomainhost -d Domain1 --tags SpecialPurpose HostA
```
- To remove the tag restriction with externally managed static resources, change the resource specification by removing the tag restriction. For example, the following command removes the tag restriction for resource specification 2 by removing the asterisk (*) from the end of the tag:
```
streamtool chresourcespec -d Domain1 -i Instance1 --numresource 1,SpecialPurpose 2
```