Sign in
Frontends

Configure frontend custom domain

Changed on

Configures one custom domain for a frontend. The default Volcano-generated frontend URL remains active. Wildcard Volcano frontend TLS remains valid and isolated from custom-domain certificate changes. The account must own the hostname: it must have verified the hostname or a domain above it (see POST /user/domains). A certificate does not prove ownership. When the account owns no domain covering the hostname, Volcano asks for a TXT record at _volcano.<registrable domain>, such as _volcano.example.com. Publishing it verifies the whole domain, so later subdomains need no record. A managed TLS request reserves the hostname and returns that record in verification_records; the reservation expires after 72 hours unless the record is published. A BYOC request gets 409 with code: ownership_verification_required and the record in required_record; publish it and send the same request again. Managed TLS then returns the CNAME that authorizes certificate issuance and renewal. An unverified reservation does not block an account that proves ownership. When another account holds one, a request gets 409 with code: ownership_verification_required and the caller's own required_record; after publishing it, the same request takes over the reservation. When another account verified the domain, the same 409 names the record that moves the domain to the caller once the other account's record is no longer published. A hostname below a domain another account owns otherwise returns 409 without code.

post/projects/{id}/frontends/{frontendId}/domain

Request

  • Base URL: https://api.volcano.dev
  • URL: https://api.volcano.dev/projects/{id}/frontends/{frontendId}/domain
  • Auth: one of:
    • HTTP bearer
    • HTTP bearer

Path parameters

idstring uuid required

Project ID

frontendIdstring uuid required

Frontend ID

Request body

CreateFrontendCustomDomainRequest required(unresolved $ref)

Response

Custom domain already configured with same hostname

domainstring required
tls_mode'managed' | 'byoc' required
domain_status'pending_verification' | 'provisioning' | 'active' | 'detaching' | 'failed' | 'deleted' required
verification_status'pending' | 'verified' | 'failed' required

verified: the domain is served by a validated certificate. pending: it is not served yet, is being re-validated after its certificate material was withdrawn, or Volcano is retrying after a failure. failed: a failure left the domain unserved, alongside domain_status: failed; managed domains report the cause in failure_reason.

failure_reasonstring

Failure category, present only when managed TLS setup has failed. Current values are provider, certificate, ownership, and internal; ownership means another account has already claimed the hostname through ownership verification. Treat unrecognized values as internal.

routing_target_hostnamestring

DNS routing target hostname for this frontend. The DNS record type depends on whether the custom domain is a zone apex.

effective_urlsstring[] required
created_atstring date-time required
updated_atstring date-time required

Changes

  • 23e7875e7c4cRevision changes
    • ○

      the endpoint scheme security ProjectAccessToken was added to the API

  • f0670c84c817Revision changes
    • ▲

      the response's body type changed from object to no type for status

    • ▲

      the response's property type changed from object to no type for status

    • ▲

      the response's property type changed from object to no type for status

    • ▲

      removed the required property from the response with the status

    • ▲

      removed the required property / from the response with the status

    • ▲

      removed the required property / from the response with the status

    • ▲

      removed the required property / from the response with the status

    • ▲

      removed the required property / from the response with the status

    • ▲

      removed the required property / from the response with the status

    • ▲

      removed the required property / from the response with the status

    • ●

      the request property's maxLength was set to 253

    • ●

      the / request property's maxLength was set to 65536

    • ●

      the / request property's maxLength was set to 65536

    • ●

      the / request property's maxLength was set to 65536

    • ●

      removed the optional property from the response with the status

    • ●

      added the new failed enum value to the response property for the response status

    • ●

      added the new failed enum value to the response property for the response status

    • ○

      the request property / became optional

    • ○

      the request property / became optional

    • ○

      added the new managed enum value to the request property /

    • ○

      added subschema #2 to the response body allOf list for the response status

    • ○

      added the optional property to the response with the status

    • ○

      added the optional property to the response with the status

    • ○

      added the optional property to the response with the status

    • ○

      added the optional property to the response with the status

    • ○

      added to the response property allOf list for the response status

    • ○

      added to the response property allOf list for the response status

    • ○

      response property required_routing_record deprecated

    • ○

      response property required_routing_record deprecated