Package com.pulumi.aws.apigateway

Class DomainName

  • public class DomainName
extends com.pulumi.resources.CustomResource
    Registers a custom domain name for use with AWS API Gateway. Additional information about this functionality can be found in the [API Gateway Developer Guide](https://docs.aws.amazon.com/apigateway/latest/developerguide/how-to-custom-domains.html). This resource just establishes ownership of and the TLS settings for a particular domain name. An API can be attached to a particular path under the registered domain name using the `aws.apigateway.BasePathMapping` resource. API Gateway domains can be defined as either 'edge-optimized' or 'regional'. In an edge-optimized configuration, API Gateway internally creates and manages a CloudFront distribution to route requests on the given hostname. In addition to this resource it's necessary to create a DNS record corresponding to the given domain name which is an alias (either Route53 alias or traditional CNAME) to the CloudFront domain name exported in the `cloudfrontDomainName` attribute. In a regional configuration, API Gateway does not create a CloudFront distribution to route requests to the API, though a distribution can be created if needed. In either case, it is necessary to create a DNS record corresponding to the given domain name which is an alias (either Route53 alias or traditional CNAME) to the regional domain name exported in the `regionalDomainName` attribute. > **Note:** API Gateway requires the use of AWS Certificate Manager (ACM) certificates instead of Identity and Access Management (IAM) certificates in regions that support ACM. Regions that support ACM can be found in the [Regions and Endpoints Documentation](https://docs.aws.amazon.com/general/latest/gr/rande.html#acm_region). To import an existing private key and certificate into ACM or request an ACM certificate, see the `aws.acm.Certificate` resource. > **Note:** The `aws.apigateway.DomainName` resource expects dependency on the `aws.acm.CertificateValidation` as only verified certificates can be used. This can be made either explicitly by adding the `dependsOn = [aws_acm_certificate_validation.cert]` attribute. Or implicitly by referring certificate ARN from the validation resource where it will be available after the resource creation: `regionalCertificateArn = aws_acm_certificate_validation.cert.certificate_arn`. ## Example Usage ### Edge Optimized (ACM Certificate) 
     
 package generated_program;
 
 import com.pulumi.Context;
 import com.pulumi.Pulumi;
 import com.pulumi.core.Output;
 import com.pulumi.aws.apigateway.DomainName;
 import com.pulumi.aws.apigateway.DomainNameArgs;
 import com.pulumi.aws.route53.Record;
 import com.pulumi.aws.route53.RecordArgs;
 import com.pulumi.aws.route53.inputs.RecordAliasArgs;
 import java.util.ArrayList;
 import java.util.Arrays;
 import java.util.Map;
 import java.io.File;
 import java.nio.file.Files;
 import java.nio.file.Paths;
 
 public class App {
     public static void main(String[] args) {
         Pulumi.run(App::stack);
     }
 
     public static void stack(Context ctx) {
         var example = new DomainName("example", DomainNameArgs.builder()
             .certificateArn(exampleAwsAcmCertificateValidation.certificateArn())
             .domainName("api.example.com")
             .build());
 
         // Example DNS record using Route53.
         // Route53 is not specifically required; any DNS host can be used.
         var exampleRecord = new Record("exampleRecord", RecordArgs.builder()
             .aliases(RecordAliasArgs.builder()
                 .evaluateTargetHealth(true)
                 .name(example.cloudfrontDomainName())
                 .zoneId(example.cloudfrontZoneId())
                 .build())
             .name(example.domainName())
             .type("A")
             .zoneId(exampleAwsRoute53Zone.id())
             .build());
 
     }
 }
    ### Regional (ACM Certificate) 
     
 package generated_program;
 
 import com.pulumi.Context;
 import com.pulumi.Pulumi;
 import com.pulumi.core.Output;
 import com.pulumi.aws.apigateway.DomainName;
 import com.pulumi.aws.apigateway.DomainNameArgs;
 import com.pulumi.aws.apigateway.inputs.DomainNameEndpointConfigurationArgs;
 import com.pulumi.aws.route53.Record;
 import com.pulumi.aws.route53.RecordArgs;
 import com.pulumi.aws.route53.inputs.RecordAliasArgs;
 import java.util.ArrayList;
 import java.util.Arrays;
 import java.util.Map;
 import java.io.File;
 import java.nio.file.Files;
 import java.nio.file.Paths;
 
 public class App {
     public static void main(String[] args) {
         Pulumi.run(App::stack);
     }
 
     public static void stack(Context ctx) {
         var example = new DomainName("example", DomainNameArgs.builder()
             .endpointConfiguration(DomainNameEndpointConfigurationArgs.builder()
                 .types("REGIONAL")
                 .build())
             .domainName("api.example.com")
             .regionalCertificateArn(exampleAwsAcmCertificateValidation.certificateArn())
             .build());
 
         // Example DNS record using Route53.
         // Route53 is not specifically required; any DNS host can be used.
         var exampleRecord = new Record("exampleRecord", RecordArgs.builder()
             .aliases(RecordAliasArgs.builder()
                 .evaluateTargetHealth(true)
                 .name(example.regionalDomainName())
                 .zoneId(example.regionalZoneId())
                 .build())
             .name(example.domainName())
             .type("A")
             .zoneId(exampleAwsRoute53Zone.id())
             .build());
 
     }
 }
    ### Enhanced Security Policy 
     
 package generated_program;
 
 import com.pulumi.Context;
 import com.pulumi.Pulumi;
 import com.pulumi.core.Output;
 import com.pulumi.aws.apigateway.DomainName;
 import com.pulumi.aws.apigateway.DomainNameArgs;
 import com.pulumi.aws.apigateway.inputs.DomainNameEndpointConfigurationArgs;
 import java.util.ArrayList;
 import java.util.Arrays;
 import java.util.Map;
 import java.io.File;
 import java.nio.file.Files;
 import java.nio.file.Paths;
 
 public class App {
     public static void main(String[] args) {
         Pulumi.run(App::stack);
     }
 
     public static void stack(Context ctx) {
         var example = new DomainName("example", DomainNameArgs.builder()
             .endpointConfiguration(DomainNameEndpointConfigurationArgs.builder()
                 .types("REGIONAL")
                 .build())
             .domainName("api.example.com")
             .regionalCertificateArn(exampleAwsAcmCertificateValidation.certificateArn())
             .securityPolicy("SecurityPolicy_TLS13_1_3_2025_09")
             .endpointAccessMode("STRICT")
             .build());
 
     }
 }
    ## Import For a private custom domain name: Using `pulumi import`, import API Gateway domain names using their `name` or `name` and `domainNameId` (for private custom domain names). For example: ```sh $ pulumi import aws:apigateway/domainName:DomainName example dev.example.com ``` For a private custom domain name: ```sh $ pulumi import aws:apigateway/domainName:DomainName example dev.api.internal.example.com/abcde12345 ```

    • Nested Class Summary

      • Nested classes/interfaces inherited from class com.pulumi.resources.CustomResource

        com.pulumi.resources.CustomResource.CustomResourceInternal

      • Nested classes/interfaces inherited from class com.pulumi.resources.Resource

        com.pulumi.resources.Resource.LazyField<T extends java.lang.Object>, com.pulumi.resources.Resource.LazyFields, com.pulumi.resources.Resource.ResourceInternal

    • Field Summary

      • Fields inherited from class com.pulumi.resources.Resource

        childResources, remote

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      com.pulumi.core.Output<java.lang.String> arn()  
      com.pulumi.core.Output<java.util.Optional<java.lang.String>> certificateArn()  
      com.pulumi.core.Output<java.util.Optional<java.lang.String>> certificateBody()  
      com.pulumi.core.Output<java.util.Optional<java.lang.String>> certificateChain()  
      com.pulumi.core.Output<java.util.Optional<java.lang.String>> certificateName()  
      com.pulumi.core.Output<java.util.Optional<java.lang.String>> certificatePrivateKey()  
      com.pulumi.core.Output<java.lang.String> certificateUploadDate()  
      com.pulumi.core.Output<java.lang.String> cloudfrontDomainName()  
      com.pulumi.core.Output<java.lang.String> cloudfrontZoneId()  
      com.pulumi.core.Output<java.lang.String> domainName()  
      com.pulumi.core.Output<java.lang.String> domainNameId()  
      com.pulumi.core.Output<java.util.Optional<java.lang.String>> endpointAccessMode()  
      com.pulumi.core.Output<DomainNameEndpointConfiguration> endpointConfiguration()  
      static DomainName get​(java.lang.String name, com.pulumi.core.Output<java.lang.String> id, DomainNameState state, com.pulumi.resources.CustomResourceOptions options)
      Get an existing Host resource's state with the given name, ID, and optional extra properties used to qualify the lookup.
      com.pulumi.core.Output<java.util.Optional<DomainNameMutualTlsAuthentication>> mutualTlsAuthentication()  
      com.pulumi.core.Output<java.lang.String> ownershipVerificationCertificateArn()  
      com.pulumi.core.Output<java.util.Optional<java.lang.String>> policy()  
      com.pulumi.core.Output<java.lang.String> region()  
      com.pulumi.core.Output<java.util.Optional<java.lang.String>> regionalCertificateArn()  
      com.pulumi.core.Output<java.util.Optional<java.lang.String>> regionalCertificateName()  
      com.pulumi.core.Output<java.lang.String> regionalDomainName()  
      com.pulumi.core.Output<java.lang.String> regionalZoneId()  
      com.pulumi.core.Output<java.lang.String> routingMode()  
      com.pulumi.core.Output<java.lang.String> securityPolicy()  
      com.pulumi.core.Output<java.util.Optional<java.util.Map<java.lang.String,​java.lang.String>>> tags()  
      com.pulumi.core.Output<java.util.Map<java.lang.String,​java.lang.String>> tagsAll()  

      • Methods inherited from class com.pulumi.resources.CustomResource

        getId, id, idFuture

      • Methods inherited from class com.pulumi.resources.Resource

        getChildResources, getResourceName, getResourceType, getUrn, pulumiChildResources, pulumiResourceName, pulumiResourceType, urn

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Constructor Detail

      • DomainName

        public DomainName​(java.lang.String name)
        Parameters:
        name - The _unique_ name of the resulting resource.

      • DomainName

        public DomainName​(java.lang.String name,
                  DomainNameArgs args)
        Parameters:
        name - The _unique_ name of the resulting resource.
        args - The arguments to use to populate this resource's properties.

      • DomainName

        public DomainName​(java.lang.String name,
                  DomainNameArgs args,
                  @Nullable
                  com.pulumi.resources.CustomResourceOptions options)
        Parameters:
        name - The _unique_ name of the resulting resource.
        args - The arguments to use to populate this resource's properties.
        options - A bag of options that control this resource's behavior.

    • Method Detail

      • arn

        public com.pulumi.core.Output<java.lang.String> arn()
        Returns:
        ARN of domain name.

      • certificateArn

        public com.pulumi.core.Output<java.util.Optional<java.lang.String>> certificateArn()
        Returns:
        ARN for an AWS-managed certificate. AWS Certificate Manager is the only supported source. Used when an edge-optimized domain name is desired. Conflicts with `certificateName`, `certificateBody`, `certificateChain`, `certificatePrivateKey`, `regionalCertificateArn`, and `regionalCertificateName`.

      • certificateBody

        public com.pulumi.core.Output<java.util.Optional<java.lang.String>> certificateBody()
        Returns:
        Certificate issued for the domain name being registered, in PEM format. Only valid for `EDGE` endpoint configuration type. Conflicts with `certificateArn`, `regionalCertificateArn`, and `regionalCertificateName`.

      • certificateChain

        public com.pulumi.core.Output<java.util.Optional<java.lang.String>> certificateChain()
        Returns:
        Certificate for the CA that issued the certificate, along with any intermediate CA certificates required to create an unbroken chain to a certificate trusted by the intended API clients. Only valid for `EDGE` endpoint configuration type. Conflicts with `certificateArn`, `regionalCertificateArn`, and `regionalCertificateName`.

      • certificateName

        public com.pulumi.core.Output<java.util.Optional<java.lang.String>> certificateName()
        Returns:
        Unique name to use when registering this certificate as an IAM server certificate. Conflicts with `certificateArn`, `regionalCertificateArn`, and `regionalCertificateName`. Required if `certificateArn` is not set.

      • certificatePrivateKey

        public com.pulumi.core.Output<java.util.Optional<java.lang.String>> certificatePrivateKey()
        Returns:
        Private key associated with the domain certificate given in `certificateBody`. Only valid for `EDGE` endpoint configuration type. Conflicts with `certificateArn`, `regionalCertificateArn`, and `regionalCertificateName`.

      • certificateUploadDate

        public com.pulumi.core.Output<java.lang.String> certificateUploadDate()
        Returns:
        Upload date associated with the domain certificate.

      • cloudfrontDomainName

        public com.pulumi.core.Output<java.lang.String> cloudfrontDomainName()
        Returns:
        Hostname created by CloudFront to represent the distribution that implements this domain name mapping.

      • cloudfrontZoneId

        public com.pulumi.core.Output<java.lang.String> cloudfrontZoneId()
        Returns:
        For convenience, the hosted zone ID (`Z2FDTNDATAQYW2`) that can be used to create a Route53 alias record for the distribution.

      • domainName

        public com.pulumi.core.Output<java.lang.String> domainName()
        Returns:
        Fully-qualified domain name to register.

      • domainNameId

        public com.pulumi.core.Output<java.lang.String> domainNameId()
        Returns:
        Identifier for the domain name resource. Supported only for private custom domain names.

      • endpointAccessMode

        public com.pulumi.core.Output<java.util.Optional<java.lang.String>> endpointAccessMode()
        Returns:
        Endpoint access mode of the DomainName. Only available for domain names that use security policies that start with `SecurityPolicy_`. Valid values: `BASIC`, `STRICT`.

      • endpointConfiguration

        public com.pulumi.core.Output<DomainNameEndpointConfiguration> endpointConfiguration()
        Returns:
        Configuration block defining API endpoint information including type. See below.

      • mutualTlsAuthentication

        public com.pulumi.core.Output<java.util.Optional<DomainNameMutualTlsAuthentication>> mutualTlsAuthentication()
        Returns:
        Mutual TLS authentication configuration for the domain name. See below.

      • ownershipVerificationCertificateArn

        public com.pulumi.core.Output<java.lang.String> ownershipVerificationCertificateArn()
        Returns:
        ARN of the AWS-issued certificate used to validate custom domain ownership (when `certificateArn` is issued via an ACM Private CA or `mutualTlsAuthentication` is configured with an ACM-imported certificate.)

      • policy

        public com.pulumi.core.Output<java.util.Optional<java.lang.String>> policy()
        Returns:
        Stringified JSON policy document that applies to the execute-api service for this DomainName regardless of the caller and Method configuration. Supported only for private custom domain names.

      • region

        public com.pulumi.core.Output<java.lang.String> region()
        Returns:
        Region where this resource will be [managed](https://docs.aws.amazon.com/general/latest/gr/rande.html#regional-endpoints). Defaults to the Region set in the provider configuration.

      • regionalCertificateArn

        public com.pulumi.core.Output<java.util.Optional<java.lang.String>> regionalCertificateArn()
        Returns:
        ARN for an AWS-managed certificate. AWS Certificate Manager is the only supported source. Used when a regional domain name is desired. Conflicts with `certificateArn`, `certificateName`, `certificateBody`, `certificateChain`, and `certificatePrivateKey`.

      • regionalCertificateName

        public com.pulumi.core.Output<java.util.Optional<java.lang.String>> regionalCertificateName()
        Returns:
        User-friendly name of the certificate that will be used by regional endpoint for this domain name. Conflicts with `certificateArn`, `certificateName`, `certificateBody`, `certificateChain`, and `certificatePrivateKey`.

      • regionalDomainName

        public com.pulumi.core.Output<java.lang.String> regionalDomainName()
        Returns:
        Hostname for the custom domain's regional endpoint.

      • regionalZoneId

        public com.pulumi.core.Output<java.lang.String> regionalZoneId()
        Returns:
        Hosted zone ID that can be used to create a Route53 alias record for the regional endpoint.

      • routingMode

        public com.pulumi.core.Output<java.lang.String> routingMode()
        Returns:
        Mode to route traffic for the domain name. Valid values: `BASE_PATH_MAPPING_ONLY`, `ROUTING_RULE_ONLY`, `ROUTING_RULE_THEN_BASE_PATH_MAPPING`.

      • securityPolicy

        public com.pulumi.core.Output<java.lang.String> securityPolicy()
        Returns:
        TLS version + cipher suite for this DomainName. Must be configured to perform drift detection. For a list of valid security policies, see [DomainName](https://docs.aws.amazon.com/apigateway/latest/api/API_DomainName.html) in the Amazon API Gateway API Reference.

      • tags

        public com.pulumi.core.Output<java.util.Optional<java.util.Map<java.lang.String,​java.lang.String>>> tags()
        Returns:
        Key-value map of resource tags. If configured with a provider `defaultTags` configuration block present, tags with matching keys will overwrite those defined at the provider-level.

      • tagsAll

        public com.pulumi.core.Output<java.util.Map<java.lang.String,​java.lang.String>> tagsAll()
        Returns:
        Map of tags assigned to the resource, including those inherited from the provider `defaultTags` configuration block.

      • get

        public static DomainName get​(java.lang.String name,
                             com.pulumi.core.Output<java.lang.String> id,
                             @Nullable
                             DomainNameState state,
                             @Nullable
                             com.pulumi.resources.CustomResourceOptions options)
        Get an existing Host resource's state with the given name, ID, and optional extra properties used to qualify the lookup.
        Parameters:
        name - The _unique_ name of the resulting resource.
        id - The _unique_ provider ID of the resource to lookup.
        state -
        options - Optional settings to control the behavior of the CustomResource.