Skip to content

Create Custom Json Config File

Jump to bottom
Tao Yang edited this page Sep 10, 2022 · 2 revisions

Creating and Updating Customized CloudNaming Json Configuration File

Introduction

The CloudNaming PowerShell module comes with a configuration file CloudNaming.json. This file is used to store configuration for the CloudNaming module. The following information is stored in CloudNaming.json:

  • Supported input parameters for the CloudNaming PowerShell module and the validation methods for each input.
  • Allowed values for certain input parameters

The CloudNaming PowerShell module is designed in a way that all business rules are stored in the CloudNaming.json configuration file so it can be updated and maintained by people who are not PowerShell savvy.

You can create a customized copy of the CloudNaming.json configuration file and use it with the CloudNaming PowerShell module. You can store your customized CloudNaming.json configuration file in a location of your choice. You can also update the CloudNaming.json configuration file to add new business rules or to change existing business rules.

Instructions

Once the modle is installed, you can use the NewCloudNamingConfigFile command to create a customized copy of the CloudNaming.json configuration file. For example:

# create a copy to C:\Temp\CustomCloudNamingConfig.json
 NewCloudNamingConfigFile -configFilePath C:\Temp\CustomCloudNamingConfig.json

The CloudNaming.json file is constructed as below:

{
    "controls": {
    //defines how a valid value should be for each input parameter when executing the commands within CloudNaming module.
    },
    "allowedValues": {
        "cloud": [
        //defines all the allowed values for the "cloud" parameter.
        ],
        "company": [
        //defines all the allowed values for the "company" parameter.
        ],
        "resourceTypes": [
        //defines all the resource types that are supported by the CloudNaming module, and the naming pattern for each type.
        ]
    }
}

Update Input Parameter Controls

The command GetCloudResourceName from the CloudNaming module takes the following parameters to generate names:

  • company (optional, string)
  • type (optional, string[])
  • location (optional, string)
  • cloud (mandatory, string)
  • environment (optional, string)
  • appIdentifier (optional, string)
  • associatedResourceType (optional, string)
  • associatedResourceName (optional, string)
  • workloadType (optional, string)
  • startInstanceNumber (optional, integer)
  • instanceCount (optional, integer)
  • configFilePath (optional, string)

Depending on the parameter, they are being validated using a combination of Minimum / Maximum Length, Minimum / Maximum Value and Regular Expression (Regex) The following values are defined in the control section of the CloudNaming.json file. They can be updated accordingly.

Name Description Type MinLength Support MaxLength Support MinValue Support MaxValue Support Regex Support
cloud related to the cloud parameter, representing the cloud provider string Yes Yes No No No
company related to the company parameter, company abbreviation string Yes Yes No No No
resourceType related to the type parameter, representing the Cloud resource type string Yes Yes No No No
environment related to the environment parameter. representing your organization's Cloud environment code string Yes Yes No No Yes
location related to the location parameter. representing your organization's Cloud location abbreviation code string Yes Yes No No no
appIdentifier related to the appIdentifier parameter. string Yes Yes No No No
associatedResourceType representing the associatedResourceType parameter string Yes Yes No No No
associatedResourceName representing the associatedResourceName parameter string Yes Yes No No Yes
workloadType representing the workloadType parameter string Yes Yes No No No
instance the instance number. it's calculated from the startInstanceNumber and instanceCount parameter integer No No Yes Yes No

Updating Allowed Values

Updating Allowed Values for the Company

This company array represents all the possible business unit / company abbreviations within your organization that can be used to construct some of the Cloud resource names. this array can be update accordingly.

NOTE: the first value defined in the company allowedValues is also the default value for the -company input parameter if not specified..

Updating Allowed values for Resource Types

the resourceType section defines each supported Cloud resource types by the CloudNaming module. each block contains the following attributes:

  • value: the short name of the resource type defined by the your organization Cloud Naming Standard.
  • description: the common name for the resource type.
  • cloud: the cloud provider for the resource type.
  • minLength: Cloud's minimum supported length of the name for this resource type
  • maxLength: Cloud's maximum supported length of the name for this resource type
  • case: the lower or upper case for the name generated for this resource type
  • leadingZeros: Boolean, specify if the instance number should contain leading zeros. i.e. if the maximum instance count (specified in the maxValue for the instance in the control section) is 99, the instance numbers would be 01...99. If the maximum instance count is 999, the instance numbers would be 001...099...999.
  • pattern: the naming pattern for the resource type. it is formed with some (or all) parameters defined in the control section. Each parameter is wrapped using curly brackets {}.

Resource types can be added, deleted and updated in the resourceType section. When updating this section, please make sure:

  • No duplicate value in the "value" attributes (meaning no resource types sharing the same abbreviation)
  • The cloud attribute value must be one of the supported cloud providers defined in the control section.
  • No duplicate value in the "description" attribute. This attribute is used by the GetCloudNamingSupportedTypes command, which is used to search for supported resource types.
  • Make sure the minLength and maxLength for the particular resource type is clearly defined according to the cloud provider's naming requirements. Each generated name are validated against these values to ensure it can be indeed used in particular cloud.
  • Make sure the correct case is defined. Some cloud resource types have such requirements i.e. Names for Azure Storage Account can only be in lower case.
  • Make sure the pattern you specified complies with the requirements from the cloud provider. i.e. some resource names cannot start with a number, no consecutive dashes -, etc.

Validation

After the CloudNaming.json configuration file is updated, make sure the following tasks are performed:

Schema validation

Validate the updated json file against it's Json Schema CloudNaming.schema.json

In PowerShell Core (PowerShell v7.x), NOT Windows PowerShell (v5.x):

$json = get-content -path <path to CloudNaming.json> -raw
$schema = get-content -path .<path to CloudNaming.schema.json> -raw
test-json -json $Json -schema $schema

NOTE: when using the CloudNaming module, the configuration file is automatically validated against the schema.

Increase Module Version Number

When updating the customized version of the CloudNaming module, make sure you increase the PowerShell module version in CloudNaming.psd1 by updating the ModuleVersion attribute. the version must be updated otherwise the pipeline will not be able to publish the updated version to the target PowerShell repository.

IMPORTANT: Generally, the Semantic Versioning format MAJOR.MINOR.PATCH are widely used for PowerShell modules. Make sure the guideline is followed when updating the version number:

  1. MAJOR version when you make incompatible API changes,
  2. MINOR version when you add functionality in a backwards compatible manner, and
  3. PATCH version when you make backwards compatible bug fixes.
Clone this wiki locally