Class DomainName

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.

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 cloudfront_domain_name 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 regional_domain_name 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. 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 depends_on = [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: regional_certificate_arn = aws_acm_certificate_validation.cert.certificate_arn.

Note: All arguments including the private key will be stored in the raw state as plain-text. Read more about sensitive data in state.

Example Usage

Edge Optimized (ACM Certificate)

using Pulumi;
using Aws = Pulumi.Aws;

class MyStack : Stack
{
public MyStack()
{
    var exampleDomainName = new Aws.ApiGateway.DomainName("exampleDomainName", new Aws.ApiGateway.DomainNameArgs
    {
        CertificateArn = aws_acm_certificate_validation.Example.Certificate_arn,
        DomainName = "api.example.com",
    });
    // Example DNS record using Route53.
    // Route53 is not specifically required; any DNS host can be used.
    var exampleRecord = new Aws.Route53.Record("exampleRecord", new Aws.Route53.RecordArgs
    {
        Aliases = 
        {
            new Aws.Route53.Inputs.RecordAliasArgs
            {
                EvaluateTargetHealth = true,
                Name = exampleDomainName.CloudfrontDomainName,
                ZoneId = exampleDomainName.CloudfrontZoneId,
            },
        },
        Name = exampleDomainName.Domain,
        Type = "A",
        ZoneId = aws_route53_zone.Example.Id,
    });
}

}

Edge Optimized (IAM Certificate)

using System.IO;
using Pulumi;
using Aws = Pulumi.Aws;

class MyStack : Stack
{
public MyStack()
{
    var exampleDomainName = new Aws.ApiGateway.DomainName("exampleDomainName", new Aws.ApiGateway.DomainNameArgs
    {
        CertificateBody = File.ReadAllText($"{path.Module}/example.com/example.crt"),
        CertificateChain = File.ReadAllText($"{path.Module}/example.com/ca.crt"),
        CertificateName = "example-api",
        CertificatePrivateKey = File.ReadAllText($"{path.Module}/example.com/example.key"),
        DomainName = "api.example.com",
    });
    // Example DNS record using Route53.
    // Route53 is not specifically required; any DNS host can be used.
    var exampleRecord = new Aws.Route53.Record("exampleRecord", new Aws.Route53.RecordArgs
    {
        Aliases = 
        {
            new Aws.Route53.Inputs.RecordAliasArgs
            {
                EvaluateTargetHealth = true,
                Name = exampleDomainName.CloudfrontDomainName,
                ZoneId = exampleDomainName.CloudfrontZoneId,
            },
        },
        Name = exampleDomainName.Domain,
        Type = "A",
        ZoneId = aws_route53_zone.Example.Id,
    });
    // See aws.route53.Zone for how to create this
}

}

Regional (ACM Certificate)

using Pulumi;
using Aws = Pulumi.Aws;

class MyStack : Stack
{
public MyStack()
{
    var exampleDomainName = new Aws.ApiGateway.DomainName("exampleDomainName", new Aws.ApiGateway.DomainNameArgs
    {
        DomainName = "api.example.com",
        EndpointConfiguration = new Aws.ApiGateway.Inputs.DomainNameEndpointConfigurationArgs
        {
            Types = "REGIONAL",
        },
        RegionalCertificateArn = aws_acm_certificate_validation.Example.Certificate_arn,
    });
    // Example DNS record using Route53.
    // Route53 is not specifically required; any DNS host can be used.
    var exampleRecord = new Aws.Route53.Record("exampleRecord", new Aws.Route53.RecordArgs
    {
        Aliases = 
        {
            new Aws.Route53.Inputs.RecordAliasArgs
            {
                EvaluateTargetHealth = true,
                Name = exampleDomainName.RegionalDomainName,
                ZoneId = exampleDomainName.RegionalZoneId,
            },
        },
        Name = exampleDomainName.Domain,
        Type = "A",
        ZoneId = aws_route53_zone.Example.Id,
    });
}

}

Regional (IAM Certificate)

using System.IO;
using Pulumi;
using Aws = Pulumi.Aws;

class MyStack : Stack
{
public MyStack()
{
    var exampleDomainName = new Aws.ApiGateway.DomainName("exampleDomainName", new Aws.ApiGateway.DomainNameArgs
    {
        CertificateBody = File.ReadAllText($"{path.Module}/example.com/example.crt"),
        CertificateChain = File.ReadAllText($"{path.Module}/example.com/ca.crt"),
        CertificatePrivateKey = File.ReadAllText($"{path.Module}/example.com/example.key"),
        DomainName = "api.example.com",
        EndpointConfiguration = new Aws.ApiGateway.Inputs.DomainNameEndpointConfigurationArgs
        {
            Types = "REGIONAL",
        },
        RegionalCertificateName = "example-api",
    });
    // Example DNS record using Route53.
    // Route53 is not specifically required; any DNS host can be used.
    var exampleRecord = new Aws.Route53.Record("exampleRecord", new Aws.Route53.RecordArgs
    {
        Aliases = 
        {
            new Aws.Route53.Inputs.RecordAliasArgs
            {
                EvaluateTargetHealth = true,
                Name = exampleDomainName.RegionalDomainName,
                ZoneId = exampleDomainName.RegionalZoneId,
            },
        },
        Name = exampleDomainName.Domain,
        Type = "A",
        ZoneId = aws_route53_zone.Example.Id,
    });
}

}
Inheritance
System.Object
Resource
CustomResource
DomainName
Inherited Members
System.Object.Equals(System.Object)
System.Object.Equals(System.Object, System.Object)
System.Object.GetHashCode()
System.Object.GetType()
System.Object.MemberwiseClone()
System.Object.ReferenceEquals(System.Object, System.Object)
System.Object.ToString()
Namespace: Pulumi.Aws.ApiGateway
Assembly: Pulumi.Aws.dll
Syntax
public class DomainName : CustomResource

Constructors

View Source

DomainName(String, DomainNameArgs, CustomResourceOptions)

Create a DomainName resource with the given unique name, arguments, and options.

Declaration
public DomainName(string name, DomainNameArgs args, CustomResourceOptions options = null)
Parameters
Type Name Description
System.String name

The unique name of the resource
DomainNameArgs args

The arguments used to populate this resource's properties
CustomResourceOptions options

A bag of options that control this resource's behavior

Properties

View Source

Arn

Amazon Resource Name (ARN)

Declaration
public Output<string> Arn { get; }
Property Value
Type Description
Output<System.String>
View Source

CertificateArn

The 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 certificate_name, certificate_body, certificate_chain, certificate_private_key, regional_certificate_arn, and regional_certificate_name.

Declaration
public Output<string> CertificateArn { get; }
Property Value
Type Description
Output<System.String>
View Source

CertificateBody

The certificate issued for the domain name being registered, in PEM format. Only valid for EDGE endpoint configuration type. Conflicts with certificate_arn, regional_certificate_arn, and regional_certificate_name.

Declaration
public Output<string> CertificateBody { get; }
Property Value
Type Description
Output<System.String>
View Source

CertificateChain

The 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 certificate_arn, regional_certificate_arn, and regional_certificate_name.

Declaration
public Output<string> CertificateChain { get; }
Property Value
Type Description
Output<System.String>
View Source

CertificateName

The unique name to use when registering this certificate as an IAM server certificate. Conflicts with certificate_arn, regional_certificate_arn, and regional_certificate_name. Required if certificate_arn is not set.

Declaration
public Output<string> CertificateName { get; }
Property Value
Type Description
Output<System.String>
View Source

CertificatePrivateKey

The private key associated with the domain certificate given in certificate_body. Only valid for EDGE endpoint configuration type. Conflicts with certificate_arn, regional_certificate_arn, and regional_certificate_name.

Declaration
public Output<string> CertificatePrivateKey { get; }
Property Value
Type Description
Output<System.String>
View Source

CertificateUploadDate

The upload date associated with the domain certificate.

Declaration
public Output<string> CertificateUploadDate { get; }
Property Value
Type Description
Output<System.String>
View Source

CloudfrontDomainName

The hostname created by Cloudfront to represent the distribution that implements this domain name mapping.

Declaration
public Output<string> CloudfrontDomainName { get; }
Property Value
Type Description
Output<System.String>
View Source

CloudfrontZoneId

For convenience, the hosted zone ID (Z2FDTNDATAQYW2) that can be used to create a Route53 alias record for the distribution.

Declaration
public Output<string> CloudfrontZoneId { get; }
Property Value
Type Description
Output<System.String>
View Source

Domain

The fully-qualified domain name to register

Declaration
public Output<string> Domain { get; }
Property Value
Type Description
Output<System.String>
View Source

EndpointConfiguration

Configuration block defining API endpoint information including type. Defined below.

Declaration
public Output<DomainNameEndpointConfiguration> EndpointConfiguration { get; }
Property Value
Type Description
Output<DomainNameEndpointConfiguration>
View Source

RegionalCertificateArn

The ARN for an AWS-managed certificate. AWS Certificate Manager is the only supported source. Used when a regional domain name is desired. Conflicts with certificate_arn, certificate_name, certificate_body, certificate_chain, and certificate_private_key.

Declaration
public Output<string> RegionalCertificateArn { get; }
Property Value
Type Description
Output<System.String>
View Source

RegionalCertificateName

The user-friendly name of the certificate that will be used by regional endpoint for this domain name. Conflicts with certificate_arn, certificate_name, certificate_body, certificate_chain, and certificate_private_key.

Declaration
public Output<string> RegionalCertificateName { get; }
Property Value
Type Description
Output<System.String>
View Source

RegionalDomainName

The hostname for the custom domain's regional endpoint.

Declaration
public Output<string> RegionalDomainName { get; }
Property Value
Type Description
Output<System.String>
View Source

RegionalZoneId

The hosted zone ID that can be used to create a Route53 alias record for the regional endpoint.

Declaration
public Output<string> RegionalZoneId { get; }
Property Value
Type Description
Output<System.String>
View Source

SecurityPolicy

The Transport Layer Security (TLS) version + cipher suite for this DomainName. The valid values are TLS_1_0 and TLS_1_2. Must be configured to perform drift detection.

Declaration
public Output<string> SecurityPolicy { get; }
Property Value
Type Description
Output<System.String>
View Source

Tags

Key-value map of resource tags

Declaration
public Output<ImmutableDictionary<string, object>> Tags { get; }
Property Value
Type Description
Output<System.Collections.Immutable.ImmutableDictionary<System.String, System.Object>>

Methods

View Source

Get(String, Input<String>, DomainNameState, CustomResourceOptions)

Get an existing DomainName resource's state with the given name, ID, and optional extra properties used to qualify the lookup.

Declaration
public static DomainName Get(string name, Input<string> id, DomainNameState state = null, CustomResourceOptions options = null)
Parameters
Type Name Description
System.String name

The unique name of the resulting resource.
Input<System.String> id

The unique provider ID of the resource to lookup.
DomainNameState state

Any extra arguments used during the lookup.
CustomResourceOptions options

A bag of options that control this resource's behavior
Returns
Type Description
DomainName