ARM 템플릿의 매개 변수

아티클
03/10/2024

이 문서에서는 ARM 템플릿(Azure Resource Manager 템플릿)에서 매개 변수를 정의하고 사용하는 방법을 설명합니다. 매개 변수에 다른 값을 제공하면 다양한 환경에 템플릿을 다시 사용할 수 있습니다.

Resource Manager는 배포 작업을 시작하기 전에 매개 변수 값을 확인합니다. 템플릿에서 매개 변수가 사용될 때마다 Resource Manager는 매개 변수를 확인된 값으로 바꿉니다.

각 매개 변수는 데이터 형식 중 하나로 설정해야 합니다.

minValue, maxValue, minLength, maxLength 및 allowedValues 외에도 languageVersion 2.0에는 정의, 매개 변수 및 출력 정의에 사용할 몇 가지 집계 형식 유효성 검사 제약 조건이 도입되었습니다. 이러한 제약 조건은 다음과 같습니다.

additionalProperties
discriminator
항목
nullable
prefixItems
properties

참고 항목

Visual Studio Code용 Azure Resource Manager 도구 확장의 현재 릴리스에서는 languageVersion 2.0의 향상된 기능을 인식하지 못합니다.

팁

ARM 템플릿과 동일한 기능을 제공하고 구문이 사용하기 더 쉽기 때문에 Bicep를 권장합니다. 자세한 내용은 매개 변수를 참조하세요.

템플릿에서 매개 변수는 256개로 제한됩니다. 자세한 내용은 템플릿 제한을 참조하세요.

매개 변수 모범 사례는 매개 변수를 참조하세요.

최소 선언

최소한 모든 매개 변수에는 이름 및 형식이 필요합니다.

Azure Portal을 통해 템플릿을 배포하면 카멜식 대/소문자 매개 변수 이름이 공백으로 구분된 이름으로 바뀝니다. 예를 들어 다음 예제의 demoString은 Demo String으로 표시됩니다. 자세한 내용은 배포 단추를 사용하여 GitHub 리포지토리에서 템플릿 배포 및 ARM 템플릿 및 Azure Portal을 사용하여 리소스 배포를 참조하세요.

"parameters": {
  "demoString": {
    "type": "string"
  },
  "demoInt": {
    "type": "int"
  },
  "demoBool": {
    "type": "bool"
  },
  "demoObject": {
    "type": "object"
  },
  "demoArray": {
    "type": "array"
  }
}

보안 매개 변수

문자열 또는 개체 매개 변수를 보안으로 표시할 수 있습니다. 보안 매개 변수의 값은 배포 기록에 저장되지 않으며 기록되지도 않습니다.

"parameters": {
  "demoPassword": {
    "type": "secureString"
  },
  "demoSecretObject": {
    "type": "secureObject"
  }
}

허용된 값

매개 변수에 허용되는 값을 정의할 수 있습니다. 배열에 허용되는 값을 제공합니다. 허용되는 값 중 하나가 아닌 매개 변수에 값이 전달되면 유효성 검사 중에 배포가 실패합니다.

"parameters": {
  "demoEnum": {
    "type": "string",
    "allowedValues": [
      "one",
      "two"
    ]
  }
}

기본값

매개 변수의 기본값을 지정할 수 있습니다. 기본값은 배포 중에 값이 제공되지 않는 경우에 사용됩니다.

"parameters": {
  "demoParam": {
    "type": "string",
    "defaultValue": "Contoso"
  }
}

매개 변수의 다른 속성과 함께 기본값을 지정하려면 다음 구문을 사용합니다.

"parameters": {
  "demoParam": {
    "type": "string",
    "defaultValue": "Contoso",
    "allowedValues": [
      "Contoso",
      "Fabrikam"
    ]
  }
}

기본값으로 식을 사용할 수 있습니다. 매개 변수 섹션에서는 reference 함수 또는 list 함수를 사용할 수 없습니다. 이러한 함수는 리소스의 런타임 상태를 가져오며 매개 변수가 확인되면 배포 전에 실행할 수 없습니다.

다른 매개 변수 속성에서는 식이 허용되지 않습니다.

"parameters": {
  "location": {
    "type": "string",
    "defaultValue": "[resourceGroup().location]"
  }
}

다른 매개 변수 값을 사용하여 기본값을 빌드할 수 있습니다. 다음 템플릿은 사이트 이름에서 호스트 계획 이름을 구성합니다.

"parameters": {
  "siteName": {
    "type": "string",
    "defaultValue": "[concat('site', uniqueString(resourceGroup().id))]"
  },
  "hostingPlanName": {
    "type": "string",
    "defaultValue": "[concat(parameters('siteName'),'-plan')]"
  }
}

길이 제약 조건

문자열 및 배열 매개 변수의 최소 길이와 최대 길이를 지정할 수 있습니다. 하나 또는 두 개의 제약 조건을 설정할 수 있습니다. 문자열의 경우 길이는 문자 수를 나타냅니다. 배열의 경우 길이는 배열의 항목 수를 나타냅니다.

다음 예제에서는 두 개의 매개 변수를 선언합니다. 한 매개 변수는 스토리지 계정 이름에 대한 것이며, 3~24자여야 합니다. 다른 매개 변수는 배열이며, 1~5개 항목이 있어야 합니다.

"parameters": {
  "storageAccountName": {
    "type": "string",
    "minLength": 3,
    "maxLength": 24
  },
  "appNames": {
    "type": "array",
    "minLength": 1,
    "maxLength": 5
  }
}

정수 제약 조건

정수 매개 변수의 최솟값과 최댓값을 설정할 수 있습니다. 하나 또는 두 개의 제약 조건을 설정할 수 있습니다.

"parameters": {
  "month": {
    "type": "int",
    "minValue": 1,
    "maxValue": 12
  }
}

개체 제약 조건

개체 제약 조건은 개체에만 허용되며 languageVersion 2.0에서만 사용할 수 있습니다.

속성

properties 값은 속성 이름 =>형식 정의의 맵입니다.

다음 예제에서는 {"foo": "string", "bar": 1}을 허용하지만 {"foo": "string", "bar": -1}, {"foo": "", "bar": 1} 또는 foo나 bar 속성이 없는 개체는 거부합니다.

"parameters": {
  "objectParameter": {
    "type": "object",
    "properties": {
      "foo": {
        "type": "string",
        "minLength": 3
      },
      "bar": {
        "type": "int",
        "minValue": 0
      }
    }
  }
}

속성의 형식 정의에 "nullable": true 제약 조건이 없는 한 모든 속성은 필수입니다. 앞의 예제에서 두 속성을 모두 선택 사항으로 만들려면 다음과 같습니다.

"parameters": {
  "objectParameter": {
    "type": "object",
    "properties": {
      "foo": {
        "type": "string",
        "minLength": 3,
        "nullable": true
      },
      "bar": {
        "type": "int",
        "minValue": 0,
        "nullable": true
      }
    }
  }
}

additionalProperties

additionalProperties 값은 형식 정의 또는 부울 값입니다. additionalProperties 제약 조건이 정의되지 않은 경우 기본값은 true입니다.

값이 형식 정의인 경우 값은 properties 제약 조건에 언급되지 않은 모든 속성에 적용되는 스키마를 설명합니다. 다음 예제에서는 {"fizz": "buzz", "foo": "bar"}를 허용하지만 {"property": 1}은 거부합니다.

"parameters": {
  "dictionaryParameter": {
    "type": "object",
    "properties": {
      "foo": {
        "type": "string",
        "minLength": 3,
        "nullable": true
      },
      "bar": {
        "type": "int",
        "minValue": 0,
        "nullable": true
      }
    },
    "additionalProperties": {
      "type": "string"
    }
  }
}

값이 false이면 properties 제약 조건에 정의된 속성 이외의 속성은 제공할 수 없습니다. 다음 예제에서는 {"foo": "string", "bar": 1}을 허용하지만 {"foo": "string", "bar": 1, "fizz": "buzz"}는 거부합니다.

"parameters": {
  "dictionaryParameter": {
    "type": "object",
    "properties": {
      "foo": {
        "type": "string",
        "minLength": 3
      },
      "bar": {
        "type": "int",
        "minValue": 0
      }
    },
    "additionalProperties": false
  }
}

값이 true이면 properties 제약 조건에 정의되지 않은 모든 속성은 모든 값을 허용합니다. 다음 예제에서는 {"foo": "string", "bar": 1, "fizz": "buzz"}를 허용합니다.

"parameters": {
  "dictionaryParameter": {
    "type": "object",
    "properties": {
      "foo": {
        "type": "string",
        "minLength": 3
      },
      "bar": {
        "type": "int",
        "minValue": 0
      }
    },
    "additionalProperties": true
  }
}

discriminator

discriminator 값은 판별자 속성을 기반으로 적용할 스키마를 정의합니다. 다음 예제에서는 {"type": "ints", "foo": 1, "bar": 2} 또는 {"type": "strings", "fizz": "buzz", "pop": "goes", "the": "weasel"}을 허용하지만 {"type": "ints", "fizz": "buzz"}는 거부합니다.

"parameters": {
  "taggedUnionParameter": {
    "type": "object",
    "discriminator": {
      "propertyName": "type",
      "mapping": {
        "ints": {
          "type": "object",
          "additionalProperties": {"type": "int"}
        },
        "strings": {
          "type": "object",
          "additionalProperties": {"type": "string"}
          }
      }
    }
  }
}

배열 제약 조건

배열 제약 조건은 배열에만 허용되며 languageVersion 2.0에서만 사용할 수 있습니다.

prefixItems

prefixItems 값은 형식 정의의 배열입니다. 값의 각 형식 정의는 동일한 인덱스에 있는 배열 요소의 유효성을 검사하는 데 사용되는 스키마입니다. 다음 예제에서는 [1, true]를 허용하지만 [1, "string"] 또는 [1]은 거부합니다.

"parameters": {
  "tupleParameter": {
    "type": "array",
    "prefixItems": [
      {"type": "int"},
      {"type": "bool"}
    ]
  }
}

항목

items 값은 형식 정의 또는 부울 값입니다. items 제약 조건이 정의되지 않은 경우 기본값은 true입니다.

값이 형식 정의인 경우 이 값은 인덱스가 prefixItems 제약 조건의 가장 큰 인덱스보다 큰 배열의 모든 요소에 적용되는 스키마를 설명합니다. 다음 예제에서는 [1, true, 1] 또는 [1, true, 1, 1]을 허용하지만 [1, true, "foo"]는 거부합니다.

"parameters": {
  "tupleParameter": {
    "type": "array",
    "prefixItems": [
      { "type": "int" },
      { "type": "bool" }
    ],
    "items": { "type": "int" },
    "defaultValue": [1, true, "foo"]
  }
}

prefixItems를 사용하지 않고 items를 사용할 수 있습니다. 다음 예제에서는 [1, 2] 또는 [1]을 허용하지만 ["foo"]는 거부합니다.

"parameters": {
  "intArrayParameter": {
    "type": "array",
    "items": {"type": "int"}
  }
}

값이 false인 경우 유효성이 검사된 배열은 prefixItems 제약 조건과 정확히 동일한 길이여야 합니다. 다음 예제에서는 [1, true]를 허용하지만 [1, true, 1] 및 [1, true, false, "foo", "bar"]는 거부합니다.

"parameters": {
  "tupleParameter": {
    "type": "array",
    "prefixItems": [
      {"type": "int"},
      {"type": "bool"}
    ],
    "items": false
  }
}

값이 true이면 인덱스가 prefixItems 제약 조건의 가장 큰 인덱스보다 큰 배열 요소는 모든 값을 허용합니다. 다음 예제에서는 [1, true], [1, true, 1] 및 [1, true, false, "foo", "bar"]를 허용합니다.

"parameters": {
  "tupleParameter": {
    "type": "array",
    "prefixItems": [
      {"type": "int"},
      {"type": "bool"}
    ]
  }
}

"parameters": {
  "tupleParameter": {
    "type": "array",
    "prefixItems": [
      {"type": "int"},
      {"type": "bool"}
    ]
  },
  "items": true
}

nullable 제약 조건

nullable 제약 조건은 languageVersion 2.0에서만 사용할 수 있습니다. 값이 null이거나 생략될 수 있음을 나타냅니다. 예제는 속성을 참조하세요.

설명

템플릿 사용자가 제공할 값을 이해할 수 있도록 매개 변수에 설명을 추가할 수 있습니다. 포털을 통해 템플릿을 배포하는 경우 설명에 제공하는 텍스트가 자동으로 해당 매개 변수에 대한 팁으로 사용됩니다. 텍스트가 매개 변수 이름에서 유추할 수 있는 것보다 더 많은 정보를 제공하는 경우에만 설명을 추가합니다.

"parameters": {
  "virtualMachineSize": {
    "type": "string",
    "metadata": {
      "description": "Must be at least Standard_A3 to support 2 NICs."
    },
    "defaultValue": "Standard_DS1_v2"
  }
}

매개 변수 사용

매개 변수의 값을 참조하려면 매개 변수 함수를 사용합니다. 다음 예제에서는 키 자격 증명 모음 이름에 매개 변수 값을 사용합니다.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "vaultName": {
      "type": "string",
      "defaultValue": "[format('keyVault{0}', uniqueString(resourceGroup().id))]"
    }
  },
  "resources": [
    {
      "type": "Microsoft.KeyVault/vaults",
      "apiVersion": "2021-06-01-preview",
      "name": "[parameters('vaultName')]",
      ...
    }
  ]
}

개체를 매개 변수로 사용

관련 값을 개체로 전달하여 구성할 수 있습니다. 이렇게 하면 템플릿의 매개 변수 수도 줄어듭니다.

다음 예제에서는 개체인 매개 변수를 보여 줍니다. 기본값은 개체의 예상 속성을 표시합니다. 이러한 속성은 배포할 리소스를 정의할 때 사용됩니다.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "vNetSettings": {
      "type": "object",
      "defaultValue": {
        "name": "VNet1",
        "location": "eastus",
        "addressPrefixes": [
          {
            "name": "firstPrefix",
            "addressPrefix": "10.0.0.0/22"
          }
        ],
        "subnets": [
          {
            "name": "firstSubnet",
            "addressPrefix": "10.0.0.0/24"
          },
          {
            "name": "secondSubnet",
            "addressPrefix": "10.0.1.0/24"
          }
        ]
      }
    }
  },
  "resources": [
    {
      "type": "Microsoft.Network/virtualNetworks",
      "apiVersion": "2021-02-01",
      "name": "[parameters('vNetSettings').name]",
      "location": "[parameters('vNetSettings').location]",
      "properties": {
        "addressSpace": {
          "addressPrefixes": [
            "[parameters('vNetSettings').addressPrefixes[0].addressPrefix]"
          ]
        },
        "subnets": [
          {
            "name": "[parameters('vNetSettings').subnets[0].name]",
            "properties": {
              "addressPrefix": "[parameters('vNetSettings').subnets[0].addressPrefix]"
            }
          },
          {
            "name": "[parameters('vNetSettings').subnets[1].name]",
            "properties": {
              "addressPrefix": "[parameters('vNetSettings').subnets[1].addressPrefix]"
            }
          }
        ]
      }
    }
  ]
}

예제 템플릿

다음 예제는 매개 변수를 사용하는 시나리오를 보여 줍니다.

템플릿	설명
parameters with functions for default values(기본값에 대한 함수가 있는 매개 변수)	매개 변수의 기본값을 정의할 때 템플릿 함수를 사용하는 방법을 보여 줍니다. 템플릿은 리소스를 배포하지 않으며, 매개 변수 값을 구성하고 해당 값을 반환합니다.
parameter object(매개 변수 개체)	매개 변수에 대한 개체 사용을 보여 줍니다. 템플릿은 리소스를 배포하지 않으며, 매개 변수 값을 구성하고 해당 값을 반환합니다.

다음 단계

매개 변수에 사용할 수 있는 속성에 대한 자세한 내용은 ARM 템플릿의 구조 및 구문 이해를 참조하세요.
매개 변수 값을 파일로 전달하는 방법에 대한 자세한 내용은 Resource Manager 매개 변수 파일 만들기를 참조하세요.
매개 변수 만들기에 대한 권장 사항은 모범 사례 - 매개 변수를 참조하세요.