Condividi tramite


Panoramica della creazione di contenitori .NET SDK

Sebbene sia possibile containerizzare le app .NET con un Dockerfile , esistono ragioni convincenti per containerizzare le app direttamente con il .NET SDK. Questo articolo offre una panoramica della funzionalità di creazione di contenitori .NET SDK, con i dettagli relativi ai dati di telemetria, alla pubblicazione di considerazioni, alle proprietà di compilazione e all'autenticazione nei registri contenitori.

Considerazioni sulla pubblicazione dei progetti

Ora che si dispone di un'app .NET, è possibile pubblicarla come contenitore. Prima di farlo, è necessario tenere presenti alcune considerazioni importanti. Prima di .NET SDK versione 8.0.200, è necessario 📦 pacchetto Microsoft.NET.Build.Containers pacchetto NuGet. Questo pacchetto non è necessario per .NET SDK versione 8.0.200 e successive, perché il supporto del contenitore è incluso per impostazione predefinita.

Per abilitare la pubblicazione di un'app .NET come contenitore, sono necessarie le proprietà di compilazione seguenti:

  • IsPublishable: impostare su true. Questa proprietà è impostata in modo implicito su true per i tipi di progetto eseguibili, ad esempio console, webappe worker.
  • EnableSdkContainerSupport: impostare su true quando il tipo di progetto è un'app console.

Per abilitare in modo esplicito il supporto dei contenitori SDK, prendere in considerazione il frammento di file di progetto seguente:

<PropertyGroup>
  <IsPublishable>true</IsPublishable>
  <EnableSdkContainerSupport>true</EnableSdkContainerSupport>
</PropertyGroup>

Pubblicare interruttori e proprietà di compilazione

Come per tutti i comandi CLI di .NET, si possono specificare proprietà di MSBuild nella riga di comando. Sono disponibili molti moduli di sintassi validi per fornire proprietà, ad esempio:

  • /p:PropertyName=Value
  • -p:PropertyName=Value
  • -p PropertyName=Value
  • --property PropertyName=Value

È possibile usare qualsiasi sintassi preferita, ma la documentazione mostra esempi che usano il modulo -p.

Consiglio

Per risolvere i problemi, è consigliabile usare i log MSBuid. Per generare un file di log binario (binlog), aggiungere l'opzione -bl al comando dotnet publish. I file Binlog sono utili per diagnosticare i problemi di compilazione e possono essere aperti nel visualizzatore log strutturato di MSBuild . Forniscono una traccia dettagliata del processo di compilazione, essenziale per l'analisi di MSBuild. Per ulteriori informazioni, vedere Risoluzione dei problemi e creazione di log per MSBuild.

Pubblicare profili e destinazioni

Quando si usa dotnet publish, specificando un profilo con -p PublishProfile=DefaultContainer è possibile impostare una proprietà che fa sì che l'SDK attivi un'altra destinazione dopo il processo di pubblicazione. Si tratta di un modo indiretto per ottenere il risultato desiderato. D'altra parte, l'uso di dotnet publish /t:PublishContainer richiama direttamente l'obiettivo PublishContainer, ottenendo lo stesso risultato, ma in modo più semplice.

In altre parole, il seguente comando .NET CLI:

dotnet publish -p PublishProfile=DefaultContainer

Che imposta la proprietà PublishProfile su DefaultContainer, equivale al comando seguente:

dotnet publish /t:PublishContainer

La differenza tra i due metodi consiste nel fatto che il primo usa un profilo per impostare la proprietà, mentre l'ultimo richiama direttamente l'obiettivo. Il motivo è importante è che i profili sono una funzionalità di MSBuild e possono essere usati per impostare le proprietà in modo più complesso rispetto all'impostazione diretta.

Un problema fondamentale è che non tutti i tipi di progetto supportano i profili o hanno lo stesso set di profili disponibili. Inoltre, esiste una disparità nel livello di supporto per i profili tra diversi strumenti, ad esempio Visual Studio e l'interfaccia della riga di comando di .NET. Pertanto, l'uso di obiettivi è in genere un metodo più chiaro e più ampiamente supportato per ottenere lo stesso risultato.

Autenticarsi nei registri dei container

L'interazione con i registri contenitori privati richiede l'autenticazione con tali registri.

Docker ha un modello stabilito con questo tramite il comando docker login, che è un modo per interagire con un file di configurazione Docker che contiene regole per l'autenticazione con registri specifici. Questo file e i tipi di autenticazione codificati sono supportati da Microsoft.Net.Build.Containers per l'autenticazione del Registro di sistema. Questo dovrebbe garantire che questo pacchetto funzioni perfettamente con qualsiasi registro con cui puoi docker pull da e docker push. Questo file viene in genere archiviato in ~/.docker/config.json, ma può essere specificato anche tramite la variabile DOCKER_CONFIG, che punta a una directory contenente un file config.json.

Tipi di autenticazione

Il file config.json contiene tre tipi di autenticazione:

Nome utente/password esplicite

La sezione auths del file config.json è una mappa chiave/valore tra i nomi del Registro di sistema e le stringhe username:password con codifica Base64. In uno scenario docker comune, l'esecuzione di docker login <registry> -u <username> -p <password> crea nuovi elementi in questa mappa. Queste credenziali sono diffuse nei sistemi di integrazione continua (CI), in cui l'accesso viene eseguito tramite token all'inizio di un'esecuzione. Tuttavia, sono meno diffusi per i computer di sviluppo degli utenti finali a causa del rischio di sicurezza di avere credenziali bare in un file.

Assistenti delle credenziali

La sezione credHelpers del file config.json è una mappa chiave/valore tra i nomi del Registro di sistema e i nomi di programmi specifici che possono essere usati per creare e recuperare le credenziali per tale registro. Questo viene spesso usato quando determinati registri hanno requisiti di autenticazione complessi. Per consentire il funzionamento di questo tipo di autenticazione, è necessario disporre di un'applicazione denominata docker-credential-{name} nel PATHdel sistema. Questi tipi di credenziali tendono a essere sicure, ma possono essere difficili da configurare su macchine di sviluppo o di integrazione continua.

Portachiavi di sistema

La sezione credsStore è una proprietà stringa singola il cui valore indica il nome di un programma helper per le credenziali Docker che sa interfacciarsi con il gestore delle password del sistema. Per Windows, ad esempio, questo potrebbe essere wincred. Questi sono diffusi con i programmi di installazione di Docker per macOS e Windows.

Autenticazione tramite variabili di ambiente

In alcuni scenari, il meccanismo di autenticazione Docker standard descritto in precedenza non è sufficiente. Questo strumento include un meccanismo aggiuntivo per fornire le credenziali ai registri: variabili di ambiente. Se vengono usate variabili di ambiente, il meccanismo di fornire le credenziali non verrà usato affatto. Sono supportate le variabili di ambiente seguenti:

  • DOTNET_CONTAINER_REGISTRY_UNAME: deve essere il nome utente del Registro di sistema. Se la password per il Registro di sistema è un token, il nome utente deve essere "<token>".
  • DOTNET_CONTAINER_REGISTRY_PWORD: deve essere la password o il token per il Registro di sistema.

Nota

A partire da .NET SDK 8.0.400, le variabili di ambiente per le operazioni del contenitore sono state aggiornate. Le variabili di SDK_CONTAINER_* sono ora precedute da DOTNET_CONTAINER_*.

Questo meccanismo è potenzialmente vulnerabile alla perdita di credenziali, quindi deve essere usato solo negli scenari in cui l'altro meccanismo non è disponibile. Ad esempio, se si usa lo strumento SDK Container all'interno di un contenitore Docker stesso. Inoltre, questo meccanismo non è con spazi dei nomi, poiché tenta di usare le stesse credenziali sia per il registro di origine (dove si trova l'immagine di base) sia per il registro di destinazione (dove si effettua il push dell'immagine finale).

Uso di registri non sicuri

Si presuppone che la maggior parte dell'accesso al Registro di sistema sia sicura, ovvero HTTPS viene usato per interagire con il Registro di sistema. Tuttavia, non tutti i registri sono configurati con certificati TLS, soprattutto in situazioni come un registro aziendale privato dietro una VPN. Per supportare questi casi d'uso, gli strumenti contenitore offrono modi per dichiarare che un registro specifico usa comunicazioni non sicure.

A partire da .NET 8.0.400, l'SDK riconosce questi file e formati di configurazione e userà automaticamente tale configurazione per determinare se è necessario usare HTTP o HTTPS. La configurazione di un registro per le comunicazioni non sicure varia in base allo strumento contenitore preferito.

Docker

Docker archivia la configurazione del Registro di sistema nella configurazione del daemon . Per aggiungere nuovi registri non sicuri, i nuovi host vengono aggiunti alla proprietà della matrice "insecure-registries":

{
  "insecure-registries": [
    "registry.mycorp.net"
  ]
}

Nota

È necessario riavviare il daemon Docker per applicare le modifiche apportate a questo file.

Podman

Podman usa un file TOML registries.conf per archiviare le informazioni di connessione del Registro di sistema. Questo file si trova in genere in /etc/containers/registries.conf. Per aggiungere nuovi registri non sicuri, viene aggiunta una sezione TOML per contenere le impostazioni per il Registro di sistema, quindi l'opzione insecure deve essere impostata su true.

[[registry]]
location = "registry.mycorp.net"
insecure = true

Nota

È necessario riavviare Podman per applicare le modifiche apportate al file registries.conf.

Variabili di ambiente

A partire dalla versione 9.0.100, .NET SDK riconosce i registri non sicuri passati attraverso la variabile di ambiente DOTNET_CONTAINER_INSECURE_REGISTRIES. Questa variabile accetta un elenco delimitato da virgole di domini per trattare come non sicuro nello stesso modo degli esempi di Docker e Podman precedenti.

$Env:DOTNET_CONTAINER_INSECURE_REGISTRIES=localhost:5000,registry.mycorp.com; dotnet publish -t:PublishContainer -p:ContainerRegistry=registry.mycorp.com -p:ContainerBaseImage=localhost:5000/dotnet/runtime:9.0

Telemetria

Quando si pubblica un'app .NET come contenitore, gli strumenti dei contenitori .NET SDK raccolgono e inviano dati di telemetria sull'utilizzo su come vengono usati gli strumenti. I dati raccolti si aggiungono ai dati di telemetria inviati dalla .NET CLI, ma utilizzano gli stessi meccanismi e, soprattutto, rispettano gli stessi controlli di opt-out .

I dati di telemetria raccolti sono destinati a essere di natura generale e non a perdere informazioni personali, lo scopo previsto è quello di aiutare a misurare:

  • Utilizzo complessivo della funzionalità di containerizzazione di .NET SDK.
  • Tassi di esito positivo e negativo, insieme a informazioni generali sui tipi di errori che si verificano più frequentemente.
  • Utilizzo di funzionalità specifiche della tecnologia, ad esempio la pubblicazione in vari tipi di Registro di sistema o il modo in cui è stata richiamata la pubblicazione.

Per rifiutare esplicitamente la telemetria, impostare la variabile di ambiente DOTNET_CLI_TELEMETRY_OPTOUT su true. Per altre informazioni, vedere telemetria dell'interfaccia della riga di comando di .NET.

Telemetria dell'inferenza

Vengono registrate le seguenti informazioni su come si è svolto il processo di inferenza dell'immagine di base:

Data di riferimento Spiegazione Valore di esempio
InferencePerformed Se gli utenti specificano manualmente immagini di base anziché usare l'inferenza. true
TargetFramework Il TargetFramework scelto durante l'inferenza dell'immagine di base. net8.0
BaseImage Valore dell'immagine di base scelta, ma solo se l'immagine di base è una delle immagini prodotte da Microsoft. Se un utente specifica un'immagine diversa dalle immagini prodotte da Microsoft in mcr.microsoft.com, questo valore è Null. mcr.microsoft.com/dotnet/aspnet
BaseImageTag Valore del tag scelto, ma solo se il tag è per una delle immagini prodotte da Microsoft. Se un utente specifica un'immagine diversa dalle immagini prodotte da Microsoft in mcr.microsoft.com, questo valore è Null. 8.0
ContainerFamily Valore della proprietà ContainerFamily se un utente ha utilizzato la funzionalità ContainerFamily per scegliere una "variante" di una delle nostre immagini di base. Questa impostazione viene impostata solo se l'utente ha scelto o dedotto una delle immagini .NET prodotte da Microsoft da mcr.microsoft.com jammy-chiseled
ProjectType Tipo di progetto che viene containerizzato. AspNetCore o Console
PublishMode Modalità di creazione del pacchetto dell'applicazione. Aot, Trimmed, SelfContainedo FrameworkDependent
IsInvariant Se l'immagine scelta richiede una globalizzazione invariante o l'utente ha scelto di aderire manualmente. true
TargetRuntime RID per cui è stata pubblicata quest'applicazione. linux-x64

Telemetria per la creazione di immagini

Vengono registrate le informazioni seguenti su come si è verificato il processo di creazione e pubblicazione del contenitore:

Punto temporale Spiegazione Valore di esempio
RemotePullType Se l'immagine di base proviene da un registro remoto, qual è il tipo di registro? Azure, AWS, Google, GitHub, DockerHub, MRC o Altro
LocalPullType Se l'immagine di base proviene da un'origine locale, ad esempio un demone di contenitori o un tarball. Docker, Podman, Tarball
RemotePushType Se è stato eseguito il push dell'immagine in un registro remoto, qual è il tipo di registro? Azure, AWS, Google, GitHub, DockerHub, MRC o Altro
LocalPushType Se l'immagine è stata caricata in una destinazione locale, qual era? Docker, Podman, Tarball

Inoltre, se si verificano diversi tipi di errori durante il processo che i dati vengono raccolti sul tipo di errore che si è verificato:

Data di riferimento Spiegazione Valore di esempio
Error Tipo di errore che si è verificato unknown_repository, credential_failure, rid_mismatch, local_load.
Direction Se l'errore è un credential_failure, è stato nel registro del push o del pull? push
RID di destinazione Se l'errore è un rid_mismatch, quale RID è stato richiesto linux-x64
RID disponibili Se l'errore era un rid_mismatch, quali RIDs supportava l'immagine di base? linux-x64,linux-arm64

Vedere anche