Haijun Platform Docs
EN

Note: MCP tunnels (terowongan MCP) sedang dalam pratinjau riset. Minta akses untuk mencobanya.

Helm chart Juglow menginstal tunnel stack sebagai satu Deployment dan melampirkannya ke tunnel Anda: tunnel yang dibuat oleh setup hook chart untuk Anda, atau tunnel yang sudah ada yang Anda buat di Console.

Sebelum Anda memulai

Anda memerlukan:

  • Sebuah tunnel. Dengan akses programatik, setup hook chart membuatkannya untuk Anda ketika Anda tidak menyediakan ID tunnel; untuk melampirkan ke tunnel yang sudah ada, buat tunnel tersebut di Console dan catat ID tunnel-nya (tnl_...). Penyediaan manual selalu dimulai dari tunnel yang dibuat di Console; Anda juga memerlukan token tunnel dan domain tunnel-nya.
  • Cara bagi chart untuk melakukan autentikasi ke Tunnels API.
  • Akses programatik (direkomendasikan). Komponen setup melakukan autentikasi melalui Workload Identity Federation, mengambil token tunnel, menghasilkan CA, mendaftarkannya ke Juglow, dan menyimpan semuanya dalam sebuah Secret. Anda memerlukan federation rule dengan cakupan workspace:manage_tunnels.
  • Manual. Lewati akses programatik. Anda akan mendapatkan token tunnel dari Console, menghasilkan CA dan sertifikat server sendiri, mendaftarkan CA di Console, dan menyediakan kredensial ke cluster sebagai Secret.
  • Sebuah cluster Kubernetes yang dapat Anda deploy menggunakan helm dan kubectl. Tab Tanpa akses programatik juga menggunakan openssl (1.1.1 atau lebih baru).
  • Satu atau lebih server MCP yang berjalan dan dapat dijangkau dari cluster pada alamat yang akan Anda konfigurasikan di bawah gateway.config.routes. Jika Anda belum memilikinya, gunakan server contoh.

Opsional: Gunakan server MCP contoh

Jika Anda tidak memiliki server MCP yang tersedia untuk pengujian, gunakan server minimal ini:

bash
kubectl create namespace mcp-tunnel --dry-run=client -o yaml | kubectl apply -f -
kubectl -n mcp-tunnel apply -f - <<'EOF'
apiVersion: v1
kind: ConfigMap
metadata:
  name: hello-mcp-src
data:
  hello_server.py: |
    from mcp.server.fastmcp import FastMCP

    mcp = FastMCP("hello-server", host="0.0.0.0", port=9000)

    @mcp.tool()
    def hello(name: str = "world") -> str:
        """Say hello to someone."""
        return f"Hello, {name}!"

    if __name__ == "__main__":
        mcp.run(transport="streamable-http")
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: hello-mcp
spec:
  replicas: 1
  selector:
    matchLabels: { app: hello-mcp }
  template:
    metadata:
      labels: { app: hello-mcp }
    spec:
      containers:
        - name: hello-mcp
          image: python:3.13-slim
          command: ["sh", "-c", "pip install --quiet mcp && python /app/hello_server.py"]
          volumeMounts:
            - { name: src, mountPath: /app }
          ports:
            - { containerPort: 9000 }
      volumes:
        - name: src
          configMap: { name: hello-mcp-src }
---
apiVersion: v1
kind: Service
metadata:
  name: hello-mcp
spec:
  selector: { app: hello-mcp }
  ports:
    - { port: 9000, targetPort: 9000 }
EOF

Langkah-langkah Instal berikut ini mencatat di mana menambahkan route yang sesuai.

Instal

Dengan akses programatik

Komponen setup menukarkan token ServiceAccount terproyeksi milik cluster melalui federation rule Anda, mengambil token tunnel, menghasilkan CA dan sertifikat server, serta mendaftarkan CA ke Juglow. Sebuah CronJob harian memperbarui sertifikat server sesuai kebutuhan, sehingga Anda tidak perlu menangani secret apa pun secara manual.

  1. Siapkan Workload Identity Federation untuk cluster

Ikuti Gunakan WIF dengan Kubernetes untuk mendaftarkan OIDC issuer cluster Anda dan membuat federation rule. Komponen setup berjalan di bawah ServiceAccount-nya sendiri di namespace release; nama persisnya mengikuti konvensi fullname Helm, jadi untuk nama release selain mcp-tunnel, jalankan helm template ... | grep -A2 'kind: ServiceAccount' untuk mengonfirmasinya sebelum membuat rule. Sisa panduan ini mengasumsikan nama release mcp-tunnel di namespace mcp-tunnel, di mana ServiceAccount-nya adalah mcp-tunnel-setup.

FieldNilai
Subjectsystem:serviceaccount:mcp-tunnel:mcp-tunnel-setup
Audienceapi.juglow.com (default chart; tanpa skema)
Scopeworkspace:manage_tunnels

Note: Audience default chart adalah api.juglow.com tanpa skema, tetapi formulir federation rule di Console menyarankan https://haijun.my.id/. Keduanya harus cocok byte demi byte atau autentikasi akan gagal. Atur audience rule ke api.juglow.com, atau atur api.wif.audience di values.yaml ke https://haijun.my.id/.

Jika tunnel berada di workspace selain workspace default organisasi, tambahkan juga service account milik rule sebagai anggota workspace tersebut di bawah Settings > Workspaces (Tunnels API melakukan otorisasi berdasarkan keanggotaan workspace service account).

Catat ID rule (fdrl_...); Anda akan mengaturnya sebagai api.wif.federationRuleId.

Note: CronJob pembaruan sertifikat harian menggunakan ServiceAccount terpisah (juga diturunkan dari fullname Helm) tetapi tidak memanggil Tunnels API; CronJob ini memperbarui sertifikat secara lokal dan hanya memerlukan RBAC Kubernetes, yang diberikan oleh chart. Federation rule tidak perlu mencakupnya.

  1. Ambil nilai default
bash
helm show values \
  oci://us-docker.pkg.dev/juglow-public-registry/charts/mcp-tunnel \
  --version 2.0.2 > values.yaml
  1. Konfigurasikan pelampiran tunnel dan route

Edit values.yaml dan atur kunci api.wif.* dengan ID federation rule dan ID organisasi, ditambah entri routes untuk setiap server MCP upstream:

yaml
api:
  wif:
    federationRuleId: "fdrl_..."
    organizationId: "00000000-0000-0000-0000-000000000000"
    # Set when the tunnel is in a non-default workspace and the
    # rule's service account is a member of that workspace.
    # workspaceId: "wrkspc_..."

tunnel:
  # Leave empty to have the setup hook create a tunnel during install.
  # Set to attach to an existing tunnel from the Console.
  id: ""
  # Increment to rotate the tunnel token on the next upgrade.
  # See the "Rotate the tunnel token" section.
  tokenVersion: "1"

gateway:
  config:
    routes:
      docs: http://docs-mcp.internal:8080
      search: http://search-mcp.internal:8080

Dengan route ini, Haijun menjangkau server di docs. dan search.. Beberapa distribusi Kubernetes terkelola mengalokasikan Service CIDR di luar rentang privat standar; jika route Anda menargetkan Service di dalam cluster, tambahkan gateway.config.upstream.allowed_ips di sini sesuai Validasi IP upstream.

Note: Jika Anda menggunakan server MCP contoh, atur routes ke echo: http://hello-mcp:9000 sebagai gantinya.

  1. Tinjau manifest yang dirender

Render chart dan tinjau outputnya sesuai praktik pemeriksaan organisasi Anda:

bash
helm template mcp-tunnel \
  oci://us-docker.pkg.dev/juglow-public-registry/charts/mcp-tunnel \
  --version 2.0.2 \
  -n mcp-tunnel \
  -f values.yaml > rendered.yaml
  1. Instal
bash
helm install mcp-tunnel \
  oci://us-docker.pkg.dev/juglow-public-registry/charts/mcp-tunnel \
  --version 2.0.2 \
  --namespace mcp-tunnel --create-namespace \
  -f values.yaml

Komponen setup berjalan sebagai Job pre-install hook Helm, sehingga helm install memblokir hingga selesai. Jika berhasil, Helm menghapus Job secara otomatis. Jika helm install gagal dengan error hook, lihat Kegagalan autentikasi komponen setup.

Ketika tunnel.id kosong, komponen setup membuat tunnel di workspace yang ditargetkan federation rule Anda (workspace default organisasi kecuali Anda mengatur api.wif.workspaceId) dan menyimpan ID serta domainnya di Secret mcp-tunnel. Temukan domain yang Anda perlukan untuk verifikasi di halaman detail tunnel di Console di bawah Manage > MCP tunnels, atau baca dari Secret:

bash
kubectl -n mcp-tunnel get secret mcp-tunnel \
  -o jsonpath='{.data.tunnel-domain}' | base64 -d

Menjalankan ulang komponen setup (selama upgrade atau rotasi token) menggunakan kembali ID tunnel yang tersimpan di Secret ini; komponen ini tidak pernah membuat tunnel kedua.

Warning: Nilai api.wif.* adalah pengenal, bukan secret, sehingga menyimpannya di Secret riwayat release Helm bukanlah risiko. Data sensitif yang tersimpan adalah Secret mcp-tunnel yang dibuat komponen setup, yang menyimpan token tunnel dan private key TLS. Terapkan praktik standar organisasi Anda untuk melindungi Kubernetes Secret pada namespace ini.

Tanpa akses programatik

Dalam mode ini (setup.enabled: false) chart tidak melakukan panggilan API apa pun; komponen setup tidak berjalan dan tidak ada CronJob cert-renew. Gunakan jalur ini jika Anda lebih memilih untuk tidak menyiapkan Workload Identity Federation.

  1. Dapatkan token dan domain tunnel

Buat tunnel dan dapatkan token tunnel dari Console.

Note: Catat domain tunnel dari halaman detail. Anda akan mengaturnya sebagai gateway.config.tunnel_domain.

  1. Hasilkan CA dan sertifikat server

Proxy mendengarkan pada WebSocket biasa, dengan inner TLS yang dibawa di dalam stream tersebut menggunakan sertifikat yang Anda hasilkan di sini. SAN sertifikat server harus menyertakan *. sesuai persyaratan sertifikat.

bash
export TUNNEL_DOMAIN=YOUR_TUNNEL_DOMAIN_HERE
mkdir -p mcp-tunnel/data
cd mcp-tunnel

# CA yang ditandatangani sendiri. Ekstensi eksplisit agar memenuhi persyaratan
# sertifikat terlepas dari default openssl.cnf distro.
openssl req -x509 -newkey rsa:2048 -nodes \
  -keyout data/ca.key -out data/ca.crt \
  -days 3650 -subj "/CN=mcp-tunnel-ca" \
  -addext "basicConstraints=critical,CA:TRUE" \
  -addext "keyUsage=critical,keyCertSign,cRLSign" \
  -addext "subjectKeyIdentifier=hash"

# File ekstensi untuk sertifikat server. Menggunakan -extfile (alih-alih
# -copy_extensions, yang hanya untuk OpenSSL 3.0+) agar tetap berfungsi di
# OpenSSL 1.1.x.
cat > data/tls.ext <<EOF
subjectAltName = DNS:${TUNNEL_DOMAIN},DNS:*.${TUNNEL_DOMAIN}
authorityKeyIdentifier = keyid,issuer
extendedKeyUsage = serverAuth
EOF

# Sertifikat server yang ditandatangani oleh CA
openssl req -newkey rsa:2048 -nodes \
  -keyout data/tls.key -out /tmp/server.csr \
  -subj "/CN=${TUNNEL_DOMAIN}"
openssl x509 -req -in /tmp/server.csr \
  -CA data/ca.crt -CAkey data/ca.key -CAcreateserial \
  -out data/tls.crt -days 90 \
  -extfile data/tls.ext

Daftarkan data/ca.crt di Console. Simpan data/ca.key di tempat yang tahan lama dan aman; Anda akan memerlukannya untuk menandatangani sertifikat server baru pada saat pembaruan.

  1. Buat dua Secret

Chart membaca kunci tertentu; nama Secret dapat dikonfigurasi tetapi kuncinya tidak. Perintah pembuatan namespace berikut tidak berpengaruh apa pun jika namespace sudah ada (misalnya, dari langkah server MCP contoh).

bash
kubectl create namespace mcp-tunnel --dry-run=client -o yaml | kubectl apply -f -
kubectl -n mcp-tunnel create secret generic mcp-tunnel-token \
  --from-literal=tunnel-token='eyJ...'
kubectl -n mcp-tunnel create secret generic mcp-tunnel-cert \
  --from-file=tls.crt=data/tls.crt \
  --from-file=tls.key=data/tls.key
  1. Ambil nilai default
bash
helm show values \
  oci://us-docker.pkg.dev/juglow-public-registry/charts/mcp-tunnel \
  --version 2.0.2 > values.yaml
  1. Konfigurasikan nilai untuk penyediaan manual

Edit values.yaml dan atur kunci berikut:

yaml
setup:
  enabled: false

external:
  tunnelTokenSecretName: mcp-tunnel-token   # must contain key: tunnel-token
  serverCertSecretName: mcp-tunnel-cert     # must contain keys: tls.crt, tls.key

gateway:
  config:
    # Required when setup.enabled is false. Replace the placeholder with
    # the $TUNNEL_DOMAIN value you exported earlier. When setup.enabled
    # is true the chart injects this from the Secret as a -tunnel-domain
    # flag instead.
    tunnel_domain: YOUR_TUNNEL_DOMAIN_HERE
    routes:
      docs: http://docs-mcp.internal:8080
      search: http://search-mcp.internal:8080

Beberapa distribusi Kubernetes terkelola mengalokasikan Service CIDR di luar rentang privat standar; jika route Anda menargetkan Service di dalam cluster, tambahkan gateway.config.upstream.allowed_ips di sini sesuai Validasi IP upstream.

Note: Jika Anda menggunakan server MCP contoh, atur routes ke echo: http://hello-mcp:9000 sebagai gantinya.

  1. Tinjau manifest yang dirender
bash
helm template mcp-tunnel \
  oci://us-docker.pkg.dev/juglow-public-registry/charts/mcp-tunnel \
  --version 2.0.2 \
  -n mcp-tunnel \
  -f values.yaml > rendered.yaml
  1. Instal
bash
helm install mcp-tunnel \
  oci://us-docker.pkg.dev/juglow-public-registry/charts/mcp-tunnel \
  --version 2.0.2 \
  --namespace mcp-tunnel --create-namespace \
  -f values.yaml

Verifikasi deployment

Verifikasi secara end-to-end dari sisi Juglow: gunakan https://./ dalam sesi Managed Agent atau permintaan Messages API, di mana adalah kunci dari gateway.config.routes dan adalah path apa pun yang dilayani server MCP upstream. Dengan server MCP contoh, itu adalah https://echo./mcp. Lihat Gunakan server MCP yang di-tunnel untuk bentuk permintaannya.

Jika gagal, periksa log pod (kubectl -n mcp-tunnel logs deploy/mcp-tunnel -c mcp-proxy dan -c cloudflared) dan lihat Pemecahan masalah.

Konfigurasi opsional

Batasi egress dengan NetworkPolicy

Ingress ke pod proxy ditolak secara default (networkPolicy.ingress.enabled: true). Untuk membatasi egress pod lebih lanjut, atur networkPolicy.egress.enabled: true dan isi networkPolicy.egress.mcpServers dengan pod label selector atau rentang CIDR yang mencakup server MCP upstream Anda. Egress dari cloudflared ke tunnel edge diizinkan secara terpisah melalui networkPolicy.egress.cloudflaredEgressCIDRs.

Sesuaikan proxy

Field di bawah gateway.config.* diteruskan ke file konfigurasi proxy. Penyesuaian umum mencakup upstream.allowed_ips, log_level, dan upstream.tls. Lihat referensi konfigurasi proxy untuk daftar field selengkapnya. Chart selalu mengatur listen_addr, tls.cert_file, dan tls.key_file; mengaturnya di gateway.config tidak berpengaruh.

Sediakan token OIDC Anda sendiri

Secara default chart memproyeksikan token ServiceAccount Kubernetes untuk komponen setup. Untuk menggunakan token dari penyedia identitas lain (seperti SPIFFE, Vault, atau sidecar cloud-SDK), mount token tersebut dengan setup.extraVolumes dan setup.extraVolumeMounts. Kemudian arahkan api.wif.tokenFile ke path mount tersebut. Chart mengatur JUGLOW_IDENTITY_TOKEN_FILE ke path itu, dan komponen setup membaca token dari sana.

Upgrade

Selalu berikan --version ke helm upgrade agar Anda tidak menarik chart yang lebih baru secara tidak terduga.

Upgrade dari chart 1.x

Chart 2.0.0 memindahkan ID tunnel dari api.wif.tunnelId ke tunnel.id. Sebelum melakukan upgrade, edit values.yaml Anda: pindahkan nilai tnl_... ke tunnel.id dan hapus api.wif.tunnelId. Membiarkan tunnel.id tidak diatur aman (komponen setup menggunakan kembali ID tunnel yang sudah tersimpan di Secret mcp-tunnel saat dijalankan ulang), tetapi pemindahan eksplisit menjaga values.yaml Anda tetap akurat. Perbarui juga cakupan federation rule Anda dari org:manage_tunnels ke workspace:manage_tunnels di Console.

Ubah konfigurasi

Untuk perubahan rutin seperti route, jumlah replika, atau NetworkPolicy:

bash
helm upgrade mcp-tunnel \
  oci://us-docker.pkg.dev/juglow-public-registry/charts/mcp-tunnel \
  --version 2.0.2 \
  -n mcp-tunnel \
  -f values.yaml

Warning: Pertahankan values.yaml yang lengkap daripada mengandalkan --reuse-values. Perilaku deep-merge Helm dapat secara diam-diam gagal menghapus route yang telah dihapus.

Rotasi token tunnel

Dengan akses programatik, naikkan tunnel.tokenVersion di values.yaml dan lakukan upgrade dengan --set setup.force=true. Komponen setup hanya berjalan ulang pada upgrade ketika dipaksa:

bash
helm upgrade mcp-tunnel \
  oci://us-docker.pkg.dev/juglow-public-registry/charts/mcp-tunnel \
  --version 2.0.2 \
  -n mcp-tunnel \
  -f values.yaml \
  --set setup.force=true

Komponen setup melakukan autentikasi dengan Workload Identity Federation; tidak ada token API yang perlu dicabut.

Tanpa akses programatik, klik Rotate token di halaman detail tunnel di Console, lalu perbarui Secret mcp-tunnel-token:

bash
kubectl -n mcp-tunnel create secret generic mcp-tunnel-token \
  --from-literal=tunnel-token='eyJ...' --dry-run=client -o yaml | kubectl apply -f -
kubectl -n mcp-tunnel rollout restart deploy/mcp-tunnel

Warning: Mengklik Rotate token langsung membatalkan token saat ini. Hingga Secret diperbarui dan rollout selesai, pod apa pun yang restart dengan token lama (eviction, node drain, OOM) tidak dapat terhubung kembali. Perbarui Secret segera setelah rotasi; untuk persyaratan ketersediaan yang lebih ketat, gunakan akses programatik agar chart menangani rotasi secara atomik.

Pembaruan sertifikat

Chart menyediakan otomatisasi, tetapi Anda tetap bertanggung jawab untuk memantau masa berlaku dan memastikan pembaruan selesai.

Dengan akses programatik, pembaruan sertifikat berlangsung otomatis. Chart men-deploy CronJob (dinamai berdasarkan fullname Helm, dengan akhiran -cert-renew) yang menjalankan setup renew-cert setiap hari (pada serverCert.cronSchedule, default 0 0 * * * UTC). Job ini tidak melakukan apa pun kecuali sertifikat berada dalam rentang serverCert.renewBefore dari masa kedaluwarsa (default 30 hari). Pembaruan bersifat lokal: job menandatangani sertifikat baru dengan CA yang sudah tersimpan di Secret, tidak melakukan panggilan API, dan hanya memerlukan RBAC Kubernetes yang diberikan chart. Proxy melakukan hot-reload sertifikat dari mount Secret, sehingga tidak diperlukan restart Deployment.

Tanpa akses programatik tidak ada CronJob. Dari dalam direktori mcp-tunnel/ yang Anda simpan setelah instalasi, tandatangani sertifikat server baru dengan CA yang sudah ada (jangan menghasilkan ulang CA):

bash
export TUNNEL_DOMAIN=YOUR_TUNNEL_DOMAIN_HERE
openssl req -new -key data/tls.key -out /tmp/server.csr \
  -subj "/CN=${TUNNEL_DOMAIN}"
openssl x509 -req -in /tmp/server.csr \
  -CA data/ca.crt -CAkey data/ca.key -CAcreateserial \
  -out data/tls.crt -days 90 -extfile data/tls.ext

kubectl -n mcp-tunnel create secret generic mcp-tunnel-cert \
  --from-file=tls.crt=data/tls.crt --from-file=tls.key=data/tls.key \
  --dry-run=client -o yaml | kubectl apply -f -

Proxy melakukan hot-reload sertifikat dari mount Secret.

Langkah selanjutnya

Lampirkan server MCP upstream ke Managed Agent atau Messages API.

Panduan hardening, rotasi kredensial, dan respons terhadap pelanggaran.

Diagnosis masalah konektivitas, TLS, dan routing.

On this page
Sebelum Anda memulaiOpsional: Gunakan server MCP contohInstalVerifikasi deploymentKonfigurasi opsionalBatasi egress dengan NetworkPolicySesuaikan proxySediakan token OIDC Anda sendiriUpgradeUpgrade dari chart 1.xUbah konfigurasiRotasi token tunnelPembaruan sertifikatLangkah selanjutnya