Sdílet prostřednictvím

Orchestrace prostředků v Aspire

V tomto článku se dozvíte, jak dále přizpůsobit chování prostředků napsáním kódu v projektu AppHost. V Aspire je prostředek závislou částí cloud-native aplikace. Mezi typy prostředků patří:

  • .NET Projekt: Vlastní mikroslužba zodpovědná za konkrétní funkce v nativní cloudové aplikaci a často vytvořená samostatným týmem vývojářů.
  • Spustitelný soubor: Pokud potřebujete vytvořit mikroslužby s nástroji, jako jsou Node.js nebo Orleans, běží jako spustitelné prostředky.
  • Kontejner: Kontejnery můžete přidat Docker na základě konkrétních imagí do vašeho Aspire řešení.
  • Prostředky integrace: Integrace často přidávají do aplikace prostředky, jako jsou databáze, mezipaměti a služby zasílání zpráv.
  • Externí služba: Představuje rozhraní API nebo službu třetí strany, na které vaše aplikace závisí, ale nespravuje Aspireji . Použijte ho pro prostředky, jako jsou veřejná rozhraní API nebo koncové body SaaS.

Základní informace o Aspire orchestraci a způsobu správy prostředků najdete Aspire v přehledu orchestrace.

Zásady vytváření názvů prostředků

Prostředky v Aspire musí dodržovat omezení pojmenování nastavená Aspire a technologií, kterou prostředek představuje. Například Aspire prostředek má maximální délku názvu 64 znaků, ale Azure kontejnerová aplikace má maximální délku 32. Při publikování prostředku kontejneru Aspire nesmí název Azure překročit délku 32 znaků.

Aspire Názvy prostředků musí dodržovat tato základní pravidla:

  • Musí mít délku 1 až 64 znaků.
  • Musí začínat písmenem ASCII.
  • Musí obsahovat pouze písmena ASCII, číslice a pomlčky.
  • Nesmí končit spojovníkem.
  • Nesmí obsahovat po sobě jdoucí pomlčky.

Nakonfigurujte explicitní spuštění zdroje

Ve výchozím nastavení se prostředky projektu, spustitelné soubory a kontejnery automaticky spouštějí s vaší distribuovanou aplikací. Prostředek lze nakonfigurovat tak, aby čekal na explicitní spouštěcí instrukci pomocí metody WithExplicitStart. Prostředek nakonfigurovaný s WithExplicitStart se inicializuje pomocí 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();

V předchozím kódu je prostředek "dbmigration" nakonfigurován tak, aby se automaticky nespouštěl společně s distribuovanou aplikací.

Prostředky, které mají explicitně nastavené spuštění, můžete zahájit z řídicího panelu Aspire kliknutím na příkaz Start. Další informace najdete na Aspire řídicím panelu: Zastavení nebo spuštění prostředku.

Čekání na prostředky

V některých případech můžete chtít počkat, až bude prostředek připravený, než začnete s jiným prostředkem. Před spuštěním rozhraní API, které na něm závisí, můžete například chtít počkat, než bude databáze připravená. K vyjádření této závislosti použijte metodu 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);

V předchozím kódu prostředek projektu "apiservice" čeká, až prostředek databáze postgresdb přejde do KnownResourceStates.Running stavu. Ukázkový kód ukazuje AspirePostgreSQL integraci, ale stejný vzor lze použít u jiných prostředků.

Jiné případy mohou vyžadovat čekání na dokončení prostředku, a to buď KnownResourceStates.Exited, nebo KnownResourceStates.Finished, než začne závislý prostředek. Pokud chcete počkat na dokončení zdroje, použijte metodu 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);

V předchozím kódu prostředek projektu "apiservice" čeká, až se prostředek projektu "migration" dokončí, a teprve poté začne. Projektový prostředek "migrace" čeká, až prostředek databáze "postgresdb" přejde do stavu KnownResourceStates.Running. To může být užitečné ve scénářích, kdy chcete spustit migraci databáze před spuštěním služby API, například.

Nucené spuštění prostředku na řídicím panelu

Čekání na prostředek je možné obejít pomocí příkazu Start na řídicím panelu. Když na řídicím panelu vyberete Start na čekající prostředek, dá se pokyn, aby se spustil okamžitě bez čekání na to, aby byl prostředek v pořádku nebo dokončený. To může být užitečné, když chcete okamžitě otestovat prostředek a nechcete čekat, až bude aplikace ve správném stavu.

Rozhraní API pro přidávání a zobrazení zdrojů

Aspire Integrace hostování a integrace klientů se doručují jako balíčky NuGet, ale slouží různým účelům. Přestože integrace klientů poskytují konfiguraci klientské knihovny pro využívání aplikací mimo rozsah AppHost, integrace hostování poskytují rozhraní API pro vyjádření prostředků a závislostí v rámci AppHostu. Další informace najdete v tématu Aspire Přehled integrací: Odpovědnosti za integraci.

Prostředky kontejneru Express

Pokud chcete vyjádřit ContainerResource, přidáte ho do instance IDistributedApplicationBuilder voláním metody 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");

Další informace najdete v tématu podpora GPU v Docker Desktop.

Předchozí kód přidá kontejnerový zdroj s názvem "ollama" s image ollama/ollama. Prostředek kontejneru je nakonfigurován s několika bind mounty, pojmenovaným koncovým bodem HTTP, vstupním bodem, který odkazuje na shell skript Unix, a parametry spuštění kontejneru s metodou WithContainerRuntimeArgs.

Přizpůsobte prostředky kontejneru

Všechny podtřídy ContainerResource je možné přizpůsobit tak, aby splňovaly vaše konkrétní požadavky. Toto může být užitečné při použití hostovací integrace, která reprezentuje prostředek kontejneru, ale vyžaduje úpravy. Pokud máte IResourceBuilder<ContainerResource>, můžete zřetězovat volání na jakékoliv z dostupných rozhraní API pro úpravu zdroje kontejneru. Aspire Prostředky kontejneru obvykle odkazují na připnuté tagy, ale místo toho můžete chtít použít latest tag.

Abychom vám to pomohli, představte si scénář, ve kterém používáte integraci AspireRedis. Pokud integrace Redis spoléhá na značku 7.4 a chcete místo toho použít značku latest, můžete zřetězit volání na rozhraní 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.

Další informace a další dostupná rozhraní API najdete v tématu ContainerResourceBuilderExtensions.

Životní cyklus kontejnerových zdrojů

Při spuštění AppHost se ContainerResource použije k určení image kontejneru, která se má vytvořit a spustit. V zákulisí spustí Aspire kontejner pomocí definovaného obrazu kontejneru delegováním volání na odpovídající kontejnerový runtime podle standardu OCI, buď Docker, nebo Podman. Používají se následující příkazy:

Nejprve se kontejner vytvoří pomocí příkazu docker container create. Kontejner se pak spustí pomocí příkazu docker container start.

Tyto příkazy se používají místo docker run ke správě připojených sítí kontejnerů, svazků a portů. Volání těchto příkazů v tomto pořadí umožňuje, aby již při počátečním spuštění byla přítomna jakákoli IP adresa (konfigurace sítě).

Kromě základních typů prostředků ProjectResource, ContainerResource a ExecutableResource poskytuje Aspire metody pro rozšíření, které umožňují přidat běžné prostředky do modelu vaší aplikace. Další informace najdete v tématu Integrace hostování.

Životnost zdroje kontejneru

Ve výchozím nastavení prostředky kontejneru používají životnost relace jako dobu životnosti kontejneru. To znamená, že při každém spuštění procesu AppHost se kontejner vytvoří a spustí. Když se AppHost zastaví, kontejner se zastaví a odebere. Prostředky kontejneru mohou zvolit trvalý režim, aby se zabránilo zbytečnému restartování a pro využití trvalého stavu kontejneru. Pokud toho chcete dosáhnout, použijte zřetězené volání rozhraní API ContainerResourceBuilderExtensions.WithLifetime a předejte ContainerLifetime.Persistent:

var builder = DistributedApplication.CreateBuilder(args);

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

Předchozí kód přidá kontejnerový zdroj s názvem "ollama" s imagí "ollama/ollama" a perzistentní životností.

Definovat externí zdroje služeb

Externí služby jsou rozhraní API a služby třetích stran, na které vaše aplikace závisí, ale existují mimo vaše Aspire řešení. Tyto služby už běží jinde a Aspire je nespravuje. Chcete-li vyjádřit ExternalServiceResource, přidáte jej do instance IDistributedApplicationBuilder voláním metody 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);

Předchozí kód přidá externí prostředek služby s názvem "nuget", který odkazuje na rozhraní NUGet API. Externí služba je nakonfigurovaná s kontrolou stavu HTTP, která monitoruje její dostupnost. Front-endový projekt pak může odkazovat na tuto externí službu pro zjišťování služeb.

Externí služby podporují několik přístupů konfigurace:

Konfigurace statické adresy URL

Externí službu se statickou adresou URL můžete nakonfigurovat pomocí řetězce nebo identifikátoru 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);

Konfigurace adresy URL založená na parametrech

Ve scénářích, ve kterých se adresa URL externí služby může lišit mezi prostředími nebo je potřeba ji konfigurovat, můžete použít parametry:

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);

Při použití konfigurace založené na parametrech je možné hodnotu adresy URL nastavit prostřednictvím konfigurace, proměnných prostředí nebo tajných kódů uživatele. Během vývoje Aspire se může zobrazit výzva k zadání hodnoty adresy URL. Další informace naleznete v tématu Externí parametry.

Požadavky na adresu URL externí služby

Adresy URL externích služeb musí splňovat konkrétní požadavky:

  • Musí to být absolutní identifikátor URI (včetně schématu, hostitele a volitelného portu).
  • Musí mít absolutní cestu nastavenou na /(žádné další segmenty cesty).
  • Nesmí obsahovat parametry dotazu ani fragmenty.

Platné příklady:

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

Neplatné příklady:

  • https://api.example.com/v1/api (obsahuje cestu)
  • https://api.example.com/?version=1 (obsahuje dotaz)
  • https://api.example.com/#section (obsahuje fragment)

Kontroly stavu externích služeb

Externí služby je možné nakonfigurovat pomocí kontrol stavu HTTP pro monitorování jejich dostupnosti:

var builder = DistributedApplication.CreateBuilder(args);

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

Metoda WithHttpHealthCheck přidá kontrolu stavu, která pravidelně dotazuje externí službu. Můžete zadat:

  • path: Relativní cesta ke koncovému bodu kontroly stavu (volitelné, výchozí hodnota není žádná další cesta).
  • statusCode: Očekávaný stavový kód HTTP (volitelné, výchozí hodnota je 200).

Zjišťování služeb přes externí systémy

Když odkazujete na externí službu z jiného prostředku, Aspire automaticky nakonfiguruje zjišťování služby vložením proměnných prostředí ve standardním formátu:

var builder = DistributedApplication.CreateBuilder(args);

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

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

Tato konfigurace vloží proměnné prostředí jako API_HTTPS=https://api.example.com/ a services__api__https__0=https://api.example.com/ do front-endového projektu, což umožňuje zjišťování služeb prostřednictvím zjednodušených i .NETspecifických mechanismů zjišťování služeb.

Životní cyklus externí služby

Externí služby implementují IResourceWithoutLifetime, což znamená, že nejsou spravovány Aspiresystémem životního cyklu. Očekává se, že budou běžet nezávisle. Během vývoje se na řídicím panelu Aspire zobrazí externí služby se stavem Spuštěno, pokud jsou dostupné, nebo se zobrazí selhání kontroly stavu, pokud nejsou dostupné.

Vztahy zdrojů

Vztahy zdrojů spojují prostředky. Relace jsou informativní a nemají vliv na chování aplikace za běhu. Místo toho se používají při zobrazení podrobností o prostředcích na řídicím panelu. Relace jsou například viditelné v podrobnostech o prostředcích na řídicím panelu a Parent relace ovládají vnoření prostředků na stránce prostředků.

Relace se automaticky vytvářejí pomocí některých rozhraní API modelu aplikace. Například:

  • WithReference přidá vztah k cílovému zdroji s typem Reference.
  • WaitFor přidá vztah k cílovému zdroji s typem WaitFor.
  • Přidání databáze do kontejneru databáze vytvoří relaci z databáze do kontejneru s typem Parent.

Relace lze také explicitně přidat do modelu aplikace pomocí WithRelationship a 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();

Předchozí příklad používá WithParentRelationship ke konfiguraci catalogdb databáze jako nadřazeného projektu migration. Relace Parent je zvláštní, protože řídí vnoření prostředků na stránce zdrojů. V tomto příkladu je migration vnořený pod catalogdb.

Note

Pro vztahy rodiče existuje ověření, které brání prostředku mít více rodičů nebo vytvořit cyklický odkaz. Tyto konfigurace nelze vykreslit v uživatelském rozhraní a model aplikace vyvolá chybu.

Viz také

  • Last updated on