PRO: Tags #
All features described on this page are part of the Professional Edition.
You can purchase licenses for the Professional Edition on the Portal: https://portal.sqldsc.com.
*** BREAKING CHANGE in 1.42.16 *** #
The word “roles” was used to group targets and for server roles and database roles. This was starting to cause confusion. Target “roles” have been renamed “tags”. Unfortunately that means some manual clean up.
- Update all target
.hcl
files to replaceroles
withtags
. Search and replace works well for this. - Update all default, role/tag, and node
.hcl
files that contain nestedroles
to contain nestedtags
.role
may also be used for server and database roles so these will need to be reviewed carefully. - Rename
./config/roles
to./config/tags
- Edit
./config/state/repository.toml
and updateversion = 4
- Test the changes
sqldsc list
sqldsc test
Tags #
Each target can be assigned multiple tags. Instances in tags can be given identical configuration. Good uses of tags include:
- Identical configuration of an AG
- Separate DEV from PROD
- Group servers together for processing
- Group servers in different data centers together
Targets #
A targets.hcl
file looks something like this
target_defaults {
tags = ["baseline"]
}
target "D40" {}
target "node1.domain1.com" {
tags = ["prod", "data-center-2", "ag-one"]
force_tags = true
}
target "server04" {
tags = ["local-backups"]
}
- The
target_defaults
section can define a base set of tags for every target. - D40 only has the
baseline
tags. - node1 has three tags and doesn’t have the
baseline
tag. Thetags
field withforce_tags=true
for a target overrides thetags
field in thetarget_defaults
. - server04 ends up with two tags:
baseline
andlocal-backups
. Thetags
field (withoutforce_tags
) adds the tags to the default tags. - Because the
target_defaults
block is per file (i.e. per domain), each domain can get a different set of default tags.
Nested Tags #
A tag can define child tags using the optional tags
attribute. The baseline.hcl
from the example above might look like this:
tags = ["logging", "monitor-login"]
// more configuration settings...
This changes the example above in the following way:
- D40 now has three tags. It has
baseline
as well aslogging
andmonitor-login
. - node1 still only has three tags.
force_tags
prevents the expanding of nested nodes as well as inherting the default nodes. - server04 now has four tags instead of two. It adds
logging
andmonitor-login
that are in thebaseline.hcl
file.
The main use case for this is Availability Groups. Typically one tag is created for an AG.
That tag can then specify the needed tags inside it. That simplifies the nodes in the target files and allow more granular tags.
Tag Order Matters #
- The Resources from the tags are processed in order the tags are specified
- List more general tags followed by more specific
- Remember that Resource in later tags can override resources in earlier tags
Configuration #
The name of a tag must match a file name in the tags
directory. The init
command doesn’t create the tags folder.
config\
nodes\
DOMAIN1\
node1.hcl
server1.hcl
tags\
ag-one.hcl
baseline.hcl
data-center-1.hcl
data-center-2.hcl
prod.hcl
defaults.hcl
targets.hcl
DOMAIN1.targets.hcl