Skip to content

Best Practices

Naming Conventions

  • Use kebab-case for all identifiers (name fields): generic-sql, web-server, vmapp
  • Use consistent naming across all your templates — don't mix vmApp and vm-app
  • Use {{deployment.shortid}} in resource names to ensure uniqueness across deployments:
svcName: "myapp-{{deployment.shortid}}"          # unique per deployment
groupName: "{{deployment.shortid}}-sysadmin"      # unique per deployment
  • Use meaningful aliases with {{deployment.name}} or {{deployment.shortid}} to avoid collisions. Existing aliases are never overwritten.

Template Composition

  • Keep Resource Group Templates small and focused — one RGT per concern (e.g., one for "web server", one for "SQL server")
  • Reuse RGTs across Deployment Templates — a well-designed genericsql RGT can be used by many DPTs
  • If you have multiple identical servers, describe the server once in an RGT and reference it multiple times in the DPT:
resourceGroups:
  - name: web0
    template: webserver
    templateVersion: 1.0.0
    templateParameters:
      cpu: 2
  - name: web1
    template: webserver
    templateVersion: 1.0.0
    templateParameters:
      cpu: 4

Parameter Design

  • Use defaults wherever a sensible default exists — most deployments shouldn't need to override every parameter
  • Use secureString for passwords and sensitive values — they are masked in the portal and logs
  • Validate with regex when the value has a known format: validation: "^(Dev|Test|Prod)$"
  • Use description to explain what the parameter does and what format is expected — this is what users see in the deployment wizard
  • Use optional: true sparingly — only for truly optional configuration

Variable Strategy

Set variables at the right level in the hierarchy:

Level Use for Example
Tenant Organization-wide defaults DEFAULT_AD_RESOURCEPROVIDER, MONITORING_SOLUTION
Collection Application-specific settings Cost center, application owner
Deployment Instance-specific overrides CUSTOM_SUBNET_NAME, feature flags

Remember: variables inherit downward, and closer values take precedence. Set a default at the Tenant level, override at the Deployment level when needed.

Expression Tips

  • Use {{computenode.vmdb.fqdn}} rather than constructing FQDNs manually
  • Use {{serviceaccount.svcdb.svcpassword}} rather than hardcoding credentials
  • Avoid circular references — if Resource A references Resource B which references Resource A, the deployment deadlocks and is terminated before any resources are created.
  • Understand resolution timing — expressions referencing resources are resolved after those resources are created. Use dependsOn if needed.

Template Validation

  • Configure your editor with the JSON Schema validation to catch errors early
  • Test templates in a non-production environment first
  • Use the portal to verify that parameters appear correctly in the deployment wizard

Next: Examples