# Menyiapkan nama domain khusus untuk titik akhir Gateway
<a name="gateway-custom-domains"></a>

Secara default, titik akhir Gateway disediakan dengan nama domain AWS-managed dalam format. `<gateway-id>.gateway.bedrock-agentcore.<region>.amazonaws.com` Untuk lingkungan produksi atau untuk menciptakan pengalaman yang lebih ramah pengguna, Anda mungkin ingin menggunakan nama domain khusus untuk titik akhir gateway Anda. Bagian ini memandu Anda melalui pengaturan nama domain khusus menggunakan Amazon CloudFront sebagai proxy terbalik.

## Prasyarat
<a name="gateway-custom-domains-prereq"></a>

Sebelum Anda mulai, pastikan Anda memiliki:
+ Titik akhir Gateway yang berfungsi
+ Delegasi DNS (jika domain Route 53 Anda harus dapat dijangkau secara publik)
+  AWS CDK diinstal dan dikonfigurasi (jika mengikuti pendekatan CDK)
+ Izin IAM yang sesuai untuk membuat dan mengelola CloudFront distribusi, zona yang dihosting Route 53, dan sertifikat ACM

## Ikhtisar solusi
<a name="gateway-custom-domains-overview"></a>

Solusinya melibatkan komponen berikut:
+  **Route 53 Hosted Zone**: Mengelola catatan DNS untuk domain kustom Anda
+  **Sertifikat ACM**: Menyediakan SSL/TLS enkripsi untuk domain kustom Anda
+  **CloudFront Distribusi**: Bertindak sebagai proxy terbalik, meneruskan permintaan dari domain kustom Anda ke titik akhir Gateway
+  **Route 53 A Record**: Memetakan domain kustom Anda ke CloudFront distribusi

Langkah-langkah berikut akan memandu Anda melalui pengaturan komponen ini menggunakan AWS CDK.

## Langkah-langkah implementasi
<a name="gateway-custom-domains-steps"></a>

### Langkah 1: Buat zona yang dihosting Route 53
<a name="gateway-custom-domains-hosted-zone"></a>

Pertama, buat zona yang dihosting Route 53 untuk domain kustom Anda:

```
import { RemovalPolicy } from 'aws-cdk-lib';
import { PublicHostedZone } from 'aws-cdk-lib/aws-route53';

const domainName = 'my.example.com';

const hostedZone = new PublicHostedZone(this, 'HostedZone', {
    zoneName: domainName,
});
this.hostedZone.applyRemovalPolicy(RemovalPolicy.RETAIN);
```

**catatan**  
Kami menerapkan kebijakan penghapusan `RETAIN` untuk mencegah penghapusan zona yang dihosting secara tidak sengaja selama pembaruan tumpukan atau penghapusan.

### Langkah 2: Buat DNS-validated sertifikat
<a name="gateway-custom-domains-certificate"></a>

Selanjutnya, buat SSL/TLS sertifikat untuk domain kustom Anda menggunakan AWS Certificate Manager (ACM) dengan validasi DNS:

```
import { RemovalPolicy } from 'aws-cdk-lib';
import { Certificate, CertificateValidation } from 'aws-cdk-lib/aws-certificatemanager';

const certificate = new Certificate(this, 'SSLCertificate', {
    domainName: domainName, // route53 hosted zone domain name from step 1
    validation: CertificateValidation.fromDns(hostedZone), // route53 hosted zone from step 1
});
this.certificate.applyRemovalPolicy(RemovalPolicy.RETAIN);
```

Validasi DNS secara otomatis membuat catatan validasi yang diperlukan di zona host Route 53 Anda.

### Langkah 3: Buat CloudFront distribusi
<a name="gateway-custom-domains-cloudfront"></a>

Buat CloudFront distribusi untuk bertindak sebagai proxy terbalik untuk titik akhir Gateway Anda:

```
import {
  AllowedMethods,
  CachePolicy,
  Distribution,
  OriginProtocolPolicy,
  ViewerProtocolPolicy
} from 'aws-cdk-lib/aws-cloudfront';
import { HttpOrigin } from 'aws-cdk-lib/aws-cloudfront-origins';

const bedrockAgentCoreGatewayHostName = '<mymcpserver>.gateway.bedrock-agentcore.<region>.amazonaws.com'
const bedrockAgentCoreGatewayPath = '/mcp' // can also be left undefined, depending on your requirement

const distribution = new Distribution(this, 'Distribution', {
    defaultBehavior: {
        origin: new HttpOrigin(bedrockAgentCoreGatewayHostName, {
            protocolPolicy: OriginProtocolPolicy.HTTPS_ONLY,
            originPath: bedrockAgentCoreGatewayPath,
        }),
        viewerProtocolPolicy: ViewerProtocolPolicy.HTTPS_ONLY,
        cachePolicy: CachePolicy.CACHING_DISABLED, // important since caching is enabled by default and hence is not suitable for a reverse proxy
        allowedMethods: AllowedMethods.ALLOW_ALL,
    },
    domainNames: [domainName], // route53 hosted zone domain name from step 1
    certificate: certificate, // ssl certificate for the route53 domain from step 2
});
```

**penting**  
Setel `cachePolicy: CachePolicy.CACHING_DISABLED` untuk memastikan bahwa respons tersebut CloudFront tidak menyimpan cache dari titik akhir Gateway Anda, yang penting untuk interaksi API dinamis.

Ganti `<mymcpserver>` dengan ID gateway Anda dan `<region>` dengan AWS Wilayah Anda (mis.,`us-east-1`).

### Langkah 4: Buat catatan Route 53 A
<a name="gateway-custom-domains-dns-record"></a>

Buat Route 53 Catatan yang mengarahkan domain kustom Anda ke CloudFront distribusi:

```
import { ARecord, RecordTarget } from 'aws-cdk-lib/aws-route53';
import { CloudFrontTarget } from 'aws-cdk-lib/aws-route53-targets';

const aRecord = new ARecord(this, 'AliasRecord', {
    zone: hostedZone, // route53 hosted zone from step 1
    recordName: domainName, // route53 hosted zone domain name from step 1
    target: RecordTarget.fromAlias(new CloudFrontTarget(distribution)), // cloudfront distribution from step 3
});
```

Ini membuat catatan alias yang memetakan domain kustom Anda ke CloudFront distribusi.

### Langkah 5: Menyebarkan infrastruktur Anda
<a name="gateway-custom-domains-deploy"></a>

Terapkan tumpukan CDK Anda untuk membuat sumber daya:

```
cdk deploy
```

Proses penyebaran mungkin memakan waktu, terutama untuk validasi sertifikat dan pembuatan CloudFront distribusi.

## Menguji domain kustom Anda
<a name="gateway-custom-domains-testing"></a>

Setelah menerapkan infrastruktur Anda, verifikasi bahwa domain kustom Anda dikonfigurasi dengan benar:

### Verifikasi resolusi DNS
<a name="gateway-custom-domains-testing-dns"></a>

Gunakan `dig` perintah untuk memverifikasi bahwa domain kustom Anda menyelesaikan distribusi: CloudFront 

```
dig my.example.com
```

Output harus menunjukkan bahwa domain Anda menyelesaikan ke CloudFront alamat IP.

### Verifikasi sertifikat SSL
<a name="gateway-custom-domains-testing-ssl"></a>

Gunakan `curl` untuk memverifikasi bahwa sertifikat SSL dikonfigurasi dengan benar:

```
curl -v https://my.example.com
```

Output harus menunjukkan jabat tangan SSL yang berhasil tanpa kesalahan sertifikat.

## Mengkonfigurasi klien MCP
<a name="gateway-custom-domains-client-config"></a>

Setelah domain kustom Anda disiapkan dan diverifikasi, Anda dapat mengonfigurasi klien MCP Anda untuk menggunakannya:

### Konfigurasi kursor
<a name="gateway-custom-domains-client-config-cursor"></a>

Untuk Kursor, perbarui file konfigurasi Anda:

```
{
  "mcpServers": {
    "my-mcp-server": {
      "url": "https://my.example.com"
    }
  }
}
```

### Klien MCP lainnya
<a name="gateway-custom-domains-client-config-other"></a>

Untuk klien MCP yang tidak mendukung HTTP yang dapat dirampingkan secara native:

```
{
  "mcpServers": {
    "my-mcp-server": {
      "command": "/path/to/uvx",
        "args": [
            "mcp-proxy",
            "--transport",
            "streamablehttp",
            "https://my.example.com"
        ]
    }
  }
}
```

## Pertimbangan tambahan
<a name="gateway-custom-domains-considerations"></a>

 **Implikasi biaya**   
Menggunakan CloudFront sebagai proxy terbalik menimbulkan biaya tambahan untuk transfer data dan penanganan permintaan. Tinjau model CloudFront penetapan harga untuk memahami implikasi biaya untuk kasus penggunaan spesifik Anda.

 **Pertimbangan keamanan**   
Pertimbangkan untuk menerapkan langkah-langkah keamanan tambahan seperti:  
+ Aturan WAF untuk melindungi titik akhir Anda dari eksploitasi web umum
+ Geo-restrictions untuk membatasi akses ke wilayah geografis tertentu
+ Header khusus atau penandatanganan permintaan untuk menambahkan lapisan otentikasi tambahan

 **Pencatatan dan pemantauan**   
Aktifkan log CloudFront akses dan konfigurasikan CloudWatch alarm untuk memantau kesehatan dan kinerja pengaturan domain kustom Anda.

 **Perpanjangan sertifikat**   
Sertifikat ACM yang dikeluarkan melalui validasi DNS diperpanjang secara otomatis selama catatan DNS tetap ada. Pastikan Anda tidak menghapus catatan validasi.

 **Titik akhir sumber daya yang dilindungi OAuth dengan domain khusus**   
Secara default, `/.well-known/oauth-protected-resource` titik akhir mengembalikan URL sumber daya yang berisi domain gateway, bukan domain kustom Anda. Hal ini dapat menyebabkan klien OAuth gagal otentikasi saat menggunakan domain khusus.  
Untuk mengatasi masalah ini, Anda dapat menerapkan fungsi Lambda @Edge yang mencegat respons penemuan OAuth dan menghasilkan respons baru dengan URL domain kustom yang benar. Berikut pendekatannya:  
+  **Gunakan Lambda @Edge dengan tipe acara ORIGIN\_RESPONSE: Buat fungsi yang memicu respons** asal untuk mencegat respons titik akhir sumber daya yang dilindungi OAuth.
+  **Hasilkan respons baru**: Lambda @Edge tidak dapat membaca badan respons asal, jadi alih-alih memodifikasi respons yang ada, hasilkan respons JSON yang sama sekali baru dengan domain khusus.
+  **Kaitkan dengan CloudFront perilaku**: Konfigurasikan fungsi Lambda @Edge untuk memicu secara khusus untuk pola `/.well-known/oauth-protected-resource` jalur.

  Setelah menerapkan solusi ini, titik akhir sumber daya yang dilindungi OAuth akan mengembalikan domain kustom yang benar:

  ```
  curl https://my-custom-domain.com/.well-known/oauth-protected-resource
  {
    "authorization_servers": ["https://my-org.okta.com/oauth2/default"],
    "resource": "https://my-custom-domain.com/mcp"
  }
  ```
**catatan**  
Sementara Lambda @Edge memberikan solusi untuk masalah ini, menerapkan domain khusus untuk AgentCore Gateway tanpa dukungan bawaan memerlukan kompleksitas tambahan yang mungkin tidak optimal untuk semua pelanggan. Pertimbangkan pendekatan ini sebagai solusi hingga dukungan asli untuk penemuan OAuth dengan domain khusus tersedia.

## Pemecahan masalah
<a name="gateway-custom-domains-troubleshooting"></a>

 **Masalah resolusi DNS**   
Jika domain kustom Anda tidak diselesaikan dengan benar:  
+ Verifikasi bahwa catatan A telah dikonfigurasi dengan benar di zona yang dihosting Route 53
+ Periksa apakah server nama domain Anda disetel dengan benar di registrar domain Anda
+ Berikan waktu untuk propagasi DNS (hingga 48 jam dalam beberapa kasus)

 **Masalah sertifikat SSL**   
Jika Anda mengalami kesalahan sertifikat SSL:  
+ Verifikasi bahwa sertifikat diterbitkan dan aktif di konsol ACM
+ Periksa apakah sertifikat terkait dengan CloudFront distribusi Anda dengan benar
+ Pastikan sertifikat mencakup nama domain yang tepat yang Anda gunakan

 **Masalah konektivitas gateway**   
Jika domain kustom Anda tidak terhubung ke gateway Anda:  
+ Verifikasi bahwa domain asal dan jalur dalam CloudFront distribusi Anda sudah benar
+ Periksa apakah titik akhir gateway Anda dapat diakses secara langsung
+ Tinjau log CloudFront distribusi untuk kesalahan apa pun

## Kesimpulan
<a name="gateway-custom-domains-conclusion"></a>

Menyiapkan nama domain khusus untuk titik akhir Gateway meningkatkan tampilan profesional aplikasi Anda dan memberikan fleksibilitas dalam mengelola titik akhir API Anda. Dengan mengikuti langkah-langkah yang diuraikan dalam panduan ini, Anda dapat membuat konfigurasi domain kustom yang aman dan andal menggunakan CloudFront sebagai proxy terbalik.

Untuk informasi selengkapnya tentang fitur dan kemampuan Gateway, lihat [Amazon Bedrock AgentCore Gateway: Menghubungkan alat dan sumber daya lainnya dengan aman ke Gateway Anda](gateway.md).