Início Rápido: Usar o Bicep para criar e publicar uma definição de Aplicativo Gerenciado do Azure

Artigo
09/22/2024

Esse início rápido descreve como usar o Bicep para criar e publicar uma definição de Aplicativo Gerenciado do Azure no seu catálogo de serviços. As definições no seu catálogo de serviços estão disponíveis para os membros da sua organização.

Para criar e publicar uma definição de aplicativo gerenciado no seu catálogo de serviços, execute as seguintes tarefas:

Use o Bicep para desenvolver seu modelo e convertê-lo em um modelo do Azure Resource Manager (modelo do ARM). O modelo define os recursos do Azure implantados pelo aplicativo gerenciado.
Converta o Bicep em JSON com o comando build do Bicep. Após o arquivo ter sido convertido em JSON, verifique se o código está correto.
Defina os elementos da interface do usuário para o portal ao implantar o aplicativo gerenciado.
Crie um pacote .zip que contenha os arquivos JSON necessários. O arquivo do pacote .zip tem um limite de 120 MB para uma definição de aplicativo gerenciado do catálogo de serviços.
Publique a definição de aplicativo gerenciado para que ela esteja disponível no catálogo de serviços.

Se a definição do aplicativo gerenciado for superior a 120 MB ou se você quiser usar sua própria conta de armazenamento por motivos de conformidade da sua organização, acesse Início Rápido: Traga seu próprio armazenamento para criar e publicar uma definição de Aplicativo Gerenciado do Azure.

Você também pode usar o Bicep para implantar uma definição de aplicativo gerenciado do catálogo de serviços. Para obter mais informações, vá para Início Rápido: Usar o Bicep para implantar uma definição de Aplicativo Gerenciado do Azure.

Pré-requisitos

Para executar as tarefas incluídas neste artigo, você precisará dos seguintes itens:

Uma conta do Azure com uma assinatura ativa e permissões para recursos do Microsoft Entra, como usuários, grupos ou entidades de serviço. Se você ainda não tiver uma conta, crie uma conta gratuita antes de começar.
Visual Studio Code com a extensão Ferramentas do Resource Manager mais recente. Para arquivos Bicep, instale a extensão Bicep para Visual Studio Code.
Instale a versão mais recente do Azure PowerShell ou da CLI do Azure.

Criar um arquivo Bicep

Cada definição de aplicativo gerenciado contém um arquivo chamado mainTemplate.json. O modelo define os recursos do Azure a serem implantados e não é diferente de um modelo normal do ARM. Você pode desenvolver o modelo usando o Bicep e, a seguir, converter o arquivo Bicep em JSON.

Abra o Visual Studio Code, crie um arquivo com o nome mainTemplate.bicep diferenciando maiúsculas de minúsculas e salve-o.

Adicione o seguinte código do Bicep e salve o arquivo. Ela define os recursos do aplicativo gerenciado para implantar um plano de Serviço de Aplicativo, Serviço de Aplicativo e uma conta de armazenamento.

param location string = resourceGroup().location

@description('App Service plan name.')
@maxLength(40)
param appServicePlanName string

@description('App Service name prefix.')
@maxLength(47)
param appServiceNamePrefix string

var appServicePlanSku = 'B1'
var appServicePlanCapacity = 1
var appServiceName = '${appServiceNamePrefix}${uniqueString(resourceGroup().id)}'
var linuxFxVersion = 'DOTNETCORE|8.0'

resource appServicePlan 'Microsoft.Web/serverfarms@2023-01-01' = {
  name: appServicePlanName
  location: location
  sku: {
    name: appServicePlanSku
    capacity: appServicePlanCapacity
  }
  kind: 'linux'
  properties: {
    zoneRedundant: false
    reserved: true
  }
}

resource appService 'Microsoft.Web/sites@2023-01-01' = {
  name: appServiceName
  location: location
  properties: {
    serverFarmId: appServicePlan.id
    httpsOnly: true
    redundancyMode: 'None'
    siteConfig: {
      linuxFxVersion: linuxFxVersion
      minTlsVersion: '1.2'
      ftpsState: 'Disabled'
    }
  }
}

output appServicePlan string = appServicePlanName
output appServiceApp string = appService.properties.defaultHostName

Converter de Bicep para JSON

Use o PowerShell ou a CLI do Azure para compilar o arquivo mainTemplate.json . Vá para o diretório no qual você salvou seu arquivo Bicep e execute o comando build.

PowerShell do Azure
CLI do Azure

bicep build mainTemplate.bicep

az bicep build --file mainTemplate.bicep

Para saber mais, vá para a compilação do Bicep.

Após o arquivo Bicep ter sido convertido em JSON, seu arquivo mainTemplate.json deverá corresponder ao exemplo a seguir. Você poderá ter valores diferentes nas propriedades de metadata para version e templateHash.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "metadata": {
    "_generator": {
      "name": "bicep",
      "version": "0.30.3.12046",
      "templateHash": "16466621031230437685"
    }
  },
  "parameters": {
    "location": {
      "type": "string",
      "defaultValue": "[resourceGroup().location]"
    },
    "appServicePlanName": {
      "type": "string",
      "maxLength": 40,
      "metadata": {
        "description": "App Service plan name."
      }
    },
    "appServiceNamePrefix": {
      "type": "string",
      "maxLength": 47,
      "metadata": {
        "description": "App Service name prefix."
      }
    }
  },
  "variables": {
    "appServicePlanSku": "B1",
    "appServicePlanCapacity": 1,
    "appServiceName": "[format('{0}{1}', parameters('appServiceNamePrefix'), uniqueString(resourceGroup().id))]",
    "linuxFxVersion": "DOTNETCORE|8.0"
  },
  "resources": [
    {
      "type": "Microsoft.Web/serverfarms",
      "apiVersion": "2023-01-01",
      "name": "[parameters('appServicePlanName')]",
      "location": "[parameters('location')]",
      "sku": {
        "name": "[variables('appServicePlanSku')]",
        "capacity": "[variables('appServicePlanCapacity')]"
      },
      "kind": "linux",
      "properties": {
        "zoneRedundant": false,
        "reserved": true
      }
    },
    {
      "type": "Microsoft.Web/sites",
      "apiVersion": "2023-01-01",
      "name": "[variables('appServiceName')]",
      "location": "[parameters('location')]",
      "properties": {
        "serverFarmId": "[resourceId('Microsoft.Web/serverfarms', parameters('appServicePlanName'))]",
        "httpsOnly": true,
        "redundancyMode": "None",
        "siteConfig": {
          "linuxFxVersion": "[variables('linuxFxVersion')]",
          "minTlsVersion": "1.2",
          "ftpsState": "Disabled"
        }
      },
      "dependsOn": [
        "[resourceId('Microsoft.Web/serverfarms', parameters('appServicePlanName'))]"
      ]
    }
  ],
  "outputs": {
    "appServicePlan": {
      "type": "string",
      "value": "[parameters('appServicePlanName')]"
    },
    "appServiceApp": {
      "type": "string",
      "value": "[reference(resourceId('Microsoft.Web/sites', variables('appServiceName')), '2023-01-01').defaultHostName]"
    }
  }
}

Definir a sua experiência do portal

Como publicador, você define a experiência do portal para criar o aplicativo gerenciado. O arquivo createUiDefinition.json gera a interface do usuário do portal. Você define como os usuários fornecem a entrada para cada parâmetro usando elementos de controle, incluindo menus suspensos e caixas de texto.

Neste exemplo, a interface do usuário solicita que você insira o prefixo de nome do Serviço de Aplicativo e o nome do plano do Serviço de Aplicativo. Durante a implantação de mainTemplate.json, as variáveis appServiceName usam a função uniqueString para acrescentar uma cadeia de caracteres de 13 caracteres aos prefixos de nome para que os nomes sejam globalmente exclusivos no Azure.

Abra o Visual Studio Code, crie um arquivo com o nome createUiDefinition.json diferenciando maiúsculas de minúsculas e salve-o.

Adicione ao arquivo o código JSON a seguir e salve-o.

{
  "$schema": "https://schema.management.azure.com/schemas/0.1.2-preview/CreateUIDefinition.MultiVm.json#",
  "handler": "Microsoft.Azure.CreateUIDef",
  "version": "0.1.2-preview",
  "parameters": {
    "basics": [
      {}
    ],
    "steps": [
      {
        "name": "webAppSettings",
        "label": "Web App settings",
        "subLabel": {
          "preValidation": "Configure the web app settings",
          "postValidation": "Completed"
        },
        "elements": [
          {
            "name": "appServicePlanName",
            "type": "Microsoft.Common.TextBox",
            "label": "App Service plan name",
            "placeholder": "App Service plan name",
            "defaultValue": "",
            "toolTip": "Use alphanumeric characters or hyphens with a maximum of 40 characters.",
            "constraints": {
              "required": true,
              "regex": "^[a-z0-9A-Z-]{1,40}$",
              "validationMessage": "Only alphanumeric characters or hyphens are allowed, with a maximum of 40 characters."
            },
            "visible": true
          },
          {
            "name": "appServiceName",
            "type": "Microsoft.Common.TextBox",
            "label": "App Service name prefix",
            "placeholder": "App Service name prefix",
            "defaultValue": "",
            "toolTip": "Use alphanumeric characters or hyphens with minimum of 2 characters and maximum of 47 characters.",
            "constraints": {
              "required": true,
              "regex": "^[a-z0-9A-Z-]{2,47}$",
              "validationMessage": "Only alphanumeric characters or hyphens are allowed, with a minimum of 2 characters and maximum of 47 characters."
            },
            "visible": true
          }
        ]
      }
    ],
    "outputs": {
      "location": "[location()]",
      "appServicePlanName": "[steps('webAppSettings').appServicePlanName]",
      "appServiceNamePrefix": "[steps('webAppSettings').appServiceName]"
    }
  }
}

Para saber mais, consulte Introdução a CreateUiDefinition.

Empacote os arquivos

Adicione os dois arquivos a um arquivo de pacote chamado app.zip. Os dois arquivos precisam estar no nível raiz do arquivo .zip. Se você colocar os arquivos em uma pasta, receberá um erro indicando que os arquivos necessários não estão presentes ao criar a definição de aplicativo gerenciado.

Carregue o arquivo app.zip em uma conta de armazenamento do Azure para que você possa usá-la ao implantar a definição do aplicativo gerenciado. O nome da conta de armazenamento deve ser globalmente exclusivo no Azure e o comprimento deve ser de 3 a 24 caracteres com apenas letras minúsculas e números. No comando, substitua o espaço reservado <pkgstorageaccountname>, incluindo os colchetes angulares (<>), pelo nome exclusivo da conta de armazenamento.

PowerShell do Azure
CLI do Azure

No Visual Studio Code, abra um novo terminal do PowerShell e entre em sua assinatura do Azure.

Connect-AzAccount

O comando abre o navegador padrão e solicita que você entre no Azure. Para obter mais informações, vá para Entrar com o Azure PowerShell.

Após se conectar, execute os comandos a seguir.

New-AzResourceGroup -Name packageStorageGroup -Location westus

$pkgstorageparms = @{
  ResourceGroupName = "packageStorageGroup"
  Name = "<pkgstorageaccountname>"
  Location = "westus"
  SkuName = "Standard_LRS"
  Kind = "StorageV2"
  MinimumTlsVersion = "TLS1_2"
  AllowBlobPublicAccess = $true
  AllowSharedKeyAccess = $false
}

$pkgstorageaccount = New-AzStorageAccount @pkgstorageparms

A variável $pkgstorageparms usa o fracionamento do PowerShell para melhorar a legibilidade dos valores de parâmetro usados no comando para criar um novo armazenamento. O fracionamento é usado em outros comandos do PowerShell que usam vários valores de parâmetro.

Após criar a conta de armazenamento, adicione a atribuição de função Colaborador de Dados de Blob de Armazenamento ao escopo da conta de armazenamento. Atribua o acesso à sua conta de usuário do Microsoft Entra. Dependendo do seu nível de acesso no Azure, talvez você precise de outras permissões atribuídas pelo administrador. Para obter mais informações, consulte Atribuir uma função do Azure para acesso a dados de blob e atribuir funções do Azure usando o portal do Azure.

Após adicionar a função à conta de armazenamento, leva alguns minutos para ficar ativa no Azure. Em seguida, você pode criar o contexto necessário para criar o contêiner e carregar o arquivo.

$pkgstoragecontext = New-AzStorageContext -StorageAccountName $pkgstorageaccount.StorageAccountName -UseConnectedAccount

New-AzStorageContainer -Name appcontainer -Context $pkgstoragecontext -Permission blob

$blobparms = @{
  File = "app.zip"
  Container = "appcontainer"
  Blob = "app.zip"
  Context = $pkgstoragecontext
}

Set-AzStorageBlobContent @blobparms

Use o comando a seguir para armazenar o URI do arquivo de pacote em uma variável chamada packageuri. Você usará o valor dessa variável ao implantar a definição de aplicativo gerenciado.

$packageuri=(Get-AzStorageBlob -Container appcontainer -Blob app.zip -Context $pkgstoragecontext).ICloudBlob.StorageUri.PrimaryUri.AbsoluteUri

No Visual Studio Code, abra uma nova sessão do terminal Bash e entre com sua assinatura do Azure. Por exemplo, se tiver o Git instalado, selecione Git Bash.

az login

O comando abre o navegador padrão e solicita que você entre no Azure. Para obter mais informações, acesse Entrar com a CLI do Azure .

Após se conectar, execute os comandos a seguir.

az group create --name packageStorageGroup --location westus

az storage account create \
  --name <pkgstorageaccountname> \
  --resource-group packageStorageGroup \
  --location westus \
  --sku Standard_LRS \
  --kind StorageV2 \
  --min-tls-version TLS1_2 \
  --allow-blob-public-access true \
  --allow-shared-key-access false

pkgstgacct=$(az storage account show \
  --resource-group packageStorageGroup \
  --name <pkgstorageaccountname> \
  --query name \
  --output tsv)

A barra invertida (\) é um caractere de continuação de linha para melhorar a legibilidade dos parâmetros do comando e é usada em muitos dos comandos da CLI do Azure. A variável pkgstgacct contém o nome da conta de armazenamento para uso em outros comandos.

Após criar a conta de armazenamento, adicione a atribuição de função Colaborador de Dados de Blob de Armazenamento ao escopo da conta de armazenamento. Atribua o acesso à sua conta de usuário do Microsoft Entra. Dependendo do seu nível de acesso no Azure, talvez você precise de outras permissões atribuídas pelo administrador. Para saber mais, consulte Atribuir uma função do Azure para acesso a dados de blob.

Após adicionar a função à conta de armazenamento, leva alguns minutos para ficar ativa no Azure. Em seguida, você poderá usar o parâmetro --auth-mode login nos comandos para criar o contêiner e carregar o arquivo.

az storage container create \
  --account-name $pkgstgacct \
  --name appcontainer \
  --auth-mode login \
  --public-access blob

az storage blob upload \
  --account-name $pkgstgacct \
  --container-name appcontainer \
  --auth-mode login \
  --name "app.zip" \
  --file "app.zip"

Para obter mais informações sobre a autenticação de armazenamento, consulte Escolher como autorizar o acesso a dados de blob com a CLI do Azure.

Use o comando a seguir para armazenar o URI do arquivo de pacote em uma variável chamada packageuri. Você usará o valor dessa variável ao implantar a definição de aplicativo gerenciado.

packageuri=$(az storage blob url \
  --account-name $pkgstgacct \
  --container-name appcontainer \
  --auth-mode login \
  --name app.zip --output tsv)

Criar a definição de aplicativo gerenciado

Nesta seção, você obtém informações de identidade do Microsoft Entra ID, cria um grupo de recursos e implanta a definição de aplicativo gerenciado.

Obter ID do grupo e ID de definição de função

A próxima etapa é selecionar um grupo de segurança, um usuário ou um aplicativo para gerenciar os recursos para o cliente. Essa identidade tem permissões no grupo de recursos gerenciados de acordo com a função atribuída. A função pode ser qualquer função interna do Azure, como Proprietário ou Colaborador.

Este exemplo usa um grupo de segurança e sua conta do Microsoft Entra deve ser um membro do grupo. Para obter a ID do objeto do grupo, substitua o espaço reservado <managedAppDemo>, incluindo os colchetes angulares (<>), pelo nome do grupo. Você usará o valor dessa variável ao implantar a definição de aplicativo gerenciado.

Para criar um novo grupo do Microsoft Entra, acesse Gerenciar grupos do Microsoft Entra e associação de grupo.

PowerShell do Azure
CLI do Azure

$principalid=(Get-AzADGroup -DisplayName <managedAppDemo>).Id

principalid=$(az ad group show --group <managedAppDemo> --query id --output tsv)

Em seguida, você precisará da ID de definição de função da função interna do Azure para conceder acesso ao usuário, grupo ou aplicativo. Você usará o valor dessa variável ao implantar a definição de aplicativo gerenciado.

PowerShell do Azure
CLI do Azure

$roleid=(Get-AzRoleDefinition -Name Owner).Id

roleid=$(az role definition list --name Owner --query [].name --output tsv)

Criar o modelo de implantação de definição

Use um arquivo Bicep para implantar a definição de aplicativo gerenciado em seu catálogo de serviços.

Abra o Visual Studio Code, crie um arquivo com o nome deployDefinition.bicep e salve-o.

Adicione o seguinte código do Bicep e salve o arquivo.

param location string = resourceGroup().location

@description('Name of the managed application definition.')
param managedApplicationDefinitionName string

@description('The URI of the .zip package file.')
param packageFileUri string

@description('Publishers Principal ID that needs permissions to manage resources in the managed resource group.')
param principalId string

@description('Role ID for permissions to the managed resource group.')
param roleId string

var definitionLockLevel = 'ReadOnly'
var definitionDisplayName = 'Sample Bicep managed application'
var definitionDescription = 'Sample Bicep managed application that deploys web resources'

resource managedApplicationDefinition 'Microsoft.Solutions/applicationDefinitions@2021-07-01' = {
  name: managedApplicationDefinitionName
  location: location
  properties: {
    lockLevel: definitionLockLevel
    description: definitionDescription
    displayName: definitionDisplayName
    packageFileUri: packageFileUri
    authorizations: [
      {
        principalId: principalId
        roleDefinitionId: roleId
      }
    ]
  }
}

Para obter mais informações sobre as propriedades do modelo, confira Microsoft.Solutions/applicationDefinitions.

O lockLevel no grupo de recursos gerenciados impede que o cliente execute operações indesejáveis nesse grupo de recursos. Atualmente, ReadOnly é o único nível de bloqueio com suporte. ReadOnly especifica que o cliente pode ler somente os recursos presentes no grupo de recursos gerenciados. As identidades do publicador que concedem acesso ao grupo de recursos gerenciado são isentas de bloqueio.

Criar o arquivo de parâmetros

O modelo de implantação da definição de aplicativo gerenciado precisa de entrada para vários parâmetros. O comando de implantação solicita os valores ou você pode criar um arquivo de parâmetros para os valores. Neste exemplo, usamos um arquivo de parâmetros para passar os valores de parâmetro para o comando de implantação.

No Visual Studio Code, crie um novo arquivo chamado deployDefinition-parameters.bicepparam e salve-o.

Adicione o seguinte ao arquivo de parâmetro e salve-o. Em seguida, substitua o <placeholder values>, incluindo os colchetes angulares (<>), por seus valores.

using './deployDefinition.bicep'

param managedApplicationDefinitionName = 'sampleBicepManagedApplication'
param packageFileUri = '<placeholder for the packageFileUri>'
param principalId = '<placeholder for principalid value>'
param roleId = '<placeholder for roleid value>'

A tabela a seguir descreve os valores de parâmetros para a definição do aplicativo gerenciado.

Parâmetro	Valor
`managedApplicationDefinitionName`	Nome da definição de aplicativo gerenciado. Para esse exemplo, use sampleBicepManagedApplication.
`packageFileUri`	Insira o URI no arquivo de pacote .zip. Use o valor da variável `packageuri`.
`principalId`	A ID da entidade de segurança do editor que precisa de permissões para gerenciar recursos no grupo de recursos gerenciados. Use o valor da variável `principalid`.
`roleId`	ID da função para permissões para o grupo de recursos gerenciados. Por exemplo, Proprietário, Colaborador, Leitor. Use o valor da variável `roleid`.

Para obter seus valores variáveis:

Azure PowerShell: No PowerShell, digite $variableName para exibir o valor de uma variável.
CLI do Azure: no Bash, digite echo $variableName para exibir o valor de uma variável.

Implantar a definição

Quando você implanta a definição de aplicativo gerenciado, ela fica disponível no catálogo de serviços. Esse processo não implanta os recursos do aplicativo gerenciado.

Crie um grupo de recursos chamado bicepDefinitionGroup e implante a definição do aplicativo gerenciado.

PowerShell do Azure
CLI do Azure

New-AzResourceGroup -Name bicepDefinitionGroup -Location westus

$deployparms = @{
  ResourceGroupName = "bicepDefinitionGroup"
  TemplateFile = "deployDefinition.bicep"
  TemplateParameterFile = "deployDefinition-parameters.bicepparam"
  Name = "deployDefinition"
}

New-AzResourceGroupDeployment @deployparms

az group create --name bicepDefinitionGroup --location westus

az deployment group create \
  --resource-group bicepDefinitionGroup \
  --template-file deployDefinition.bicep \
  --parameters deployDefinition-parameters.bicepparam \
  --name "deployDefinition"

Verifique os resultados

Execute o comando a seguir para verificar se a definição foi publicada no seu catálogo de serviços.

PowerShell do Azure
CLI do Azure

Get-AzManagedApplicationDefinition -ResourceGroupName bicepDefinitionGroup

Get-AzManagedApplicationDefinition lista todas as definições disponíveis no grupo de recursos especificado, como sampleBicepManagedApplication.

az managedapp definition list --resource-group bicepDefinitionGroup

O comando lista todas as definições disponíveis no grupo de recursos especificado, como sampleBicepManagedApplication.

Verifique se os usuários podem ver sua definição

Você tem acesso à definição de aplicativo gerenciado, mas você deve certificar-se de que outros usuários na sua organização podem acessá-lo. Conceda a eles pelo menos a função de Leitor para a definição. Eles podem ter herdado esse nível de acesso da assinatura ou grupo de recursos. Para verificar quem tem acesso à definição e adicionar usuários ou grupos, confira Atribuir funções do Azure usando o portal do Azure.

Limpar recursos

Se estiver planejando implantar a definição, prossiga para a seção Próximas etapas, que inclui um link para o artigo com instruções para implantar a definição com o Bicep.

Se tiver terminado a definição do aplicativo gerenciado, você pode excluir os grupos de recursos que criou com os nomes packageStorageGroup e bicepDefinitionGroup.

PowerShell do Azure
CLI do Azure

O comando solicita que você confirme se deseja remover o grupo de recursos.

Remove-AzResourceGroup -Name packageStorageGroup

Remove-AzResourceGroup -Name bicepDefinitionGroup

O comando solicita a confirmação e retorna ao prompt de comando enquanto os recursos estão sendo excluídos.

az group delete --resource-group packageStorageGroup --no-wait

az group delete --resource-group bicepDefinitionGroup --no-wait

Próximas etapas

Você publicou a definição de aplicativo gerenciado. A próxima etapa é aprender a implantar uma instância dessa definição.

Início Rápido: Usar o Bicep para implantar uma definição de Aplicativo Gerenciado do Azure.

Compartilhar via