Tutorial: Compilar e implantar seu aplicativo nos Aplicativos de Contêiner do Azure

Este artigo demonstra como criar e implantar um microsserviço nos Aplicativos de Contêiner do Azure de um repositório de origem usando a sua linguagem de programação preferida.

Este é o primeiro tutorial da série de artigos que o guiam sobre como usar as principais capacidades dentro dos Aplicativos de Contêiner do Azure. A primeira etapa é criar um serviço de API Web de back-end que retorna uma coleção estática de álbuns de música.

Observação

Você também pode compilar e implantar este aplicativo usando o az containerapp up, seguindo as instruções no artigo Início Rápido: Compilar e implantar um aplicativo nos Aplicativos de Contêiner do Azure a partir de um repositório. O comando az containerapp up é uma maneira rápida e conveniente de compilar e implantar seu aplicativo nos Aplicativos de Contêiner do Azure usando um único comando. No entanto, ele não fornece o mesmo nível de personalização para o seu aplicativo de contêiner.

O próximo tutorial da série compilará e implantará o aplicativo Web front-end nos Aplicativos de Contêiner do Azure.

A captura de tela a seguir mostra a saída do álbum da API implantado neste tutorial.

Pré-requisitos

Para concluir este projeto, você precisa dos seguintes itens:

Requisito	Instruções
Conta do Azure	Se você não tiver, crie uma conta gratuita. Você precisa da permissão de Administrador de Acesso do Usuário ou Proprietário na assinatura do Azure para continuar. Use a função mais restritiva para o contexto. Consulte Atribuir funções do Azure usando o portal do Azure e Funções do Azure, funções do Microsoft Entra e funções de administrador de assinatura clássica para obter detalhes.
Conta do GitHub	Inscreva-se gratuitamente.
Git	Instale o git
CLI do Azure	Instale a CLI do Azure.

Requisito	Instruções
Conta do Azure	Se você não tiver, crie uma conta gratuita. Você precisa da permissão de Colaborador ou Proprietário na assinatura do Azure para continuar. Consulte Atribuir funções do Azure usando o portal do Azure para obter detalhes.
Conta do GitHub	Inscreva-se gratuitamente.
Git	Instale o git
CLI do Azure	Instale a CLI do Azure.
Docker Desktop	O Docker fornece instaladores que configuram o ambiente do Docker no macOS, no Windows e no Linux. No prompt de comando, digite docker para garantir que o Docker esteja em execução.

Instalação

Para entrar no Azure usando a CLIl, execute o comando a seguir e siga os prompts para concluir o processo de autenticação.

Bash

az login

PowerShell do Azure

Connect-AzAccount

Para garantir que você esteja executando a versão mais recente da CLI, execute o comando “upgrade”.

Bash

az upgrade

PowerShell do Azure

Install-Module -Name Az -Scope CurrentUser -Repository PSGallery -Force

Ignore quaisquer avisos sobre módulos em uso no momento.

Em seguida, instale ou atualize a extensão dos Aplicativos de Contêiner do Azure para a CLI.

Se você receber erros sobre parâmetros ausentes ao executar comandos az containerapp na CLI do Azure ou cmdlets do módulo Az.App no Azure PowerShell, verifique se está com a versão mais recente da extensão Aplicativos de Contêiner do Azure instalada.

Bash

az extension add --name containerapp --upgrade

Observação

A partir de maio de 2024, as extensões da CLI do Azure já não permitem funcionalidades de versão prévia do recurso por padrão. Para acessar as versões prévias dos recursos dos Aplicativos de Contêiner, instale a extensão Aplicativos de Contêiner com --allow-preview true.

az extension add --name containerapp --upgrade --allow-preview true

PowerShell do Azure

Install-Module -Name Az.App

Atualize o módulo Az.App para a versão mais recente.

Update-Module -Name Az.App

Agora que a extensão ou módulo atual está instalado, registre os namespaces Microsoft.App e Microsoft.OperationalInsights.

Bash

az provider register --namespace Microsoft.App

az provider register --namespace Microsoft.OperationalInsights

PowerShell do Azure

Register-AzResourceProvider -ProviderNamespace Microsoft.App

Register-AzResourceProvider -ProviderNamespace Microsoft.OperationalInsights

Criar variáveis de ambiente

Agora que a configuração da CLI do Azure foi concluída, você pode definir as variáveis de ambiente que são usadas ao longo deste artigo.

Bash

Defina as variáveis a seguir no shell bash.

RESOURCE_GROUP="album-containerapps"
LOCATION="canadacentral"
ENVIRONMENT="env-album-containerapps"
API_NAME="album-api"
FRONTEND_NAME="album-ui"
GITHUB_USERNAME="<YOUR_GITHUB_USERNAME>"

Antes de executar o comando, substitua <YOUR_GITHUB_USERNAME> pelo seu nome de usuário do GitHub.

Em seguida, defina um nome de registro de contêiner exclusivo para você.

ACR_NAME="acaalbums"$GITHUB_USERNAME

PowerShell do Azure

Defina as variáveis a seguir no console do PowerShell.

$ResourceGroup = "album-containerapps"
$Location = "canadacentral"
$Environment = "env-album-containerapps"
$APIName="album-api"
$FrontendName="album-ui"
$GITHUB_USERNAME = "<YOUR_GITHUB_USERNAME>"

Antes de executar o comando, substitua <YOUR_GITHUB_USERNAME> pelo seu nome de usuário do GitHub.

Em seguida, defina um nome de registro de contêiner exclusivo para você.

$ACRName = "acaalbums"+$GITHUB_USERNAME

Preparar o repositório GitHub

Navegue até o repositório para seu idioma preferido e bifurque-o.

C#

Selecione o botão Criar fork na parte superior do repositório da API do álbum para bifurcar o repositório em sua conta.

Agora, você pode clonar o fork do repositório de exemplo.

Use o seguinte comando GIT para clonar seu repositório com fork na pasta code-to-cloud:

git clone https://github.com/$GITHUB_USERNAME/containerapps-albumapi-csharp.git code-to-cloud

Ir

Selecione o botão Criar fork na parte superior do repositório da API do álbum para bifurcar o repositório em sua conta.

Agora, você pode clonar o fork do repositório de exemplo.

Use o seguinte comando GIT para clonar seu repositório com fork na pasta code-to-cloud:

git clone https://github.com/$GITHUB_USERNAME/containerapps-albumapi-go.git code-to-cloud

Java

Selecione o botão Criar fork na parte superior do repositório da API do álbum para bifurcar o repositório em sua conta.

Agora, você pode clonar o fork do repositório de exemplo.

Use o seguinte comando GIT para clonar seu repositório com fork na pasta code-to-cloud:

git clone https://github.com/$GITHUB_USERNAME/containerapps-albumapi-java.git code-to-cloud

Observação

O exemplo em Java dá suporte apenas a um build do Maven, o que resulta em um arquivo JAR executável. O build usa as configurações padrão, pois não há suporte para a passagem de variáveis de ambiente.

JavaScript

Selecione o botão Criar fork na parte superior do repositório da API do álbum para bifurcar o repositório em sua conta.

Agora, você pode clonar o fork do repositório de exemplo.

Use o seguinte comando GIT para clonar seu repositório com fork na pasta code-to-cloud:

git clone https://github.com/$GITHUB_USERNAME/containerapps-albumapi-javascript.git code-to-cloud

Python

Selecione o botão Criar fork na parte superior do repositório da API do álbum para bifurcar o repositório em sua conta.

Agora, você pode clonar o fork do repositório de exemplo.

Use o seguinte comando GIT para clonar seu repositório com fork na pasta code-to-cloud:

git clone https://github.com/$GITHUB_USERNAME/containerapps-albumapi-python.git code-to-cloud

Em seguida, altere o diretório para a raiz do repositório clonado.

cd code-to-cloud/src

Criar um grupo de recursos do Azure

Crie um grupo de recursos para organizar os serviços relacionados à implantação do aplicativo de contêiner.

Bash

az group create \
  --name $RESOURCE_GROUP \
  --location "$LOCATION"

PowerShell do Azure

New-AzResourceGroup -Location $Location -Name $ResourceGroupName

Criar um Registro de Contêiner do Azure

1. Depois que a imagem de contêiner da API do álbum for criada, crie uma instância do ACR (Registro de Contêiner do Azure) em seu grupo de recursos para armazená-la.

   Bash

   az acr create \
       --resource-group $RESOURCE_GROUP \
       --location $LOCATION \
       --name $ACR_NAME \
       --sku Basic
   

   PowerShell do Azure

   $acr = New-AzContainerRegistry `
       -ResourceGroupName $ResourceGroup `
       -Location $Location `
       -Name $ACRName `
       -Sku Basic
   

2. O registro de contêiner deve permitir tokens de audiência do ARM (Azure Resource Manager) para autenticação a fim de usar a identidade gerenciada para efetuar pull de imagens.

   Use o comando a seguir para verificar se os tokens do ARM têm permissão para acessar o ACR (Registro de Contêiner do Azure).

   Bash

   az acr config authentication-as-arm show --registry "$ACR_NAME"
   

   Se os tokens do ARM forem permitidos, o comando produzirá o seguinte.

   {
     "status": "enabled"
   }
   

   Se status for disabled, permita tokens do ARM com o comando a seguir.

   az acr config authentication-as-arm update --registry "$ACR_NAME" --status enabled
   

   PowerShell do Azure

   $acr.AzureAdAuthenticationAsArmPolicyStatus
   

   Se o comando retornar disabled, permita tokens ARM com o comando a seguir.

   Update-AzContainerRegistry `
       -ResourceGroupName $acr.ResourceGroupName `
       -Name $acr.Name `
       -AzureAdAuthenticationAsArmPolicyStatus enabled
   

Criar uma identidade gerenciada atribuída ao usuário

Para evitar o uso de credenciais administrativas, efetue pull de imagens de repositórios privados no Registro de Contêiner do Microsoft Azure usando identidades gerenciadas para autenticação. Quando possível, use uma identidade gerenciada atribuída pelo usuário para efetuar pull de imagens.

Bash

1. Criar uma identidade gerenciada atribuída pelo usuário. Antes de executar os comandos a seguir, escolha um nome para sua identidade gerenciada e substitua o \<PLACEHOLDER\> pelo nome.

   IDENTITY="<YOUR_IDENTITY_NAME>"
   

   az identity create \
       --name $IDENTITY \
       --resource-group $RESOURCE_GROUP
   

2. Obtenha a ID do recurso da identidade.

   IDENTITY_ID=$(az identity show \
       --name $IDENTITY \
       --resource-group $RESOURCE_GROUP \
       --query id \
       --output tsv)
   

PowerShell do Azure

1. Criar uma identidade gerenciada atribuída pelo usuário. Antes de executar os comandos a seguir, escolha um nome para sua identidade gerenciada e substitua o \<PLACEHOLDER\> pelo nome.

   $IdentityName="<YOUR_IDENTITY_NAME>"
   $Identity = New-AzUserAssignedIdentity -ResourceGroupName $ResourceGroup -Name $IdentityName
   

2. Obtenha o recurso da identidade e a ID da entidade de segurança

   $IdentityId = $Identity.Id
   $PrincipalId = (Get-AzUserAssignedIdentity -Name $IdentityName -ResourceGroupName $ResourceGroup).PrincipalId
   

3. Obtenha a ID de recurso do registro. Antes de executar o comando a seguir, substitua os <espaços reservados> pelo nome do grupo de recursos do registro.

   $RegistryId = (Get-AzContainerRegistry -ResourceGroupName $ResourceGroup -Name $ACRName).Id
   

4. Crie a atribuição de função acrpull para a identidade.

   New-AzRoleAssignment -ObjectId $PrincipalId -Scope $RegistryId -RoleDefinitionName acrpull
   

Crie seu aplicativo

Com as tarefas do ACR, você pode compilar e efetuar push da imagem do docker para a API do álbum sem instalar o Docker localmente.

Compilar o contêiner com o ACR

Execute o comando a seguir para iniciar o processo de build e push da imagem usando o ACR. O . ao final do comando representa o contexto de compilação do Docker, o que significa que esse comando deve ser executado na pasta src em que o Dockerfile está.

Bash

az acr build --registry $ACR_NAME --image $API_NAME .

PowerShell do Azure

O comando az acr build não tem um equivalente do PowerShell, mas pode ser executado no PowerShell.

Para entrar no Azure usando a CLI do Azure, execute o comando a seguir e siga os prompts para concluir o processo de autenticação.

az login

Depois, compile o contêiner.

az acr build --registry $AcrName --image $APIName .

A saída do comando az acr build mostra o progresso do upload do código-fonte para o Azure e os detalhes das operações docker build e docker push.

Crie seu aplicativo

As etapas a seguir demonstram como compilar a imagem de contêiner localmente usando o Docker e efetuar push dela para o novo registro de contêiner.

Compilar o contêiner com o Docker

O comando a seguir cria uma imagem de contêiner para a API do álbum e a marca com o nome totalmente qualificado do servidor de logon do ACR. O . ao final do comando representa o contexto de compilação do Docker, o que significa que esse comando deve ser executado na pasta src em que o Dockerfile está.

Bash

docker build --tag $ACR_NAME.azurecr.io/$API_NAME .

PowerShell do Azure

docker build --tag "$ACRName.azurecr.io/$APIName" .

Efetuar push da imagem para o seu registro de contêiner

Primeiro, entre no Registro de Contêiner do Azure.

Bash

az acr login --name $ACR_NAME

PowerShell do Azure

Connect-AzContainerRegistry -Name $ACRName

Agora, envie a imagem por push ao registro.

Bash

docker push $ACR_NAME.azurecr.io/$API_NAME

PowerShell do Azure

docker push "$ACRName.azurecr.io/$APIName"

Criar um ambiente dos Aplicativos de Contêiner

Um ambiente em Aplicativos de Contêiner do Azure age como um limite seguro para um grupo de aplicativos de contêiner.

Crie o ambiente dos Aplicativos de Contêiner usando o comando a seguir.

Bash

az containerapp env create \
  --name $ENVIRONMENT \
  --resource-group $RESOURCE_GROUP \
  --location "$LOCATION"

PowerShell do Azure

Um workspace do Log Analytics é necessário para o ambiente de Aplicativos de Contêiner. Os comandos a seguir criam um workspace do Log Analytics e salvam a ID do workspace e a chave compartilhada primária em variáveis.

$WorkspaceArgs = @{
    Name = 'my-album-workspace'
    ResourceGroupName = $ResourceGroup
    Location = $Location
    PublicNetworkAccessForIngestion = 'Enabled'
    PublicNetworkAccessForQuery = 'Enabled'
}
New-AzOperationalInsightsWorkspace @WorkspaceArgs
$WorkspaceId = (Get-AzOperationalInsightsWorkspace -ResourceGroupName $ResourceGroup -Name $WorkspaceArgs.Name).CustomerId
$WorkspaceSharedKey = (Get-AzOperationalInsightsWorkspaceSharedKey -ResourceGroupName $ResourceGroup -Name $WorkspaceArgs.Name).PrimarySharedKey

Para criar o ambiente, execute o seguinte comando:

$EnvArgs = @{
    EnvName = $Environment
    ResourceGroupName = $ResourceGroup
    Location = $Location
    AppLogConfigurationDestination = 'log-analytics'
    LogAnalyticConfigurationCustomerId = $WorkspaceId
    LogAnalyticConfigurationSharedKey = $WorkspaceSharedKey
}

New-AzContainerAppManagedEnv @EnvArgs

Implantar sua imagem em um aplicativo de contêiner

Agora que tem um ambiente criado, você pode criar e implantar seu aplicativo de contêiner com o comando az containerapp create.

Crie e implante seu aplicativo de contêiner com o comando a seguir.

Bash

az containerapp create \
  --name $API_NAME \
  --resource-group $RESOURCE_GROUP \
  --environment $ENVIRONMENT \
  --image $ACR_NAME.azurecr.io/$API_NAME \
  --target-port 8080 \
  --ingress external \
  --registry-server $ACR_NAME.azurecr.io \
  --user-assigned "$IDENTITY_ID" \
  --registry-identity "$IDENTITY_ID" \
  --query properties.configuration.ingress.fqdn

• Ao definir --ingress como external, seu aplicativo de contêiner está acessível a partir da Internet pública.

• O target-port é definido como 8080 para corresponder à porta na qual o contêiner está ouvindo solicitações.

• Sem uma propriedade query, a chamada para az containerapp create retorna uma resposta JSON que inclui um conjunto avançado de detalhes sobre o aplicativo. A adição de um parâmetro de consulta filtra a saída apenas para o FQDN (nome de domínio totalmente qualificado) do aplicativo.

• Esse comando adiciona a função acrPull à sua identidade gerenciada atribuída pelo usuário, para que ela possa efetuar pull de imagens do registro de contêiner.

PowerShell do Azure

Para criar o aplicativo de contêiner, crie os objetos de modelo para passar como argumentos ao comando New-AzContainerApp.

1. Crie um objeto de modelo para definir os parâmetros da imagem de contêiner.

   $ImageParams = @{
       Name = $APIName
       Image = $ACRName + '.azurecr.io/' + $APIName + ':latest'
   }
   $TemplateObj = New-AzContainerAppTemplateObject @ImageParams
   

2. Crie um objeto de credencial do registro para definir as informações do registro.

   $RegistryArgs = @{
       Server = $ACRName + '.azurecr.io'
       Identity = $IdentityId
   }
   $RegistryObj = New-AzContainerAppRegistryCredentialObject @RegistryArgs
   

3. Obtenha a ID de ambiente.

   $EnvId = (Get-AzContainerAppManagedEnv -EnvName $Environment -ResourceGroup $ResourceGroup).Id
   

4. Crie o aplicativo de contêiner.

   $AppConfig = @{
       IngressTargetPort = 8080
       IngressExternal = $true
       Registry = $RegistryObj
   }
   $AppConfigObj = New-AzContainerAppConfigurationObject @AppConfig
   
   $AppArgs = @{
       Name = $APIName
       Location = $Location
       ResourceGroupName = $ResourceGroup
       ManagedEnvironmentId = $EnvId
       TemplateContainer = $TemplateObj
       Configuration = $AppConfigObj
       UserAssignedIdentity = @($IdentityId)
   }
   $MyApp = New-AzContainerApp @AppArgs
   
   # Show the app's fully qualified domain name (FQDN).
   $MyApp.LatestRevisionFqdn
   

   • Ao definir IngressExternal como $true, seu aplicativo de contêiner está acessível a partir da Internet pública.
   • O parâmetro IngressTargetPort é definido como 8080 para corresponder à porta na qual o contêiner está ouvindo solicitações.

Verificar a implantação

Copie o FQDN para um navegador da Web. No navegador da Web, navegue até o ponto de extremidade /albums do FQDN.

Limpar os recursos

Se não for continuar para o tutorial Comunicação entre microsserviços, você poderá remover os recursos do Azure criados durante este guia de início rápido. Execute o comando a seguir para excluir o grupo de recursos junto com todos os recursos criados neste guia de início rápido.

Bash

az group delete --name $RESOURCE_GROUP

PowerShell do Azure

Remove-AzResourceGroup -Name $ResourceGroup -Force

Dica

Está enfrentando problemas? Deixe-nos saber sobre GitHub abrindo um problema no repositório dos Aplicativos de Contêiner do Azure.

Próximas etapas

Este guia de início rápido é o ponto de entrada para um conjunto de tutoriais progressivos que mostram os vários recursos nos Aplicativos de Contêiner do Azure. Prossiga para aprender como habilitar a comunicação de um front-end da Web que chama a API implantada neste artigo.

Tutorial: comunicação entre microsserviços