feat(api): support managed custom-domain TLS

Author: swkeever

features/contract/managed_tls.feature

@@ -0,0 +1,8 @@
+Feature: Managed custom-domain TLS contract
+
+  @managed-tls @TLS-MANAGED-001
+  Scenario: Managed TLS uses an explicit secret-free request and DNS lifecycle response
+    Given a managed custom-domain TLS request
+    When the client encodes the request and decodes a pending verification response
+    Then the request selects managed TLS without certificate material
+    And the response exposes the managed lifecycle and DNS records

features/steps/sdk_contract_steps.py

@@ -13,6 +13,15 @@
 )
 
 from volcano_sdk import VolcanoClient
+from volcano_sdk._generated.models.create_frontend_custom_domain_request import (
+    CreateFrontendCustomDomainRequest,
+)
+from volcano_sdk._generated.models.frontend_custom_domain_response import (
+    FrontendCustomDomainResponse,
+)
+from volcano_sdk._generated.models.managed_frontend_custom_domain_tls_config import (
+    ManagedFrontendCustomDomainTLSConfig,
+)
 
 ACCESS_TOKEN_CLOCK_TICK_SECONDS = 1.1
 
@@ -395,3 +404,67 @@ def subscriber_received_message(context: Any) -> None:
     world = _world(context)
     assert world.last_outcome is not None
     assert world.last_outcome.value == world.realtime_message
+
+
+@given("a managed custom-domain TLS request")
+def managed_tls_request(context: Any) -> None:
+    _world(context).managed_tls_request = CreateFrontendCustomDomainRequest(
+        domain="app.example.com",
+        tls=ManagedFrontendCustomDomainTLSConfig(mode="managed"),
+    )
+
+
+@when("the client encodes the request and decodes a pending verification response")
+def encode_managed_tls_request(context: Any) -> None:
+    world = _world(context)
+    world.managed_tls_wire_request = world.managed_tls_request.to_dict()
+    world.managed_tls_response = FrontendCustomDomainResponse.from_dict(
+        {
+            "domain": "app.example.com",
+            "tls_mode": "managed",
+            "domain_status": "pending_verification",
+            "verification_status": "pending",
+            "verification_records": [
+                {
+                    "name": "_token.app.example.com",
+                    "type": "CNAME",
+                    "value": "_validation.volcano.dev",
+                }
+            ],
+            "required_routing_record": {
+                "record_type": "CNAME",
+                "name": "app.example.com",
+                "value": "frontend.frontends.volcano.dev",
+            },
+            "effective_urls": ["https://frontend.frontends.volcano.dev/"],
+            "created_at": "2026-09-02T12:00:00Z",
+            "updated_at": "2026-09-02T12:00:00Z",
+        }
+    )
+
+
+@then("the request selects managed TLS without certificate material")
+def managed_tls_request_has_no_certificate(context: Any) -> None:
+    assert _world(context).managed_tls_wire_request == {
+        "domain": "app.example.com",
+        "tls": {"mode": "managed"},
+    }
+
+
+@then("the response exposes the managed lifecycle and DNS records")
+def managed_tls_response_has_lifecycle(context: Any) -> None:
+    response = _world(context).managed_tls_response
+    assert response.domain == "app.example.com"
+    assert response.tls_mode == "managed"
+    assert response.domain_status == "pending_verification"
+    assert response.verification_status == "pending"
+    assert response.verification_records[0].to_dict() == {
+        "name": "_token.app.example.com",
+        "type": "CNAME",
+        "value": "_validation.volcano.dev",
+    }
+    assert response.required_routing_record.to_dict() == {
+        "record_type": "CNAME",
+        "name": "app.example.com",
+        "value": "frontend.frontends.volcano.dev",
+    }

openapi/openapi.yaml

@@ -10993,13 +10993,14 @@ components:
         - text_body
     CreateFrontendCustomDomainRequest:
       type: object
+      additionalProperties: false
       properties:
         domain:
           type: string
           description: Fully-qualified domain name (hostname only, no scheme/path)
           example: app.example.com
         tls:
-          $ref: '#/components/schemas/FrontendCustomDomainTLSConfig'
+          $ref: '#/components/schemas/CreateFrontendCustomDomainTLSConfig'
       required:
         - domain
         - tls
@@ -12492,6 +12493,7 @@ components:
           enum:
             - pending
             - verified
+            - failed
         verification_records:
           type: array
           items:
@@ -12516,15 +12518,35 @@ components:
         - effective_urls
         - created_at
         - updated_at
-    FrontendCustomDomainTLSConfig:
+    CreateFrontendCustomDomainTLSConfig:
+      oneOf:
+        - $ref: '#/components/schemas/ManagedFrontendCustomDomainTLSConfig'
+        - $ref: '#/components/schemas/BYOCFrontendCustomDomainTLSConfig'
+      discriminator:
+        propertyName: mode
+        mapping:
+          managed: '#/components/schemas/ManagedFrontendCustomDomainTLSConfig'
+          byoc: '#/components/schemas/BYOCFrontendCustomDomainTLSConfig'
+    ManagedFrontendCustomDomainTLSConfig:
+      type: object
+      description: Volcano issues and renews the certificate. Do not send certificate material.
+      additionalProperties: false
+      properties:
+        mode:
+          type: string
+          enum:
+            - managed
+      required:
+        - mode
+    BYOCFrontendCustomDomainTLSConfig:
       type: object
+      description: Use certificate material that you manage.
+      additionalProperties: false
       properties:
         mode:
           type: string
           enum:
             - byoc
-          default: byoc
-          description: BYOC is mandatory for custom domain creation.
         certificate_pem:
           type: string
           description: Required. PEM-encoded certificate.
@@ -12538,6 +12560,64 @@ components:
         - mode
         - certificate_pem
         - private_key_pem
+    FrontendCustomDomainTLSConfig:
+      type: object
+      deprecated: true
+      description: Deprecated compatibility model. Use BYOCFrontendCustomDomainTLSConfig.
+      properties:
+        mode:
+          type: string
+          enum:
+            - byoc
+          default: byoc
+        certificate_pem:
+          type: string
+        private_key_pem:
+          type: string
+        certificate_chain_pem:
+          type: string
+      required:
+        - mode
+        - certificate_pem
+        - private_key_pem
+    ProjectConfigFrontendCustomDomainTLSConfig:
+      oneOf:
+        - $ref: '#/components/schemas/ManagedProjectConfigFrontendCustomDomainTLSConfig'
+        - $ref: '#/components/schemas/BYOCProjectConfigFrontendCustomDomainTLSConfig'
+      discriminator:
+        propertyName: mode
+        mapping:
+          managed: '#/components/schemas/ManagedProjectConfigFrontendCustomDomainTLSConfig'
+          byoc: '#/components/schemas/BYOCProjectConfigFrontendCustomDomainTLSConfig'
+    ManagedProjectConfigFrontendCustomDomainTLSConfig:
+      type: object
+      additionalProperties: false
+      properties:
+        mode:
+          type: string
+          enum:
+            - managed
+      required:
+        - mode
+    BYOCProjectConfigFrontendCustomDomainTLSConfig:
+      type: object
+      additionalProperties: false
+      properties:
+        mode:
+          type: string
+          enum:
+            - byoc
+        certificate_pem:
+          type: string
+          description: PEM-encoded certificate for BYOC create or rotation. Omitted from exports.
+        private_key_pem:
+          type: string
+          description: PEM-encoded private key for BYOC create or rotation. Omitted from exports.
+        certificate_chain_pem:
+          type: string
+          description: Optional PEM-encoded certificate chain for BYOC. Omitted from exports.
+      required:
+        - mode
     FrontendDeployment:
       type: object
       properties:
@@ -12630,8 +12710,10 @@ components:
       properties:
         record_type:
           type: string
+          description: CNAME for a subdomain; ALIAS means provider-supported ALIAS, ANAME, or CNAME flattening at a zone apex.
           enum:
             - CNAME
+            - ALIAS
         name:
           type: string
         value:
@@ -12642,6 +12724,7 @@ components:
         - value
     FrontendDomainVerificationRecord:
       type: object
+      additionalProperties: false
       properties:
         name:
           type: string
@@ -14274,17 +14357,15 @@ components:
       type: object
       additionalProperties: false
       description: |
-        Custom domain with BYOC TLS (PRO plan). `tls` is required when the
-        domain is first created and optional afterwards: providing new TLS
-        material for the same domain rotates the certificate in place (zero
-        downtime); omitting `tls` keeps the stored certificate. TLS material is
-        write-only and omitted from config export.
+        Custom domain with managed or BYOC TLS (PRO plan). `tls` is required
+        when the domain is first created and optional afterwards. BYOC TLS
+        material is write-only and omitted from config export.
       properties:
         domain:
           type: string
           description: Fully-qualified domain name (hostname only, no scheme/path)
         tls:
-          $ref: '#/components/schemas/FrontendCustomDomainTLSConfig'
+          $ref: '#/components/schemas/ProjectConfigFrontendCustomDomainTLSConfig'
       required:
         - domain
     ProjectConfigDatabase:

src/volcano_sdk/_generated/models/__init__.py

@@ -83,6 +83,10 @@
 from .batch_function_deploy_failure import BatchFunctionDeployFailure
 from .batch_function_deploy_failure_operation import BatchFunctionDeployFailureOperation
 from .batch_function_deploy_response import BatchFunctionDeployResponse
+from .byoc_frontend_custom_domain_tls_config import BYOCFrontendCustomDomainTLSConfig
+from .byoc_frontend_custom_domain_tls_config_mode import BYOCFrontendCustomDomainTLSConfigMode
+from .byoc_project_config_frontend_custom_domain_tls_config import BYOCProjectConfigFrontendCustomDomainTLSConfig
+from .byoc_project_config_frontend_custom_domain_tls_config_mode import BYOCProjectConfigFrontendCustomDomainTLSConfigMode
 from .call_o_auth_provider_api_body import CallOAuthProviderAPIBody
 from .call_o_auth_provider_api_body_body import CallOAuthProviderAPIBodyBody
 from .call_o_auth_provider_api_body_method import CallOAuthProviderAPIBodyMethod
@@ -266,6 +270,10 @@
 from .log_search_request import LogSearchRequest
 from .log_search_response import LogSearchResponse
 from .log_stream_request import LogStreamRequest
+from .managed_frontend_custom_domain_tls_config import ManagedFrontendCustomDomainTLSConfig
+from .managed_frontend_custom_domain_tls_config_mode import ManagedFrontendCustomDomainTLSConfigMode
+from .managed_project_config_frontend_custom_domain_tls_config import ManagedProjectConfigFrontendCustomDomainTLSConfig
+from .managed_project_config_frontend_custom_domain_tls_config_mode import ManagedProjectConfigFrontendCustomDomainTLSConfigMode
 from .metric_usage_data import MetricUsageData
 from .o_auth_config import OAuthConfig
 from .o_auth_config_provider import OAuthConfigProvider
@@ -536,6 +544,10 @@
     "BatchFunctionDeployFailure",
     "BatchFunctionDeployFailureOperation",
     "BatchFunctionDeployResponse",
+    "BYOCFrontendCustomDomainTLSConfig",
+    "BYOCFrontendCustomDomainTLSConfigMode",
+    "BYOCProjectConfigFrontendCustomDomainTLSConfig",
+    "BYOCProjectConfigFrontendCustomDomainTLSConfigMode",
     "CallOAuthProviderAPIBody",
     "CallOAuthProviderAPIBodyBody",
     "CallOAuthProviderAPIBodyMethod",
@@ -719,6 +731,10 @@
     "LogSearchRequest",
     "LogSearchResponse",
     "LogStreamRequest",
+    "ManagedFrontendCustomDomainTLSConfig",
+    "ManagedFrontendCustomDomainTLSConfigMode",
+    "ManagedProjectConfigFrontendCustomDomainTLSConfig",
+    "ManagedProjectConfigFrontendCustomDomainTLSConfigMode",
     "MetricUsageData",
     "OAuthConfig",
     "OAuthConfigProvider",

src/volcano_sdk/_generated/models/byoc_frontend_custom_domain_tls_config.py

@@ -0,0 +1,91 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any, TypeVar, BinaryIO, TextIO, TYPE_CHECKING, Generator
+
+from attrs import define as _attrs_define
+from attrs import field as _attrs_field
+
+from ..types import UNSET, Unset
+
+from ..models.byoc_frontend_custom_domain_tls_config_mode import BYOCFrontendCustomDomainTLSConfigMode
+from ..models.byoc_frontend_custom_domain_tls_config_mode import check_byoc_frontend_custom_domain_tls_config_mode
+from ..types import UNSET, Unset
+from typing import cast
+
+
+
+
+
+
+T = TypeVar("T", bound="BYOCFrontendCustomDomainTLSConfig")
+
+
+
+@_attrs_define
+class BYOCFrontendCustomDomainTLSConfig:
+    """ Use certificate material that you manage.
+
+        Attributes:
+            mode (BYOCFrontendCustomDomainTLSConfigMode):
+            certificate_pem (str): Required. PEM-encoded certificate.
+            private_key_pem (str): Required. PEM-encoded private key.
+            certificate_chain_pem (str | Unset): Optional PEM-encoded certificate chain.
+     """
+
+    mode: BYOCFrontendCustomDomainTLSConfigMode
+    certificate_pem: str
+    private_key_pem: str
+    certificate_chain_pem: str | Unset = UNSET
+
+
+
+
+
+    def to_dict(self) -> dict[str, Any]:
+        mode: str = self.mode
+
+        certificate_pem = self.certificate_pem
+
+        private_key_pem = self.private_key_pem
+
+        certificate_chain_pem = self.certificate_chain_pem
+
+
+        field_dict: dict[str, Any] = {}
+
+        field_dict.update({
+            "mode": mode,
+            "certificate_pem": certificate_pem,
+            "private_key_pem": private_key_pem,
+        })
+        if certificate_chain_pem is not UNSET:
+            field_dict["certificate_chain_pem"] = certificate_chain_pem
+
+        return field_dict
+
+
+
+    @classmethod
+    def from_dict(cls: type[T], src_dict: Mapping[str, Any]) -> T:
+        d = dict(src_dict)
+        mode = check_byoc_frontend_custom_domain_tls_config_mode(d.pop("mode"))
+
+
+
+
+        certificate_pem = d.pop("certificate_pem")
+
+        private_key_pem = d.pop("private_key_pem")
+
+        certificate_chain_pem = d.pop("certificate_chain_pem", UNSET)
+
+        byoc_frontend_custom_domain_tls_config = cls(
+            mode=mode,
+            certificate_pem=certificate_pem,
+            private_key_pem=private_key_pem,
+            certificate_chain_pem=certificate_chain_pem,
+        )
+
+        return byoc_frontend_custom_domain_tls_config
+