Use dependências no nível do sistema operacional por meio de contêineres com Azure Functions Flex Consumption

Importante

Este recurso está em versão preliminar. Os recursos em prévia podem mudar.

Ao usar o suporte a dependências em nível de sistema operacional por meio de contêineres, você pode executar aplicativos de função do Flex Consumption que precisam de mais do que apenas código do aplicativo e pacotes de idioma em seu ambiente de execução. Você fornece uma imagem de contêiner Linux que inclui o aplicativo e suas dependências de idioma e sistema operacional necessários. Azure continua fornecendo o host do Functions, integração de gatilhos, roteamento e escalonamento.

Overview

Você cria uma imagem de contêiner Linux que inclui o código da função, um worker de linguagem do Functions com suporte, dependências de linguagem e do aplicativo, além dos pacotes do sistema, bibliotecas nativas, executáveis, fontes, certificados ou outros arquivos de que seu aplicativo precisa em tempo de execução.

O Azure executa e aplica patches no host do Functions, além de gerenciar o roteamento, a integração com gatilhos e o escalonamento fora da imagem. Essa separação permite personalizar o ambiente do worker, ao mesmo tempo que reduz a superfície da imagem e elimina a necessidade de empacotar, proteger e atualizar o host do Functions por conta própria.

Flex Consumption utiliza um modelo de contêineres apenas para trabalhadores. Sua imagem não é um contêiner web arbitrário. Também não é uma imagem completa do aplicativo de funções, que empacota o host das Funções, o worker da linguagem, o aplicativo e as dependências para uma outra opção de hospedagem.

Para um exemplo completo que empacota uma dependência em nível de SO em uma imagem de contêiner somente worker, consulte o exemplo de contêiner isolado Azure Functions Flex Consumption .NET.

Para um exemplo completo que empacota uma dependência em nível de SO em uma imagem de contêiner somente worker, consulte o exemplo de contêiner Python do Azure Functions Flex Consumption.

Para um exemplo completo que empacota uma dependência em nível de SO em uma imagem de contêiner apenas para o worker, consulte o exemplo de contêiner Azure Functions Flex Consumption Go.

Para um exemplo completo que empacota uma dependência em nível de SO em uma imagem de contêiner somente worker, consulte o exemplo Azure Functions Flex Consumption Node.js container.

Benefits

  • Agrupe o aplicativo, o worker de idioma, as dependências de idioma e as dependências em nível de sistema operacional em uma única imagem versionada.
  • Escolha quando adotar atualizações de worker, runtime de linguagem e dependências reconstruindo, testando e reimplantando a imagem.
  • O host do Functions, a integração de gatilhos, o roteamento e o escalonamento são mantidos gerenciados e corrigidos pelo Azure fora da imagem.
  • Reduza os componentes que você deve incluir, proteger e manter na sua imagem em comparação com uma imagem completa do Function App.

Quando usar esse recurso

Use contêineres para dependências em nível de SO no Flex Consumption quando:

  • Seu aplicativo Flex Consumption requer dependências que você não consegue obter apenas por meio do gerenciador de pacotes da linguagem.
  • Você pode construir, escanear, aplicar patches, testar e publicar uma imagem Linux.
  • Você pode manter a imagem base selecionada e a versão do worker de idioma na imagem.

Comparar opções de hospedagem de contêineres

Escolha o modelo de hospedagem que corresponda à parte do tempo de execução que você precisa controlar.

Capability Imagem do contêiner Flex Consumption Imagem personalizada Elastic Premium ou Dedicated (App Service) Funções no Aplicativos de Contêiner do Azure
Image contract Somente trabalhador Imagem completa do Function App Imagem completa do Function App
Host/runtime do Functions Fornecido, operado e atualizado pelo Azure fora da sua imagem Incluído na sua imagem, normalmente a partir de uma imagem base de Funções Incluído na sua imagem
Sua imagem contém App, worker de um idioma, dependências de idioma/aplicação e pacotes de sistema operacional Funções host, worker, app e dependências Funções host, worker, app e dependências
Scaling Scaling de Flex Consumption gerenciado por funções Escalonamento Premium gerenciado pelo Functions ou escalonamento do plano do App Service Escalonamento de Container Apps
Faturamento Cobrança padrão do Standard Flex Consumption Cobrança do plano Elastic Premium ou App Service Cobrança do Container Apps
Melhor ajuste Adicione dependências em nível de sistema operacional mantendo o contrato da plataforma serverless Flex Controle um contêiner completo de Functions na infraestrutura do App Service Execute contêineres completos de Funções com recursos de Apps de Contêiner

Para mais informações sobre imagens completas do Function App, consulte Suporte a contêineres Linux no Azure Functions.

Arquitetura e limite de responsabilidade

Um evento ou requisição HTTP chega primeiro à plataforma de Funções gerenciadas pelo Azure. Azure executa o host e o runtime do Functions, avalia disparadores, encaminha invocações e determina quando adicionar ou remover instâncias. Quando uma invocação estiver pronta, a plataforma a envia para o worker de linguagem Functions na sua imagem. O worker de linguagem carrega seu aplicativo de funções, e seu aplicativo pode usar as dependências de linguagem, aplicação e nível de sistema operacional incluídas na imagem.

Sua imagem não inclui nem substitui o host de Funções, não implementa roteamento de gatilhos nem controla o escalonamento da plataforma. Você mantém o aplicativo, o worker de idioma, a imagem base e as dependências dentro da imagem. A Microsoft mantém e atualiza os componentes da plataforma Functions fora da imagem.

O worker de linguagem ativo do Functions deve ser um dos workers listados na tabela de suporte da versão prévia. A prévia não dá suporte à substituição por um worker de linguagem arbitrário desenvolvido pelo cliente ou por um manipulador personalizado. A imagem pode incluir outros tempos de execução ou executáveis, como um componente Rust invocado por uma função suportada, como dependências de aplicação. A restrição de um único trabalhador se aplica a trabalhadores ativos da linguagem de Funções, não a runtimes auxiliares ou ferramentas empacotadas com o aplicativo.

Suporte a idiomas em versão prévia

A pré-visualização oferece suporte aos seguintes workers de linguagem do Functions. Selecione seu idioma no topo do artigo para ver versões de runtime suportadas, informações de compatibilidade com trabalhadores e um arquivo Dockerfile de exemplo.

Linguagem das Functions Como o worker é incluído
.NET isolado Incluído através das dependências NuGet e da saída de publicação do aplicativo
Python Adicionado como um artefato de worker da Microsoft específico da versão do Python
Node.js Adicionado como um artefato de worker do Node.js publicado pela Microsoft
Go Incluído através do SDK de worker do Go e compilado no binário da aplicação

Outros workers de linguagem do Functions não são suportados durante a pré-visualização.

Pré-requisitos

Antes de começar, você precisa de:

  • Um aplicativo que utiliza uma linguagem de visualização prévia suportada.
  • Um ambiente de construção de imagem compatível com Docker.
  • Uma imagem Linux ou base de linguagem que você possa manter.
  • O código-fonte do aplicativo e suas dependências de linguagem.
  • Os pacotes de sistema operacional necessários, bibliotecas nativas, fontes, drivers ou ferramentas.
  • Acesso a um registro de contêineres.
  • Permissão para construir, escanear, enviar e implantar imagens.

A prévia suporta imagens Linux amd64.

Entenda o modelo de contêineres Flex Consumption

Sua imagem é responsável por:

  • A carga útil da aplicação.
  • Um worker de linguagem do Functions suportado.
  • Dependências de linguagem e aplicação.
  • Dependências em nível de sistema operacional.
  • A imagem base do Linux ou da linguagem que você seleciona.
  • Segurança de imagem, remediação de vulnerabilidades e versões explícitas de componentes.

O Azure é responsável por:

  • O host das Funções.
  • Integração de roteamento e gatilhos.
  • Escalonamento gerenciado por funções.
  • Componentes de plataforma fora da sua imagem.

O Flex Consumption permite que você escolha a imagem base Linux ou de linguagem que melhor atenda às necessidades da sua aplicação e da organização. Baseie-se nessa imagem adicionando um worker de linguagem Functions suportado, sua aplicação e suas dependências de acordo com esse modelo de contêiner somente de worker. A Microsoft fornece artefatos de trabalho versionados e arquivos Dockerfiles de exemplo para ajudar você a criar uma imagem compatível, enquanto o Azure gerencia o host de Funções fora da sua imagem.

A inicialização do worker é específica da linguagem. Use o Dockerfile de exemplo para seu idioma em vez de copiar um ponto de entrada de outro idioma. A plataforma fornece ao worker os argumentos de conexão RPC e o diretório do aplicativo. Sua imagem inicia o binário de worker de linguagem ou aplicação diretamente; ela não instala nem inicia a configuração de endpoint host ou de plataforma Functions.

Variáveis de ambiente e raiz do script

Você não configura variáveis de ambiente de Funções, host ou conexão de trabalho. A plataforma injeta os valores de identidade do trabalhador, conexão, protocolo e bootstrap que o worker da linguagem precisa para se comunicar com o host de Funções gerenciadas pelo Azure.

Quando seu aplicativo Flex Consumption usa uma imagem de contêiner, configure a configuração do aplicativo AzureWebJobsScriptRoot=/home/site/wwwroot. Sua imagem deve posicionar a aplicação da função nesse caminho. O Azure injeta a configuração no container em tempo de execução, então você não precisa declará-la como uma ENV instrução no Dockerfile. Você pode continuar usando outras configurações de aplicativo exigidas pela sua aplicação.

Não adicione FUNCTIONS_WORKER_RUNTIME nem FUNCTIONS_EXTENSION_VERSION a um aplicativo Flex Consumption que use uma imagem de container. A plataforma gerencia esses detalhes de tempo de execução fora da sua imagem.

Obtenha o worker de linguagem

Use a referência do worker compatível documentada para o seu idioma. Os exemplos Python e Node.js usam referências gerenciadas pela Microsoft aka.ms que apontam para o artefato do worker com suporte mais recente. A ferramenta de implantação deles resolve ou faz hash do artefato atual para que uma atualização do worker altere a entrada de construção da imagem.

Verifique os artefatos do worker baixados usando o checksum SHA-256 publicado. Quando uma referência flutuante de worker avançar, reconstrua, teste, envie e reimplante a imagem antes de adotar o worker atualizado. Para um worker fornecido por meio de uma dependência de aplicação, especifique a versão da dependência no projeto de aplicação.

.NET isolado

A prévia suporta o modelo de worker isolado .NET em .NET 10 e .NET 11. Uma aplicação isolada .NET inclui o worker Functions por meio de suas dependências normais do NuGet e da saída de compilação. O worker não é publicado como um artefato separado para cada versão de runtime .NET suportada. Especifique as versões do Microsoft.Azure.Functions.Worker e do pacote relacionado no projeto, e publique o aplicativo para /home/site/wwwroot.

Use a versão mais recente de Azure.Functions.Sdk como o SDK do projeto. Para projetos existentes, siga as instruções em Migrar para Azure.Functions.Sdk.

Use as seguintes versões mínimas de pacotes:

  • Microsoft.Azure.Functions.Worker versão 2.53.0-preview.1 ou posterior.
  • Microsoft.Azure.Functions.Worker.Extensions.Http.AspNetCoreversão 2.1.2-preview.1 ou posterior, se seu aplicativo usar integração ASP.NET Core.

Importante

Use uma versão .NET suportada. Você é responsável por selecionar e manter uma imagem de runtime .NET suportada e as dependências compatíveis do worker do Functions e do aplicativo.

Para os arquivos completos de aplicativo e implantação, consulte o exemplo de contêiner .NET isolado do Azure Functions Flex Consumption.

Dockerfile de exemplo do .NET isolado

O seguinte Dockerfile de exemplo publica o aplicativo isolado .NET e copia a saída de publicação em uma imagem de runtime .NET 10:

FROM mcr.microsoft.com/dotnet/sdk:10.0-noble AS build

WORKDIR /src
COPY NuGet.config FlexDotnetWorker.csproj ./
RUN dotnet restore FlexDotnetWorker.csproj --runtime linux-x64 -p:PublishReadyToRun=true

COPY *.cs host.json ./

RUN dotnet publish FlexDotnetWorker.csproj --configuration Release --runtime linux-x64 --self-contained false \
    --no-restore -p:PublishReadyToRun=true --output /publish \
    && rm -f /publish/worker.config.json /publish/functions.metadata

FROM mcr.microsoft.com/dotnet/aspnet:10.0-noble

WORKDIR /home/site/wwwroot
COPY --from=build /publish/ ./

USER $APP_UID
ENTRYPOINT ["dotnet", "FlexDotnetWorker.dll"]

Este exemplo tem como alvo .NET 10. Ao selecionar outra versão .NET suportada, atualize ambas as tags de imagem base .NET juntas e valide as versões do pacote de trabalho do aplicativo e das Funções.

Python

A prévia suporta Python 3.13 até Python 3.15. Uma imagem Python contém o aplicativo, dependências de Python, dependências em nível de sistema operacional e um artefato do worker do Python Functions compatível. O artefato worker deve corresponder à versão do runtime Python na imagem.

Importante

Use uma versão Python suportada e seu artefato worker correspondente. Não combine um artefato worker de uma versão Python com uma versão diferente de runtime Python.

Comece com o exemplo de arquivo Dockerfile no Azure Functions Flex Consumption Python container sample.

O aplicativo de exemplo usa azure-functions==2.3.0. O arquivo Dockerfile Python baixa o worker Python suportado atualmente a partir de uma referência gerenciada aka.ms pela Microsoft, verifica o artefato baixado por meio de seu checksum SHA-256 publicado e o extrai para a imagem. Seu ponto de entrada inicia diretamente o worker Python.

Python Dockerfile

Os valores a seguir identificam a imagem base suportada e a referência do worker flutuante para cada versão de Python:

Versão do Python Imagem de base Referência do worker
3.13 python:3.13-slim-bookworm https://aka.ms/azurefunctions/releases/python/3.13/worker/latest/azure-functions-python-worker-py313-linux-x64.tar.gz
3,14 python:3.14-slim-bookworm https://aka.ms/azurefunctions/releases/python/3.14/worker/latest/azure-functions-python-worker-py314-linux-x64.tar.gz
3.15 python:3.15-slim-bookworm https://aka.ms/azurefunctions/releases/python/3.15/worker/latest/azure-functions-python-worker-py315-linux-x64.tar.gz

Este exemplo tem como alvo Python 3.15. Crie um arquivo chamado worker-release-url.txt que contenha a referência do worker do Python 3.15 da tabela anterior. Ao selecionar Python 3.13 ou 3.14, atualize a imagem base, a referência do worker e o nome do arquivo de worker juntos.

FROM python:3.15-slim-bookworm AS build

COPY worker-release-url.txt /tmp/worker-release-url.txt

RUN python -c "from pathlib import Path; from urllib.request import urlretrieve; url = Path('/tmp/worker-release-url.txt').read_text(encoding='utf-8').strip(); latest = 'https://aka.ms/azurefunctions/releases/python/3.15/worker/latest/azure-functions-python-worker-py315-linux-x64.tar.gz'; archive = '/tmp/azure-functions-python-worker-py315-linux-x64.tar.gz'; urlretrieve(latest, archive); urlretrieve(latest + '.sha256', archive + '.sha256'); urlretrieve(url + '.sha256', archive + '.expected.sha256')" \
    && cd /tmp \
    && cmp azure-functions-python-worker-py315-linux-x64.tar.gz.sha256 azure-functions-python-worker-py315-linux-x64.tar.gz.expected.sha256 \
    && sha256sum --check --strict azure-functions-python-worker-py315-linux-x64.tar.gz.sha256 \
    && mkdir -p /opt/functions-worker \
    && tar -xzf azure-functions-python-worker-py315-linux-x64.tar.gz -C /opt/functions-worker \
    && rm azure-functions-python-worker-py315-linux-x64.tar.gz azure-functions-python-worker-py315-linux-x64.tar.gz.sha256 azure-functions-python-worker-py315-linux-x64.tar.gz.expected.sha256

COPY requirements.txt /tmp/requirements.txt
RUN --mount=type=secret,id=pip_config,target=/etc/pip.conf \
    python -m pip install --no-cache-dir --only-binary=:all: \
    --target /home/site/wwwroot/.python_packages/lib/site-packages \
    -r /tmp/requirements.txt

FROM python:3.15-slim-bookworm

RUN groupadd --gid 10001 app \
    && useradd --uid 10001 --gid 10001 --create-home --shell /usr/sbin/nologin app

WORKDIR /home/site/wwwroot
COPY --from=build /opt/functions-worker/ /opt/functions-worker/
COPY --from=build /tmp/worker-release-url.txt /opt/functions-worker-release-url.txt
COPY --from=build /home/site/wwwroot/.python_packages/ ./.python_packages/
COPY function_app.py host.json ./

USER 10001:10001
ENTRYPOINT ["python", "/opt/functions-worker/worker.py"]

O Exemplo do Azure resolve a referência flutuante do worker para sua URL da release versionada no GitHub antes de preparar o contexto da imagem. O Dockerfile exige que a soma de verificação daquela versão selecionada corresponda à soma de verificação atualmente publicada através de aka.ms, e então verifica o arquivo. Se as referências discordarem, a compilação falha.

A partir do diretório que contém o arquivo Dockerfile e os arquivos do aplicativo, construa e envie a imagem. Este exemplo usa o Registro de Contêiner do Azure e a identidade atribuída ao sistema:

az acr login --name <ACR_NAME>

docker build --platform linux/amd64 --progress plain \
  -f Dockerfile \
  -t <ACR_NAME>.azurecr.io/<REPOSITORY>:python315 .

docker push <ACR_NAME>.azurecr.io/<REPOSITORY>:python315

az functionapp create -g <RESOURCE_GROUP> -n <APP_NAME> -s <STORAGE_ACCOUNT> \
  --flexconsumption-location <REGION> \
  --deployment-image <ACR_NAME>.azurecr.io/<REPOSITORY>:python315 \
  --deployment-image-auth-type SystemAssignedIdentity \
  --assign-identity [system] --role AcrPull --scope <ACR_RESOURCE_ID>

az functionapp deployment config show -g <RESOURCE_GROUP> -n <APP_NAME>

Go

A prévia suporta o Go 1.27. Uma imagem Go contém o aplicativo, dependências em nível de SO e o worker e o SDK de Go Functions suportados compilados no binário da aplicação. O worker não é publicado como um artefato separado para cada versão suportada do Go.

Importante

Use uma versão do Go suportada. Você é responsável por compilar o aplicativo com uma cadeia de ferramentas Go suportada e uma versão compatível do SDK worker do Go Functions.

Comece com o exemplo Dockerfile no exemplo de contêiner Azure Functions Flex Consumption Go.

O arquivo de exemplo go.mod especifica github.com/azure/azure-functions-golang-worker a versão v1.0.2. O Go Dockerfile usa uma compilação em múltiplas etapas e inicia o binário compilado da aplicação diretamente.

Dockerfile do Go

FROM golang:1.27-bookworm AS build
WORKDIR /src

COPY go.mod go.sum ./
RUN go mod download

COPY *.go ./
RUN CGO_ENABLED=0 GOOS=linux GOARCH=amd64 \
    go build -mod=readonly -trimpath -ldflags="-s -w" -o /out/app .

FROM ubuntu:24.04

WORKDIR /home/site/wwwroot
COPY --from=build /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/ca-certificates.crt
COPY --from=build --chmod=0555 /out/app ./app
COPY host.json ./

USER 10001:10001
ENTRYPOINT ["/home/site/wwwroot/app"]

A partir do diretório que contém o arquivo Dockerfile e os arquivos do aplicativo, construa e envie a imagem. Este exemplo usa o Registro de Contêiner do Azure e a identidade atribuída ao sistema:

az acr login --name <ACR_NAME>

docker build --platform linux/amd64 --progress plain \
  -f go.Dockerfile \
  -t <ACR_NAME>.azurecr.io/<REPOSITORY>:go127 .

docker push <ACR_NAME>.azurecr.io/<REPOSITORY>:go127

az functionapp create -g <RESOURCE_GROUP> -n <APP_NAME> -s <STORAGE_ACCOUNT> \
  --flexconsumption-location <REGION> \
  --deployment-image <ACR_NAME>.azurecr.io/<REPOSITORY>:go127 \
  --deployment-image-auth-type SystemAssignedIdentity \
  --assign-identity [system] --role AcrPull --scope <ACR_RESOURCE_ID>

az functionapp deployment config show -g <RESOURCE_GROUP> -n <APP_NAME>

Node.js

A prévia suporta Node.js 24. Uma imagem Node.js contém o aplicativo, dependências do Node.js, dependências em nível de SO e um artefato do worker do Functions do Node.js compatível. O worker não é publicado como um artefato separado para cada versão de Node.js em tempo de execução suportada.

Importante

Use uma versão Node.js suportada. Você é responsável por selecionar e manter uma imagem base do Node.js compatível e dependências compatíveis do worker do Functions e do aplicativo.

Comece com o arquivo Dockerfile de exemplo em JavaScript ou TypeScript no sample de contêiner do Azure Functions Flex Consumption Node.js.

O aplicativo de exemplo usa a versão @azure/functions4.17.0. O arquivo DockerfileNode.js baixa o worker Node.js atualmente suportado a partir de uma referência gerenciada aka.ms pela Microsoft e o extrai para a imagem. A ferramenta de implantação de exemplo calcula o valor SHA-256 do artefato baixado, inclui esse valor no hash do contexto da imagem e o encaminha para a compilação da imagem para verificação. O ponto de entrada da imagem inicia o worker do Node.js diretamente.

Node.js Dockerfile

Os seguintes arquivos Dockerfiles usam o layout dos projetos de exemplo JavaScript e TypeScript. Atualize os COPY comandos e etapas de compilação para corresponder à estrutura de diretórios e à saída da compilação da sua aplicação. Para TypeScript, o exemplo compila o aplicativo e copia o JavaScript gerado a partir de dist. O diretório dist é uma convenção de exemplo, não um requisito do modelo de contêineres Flex Consumption. Certifique-se de que o campo main em package.json identifique os arquivos JavaScript gerados.

FROM node:24-bookworm-slim AS worker

ARG FUNCTIONS_NODE_WORKER_SHA256

ADD --checksum=sha256:${FUNCTIONS_NODE_WORKER_SHA256} \
    https://aka.ms/azurefunctions/releases/node/worker/latest/worker.tar.gz \
    /tmp/worker.tar.gz

RUN mkdir -p /opt/functions-worker \
    && tar -xzf /tmp/worker.tar.gz -C /opt/functions-worker \
    && rm /tmp/worker.tar.gz

FROM node:24-bookworm-slim AS dependencies
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci --omit=dev --ignore-scripts --no-audit --no-fund

FROM node:24-bookworm-slim
WORKDIR /home/site/wwwroot
COPY --from=worker /opt/functions-worker/ /opt/functions-worker/
COPY --from=dependencies /app/node_modules/ ./node_modules/
COPY package.json host.json ./
COPY src/ ./src/

USER node
ENTRYPOINT ["node", "/opt/functions-worker/dist/src/nodejsWorker.js"]

A partir do diretório que contém o arquivo Dockerfile e os arquivos do aplicativo, construa e envie a imagem. Este exemplo usa o Registro de Contêiner do Azure e a identidade atribuída ao sistema:

(
  set -e

  az acr login --name <ACR_NAME>

  WORKER_URL=https://aka.ms/azurefunctions/releases/node/worker/latest/worker.tar.gz
  WORKER_FILE=azure-functions-nodejs-worker.tar.gz
  WORKER_DIR=$(mktemp -d)

  trap 'rm -f -- "$WORKER_DIR/$WORKER_FILE" "$WORKER_DIR/$WORKER_FILE.sha256"; rmdir -- "$WORKER_DIR"' EXIT

  curl --fail --location "$WORKER_URL" \
    --output "$WORKER_DIR/$WORKER_FILE"
  curl --fail --location "${WORKER_URL}.sha256" \
    --output "$WORKER_DIR/$WORKER_FILE.sha256"

  (
    cd "$WORKER_DIR"
    sha256sum --check --strict "$WORKER_FILE.sha256"
  )

  FUNCTIONS_NODE_WORKER_SHA256=$(
    sha256sum "$WORKER_DIR/$WORKER_FILE" | cut -d ' ' -f 1
  )

  docker build --platform linux/amd64 --progress plain \
    -f node24.Dockerfile \
    --build-arg FUNCTIONS_NODE_WORKER_SHA256="$FUNCTIONS_NODE_WORKER_SHA256" \
    -t <ACR_NAME>.azurecr.io/<REPOSITORY>:node24 .

  docker push <ACR_NAME>.azurecr.io/<REPOSITORY>:node24

  az functionapp create -g <RESOURCE_GROUP> -n <APP_NAME> -s <STORAGE_ACCOUNT> \
    --flexconsumption-location <REGION> \
    --deployment-image <ACR_NAME>.azurecr.io/<REPOSITORY>:node24 \
    --deployment-image-auth-type SystemAssignedIdentity \
    --assign-identity [system] --role AcrPull --scope <ACR_RESOURCE_ID>

  az functionapp deployment config show -g <RESOURCE_GROUP> -n <APP_NAME>
)

Criar a imagem

Use o exemplo de Dockerfile para o seu idioma compatível como ponto de partida:

Comece a partir do Dockerfile de exemplo do Node.js.

O arquivo Dockerfile de exemplo monta uma imagem de contêiner; não é uma imagem base fornecida pela Microsoft.

  1. Selecione uma imagem Linux ou base de idioma suportada de uma fonte em que sua organização confie.
  2. Selecione uma tag de versão de imagem base explícita ou um digest imutável de acordo com sua política de cadeia de suprimentos. Evite tags flutuantes como latest.
  3. Instale os pacotes de SO necessários e remova os dados temporários do gerenciador de pacotes.
  4. Restaurar ou instalar dependências de idioma e aplicação.
  5. Adicione o payload da aplicação e o worker de linguagem Functions suportado.
  6. Configure o ponto de entrada específico do idioma de acordo com o arquivo Dockerfile de exemplo para o seu idioma. Não incorpore a configuração do endpoint da plataforma na imagem.
  7. Construa e escaneie a imagem.
  8. Confirme que a imagem tem como alvo Linux amd64 e que os arquivos necessários e as permissões executáveis estão presentes.
  9. Atribua uma tag de versão ou um digest. Ambas as formas de referência são suportadas, mas um digest é preferido para implantação determinística e reversão.

A pré-visualização atualmente não oferece uma experiência de desenvolvedor suportada para executar ou testar localmente a imagem do container.

Desenvolvimento e teste locais

Desenvolva seu código de função normalmente. Use as ferramentas de teste da sua linguagem e execute func start para validar localmente a aplicação-fonte.

Após a validação em nível de origem, construa a imagem do contêiner usando o contrato de imagem publicado e o arquivo Dockerfile de exemplo para sua linguagem. Você pode confirmar que a compilação foi bem-sucedida e inspecionar a arquitetura da imagem, os arquivos e as permissões. A pré-visualização atualmente não oferece uma experiência de desenvolvedor suportada para executar ou testar localmente a imagem do container.

Envie a imagem, configure o aplicativo da função Flex Consumption usando o CLI do Azure e valide a carga de trabalho continerizada no Azure.

Enviar a imagem para um registro

Depois de concluir os testes no nível do código-fonte, o build da imagem e as verificações de segurança:

  1. Marque a imagem para o registro e repositório escolhidos.
  2. Autentice-se no registro.
  3. Publicar uma versão de imagem imutável.
  4. Registre a tag resultante e diga o conteúdo.
  5. Confirme que a identidade ou credencial usada pelo aplicativo Flex Consumption pode puxar a imagem.

Suporte ao Registro

Publique a imagem no registro de contêineres escolhido.

A configuração de imagem do contêiner suporta acesso anônimo, autenticação básica, identidade atribuída pelo sistema e identidade atribuída pelo usuário. Use o acesso anônimo para uma imagem pública. Autenticação básica faz referência a nomes de configuração de aplicativo que contêm as credenciais do registro; não coloque valores de credenciais diretamente na configuração da imagem do contêiner. A autenticação de identidade gerenciada atribuída ao sistema e ao usuário aplica-se ao Registro de Contêiner do Azure.

Usar containers no Flex Consumption não introduz restrições adicionais de rede. Os requisitos existentes de rede de Flex Consumption se aplicam. O registro configurado deve ser acessível e resolvível por DNS a partir do caminho de rede do aplicativo.

Use identidade gerenciada e referências do Key Vault

Um aplicativo Flex Consumption que usa uma imagem de contêiner suporta o mesmo comportamento de identidade gerenciada em nível de aplicativo que um aplicativo Flex com pacote de código. Você pode atribuir uma identidade atribuída pelo sistema ou pelo usuário ao aplicativo de funções, e o host de Funções gerenciadas pelo Azure e as extensões suportadas podem usar essa identidade normalmente. Seu código de aplicativo também pode usar a identidade atribuída por meio da biblioteca de identidade Azure apropriada.

As configurações do aplicativo podem usar referências do Key Vault da mesma forma que outros aplicativos do Flex Consumption. Você configura a identidade usada para resolver uma referência ao Key Vault independentemente do método de autenticação usado para puxar a imagem do container. Por exemplo, você pode usar uma identidade atribuída pelo usuário para a pull do registro e outra identidade para acesso de aplicativos aos recursos do Azure.

Configure um aplicativo da função Flex Consumption para usar uma imagem de contêiner

Você pode criar um novo aplicativo da função Flex Consumption com a implantação do Registro ou alterar um aplicativo existente elegível de BlobContainer implantação para Registry implantação.

O Microsoft.Web/sites recurso usa o tipo de armazenamento de implantação para identificar o modelo de implantação:

  • Um aplicativo de pacote de código usa properties.functionAppConfig.deployment.storage.type definido como BlobContainer.
  • Uma implantação de imagem de contêiner usa properties.functionAppConfig.deployment.storage.type definido como Registry.

Para implantação no Registry:

  • Defina deployment.storage.value para a referência completa da imagem. Preserve exatamente o valor.
  • Definir deployment.storage.authentication para um tipo de autenticação compatível.
  • Omita functionAppConfig.runtime.

Escolha uma referência de imagem

A propriedade properties.functionAppConfig.deployment.storage.value deve conter um nome de host de registro totalmente qualificado e uma tag, digest explícito ou ambos:

  • Digest (recomendado):myregistry.example.com/app/worker@sha256:<digest>
  • Tag:myregistry.example.com/app/worker:v1
  • Tag e digest:myregistry.example.com/app/worker:v1@sha256:<digest>

Quando uma referência de imagem contém tanto uma tag quanto um digest, a plataforma puxa a imagem identificada pelo digest. A etiqueta é descritiva.

Uma referência de imagem sem uma tag ou digest explícito não é suportada. Para usar a latest tag, especifique-a explicitamente como myregistry.example.com/app/worker:latest. A API também rejeita a forma abreviada do registro que omite o nome de host totalmente qualificado do registro.

Para uma referência apenas de tag, a plataforma resolve a tag sempre que cria uma instância de worker. Se o conteúdo da tag mudar sem uma alteração correspondente em deployment.storage.value, diferentes versões da imagem poderão ser executadas ao mesmo tempo. Para mais informações, consulte Evitar atualizar uma tag mutável existente.

Configure o recurso

O seguinte fragmento de Bicep mostra a properties forma:

properties: {
  functionAppConfig: {
    deployment: {
      storage: {
        type: 'Registry'
        value: '<qualified-image-reference>'
        authentication: {
          type: 'SystemAssignedIdentity'
        }
      }
    }
  }
}

Ao atualizar, preserve os valores existentes scaleAndConcurrency e siteUpdateStrategy, a menos que pretenda alterá-los.

Use uma destas formas de autenticação:

Tipo de autenticação Campos adicionais Usage
Anonymous None Baixe de um repositório que permite acesso anônimo.
SystemAssignedIdentity None Use a identidade atribuída pelo sistema do aplicativo.
UserAssignedIdentity userAssignedIdentityResourceId Use a identidade atribuída pelo usuário especificada.
Basic usernameSettingName, passwordSettingName Use as configurações do aplicativo que contêm as credenciais do registro. Nunca coloque valores de credenciais diretamente.

Quando você lê ou atualiza o recurso:

  1. Compare deployment.storage.type sem diferenciar maiúsculas de minúsculas antes de ler runtime.name ou runtime.version. Aplicativos que utilizam a implantação via Registro omitem runtime.
  2. Mantenha scaleAndConcurrency, siteUpdateStrategy, os nomes das configurações de autenticação e os campos functionAppConfig não reconhecidos, a menos que você pretenda alterá-los.
  3. Mantenha a referência da imagem exatamente como fornecida.

CLI do Azure

A versão prévia inclui suporte para CLI do Azure. Use CLI do Azure para criar um aplicativo de função Flex Consumption com uma imagem de contêiner ou atualizar um aplicativo existente elegível.

As opções de imagem se aplicam a estes comandos:

  • az functionapp create
  • az functionapp deployment config set
  • az functionapp deployment config show
  • az functionapp show
Argument Alias Purpose
--deployment-image None Referência de imagem qualificada. O valor é enviado inalterado.
--deployment-image-auth-type --diat Anonymous, SystemAssignedIdentity, UserAssignedIdentity ou Basic.
--deployment-image-identity --dii ID de recurso de identidade atribuído pelo usuário.
--deployment-image-username-setting --dius Nome da configuração do aplicativo que contém o nome de usuário do registro.
--deployment-image-password-setting --dips Nome da configuração do aplicativo que contém a senha do registry.

Crie um aplicativo de função com uma imagem de contêiner

Crie um aplicativo de funções Flex Consumption que use sua identidade atribuída pelo sistema para obter a imagem do Registro de Contêiner do Azure:

az functionapp create -g <RESOURCE_GROUP> -n <APP_NAME> -s <STORAGE_ACCOUNT> \
  --flexconsumption-location <REGION> \
  --deployment-image <REGISTRY>/<REPOSITORY>@sha256:<DIGEST> \
  --deployment-image-auth-type SystemAssignedIdentity \
  --assign-identity [system] --role AcrPull --scope <ACR_RESOURCE_ID>

Atualize um aplicativo de funções existente para usar uma imagem de contêiner

Altere um aplicativo de funções elegível do Flex Consumption de BlobContainer para Registry com uma identidade atribuída pelo usuário:

az functionapp deployment config set -g <RESOURCE_GROUP> -n <APP_NAME> \
  --deployment-image <REGISTRY>/<REPOSITORY>:<TAG> \
  --deployment-image-auth-type UserAssignedIdentity \
  --deployment-image-identity <IDENTITY_RESOURCE_ID>

Altere um aplicativo existente que usa a implantação via registro para autenticação básica referenciando as configurações de credenciais do aplicativo:

az functionapp deployment config set -g <RESOURCE_GROUP> -n <APP_NAME> \
  --deployment-image-auth-type Basic \
  --deployment-image-username-setting REGISTRY_USERNAME \
  --deployment-image-password-setting REGISTRY_PASSWORD

A interface de linha de comando (CLI) envia a referência da imagem inalterada para a validação do serviço. A autenticação básica aceita os nomes de configuração, não os valores das credenciais. Configure as atribuições de identidade e de função do registro separadamente usando opções como --assign-identity, --role e --scope.

As opções de tempo de execução não se aplicam a aplicativos que usam implantação por registro. Os comandos show retornam os nomes da configuração do registry e das configurações de autenticação, mas nunca credenciais de registry.

Verificar implantação e primeira invocação

Após a implantação, valide a imagem do container e a integração da plataforma no Azure:

  1. Confirme que o aplicativo faz referência à tag de imagem ou ao digest pretendidos.
  2. Confirme que a plataforma pode se autenticar no registro e extrair a imagem.
  3. Confirme que o processo de trabalhador inicia e fica pronto.
  4. Confirme que as funções e gatilhos esperados foram descobertos.
  5. Invocar uma função representativa.
  6. Verifique se a dependência necessária no nível do sistema operacional está sendo utilizada.
  7. Revise a telemetria do aplicativo em busca de falhas de inicialização e invocação.

Gatilhos HTTP e não-HTTP

Durante a visualização, um aplicativo de função Flex Consumption que usa uma imagem de contêiner suporta os mesmos gatilhos HTTP e não-HTTP que um aplicativo Flex Consumption com pacote de código, exceto Durable Functions e a extensão Barramento de Serviço do Azure.

Atualizar e reverter uma imagem

Use um digest imutável para implantações e reversões previsíveis. Se você usar tags, atribua uma nova tag a cada versão da imagem em vez de sobrescrever uma tag que já está em uso.

Para atualizar o código do aplicativo, o worker de funções, o runtime da linguagem, o sistema operacional base, os pacotes do sistema operacional ou as dependências do aplicativo:

  1. Atualize as versões explícitas dos componentes na fonte da imagem.
  2. Reconstrua a imagem.
  3. Execute testes em nível de fonte, construção de imagem e verificações de segurança.
  4. Envie a nova imagem e registre seu digest ou atribua uma nova tag a ela.
  5. Atualize o aplicativo da função Flex Consumption para referenciar a nova imagem.
  6. Verifique inicialização, descoberta de gatilhos e invocações representativas.

A Microsoft não corrige silenciosamente uma imagem que você já gerou. Monitore as fontes a montante para sua imagem base e dependências, e reconstrua quando forem necessárias atualizações.

Comportamento de implantação, drenagem e reversão da plataforma

Quando você atualiza o aplicativo de função para referenciar um digest ou tag de imagem diferente, a atualização começa a se propagar e aciona as seguintes ações:

  • Novas instâncias de trabalho usam a imagem atualizada.
  • A plataforma identifica os gatilhos na imagem atualizada e atualiza os gatilhos registrados no aplicativo.
  • Instâncias existentes param de aceitar novas invocações e começam a drenar sem esperar que a imagem atualizada inicie ou conclua a descoberta de gatilhos.
  • A plataforma permite que solicitações HTTP e execuções de funções não-HTTP que já estejam em execução sejam concluídas, até o período de carência da terminação da plataforma.

Essas ações ocorrem em paralelo. A descoberta de gatilhos não precisa terminar antes que as instâncias existentes comecem a drenar.

Importante

Uma atualização de imagem não possui uma verificação de integridade pré-implantação nem uma reversão automática. Se a imagem atualizada não puder ser baixada, não iniciar ou não conseguir concluir a descoberta do gatilho, as instâncias anteriores continuam sendo encerradas gradualmente. Gatilhos HTTP e não-HTTP podem falhar até que você configure uma imagem válida.

Se o aplicativo de função for parado quando você atualiza sua referência de imagem, a plataforma remove quaisquer instâncias existentes e registra a nova referência. Quando você inicia o aplicativo, a plataforma usa a imagem atualizada e identifica seus gatilhos.

Evite atualizar uma tag mutável existente

Enviar uma nova imagem sob a mesma tag mutável não inicia um rollout porque a referência de imagem configurada no app de funções não mudou. As instâncias existentes continuam a usar a imagem anterior. Instâncias criadas durante um escalamento posterior podem resolver a tag para a nova imagem, o que pode fazer com que diferentes versões de imagem sejam executadas ao mesmo tempo.

Reiniciar o aplicativo de funções drena as instâncias existentes para que as instâncias recém-criadas resolvam a tag atualizada. No entanto, um reinício não reexecuta a descoberta de gatilhos. Se a imagem atualizada adicionar ou alterar funções ou gatilhos, atualize o aplicativo de funções para referenciar um novo resumo ou tag.

Para um comportamento previsível de implantação, atualize o aplicativo de função para um novo digest imutável a cada versão.

Reverter uma imagem

A plataforma não reverte automaticamente uma atualização de imagem que não tenha sucesso. Mantenha o digest de cada imagem previamente validada.

Para reverter o processo, atualize o aplicativo de funções para referenciar o digest ou tag funcional anterior. Essa atualização inicia a descoberta de gatilhos e provisiona novas instâncias de worker a partir da imagem restaurada.

Registro em log e telemetria

As recomendações de comportamento e registro do Application Insights para aplicativos Flex Consumption que usam uma imagem de contêiner são os mesmos que para o Flex Consumption padrão e outras opções de hospedagem do Azure Functions.

Para logs e rastreamentos de aplicações, instrumente seu aplicativo de funções com OpenTelemetry e envie telemetria diretamente para o Application Insights. A instrumentação direta é recomendada em vez de depender do host do Functions para encaminhar a telemetria do aplicativo, especialmente conforme o app escala. Para orientações de configuração, consulte Use OpenTelemetry with Azure Functions.

Para logs e rastreamentos de aplicações, instrumente seu aplicativo de função Go com OpenTelemetry. O middleware worker Go exporta telemetria usando configurações do OpenTelemetry Protocol (OTLP). Envie a telemetria para um OpenTelemetry Collector ou outro pipeline de telemetria que a encaminhe para o Azure Monitor. Uma cadeia de conexão do Application Insights sozinha não é suficiente para a telemetria do trabalhador do Go. Para orientações de configuração, consulte Use OpenTelemetry with Azure Functions.

A plataforma gerenciada pelo Azure continua encaminhando erros de inicialização de trabalhadores e indexação de funções para o Application Insights. Use estes erros para investigar falhas que ocorrem antes que uma invocação de função chegue ao código do seu aplicativo.

A experiência de métricas do Azure Monitor no portal Azure não é suportada na prévia. Use logs e rastreamentos do Application Insights para monitorar e solucionar problemas no aplicativo.

Monitorar e solucionar problemas

Solucione o problema da implantação em ordem de ciclo de vida:

  1. Configuração: Confirme que o aplicativo referencia a imagem pretendida e as configurações de autenticação.
  2. Acesso ao registro: Confirme que a identidade ou credenciais configuradas podem acessar a imagem.
  3. Rede e DNS: Confirme que a plataforma pode resolver e alcançar o registro de contêiner.
  4. Resolução e pull da imagem: Confirme que a tag ou digest existe e usa um formato suportado.
  5. Inicialização: Confirme que o processo de worker inicia e estabelece a conexão com a plataforma específica da linguagem.
  6. Prontidão do worker: Confirme que a aplicação fica pronta.
  7. Descoberta e escalonamento de gatilhos: Confirme que as funções e os gatilhos esperados são descobertos e escalados conforme o esperado.
  8. Invocação: Confirme que o worker recebe invocações e pode usar a dependência empacotada.
  9. Atualizar ou reverter: Confirme que o aplicativo referencia a versão da imagem pretendida.

Colete a referência da imagem, o tempo de implantação, a versão do trabalhador, a imagem base, a região, o tipo de gatilho e os identificadores de correlação relevantes antes de entrar em contato com o suporte. Não inclua credenciais de registro.

Responsabilidades de segurança, patches e manutenção

Area Responsabilidade do cliente Responsabilidades da Microsoft
Linux base ou imagem de linguagem Selecione uma versão explícita, escanee, faça patch, reconstrua e valide Requisitos de compatibilidade da plataforma de publicação
worker de linguagem do Functions na imagem Especifique uma versão suportada, inclua-a corretamente, reconstrua, teste e reimplante atualizações Publicar artefatos do worker suportados, informações de lançamento e exemplos
Dependências de sistemas operacionais e aplicações Selecione, configure, licencie, escanee, faça patches e valide Restrições da plataforma de publicação
Código do aplicativo Compilar, testar, verificar, aplicar correções e implantar Operar os componentes da plataforma gerenciados pelo Azure que invocam o worker
Proveniência da imagem e registry Aplique controles na cadeia de suprimentos e restrinja o acesso Dê suporte à autenticação documentada do registro e ao caminho de recuperação de imagens
Host de Funções, roteamento, gatilhos e escalonamento Configure o aplicativo por meio de interfaces suportadas Operar e aplicar patches na plataforma gerenciada pelo Azure

Use acesso ao registro de menor privilégio, versões de imagem imutáveis, escaneamento de vulnerabilidades, práticas de lista de materiais de software e fontes confiáveis de artefatos de acordo com as políticas da sua organização.

Limitações de pré-visualização

  • Durable Functions não é suportado.
  • A extensão Barramento de Serviço do Azure não é suportada.
  • O suporte para zonas de disponibilidade não está disponível.
  • As imagens devem ter como alvo o Linux amd64.
  • O suporte a linguagens em pré-visualização é limitado a .NET isolado, Python, Node.js e Go.
  • A pré-visualização atualmente não oferece uma experiência de desenvolvedor suportada para executar ou testar localmente a imagem do container.
  • A experiência de métricas do Azure Monitor no portal Azure não é suportada. Use logs e Application Insights para monitoramento.

Próximas Etapas