Conceitos básicos da estrutura de definição do Azure Policy

  • Artigo

Parâmetros ajudam a simplificar o gerenciamento de política, reduzindo o número de definições de política. Pense em parâmetros como os campos em um formulário: name, address, city e state. Esses parâmetros sempre permanecem iguais, porém, os valores deles mudam com base no preenchimento individual do formulário. Os parâmetros funcionam da mesma maneira que ao criar políticas. Ao incluir parâmetros em uma definição de política, você pode reutilizar essa política para diferentes cenários usando valores diferentes.

Adicionando ou removendo parâmetros

Os parâmetros podem ser adicionados a uma definição existente e atribuída. O novo parâmetro precisa incluir a propriedade defaultValue. Isso impede que atribuições existentes da política ou da iniciativa sejam indiretamente tornadas inválidas.

Os parâmetros não podem ser removidos de uma definição de política porque pode haver uma atribuição que define o valor do parâmetro, caso em que essa referência se tornaria inválida. Algumas definições de política internas fazem a preterição de parâmetros usando metadados "deprecated": true, o que oculta o parâmetro ao atribuir a definição no portal do Azure. Embora esse método não seja compatível com definições de política personalizadas, outra opção é duplicar e criar uma definição de política personalizada sem o parâmetro.

Propriedades do parâmetro

Um parâmetro usa as seguintes propriedades em uma definição de política:

  • name: o nome do seu parâmetro. Usado pela função de implantação parameters dentro da regra de política. Para saber mais, confira Usar o valor de parâmetro.
  • type: determina se o parâmetro é um string, array, object, boolean, integer, float ou dateTime.
  • metadata: define as sub-propriedades usadas principalmente pelo portal do Azure para exibição de informações simples:
    • description: a explicação de uso do parâmetro. Pode ser usado para fornecer exemplos de valores aceitáveis.
    • displayName: O nome amigável exibido no portal para o parâmetro.
    • strongType: (opcional) usado ao atribuir a definição de política por meio do portal. Fornece uma lista de reconhecimento de contexto. Para obter mais informações, confira strongType.
    • assignPermissions: (opcional) defina essa opção como true para que o portal do Azure crie atribuições de função durante a atribuição de política. Essa propriedade é útil caso você queira atribuir permissões fora do escopo de atribuição. Há uma atribuição de função por definição de função na política (ou por definição de função em todas as políticas na iniciativa). O valor do parâmetro precisa ser um recurso ou um escopo válido.
    • deprecated: um sinalizador booliano para indicar se um parâmetro foi preterido em uma definição interna.
  • defaultValue: (opcional) define o valor do parâmetro em uma atribuição se não houver valor fornecido. Necessário ao atualizar uma definição de política existente que é atribuída. Para parâmetros do tipo “objeto”, o valor deve corresponder ao esquema apropriado.
  • allowedValues: (opcional) fornece uma matriz de valores que o parâmetro aceita durante a atribuição.
    • Diferenciação de maiúsculas de minúsculas: as comparações de valor permitidas diferenciam maiúsculas de minúsculas ao atribuir uma política, o que significa que os valores de parâmetro selecionados na atribuição devem corresponder à caixa de valores na matriz allowedValues na definição. No entanto, depois que os valores são selecionados para a atribuição, a avaliação das comparações de cadeia de caracteres pode não diferenciar maiúsculas de minúsculas, dependendo da condição usada. Por exemplo, se o parâmetro especificar Dev como um valor de marca permitido em uma atribuição e esse valor for comparado a uma cadeia de caracteres de entrada usando a condição equals, o Azure Policy mais tarde avaliará um valor de marca de dev como uma correspondência, mesmo que seja minúscula porque notEquals não diferencia maiúsculas de minúsculas.
    • Para parâmetros de tipo de objeto, os valores devem corresponder ao esquema apropriado.
  • schema: (opcional) fornece validação de entradas de parâmetro durante a atribuição usando um esquema JSON autodefinido. Essa propriedade só tem suporte para parâmetros do tipo “objeto” e segue a implementação do Esquema Json.NET 2019-09. Saiba mais sobre como usar esquemas em https://json-schema.org/ e como testar esquemas de rascunho em https://www.jsonschemavalidator.net/.

Parâmetros de exemplo

Exemplo 1

Por exemplo, você pode definir uma definição de política para limitar os locais em que os recursos podem ser implantados. Um parâmetro para essa definição de política pode ser allowedLocations e usado por cada atribuição da definição de política para limitar os valores aceitos. O uso de strongType fornece uma experiência aprimorada ao concluir a atribuição por meio do portal:

"parameters": {
  "allowedLocations": {
    "type": "array",
    "metadata": {
      "description": "The list of allowed locations for resources.",
      "displayName": "Allowed locations",
      "strongType": "location"
    },
    "defaultValue": [
      "westus2"
    ],
    "allowedValues": [
      "eastus2",
      "westus2",
      "westus"
    ]
  }
}

Uma entrada de exemplo para esse parâmetro do tipo matriz (sem strongType) no momento da atribuição pode ser ["westus", "eastus2"].

Exemplo 2

Em um cenário mais avançado, é possível definir uma política que exige que os pods de cluster do Kubernetes usem rótulos especificados. Um parâmetro para essa definição de política poderia ser labelSelector, que poderia ser usado por cada atribuição da definição de política para especificar recursos do Kubernetes em questão com base em chaves de rótulo e valores:

"parameters": {
  "labelSelector": {
    "type": "Object",
    "metadata": {
      "displayName": "Kubernetes label selector",
      "description": "Label query to select Kubernetes resources for policy evaluation. An empty label selector matches all Kubernetes resources."
    },
    "defaultValue": {},
    "schema": {
      "description": "A label selector is a label query over a set of resources. The result of matchLabels and matchExpressions are ANDed. An empty label selector matches all resources.",
      "type": "object",
      "properties": {
        "matchLabels": {
          "description": "matchLabels is a map of {key,value} pairs.",
          "type": "object",
          "additionalProperties": {
            "type": "string"
          },
          "minProperties": 1
        },
        "matchExpressions": {
          "description": "matchExpressions is a list of values, a key, and an operator.",
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "key": {
                "description": "key is the label key that the selector applies to.",
                "type": "string"
              },
              "operator": {
                "description": "operator represents a key's relationship to a set of values.",
                "type": "string",
                "enum": [
                  "In",
                  "NotIn",
                  "Exists",
                  "DoesNotExist"
                ]
              },
              "values": {
                "description": "values is an array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty.",
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            },
            "required": [
              "key",
              "operator"
            ],
            "additionalProperties": false
          },
          "minItems": 1
        }
      },
      "additionalProperties": false
    }
  },
}

Uma entrada de exemplo para esse parâmetro do tipo “objeto” no momento da atribuição estaria no formato JSON, seria validada pelo esquema especificado e poderia ser o seguinte:

{
  "matchLabels": {
    "poolID": "abc123",
    "nodeGroup": "Group1",
    "region": "southcentralus"
  },
  "matchExpressions": [
    {
      "key": "name",
      "operator": "In",
      "values": [
        "payroll",
        "web"
      ]
    },
    {
      "key": "environment",
      "operator": "NotIn",
      "values": [
        "dev"
      ]
    }
  ]
}

Usando um valor de parâmetro

Na regra de política, você referencia os parâmetros com a seguinte sintaxe de função parameters:

{
  "field": "location",
  "in": "[parameters('allowedLocations')]"
}

Este exemplo faz referência ao parâmetro allowedLocations que foi demonstrado nas propriedades do parâmetro.

strongType

Na propriedade metadata, você pode usar strongType para fornecer uma lista de opções de seleção múltipla no portal do Azure. strongType pode ser um tipo de recurso compatível ou um valor permitido. Para determinar se um tipo de recurso é válido para strongType, use Get-AzResourceProvider. O formato de um tipo de recursostrongType é <Resource Provider>/<Resource Type>. Por exemplo, Microsoft.Network/virtualNetworks/subnets.

Alguns tipos de recurso não retornados por Get-AzResourceProvider são compatíveis. Esses tipos são:

  • Microsoft.RecoveryServices/vaults/backupPolicies

Os valores permitidos que não são tipo de recurso para strongType são:

  • location
  • resourceTypes
  • storageSkus
  • vmSKUs
  • existingResourceGroups

Próximas etapas