Skip to content

lablink_allocator_service.conf.structured_config

This module defines the database configuration structure for the LabLink Allocator Service.

Configuration for allocator service deployment.

This section is used by infrastructure deployment (OpenTofu) to specify which Docker image tag to use for the allocator service. The allocator service itself doesn't use this field, but it must be present in the schema to accept infrastructure configuration files.

Attributes:

Name Type Description
image_tag str

Docker image tag for the allocator service. Examples: "linux-amd64-latest-test", "linux-amd64-v1.2.3"

Configuration for the LabLink Allocator Service application.

Attributes:

Name Type Description
admin_user str

The username for the admin user.
admin_password str

The password for the admin user.
region str

The AWS region where the service is deployed.
admin_session_timeout_minutes int

Fixed duration cap for an admin's VNC troubleshooting session on an unassigned VM, after which the reservation is force-released.

Configuration for the LabLink Allocator Service. This class aggregates the database, machine, and application configurations.

Attributes:

Name Type Description
deployment_name str

Unique name for this deployment (e.g., sleap-lablink). Used as prefix for all AWS resource names. Must be 3-32 characters, lowercase kebab-case.
environment str

Deployment environment (dev, test, ci-test, prod).
provider str

VM provisioning provider. One of: - "aws": EC2 via OpenTofu (the existing behavior). - "manual": no automated provisioning — BYO clients register themselves via lablink client register.
db DatabaseConfig

The database configuration.
machine MachineConfig

The machine configuration.
app AppConfig

The application configuration.
dns DNSConfig

The DNS configuration.
eip EIPConfig

The EIP management configuration.
ssl SSLConfig

The SSL certificate configuration.
allocator AllocatorConfig

The allocator deployment configuration.
bucket_name str

The S3 bucket name for OpenTofu state.

Configuration for DNS and domain setup.

This class defines DNS settings for Route 53 hosted zones and records. DNS can be disabled entirely, or configured with external DNS providers.

Attributes:

Name Type Description
enabled bool

Whether DNS is enabled. If False, only IP addresses are used.
terraform_managed bool

Whether OpenTofu creates/destroys DNS records. - True: OpenTofu manages Route53 DNS records (creates and destroys) - False: External DNS management (CloudFlare, manual Route53, etc.)
domain str

Full domain name for the allocator (e.g., "lablink.sleap.ai", "test.lablink.sleap.ai"). Required when enabled=true. Supports sub-subdomains for environment separation.
zone_id str

Optional Route53 hosted zone ID. If provided, skips zone lookup. Use this when zone lookup finds the wrong zone (e.g., parent vs subdomain).

Database config. Only the password is deployment-configurable; everything else is fixed — see the DB_* constants above.

Configuration for Elastic IP management strategy.

Attributes:

Name Type Description
strategy str

EIP allocation strategy. Options: - "persistent": Reuse existing tagged EIP across deployments - "dynamic": Create new EIP for each deployment

Configuration for the machine used in the LabLink Allocator Service. This class defines the machine type, repository, image, AMI ID, and software to be used.

Attributes:

Name Type Description
machine_type str

The type of the machine to be used.
repository Optional[str]

The repository URL for the machine image.
image str

The Docker image ID to be used for the machine.
ami_id str

AMI for client VMs. Empty (the default) resolves AWS's Deep Learning Base AMI for the deployment's region, which carries Docker, the NVIDIA driver and nvidia-container-runtime — all three required, since the client's boot script installs none of them. Set this to use a specific image, such as LabLink's leaner published one where that exists.
software str

The software to be installed on the machine.

Configuration for the manual provider's client connectivity and participant-exposure strategy.

Attributes:

Name Type Description
connectivity str

How the browser reaches a manual client's KasmVNC desktop. Options: - "lan_direct": the browser opens a WebSocket straight to the client's LAN IP (default; requires client on the allocator's own LAN). - "mesh_overlay": the client joins a Tailscale tailnet; the allocator reaches it via that overlay and proxies the byte path through its own nginx, same as the AWS path. For clients that aren't on the allocator's LAN (e.g. a Run:AI-hosted workload).
overlay_tailnet str

The Tailscale tailnet's MagicDNS domain suffix (e.g. "example.ts.net"), used to resolve a registered client's overlay hostname, and/or the allocator's own Funnel-published hostname. Required when connectivity is "mesh_overlay" or participant_exposure is "tailscale_funnel"; ignored otherwise.
participant_exposure str

How participants (not clients) reach the allocator when it isn't on their LAN. Independent of connectivity — an admin can have lan_direct clients and still want off-LAN participants, or vice versa. Options: - "none": unchanged, LAN-only (default). - "tailscale_funnel": publish the allocator's HTTP port to the public internet via the tailnet named by overlay_tailnet, using the same tailscale sidecar connectivity="mesh_overlay" already provisions (reused, not a second sidecar). - "cloudflare_tunnel": publish the allocator at public_hostname via a Cloudflare Tunnel the admin created in their own Cloudflare account. Requires a domain whose nameservers point at Cloudflare (free-plan "full setup" — partial/CNAME setup is Business-tier, subdomain zones are Enterprise, so an institutional domain cannot be used). NOTE: unlike Funnel, which terminates TLS on this machine, Cloudflare decrypts all traffic at its edge — admin logins and participant desktop streams included.
public_hostname str

The public hostname participants open, e.g. "lab.smithlab.org". Required when participant_exposure is "cloudflare_tunnel"; ignored otherwise. Deliberately generic: any future exposure mode with an admin-chosen hostname reuses this field rather than adding a vendor-named one.

Configuration for SSL/TLS certificate management.

Attributes:

Name Type Description
provider str

SSL provider. Options: - "none": HTTP only, no SSL - "letsencrypt": Automatic SSL via Caddy + Let's Encrypt - "cloudflare": CloudFlare proxy handles SSL (requires terraform_managed=false) - "acm": AWS Certificate Manager (requires ALB, certificate_arn)
email str

Email address for Let's Encrypt notifications (required when provider="letsencrypt")
certificate_arn str

AWS ACM certificate ARN (required when provider="acm")

Configuration for startup behavior of the allocator service. Attributes: enabled (bool): Whether startup script execution is enabled. path (str): Path to the startup script to be executed. on_error (str): Behavior on startup script error. Options: - "continue": Log the error and continue startup. - "fail": Abort startup on error. max_attempts (int): Total attempts to run the startup script before giving up (1 = no retry). base_delay_seconds (int): Base delay for exponential backoff between retries; doubles each attempt, plus jitter. success_check (str): Optional shell command run after the script exits 0 to verify success beyond its own exit code. Empty string disables the check (success = exit code only).

True if value is an unfilled sentinel rather than a real credential.

Covers the schema default (MISSING) and the template's PLACEHOLDER_* literals. A placeholder reaching a running allocator means the substitution never happened — the deploy workflow is the only thing that performs it, so a local tofu apply (a documented path in lablink-template) bakes the literal straight into the instance.

Parameters:

Name Type Description Default
value str

The configured credential to inspect.

 required

Returns:

Type Description
bool

True when the value is a sentinel and must not be trusted.
Source code in packages/allocator/src/lablink_allocator_service/conf/structured_config.py 
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
def is_unresolved_secret(value: str) -> bool:
    """True if *value* is an unfilled sentinel rather than a real credential.

    Covers the schema default (``MISSING``) and the template's
    ``PLACEHOLDER_*`` literals. A placeholder reaching a *running* allocator
    means the substitution never happened — the deploy workflow is the only
    thing that performs it, so a local ``tofu apply`` (a documented path
    in lablink-template) bakes the literal straight into the instance.

    Args:
        value: The configured credential to inspect.

    Returns:
        True when the value is a sentinel and must not be trusted.
    """
    return value == MISSING_SECRET or value.startswith(PLACEHOLDER_SECRET_PREFIX)