Parámetros de estructura de definición de Azure Policy

  • Artículo

Los parámetros ayudan a simplificar la administración de directivas mediante la reducción del número de definiciones de directiva. Piense en los parámetros como si fueran los campos de un formulario: name, address, city y state. Estos parámetros no cambian, pero sí sus valores en función del individuo que rellena el formulario. Los parámetros funcionan del mismo modo al crear las directivas. Con la inclusión de parámetros en una definición de directiva, puede volver a usar esa directiva en distintos escenarios con valores diferentes.

Adición o eliminación de parámetros

Pueden agregarse parámetros a una definición existente y asignada. El nuevo parámetro debe incluir la propiedad defaultValue. Esta propiedad evita que las asignaciones existentes de la directiva o la iniciativa realizadas indirectamente no sean válidas.

Los parámetros no se pueden quitar de una definición de directiva porque puede haber una asignación que establezca el valor del parámetro y esa referencia se rompería. Algunas definiciones de directiva integradas ponen parámetros en desuso mediante metadatos "deprecated": true, que oculta el parámetro al asignar la definición en Azure Portal. Aunque este método no se admite para las definiciones de directivas personalizadas, otra opción es duplicar y crear una nueva definición de directiva personalizada sin el parámetro.

Propiedades del parámetro

Un parámetro usa las siguientes propiedades en una definición de directiva:

  • name: El nombre del parámetro. Lo utiliza la función de la implementación parameters dentro de la regla de directiva. Para más información, consulte Uso de un valor de parámetro.
  • typeDetermina si el parámetro es de tipo string, array, object, boolean, integer, float o dateTime.
  • metadata: define las subpropiedades que usa principalmente Azure Portal para mostrar información intuitiva:
    • description: La explicación de para qué se usa el parámetro. Puede utilizarse para proporcionar ejemplos de valores aceptables.
    • displayName: El nombre descriptivo que se muestra en el portal para el parámetro.
    • strongType: (Opcional) Se usa al asignar la definición de directiva mediante el portal. Proporciona una lista que tiene en cuenta el contexto. Para más información, consulte strongType.
    • assignPermissions: (Opcional) Establecer como true para que Azure Portal cree asignaciones de roles durante la asignación de directivas. Esta propiedad es útil en caso de que desee asignar permisos fuera del ámbito de asignación. Hay una asignación de roles por cada definición de roles de la directiva (o por cada definición de roles de todas las directivas de la iniciativa). El valor del parámetro debe ser un recurso o un ámbito válidos.
    • deprecated: una marca booleana para indicar si un parámetro está en desuso en una definición integrada.
  • defaultValue: (Opcional) Establece el valor del parámetro en una asignación, si no se especifica ningún valor. Requerido cuando se actualiza una definición de directiva existente que está asignada. Para los parámetros de tipo objeto, el valor debe coincidir con el esquema adecuado.
  • allowedValues: (Opcional) Proporciona una matriz de los valores que acepta el parámetro durante la asignación.
    • Distinción entre mayúsculas y minúsculas: las comparaciones de valores permitidos distinguen mayúsculas de minúsculas al asignar una directiva, lo que significa que los valores de parámetro seleccionados de la asignación deben coincidir con el uso de mayúsculas y minúsculas de los valores de la matriz en la definición allowedValues. Sin embargo, una vez seleccionados los valores para la asignación, la evaluación de comparaciones de cadenas puede no distinguir entre mayúsculas y minúsculas en función de la condición utilizada. Por ejemplo, si el parámetro especifica Dev como un valor de etiqueta permitido en una asignación y este valor se compara con una cadena de entrada mediante la condición equals, Azure Policy evaluaría posteriormente un valor de etiqueta dev como coincidencia aunque sea en minúsculas porque notEquals no distingue mayúsculas de minúsculas.
    • Para los parámetros de tipo objeto, el valor debe coincidir con el esquema adecuado.
  • schema: (Opcional) Proporciona validación de entradas de parámetro durante la asignación mediante un esquema JSON autodefinido. Esta propiedad solo se admite para los parámetros de tipo de objeto y sigue la implementación 2019-09 del esquema Json.NET. Puede obtener más información sobre el uso de esquemas en https://json-schema.org/ y probar borradores de esquemas en https://www.jsonschemavalidator.net/.

Parámetros de ejemplo

Ejemplo 1

Por ejemplo, podría definir una definición de directiva para limitar las ubicaciones en las que se pueden implementar los recursos. Un parámetro para esta directiva podría ser allowedLocations y utilizarse por cada asignación de la definición de directiva para limitar los valores aceptados. El uso de strongType proporciona una experiencia mejorada al completar la asignación mediante el 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"
    ]
  }
}

Una entrada de ejemplo para este parámetro de tipo de matriz (sin strongType) en el momento de la asignación podría ser ["westus", "eastus2"].

Ejemplo 2

En un escenario más avanzado, podría definir una directiva que requiera pods de clúster de Kubernetes para usar etiquetas especificadas. Un parámetro para esa definición de directiva podría ser labelSelector y utilizarse en cada asignación de la definición de directiva para especificar los recursos de Kubernetes en cuestión según las claves de etiqueta y los 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
    }
  },
}

Una entrada de ejemplo de este parámetro de tipo de objeto en el momento de la asignación estaría en formato JSON, se validaría mediante el esquema especificado y podría ser:

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

Uso de un valor de parámetro

En la regla de directiva, se hace referencia a los parámetros con la siguiente sintaxis de función parameters:

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

En este ejemplo se hace referencia al parámetro allowedLocations que se mostró en las propiedades del parámetro.

strongType

Dentro de la propiedad metadata, puede usar strongType para proporcionar una lista de opciones de selección múltiple en Azure Portal. strongType puede ser un tipo de recurso compatible o un valor permitido. Para determinar si un tipo de recurso es válido para strongType, use Get-AzResourceProvider. El formato de un tipo de recursostrongType es <Resource Provider>/<Resource Type>. Por ejemplo, Microsoft.Network/virtualNetworks/subnets.

Se admiten algunos tipos de recursos que no devuelve Get-AzResourceProvider. Estos tipos son:

  • Microsoft.RecoveryServices/vaults/backupPolicies

Los valores permitidos que no son de tipo de recurso para strongType son:

  • location
  • resourceTypes
  • storageSkus
  • vmSKUs
  • existingResourceGroups

Pasos siguientes