FiveM + txAdmin — Integration Plan¶

Overview¶

FiveM is the second service kind. The image used is spritsail/fivem (bundles txAdmin). txAdmin is exposed via a Traefik IngressRoute.

Old Architecture Reference¶

Resource	Detail
Docker image	`spritsail/fivem`
Ports	30120 TCP + 30120 UDP
PVC mounts	`/config` (sub_path: config), `/txData` (sub_path: txData)
txAdmin port	40120 (inside container)
txAdmin access	Traefik IngressRoute → `{id}.zone.zaroz.cloud` (HTTPS, wildcard TLS)
Terminal	terminal-bridge init container + command override, port 25 TCP
Sidecar	separate Deployment + ClusterIP Service, gRPC port 4646

New Architecture¶

Provisions per FiveM Order¶

local_id	Kind	Primary	Hidden	Purpose
`data-pvc`	PVC	No	No	Single PVC for all data
`server`	Deployment	Yes	No	FiveM + txAdmin process
`sidecar`	Deployment	No	Yes	gRPC file access
`sidecar-svc`	ClusterIpService	No	Yes	Internal DNS for sidecar
`server-svc`	ClusterIpService	No	Yes	Internal routing (game + terminal)
`txadmin-svc`	ClusterIpService	No	Yes	Internal routing for txAdmin
`txadmin-ingress`	IngressRoute	No	No	HTTPS access to txAdmin panel
`fivem-external`	ExternalService	No	No	Player-facing game port (TCP)
`fivem-external-udp`	ExternalService	No	No	Player-facing game port (UDP)

PVC Sub-Paths¶

Container Path	Sub-Path	Used By
`/config`	`config`	FiveM server config (`server.cfg`, resources/)
`/txData`	`txData`	txAdmin state
`/data`	`sidecar`	Sidecar gRPC file service

txAdmin Access URL¶

Format: https://{txadmin_ingress_provision_id}.zone.zaroz.cloud

What Needs to Be Built¶

1. `CatalogServiceKind::FiveM`¶

Add FiveM variant to CatalogServiceKind.

2. `FiveMConfiguration`¶

pub struct FiveMConfiguration {
    pub license_key: String,
    pub server_name: String,
}

3. `FiveMSetupFlow`¶

2-step flow: 1. Input step: license_key (cfx.re License Key) + server_name 2. Confirm step: summary → submit

4. `IngressRoute` Provision Kind¶

apply_ingress_route() creates a Traefik IngressRoute CRD: - entryPoints: [websecure] - match: Host(...) - tls.secretName: zone-zaroz-cloud-tls (existing shared wildcard)

Implemented via kube::core::DynamicObject (custom CRD).

5. UDP ExternalService¶

FiveM requires UDP 30120. Verify that PortProtocol::Udp is supported end-to-end in the port_allocations + NodePort/MetalLB service creation path.

6. `FiveMBlueprint`¶

Server Deployment env:

NO_DEFAULT_CONFIG=true
license_key (from FiveMConfiguration, set as env var for txAdmin)

7. Catalog Item¶

Add a FiveM catalog item via admin API or migration.

8. Dashboard Changes¶

Store: show FiveM as purchasable service
Setup flow: render license key + server name inputs
Order page → Access tab: player-facing connection string + "txAdmin Panel" button
Order page → Provisions tab: IngressRoute provision shows its URL

Implementation Order¶

Phase	What
1	Domain + Flow (FiveM CatalogServiceKind, FiveMConfiguration, FiveMSetupFlow, FlowEngine wiring)
2	IngressRoute Provision Kind (`apply_ingress_route()` via Traefik CRD)
3	FiveMBlueprint + verify UDP ExternalService
4	Catalog Item + end-to-end test
5	Dashboard (icon, flow rendering, access tab, provisions tab)

Notes¶

spritsail/fivem vs official image: spritsail/fivem bundles txAdmin and is the pragmatic choice.
txAdmin subdomain: Using the txadmin-ingress provision UUID as the subdomain is stable and unique.
Sidecar file access: Mount sub-path config so users can edit server.cfg and resources via the file browser.
UDP port allocation: Confirm the ip_pools / PortAllocation system can allocate UDP.