Appearance
apphost.site.domain-attach
Attach a custom hostname to a hosted site: request ACM covering *.app.orkestia.dev plus the hostname, return DNS validation records, poll until ISSUED, then add the CloudFront alias and KVS routing key.
Request ACM, wait for DNS validation, attach hostname to CloudFront + KVS.
Overview
| Property | Value |
|---|---|
| Workflow type | Linear |
| Library | App-apphost |
| Version | 1.0 |
Input Schema
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
site_uuid | uuid | Yes | — | HostedSite to attach the hostname to |
hostname | string | Yes | — | CNAME-able FQDN (e.g. auth.example.com), not *.app.orkestia.dev |
Output Schema
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
site_uuid | uuid | No | — | — |
domain_uuid | uuid | No | — | — |
hostname | string | No | — | — |
status | string | No | — | — |
url | string | No | — | — |
acm_certificate_arn | string | No | — | — |
dns_records | json | No | — | Paste-ready DNS records (ACM validation CNAME + traffic CNAME) |
already_attached | boolean | No | — | — |
certificate_status | string | No | — | Last ACM certificate Status seen (PENDING_VALIDATION, ISSUED, ...) |
certificate_validated | boolean | No | — | True once ACM reports ISSUED (or the hostname was already attached) |
validation_check_count | integer | No | — | Number of check_validation polls performed so far |
callback_registered | boolean | No | — | — |
retried_from | string | No | — | Previous terminal state when a failed run was retried |
retry_count | integer | No | — | Number of retry attempts recorded by the workflow engine |
failure_reason | string | No | — | — |
failure_type | string | No | — | — |
failed_action | string | No | — | — |
failed_at_state | string | No | — | — |
failed_step | json | No | — | — |
failed_layer | json | No | — | — |
error | string | No | — | — |
error_type | string | No | — | — |
States
| State | Initial | Terminal | Success | Auto-advance | Description |
|---|---|---|---|---|---|
pending | Yes | No | — | request_certificate | — |
attaching | No | No | — | complete | — |
requesting_certificate | No | No | — | wait_for_validation | — |
waiting_for_validation | No | No | — | — | Poll ACM until ISSUED; customer creates the DNS validation CNAME |
completed | No | Yes | Yes | — | — |
failed | No | Yes | No | — | — |
State Diagram
Transitions
| From | Action | To | Description |
|---|---|---|---|
pending | request_certificate | requesting_certificate | — |
requesting_certificate | wait_for_validation | waiting_for_validation | — |
waiting_for_validation | check_validation | waiting_for_validation | — |
waiting_for_validation | attach | attaching | — |
attaching | complete | completed | — |
* (any state) | fail | failed | — |
Outcomes
| Outcome | Type | Description | State Data Keys |
|---|---|---|---|
attached | SUCCESS | Custom hostname validated, aliased on CloudFront, and routed at the edge | site_uuid, domain_uuid, hostname, url |
failed | FAILURE | Apphost workflow failed | failure_reason |
API Usage
bash
POST /api/workflows/start
Content-Type: application/json
{
"workflow_type": "apphost.site.domain-attach",
"initial_data": {
"site_uuid": "value",
"hostname": "value"
}
}