Оркестрация ресурсов в Aspire

Из этой статьи вы узнаете, как настроить поведение ресурсов дальше, написав код в проекте AppHost. В Aspireэтом случае ресурс является зависимой частью облачного приложения. Типы ресурсов включают:

• .NET Проект: пользовательская микрослужба, отвечающая за конкретную функциональность в облачном приложении и часто созданная отдельной командой разработчиков.
• Выполняемый: Если необходимо создать микрослужбы с инструментами, такими как Node.js или Orleans, они выполняются как исполняемые ресурсы.
• Контейнер: Вы можете добавлять Docker контейнеры, основанные на конкретных образах, в ваше Aspire решение.
• Ресурсы интеграции. Интеграция часто добавляет такие ресурсы, как базы данных, кэши и службы обмена сообщениями в приложение.
• Внешняя служба: представляет сторонний API или службу, от которой зависит ваше приложение, но не управляется Aspire. Используйте это для ресурсов, таких как общедоступные API или конечные точки SaaS.

Для изучения основ Aspire оркестрации и управления ресурсами см. обзор оркестрации Aspire.

Соглашения об именовании ресурсов

Ресурсы в Aspire должны следовать ограничениям именования, установленным Aspire, а также технологией, которую представляет ресурс. Например, Aspire ресурс имеет максимальную длину имени 64 символов, но Azure приложение-контейнер имеет максимальную длину 32. При публикации Aspire контейнера Azure имя не должно превышать 32 символов.

Aspire Имена ресурсов должны соответствовать этим основным правилам:

• Должно быть от 1 до 64 символов длиной.
• Должно начинаться с буквы ASCII.
• Должен содержать только буквы ASCII, цифры и дефисы.
• Не должен заканчиваться дефисом.
• Не должно содержать последовательные дефисы.

Настройка явного запуска ресурса

Ресурсы проекта, исполняемого файла и контейнера автоматически запускаются с распределенным приложением по умолчанию. Ресурс можно настроить для ожидания явной инструкции запуска с помощью метода WithExplicitStart. Ресурс, настроенный с WithExplicitStart, инициализируется при помощи KnownResourceStates.NotStarted.

var builder = DistributedApplication.CreateBuilder(args);

var postgres = builder.AddPostgres("postgres");
var postgresdb = postgres.AddDatabase("postgresdb");

builder.AddProject<Projects.AspireApp_DbMigration>("dbmigration")
       .WithReference(postgresdb)
       .WithExplicitStart();

В приведенном выше коде ресурс "dbmigration" настроен так, чтобы не запускаться автоматически вместе с распределенным приложением.

Ресурсы с явным запуском Aspire можно запустить с панели мониторинга, нажав команду "Пуск". Дополнительные сведения см. на Aspire панели мониторинга: остановка или запуск ресурса.

Ожидание ресурсов

В некоторых случаях может потребоваться ждать, пока ресурс будет готов, прежде чем запускать другой ресурс. Например, вам может потребоваться дождаться готовности базы данных перед запуском API, который зависит от него. Чтобы выразить эту зависимость, используйте метод WaitFor:

var builder = DistributedApplication.CreateBuilder(args);

var postgres = builder.AddPostgres("postgres");
var postgresdb = postgres.AddDatabase("postgresdb");

builder.AddProject<Projects.AspireApp_ApiService>("apiservice")
       .WithReference(postgresdb)
       .WaitFor(postgresdb);

В приведенном выше коде ресурс проекта apiservice ожидает, когда ресурс базы данных postgresdb перейдёт в состояние KnownResourceStates.Running. В примере кода показана интеграция AspirePostgreSQL, но к другим ресурсам можно применить тот же шаблон.

В других случаях может потребоваться ожидать завершения ресурса, будь то KnownResourceStates.Exited или KnownResourceStates.Finished, прежде чем зависимый ресурс сможет запуститься. Чтобы ожидать завершения ресурса, используйте метод WaitForCompletion:

var builder = DistributedApplication.CreateBuilder(args);

var postgres = builder.AddPostgres("postgres");
var postgresdb = postgres.AddDatabase("postgresdb");

var migration = builder.AddProject<Projects.AspireApp_Migration>("migration")
                       .WithReference(postgresdb)
                       .WaitFor(postgresdb);

builder.AddProject<Projects.AspireApp_ApiService>("apiservice")
       .WithReference(postgresdb)
       .WaitForCompletion(migration);

В показанном выше коде ресурс проекта "apiservice" ожидает, пока ресурс проекта "миграция" полностью не завершится, прежде чем начать. Ресурс проекта "migration" ожидает, пока ресурс базы данных "postgresdb" войдёт в состояние KnownResourceStates.Running. Это может быть полезно в сценариях, когда необходимо выполнить миграцию базы данных перед запуском службы API, например.

Принудительный запуск ресурсов на панели мониторинга

Ожидание ресурса можно обойти с помощью команды Start на панели управления. При выборе кнопки «Пуск» на панели мониторинга ожидаемому ресурсу даётся команда на немедленный запуск без ожидания его полной готовности или завершения. Это может быть полезно, если вы хотите немедленно протестировать ресурс и не хотите ждать, пока приложение будет находиться в правильном состоянии.

API для добавления и выражения ресурсов

Aspire Хостинг-интеграции и Интеграции клиентов предоставляются как пакеты NuGet, но они служат разным целям. Хотя интеграция клиентов обеспечивает конфигурацию клиентской библиотеки для использования приложений вне области AppHost, интеграция размещения предоставляет API для выражения ресурсов и зависимостей в AppHost. Дополнительные сведения см. в обзореAspire интеграции: обязанности по интеграции.

Ресурсы контейнера Express

Чтобы выразить ContainerResource, добавьте его в экземпляр IDistributedApplicationBuilder, вызвав метод AddContainer.

var builder = DistributedApplication.CreateBuilder(args);

var ollama = builder.AddContainer("ollama", "ollama/ollama")
    .WithBindMount("ollama", "/root/.ollama")
    .WithBindMount("./ollamaconfig", "/usr/config")
    .WithHttpEndpoint(port: 11434, targetPort: 11434, name: "ollama")
    .WithEntrypoint("/usr/config/entrypoint.sh")
    .WithContainerRuntimeArgs("--gpus=all");

var builder = DistributedApplication.CreateBuilder(args);

var ollama = builder.AddContainer("ollama", "ollama/ollama")
    .WithBindMount("ollama", "/root/.ollama")
    .WithBindMount("./ollamaconfig", "/usr/config")
    .WithHttpEndpoint(port: 11434, targetPort: 11434, name: "ollama")
    .WithEntrypoint("/usr/config/entrypoint.sh")
    .WithContainerRuntimeArgs("--device", "nvidia.com/gpu=all");

Предыдущий код добавляет ресурс контейнера с именем "ollama" и изображением ollama/ollama. Ресурс контейнера настраивается с несколькими точками монтирования, с именованной конечной точкой HTTP, точкой входа, которая ссылается на скрипт оболочки Unix, и аргументами запуска контейнера с помощью метода WithContainerRuntimeArgs.

Настройка ресурсов контейнера

Все подклассы ContainerResource можно настроить в соответствии с конкретными требованиями. Это может быть полезно при использовании интеграции хостинга , которая моделирует ресурс контейнера, но требует модификаций. Если у вас есть IResourceBuilder<ContainerResource>, вы можете создавать цепочки вызовов с любым из доступных API и изменять ресурс контейнера. Aspire Ресурсы контейнера обычно указывают на закрепленные теги, но вы можете вместо этого использовать latest тег.

Чтобы иллюстрировать это, представьте сценарий, в котором вы используете интеграцию AspireRedis. Если интеграция Redis использует тег 7.4 и вы хотите использовать тег latest вместо этого, можно создать цепочку вызовов к API WithImageTag:

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddRedis("cache")
                   .WithImageTag("latest");

// Instead of using the "7.4" tag, the "cache" 
// container resource now uses the "latest" tag.

Дополнительные сведения о доступных API см. в ContainerResourceBuilderExtensions.

Жизненный цикл ресурсов контейнера

При запуске ContainerResource AppHost используется для определения образа контейнера для создания и запуска. Под капотом Aspire запускает контейнер, используя определенный образ контейнера, делегируя вызовы совместимой с OCI среде выполнения контейнеров, либо Docker, либо Podman. Используются следующие команды:

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

Срок службы ресурса контейнера

По умолчанию ресурсы контейнеров используют время жизни контейнера сессии. Это означает, что при каждом запуске процесса AppHost контейнер создается и запускается. После остановки AppHost контейнер останавливается и удаляется. Ресурсы контейнеров могут выбрать постоянное время существования, чтобы избежать ненужных перезапусков и сохранить состояние контейнера. Для этого выполните цепочку вызовов API ContainerResourceBuilderExtensions.WithLifetime и передайте ContainerLifetime.Persistent.

var builder = DistributedApplication.CreateBuilder(args);

var ollama = builder.AddContainer("ollama", "ollama/ollama")
    .WithLifetime(ContainerLifetime.Persistent);

Предыдущий код добавляет контейнерный ресурс с именем "ollama", используя образ "ollama/ollama" и обеспечивает его постоянное существование.

Опции внешних сервисов Express

Внешние службы — это сторонние API и службы, от которых зависит ваше приложение, но которые существуют вне вашего Aspire решения. Эти службы уже работают в другом месте и не находятся под управлением Aspire. Чтобы выразить ExternalServiceResource, добавьте его к экземпляру IDistributedApplicationBuilder, вызвав метод AddExternalService:

var builder = DistributedApplication.CreateBuilder(args);

var nuget = builder.AddExternalService("nuget", "https://api.nuget.org/")
    .WithHttpHealthCheck(path: "/v3/index.json");

var frontend = builder.AddProject<Projects.Frontend>("frontend")
    .WithReference(nuget);

Предыдущий код добавляет внешний ресурс службы с именем nuget, указывающий на API NuGet. Внешняя служба настроена с помощью проверки состояния HTTP для мониторинга доступности сервиса. Затем фронтенд-проект может ссылаться на эту внешнюю службу для обнаружения служб.

Внешние службы поддерживают несколько подходов к настройке:

Конфигурация статического URL-адреса

Вы можете настроить внешнюю службу со статическим URL-адресом с помощью строки или URI:

var builder = DistributedApplication.CreateBuilder(args);

// Using a string URL
var nuget = builder.AddExternalService("nuget", "https://api.nuget.org/");

// Using a URI
var uri = new Uri("https://api.example.com/");
var api = builder.AddExternalService("external-api", uri);

Конфигурация URL-адреса на основе параметров

В сценариях, когда URL-адрес внешней службы может отличаться от сред или должен быть настраиваемым, можно использовать параметры:

var builder = DistributedApplication.CreateBuilder(args);

var externalServiceUrl = builder.AddParameter("external-service-url");
var externalService = builder.AddExternalService("external-service", externalServiceUrl);

var frontend = builder.AddProject<Projects.Frontend>("frontend")
    .WithReference(externalService);

При использовании конфигурации на основе параметров значение URL-адреса можно задать с помощью конфигурации, переменных среды или секретов пользователя. Во время разработки Aspire может потребоваться, чтобы вы указали значение URL-адреса. Дополнительные сведения см. в разделе "Внешние параметры".

Требования к URL-адресу внешней службы

URL-адреса внешних служб должны соответствовать определенным требованиям:

• Должен быть абсолютным URI (включая схему, узел и необязательный порт).
• Должен иметь абсолютный путь "/" (без дополнительных сегментов пути).
• Не должен содержать параметры запроса или фрагменты.

Допустимые примеры:

• https://api.example.com/
• http://localhost:8080/
• https://service.example.com:9443/

Недопустимые примеры:

• https://api.example.com/v1/api (содержит путь)
• https://api.example.com/?version=1 (содержит запрос)
• https://api.example.com/#section (содержит фрагмент)

Проверки работоспособности внешних служб

Внешние службы можно настроить с помощью проверок работоспособности HTTP для мониторинга их доступности:

var builder = DistributedApplication.CreateBuilder(args);

var api = builder.AddExternalService("api", "https://api.example.com/")
    .WithHttpHealthCheck(path: "/health", statusCode: 200);

Метод WithHttpHealthCheck добавляет проверку состояния, которая периодически опрашивает внешнюю службу. Можно указать следующее:

• path: относительный путь для конечной точки проверки работоспособности (необязательно, по умолчанию отсутствует дополнительный путь).
• statusCode: ожидаемый код состояния HTTP (необязательно, по умолчанию — 200).

Обнаружение служб с помощью внешних служб

При ссылке на внешние службы из другого ресурса, Aspire автоматически настраивает обнаружение служб, внедряя переменные среды в стандартном формате.

var builder = DistributedApplication.CreateBuilder(args);

var api = builder.AddExternalService("api", "https://api.example.com/");

var frontend = builder.AddProject<Projects.Frontend>("frontend")
    .WithReference(api);

Эта конфигурация внедряет переменные среды, такие как API_HTTPS=https://api.example.com/ и services__api__https__0=https://api.example.com/ в интерфейсный проект, позволяя обнаружение служб с помощью упрощенных и .NETконкретных механизмов обнаружения служб.

Жизненный цикл внешней службы

Внешние службы реализуют IResourceWithoutLifetime, то есть ими не управляет система жизненного цикла Aspire. Ожидается, что они будут работать независимо. Во время разработки внешние службы отображаются на Aspire панели мониторинга с состоянием "Запущено", если они доступны, или показывают ошибки проверки работоспособности, если они недоступны.

Связи ресурсов

Связи ресурсов связывают ресурсы. Связи являются информационными и не влияют на поведение среды выполнения приложения. Вместо этого они используются при отображении сведений о ресурсах на панели мониторинга. Например, связи отображаются в сведениях о ресурсах панели мониторинга , а Parent связи управляют вложенностью ресурсов на странице ресурсов.

Связи автоматически создаются некоторыми API модели приложений. Рассмотрим пример.

• WithReference добавляет связь к целевому ресурсу с типом Reference.
• WaitFor добавляет связь к целевому ресурсу с типом WaitFor.
• Добавление базы данных в контейнер базы данных создает связь из базы данных с контейнером с типом Parent.

Связи также можно явно добавить в модель приложения с помощью WithRelationship и WithParentRelationship.

var builder = DistributedApplication.CreateBuilder(args);

var catalogDb = builder.AddPostgres("postgres")
                       .WithDataVolume()
                       .AddDatabase("catalogdb");

builder.AddProject<Projects.AspireApp_CatalogDbMigration>("migration")
       .WithReference(catalogDb)
       .WithParentRelationship(catalogDb);

builder.Build().Run();

В предыдущем примере используется WithParentRelationship для настройки базы данных catalogdb в качестве родительского проекта migration. Связь Parent является особой, так как она управляет вложением ресурсов на странице ресурса. В этом примере migration находится под catalogdb.

См. также

• Aspire Обзор оркестрации
• События в Aspire