Tasks
Virtual Worker Site Register
Registers a public URL for a web server running on a Virtual Worker. Supports updating the target worker or port and protecting the site with Basic Auth.
Use virtual_worker_site_register after starting a web server on a Kubernetes Virtual Worker. The task routes requests for the site's hostname to the selected worker and port.
See Virtual Worker Send Commands for running commands on the worker and Virtual Worker Warmup for starting one.
Basic usage
Start your application on the worker first. It must listen on 0.0.0.0 at the chosen port so it can receive traffic from outside the container. Keep the server process running after the command that starts it finishes.
This example registers an application already listening on port 5173 on website-worker:
The base domain is currently always stubber.site, so the hostname is <name>.stubber.site. This example registers https://my-cool-site.stubber.site. Use the returned payload.url for the site's address.
Parameters
name string required
The site name, which becomes the first label of its hostname. Names are converted to lowercase and must be between 1 and 63 characters, start with a letter, contain only letters, digits, or hyphens, and end with a letter or digit.
Registering the same name again in the same organization and cluster updates its worker and port. Choose a name that does not conflict with another site's hostname under stubber.site.
port number required
The HTTP port your application listens on inside the worker. Must be an integer between 1 and 65535. Supply a number, such as 5173, rather than a string.
runtime Object optional
Selects the cluster and existing worker. Use the same runtime as the task that started your application.
Show child attributes
cluster Object optional
Show child attributes
name string optional
The cluster containing the worker.
Default: stubber_k8s
worker Object optional
Show child attributes
name string optional
The existing worker to route traffic to. Worker names are converted to lowercase and may contain letters, digits, and hyphens, with a letter or digit at either end.
Default: the current stub's stubref, converted to lowercase.
Registration requires a worker in the same organization whose phase is Running or Pending. It does not start a worker, run the application, or apply worker image or resource settings. A successful registration does not confirm that the application is ready to serve requests.
basic_auth Object | null optional
Controls HTTP Basic Auth for the site:
- Supply an object with
usernameandpasswordto enable protection or replace the credentials. - Omit
basic_authto preserve the existing authentication settings. A new site is public by default. - Supply
nullto remove protection and make the site public.
Show child attributes
username string required
Between 1 and 128 characters. Supports letters, digits, underscores, dots, @, and hyphens.
password string required
A non-empty password of at most 72 UTF-8 bytes. The server stores a bcrypt hash and does not return the credentials in task results.
Protecting a site
Include basic_auth when registering or updating the site:
To remove authentication, run the same registration with "basic_auth": null. The name and port parameters are still required when changing authentication.
Returns
Example result:
registered indicates that both the routing Service and Ingress exist. basic_auth indicates whether the site's authentication middleware is attached. Neither field checks application health.
Updating and removing sites
To move a site to another worker or port, register the same name again with the new runtime.cluster.worker.name and port. The hostname stays the same. Omitting basic_auth preserves its credentials.
Use virtual_worker_site_list to list all site registrations in the current organization and selected cluster:
The result's payload.sites is an array of site objects with the same fields as the registration payload. Supply params.runtime.cluster.name when targeting a different cluster. Listing does not require a running worker and may include incomplete registrations with registered: false.
Use virtual_worker_site_unregister to remove a route and its authentication resources:
Supply params.runtime.cluster.name if the site is on a different cluster. The result contains success: true, the message Site unregistered., and payload with the site name and cluster. Repeated removal succeeds even if the registration is already gone. Unregistering leaves the worker and application running.
Worker lifetime
Site registration does not extend the worker's idle timeout. Site requests and registration tasks do not count as command tasks received by the worker. Configure an appropriate runtime.cluster.worker.worker_spec.idle_timeout_minutes when starting the worker.
When the router cleans up an idle or failed worker, it removes the sites and authentication resources still attached to that worker. If a worker is deleted separately, its registration may remain listed, but the application will be unavailable. Register the site against a running replacement worker or unregister it to remove the route.