Información general del proveedor AzAPI de Terraform

Artículo
11/05/2024

El proveedor AzAPI es una fina capa que está sobre las API REST de Azure ARM. Permite administrar cualquier tipo de recurso de Azure mediante cualquier versión de API, lo que le permite usar las funcionalidades más recientes en Azure. AzAPI es un proveedor de primera categoría diseñado para usarse por su cuenta o junto con el proveedor AzureRM.

Recursos

Para poder administrar todos los recursos y características de Azure sin necesidad de actualizaciones, el proveedor AzAPI incluye los siguientes recursos genéricos:

Nombre del recurso	Descripción
azapi_resource	Se usa para administrar completamente cualquier recurso de Azure (plano de control) (API) con CRUD completo. Casos de uso de ejemplo: Nuevo servicio de vista previa Nueva característica agregada al servicio existente Característica o servicio existente sin utilizar actualmente
azapi_update_resource	Sirve para administrar recursos o partes de recursos que no tienen un CRUD completo Casos de uso de ejemplo: Actualización de nuevas propiedades en un servicio existente Actualización del recurso secundario creado previamente, como el registro SOA del DNS.
azapi_resource_action	Sirve para realizar una sola operación en un recurso sin administrar el ciclo de vida de este. Casos de uso de ejemplo: Apagar una máquina virtual Añadir un secreto a Key Vault
azapi_data_plane_resource	Sirve para administrar un subconjunto específico de recursos del plano de datos de Azure Casos de uso de ejemplo: Contactos de certificado de KeyVault Bibliotecas del área de trabajo de Synapse

Jerarquía de uso

En general, el modo de uso debe tener en cuenta estos pasos:

Siempre se recomienda empezar por realizar tantas operaciones como sea posible en azapi_resource.
Si el tipo de recurso no existe dentro de azapi_resource, pero se encuentra en uno de los tipos admitidos por azapi_data_plane_resource, úselo en su lugar.
Si el recurso ya existe en AzureRM o tiene una propiedad a la que no se puede acceder dentro de azapi_resource, use azapi_update_resource para acceder a estas propiedades específicas. Los recursos que no admiten azapi_resource o azapi_data_plane_resource no se pueden actualizar a través de este recurso.
Si está va a realizar una acción que no se basa en un recurso de Azure compatible con CRUD, azapi_resource_action será menos directo que azapi_update_resource, pero más flexible.

Ejemplos de configuración de recursos

El siguiente fragmento de código configura un recurso que no existe actualmente en el proveedor AzureRM:

resource "azapi_resource" "publicip" {
  type      = "Microsoft.Network/Customipprefixes@2021-03-01"
  name      = "exfullrange"
  parent_id = azurerm_resource_group.example.id
  location  = "westus2"

  body = {
    properties = {
      cidr          = "10.0.0.0/24"
      signedMessage = "Sample Message for WAN"
    }
  }
}

El siguiente fragmento de código configura una propiedad preliminar para un recurso existente de AzureRM:

resource "azapi_update_resource" "test" {
  type        = "Microsoft.ContainerRegistry/registries@2020-11-01-preview"
  resource_id = azurerm_container_registry.acr.id

  body = {
    properties = {
      anonymousPullEnabled = var.bool_anonymous_pull
    }
  }
}

El siguiente fragmento de código configura una acción de recurso en un recurso de AzureRM existente:

resource "azapi_resource_action" "vm_shutdown" {
  type = "Microsoft.Compute/virtualMachines@2023-07-01"
  resource_id = azurerm_linux_virtual_machine.example.id
  action = "powerOff”
}

El fragmento de código siguiente configura un recurso que no existe actualmente en el proveedor AzureRM ya que se aprovisiona en el plano de datos:

resource "azapi_data_plane_resource" "dataset" {
  type      = "Microsoft.Synapse/workspaces/datasets@2020-12-01"
  parent_id = trimprefix(data.azurerm_synapse_workspace.example.connectivity_endpoints.dev, "https://")
  name      = "example-dataset"
  body = {
    properties = {
      type = "AzureBlob",
      typeProperties = {
        folderPath = {
          value = "@dataset().MyFolderPath"
          type  = "Expression"
        }
        fileName = {
          value = "@dataset().MyFileName"
          type  = "Expression"
        }
        format = {
          type = "TextFormat"
        }
      }
      parameters = {
        MyFolderPath = {
          type = "String"
        }
        MyFileName = {
          type = "String"
        }
      }
    }
  }
}

Autenticación mediante el proveedor AzAPI

El proveedor AzAPI permite los mismos métodos de autenticación que el proveedor AzureRM. Para obtener más información sobre las opciones de autenticación, consulte Autenticación de Terraform en Azure.

Ventajas de usar el proveedor AzAPI

El proveedor AzAPI ofrece las siguientes ventajas:

Admite todos los servicios del plano de control de Azure:
- Servicios y características en versión preliminar
- Todas las versiones de API
Fidelidad completa del archivo de estado de Terraform
- Las propiedades y los valores se guardan en el estado
Sin dependencia de Swagger
Autenticación común y coherente de Azure
Extensión VS Code robusta

Solución y ciclo de vida del proveedor AzAPI

En esta sección se describen algunas herramientas que le ayudarán a usar el proveedor AzAPI.

Extensión VS Code y servidor de lenguaje

La extensión VS Code de AzAPI aporta una solución de creación enriquecida con las siguientes ventajas:

Muestra todos los tipos de recursos y versiones de API disponibles.
Finalización automática de propiedades y valores permitidos en cualquier recurso.
Muestra sugerencias al dejar el cursor sobre una propiedad.
Validación de sintaxis
Finalización automática con ejemplos de código.

Herramienta de migración AzAPI2AzureRM

El proveedor AzureRM ofrece el entorno de Terraform más integrado para administrar recursos de Azure. De este modo, el uso recomendado de los proveedores AzAPI y AzureRM es el siguiente:

Mientras el servicio o la característica están en versión preliminar, use el proveedor AzAPI.
Una vez que el servicio se lance oficialmente, use el proveedor AzureRM.

La herramienta AzAPI2AzureRM está diseñada para migrar del proveedor AzAPI al proveedor AzureRM.

AzAPI2AzureRM es una herramienta de código abierto que automatiza el proceso de conversión de recursos de AzAPI en recursos de AzureRM.

AzAPI2AzureRM tiene dos modos: planificar y migrar.

La planificación muestra los recursos de AzAPI que se pueden migrar.
La migración se encarga de migrar los recursos de AzAPI a los recursos de AzureRM tanto en los archivos de HCL como en el estado.

AzAPI2AzureRM garantiza después de la migración que la configuración y el estado de Terraform se ajusten al estado real. Puede validar el cambio del estado ejecutando terraform plan después de completar la migración para ver que nada ha cambiado.

Uso del proveedor AzAPI

Instale la extensión VS Code.

Agregue el proveedor AzAPI a la configuración de Terraform.

terraform {
  required_providers {
    azapi = {
      source  = "Azure/azapi"
    }
  }
}

provider "azapi" {
  # More information on the authentication methods supported by
  # the AzureRM Provider can be found here:
  # https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs

  # subscription_id = "..."
  # client_id       = "..."
  # client_secret   = "..."
  # tenant_id       = "..."
}

Declare uno o varios recursos de AzAPI, tal como se muestra en el código de ejemplo siguiente:

resource "azapi_resource" "example" {
  name = "example"
  parent_id = data.azurerm_machine_learning_workspace.existing.id
  type = "Microsoft.MachineLearningServices/workspaces/computes@2021-07-01"

  location = "eastus"
  body = {
    properties = {
      computeType      = "ComputeInstance"
      disableLocalAuth = true
      properties = {
        vmSize = "STANDARD_NC6"
      }
    }
  }
}

Compartir vía