huatuo-apiserver Configuration

1. Overview

huatuo-apiserver uses a strictly decoded TOML configuration file. Unknown or obsolete options prevent startup. Commented options use the built-in defaults shown below.

2. Logging and Runtime Limits

huatuo-apiserver does not create its own cgroup by default. The [Runtime] section applies only when --enable-cgroup is explicitly passed; Kubernetes and systemd deployments should use their native resource controls.

# Log Configuration
[Log]
    # - Level
    # The log level for huatuo-apiserver: Debug, Info, Warn, Error, Panic.
    # Default: Info
    #
    # Level = "Info"

# Runtime limits for the huatuo-apiserver process.
[Runtime]
    # - CPULimitCores
    # CPU limit in cores.
    # Default: 20
    #
    # - MemoryLimitMiB
    # Memory limit in MiB.
    # Default: 4096
    #
    # CPULimitCores = 20
    # MemoryLimitMiB = 4096
  • Log.Level supports Debug, Info, Warn, Error, and Panic.
  • CPULimitCores limits the API server process in CPU cores.
  • MemoryLimitMiB limits the API server process in MiB.

All resource limits must be greater than zero. --log-debug overrides Log.Level.

3. HTTP Server

# HTTP server configuration.
[APIServer]
    # - ListenAddress
    # Listen address in "host:port" form.
    # Default: ":12740"
    #
    # ListenAddress = ":12740"

    # Request rate limiting.
    [APIServer.RateLimit]
        # - RequestsPerSecond
        # Maximum process-wide request rate per second.
        # Default: 200
        #
        # - Burst
        # Maximum process-wide request burst.
        # Default: 200
        #
        # RequestsPerSecond = 200
        # Burst = 200

ListenAddress uses host:port form. An empty host listens on all interfaces. RateLimit is a process-wide token bucket; both values must be positive. HTTP timeouts and request-size limits are fixed service safeguards and are not user configurable.

4. Jobs and Agent Communication

# Job persistence.
[Jobs]
    # - StoreDSN
    # SQLite DSN. Relative paths are resolved from this file's directory.
    # Default: "jobs.db"
    #
    # StoreDSN = "jobs.db"

    # Job records use an internal revision for concurrent updates. Only records
    # written by this server version are supported; stop the old service and
    # remove or replace an incompatible database before starting this version.

    # Profiling and tracing retain independent quotas because their resource
    # costs and expected concurrency differ.
    [Jobs.Profiling]
        # - MaxConcurrentPerHost
        # Maximum concurrent profiling jobs on one host.
        # Default: 3
        #
        # - MaxConcurrent
        # Maximum concurrent profiling jobs across all hosts.
        # Default: 500
        #
        # MaxConcurrentPerHost = 3
        # MaxConcurrent = 500

    [Jobs.Tracing]
        # - MaxConcurrentPerHost
        # Maximum concurrent tracing jobs on one host.
        # Default: 5
        #
        # - MaxConcurrent
        # Maximum concurrent tracing jobs across all hosts.
        # Default: 1000
        #
        # MaxConcurrentPerHost = 5
        # MaxConcurrent = 1000

    # Apiserver-owned Job lifecycle policy.
    [Jobs.Controller]
        # StatusPollIntervalSeconds = 5
        # PendingTimeoutSeconds = 30
        # CompletionGracePeriodSeconds = 60
        # NodeUnavailableGracePeriodSeconds = 30
        # JobRetentionPeriodHours = 720

# huatuo-bamai Agent HTTP client configuration.
[Agent]
    # - HTTPPort
    # Agent HTTP server port.
    # Default: 19704
    #
    # HTTPPort = 19704

    [Agent.Auth]
        # Must match HTTPServer.Auth.BearerToken on every Node.
        BearerToken = "REPLACE_WITH_RANDOM_HEX"

StoreDSN is the SQLite data source for durable job state. Relative paths are resolved from the configuration directory.

Profiling and tracing use the same quota model but retain independent values. Their resource cost and expected concurrency differ, so a shared limit would allow one workload to starve the other.

Agent request transport safeguards use internal client defaults. Job polling, deadlines, unavailable grace, and retention are owned independently by Jobs.Controller; no runtime negotiation with the Node is performed.

During shutdown, the API server leaves active Node operations running. A replacement API server recovers active Jobs from durable state and resumes monitoring without replaying Start.

5. Elasticsearch/OpenSearch

# Optional Elasticsearch/OpenSearch backend for querying profiling data.
[Elasticsearch]
    # Address, Username, and Password must be configured together to enable
    # this backend.
    #
    # - Address
    # Elasticsearch or OpenSearch HTTP address.
    #
    # - Username
    # Elasticsearch or OpenSearch username.
    #
    # - Password
    # Elasticsearch or OpenSearch password.
    #
    # - Index
    # Index containing huatuo-bamai profiling data.
    # Default: "huatuo_bamai"
    #
    # Address = "https://elasticsearch.example.com:9200"
    # Username = "huatuo-apiserver"
    # Password = "REPLACE_WITH_STRONG_PASSWORD"
    # Index = "huatuo_bamai"

Storage is optional. Address, Username, and Password must either all be empty or all be configured. Index defaults to huatuo_bamai and must match the collector storage index. When disabled, raw-profile and flame graph query routes are not registered.

6. Authentication and Authorization

# Authentication configuration.
[Auth]
    # - ID
    # Stable principal identifier stored with jobs.
    #
    # - BearerToken
    # Secret used only to authenticate requests. IDs and tokens must be unique.
    #
    # - Admin
    # Whether the principal has unrestricted API access.
    #
    # - Permissions
    # API method and path patterns granted to a restricted principal.
    #
    # Administrator example:
    # [[Auth.Users]]
    #     ID = "administrator"
    #     BearerToken = "REPLACE_WITH_RANDOM_HEX"
    #     Admin = true
    #
    # Restricted example:
    # [[Auth.Users]]
    #     ID = "huatuo-front"
    #     BearerToken = "REPLACE_WITH_ANOTHER_RANDOM_HEX"
    #     Permissions = [
    #         "GET /v1/tracing",
    #         "GET /v1/tracing/**",
    #         "GET /v1/profiling",
    #         "GET /v1/profiling/**",
    #     ]
  • ID is the required stable principal identifier stored with jobs.
  • BearerToken is a required secret used only to authenticate requests.
  • Admin grants access to all routes and ignores Permissions.
  • Permissions is required for non-admin users. Entries may be path-only or prefixed with an HTTP method. * matches one path segment and ** matches a suffix.

IDs and bearer tokens must each be unique. Rotating a bearer token does not change job ownership because tokens are never used as principal IDs.

/readyz, /metrics, and /version are public. /debug/pprof/** and /v1/profiling/flamegraph/** require an administrator.

7. Profiling

# Profiling result-link configuration.
[Profiling]
    # - DashboardBaseURL
    # Optional dashboard base URL. Result URLs are omitted when empty.
    # Default: empty
    #
    # DashboardBaseURL = "https://grafana.example.com/d"
  • DashboardBaseURL is optional and must use HTTP or HTTPS when configured. Result-capable jobs omit a dashboard URL when it is empty.

Profiler execution and aggregation settings are Node-local configuration.