Přidejte soubory Dockerfile do modelu aplikace .NET

S aplikací Aspire je možné určit Dockerfile, co bude sestaveno, když se AppHost spustí, pomocí buď AddDockerfile nebo WithDockerfile metod rozšíření.

Tyto dvě metody slouží různým účelům:

• AddDockerfile: Vytvoří novou kontejnerovou instanci z existujícího Dockerfile. Tuto možnost použijte, když chcete do modelu aplikace přidat vlastní kontejnerizovanou službu.
• WithDockerfile: Přizpůsobí existující kontejnerový prostředek (například databázi nebo mezipaměť) tak, aby používal jinou Dockerfile. Tuto možnost použijte, pokud chcete upravit výchozí image kontejneru pro komponentu Aspire .

Obě metody předpokládají existenci Dockerfile v určené kontextové cestě—ani jedna metoda pro vás nevytvoří Dockerfile.

Kdy použít AddDockerfile vs WithDockerfile

V závislosti na vašem scénáři zvolte příslušnou metodu:

Použít AddDockerfile, když:

• Do modelu aplikace chcete přidat vlastní kontejnerizovanou službu.
• Máte existující Dockerfile pro vlastní aplikaci nebo službu.
• Potřebujete vytvořit nový zdroj kontejneru, který není poskytován komponentami Aspire.

Použít WithDockerfile, když:

• Chcete přizpůsobit existující Aspire komponentu (například PostgreSQL, Redisatd.).
• Musíte nahradit výchozí obraz kontejneru vlastním obrazem.
• Chcete zachovat silně typovaný tvůrce prostředků a jeho rozšiřující metody.
• Máte specifické požadavky, které výchozí image kontejneru nesplňuje.

Přidejte Dockerfile do modelu aplikace

V následujícím příkladu se metoda rozšíření AddDockerfile používá k určení kontejneru odkazem na kontextovou cestu pro sestavení kontejneru.

var builder = DistributedApplication.CreateBuilder(args);

var container = builder.AddDockerfile(
    "mycontainer", "relative/context/path");

Pokud není argumentem kontextové cesty kořenová cesta, cesta kontextu se interpretuje jako relativní vzhledem k adresáři projektů AppHost (kde se nachází složka AppHost *.csproj ).

Ve výchozím nastavení je název Dockerfile, který se používá, Dockerfile a očekává se, že bude v adresáři kontextové cesty. Název Dockerfile je možné explicitně zadat buď jako absolutní cestu, nebo relativní cestu k kontextové cestě.

To je užitečné, pokud chcete upravit konkrétní Dockerfile použití při místním spuštění nebo při nasazování AppHost.

var builder = DistributedApplication.CreateBuilder(args);

var container = builder.ExecutionContext.IsRunMode
    ? builder.AddDockerfile(
          "mycontainer", "relative/context/path", "Dockerfile.debug")
    : builder.AddDockerfile(
          "mycontainer", "relative/context/path", "Dockerfile.release");

Přizpůsobte existující prostředky kontejneru

Při použití AddDockerfile návratová hodnota je IResourceBuilder<ContainerResource>. Aspire obsahuje mnoho vlastních typů prostředků, které jsou odvozeny z ContainerResource.

Pomocí metody rozšíření je možné vzít existující komponentu WithDockerfile (například Aspire, PostgreSQL nebo Redis) a nahradit její výchozí obraz kontejneru vlastním, sestaveným z vašich vlastních SQL Server. To vám umožní pokračovat v používání silně typovaných typů prostředků a jejich konkrétních rozšiřujících metod při přizpůsobování základního kontejneru.

var builder = DistributedApplication.CreateBuilder(args);

// This replaces the default PostgreSQL container image with a custom one
// built from your Dockerfile, while keeping PostgreSQL-specific functionality
var pgsql = builder.AddPostgres("pgsql")
                   .WithDockerfile("path/to/context")
                   .WithPgAdmin(); // Still works because it's still a PostgreSQL resource

Předání argumentů sestavení

Metodu WithBuildArg lze použít k předání argumentů do sestavení image kontejneru.

var builder = DistributedApplication.CreateBuilder(args);

var container = builder.AddDockerfile("mygoapp", "relative/context/path")
                       .WithBuildArg("GO_VERSION", "1.22");

Parametr hodnoty v metodě WithBuildArg může být doslovná hodnota (boolean, string, int) nebo může vytvořit prostředek pro parametr prostředku. Následující kód nahradí GO_VERSION hodnotou parametru, kterou je možné zadat v době nasazení.

var builder = DistributedApplication.CreateBuilder(args);

var goVersion = builder.AddParameter("goversion");

var container = builder.AddDockerfile("mygoapp", "relative/context/path")
                       .WithBuildArg("GO_VERSION", goVersion);

Argumenty sestavení odpovídají příkazu ARG v Dockerfiles . Rozbalením předchozího příkladu se jedná o vícefázový Dockerfile, který určuje konkrétní verzi image kontejneru, která se má použít jako parametr.

# Stage 1: Build the Go program
ARG GO_VERSION=1.22
FROM golang:${GO_VERSION} AS builder
WORKDIR /build
COPY . .
RUN go build mygoapp.go

# Stage 2: Run the Go program
FROM mcr.microsoft.com/cbl-mariner/base/core:2.0
WORKDIR /app
COPY --from=builder /build/mygoapp .
CMD ["./mygoapp"]

Poznámka

Doporučuje se místo hardcodingování hodnot do obrazu kontejneru používat proměnné prostředí pro hodnoty, které se často mění. Tím se zabrání nutnosti znovu sestavit image kontejneru pokaždé, když je potřeba provést změnu.

Předání tajných kódů sestavení

Kromě argumentů sestavení je možné určit tajné kódy sestavení pomocí WithBuildSecret, které jsou selektivně dostupné jednotlivým příkazům v Dockerfile pomocí syntaxe --mount=type=secret u příkazů RUN.

var builder = DistributedApplication.CreateBuilder(args);

var accessToken = builder.AddParameter("accesstoken", secret: true);

var container = builder.AddDockerfile("myapp", "relative/context/path")
                       .WithBuildSecret("ACCESS_TOKEN", accessToken);

Představte si například příkaz RUN v Dockerfile, který zveřejňuje zadaný tajný kód konkrétnímu příkazu:

# The helloworld command can read the secret from /run/secrets/ACCESS_TOKEN
RUN --mount=type=secret,id=ACCESS_TOKEN helloworld

Opatrnost

Při předávání tajemství v sestavovacích prostředích byste měli postupovat opatrně. To se často provádí při použití tokenu k načtení závislostí z privátních úložišť nebo informačních kanálů před sestavením. Je důležité zajistit, aby vložené tajné kódy nebyly zkopírovány do konečných nebo zprostředkujících imagí.