Aspire Обзор публикации и развертывания

Aspire отделяет акт создания ресурсов развертывания от выполнения развертывания. Интерфейс Aspire командной строки (aspire) предоставляет две высокоуровневые точки входа:

• aspire publish: создает промежуточные, параметризованные ресурсы для одной или нескольких интеграций хостинга, которые реализуют семантику публикации.
• aspire deploy: выполняет развертывание (когда интеграция реализует семантику развертывания), разрешая параметры и применяя изменения к целевой среде.

Эти команды предоставляют прямой доступ к возможностям публикации и развертывания. Фактическое поведение (что именно создается и как выполняется развертывание) определяется хостинговыми интеграциями, на которые вы ссылаетесь (например, Docker, Kubernetes, Azure). Система расширяема— вы можете создавать собственные интеграции публикации или развертывания, подключающиеся к той же модели.

Команда aspire publish создает артефакты развертывания, содержащие неразрешенные параметры (заполнители). Команда aspire deploy использует эти артефакты, определяет параметры при поддержке целевой интеграции и затем выполняет развертывание. Некоторые интеграции не поддерживают deploy команду.

Aspire Команды CLI (концептуальное поведение)

Если интеграция не реализует функциональность развертывания, aspire deploy не будет развертывать этот целевой компонент (он может выдавать предупреждение или не выполнять никаких операций для него).

При запуске aspire publish без каких-либо интеграций, поддерживающих публикацию, вы увидите:

Step 1: Analyzing model.

       ✗ FAILED: Analyzing the distributed application model for publishing and deployment capabilities. 00:00:00
           No resources in the distributed application model support publishing.

❌ FAILED: Analyzing model. completed with errors

Аналогичным образом при выполнении aspire deploy без каких-либо интеграций, поддерживающих развертывание, вы увидите следующую ошибку:

Step 1: Analyzing model.

       ✗ FAILED: Analyzing the distributed application model for publishing and deployment capabilities. 00:00:00
           No resources in the distributed application model support deployment.

❌ FAILED: Analyzing model. completed with errors

Эти сообщения указывают на то, что необходимо добавить хостинговые интеграции в проект AppHost. Интеграция размещения — это пакеты NuGet (например Aspire.Hosting.Docker, Aspire.Hosting.Kubernetesили Aspire.Hosting.Azure), предоставляющие возможности публикации и развертывания для конкретных целевых платформ.

Заполнители параметров

Опубликованные ресурсы намеренно содержат заполнители вместо конкретных значений. Для Docker выходных данных публикации на основе Compose параметризация отображается как стандартные ссылки на переменные среды. Например, артефакт публикации может включать:

services:
  pg:
    image: "docker.io/library/postgres:17.6"
    environment:
      POSTGRES_HOST_AUTH_METHOD: "scram-sha-256"
      POSTGRES_INITDB_ARGS: "--auth-host=scram-sha-256 --auth-local=scram-sha-256"
      POSTGRES_USER: "postgres"
      POSTGRES_PASSWORD: "${PG_PASSWORD}"
    ports:
      - "8000:5432"
    networks:
      - "aspire"
  dbsetup:
    image: "${DBSETUP_IMAGE}"
    environment:
      OTEL_DOTNET_EXPERIMENTAL_OTLP_EMIT_EXCEPTION_LOG_ATTRIBUTES: "true"
      OTEL_DOTNET_EXPERIMENTAL_OTLP_EMIT_EVENT_LOG_ATTRIBUTES: "true"
      OTEL_DOTNET_EXPERIMENTAL_OTLP_RETRY: "in_memory"
      ASPNETCORE_FORWARDEDHEADERS_ENABLED: "true"
      HTTP_PORTS: "8001"
      ConnectionStrings__db: "Host=pg;Port=5432;Username=postgres;Password=${PG_PASSWORD};Database=db"
    ports:
      - "8002:8001"
      - "8004:8003"
    depends_on:
      pg:
        condition: "service_started"
    networks:
      - "aspire"

Основные моменты:

• ${PG_PASSWORD}, ${DBSETUP_IMAGE} и аналогичные являются заполнителями в опубликованном ресурсе.
• Они не разрешаются в процессе aspire publish.
• Подсистема развертывания (которая может быть aspire deploy, docker compose а также скрипт экспорта переменных, внедрение переменных CI/CD и т. д.) предоставляет их значения позже.
• Благодаря этому секреты и значения, относящиеся к среде, отделены от созданной структуры.

Различные интеграции могут использовать разные соглашения по заполнителям (переменные среды, токены или метаданные параметров), но принцип остается тем же: публикация сохраняет структуру, развертывание добавляет значения.

Модель издателя и вычислительные среды

Aspire использует гибкую модель издателя, которая распределяет поведение публикации по графу приложения. Ресурсы поддерживают публикацию и развертывание с помощью заметок:

• aspire publish
• aspire deploy

Эта конструкция позволяет развертывать гибридные и разнородные развертывания, где различные службы в одном приложении могут развертываться в разных целевых объектах (облако, edge, локальный).

Вычислительные среды

Вычислительная среда — это базовая концепция развертывания, Aspire представляющая целевую платформу, в которой будут развернуты ресурсы приложения. Вычислительные среды определяют, как следует преобразовать ресурсы и какие артефакты развертывания следует создать. Примеры встроенных компьютерных сред включают Azure Container Apps среду и Docker среду Compose.

Вычислительные ресурсы — это выполняемые части приложения, такие как .NET проекты, контейнеры и исполняемые файлы, которые необходимо развернуть в вычислительной среде.

При добавлении вычислительной среды, такой как Docker Compose или Kubernetes, Aspire применяется правильное поведение публикации ко всем совместимым вычислительным ресурсам в модели приложения— дополнительная конфигурация не требуется.

Для нескольких сред необходимо устранение неоднозначности

При добавлении нескольких вычислительных сред необходимо знать, Aspire куда идет ресурс. Вычислительные среды применяют их преобразования ко всем применимым вычислительным ресурсам (проектам, контейнерам, исполняемым файлам). Если более одной среды соответствует заданному ресурсу, Aspire выбрасывает исключение неоднозначной среды во время публикации.

Это можно устранить с помощью WithComputeEnvironment:

var k8s = builder.AddKubernetesEnvironment("k8s-env");
var compose = builder.AddDockerComposeEnvironment("docker-env");

builder.AddProject<Projects.Frontend>("frontend")
    .WithComputeEnvironment(k8s);

builder.AddProject<Projects.Backend>("backend")
    .WithComputeEnvironment(compose);

В этом примере показано, как явно сопоставить службы с разными вычислительными средами. Например, фронтенд в Kubernetes и бэкенд в Docker Compose.

Матрица поддержки интеграции размещения

Типичные рабочие процессы

1. Создание артефактов (любая интеграция)

aspire publish -o artifacts/

Просмотрите содержимое артефактов/ (например, Docker Compose-файлов, Kubernetes манифестов, Azure спецификаций и т. д.).

2. Локальное выполнение (Docker пример)

# Provide or export required environment variables, then:
docker compose -f artifacts/docker-compose.yml up --build

Отсутствующие переменные, такие как PG_PASSWORD, должны быть заданы в оболочке, в файле .env, или введены выбранным исполнителем.

3. Использование aspire deploy

Если интеграция поддерживает развертывание, можно выполнить следующее:

aspire deploy

Это устраняет параметры и применяет изменения развертывания для интеграций, поддерживающих развертывание.

Extensibility

Команды aspire publish и aspire deploy поддерживают расширяемые рабочие процессы через аннотации, которые можно добавлять к ресурсам. Эта функция доступна в предварительной версии и может измениться в будущих выпусках.

Настраиваемые обратные вызовы вывода и развертывания

Ресурсы поддерживают пользовательское поведение публикации и развертывания с помощью аннотаций.

• PublishingCallbackAnnotation: выполняет пользовательскую логику во время aspire publish операций.
• DeployingCallbackAnnotation: выполняет пользовательскую логику во время aspire deploy операций.

В следующем примере показано использование DeployingCallbackAnnotation для регистрации пользовательского поведения развертывания:

#pragma warning disable ASPIREPUBLISHERS001
#pragma warning disable ASPIREINTERACTION001

using Aspire.Hosting.Publishing;
using Microsoft.Extensions.DependencyInjection;

var builder = DistributedApplication.CreateBuilder(args);

// Custom deployment step defined below
builder.AddDataSeedJob("SeedInitialData", seedDataPath: "data/seeds");

builder.Build().Run();

internal class DataSeedJobResource([ResourceName] string name, string seedDataPath)
    : Resource(name)
{
    public string SeedDataPath { get; } = seedDataPath;
}

internal static class DataSeedJobResourceBuilderExtensions
{
    public static IResourceBuilder<DataSeedJobResource> AddDataSeedJob(
        this IDistributedApplicationBuilder builder,
        string name,
        string seedDataPath = "data/seeds")
    {
        var job = new DataSeedJobResource(name, seedDataPath);
        var resourceBuilder = builder.AddResource(job);

        // Attach a DeployingCallbackAnnotation that will be invoked on `aspire deploy`
        job.Annotations.Add(new DeployingCallbackAnnotation(async ctx =>
        {
            CancellationToken ct = ctx.CancellationToken;

            // Prompt the user for a confirmation using the interaction service
            var interactionService = ctx.Services.GetRequiredService<IInteractionService>();

            var envResult = await interactionService.PromptInputAsync(
                "Environment Configuration",
                "Please enter the target environment name:",
                new InteractionInput
                {
                    Label = "Environment Name",
                    InputType = InputType.Text,
                    Required = true,
                    Placeholder = "dev, staging, prod"
                },
                cancellationToken: ct);

            // Custom deployment logic here
            var reporter = ctx.ActivityReporter;
            await using (var deployStep = await reporter.CreateStepAsync(
                $"Deploying data seed job to {envResult.Value}", ct))
            {
                // Simulate deployment work
                await Task.Delay(2000, ct);
                await deployStep.SucceedAsync("Data seed job deployed successfully", ct);
            }
        }));

        return resourceBuilder;
    }
}

Эта настраиваемая логика развертывания легко интегрируется с командой aspire deploy , предоставляя интерактивные запросы и отчеты о ходе выполнения. Дополнительные сведения см. в Aspireзаметках о ресурсах.

Диагностика и аудит

Публикация позволяет получить неизменяемое изображение целевой структуры до появления секретов. Вы можете:

• Показать изменения в опубликованных данных между коммитами.
• Сканирование запрещенных изображений или конфигураций.
• Сохраните запись для соответствия требованиям, а затем отдельно запишите разрешенный набор, примененный во время развертывания.

Дополнительные инструменты

Azure Developer CLI (azd)

Azure Developer CLI (azd) имеет поддержку первого класса для развертывания Aspire проектов. Он может подготавливать инфраструктуру, управлять окружениями и координировать внедрение секретов/значений. Вы можете включить Aspire публикуемые артефакты в azd рабочие процессы или напрямую использовать интеграцию Azure (предварительный просмотр).

Манифест развертывания

Начиная с Aspire версии 9.2, формат манифеста постепенно выводится из использования в пользу поддержки команд и API Aspire для публикации и развертывания. Ранее рабочие процессы сосредотачивались на одном "манифесте развертывания", созданном с использованием специализированных таргетов AppHost. Современный подход сосредоточен на расширяемости интеграции aspire publish. Устаревший формат манифеста не развивается дальше, но его можно создать для проверки или отладки:

aspire publish --publisher manifest -o diagnostics/

Этот:

• Создает моментальный снимок манифеста, полезный для понимания графов ресурсов или устранения неполадок.
• Не следует считать основным контрактом на развертывание.
• Предоставляется исключительно для обратной совместимости и обеспечения видимости для отладки.

Основные выводы

Публикация выполняется сначала, а затем развертывание, которое отделяет структуру от значений. Артефакты, созданные во время публикации, параметризуются, причем разрешение параметров происходит на более позднем этапе процесса. Конкретные интеграции определяют фактическое поведение публикации и развертывания, а система предназначена для расширения, что позволяет создавать пользовательские интеграции, предназначенные для новых платформ или внутренних инструментов. Хотя устаревший манифест по-прежнему может быть создан, он остается неизменным и больше не обновляется.

См. также

• Общие сведения об интеграциях хостинга
• Azure развертывание с помощью приложений-контейнеров
• Aspire Справочник по CLI