Bagikan melalui


Gambaran umum pembuatan kontainer .NET SDK

Meskipun dimungkinkan untuk mengontainerisasi aplikasi .NET dengan Dockerfile, ada alasan menarik untuk mengontainerisasi aplikasi secara langsung dengan .NET SDK. Artikel ini memberikan gambaran umum tentang fitur pembuatan kontainer .NET SDK, dengan detail yang terkait dengan telemetri, pertimbangan penerbitan, properti build, dan autentikasi ke registri kontainer.

Menerbitkan pertimbangan proyek

Setelah memiliki aplikasi .NET, Anda dapat menerbitkannya sebagai kontainer. Sebelum melakukannya, ada beberapa pertimbangan penting yang perlu diingat. Sebelum .NET SDK versi 8.0.200, Anda memerlukan paket 📦 Microsoft.NET.Build.Containers NuGet. Paket ini tidak diperlukan untuk .NET SDK versi 8.0.200 dan yang lebih baru, karena dukungan kontainer disertakan secara default.

Untuk mengaktifkan penerbitan aplikasi .NET sebagai kontainer, properti build berikut diperlukan:

  • IsPublishable: Atur ke true. Properti ini secara implisit diatur ke true untuk jenis proyek yang dapat dieksekusi, seperti console, webapp, dan worker.
  • EnableSdkContainerSupport: Atur ke true saat jenis proyek Anda adalah aplikasi konsol.

Untuk mengaktifkan dukungan kontainer SDK secara eksplisit, pertimbangkan cuplikan file proyek berikut:

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

Menerbitkan opsi dan properti pembangunan

Seperti semua perintah .NET CLI, Anda dapat menentukan properti MSBuild pada baris perintah. Ada banyak formulir sintaks yang valid yang tersedia untuk menyediakan properti, seperti:

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

Anda bebas menggunakan sintaks apa pun yang Anda inginkan, tetapi dokumentasi menunjukkan contoh menggunakan formulir -p.

Saran

Untuk membantu memecahkan masalah, pertimbangkan untuk menggunakan log MSBuid. Untuk menghasilkan file log biner (binlog), tambahkan sakelar -bl ke perintah dotnet publish. File binlog berguna untuk mendiagnosis masalah build dan dapat dibuka di MSBuild Structured Log Viewer. Mereka memberikan jejak terperinci dari proses build, penting untuk analisis MSBuild. Untuk informasi selengkapnya, lihat Pemecahan masalah dan pembuatan log untuk MSBuild.

Publikasikan profil dan target

Saat menggunakan dotnet publish, menentukan profil dengan -p PublishProfile=DefaultContainer dapat mengatur properti yang menyebabkan SDK memicu target lain setelah proses penerbitan. Ini adalah cara tidak langsung untuk mencapai hasil yang diinginkan. Di sisi lain, menggunakan dotnet publish /t:PublishContainer secara langsung memanggil target PublishContainer, mencapai hasil yang sama tetapi dengan cara yang lebih mudah.

Dengan kata lain, perintah .NET CLI berikut:

dotnet publish -p PublishProfile=DefaultContainer

Yang mengatur properti PublishProfile ke DefaultContainer, setara dengan perintah berikut:

dotnet publish /t:PublishContainer

Perbedaan antara kedua metode adalah bahwa yang pertama menggunakan profil untuk mengatur properti, sementara yang terakhir langsung memanggil target. Alasan pentingnya adalah profil adalah fitur MSBuild, dan dapat digunakan untuk mengatur properti dengan cara yang lebih kompleks daripada hanya mengaturnya secara langsung.

Salah satu masalah utamanya adalah tidak semua jenis proyek mendukung profil atau memiliki kumpulan profil yang sama yang tersedia. Selain itu, ada disparitas dalam tingkat dukungan untuk profil antara alat yang berbeda, seperti Visual Studio dan .NET CLI. Oleh karena itu, menggunakan target umumnya merupakan metode yang lebih jelas dan didukung lebih luas untuk mencapai hasil yang sama.

Mengautentikasi ke registri kontainer

Berinteraksi dengan registri kontainer privat memerlukan autentikasi dengan registri tersebut.

Docker memiliki pola yang mapan dengan ini melalui perintah docker login, yang merupakan cara berinteraksi dengan file konfigurasi Docker yang berisi aturan untuk mengautentikasi dengan registri tertentu. File ini, dan jenis autentikasi yang dikodekannya, didukung oleh Microsoft.Net.Build.Containers untuk autentikasi registri. Ini harus memastikan bahwa paket ini bekerja tanpa hambatan dengan registri mana pun dari mana Anda dapat docker pull dan docker push. File ini biasanya disimpan di ~/.docker/config.json, tetapi dapat ditentukan juga melalui variabel DOCKER_CONFIG, yang menunjuk ke direktori yang berisi file config.json.

Jenis autentikasi

File config.json berisi tiga jenis autentikasi:

Nama pengguna/kata sandi eksplisit

Bagian auths dari file config.json adalah peta kunci/nilai antara nama registri dan string nama pengguna:kata sandi yang dikodekan Base64. Dalam skenario Docker umum, menjalankan docker login <registry> -u <username> -p <password> membuat item baru di peta ini. Kredensial ini populer dalam sistem integrasi berkelanjutan (CI), di mana proses masuk dilakukan menggunakan token pada awal pengoperasian. Namun, mereka kurang populer untuk mesin pengembangan pengguna akhir karena risiko keamanan memiliki kredensial kosong dalam file.

Pembantu kredensial

Bagian credHelpers dari file config.json adalah peta kunci/nilai antara nama registri dan nama program tertentu yang dapat digunakan untuk membuat dan mengambil kredensial untuk registri tersebut. Ini sering digunakan ketika registri tertentu memiliki persyaratan autentikasi yang kompleks. Agar autentikasi semacam ini berfungsi, Anda harus memiliki aplikasi bernama docker-credential-{name} pada PATHsistem Anda. Kredensial semacam ini cenderung aman, namun bisa sulit diatur pada mesin pengembangan atau CI.

Rantai kunci sistem

Bagian credsStore adalah properti string tunggal yang nilainya adalah nama program pembantu kredensial docker yang tahu cara berinteraksi dengan pengelola kata sandi sistem. Untuk Windows, ini mungkin wincred misalnya. Ini banyak digunakan oleh penginstal Docker untuk macOS dan Windows.

Autentikasi melalui variabel lingkungan

Dalam beberapa skenario, mekanisme autentikasi Docker standar yang dijelaskan di atas tidak cukup efektif. Alat ini memiliki mekanisme tambahan untuk memberikan kredensial ke registri: variabel lingkungan. Jika variabel lingkungan digunakan, mekanisme penyediaan kredensial tidak akan digunakan sama sekali. Variabel lingkungan berikut didukung:

  • DOTNET_CONTAINER_REGISTRY_UNAME: Ini harus menjadi nama pengguna untuk registri. Jika kata sandi untuk registri adalah token, maka nama pengguna harus "<token>".
  • DOTNET_CONTAINER_REGISTRY_PWORD: Ini harus menjadi kata sandi atau token untuk registri.

Nota

Pada .NET SDK 8.0.400, variabel lingkungan untuk operasi kontainer telah diperbarui. Variabel SDK_CONTAINER_* sekarang diawali dengan DOTNET_CONTAINER_*.

Mekanisme ini berpotensi rentan terhadap kebocoran kredensial, sehingga hanya boleh digunakan dalam skenario di mana mekanisme lain tidak tersedia. Misalnya, jika Anda menggunakan alat Kontainer SDK di dalam kontainer Docker itu sendiri. Selain itu, mekanisme ini tidak memiliki namespace—mekanisme ini mencoba menggunakan kredensial yang sama untuk registri sumber (tempat citra dasar Anda berada) dan registri tujuan (tempat Anda mendorong citra akhir).

Menggunakan registri yang tidak aman

Sebagian besar akses registri diasumsikan aman, yang berarti HTTPS digunakan untuk berinteraksi dengan registri. Namun, tidak semua registri dikonfigurasi dengan sertifikat TLS - terutama dalam situasi seperti registri perusahaan swasta di belakang VPN. Untuk mendukung kasus penggunaan ini, alat kontainer menyediakan cara mendeklarasikan bahwa registri tertentu menggunakan komunikasi yang tidak aman.

Mulai dari .NET 8.0.400, SDK memahami file dan format konfigurasi ini dan akan secara otomatis menggunakan konfigurasi tersebut untuk menentukan apakah HTTP atau HTTPS harus digunakan. Mengonfigurasi registri untuk komunikasi yang tidak aman bervariasi berdasarkan alat pilihan kontainer Anda.

Docker

Docker menyimpan konfigurasi registrinya dalam konfigurasi daemon . Untuk menambahkan registri baru yang tidak aman, host baru ditambahkan ke properti array "insecure-registries":

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

Nota

Anda harus memulai ulang daemon Docker untuk menerapkan perubahan apa pun pada file ini.

Podman

Podman menggunakan file TOML registries.conf untuk menyimpan informasi koneksi registri. File ini biasanya berada di /etc/containers/registries.conf. Untuk menambahkan registri tidak aman baru, bagian TOML ditambahkan untuk menahan pengaturan untuk registri, maka opsi insecure harus diatur ke true.

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

Nota

Anda harus menghidupkan ulang Podman untuk menerapkan perubahan apa pun pada file registries.conf.

Variabel lingkungan

Mulai dari 9.0.100, .NET SDK mengenali registri yang tidak aman melewati variabel lingkungan DOTNET_CONTAINER_INSECURE_REGISTRIES. Variabel ini mengambil daftar domain yang dipisahkan koma untuk diperlakukan tidak aman dengan cara yang sama seperti contoh Docker dan Podman di atas.

$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

Telemetri

Saat Anda menerbitkan aplikasi .NET sebagai kontainer, alat kontainer .NET SDK mengumpulkan dan mengirim telemetri penggunaan tentang cara alat digunakan. Data yang dikumpulkan ini merupakan tambahan dari telemetri yang dikirim oleh .NET CLI, tetapi menggunakan mekanisme yang sama dan, yang penting, mematuhi kontrol penolakan yang sama .

Telemetri yang dikumpulkan dimaksudkan untuk bersifat umum dan tidak membocorkan informasi pribadi apa pun—tujuan yang dimaksudkan adalah untuk membantu mengukur:

  • Penggunaan fitur kontainerisasi .NET SDK secara keseluruhan.
  • Tingkat keberhasilan dan kegagalan, bersama dengan informasi umum tentang jenis kegagalan apa yang paling sering terjadi.
  • Penggunaan fitur khusus dari teknologi, seperti penerbitan ke berbagai jenis registri, atau bagaimana penerbitan dijalankan.

Untuk menolak telemetri, atur variabel lingkungan DOTNET_CLI_TELEMETRY_OPTOUT ke true. Untuk informasi selengkapnya, lihat telemetri .NET CLI.

Telemetri inferensi

Informasi berikut tentang bagaimana proses inferensi gambar dasar terjadi dicatat:

Titik tanggal Penjelasan Nilai sampel
InferencePerformed Jika pengguna secara manual menentukan gambar dasar dibandingkan dengan menggunakan inferensi. true
TargetFramework TargetFramework dipilih saat melakukan inferensi gambar dasar. net8.0
BaseImage Nilai gambar dasar yang dipilih, tetapi hanya jika gambar dasar tersebut adalah salah satu gambar yang diproduksi Microsoft. Jika pengguna menentukan gambar apa pun selain gambar yang diproduksi Microsoft di mcr.microsoft.com, nilai ini null. mcr.microsoft.com/dotnet/aspnet
BaseImageTag Nilai tag yang dipilih, tetapi hanya jika tag tersebut adalah untuk salah satu gambar yang diproduksi Microsoft. Jika pengguna menentukan gambar apa pun selain gambar yang diproduksi Microsoft di mcr.microsoft.com, nilai ini null. 8.0
ContainerFamily Nilai properti ContainerFamily jika pengguna menggunakan fitur ContainerFamily untuk memilih 'rasa' dari salah satu gambar dasar kami. Ini hanya diatur jika pengguna memilih atau menyimpulkan salah satu gambar .NET yang diproduksi Microsoft dari mcr.microsoft.com jammy-chiseled
ProjectType Jenis proyek yang sedang dikontainerisasi. AspNetCore atau Console
PublishMode Bagaimana aplikasi dikemas. Aot, Trimmed, SelfContained, atau FrameworkDependent
IsInvariant Jika gambar yang dipilih memerlukan globalisasi yang tidak berubah atau pengguna memilihnya secara manual. true
TargetRuntime RID tempat aplikasi ini diterbitkan. linux-x64

Telemetri pembuatan gambar

Informasi berikut tentang bagaimana proses pembuatan dan penerbitan kontainer terjadi dicatat:

Titik tanggal Penjelasan Nilai sampel
RemotePullType Jika gambar dasar berasal dari registri jarak jauh, registri seperti apa itu? Azure, AWS, Google, GitHub, DockerHub, MRC, atau Lainnya
LocalPullType Jika gambar dasar berasal dari sumber lokal, seperti daemon kontainer atau tarball. Docker, Podman, Tarball
RemotePushType Jika gambar didorong ke registri jarak jauh, registri jenis apa itu? Azure, AWS, Google, GitHub, DockerHub, MRC, atau Lainnya
LocalPushType Jika gambar dikirim ke tujuan lokal, apa tujuannya? Docker, Podman, Tarball

Selain itu, jika berbagai jenis kesalahan terjadi selama proses data dikumpulkan tentang jenis kesalahan apa itu:

Titik tanggal Penjelasan Nilai sampel
Error Jenis kesalahan yang terjadi unknown_repository, credential_failure, rid_mismatch, local_load.
Direction Jika kesalahan adalah credential_failure, apakah itu ke registri pendorongan atau penarikan? push
Target RID Jika kesalahan adalah rid_mismatch, RID apa yang dimohon linux-x64
RID yang tersedia Jika kesalahan adalah rid_mismatch, RID apa saja yang didukung oleh gambar dasar? linux-x64,linux-arm64

Lihat juga