PRO: Roles #
All features described in 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 thesqldsc.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
.
Breaking change in 1.36 #
The attribute names that Targets use to add to and override the default roles have changed to make them simpler and more explicit.
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 rolesroles
– 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 rolesonly_roles
– set the list of roles for this target
Updating your repository #
- For targets, rename
roles = [...]
toonly_roles = [...]
EXCEPT in thetarget_defaults
block For targets, renameadded_roles = [...]
toadd_roles = [...]
- For
target_defaults
, no changes are needed - In
/config/state/repository.toml
, update the version to 2 (version=2
). This is a new file created by this version and will need to checked into your repository.
The documentation for the earlier behavior is further down the page.
Roles #
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 theroles
field in thetarget_defaults
. In the example,node1
has three roles and doesn’t have thebaseline
role. - The
add_roles
field adds the roles to the default roles. In the example,server04
ends up with two roles:baseline
andlocal-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 theroles
field in thetarget_defaults
. In the example,node1
has three roles and doesn’t have thebaseline
role. - The
added_roles
field adds the roles to the default roles. In the example,server04
ends up with two roles:baseline
andlocal-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