Chapter 4. Introducing the Kubernetes Gateway API for custom image migration

Procedure

1. Implement required health check endpoints. The Gateway API requires a specific endpoint to verify workbench pod availability.

   • Configure the application to return an HTTP 200 status at: GET /{NB_PREFIX}/api.

2. Configure culler support:

   To support automatic idleness culling, the workbench must expose kernels and terminal status as JSON arrays. Ensure the application implements these endpoints:

   • GET /{NB_PREFIX}/api/kernels
   • GET /{NB_PREFIX}/api/terminals

3. Use relative URLs throughout your application.

   Note

   Avoid hardcoded absolute paths such as /static/app.js or /api/data. These paths bypass the {NB_PREFIX} and cannot be routed by the Gateway. Instead, use relative paths like static/app.js or api/data, which resolve correctly within the prefixed context.

   If your application contains hardcoded absolute URLs that cannot be modified, you must use NGINX as a reverse proxy to handle path translation. See Migrating your custom workbench images to the Kubernetes Gateway API using NGINX for configuration details.

4. Configure your application’s base path.

   If your framework supports a configurable base path or root path, set it to the value of the NB_PREFIX environment variable. This ensures that generated URLs, redirects, and static asset references include the correct prefix.

   For example, in Python frameworks you can set root_path (FastAPI) or APPLICATION_ROOT (Flask). In JavaScript frameworks, configure the base URL or public path setting accordingly.

Procedure

1. Update redirects to preserve NB_PREFIX. All redirects must include ${NB_PREFIX} to keep requests within the Gateway route:

   # ❌ BAD - Strips prefix
   location = ${NB_PREFIX} {
       return 302 $custom_scheme://$http_host/myapp/;
   }
   
   # ✅ GOOD - Preserves prefix
   location ${NB_PREFIX} {
       return 302 $custom_scheme://$http_host${NB_PREFIX}/myapp/;
   }

   Copy to Clipboard Toggle word wrap

2. Add a prefix-aware proxy location that matches the full prefixed path, and strips the prefix before proxying.

   location ${NB_PREFIX}/myapp/ {
       # Strip the prefix before proxying to backend
       rewrite ^${NB_PREFIX}/myapp/(.*)$ /$1 break;
   
       # Proxy to your application
       proxy_pass http://localhost:8080/;
       proxy_http_version 1.1;
   
       # Essential for WebSocket support
       proxy_set_header Upgrade $http_upgrade;
       proxy_set_header Connection $connection_upgrade;
   
       # Long timeout for interactive sessions
       proxy_read_timeout 20d;
   
       # Pass through important headers
       proxy_set_header Host $http_host;
       proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
       proxy_set_header X-Forwarded-Proto $custom_scheme;
   }

   Copy to Clipboard Toggle word wrap

3. Update health check endpoints to preserve the prefix:

   # Health check endpoint
   location = ${NB_PREFIX}/api {
       return 302 ${NB_PREFIX}/myapp/healthz/;
       access_log off;
   }

   Copy to Clipboard Toggle word wrap