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.

1. Update all target .hcl files to replace roles with tags. Search and replace works well for this.
2. Update all default, role/tag, and node .hcl files that contain nested roles to contain nested tags. role may also be used for server and database roles so these will need to be reviewed carefully.
3. Rename ./config/roles to ./config/tags
4. Edit ./config/state/repository.toml and update version = 4
5. Test the changes
   1. sqldsc list
   2. 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. The tags field with force_tags=true for a target overrides the tags field in the target_defaults.
• server04 ends up with two tags: baseline and local-backups. The tags field (without force_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 as logging and monitor-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 and monitor-login that are in the baseline.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