Mengonfigurasi host virtual

Anda sedang melihat dokumentasi Apigee Edge.
Buka dokumentasi Apigee X. info

Pelanggan Cloud dengan akun berbayar dan semua pelanggan Edge for Private Cloud dapat membuat host virtual di organisasi. Pengguna yang membuat host virtual harus memiliki peran administrator organisasi, atau memiliki peran kustom dengan izin untuk mengubah host virtual. Pengguna dalam peran lain tidak memiliki otorisasi untuk membuat host virtual.

Tonton video pengantar tentang host virtual.

Membuat host virtual

Gunakan prosedur dasar berikut untuk membuat host virtual. Prosedur yang sebenarnya Anda gunakan didasarkan pada apakah Anda adalah pelanggan Cloud atau Cloud Pribadi, dan apakah Anda mengaktifkan TLS:

  1. Buat entri DNS dan data CNAME untuk domain yang ditampilkan secara publik.
  2. Jika mengaktifkan TLS di host virtual:
    1. Buat dan konfigurasikan keystore menggunakan prosedur yang dijelaskan di sini: Keystore dan Truststore.
    2. Upload sertifikat dan kunci Anda ke keystore. Pastikan nama domain yang ditentukan oleh sertifikat Anda cocok dengan alias host yang ingin Anda gunakan untuk host virtual.
    3. Buat referensi ke keystore menggunakan UI atau API Edge. Referensi menentukan nama keystore dan jenis referensi sebagai KeyStore. Lihat Menggunakan referensi untuk mengetahui informasi selengkapnya tentang cara membuat dan mengubah referensi.
    4. Jika Anda melakukan TLS dua arah, buat truststore, upload sertifikat, dan buat referensi ke truststore. Buat truststore menggunakan prosedur yang dijelaskan di sini: Keystore dan Truststore.
  3. Buat host virtual menggunakan API Buat Host Virtual. Jika mengaktifkan TLS, pastikan untuk menentukan referensi keystore, referensi truststore, dan alias kunci yang benar.
  4. Jika Anda sudah memiliki proxy API, tambahkan host virtual ke ProxyEndpoint. Host virtual ditambahkan secara otomatis ke semua proxy API baru. Lihat Mengonfigurasi proxy API untuk menggunakan host virtual.

Setelah mengupdate proxy API untuk menggunakan host virtual, dan membuat entri DNS dan data CNAME untuk alias host, Anda dapat mengakses proxy API seperti yang ditunjukkan di bawah:

https://api.myCompany.com/v1/project-base-path/resource-path

Contoh:

https://api.myCompany.com/v1/weather/forecastrss?w=12797282

Membuat host virtual menggunakan API atau UI

Anda dapat membuat host virtual menggunakan Edge API atau Edge UI.

Sebagian besar contoh di bawah menggunakan Edge API. Untuk mengakses UI guna membuat, mengubah, dan menghapus host virtual di UI Edge:

  1. Login ke apigee.com/edge

    Pelanggan Edge for Private Cloud menggunakan http://ms-ip:9000 (lokal), dengan ms-ip adalah alamat IP atau nama DNS node Server Pengelolaan.

  2. Pilih Admin > Virtual Hosts di menu navigasi sebelah kiri.
  3. Pilih lingkungan, seperti prod atau test.
    Host virtual yang ditentukan untuk lingkungan akan ditampilkan.
  4. Pilih + Virtual Host untuk membuat host virtual atau pilih nama host virtual yang ada untuk mengeditnya.

Membuat host virtual untuk HTTP

Pelanggan Edge untuk Private Cloud dapat membuat host virtual menggunakan HTTP.

Untuk membuat host virtual yang tidak mendukung TLS, buat objek XML yang menentukan host virtual. Misalnya, objek XML berikut menentukan host virtual yang menggunakan protokol HTTP:

<VirtualHost name="myVHost">
   <HostAliases>
     <HostAlias>api.myCompany.com</HostAlias>
   </HostAliases>
   <Interfaces/>
   <Port>80</Port>
</VirtualHost>

Dalam definisi ini, Anda:

  • Tentukan name sebagai myVHost. Gunakan nama untuk mereferensikan host virtual di proxy API atau dalam panggilan API.
  • Tentukan alias host sebagai api.perusahaansaya.com. Ini adalah domain yang ditampilkan secara publik yang digunakan untuk mengakses API Anda seperti yang ditentukan oleh definisi DNS dan data CNAME.
  • Tentukan nomor port sebagai 80. Jika dihilangkan, secara default port ditetapkan ke 443.

  • Ada properti tambahan yang dapat Anda tetapkan di host virtual. Untuk referensi semua properti, lihat Referensi properti host virtual.

Jika Anda sudah memiliki proxy API, tambahkan host virtual ke elemen <HTTPConnection> di Endpoint Proxy. Host virtual ditambahkan secara otomatis ke semua proxy API baru. Lihat Mengonfigurasi proxy API untuk menggunakan host virtual. Jika Anda membuat proxy API baru yang tidak boleh diakses melalui host virtual tertentu, Anda harus mengedit proxy API untuk menghapus host virtual tersebut dari ProxyEndpoint-nya.

Kemudian, Anda dapat mengakses proxy API melalui host virtual ini dengan membuat permintaan ke:

http://api.myCompany.com/proxy-base-path/resource-path
https://api.myCompany.com/proxy-base-path/resource-path

Buat host virtual menggunakan API Buat Host Virtual:

curl -X POST -H "Content-Type:application/xml" \
  http://ms-IP:8080/v1/o/org_name/environments/env_name/virtualhosts \
  -d '<VirtualHost name="myVHost">
        <HostAliases>
            <HostAlias>api.myCompany.com</HostAlias>
        </HostAliases>
        <Interfaces/>
        <Port>80</Port>
    </VirtualHost>' \
  -u sysAdminEmail:password

Membuat host virtual untuk TLS satu arah

Objek XML berikut menentukan host virtual untuk TLS satu arah:

<VirtualHost name="myTLSVHost">
    <HostAliases>
        <HostAlias>api.myCompany.com</HostAlias>
    </HostAliases>
    <Port>443</Port>
    <SSLInfo>
        <Enabled>true</Enabled>
        <ClientAuthEnabled>false</ClientAuthEnabled>
        <KeyStore>ref://myTestKeystoreRef</KeyStore>
        <KeyAlias>myKeyAlias</KeyAlias>
    </SSLInfo>
</VirtualHost>

Dalam definisi ini, Anda mengaktifkan TLS dengan menetapkan elemen <Enable> ke true, dan menggunakan elemen <KeyStore> dan <KeyAliase> untuk menentukan keystore dan alias kunci yang digunakan oleh koneksi TLS.

Lihat TLS/SSL untuk mengetahui informasi selengkapnya tentang penggunaan TLS.

Menentukan cara menentukan nama keystore dan truststore di host virtual

Saat mengonfigurasi host virtual untuk mendukung TLS, Anda menentukan keystore menggunakan referensi. Referensi adalah variabel yang berisi nama keystore atau truststore, bukan menentukan nama keystore atau truststore secara langsung, seperti yang ditunjukkan di bawah:

    <SSLInfo>
        <Enabled>true</Enabled>
        <ClientAuthEnabled>false</ClientAuthEnabled>
        <KeyStore>ref://myTestKeystoreRef</KeyStore>
        <KeyAlias>myKeyAlias</KeyAlias>
    </SSLInfo>

Keuntungan menggunakan referensi adalah Anda dapat mengubah nilai referensi untuk mengubah keystore yang digunakan oleh host virtual, biasanya karena masa berlaku sertifikat di keystore saat ini akan segera berakhir. Mengubah nilai referensi tidak mengharuskan Anda memulai ulang Edge Router. Lihat Menggunakan referensi untuk mengetahui informasi selengkapnya tentang cara membuat dan mengubah referensi.

Anda hanya dapat menggunakan referensi ke keystore dan truststore; Anda tidak dapat menggunakan referensi ke alias. Saat Anda mengubah referensi ke keystore, pastikan nama alias sertifikat sama dengan yang ada di keystore lama.

Pembatasan dalam menggunakan referensi ke keystore dan truststore

Anda harus mempertimbangkan batasan berikut saat menggunakan referensi ke keystore dan truststore:

  • Anda hanya dapat menggunakan referensi keystore dan truststore di host virtual jika mendukung SNI dan menghentikan SSL di Router Apigee.
  • Jika Anda memiliki load balancer di depan Router Apigee, dan Anda menghentikan TLS di load balancer, Anda tidak dapat menggunakan referensi keystore dan truststore di host virtual.

Membuat host virtual untuk TLS dua arah

Untuk mengaktifkan TLS dua arah, tetapkan elemen <ClientAuthEnabled> ke true, dan tentukan truststore dengan menggunakan referensi dengan elemen <TrustStore>. Truststore menyimpan penerbit sertifikat klien dan rantai CA sertifikat, yang diperlukan. Klien juga harus dikonfigurasi dengan benar untuk TLS dua arah.

Untuk membuat host virtual untuk TLS dua arah, buat objek XML yang menentukan host virtual:

<VirtualHost name="myTLSVHost">
    <HostAliases>
        <HostAlias>api.myCompany.com</HostAlias>
    </HostAliases>
    <Port>443</Port>
    <SSLInfo>
        <Enabled>true</Enabled>
        <ClientAuthEnabled>true</ClientAuthEnabled>
        <KeyStore>ref://myTestKeystoreRef</KeyStore>
        <KeyAlias>myKeyAlias</KeyAlias>
        <TrustStore>ref://myTestTruststoreRef</TrustStore>
    </SSLInfo>
</VirtualHost>

Dalam definisi ini, Anda:

  • Aktifkan TLS dua arah dengan menetapkan <ClientAuthEnabled> ke true.
  • Tentukan referensi ke truststore menggunakan elemen <TrustStore>. Truststore menyimpan penerbit sertifikat klien dan rantai CA sertifikat, yang diperlukan.

Lihat TLS/SSL untuk mengetahui informasi selengkapnya tentang penggunaan TLS.

Mengubah host virtual

Pelanggan Cloud dengan akun berbayar dan semua pelanggan Edge for Private Cloud dapat menggunakan Update a Virtual Host API untuk mengupdate host virtual. API ini memungkinkan Anda menetapkan semua properti untuk host virtual yang dijelaskan di Referensi properti host virtual.

Perbarui host virtual menggunakan Update Virtual Host API. Saat menggunakan API, Anda harus menentukan definisi lengkap host virtual dalam isi permintaan, bukan hanya elemen yang ingin diubah.

Dalam contoh ini, Anda menetapkan nilai properti proxy_read_timeout:

curl -X PUT -H "Content-Type:application/xml" \
    https://api.enterprise.apigee.com/v1/o/org_name/e/env_name/virtualhosts/vhost_name \
    -d '<VirtualHost  name="myTLSVHost">
         <HostAliases>
           <HostAlias>api.myCompany.com</HostAlias>
         </HostAliases>
         <Port>443</Port>
         <SSLInfo>
           <Enabled>true</Enabled>
           <ClientAuthEnabled>false</ClientAuthEnabled>
           <KeyStore>ref://myTestKeystoreRef</KeyStore>
           <KeyAlias>myKeyAlias</KeyAlias>
         </SSLInfo>
         <Properties>
           <Property name="proxy_read_timeout">50</Property>
         </Properties>
     </VirtualHost>' \
    -u orgAdminEmail:password

Menghapus host virtual

Sebelum dapat menghapus host virtual dari lingkungan, Anda harus memperbarui proxy API apa pun yang mereferensikan host virtual untuk menghapus referensi. Lihat Mengonfigurasi proxy API untuk menggunakan host virtual.

Hapus host virtual menggunakan Delete a Virtual Host API:

curl -X DELETE \
  https://api.enterprise.apigee.com/v1/o/org_name/e/env_name/virtualhosts/vhost_name \
  -u orgAdminEmail:password

Melihat informasi tentang host virtual

Lihat informasi tentang host virtual yang ditentukan di lingkungan, seperti yang dijelaskan di bawah.

Edge

Untuk melihat informasi tentang host virtual menggunakan UI Edge:

  1. Login ke apigee.com/edge.

    Pelanggan Edge for Private Cloud menggunakan http://ms-ip:9000 (lokal), dengan ms-ip adalah alamat IP atau nama DNS node Server Pengelolaan.

  2. Pilih Admin > Virtual Hosts di menu navigasi sebelah kiri.
  3. Pilih lingkungan, seperti prod atau test.

    Host virtual yang ditentukan untuk lingkungan akan muncul. Jika host virtual dikonfigurasi untuk menggunakan keystore atau truststore, klik Tampilkan untuk melihat informasi selengkapnya.

Jika host virtual dikonfigurasi untuk menggunakan TLS/SSL, ikon gembok akan muncul di samping nama host virtual. Artinya, sertifikat, kunci, dan rantai sertifikat TLS/SSL telah diupload ke Edge dan dikaitkan dengan host virtual. Untuk melihat informasi tentang sertifikat yang tersedia:

  1. Pilih Admin > Lingkungan > Keystore TLS di menu navigasi sebelah kiri.
  2. Pilih Lingkungan (biasanya prod atau test).
  3. Luaskan keystore untuk melihat sertifikat.

Edge Klasik (Private Cloud)

Untuk melihat informasi tentang host virtual menggunakan UI Edge Klasik:

  1. Login ke http://ms-ip:9000, dengan ms-ip adalah alamat IP atau nama DNS node Server Pengelolaan.
  2. Pilih Admin > Virtual Hosts di menu navigasi sebelah kiri.
  3. Pilih lingkungan, seperti prod atau test.
  4. Klik tab Virtual Hosts.

    Host virtual yang ditentukan untuk lingkungan akan muncul. Jika host virtual dikonfigurasi untuk menggunakan keystore atau truststore, klik Tampilkan untuk melihat informasi selengkapnya.

    Tab Virtual Hosts menampilkan informasi tentang nama, port, dan alias, serta lainnya.

Jika host virtual dikonfigurasi untuk menggunakan TLS/SSL, ikon gembok akan muncul di samping nama host virtual. Artinya, sertifikat, kunci, dan rantai sertifikat TLS/SSL telah diupload ke Edge dan dikaitkan dengan host virtual. Untuk melihat informasi tentang sertifikat yang tersedia:

  1. Pilih Admin > Sertifikat TLS di menu navigasi atas.
  2. Pilih Lingkungan (biasanya prod atau test).
  3. Luaskan keystore untuk melihat sertifikat.

Melihat host virtual dengan Edge API

Anda juga dapat menggunakan Edge API untuk melihat informasi tentang host virtual. Misalnya, List Virtual Hosts API menampilkan daftar semua host virtual:

curl -X GET -H "accept:application/xml" \
    https://api.enterprise.apigee.com/v1/o/org_name/environments/env_name/virtualhosts \
    -u orgAdminEmail:pWord

Dengan orgAdminEmail:pWord adalah nama pengguna dan sandi admin org, dan org_name/env_name menentukan organisasi dan lingkungan yang berisi host virtual. Contoh respons:

[
 "default",
 "secure"
]

Untuk melihat informasi tentang host virtual tertentu, gunakan API Get Virtual Host:

curl -X GET -H "accept:application/xml" \
    https://api.enterprise.apigee.com/v1/o/org_name/environments/env_name/virtualhosts/vhost_name \
    -u orgAdminEmail:pWord

Dengan vhost_name adalah nama host virtual. Misalnya, Anda dapat menentukan vhost_name sebagai "secure" untuk melihat konfigurasi host virtual aman default yang dibuat oleh Apigee:

<VirtualHost name="secure">
    <HostAliases>
        <HostAlias>api.myCompany.com</HostAlias>
    </HostAliases>
    <Port>443</Port>
    <Properties/>
    <Interfaces/>
    <RetryOptions/>
    <SSLInfo>
        <ClientAuthEnabled>false</ClientAuthEnabled>
        <Enabled>true</Enabled>
        <KeyAlias>freetrial</KeyAlias>
        <KeyStore>ref://freetrial</KeyStore>
        <IgnoreValidationErrors>false</IgnoreValidationErrors>
    </SSLInfo>
</VirtualHost>

Mengonfigurasi proxy API untuk menggunakan host virtual

Saat Anda membuat proxy API baru, Edge akan otomatis mengonfigurasinya untuk menggunakan semua host virtual yang tersedia di organisasi. Permintaan ke proxy API melalui host virtual menggunakan formulir:

https://host-alias/proxy-base-path/resource-path

Dengan keterangan:

  • host-alias biasanya adalah nama DNS host virtual.
  • proxy-base-path ditentukan saat Anda membuat proxy API dan bersifat unik untuk setiap proxy API.
  • resource-path jalur ke resource yang dapat diakses melalui proxy API.

Mengontrol host virtual yang digunakan oleh proxy API

Dalam konfigurasi XML proxy API, Anda menggunakan tag virtualhost untuk menentukan nama host virtual yang terkait dengan proxy API:

<HTTPProxyConnection>
  <BasePath>/v1/my/proxy/basepath</BasePath>
  <VirtualHost>secure</VirtualHost>
  <VirtualHost>default</VirtualHost>
</HTTPProxyConnection>

Misalnya, <VirtualHost>secure</VirtualHost> berarti klien dapat memanggil proxy API menggunakan alias host dari host virtual "aman".

Anda biasanya mengubah host virtual yang terkait dengan proxy API saat:

  • Anda membuat host virtual baru dan memiliki proxy API yang sudah ada. Anda harus mengedit proxy API yang ada untuk menambahkan host virtual baru.
  • Anda membuat proxy API baru yang tidak boleh diakses melalui host virtual tertentu. Anda harus mengedit proxy API untuk menghapus host virtual tersebut dari definisinya.

Untuk mengubah host virtual yang terkait dengan proxy API:

  1. Akses editor proxy API, seperti yang dijelaskan di bawah ini.

    Edge

    Untuk mengakses editor proxy API menggunakan UI Edge:

    1. Login ke apigee.com/edge.

      Pelanggan Edge for Private Cloud menggunakan http://ms-ip:9000 (lokal), dengan ms-ip adalah alamat IP atau nama DNS node Server Pengelolaan.

    2. Pilih Develop > API proxies di menu navigasi sebelah kiri.
    3. Pilih proxy API yang ingin Anda edit dalam daftar.

    Edge Klasik (Private Cloud)

    Untuk mengakses editor proxy API menggunakan UI Edge Klasik:

    1. Login ke http://ms-ip:9000, dengan ms-ip adalah alamat IP atau nama DNS node Server Pengelolaan.
    2. Pilih APIs > API proxies di menu navigasi atas.
    3. Pilih proxy API yang ingin Anda edit dalam daftar.
  2. Klik tab Mengembangkan.
  3. Di bagian Proxy Endpoints, pilih default.
  4. Di area kode:
    1. Hapus semua elemen <VirtualHost> untuk host virtual yang tidak didukung oleh proxy API.
    2. Tambahkan elemen <VirtualHost> baru dengan nama host virtual baru. Misalnya, jika host virtual baru bernama MyVirtualHost, tambahkan tag berikut:
      <HTTPProxyConnection>
  <BasePath>/v1/my/proxy/basepath</BasePath>
  <VirtualHost>default</VirtualHost>
  <VirtualHost>secure</VirtualHost>
  <VirtualHost>MyVirtualHost</VirtualHost>
</HTTPProxyConnection>
  5. Simpan proxy API. Jika proxy API telah di-deploy, menyimpannya akan men-deploy ulang dengan setelan baru.

Menetapkan URL dasar yang ditampilkan oleh UI Edge untuk proxy API

UI Edge menampilkan URL proxy API berdasarkan setelan di host virtual yang sesuai dengan tempat proxy di-deploy. Tampilan ini dapat menyertakan nomor port Router host virtual.

Pada umumnya, URL yang ditampilkan di UI Edge adalah URL yang benar untuk membuat permintaan eksternal ke proxy. Namun, untuk beberapa konfigurasi, URL yang ditampilkan salah. Misalnya, salah satu konfigurasi berikut dapat menyebabkan URL yang ditampilkan tidak sesuai dengan URL sebenarnya yang digunakan untuk membuat permintaan eksternal ke proxy:

  • Penghentian SSL terjadi di load balancer
  • Pemetaan port terjadi antara load balancer dan Router Apigee
  • Load balancer yang dikonfigurasi dengan penulisan ulang jalur

Edge mendukung atribut di host virtual yang disebut <BaseUrl> yang memungkinkan Anda mengganti URL yang ditampilkan oleh UI Edge. Berikut adalah contoh yang menampilkan objek host virtual dengan atribut <BaseUrl>. Dalam contoh ini, nilai "http://myCo.com" muncul di UI Edge:

<VirtualHost name="myTLSVHost">
  <HostAliases>
    <HostAlias>api.myCompany.com</HostAlias>
  </HostAliases>
  <BaseUrl>http://myCo.com</BaseUrl>
  <Port>443</Port>
  <SSLInfo>
    <Enabled>true</Enabled>
    <ClientAuthEnabled>false</ClientAuthEnabled>
    <KeyStore>ref://myTestKeystoreRef</KeyStore>
    <KeyAlias>myKeyAlias</KeyAlias>
  </SSLInfo>
</VirtualHost>

Perhatikan bahwa nilai <BaseUrl> harus menyertakan protokol (yaitu, "http://" atau "https://").

Jika <BaseUrl> tidak ditetapkan, URL default yang dirender oleh UI Edge akan muncul sebagai: "api.myCompany.com", sedangkan alias host yang sebenarnya adalah "http://myCo.com".