Aggiungere Dockerfile al modello di app .NET

Con Aspire è possibile specificare un Dockerfile da compilare quando AppHost viene avviato utilizzando sia i metodi di estensione AddDockerfile che WithDockerfile.

Questi due metodi servono a scopi diversi:

• AddDockerfile: crea una nuova risorsa contenitore da un oggetto esistente Dockerfile. Usare questa opzione quando si vuole aggiungere un servizio personalizzato in contenitori al modello di app.
• WithDockerfile: personalizza una risorsa contenitore esistente ,ad esempio un database o una cache, per usare un oggetto diverso Dockerfile. Usare questa opzione quando si vuole modificare l'immagine del contenitore predefinita per un Aspire componente.

Entrambi i metodi prevedono un oggetto esistente Dockerfile nel percorso di contesto specificato. Nessuno dei due metodi crea automaticamente un oggetto Dockerfile .

Quando usare AddDockerfile e WithDockerfile

Scegliere il metodo appropriato in base allo scenario:

Usare AddDockerfile quando:

• Si vuole aggiungere un servizio personalizzato in contenitori al modello di app.
• Si dispone di un'istanza esistente Dockerfile per un'applicazione o un servizio personalizzato.
• È necessario creare una nuova risorsa contenitore non fornita dai Aspire componenti.

Usare WithDockerfile quando:

• Si vuole personalizzare un componente esistente Aspire ,ad esempio PostgreSQL, Redise così via.
• È necessario sostituire l'immagine del contenitore predefinita con una personalizzata.
• Si vuole mantenere il generatore di risorse fortemente tipizzato e i relativi metodi di estensione.
• Sono previsti requisiti specifici che l'immagine del contenitore predefinita non soddisfa.

Aggiungere un Dockerfile al modello di app

Nell'esempio seguente viene usato il metodo di estensione AddDockerfile per specificare un contenitore facendo riferimento al percorso di contesto per la compilazione del contenitore.

var builder = DistributedApplication.CreateBuilder(args);

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

A meno che l'argomento del percorso di contesto non sia un percorso rooted, il percorso del contesto viene interpretato come relativo alla directory dei progetti AppHost (dove si trova la cartella AppHost *.csproj ).

Per impostazione predefinita, il nome del Dockerfile usato è Dockerfile e deve trovarsi all'interno della directory del percorso di contesto. È possibile specificare in modo esplicito il nome Dockerfile come percorso assoluto o come percorso relativo al percorso del contesto.

Ciò è utile se si vuole modificare lo specifico Dockerfile usato durante l'esecuzione in locale o quando appHost viene distribuito.

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

Personalizzare le risorse del contenitore esistenti

Quando si usa AddDockerfile il valore restituito è un IResourceBuilder<ContainerResource>. Aspire include molti tipi di risorse personalizzati derivati da ContainerResource.

Usando il WithDockerfile metodo di estensione è possibile accettare un componente esistente Aspire (ad esempio PostgreSQL, Rediso SQL Server) e sostituire l'immagine del contenitore predefinita con una personalizzata creata dal proprio Dockerfile. In questo modo è possibile continuare a usare i tipi di risorse fortemente tipizzati e i metodi di estensione specifici mentre si personalizza il contenitore sottostante.

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

Inserire argomenti di compilazione

Il metodo WithBuildArg può essere usato per passare argomenti alla compilazione dell'immagine del contenitore.

var builder = DistributedApplication.CreateBuilder(args);

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

Il parametro value nel metodo WithBuildArg può essere un valore letterale (boolean, string, int) oppure può essere un generatore di risorse per una risorsa parametro . Il codice seguente sostituisce il GO_VERSION con un valore di parametro che può essere specificato in fase di distribuzione.

var builder = DistributedApplication.CreateBuilder(args);

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

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

Gli argomenti del build corrispondono al comando ARG in Dockerfiles. Espandendo l'esempio precedente, si tratta di un Dockerfile a più fasi che specifica la versione specifica dell'immagine del contenitore da usare come parametro.

# 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"]

Nota

Invece di inserire i valori codificati direttamente nell'immagine del contenitore, è consigliabile utilizzare le variabili di ambiente per i valori che cambiano frequentemente. In questo modo si evita la necessità di ricompilare l'immagine del contenitore ogni volta che è necessaria una modifica.

Trasmettere i segreti di build

Oltre agli argomenti di compilazione, è possibile specificare i segreti di compilazione utilizzando WithBuildSecret, che vengono resi disponibili selettivamente ai singoli comandi nella Dockerfile, usando la sintassi --mount=type=secret sui comandi 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);

Si consideri ad esempio il comando RUN in un Dockerfile che espone il segreto specificato al comando specifico:

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

Attenzione

Prestare attenzione quando si passano informazioni riservate in ambienti di compilazione. Questa operazione viene spesso eseguita quando si usa un token per recuperare le dipendenze da repository o feed privati prima di una compilazione. È importante assicurarsi che i segreti inseriti non vengano copiati nelle immagini finali o intermedie.