REST Resource: projects.locations.backends.domains

Resource: Domain

A domain name that is associated with a backend.

JSON representation
{
  "name": string,
  "displayName": string,
  "createTime": string,
  "updateTime": string,
  "type": enum (Type),
  "disabled": boolean,
  "serve": {
    object (ServingBehavior)
  },
  "customDomainStatus": {
    object (CustomDomainStatus)
  },
  "reconciling": boolean,
  "deleteTime": string,
  "purgeTime": string,
  "labels": {
    string: string,
    ...
  },
  "annotations": {
    string: string,
    ...
  },
  "uid": string,
  "etag": string
}
Fields
name

string

Identifier. The resource name of the domain, e.g. /projects/p/locations/l/backends/b/domains/foo.com

displayName

string

Optional. Mutable human-readable name for the domain. 63 character limit. e.g. prod domain.

createTime

string (Timestamp format)

Output only. Time at which the domain was created.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".

updateTime

string (Timestamp format)

Output only. Time at which the domain was last updated.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".

type

enum (Type)

Output only. The type of the domain.

disabled

boolean

Optional. Whether the domain is disabled. Defaults to false.

serve

object (ServingBehavior)

Optional. The serving behavior of the domain. If specified, the domain will serve content other than its backend's live content.

customDomainStatus

object (CustomDomainStatus)

Output only. Represents the state and configuration of a CUSTOM type domain. It is only present on Domains of that type.

reconciling

boolean

Output only. A field that, if true, indicates that the build has an ongoing LRO.

deleteTime

string (Timestamp format)

Output only. Time at which the domain was deleted.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".

purgeTime

string (Timestamp format)

Output only. Time at which a soft-deleted domain will be purged, rendering in permanently deleted.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".

labels

map (key: string, value: string)

Optional. Labels as key value pairs.

An object containing a list of "key": value pairs. Example: { "name": "wrench", "mass": "1.3kg", "count": "3" }.

annotations

map (key: string, value: string)

Optional. Annotations as key value pairs.

An object containing a list of "key": value pairs. Example: { "name": "wrench", "mass": "1.3kg", "count": "3" }.

uid

string

Output only. System-assigned, unique identifier.

etag

string

Output only. Server-computed checksum based on other values; may be sent on update or delete to ensure operation is done on expected resource.

Type

The type of the domain.

Enums
TYPE_UNSPECIFIED The type is unspecified (this should not happen).
DEFAULT Default, App Hosting-provided and managed domains. These domains are created automatically with their parent backend and cannot be deleted except by deleting that parent, and cannot be moved to another backend. Default domains can be disabled via the disabled field.
CUSTOM Custom, developer-owned domains. Custom Domains allow you to associate a domain you own with your App Hosting backend, and configure that domain to serve your backend's content.

ServingBehavior

Indicates whether App Hosting will serve content on the domain.

JSON representation
{

  // Union field serving_behavior can be only one of the following:
  "redirect": {
    object (Redirect)
  }
  // End of list of possible types for union field serving_behavior.
}
Fields
Union field serving_behavior. If specified, customizes the serving behaviour of a domain. serving_behavior can be only one of the following:
redirect

object (Redirect)

Optional. Redirect behavior for a domain, if provided.

Redirect

Specifies redirect behavior for a domain.

JSON representation
{
  "uri": string,
  "status": string
}
Fields
uri

string

Required. The URI of the redirect's intended destination. This URI will be prepended to the original request path. URI without a scheme are assumed to be HTTPS.

status

string (int64 format)

Optional. The status code to use in a redirect response. Must be a valid HTTP 3XX status code. Defaults to 302 if not present.

CustomDomainStatus

The status of a custom domain's linkage to a backend.

JSON representation
{
  "hostState": enum (HostState),
  "ownershipState": enum (OwnershipState),
  "certState": enum (CertState),
  "requiredDnsUpdates": [
    {
      object (DnsUpdates)
    }
  ],
  "issues": [
    {
      object (Status)
    }
  ]
}
Fields
hostState

enum (HostState)

Output only. Tracks whether a custom domain is detected as appropriately directing traffic to App Hosting.

ownershipState

enum (OwnershipState)

Output only. Tracks whether the backend is permitted to serve content on the domain, based off the domain's DNS records.

certState

enum (CertState)

Output only. Tracks SSL certificate status for the domain.

requiredDnsUpdates[]

object (DnsUpdates)

Output only. Lists the records that must added or removed to a custom domain's DNS in order to finish setup and start serving content. Field is present during onboarding. Also present after onboarding if one or more of the above states is not *_ACTIVE, indicating the domain's DNS records are in a bad state.

issues[]

object (Status)

Output only. A list of issues with domain configuration. Allows users to self-correct problems with DNS records.

HostState

The host state of your domain. Host state is determined by checking each IP address associated with your domain to see if it's serving through the appropriate shard of App Hosting's Origin.

Enums
HOST_STATE_UNSPECIFIED Your custom domain's host state is unspecified. The message is invalid if this is unspecified.
HOST_UNHOSTED Your custom domain isn't associated with any IP addresses.
HOST_UNREACHABLE Your custom domain can't be reached. App Hosting services' DNS queries to find your domain's IP addresses resulted in errors. See your CustomDomainStatus's issues field for more details.
HOST_NON_FAH Your domain has only IP addresses that don't ultimately resolve to App Hosting.
HOST_CONFLICT Your domain has IP addresses that resolve to both App Hosting and to other services. To ensure consistent results, remove A and AAAA records related to non-App-Hosting services.
HOST_WRONG_SHARD Your domain has IP addresses that resolve to an incorrect region and/or replication shard of App Hosting.
HOST_ACTIVE All requests against your domain are served by App Hosting, via your domain's assigned shard. If the custom domain's OwnershipState is also OWNERSHIP_ACTIVE, App Hosting serves its backend's content on requests for the domain.

OwnershipState

The ownership state of your custom domain.

Enums
OWNERSHIP_STATE_UNSPECIFIED Your custom domain's ownership state is unspecified. This should never happen.
OWNERSHIP_MISSING Your custom domain's domain has no App-Hosting-related ownership records; no backend is authorized to serve on the domain in this Origin shard.
OWNERSHIP_UNREACHABLE Your custom domain can't be reached. App Hosting services' DNS queries to find your domain's ownership records resulted in errors. See your CustomDomainStatus's issues field for more details.
OWNERSHIP_MISMATCH Your custom domain is owned by another App Hosting custom domain. Remove the conflicting records and replace them with records for your current custom domain.
OWNERSHIP_CONFLICT Your custom domain has conflicting TXT records that indicate ownership by both your current custom domain one or more others. Remove the extraneous ownership records to grant the current custom domain ownership.
OWNERSHIP_PENDING Your custom domain's DNS records are configured correctly. App Hosting will transfer ownership of your domain to this custom domain within 24 hours.
OWNERSHIP_ACTIVE Your custom domain owns its domain.

CertState

The state of the SSL certificate App Hosting has for your domain name. This can represent either the state of the actual certificate or, for new custom domains, App Hosting's in-progress attempt to create a certificate.

Enums
CERT_STATE_UNSPECIFIED The certificate's state is unspecified. The message is invalid if this is unspecified.
CERT_PREPARING The initial state of every certificate, represents App Hosting's intent to create a certificate before requests to a Certificate Authority are made.
CERT_VALIDATING App Hosting is validating whether a domain name's DNS records are in a state that allow certificate creation on its behalf.
CERT_PROPAGATING The certificate was recently created, and needs time to propagate in App Hosting's load balancers.
CERT_ACTIVE The certificate is active, providing secure connections for the domain names it represents.
CERT_EXPIRING_SOON The certificate is expiring, all domain names on it will be given new certificates.
CERT_EXPIRED The certificate has expired. App Hosting can no longer serve secure content on your domain name.

DnsUpdates

A set of DNS record updates that you should make to allow App Hosting to serve secure content in response to requests against your domain. These updates present the current state of your domain's and related subdomains' DNS records when App Hosting last queried them, and the desired set of records that App Hosting needs to see before your custom domain can be fully active.

JSON representation
{
  "domainName": string,
  "discovered": [
    {
      object (DnsRecordSet)
    }
  ],
  "desired": [
    {
      object (DnsRecordSet)
    }
  ],
  "checkTime": string
}
Fields
domainName

string

Output only. The domain name the DNS updates pertain to.

discovered[]

object (DnsRecordSet)

Output only. The set of DNS records App Hosting discovered when inspecting a domain.

desired[]

object (DnsRecordSet)

Output only. The set of DNS records App Hosting needs in order to be able to serve secure content on the domain.

checkTime

string (Timestamp format)

Output only. The last time App Hosting checked your custom domain's DNS records.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".

DnsRecordSet

A set of DNS records relevant to the setup and maintenance of a custom domain in App Hosting.

JSON representation
{
  "domainName": string,
  "checkError": {
    object (Status)
  },
  "records": [
    {
      object (DnsRecord)
    }
  ]
}
Fields
domainName

string

Output only. The domain name the record set pertains to.

checkError

object (Status)

Output only. An error App Hosting services encountered when querying your domain's DNS records. Note: App Hosting ignores NXDOMAIN errors, as those generally just mean that a domain name hasn't been set up yet.

records[]

object (DnsRecord)

Output only. Records on the domain.

DnsRecord

A representation of a DNS records for a domain.

DNS records are resource records that define how systems and services should behave when handling requests for a domain. For example, when you add A records to your domain's DNS records, you're informing other systems (such as your users' web browsers) to contact those IPv4 addresses to retrieve resources relevant to your domain (such as your App Hosting files).

JSON representation
{
  "domainName": string,
  "type": enum (Type),
  "rdata": string,
  "requiredAction": enum (Action),
  "relevantState": [
    enum (CustomDomainState)
  ]
}
Fields
domainName

string

Output only. The domain the record pertains to, e.g. foo.bar.com..

type

enum (Type)

Output only. The record's type, which determines what data the record contains.

rdata

string

Output only. The data of the record. The meaning of the value depends on record type: - A and AAAA: IP addresses for the domain. - CNAME: Another domain to check for records. - TXT: Arbitrary text strings associated with the domain. App Hosting uses TXT records to determine which Firebase projects have permission to act on the domain's behalf. - CAA: The record's flags, tag, and value, e.g. 0 issue "pki.goog".

requiredAction

enum (Action)

Output only. An enum that indicates the a required action for this record. Populated when the record is part of a required change in a DnsUpdates discovered or desired record set.

relevantState[]

enum (CustomDomainState)

Output only. An enum that indicates which state(s) this DNS record applies to. Populated for all records with an ADD or REMOVE required action.

Type

The type of the DNS record, including A, TXT, AAAA, and CAA.

Enums
TYPE_UNSPECIFIED The record's type is unspecified. The message is invalid if this is unspecified.
A An A record, as defined in RFC 1035. A records determine which IPv4 addresses a domain directs traffic towards.
CNAME A CNAME record, as defined in RFC 1035. CNAME or Canonical Name records map a domain to a different, canonical domain. If a CNAME record is present, it should be the only record on the domain.
TXT A TXT record, as defined in RFC 1035. TXT records hold arbitrary text data on a domain. Hosting uses TXT records to establish which Firebase Project has permission to act on a domain.
AAAA An AAAA record, as defined in RFC 3596 AAAA records determine which IPv6 addresses a domain directs traffic towards.
CAA

A CAA record, as defined in RFC 6844. CAA, or Certificate Authority Authorization, records determine which Certificate Authorities (SSL certificate minting organizations) are authorized to mint a certificate for the domain. App Hosting uses pki.goog as its primary CA.

CAA records cascade. A CAA record on foo.com also applies to bar.foo.com unless bar.foo.com has its own set of CAA records.

CAA records are optional. If a domain and its parents have no CAA records, all CAs are authorized to mint certificates on its behalf. In general, App Hosting only asks you to modify CAA records when doing so is required to unblock SSL cert creation.

Action

The type of action you should take on this DNS record to configure your domain for use with App Hosting.

Enums
NONE No action necessary.
ADD Add this record to your DNS records.
REMOVE Remove this record from your DNS records.

CustomDomainState

A set of states relevant to the healthy functioning of a custom domain.

Enums
CUSTOM_DOMAIN_STATE_UNSPECIFIED This message is invalid if this is unspecified.
HOST_STATE The custom domain's host state.
OWNERSHIP_STATE The custom domain's ownership state.
CERT_STATE The custom domain's certificate state.

Methods

create

Links a new domain to a backend.

delete

Deletes a single domain.

get

Gets information about a domain.

list

Lists domains of a backend.

patch

Updates the information for a single domain.