Estrutura de definição da iniciativa do Azure Policy

  • Artigo

Iniciativas permitem que você agrupe várias definições de políticas relacionadas para simplificar atribuições e gerenciamento, pois você trabalha com um grupo como um único item. Por exemplo, você pode agrupar as 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 de política contém elementos para:

O exemplo a seguir ilustra como criar uma iniciativa para lidar com duas marcas: costCenter e productName. Ele usa duas políticas internas para aplicar o valor da marca 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 os itens internos do Azure Policy estão em Amostras do Azure Policy.

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 pelo Azure Policy e em itens internos.

Propriedades de metadados comuns

  • version (cadeia de caracteres): controla os detalhes sobre a versão do conteúdo de uma definição de iniciativa de política. Para itens internos, essa versão de metadados segue a propriedade de versão do item interno. É recomendável usar a propriedade de versão nessa versão de metadados.

  • category (cadeia de caracteres): determina em qual categoria do portal do Azure a definição de política é exibida.

    Observação

    Para uma iniciativa de Conformidade regulatória, o category deve ser Conformidade Regulatória.

  • preview (booleano): sinalizador true ou false para se a definição da iniciativa de política for versão preliminar.

  • deprecated (booleano): sinalizador true ou false para se a definição da iniciativa de política tiver sido marcada como preterida.

Versão (versão prévia)

As iniciativas de política internas podem hospedar várias versões com o mesmo definitionID. Se nenhum número de versão for especificado, todas as experiências mostrarão a última versão da definição. Para ver uma versão específica de um item interno, ela deve ser especificada na API, no SDK ou na interface do usuário. Para fazer referência a uma versão específica de uma definição dentro de uma atribuição, consulte versão de definição dentro da atribuição

O serviço Azure Policy usa as propriedades version, preview e deprecated para transmitir o estado e nível de alteração para uma definição ou iniciativa de política interna. O formato de version é: {Major}.{Minor}.{Patch}. Quando uma definição de política está em estado de pré-visualização, o sufixo pré-visualização é anexado à propriedade version e tratado como um booliano. Quando uma definição de política é preterida, a substituição é capturada como um booliano nos metadados da definição usando "deprecated": "true".

  • Versão principal (exemplo: 2.0.0): introduz alterações interruptivas, como alterações principais da lógica de regra, 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 alterações secundárias da lógica de regra, adição de novos valores permitidos de parâmetro, alteração em definitionIds de função, adição ou remoção de definições em uma iniciativa.
  • Versão do patch (exemplo: 2.1.4): introduz alterações de cadeia de caracteres ou metadados e cenários de emergência de segurança (raro).

As iniciativas internas são baseadas em versão 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 versão prévia, 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. Em vez disso, todas as referências de política internas em iniciativas personalizadas criadas por meio do portal serão padrão para a última versão da definição de política.

Para obter mais informações sobre itens internos de versões do Azure Policy, consulte Controle de versão de itens internos. Para saber o que significa uma política ser preterida ou estar em versão prévia, confira Políticas preteridas e em versão prévia.

Parâmetros

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, state. Esses parâmetros sempre permanecem iguais, porém, seus valores mudam com base no preenchimento individual do formulário. Os parâmetros funcionam da mesma maneira que ao criar iniciativas de 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.

Observação

Depois que uma iniciativa é atribuída, os parâmetros no nível da iniciativa não podem ser alterados. Por conta disso, 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 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 é uma cadeia de caracteres, uma matriz, um objeto, um booliano, um inteiro, um float ou um datetime.
  • metadata: define as sub-propriedades usadas principalmente pelo portal do Azure para exibição de informações simples:
    • description: (Opcional) 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.
  • defaultValue: (opcional) define o valor do parâmetro em uma atribuição se não houver valor fornecido.
  • allowedValues: (opcional) fornece uma matriz de valores que o parâmetro aceita durante a atribuição.

Por exemplo, você pode definir uma definição de iniciativa de política para limitar os locais dos recursos nas várias definições de política incluídas. Um parâmetro para essa definição de iniciativa de política pode ser allowedLocations. 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 de 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"
        ]
    }
}

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

Declare quais parâmetros de iniciativa você passa, aos quais foram incluídas definições de política na matriz policyDefinitions da definição da 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 leitura do código.

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

"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')]"
            }
        }
    }
]

Esta amostra 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.

Há suporte para alguns tipos de recursos não retornados pelo Get-AzResourceProvider. Esses tipos de recursos são:

  • Microsoft.RecoveryServices/vaults/backupPolicies

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

  • location
  • resourceTypes
  • storageSkus
  • vmSKUs
  • existingResourceGroups

Definições de política

A parte policyDefinitions da definição da iniciativa é uma matriz, a partir da qual as definições de política existentes são incluídas na iniciativa. Conforme mencionado em Passagem de 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 da Definição de Política

Cada elemento da 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 (cadeia de caracteres): um nome curto para a definição de política incluída.
  • parameters: (opcional) os pares de 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, confira Parâmetros.
  • definitionVersion: (opcional) a versão da definição interna a ser referenciada. Se nenhuma for especificada, ela se referirá à versão principal mais recente no momento da atribuição e irá ingerir automaticamente as atualizações secundárias. Para obter mais informações, consulte versão de definição
  • groupNames (matriz de cadeias de caracteres): (opcional) o grupo do qual a definição de política é membro. Para saber mais, consulte Grupos de políticas.

Aqui está um exemplo de policyDefinitions que tem duas definições de política incluídas que passam pelo 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ções de política

As definições de política em uma definição de iniciativa podem ser agrupadas e categorizadas. O recurso de Conformidade regulatória do Azure Policy (versão preliminar) usa essa propriedade para agrupar definições em controles e domínios de conformidade. Essas informações são definidas na propriedade policyDefinitionGroups da matriz. É possível encontrar mais detalhes de agrupamento em um objeto policyMetadata criado pela Microsoft. Para obter informações, consulte objetos de metadados.

Parâmetros de grupos de definição de política

Cada elemento da matriz em policyDefinitionGroups deve ter as duas propriedades a seguir:

  • name (cadeia de caracteres) [obrigatório]: o nome curto para o grupo. Em Conformidade regulatória, o controle. O valor dessa propriedade é usado por groupNames em policyDefinitions.

  • category (cadeia de caracteres): a hierarquia à qual o grupo pertence. Em Conformidade regulatória, o domínio de conformidade do controle.

  • displayName (cadeia de caracteres): o nome amigável para o grupo ou controle. Usado pelo portal.

  • description (cadeia de caracteres): uma descrição do que o grupo oucontrole abrange.

  • additionalMetadataId (cadeia de caracteres): o local do objeto policyMetadata que tem detalhes adicionais sobre o controle e o domínio de conformidade.

    Observação

    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 propriedade policyDefinitionGroups da definição de iniciativa interna do NIST é semelhante a:

"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 itens internos de Conformidade regulatória criados pela Microsoft têm informações adicionais sobre cada controle. Essas informações são:

  • Exibidas no portal do Azure na visão geral de um controle em uma iniciativa de Conformidade regulatória.
  • Disponíveis por meio da API REST. Consulte o provedor de recursos Microsoft.PolicyInsights e o grupo de operações policyMetadata.
  • Disponível por meio 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 grupo de políticas têm as seguintes informações no nó properties:

  • metadataId: a ID de controle à qual o agrupamento está relacionado.
  • category (obrigatório): o domínio de conformidade ao qual o controle pertence.
  • title (obrigatório): o nome amigável da ID de controle.
  • owner (obrigatório): identifica quem tem responsabilidade pelo controle no Azure: Cliente, Microsoft, Compartilhada.
  • description: informações adicionais sobre o controle.
  • requirements: detalhes sobre a responsabilidade da implementação do controle.
  • additionalContentUrl: um link para obter mais informações sobre o controle. Essa propriedade é geralmente um link para a seção da documentação que aborda esse controle no padrão de conformidade.

Veja abaixo 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óximas etapas