Mengelola agen transfer

Agen Storage Transfer Service adalah aplikasi yang berjalan di dalam container Docker, yang berkoordinasi dengan Storage Transfer Service untuk transfer yang melibatkan sistem file atau penyimpanan yang kompatibel dengan S3.

Jika transfer Anda tidak melibatkan sistem file atau penyimpanan yang kompatibel dengan S3, Anda tidak perlu menyiapkan agen.

Transfer dari Amazon S3 tidak memerlukan agen. Penyimpanan yang kompatibel dengan S3 mengacu pada sistem penyimpanan yang menggunakan S3 API, tetapi tidak dihosting oleh Amazon secara langsung.

Dokumen ini menjelaskan cara mengelola agen transfer di server Anda.

Ringkasan

• Proses agen bersifat dinamis. Saat menjalankan transfer, Anda dapat menambahkan agen untuk meningkatkan performa. Agen yang baru dimulai bergabung ke kumpulan agen yang ditetapkan dan melakukan pekerjaan dari transfer yang ada. Anda dapat menggunakan ini untuk menyesuaikan jumlah agen yang berjalan, atau menyesuaikan performa transfer dengan perubahan permintaan transfer.

• Proses agen adalah kolektif {i> fault-tolerant<i}. Jika satu agen berhenti berjalan, agen yang tersisa akan terus bekerja. Jika semua agen berhenti, saat Anda memulai ulang agen, transfer akan dilanjutkan saat agen dihentikan. Hal ini memungkinkan Anda menghindari pemantauan agen, mencoba ulang transfer, atau menerapkan logika pemulihan. Anda dapat mem-patch, memindahkan, dan menskalakan kumpulan agen secara dinamis tanpa periode nonaktif transfer dengan mengoordinasikan agen dengan Google Kubernetes Engine.

  Misalnya, Anda mengirimkan dua transfer saat dua agen sedang berjalan. Jika salah satu agen berhenti karena mulai ulang mesin atau patch sistem operasi, agen yang tersisa akan terus bekerja. Kedua transfer masih berjalan, tetapi lebih lambat karena satu agen memindahkan data. Jika agen yang tersisa juga berhenti, semua transfer akan berhenti membuat progres, karena tidak ada agen yang berjalan. Saat Anda memulai ulang proses agen, transfer akan dilanjutkan dari proses terakhir yang terhenti.

• Proses agen termasuk dalam kumpulan. Mereka secara kolektif memindahkan data Anda secara paralel. Oleh karena itu, semua agen dalam kumpulan harus memiliki akses yang sama ke semua sumber data yang ingin Anda transfer.

  Misalnya, jika Anda mentransfer data dari sistem file tertentu, Anda harus memasang sistem file ke setiap mesin yang menghosting agen di kumpulan agen Anda. Jika beberapa agen dalam kumpulan Anda dapat menjangkau sumber data dan yang lainnya tidak dapat, transfer dari sumber data tersebut tidak akan berhasil.

Sebelum memulai

Sebelum mengonfigurasi transfer, pastikan Anda telah mengonfigurasi akses: untuk pengguna dan akun layanan.

Jika Anda akan menggunakan perintah gcloud, instal gcloud CLI.

Menginstal dan menjalankan agen transfer

Penting: Pengguna yang dapat membuat tugas transfer dapat mengambil data dari, dan mendownload data ke, direktori sistem file apa pun yang dapat diakses oleh agen. Jika agen dijalankan sebagai root dan diberi akses ke seluruh sistem file, pelaku kejahatan mungkin dapat mengambil alih host. Sebaiknya Anda membatasi akses agen hanya ke direktori yang diperlukan.

Sebaiknya instal minimal tiga agen per kumpulan agen, idealnya di mesin terpisah. Untuk mengetahui informasi selengkapnya tentang cara menentukan jumlah agen yang akan dijalankan, lihat Memaksimalkan performa agen transfer.

Jangan sertakan informasi sensitif seperti informasi identitas pribadi (PII) atau data keamanan di awalan ID agen Anda. Nama resource dapat diterapkan ke nama resource Google Cloud lainnya dan dapat diekspos ke sistem internal Google di luar project Anda.

Untuk menginstal dan menjalankan agen transfer:

12 April 2023: Agen yang digunakan untuk transfer dari penyimpanan yang kompatibel dengan S3 harus melakukan autentikasi dengan kunci akun layanan. Gunakan flag --creds-file untuk menentukan jalur ke file kunci akun layanan. Kesalahan penggunaan akun layanan akan menyebabkan transfer terhenti; tugas akan ditampilkan sebagai sedang berlangsung, tetapi tidak ada data yang ditransfer.

Pemberitahuan ini akan dihapus saat masalah diselesaikan.

Konsol Google Cloud

1. Di konsol Google Cloud, buka halaman Agent pool.

   Buka Agent pool

2. Pilih kumpulan agen tempat akan menambahkan agen baru.

3. Klik Instal agen.

4. Ikuti petunjuk untuk menginstal dan menjalankan agen.

   Untuk mengetahui informasi selengkapnya tentang opsi command line agen, lihat Opsi command line agen.

gcloud CLI

Untuk menginstal satu atau beberapa agen menggunakan gcloud CLI, jalankan gcloud transfer agents install:

gcloud transfer agents install --pool=POOL_NAME --count=NUM_AGENTS \
  --mount-directories=MOUNT_DIRECTORIES

Alat ini akan memandu Anda melakukan langkah-langkah yang diperlukan untuk menginstal agen. Perintah ini menginstal agen NUM_AGENTS di komputer Anda, memetakan ke nama kumpulan yang ditentukan sebagai POOL_NAME, dan mengautentikasi agen menggunakan kredensial gcloud Anda. Nama kumpulan harus ada, atau error akan ditampilkan.

Flag --mount-directories bersifat opsional, tetapi sangat direkomendasikan. Nilainya adalah daftar direktori yang dipisahkan koma pada sistem file yang akan diberikan akses agen. Jika flag ini tidak ada, seluruh sistem file akan dipasang ke container agen. Lihat referensi gcloud untuk mengetahui detail selengkapnya.

Sumber yang kompatibel dengan S3

Saat menginstal agen untuk digunakan dengan sumber yang kompatibel dengan S3, Anda harus memberikan kredensial AWS baik sebagai variabel lingkungan sebagai nilai AWS_ACCESS_KEY_ID dan AWS_SECRET_ACCESS_KEY, atau yang disimpan sebagai kredensial default di file konfigurasi sistem Anda.

export AWS_ACCESS_KEY_ID=ID
export AWS_SECRET_ACCESS_KEY=SECRET
gcloud transfer agents install --pool=POOL_NAME \
  --creds-file=/relative/path/to/service-account-key.json

Gunakan kunci akun layanan

Catatan: Kunci akun layanan akan berisiko keamanan jika tidak dikelola dengan benar. Anda harus memilih alternatif yang lebih aman untuk kunci akun layanan jika memungkinkan. Jika harus melakukan autentikasi dengan kunci akun layanan, Anda bertanggung jawab atas keamanan kunci pribadi dan untuk operasi lain yang dijelaskan dalam Praktik terbaik untuk mengelola kunci akun layanan. Jika Anda tidak dapat membuat kunci akun layanan, pembuatan kunci akun layanan mungkin dinonaktifkan untuk organisasi Anda. Untuk mengetahui informasi selengkapnya, lihat Mengelola resource organisasi yang aman secara default.

Untuk menjalankan agen menggunakan kunci akun layanan, gunakan opsi --creds-file:

gcloud transfer agents install --pool=POOL_NAME --count=NUM_AGENTS \
   --creds-file=/relative/path/to/service-account-key.json

Info selengkapnya

Untuk daftar lengkap flag opsional, jalankan gcloud transfer agents install --help atau baca referensi gcloud transfer.

docker run

Sebelum menggunakan docker run untuk menginstal agen, ikuti petunjuk untuk menginstal Docker.

Perintah docker run menginstal satu agen. Untuk menambah jumlah agen di kumpulan Anda, jalankan kembali perintah ini sebanyak yang diperlukan.

Saat menginstal agen, Anda dapat memilih untuk melakukan autentikasi menggunakan kredensial default gcloud, atau dengan akun layanan.

Kredensial default

Agar container Docker dapat melakukan autentikasi dengan kredensial default gcloud, buat volume Docker yang berisi file yang berisi kredensial default aplikasi Anda dengan menjalankan perintah berikut:

sudo docker run -ti --name gcloud-config google/cloud-sdk gcloud auth application-default login

Lalu, gunakan perintah berikut untuk menginstal agen, menggunakan flag --volumes-from untuk memasang volume kredensial gcloud-config:

sudo docker run --ulimit memlock=64000000 -d --rm \
--volumes-from gcloud-config \
-v HOST_DIRECTORY:CONTAINER_DIRECTORY \
gcr.io/cloud-ingest/tsop-agent:latest \
--project-id=PROJECT_ID \
--hostname=$(hostname) \
--agent-pool=POOL_NAME

Autentikasi akun layanan

Untuk menginstal dan menjalankan agen transfer docker run menggunakan kredensial akun layanan, tentukan jalur ke kunci akun layanan berformat JSON menggunakan flag --creds-file.

Jalur harus diawali dengan string, /transfer_root.

Lihat Membuat dan mengelola kunci akun layanan untuk mengetahui informasi selengkapnya tentang kunci akun layanan.

Catatan: Kunci akun layanan akan berisiko keamanan jika tidak dikelola dengan benar. Anda harus memilih alternatif yang lebih aman untuk kunci akun layanan jika memungkinkan. Jika harus melakukan autentikasi dengan kunci akun layanan, Anda bertanggung jawab atas keamanan kunci pribadi dan untuk operasi lain yang dijelaskan dalam Praktik terbaik untuk mengelola kunci akun layanan. Jika Anda tidak dapat membuat kunci akun layanan, pembuatan kunci akun layanan mungkin dinonaktifkan untuk organisasi Anda. Untuk mengetahui informasi selengkapnya, lihat Mengelola resource organisasi yang aman secara default.

sudo docker run --ulimit memlock=64000000 -d --rm \
-v HOST_DIRECTORY:CONTAINER_DIRECTORY \
-v PATH/TO/KEY.JSON:PATH/TO/KEY.JSON \
gcr.io/cloud-ingest/tsop-agent:latest \
--project-id=PROJECT_ID \
--creds-file=/transfer_root/PATH/TO/KEY.JSON
--hostname=$(hostname) \
--agent-pool=POOL_NAME

Opsi dan tanda

Ganti variabel dalam contoh di atas dengan informasi berikut:

• HOST_DIRECTORY adalah direktori di mesin host yang ingin Anda salin. Anda dapat menggunakan lebih dari satu flag -v untuk menentukan direktori tambahan yang akan disalin.
• CONTAINER_DIRECTORY adalah direktori yang dipetakan dalam penampung agen. Atribut ini harus sama dengan HOST_DIRECTORY.
• PROJECT_ID adalah project ID yang menghosting transfer.
• POOL_NAME adalah nama kumpulan agen tempat menginstal agen ini. Jika Anda menghapus tanda ini, agen akan diinstal ke dalam kumpulan transfer_service_default project Anda.

Perintah docker run mendukung flag tambahan.

• --enable-mount-directory memasang seluruh sistem file pada direktori /transfer_root di container. Jika --enable-mount-directory ditentukan, pembatasan direktori yang menggunakan tanda -v tidak akan diterapkan.

  Perhatian: Jika agen dijalankan sebagai root dan diberi akses ke seluruh sistem file, pelaku kejahatan mungkin dapat mengambil alih host. Sebaiknya Anda membatasi akses agen hanya ke direktori yang diperlukan.

• --creds-file=CREDENTIAL_FILE menentukan jalur ke file kredensial akun layanan berformat JSON. Kecuali jika menggunakan --enable_mount_directory, Anda harus:

  1. Pasang file kredensial menggunakan flag -v.
  2. Awali jalur ke --creds-file dengan /transfer_root.

  Contoh:

  -v /tmp/key.json:/tmp/key.json \
  --creds-file=/transfer_root/tmp/key.json
  

• --enable-s3 menentukan bahwa agen ini ditujukan untuk transfer dari penyimpanan yang kompatibel dengan S3. Agen yang diinstal dengan opsi ini tidak dapat digunakan untuk transfer dari sistem file POSIX.

• Jika transfer Anda berasal dari penyimpanan yang kompatibel dengan AWS S3 atau S3, teruskan ID kunci akses dan kunci rahasia menggunakan variabel lingkungan:

  -e AWS_ACCESS_KEY_ID=AWS_ACCESS_KEY_ID \
  -e AWS_SECRET_ACCESS_KEY=AWS_SECRET_ACCESS_KEY
  

• --env HTTPS_PROXY=PROXY menentukan proxy penerusan di jaringan Anda. Nilai PROXY adalah URL HTTP dan port server proxy. Pastikan Anda menentukan URL HTTP, dan bukan URL HTTPS, untuk menghindari permintaan penggabungan ganda dalam enkripsi TLS. Permintaan yang digabungkan dua kali mencegah server proxy mengirim permintaan keluar yang valid.

• --agent-id-prefix=ID_PREFIX menentukan awalan opsional yang ditambahkan ke ID agen untuk membantu mengidentifikasi agen atau mesinnya di Konsol Google Cloud. Saat awalan digunakan, ID agen diformat sebagai prefix + hostname + Docker container ID.

• --log-dir=LOGS_DIRECTORY mengubah direktori tempat agen menulis log. Direktori default-nya adalah /tmp/.

  Jika belum menentukan --enable_mount_directory, Anda harus memberi awalan pada jalur ini dengan /transfer_root. Contohnya, /transfer_root/logs.

• --max-physical-mem=MAX_MEMORY: agen secara default menggunakan memori sistem maksimum 8 GiB. Jika defaultnya tidak sesuai dengan lingkungan Anda, Anda dapat menentukan penggunaan memori maksimum yang relevan dalam format berikut:

  Nilai max-physical-mem	Setelan memori maksimum
  6g	6 gigabita
  6gb	6 gigabita
  6GiB	6 gibibyte

Konfirmasi koneksi agen

Untuk memastikan bahwa agen Anda telah terhubung:

1. Di konsol Google Cloud, buka halaman Agent pool.

   Buka Agent pool

   Kumpulan agen Anda ditampilkan, dengan jumlah agen yang terhubung.

2. Pilih kumpulan agen untuk melihat detail tentang agen yang terhubung.

Jika agen baru tidak muncul di halaman kumpulan agen dalam waktu 10 menit setelah dibuat, lihat Agen tidak terhubung.

Memantau aktivitas agen

Anda dapat menggunakan pemberitahuan Cloud Monitoring untuk memantau aktivitas agen.

Pemantauan tersedia di sepanjang dimensi project, agent_pool, dan agent_id.

Dengan data pemantauan ini, Anda dapat menyiapkan pemberitahuan untuk memberi tahu tentang potensi masalah pada transfer. Untuk melakukannya, buat pemberitahuan di salah satu metrik Google Cloud berikut:

Nama metrik	Deskripsi	Penggunaan yang disarankan
storagetransfer.googleapis.com/agent/transferred_bytes_count	Mengukur seberapa cepat agen tertentu memindahkan data di semua tugas yang dilayaninya pada satu waktu tertentu.	Notifikasi untuk penurunan performa.
storagetransfer.googleapis.com/agent/connected	Boolean yang bernilai True untuk setiap agen tempat Google Cloud menerima pesan heartbeat terbaru.	Notifikasi untuk agen yang gagal Tidak berada di bawah sejumlah agen yang Anda anggap diperlukan untuk menghasilkan performa yang wajar Memberi sinyal masalah terkait mesin agen

Menghentikan agen

Untuk menghentikan agen, jalankan docker stop pada ID container Docker agen. Untuk menemukan ID dan menghentikan agen:

1. Di konsol Google Cloud, buka halaman Agent pool.

   Buka Agent pool

2. Pilih kumpulan agen yang berisi agen yang akan dihentikan.

3. Pilih agen dari daftar. Gunakan kolom Filter untuk menelusuri awalan, status agen, usia agen, dan lainnya.

4. Klik Hentikan agen. Perintah docker stop dengan ID penampung tertentu akan ditampilkan.

5. Jalankan perintah pada mesin tempat agen dijalankan. Perintah docker stop yang berhasil akan menampilkan ID penampung.

Setelah dihentikan, agen akan ditampilkan dalam daftar kumpulan agen sebagai Terputus.

Menghapus agen

Untuk menghapus agen tertentu, cantumkan agen mana yang berjalan di perangkat Anda:

docker container list --all --filter ancestor=gcr.io/cloud-ingest/tsop-agent

Kemudian, teruskan ID agen ke transfer agents delete:

gcloud transfer agents delete --ids=id1,id2,…

Untuk menghapus semua agen yang berjalan di mesin, gunakan flag --all atau flag --uninstall. Kedua flag menghapus semua agen di mesin; flag --uninstall juga meng-uninstal image Docker agen.

gcloud transfer agents delete --all
gcloud transfer agents delete --uninstall

Detail transfer sistem file

Transfer inkremental

Storage Transfer Service memulai semua transfer dengan menghitung data yang ada di sumber dan tujuan untuk menentukan file sumber mana yang baru, diperbarui, atau dihapus sejak transfer terakhir. Kami melakukan hal ini untuk mengurangi jumlah data yang kami kirim dari mesin Anda, menggunakan bandwidth secara efektif, dan mengurangi waktu transfer.

Untuk mendeteksi apakah file telah berubah, kami menggunakan algoritma yang mirip dengan gsutil rsync: kami memeriksa waktu dan ukuran file sumber terakhir diubah, lalu membandingkannya dengan waktu dan ukuran terakhir yang diubah yang direkam saat file terakhir disalin. Saat mendeteksi file baru atau yang diubah, kami menyalin seluruh file ke tujuannya. Untuk mengetahui informasi selengkapnya tentang keaktualan file, lihat Detail konsistensi data.

Secara default, kami mendeteksi, tetapi tidak menindaklanjuti, file yang dihapus di sumbernya. Jika Anda memilih opsi sinkronisasi Hapus file tujuan yang tidak ada di sumber saat membuat atau mengedit, transfer Anda akan menghapus objek yang sesuai di tujuan.

Jika Anda memilih opsi sinkronisasi Hapus file tujuan yang tidak ada di sumber, file yang tidak sengaja dihapus di sumbernya juga akan dihapus di tujuan. Untuk mencegah kehilangan data karena penghapusan yang tidak disengaja, sebaiknya aktifkan pembuatan versi objek di bucket tujuan jika Anda memilih untuk menggunakan opsi ini. Kemudian, jika tidak sengaja menghapus file, Anda dapat memulihkan objek di Cloud Storage ke versi lama.

Detail konsistensi data

Operasi transfer yang berhasil akan mentransfer semua file sumber yang ada dan tidak diubah selama operasi berjalan. File sumber yang dibuat, diperbarui, atau dihapus selama transfer mungkin akan memiliki perubahan tersebut atau tidak tercermin dalam set data tujuan.

Storage Transfer Service menggunakan waktu dan ukuran file terakhir diubah untuk menentukan apakah file berubah atau tidak. Jika file diupdate tanpa mengubah waktu atau ukuran terakhirnya, dan Anda mengaktifkan opsi delete-objects-from-source, Anda mungkin kehilangan data dari perubahan tersebut.

Saat menggunakan fitur delete-objects-from-source, sebaiknya Anda membekukan penulisan ke sumber selama durasi transfer untuk melindungi dari kehilangan data.

Untuk membekukan penulisan ke sumber Anda, lakukan salah satu hal berikut:

• Clone direktori yang ingin Anda transfer, lalu gunakan direktori yang di-clone sebagai sumber transfer.
• Menghentikan aplikasi yang menulis ke direktori sumber.

Jika penting untuk menangkap perubahan yang terjadi selama transfer, Anda dapat menjalankan ulang transfer atau menetapkan sistem file sumber sebagai hanya-baca saat operasi sedang berjalan.

Karena Cloud Storage tidak memiliki konsep direktori, direktori sumber kosong tidak akan ditransfer.

Penting: Sebaiknya Anda memvalidasi bahwa transfer berhasil sebelum menghapus data sumber apa pun. Layanan ini tidak memiliki kemampuan untuk memulihkan data di Cloud Storage.