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",
        "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",
                "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.

  • 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.

Observação

O serviço Azure Policy usa as propriedades version, preview e deprecated para transmitir o nível de alteração para uma definição de política interna ou uma iniciativa e um estado. O formato de version é: {Major}.{Minor}.{Patch}. Estados específicos, como preterido ou versão prévia, são acrescentados à propriedade version ou a outra propriedade como um booliano. Para obter mais informações sobre a maneira como o Azure Policy versiona os itens internos, consulte Controle de versão de itens internos.

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.
  • 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",
        "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