configuration-files.adoc

Configuration files for archetypes

An archetype is defined by a configuration file using JSON notation. In our examples, configuration files are named archetype.json. The sample configuration files provided in the toolkit are named archetype.test.json. You’ll find these sample configuration files in the archetypes folder.

An archetype configuration file contains all of the necessary settings for the toolkit to deploy the archetype environment. You will need to modify the sample configuration files to match your Azure environment before deploying them.

Structure of configuration files

The settings in the archetype configuration files are grouped into sections.

{
    "general": {},
    "orchestration": {},
    "on-premises": {},
    "shared-services": {},
    "workload": {}
}

general

This section contain parameters that are used in more than one section in the config file. The general section allows you to specify the value just once, instead of having to repeat it throughout the config file. These values are referenced in other sections of the config file using a syntax like ${general.some.property}.

orchestration

This section lists the modules that make up the archetype. It determines the order that the individual modules are deployed in and provides module specific configuration.

on-premises

This section contains the configuration for the simulated on-premise environment. In the special case of deploying the simulated on-premise environment, it is used to construct that environment. In all other cases, it is used to reference resources in simulated on-premise environment.

shared-services

This section contains the configuration for the shared services environment. In the special case of deploying the shared services environment, it is used to construct that environment. In all other cases, it is used to reference resources in the shared services environment.

workload

This section contains the majority of the parameters that define most archetypes (those deployed with the workload identifier).

Creating configuration files

Note	These archetype.test.json files are not the actual files your deployments will use. The provided example files are a starting point for reference. They are also used for the integration testing of the toolkit.

To create a configuration file for deploying one of the sample archetype to your Azur environment, you will need to make a copy of a sample config file and rename it archetype.json. This file can remain in the same folder as the original sample file.

In the archetype.json file you will enter your subscription, tenant, organizational, and other configuration information. Do not modify or delete the test file, as the values defined there are required to support integration testing.

Because your config files will contain sensitive information such as subscription IDs and user names, the toolkit repository’s .gitignore file is set to prevent files name archetype.json from being tracked by Git.

Referencing other parameters

The toolkit allows you to reference values defined elsewhere in the configuration file when setting a parameter’s value. This mechanism is provided to avoid repeating the same value more than more once, and potentially introducing copy-and-paste errors.

You can reference an existing parameter value using the format: ${path.to.value}

For example, if you have a parameter resource-group-name and you want to set it to a combination of the the organization-name from the general section and deployment-name from the shared-services section:

"resource-group-name": "${general.organization-name}-${general.shared-services.deployment-name}-net-rg",

In this case, if your parameter file defines organization-name as contoso and deployment-name as hub001, the toolkit will set resource-group-name to contoso-hub001-net-rg when deploying the archetype.

Referencing command line arguments

You can also reference values passed as arguments when the deployment script, vdc.py is executed. These are treated as environment variables and can be referenced using the format: ${ENV:[variable-name]}.

Environment variables can be used in the same manner as parameter references.

The toolkit currently supports referencing the following arguments in parameters files:

Argument	Description	Variable Reference
{environment type identifer}	Environment (shared-services, workload, on-premises).	${ENV:ENVIRONMENT-TYPE}
-m	Resource module being deployed (ops, net, etc…). If no value is passed, then environment variable is null.	${ENV:RESOURCE}
-rg	Resource group argument. If no value is passed, then environment variable is null.	$(ENV:RESOURCE-GROUP)

For more information on these arguments, see the vdc.py reference.

Next steps

Review the common parameters generally found in all archetype config files.