PRO: Roles #

All features described on this page are part of the Professional Edition.

While in beta, you can enable the Professional Edition by creating an empty key.xt file next to the sqldsc.exe file.

The PRO edition will become a paid version. Until then, PRO features expire 90 days after the build date. Please see https://www.scalesql.com for updated builds or run sqldsc update.

Roles #

Roles changed in 1.39. Please see the Breaking Changes section if you are upgrading.

Each target can be assigned multiple roles. Instances in roles can be given identical configuration. Good uses of roles 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 {
    roles = ["baseline"]
}

target "D40" {}

target "node1.domain1.com" {
    roles = ["prod", "data-center-2", "ag-one"]
    force_roles = true
}

target "server04" {
    roles = ["local-backups"]
}

The target_defaults section can define a base set of roles for every target.
D40 only has the baseline roles.
node1 has three roles and doesn’t have the baseline role. The roles field with force_roles=true for a target overrides the roles field in the target_defaults.
server04 ends up with two roles: baseline and local-backups. The roles field (without force_roles) adds the roles to the default roles.
Because the target_defaults block is per file (i.e. per domain), each domain can get a different set of default roles.

Nested Roles #

A role can define child roles using the optional roles attribute. The baseline.hcl from the example above might look like this:

roles = ["logging", "monitor-login"]
// more configuration settings...

This changes the example above in the following way:

D40 now has three roles. It has baseline as well as logging and monitor-login.
node1 still only has three roles. force_roles prevents the expanding of nested nodes as well as inherting the default nodes.
server04 now has four roles 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 role is created for an AG.
That role can then specify the needed roles inside it. That simplifies the nodes in the target files and allow more granular roles.

Role Order Matters #

The Resources from the roles are processed in order the roles are specified
List more general roles followed by more specific
Remember that Resource in later roles can override resources in earlier roles

Configuration #

The name of a role must match a file name in the roles directory. The init command doesn’t create the roles folder.

config\
    nodes\
        DOMAIN1\   
            node1.hcl
            server1.hcl
    roles\
        ag-one.hcl
        baseline.hcl
        data-center-1.hcl
        data-center-2.hcl
        prod.hcl
    defaults.hcl
    targets.hcl
    DOMAIN1.targets.hcl

Breaking change in 1.39 #

The attribute names that Targets use to add to and override the default roles have changed (again) to make them simpler and more explicit. See below to update your repository. The target_defaults block in a Targets file can define an array of roles using the roles attribute. Targets can override these or add more roles. This is unchanged.

Prior to version 1.36, a Target could have one of the following two attributes
- added_roles – roles that are added to any default roles
- roles – set the list of roles for this target
Starting in version 1.36, a Target can have one of the two following attributes
- add_roles – roles that are added to any default roles
- only_roles – set the list of roles for this target
Starting in version 1.39, a Target can have the two following attributs
- roles – roles that are added to the default roles
- force_roles – changes roles so that only those roles are used. There is no inheritance.

Updating your repository from 1.36 #

For targets, rename add_roles=[...] to roles=[...]
For targets, rename only_roles=[...] to roles=[...] and add force_roles=true
In /config/state/repository.toml, update the version to 3 (version=3). This file is created starting in 1.36 and will need to checked into your repository.

The documentation for the earlier behavior is further down the page.

Roles (prior to 1.39) #

Each target can be assigned multiple roles. Instances in roles can be given identical configuration. Good uses of roles 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 {
    roles = ["baseline"]
}

target "D40\SQL2016" {}

target "server1.domain1.com" {
    only_roles = ["baseline", "data-center-1"]
}

target "node1.domain1.com" {
    only_roles = ["prod", "data-center-2", "ag-one"]
}

target "server04" {
    add_roles = ["local-backups"]
}

The target_defaults section can define a base set of roles for every target.
The only_roles field for a target overrides the roles field in the target_defaults. In the example, node1 has three roles and doesn’t have the baseline role.
The add_roles field adds the roles to the default roles. In the example, server04 ends up with two roles: baseline and local-backups.
Because the target_defaults block is per file (i.e. per domain), each domain can get a different set of default roles.

Role Order Matters #

The Resources from the roles are processed in order the roles are specified
List more general roles followed by more specific
Remember that Resource in later roles can override resources in earlier roles

Configuration #

The name of a role must match a file name in the roles directory. The init command doesn’t create the roles folder.

config\
    nodes\
        DOMAIN1\   
            node1.hcl
            server1.hcl
    roles\
        ag-one.hcl
        baseline.hcl
        data-center-1.hcl
        data-center-2.hcl
        prod.hcl
    defaults.hcl
    targets.hcl
    DOMAIN1.targets.hcl

Roles (prior to 1.36) #

Each target can be assigned multiple roles. Instances in roles can be given identical configuration. Good uses of roles 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 {
    roles = ["baseline"]
}

target "D40\SQL2016" {}

target "server1.domain1.com" {
    roles = ["baseline", "data-center-1"]
}

target "node1.domain1.com" {
    roles = ["prod", "data-center-2", "ag-one"]
}

target "server04" {
    added_roles = ["local-backups"]
}

The target_defaults section can define a base set of roles for every target.
The roles field for a target overrides the roles field in the target_defaults. In the example, node1 has three roles and doesn’t have the baseline role.
The added_roles field adds the roles to the default roles. In the example, server04 ends up with two roles: baseline and local-backups.
Because the target_defaults block is per file (i.e. per domain), each domain can get a different set of default roles.

Role Order Matters #

The Resources from the roles are processed in order the roles are specified
List more general roles followed by more specific
Remember that Resource in later roles can override resources in earlier roles

Configuration #

The name of a role must match a file name in the roles directory. The init command doesn’t create the roles folder.

config\
    nodes\
        DOMAIN1\   
            node1.hcl
            server1.hcl
    roles\
        ag-one.hcl
        baseline.hcl
        data-center-1.hcl
        data-center-2.hcl
        prod.hcl
    defaults.hcl
    targets.hcl
    DOMAIN1.targets.hcl