Membuat kontainer referensi aplikasi .NET

Dalam artikel referensi ini, Anda mempelajari cara mengonfigurasi gambar kontainer yang dihasilkan saat Anda menerbitkan aplikasi .NET sebagai kontainer. Artikel ini membahas berbagai properti yang dapat Anda atur untuk mengontrol gambar, lingkungan eksekusi, dan perintah yang dijalankan saat kontainer dimulai.

Mengonfigurasi gambar kontainer

Anda dapat mengontrol banyak aspek kontainer yang dihasilkan melalui properti MSBuild. Secara umum, jika Anda dapat menggunakan perintah di Dockerfile untuk mengatur beberapa konfigurasi, Anda dapat melakukan hal yang sama melalui MSBuild.

Tidak ada cara untuk melakukan perintah RUN dengan .NET SDK. Perintah ini sering digunakan untuk menginstal beberapa paket OS atau membuat pengguna OS baru, atau sejumlah hal arbitrer. Jika Anda ingin tetap menggunakan fitur pembuatan kontainer .NET SDK, Anda dapat membuat gambar dasar kustom dengan perubahan ini lalu menggunakan gambar dasar ini. Untuk informasi selengkapnya, lihat ContainerBaseImage.

ContainerArchiveOutputPath

Untuk membuat gambar kontainer dalam arsip tar.gz, gunakan properti ContainerArchiveOutputPath. Fitur ini berguna jika alur kerja Anda tidak mudah dan mengharuskan Anda, misalnya, menjalankan alat pemindaian di atas gambar Anda sebelum mendorongnya. Setelah arsip dibuat, Anda dapat memindahkannya, memindainya, atau memuatnya ke toolchain Docker lokal.

Untuk menerbitkan ke arsip, tambahkan properti ContainerArchiveOutputPath ke perintah dotnet publish Anda, misalnya:

dotnet publish \
  -p PublishProfile=DefaultContainer \
  -p ContainerArchiveOutputPath=./images/sdk-container-demo.tar.gz

Anda dapat menentukan nama folder atau jalur dengan nama file tertentu. Jika Anda menentukan nama folder, nama file yang dihasilkan untuk file arsip gambar diberi nama $(ContainerRepository).tar.gz. Arsip ini dapat berisi beberapa tag di dalamnya, hanya karena satu file dibuat untuk semua ContainerImageTags.

Konfigurasi penamaan gambar kontainer

Gambar kontainer mengikuti konvensi penamaan tertentu. Nama gambar terdiri dari beberapa bagian, registri, port opsional, repositori, dan tag dan keluarga opsional.

REGISTRY[:PORT]/REPOSITORY[:TAG[-FAMILY]]

Misalnya, pertimbangkan nama gambar mcr.microsoft.com/dotnet/runtime:8.0-alpine yang sepenuhnya memenuhi syarat:

• mcr.microsoft.com adalah registri (dan dalam hal ini mewakili registri kontainer Microsoft).
• dotnet/runtime adalah repositori (tetapi beberapa menganggap ini sebagai user/repository).
• 8.0-alpine adalah tag dan keluarga (keluarga adalah penentu opsional yang membantu membedakan kemasan OS).

Beberapa properti yang dijelaskan di bagian berikut sesuai dengan mengelola bagian dari nama gambar yang dihasilkan. Pertimbangkan tabel berikut yang memetakan hubungan antara nama gambar dan properti build:

Bagian berikut menjelaskan berbagai properti yang dapat digunakan untuk mengontrol gambar kontainer yang dihasilkan.

ContainerBaseImage

Properti gambar dasar kontainer mengontrol gambar yang digunakan sebagai dasar untuk gambar Anda. Secara default, nilai berikut disimpulkan berdasarkan properti proyek Anda:

• Jika proyek Anda mandiri, gambar mcr.microsoft.com/dotnet/runtime-deps digunakan sebagai gambar dasar.
• Jika proyek Anda adalah proyek ASP.NET Core, gambar mcr.microsoft.com/dotnet/aspnet digunakan sebagai gambar dasar.
• Jika tidak, gambar mcr.microsoft.com/dotnet/runtime digunakan sebagai gambar dasar.

Tag gambar disimpulkan menjadi komponen numerik dari TargetFrameworkyang Anda pilih. Misalnya, proyek yang menargetkan net6.0 menghasilkan tag 6.0 gambar dasar yang disimpulkan, dan proyek net7.0-linux menggunakan tag 7.0, dan sebagainya.

Jika Anda menetapkan nilai di sini, Anda harus mengatur nama gambar yang sepenuhnya memenuhi syarat untuk digunakan sebagai dasar, termasuk tag apa pun yang Anda sukai:

<PropertyGroup>
    <ContainerBaseImage>mcr.microsoft.com/dotnet/runtime:8.0</ContainerBaseImage>
</PropertyGroup>

Dengan .NET SDK versi 8.0.200, inferensi ContainerBaseImage ditingkatkan untuk mengoptimalkan ukuran dan keamanan:

• Menargetkan Pengidentifikasi Runtime linux-musl-x64 atau linux-musl-arm64, secara otomatis memilih varian gambar alpine untuk memastikan proyek Anda berjalan:
  • Jika proyek menggunakan PublishAot=true maka varian nightly/runtime-depsjammy-chiseled-aot gambar dasar untuk ukuran dan keamanan terbaik.
  • Jika proyek menggunakan InvariantGlobalization=false maka varian -extra digunakan untuk memastikan pelokalan masih berfungsi.

Untuk informasi selengkapnya mengenai ukuran dan karakteristik varian gambar, lihat Laporan Ukuran Gambar Kontainer .NET 8.0.

ContainerFamily

Dimulai dengan .NET 8, Anda dapat menggunakan properti ContainerFamily MSBuild untuk memilih keluarga gambar kontainer yang disediakan Microsoft yang berbeda sebagai gambar dasar untuk aplikasi Anda. Saat diatur, nilai ini ditambahkan ke akhir tag khusus TFM yang dipilih, mengubah tag yang disediakan. Misalnya, untuk menggunakan varian Linux Alpine dari gambar dasar .NET, Anda dapat mengatur ContainerFamily ke alpine:

<PropertyGroup>
    <ContainerFamily>alpine</ContainerFamily>
</PropertyGroup>

Konfigurasi proyek sebelumnya menghasilkan tag akhir 8.0-alpine untuk aplikasi penargetan .NET 8.

Bidang ini berbentuk bebas, dan sering kali dapat digunakan untuk memilih distribusi sistem operasi yang berbeda, konfigurasi paket default, atau rasa lainnya perubahan pada gambar dasar. Bidang ini diabaikan ketika ContainerBaseImage diatur. Untuk informasi selengkapnya, lihat gambar kontainer .NET.

ContainerRuntimeIdentifier(s)

Properti ContainerRuntimeIdentifier menentukan OS dan arsitektur untuk kontainer Anda jika ContainerBaseImage mendukung beberapa platform. Misalnya, gambar mcr.microsoft.com/dotnet/runtime mendukung linux-x64, linux-arm, linux-arm64, dan win10-x64. Secara default, ini diatur ke RuntimeIdentifier digunakan saat menerbitkan kontainer. Biasanya, Anda tidak perlu mengatur properti ini secara eksplisit; sebagai gantinya, gunakan opsi -r dengan perintah dotnet publish. Jika gambar yang dipilih tidak mendukung RuntimeIdentifieryang ditentukan, kesalahan menunjukkan pengidentifikasi yang didukung.

Anda selalu dapat mengatur properti ContainerBaseImage ke nama gambar yang sepenuhnya memenuhi syarat, termasuk tag, untuk menghindari perlunya menggunakan properti ini sama sekali.

<PropertyGroup>
    <ContainerRuntimeIdentifier>linux-arm64</ContainerRuntimeIdentifier>
</PropertyGroup>

Untuk menentukan beberapa pengidentifikasi runtime kontainer untuk gambar multi-arsitektur, gunakan serangkaian pengidentifikasi runtime yang dibatasi titik koma di properti ContainerRuntimeIdentifiers, mirip dengan mengatur beberapa TargetFrameworks:

<PropertyGroup>
    <ContainerRuntimeIdentifiers>linux-x64;linux-arm64</ContainerRuntimeIdentifiers>
</PropertyGroup>

Untuk informasi selengkapnya mengenai pengidentifikasi runtime yang didukung oleh .NET, lihat katalog RID.

ContainerRegistry

Properti registri kontainer mengontrol registri tujuan, tempat gambar yang baru dibuat akan didorong. Secara default didorong ke daemon Docker lokal, tetapi Anda juga dapat menentukan registri jarak jauh. Saat menggunakan registri jarak jauh yang memerlukan autentikasi, Anda mengautentikasi menggunakan mekanisme docker login terkenal. Untuk informasi selengkapnya, Lihat mengautentikasi ke registri kontainer untuk detail selengkapnya. Untuk contoh konkret penggunaan properti ini, pertimbangkan contoh XML berikut:

<PropertyGroup>
    <ContainerRegistry>registry.mycorp.com:1234</ContainerRegistry>
</PropertyGroup>

Alat ini mendukung penerbitan ke registri apa pun yang mendukung Docker Registry HTTP API V2. Ini termasuk registri berikut secara eksplisit (dan kemungkinan banyak lebih implisit):

• Azure Container Registry
• Amazon Elastic Container Registry
• Registri Artefak Google
• Docker Hub
• Paket GitHub
• Container Registry yang dihosting GitLab
• Quay.io

Untuk catatan tentang bekerja dengan registri ini, lihat catatan khusus registri .

ContainerRepository

Repositori kontainer adalah nama gambar itu sendiri, misalnya, dotnet/runtime atau my-app. Secara default, AssemblyName proyek digunakan.

<PropertyGroup>
    <ContainerRepository>my-app</ContainerRepository>
</PropertyGroup>

Nama gambar terdiri dari satu atau beberapa segmen yang dibatasi garis miring, yang masing-masing hanya dapat berisi karakter alfanumerik huruf kecil, titik, garis bawah, dan tanda hubung, dan harus dimulai dengan huruf atau angka. Karakter lain mengakibatkan kesalahan dilemparkan.

ContainerImageTag(s)

Properti tag gambar kontainer mengontrol tag yang dihasilkan untuk gambar. Untuk menentukan satu tag, gunakan ContainerImageTag dan untuk beberapa tag, gunakan ContainerImageTags.

Tag sering digunakan untuk merujuk ke versi aplikasi yang berbeda, tetapi mereka juga dapat merujuk ke distribusi sistem operasi yang berbeda, atau bahkan konfigurasi yang berbeda.

Dimulai dengan .NET 8, ketika tag tidak disediakan, defaultnya adalah latest.

Untuk mengambil alih default, tentukan salah satu hal berikut ini:

<PropertyGroup>
    <ContainerImageTag>1.2.3-alpha2</ContainerImageTag>
</PropertyGroup>

Untuk menentukan beberapa tag, gunakan kumpulan tag yang dibatasi titik koma di properti ContainerImageTags, mirip dengan mengatur beberapa TargetFrameworks:

<PropertyGroup>
    <ContainerImageTags>1.2.3-alpha2;latest</ContainerImageTags>
</PropertyGroup>

Tag hanya dapat berisi hingga 127 karakter alfanumerik, titik, garis bawah, dan tanda hubung. Mereka harus dimulai dengan karakter alfanumerik atau garis bawah. Formulir lain menghasilkan kesalahan yang dilemparkan.

dotnet publish --os linux --arch x64 /t:PublishContainer /p:ContainerImageTags=`"1.2.3-alpha2`;latest`"

dotnet publish --os linux --arch x64 /t:PublishContainer /p:ContainerImageTags=\"1.2.3-alpha2;latest\"

$Env:ContainerImageTags='1.2.3;latest'; dotnet publish --os linux --arch x64 /t:PublishContainer

ContainerLabel

Label kontainer menambahkan label metadata ke kontainer. Label sering digunakan untuk menyimpan metadata versi dan penulisan untuk digunakan oleh pemindai keamanan dan alat infrastruktur lainnya. Anda dapat menentukan sejumlah label kontainer.

Simpul ContainerLabel memiliki dua atribut:

• Include: Kunci label.
• Value: Nilai label (ini mungkin kosong).

<ItemGroup>
    <ContainerLabel Include="org.contoso.businessunit" Value="contoso-university" />
</ItemGroup>

Untuk daftar label yang dibuat secara default, lihat label kontainer default.

Mengonfigurasi eksekusi kontainer

Untuk mengontrol eksekusi kontainer, Anda dapat menggunakan properti MSBuild berikut.

ContainerWorkingDirectory

Simpul direktori kerja kontainer mengontrol direktori kerja kontainer, direktori yang perintah dijalankan jika tidak perintah lain dijalankan.

Secara default, nilai direktori /app digunakan sebagai direktori kerja.

<PropertyGroup>
    <ContainerWorkingDirectory>/bin</ContainerWorkingDirectory>
</PropertyGroup>

ContainerPort

Port kontainer menambahkan port Protokol Kontrol Transmisi (TCP) atau Protokol Datagram Pengguna (UDP) ke daftar port yang diketahui untuk kontainer. Ini memungkinkan runtime kontainer seperti Docker untuk memetakan port ini ke komputer host secara otomatis. Ini sering digunakan sebagai dokumentasi untuk kontainer, tetapi juga dapat digunakan untuk mengaktifkan pemetaan port otomatis.

Simpul ContainerPort memiliki dua atribut:

• Include: Nomor port yang akan diekspos.
• Type: Default ke tcp, nilai yang valid adalah tcp atau udp.

<ItemGroup>
    <ContainerPort Include="80" Type="tcp" />
</ItemGroup>

Dimulai dengan .NET 8, ContainerPort disimpulkan ketika tidak secara eksplisit disediakan berdasarkan beberapa variabel lingkungan ASP.NET terkenal:

• ASPNETCORE_URLS
• ASPNETCORE_HTTP_PORTS
• ASPNETCORE_HTTPS_PORTS

Jika variabel lingkungan ini ada, nilainya diurai dan dikonversi ke pemetaan port TCP. Variabel lingkungan ini dibaca dari gambar dasar Anda, jika ada, atau dari variabel lingkungan yang ditentukan dalam proyek Anda melalui item ContainerEnvironmentVariable. Untuk informasi selengkapnya, lihat ContainerEnvironmentVariable.

ContainerEnvironmentVariable

Simpul variabel lingkungan kontainer memungkinkan Anda menambahkan variabel lingkungan ke kontainer. Variabel lingkungan dapat diakses oleh aplikasi yang berjalan di kontainer segera, dan sering digunakan untuk mengubah perilaku run-time aplikasi yang sedang berjalan.

Simpul ContainerEnvironmentVariable memiliki dua atribut:

• Include: Nama variabel lingkungan.
• Value: Nilai variabel lingkungan.

<ItemGroup>
  <ContainerEnvironmentVariable Include="LOGGER_VERBOSITY" Value="Trace" />
</ItemGroup>

Untuk informasi selengkapnya, lihat variabel lingkungan .NET.

Mengonfigurasi perintah kontainer

Secara default, alat kontainer meluncurkan aplikasi Anda menggunakan biner AppHost yang dihasilkan untuk aplikasi Anda (jika aplikasi Anda menggunakan AppHost), atau perintah dotnet ditambah DLL aplikasi Anda.

Namun, Anda dapat mengontrol bagaimana aplikasi Anda dijalankan dengan menggunakan beberapa kombinasi ContainerAppCommand, ContainerAppCommandArgs, ContainerDefaultArgs, dan ContainerAppCommandInstruction.

Titik konfigurasi yang berbeda ini ada karena gambar dasar yang berbeda menggunakan kombinasi yang berbeda dari ENTRYPOINT kontainer dan properti COMMAND, dan Anda ingin dapat mendukung semuanya. Default harus dapat digunakan untuk sebagian besar aplikasi, tetapi jika Anda ingin menyesuaikan perilaku peluncuran aplikasi, Anda harus:

• Identifikasi biner untuk dijalankan dan atur sebagai ContainerAppCommand
• Identifikasi argumen mana yang diperlukan agar aplikasi Anda berjalan dan atur sebagai ContainerAppCommandArgs
• Identifikasi argumen mana (jika ada) yang opsional dan dapat ditimpa oleh pengguna dan atur sebagai ContainerDefaultArgs
• Atur ContainerAppCommandInstruction ke DefaultArgs

Untuk informasi selengkapnya, lihat item konfigurasi berikut.

ContainerAppCommand

Item konfigurasi perintah aplikasi adalah titik masuk logis aplikasi Anda. Untuk sebagian besar aplikasi, ini adalah AppHost, biner yang dapat dieksekusi yang dihasilkan untuk aplikasi Anda. Jika aplikasi Anda tidak menghasilkan AppHost, perintah ini biasanya dotnet <your project dll>. Nilai-nilai ini diterapkan setelah ENTRYPOINT dalam kontainer dasar Anda, atau secara langsung jika tidak ada ENTRYPOINT yang ditentukan.

Konfigurasi ContainerAppCommand memiliki satu properti Include, yang mewakili perintah, opsi, atau argumen yang akan digunakan dalam perintah entrypoint:

<ItemGroup Label="ContainerAppCommand Assignment">
  <!-- This is how you would start the dotnet ef tool in your container -->
  <ContainerAppCommand Include="dotnet" />
  <ContainerAppCommand Include="ef" />

  <!-- This shorthand syntax means the same thing, note the semicolon separating the tokens. -->
  <ContainerAppCommand Include="dotnet;ef" />
</ItemGroup>

ContainerAppCommandArgs

Item konfigurasi args perintah aplikasi ini mewakili argumen yang diperlukan secara logis untuk aplikasi Anda yang harus diterapkan ke ContainerAppCommand. Secara default, tidak ada yang dihasilkan untuk aplikasi. Saat ada, arg diterapkan ke kontainer Anda saat dijalankan.

Konfigurasi ContainerAppCommandArgs memiliki satu properti Include, yang mewakili opsi atau argumen untuk diterapkan ke perintah ContainerAppCommand.

<ItemGroup>
  <!-- Assuming the ContainerAppCommand defined above,
       this would be the way to force the database to update.
  -->
  <ContainerAppCommandArgs Include="database" />
  <ContainerAppCommandArgs Include="update" />

  <!-- This is the shorthand syntax for the same idea -->
  <ContainerAppCommandArgs Include="database;update" />
</ItemGroup>

ContainerDefaultArgs

Item konfigurasi args default ini mewakili argumen yang dapat diganti pengguna untuk aplikasi Anda. Ini adalah cara yang baik untuk menyediakan default yang mungkin perlu dijalankan aplikasi Anda dengan cara yang memudahkan untuk memulai, namun masih mudah disesuaikan.

Konfigurasi ContainerDefaultArgs memiliki satu properti Include, yang mewakili opsi atau argumen untuk diterapkan ke perintah ContainerAppCommand.

<ItemGroup>
  <!-- Assuming the ContainerAppCommand defined above,
       this would be the way to force the database to update.
  -->
  <ContainerDefaultArgs Include="database" />
  <ContainerDefaultArgs Include="update" />

  <!-- This is the shorthand syntax for the same idea -->
  <ContainerDefaultArgs Include="database;update" />
</ItemGroup>

ContainerAppCommandInstruction

Konfigurasi instruksi perintah aplikasi membantu mengontrol cara ContainerEntrypoint, ContainerEntrypointArgs, ContainerAppCommand, ContainerAppCommandArgs, dan ContainerDefaultArgs digabungkan untuk membentuk perintah akhir yang dijalankan dalam kontainer. Ini sangat tergantung pada apakah ENTRYPOINT ada dalam gambar dasar. Properti ini mengambil salah satu dari tiga nilai: "DefaultArgs", "Entrypoint", atau "None".

• Entrypoint:
  • Dalam mode ini, titik masuk didefinisikan oleh ContainerAppCommand, ContainerAppCommandArgs, dan ContainerDefaultArgs.
• None:
  • Dalam mode ini, titik masuk didefinisikan oleh ContainerEntrypoint, ContainerEntrypointArgs, dan ContainerDefaultArgs.
• DefaultArgs:
  • Ini adalah mode paling kompleks—jika tidak ada item ContainerEntrypoint[Args] yang ada, ContainerAppCommand[Args] dan ContainerDefaultArgs digunakan untuk membuat titik masuk dan perintah. Titik masuk gambar dasar untuk gambar dasar yang memilikinya dikodekan secara permanen ke dotnet atau /usr/bin/dotnet dilewati sehingga Anda memiliki kontrol penuh.
  • Jika ContainerEntrypoint dan ContainerAppCommand ada, maka ContainerEntrypoint menjadi titik masuk, dan ContainerAppCommand menjadi perintah.

ContainerUser

Properti konfigurasi pengguna mengontrol pengguna default tempat kontainer berjalan. Ini sering digunakan untuk menjalankan kontainer sebagai pengguna non-root, yang merupakan praktik terbaik untuk keamanan. Ada beberapa batasan untuk mengetahui konfigurasi ini:

• Ini dapat mengambil berbagai formulir—nama pengguna, ID pengguna linux, nama grup, ID grup linux, username:groupname, dan varian ID lainnya.
• Tidak ada verifikasi bahwa pengguna atau grup yang ditentukan ada pada gambar.
• Mengubah pengguna dapat mengubah perilaku aplikasi, terutama sehubungan dengan hal-hal seperti izin Sistem File .

Nilai default bidang ini bervariasi menurut TFM proyek dan sistem operasi target:

• Jika Anda menargetkan .NET 8 atau yang lebih tinggi dan menggunakan gambar runtime Microsoft, maka:
  • di Linux, pengguna tanpa akar app digunakan (meskipun dirujuk oleh ID penggunanya)
  • pada Windows, ContainerUser pengguna tanpa akar digunakan
• Jika tidak, tidak ada ContainerUser default yang digunakan

<PropertyGroup>
  <ContainerUser>my-existing-app-user</ContainerUser>
</PropertyGroup>

Untuk mengonfigurasi aplikasi Anda agar berjalan sebagai pengguna root, atur properti ContainerUser ke root. Di file proyek Anda, tambahkan yang berikut ini:

<PropertyGroup>
  <ContainerUser>root</ContainerUser>
</PropertyGroup>

Atau, Anda dapat mengatur nilai ini saat memanggil dotnet publish dari baris perintah:

dotnet publish -p ContainerUser=root

Label kontainer default

Label sering digunakan untuk menyediakan metadata yang konsisten pada gambar kontainer. Paket ini menyediakan beberapa label default untuk mendorong pemeliharaan gambar yang dihasilkan dengan lebih baik.

• org.opencontainers.image.created diatur ke format ISO 8601 dari nilai DateTime.UtcNowsaat ini.

Untuk informasi selengkapnya, lihat Menerapkan label konvensional di atas infrastruktur label yang ada.

Lihat juga

• Kontainerisasi aplikasi .NET dengan penerbitan dotnet
• gambar kontainer .NET