Estrutura de definição da iniciativa da Política do Azure

Artigo
07/10/2024

As iniciativas permitem agrupar várias definições de política relacionadas para simplificar atribuições e gerenciamento porque você trabalha com um grupo como um único item. Por exemplo, você pode agrupar definições de política de marcação relacionadas em uma única iniciativa. Em vez de atribuir cada política individualmente, você aplica a iniciativa.

Você usa JSON para criar uma definição de iniciativa de política. A definição de iniciativa política contém elementos para:

nome a apresentar
descrição
do IdP
versão
parâmetros
definições de política
grupos de políticas (esta propriedade faz parte do recurso Conformidade Regulatória (Visualização))

O exemplo a seguir ilustra como criar uma iniciativa para lidar com duas tags: costCenter e productName. Ele usa duas políticas internas para aplicar o valor de tag padrão.

{
    "properties": {
        "displayName": "Billing Tags Policy",
        "policyType": "Custom",
        "description": "Specify cost Center tag and product name tag",
        "version" : "1.0.0",
        "metadata": {
            "version": "1.0.0",
            "category": "Tags"
        },
        "parameters": {
            "costCenterValue": {
                "type": "String",
                "metadata": {
                    "description": "required value for Cost Center tag"
                },
                "defaultValue": "DefaultCostCenter"
            },
            "productNameValue": {
                "type": "String",
                "metadata": {
                    "description": "required value for product Name tag"
                },
                "defaultValue": "DefaultProduct"
            }
        },
        "policyDefinitions": [{
                "policyDefinitionId": "/providers/Microsoft.Authorization/policyDefinitions/1e30110a-5ceb-460c-a204-c1c3969c6d62",
                "definitionVersion": "1.*.*"
                "parameters": {
                    "tagName": {
                        "value": "costCenter"
                    },
                    "tagValue": {
                        "value": "[parameters('costCenterValue')]"
                    }
                }
            },
            {
                "policyDefinitionId": "/providers/Microsoft.Authorization/policyDefinitions/2a0e14a6-b0a6-4fab-991a-187a4f81c498",
                "parameters": {
                    "tagName": {
                        "value": "costCenter"
                    },
                    "tagValue": {
                        "value": "[parameters('costCenterValue')]"
                    }
                }
            },
            {
                "policyDefinitionId": "/providers/Microsoft.Authorization/policyDefinitions/1e30110a-5ceb-460c-a204-c1c3969c6d62",
                "parameters": {
                    "tagName": {
                        "value": "productName"
                    },
                    "tagValue": {
                        "value": "[parameters('productNameValue')]"
                    }
                }
            },
            {
                "policyDefinitionId": "/providers/Microsoft.Authorization/policyDefinitions/2a0e14a6-b0a6-4fab-991a-187a4f81c498",
                "parameters": {
                    "tagName": {
                        "value": "productName"
                    },
                    "tagValue": {
                        "value": "[parameters('productNameValue')]"
                    }
                }
            }
        ]
    }
}

Os padrões e internos da Política do Azure estão em Exemplos de Política do Azure.

Metadados

A propriedade opcional metadata armazena informações sobre a definição da iniciativa de política. Os clientes podem definir quaisquer propriedades e valores úteis para sua organização no metadata. No entanto, há algumas propriedades comuns usadas pela Política do Azure e em internos.

Propriedades comuns de metadados

version (string): rastreia detalhes sobre a versão do conteúdo de uma definição de iniciativa de política. Para built-ins, esta versão de metadados segue a propriedade version do built-in. É recomendável usar a propriedade version sobre essa versão de metadados.
category (string): determina em qual categoria no portal do Azure a definição de política é exibida.

Nota

Para uma iniciativa de Conformidade Regulamentar, a category Conformidade Regulatória deve ser.
preview (booleano): Bandeira verdadeira ou falsa para se a definição da iniciativa política for visualizada.
deprecated (booleano): Sinalizador verdadeiro ou falso para se a definição da iniciativa política tiver sido marcada como obsoleta.

Versão (pré-visualização)

As iniciativas de políticas incorporadas podem alojar várias versões com o mesmo definitionIDficheiro . Se nenhum número de versão for especificado, todas as experiências mostrarão a versão mais recente da definição. Para ver uma versão específica de um built-in, ele deve ser especificado em API, SDK ou UI. Para fazer referência a uma versão específica de uma definição dentro de uma atribuição, consulte Versão da definição dentro da atribuição

O serviço de Política do Azure usa version, previewe deprecated propriedades para transmitir o estado e o nível de alteração para uma definição ou iniciativa de política interna. O formato do version é: {Major}.{Minor}.{Patch}. Quando uma definição de política está no estado de visualização, a visualização do sufixo é anexada version à propriedade e tratada como booleana. Quando uma definição de política é preterida, a depreciação é capturada como um booleano nos metadados da definição usando "deprecated": "true".

Versão principal (exemplo: 2.0.0): introduz alterações de quebra, como alterações de lógica de regras principais, remoção de parâmetros, adição de um efeito de imposição por padrão.
Versão secundária (exemplo: 2.1.0): introduz alterações como pequenas alterações na lógica da regra, adiciona novos valores permitidos de parâmetros, altera a definição de funçãoIds, adiciona ou remove definições dentro de uma iniciativa.
Versão do patch (exemplo: 2.1.4): introduz alterações de cadeia de caracteres ou metadados e quebra de vidro em cenários de segurança (raros).

As iniciativas internas são versionadas e versões específicas de definições de política internas também podem ser referenciadas em iniciativas internas ou personalizadas. Para obter mais informações, consulte definição de referência e versões.

Durante a visualização, ao criar uma iniciativa por meio do portal, você não poderá especificar versões para referências de definição de política internas. Todas as referências de política incorporadas em iniciativas personalizadas criadas através do portal serão, em vez disso, padronizadas para a versão mais recente da definição de política.

Para obter mais informações sobre versões internas da Política do Azure, consulte Controle de versão interno. Para saber mais sobre o que significa uma política ser preterida ou estar em pré-visualização, consulte Pré-visualização e políticas preteridas.

Parâmetros

Os parâmetros ajudam a simplificar a gestão das políticas ao reduzirem o número de definições de política. Pense em parâmetros como os campos em um formulário - name, address, city, state. Estes parâmetros permanecem sempre os mesmos, no entanto os seus valores mudam com base no indivíduo que preenche o formulário. Os parâmetros funcionam da mesma forma quando se elaboram iniciativas políticas. Ao incluir parâmetros em uma definição de iniciativa de política, você pode reutilizar esse parâmetro nas políticas incluídas.

Nota

Depois que uma iniciativa é atribuída, os parâmetros de nível de iniciativa não podem ser alterados. Devido a isso, a recomendação é definir um defaultValue ao definir o parâmetro.

Propriedades do parâmetro

Um parâmetro tem as seguintes propriedades que são usadas na definição de iniciativa política:

name: O nome do seu parâmetro. Usado pela função de parameters implantação dentro da regra de política. Para obter mais informações, consulte o uso de um valor de parâmetro.
type: Determina se o parâmetro é uma cadeia de caracteres, matriz, objeto, booleano, inteiro, float ou datetime.
metadata: Define subpropriedades usadas principalmente pelo portal do Azure para exibir informações amigáveis:
- description: (Opcional) A explicação de para que o parâmetro é usado. Pode ser usado para fornecer exemplos de valores aceitáveis.
- displayName: O nome amigável mostrado no portal para o parâmetro.
- strongType: (Opcional) Usado ao atribuir a definição de política através do portal. Fornece uma lista sensível ao contexto. Para obter mais informações, consulte strongType.
defaultValue: (Opcional) Define o valor do parâmetro em uma atribuição se nenhum valor for dado.
allowedValues: (Opcional) Fornece uma matriz de valores que o parâmetro aceita durante a atribuição.

Como exemplo, você pode definir uma definição de iniciativa de política para limitar os locais de recursos nas várias definições de política incluídas. Um parâmetro para essa definição de iniciativa política poderia ser permitidoLocais. O parâmetro fica então disponível para cada definição de política incluída e definido durante a atribuição da iniciativa política.

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

Passando um valor de parâmetro para uma definição de política

Você declara quais parâmetros de iniciativa você passa para quais definições de política incluídas na matriz policyDefinitions da definição de iniciativa. Embora o nome do parâmetro possa ser o mesmo, o uso de nomes diferentes nas iniciativas do que nas definições de política simplifica a legibilidade do código.

Por exemplo, o parâmetro init_allowedLocations initiative definido anteriormente pode ser passado para várias definições de política incluídas e seus parâmetros, sql_locations e vm_locations, como este:

"policyDefinitions": [
    {
        "policyDefinitionId": "/providers/Microsoft.Authorization/policyDefinitions/0ec8fc28-d5b7-4603-8fec-39044f00a92b",
        "policyDefinitionReferenceId": "allowedLocationsSQL",
        "parameters": {
            "sql_locations": {
                "value": "[parameters('init_allowedLocations')]"
            }
        }
    },
    {
        "policyDefinitionId": "/providers/Microsoft.Authorization/policyDefinitions/aa09bd0f-aa5f-4343-b6ab-a33a6a6304f3",
        "policyDefinitionReferenceId": "allowedLocationsVMs",
        "parameters": {
            "vm_locations": {
                "value": "[parameters('init_allowedLocations')]"
            }
        }
    }
]

Este exemplo faz referência ao parâmetro init_allowedLocations que foi demonstrado nas propriedades dos parâmetros.

strongType

Dentro da metadata propriedade, 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 suportado ou um valor permitido. Para determinar se um tipo de recurso é válido para strongType, use Get-AzResourceProvider.

Alguns tipos de recursos não retornados por Get-AzResourceProvider são suportados. Esses tipos de recursos são:

Microsoft.RecoveryServices/vaults/backupPolicies

Os valores permitidos do tipo não-recurso para strongType são:

location
resourceTypes
storageSkus
vmSKUs
existingResourceGroups

Definições de política

A policyDefinitions parte da definição da iniciativa é uma matriz da qual as definições de políticas existentes estão incluídas na iniciativa. Como mencionado em Passando um valor de parâmetro para uma definição de política, essa propriedade é onde os parâmetros de iniciativa são passados para a definição de política.

Propriedades de definição de política

Cada elemento de matriz que representa uma definição de política tem as seguintes propriedades:

policyDefinitionId (string): a ID da definição de política personalizada ou interna a ser incluída.
policyDefinitionReferenceId (string): Um nome curto para a definição de política incluída.
parameters: (Opcional) Os pares nome/valor para passar um parâmetro de iniciativa para a definição de política incluída como uma propriedade nessa definição de política. Para obter mais informações, consulte Parâmetros.
definitionVersion : (Opcional) A versão da definição interna a que se refere. Se nenhuma for especificada, refere-se à versão principal mais recente no momento da atribuição e à ingestão automática de quaisquer atualizações menores. Para obter mais informações, consulte a versão da definição
groupNames (matriz de cadeias de caracteres): (Opcional) O grupo do qual a definição de política é membro. Para obter mais informações, consulte Grupos de políticas.

Aqui está um exemplo de que tem duas definições de policyDefinitions política incluídas que são passadas cada uma com o mesmo parâmetro de iniciativa:

"policyDefinitions": [
    {
        "policyDefinitionId": "/providers/Microsoft.Authorization/policyDefinitions/0ec8fc28-d5b7-4603-8fec-39044f00a92b",
        "policyDefinitionReferenceId": "allowedLocationsSQL",
        "definitionVersion": "1.2.*"
        "parameters": {
            "sql_locations": {
                "value": "[parameters('init_allowedLocations')]"
            }
        }
    },
    {
        "policyDefinitionId": "/providers/Microsoft.Authorization/policyDefinitions/aa09bd0f-aa5f-4343-b6ab-a33a6a6304f3",
        "policyDefinitionReferenceId": "allowedLocationsVMs",
        "parameters": {
            "vm_locations": {
                "value": "[parameters('init_allowedLocations')]"
            }
        }
    }
]

Grupos de definição de políticas

As definições de política em uma definição de iniciativa podem ser agrupadas e categorizadas. O recurso de Conformidade Regulatória (visualização) da Política do Azure usa essa propriedade para agrupar definições em controles e domínios de conformidade. Essas informações são definidas na policyDefinitionGroups propriedade array . Mais detalhes de agrupamento podem ser encontrados em um objeto policyMetadata criado pela Microsoft. Para obter informações, consulte objetos de metadados.

Definição de políticas agrupa parâmetros

Cada elemento de matriz em policyDefinitionGroups deve ter ambas as seguintes propriedades:

name (string) [required]: O nome abreviado do grupo. Em Conformidade Regulatória, o controle. O valor desta propriedade é usado por groupNames in policyDefinitions.
category (string): A hierarquia à qual o grupo pertence. Em Conformidade Regulatória, o domínio de conformidade do controle.
displayName (string): O nome amigável para o grupo ou controle. Utilizado pelo portal.
description (string): uma descrição do que o grupo ou controle abrange.
additionalMetadataId(string): o local do objeto policyMetadata que tem detalhes adicionais sobre o domínio de controle e conformidade.

Nota

Os clientes podem apontar para um objeto policyMetadata existente. No entanto, esses objetos são somente leitura e criados somente pela Microsoft.

Um exemplo da policyDefinitionGroups propriedade da definição de iniciativa interna do NIST tem esta aparência:

"policyDefinitionGroups": [
    {
        "name": "NIST_SP_800-53_R4_AC-1",
        "additionalMetadataId": "/providers/Microsoft.PolicyInsights/policyMetadata/NIST_SP_800-53_R4_AC-1"
    }
]

Objetos de metadados

Os internos de conformidade regulatória criados pela Microsoft têm informações adicionais sobre cada controle. Esta informação é:

Exibido no portal do Azure na visão geral de um controle em uma iniciativa de Conformidade Regulamentar.
Disponível via API REST. Consulte o Microsoft.PolicyInsights provedor de recursos e o grupo de operação policyMetadata.
Disponível através da CLI do Azure. Consulte o comando az policy metadata .

Importante

Os objetos de metadados para conformidade regulatória são somente leitura e não podem ser criados pelos clientes.

Os metadados de um agrupamento de políticas têm as properties seguintes informações no nó:

metadataId: A ID de controle à qual o agrupamento se relaciona.
category (obrigatório): O domínio de conformidade ao qual o controle pertence.
title (obrigatório): O nome amigável do ID de controle.
owner (obrigatório): Identifica quem é responsável pelo controle no Azure: Cliente, Microsoft, Compartilhado.
description: Informações adicionais sobre o controlo.
requirements: Detalhes sobre a responsabilidade da implementação do controle.
additionalContentUrl: Um link para mais informações sobre o controle. Essa propriedade geralmente é um link para a seção de documentação que abrange esse controle no padrão de conformidade.

Abaixo está um exemplo do objeto policyMetadata . Este exemplo de metadados pertence ao controle NIST SP 800-53 R4 AC-1 .

{
  "properties": {
    "metadataId": "NIST SP 800-53 R4 AC-1",
    "category": "Access Control",
    "title": "Access Control Policy and Procedures",
    "owner": "Shared",
    "description": "**The organization:**    \na. Develops, documents, and disseminates to [Assignment: organization-defined personnel or roles]:  \n1. An access control policy that addresses purpose, scope, roles, responsibilities, management commitment, coordination among organizational entities, and compliance; and  \n2. Procedures to facilitate the implementation of the access control policy and associated access controls; and  \n
\nb. Reviews and updates the current:  \n1. Access control policy [Assignment: organization-defined frequency]; and  \n2. Access control procedures [Assignment: organization-defined frequency].",
    "requirements": "**a.**  The customer is responsible for developing, documenting, and disseminating access control policies and procedures. The customer access control policies and procedures address access to all customer-deployed resources and customer system access (e.g., access to customer-deployed virtual machines, access to customer-built applications).  \n**b.**  The customer is responsible for reviewing and updating access control policies and procedures in accordance with FedRAMP requirements.",
    "additionalContentUrl": "https://nvd.nist.gov/800-53/Rev4/control/AC-1"
  },
  "id": "/providers/Microsoft.PolicyInsights/policyMetadata/NIST_SP_800-53_R4_AC-1",
  "name": "NIST_SP_800-53_R4_AC-1",
  "type": "Microsoft.PolicyInsights/policyMetadata"
}

Próximos passos

Ver a estrutura da definição
Analise exemplos em Exemplos de Política do Azure.
Veja Compreender os efeitos do Policy.
Entenda como criar políticas de forma programática.
Saiba como obter dados de conformidade.
Saiba como corrigir recursos não compatíveis.
Analise o que é um grupo de gerenciamento com Organize seus recursos com grupos de gerenciamento do Azure.

Partilhar via