Create AWS Direct Connect Connections

The aws:directconnect/connection:Connection resource, part of the Pulumi AWS provider, provisions the physical Direct Connect connection itself: bandwidth allocation, location placement, and optional MACsec encryption capability. This guide focuses on three capabilities: basic connection creation, MACsec capability requests, and encryption mode configuration.

Direct Connect connections require an AWS Direct Connect location with available capacity. For MACsec-enabled connections, you also need compatible network equipment at your colocation facility. The examples are intentionally small. Combine them with virtual interfaces, BGP configuration, and your own network infrastructure.

Create a basic Direct Connect connection

Most deployments start by establishing a physical connection at an AWS Direct Connect location, creating the foundation for private connectivity between your data center and AWS.

import * as pulumi from "@pulumi/pulumi";
import * as aws from "@pulumi/aws";

const hoge = new aws.directconnect.Connection("hoge", {
    name: "tf-dx-connection",
    bandwidth: "1Gbps",
    location: "EqDC2",
});

import pulumi
import pulumi_aws as aws

hoge = aws.directconnect.Connection("hoge",
    name="tf-dx-connection",
    bandwidth="1Gbps",
    location="EqDC2")

package main

import (
	"github.com/pulumi/pulumi-aws/sdk/v7/go/aws/directconnect"
	"github.com/pulumi/pulumi/sdk/v3/go/pulumi"
)

func main() {
	pulumi.Run(func(ctx *pulumi.Context) error {
		_, err := directconnect.NewConnection(ctx, "hoge", &directconnect.ConnectionArgs{
			Name:      pulumi.String("tf-dx-connection"),
			Bandwidth: pulumi.String("1Gbps"),
			Location:  pulumi.String("EqDC2"),
		})
		if err != nil {
			return err
		}
		return nil
	})
}

using System.Collections.Generic;
using System.Linq;
using Pulumi;
using Aws = Pulumi.Aws;

return await Deployment.RunAsync(() => 
{
    var hoge = new Aws.DirectConnect.Connection("hoge", new()
    {
        Name = "tf-dx-connection",
        Bandwidth = "1Gbps",
        Location = "EqDC2",
    });

});

package generated_program;

import com.pulumi.Context;
import com.pulumi.Pulumi;
import com.pulumi.core.Output;
import com.pulumi.aws.directconnect.Connection;
import com.pulumi.aws.directconnect.ConnectionArgs;
import java.util.List;
import java.util.ArrayList;
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 hoge = new Connection("hoge", ConnectionArgs.builder()
            .name("tf-dx-connection")
            .bandwidth("1Gbps")
            .location("EqDC2")
            .build());

    }
}

resources:
  hoge:
    type: aws:directconnect:Connection
    properties:
      name: tf-dx-connection
      bandwidth: 1Gbps
      location: EqDC2

The location property specifies the AWS Direct Connect facility using a location code (find available locations via the DescribeLocations API). The bandwidth property sets the connection speed; valid values depend on whether you’re ordering a dedicated or hosted connection. The name property provides a human-readable identifier for the connection.

Request a connection with MACsec capability

Organizations with strict security requirements can request connections that support MAC Security (MACsec) for layer 2 encryption.

import * as pulumi from "@pulumi/pulumi";
import * as aws from "@pulumi/aws";

const example = new aws.directconnect.Connection("example", {
    name: "tf-dx-connection",
    bandwidth: "10Gbps",
    location: "EqDA2",
    requestMacsec: true,
});

import pulumi
import pulumi_aws as aws

example = aws.directconnect.Connection("example",
    name="tf-dx-connection",
    bandwidth="10Gbps",
    location="EqDA2",
    request_macsec=True)

package main

import (
	"github.com/pulumi/pulumi-aws/sdk/v7/go/aws/directconnect"
	"github.com/pulumi/pulumi/sdk/v3/go/pulumi"
)

func main() {
	pulumi.Run(func(ctx *pulumi.Context) error {
		_, err := directconnect.NewConnection(ctx, "example", &directconnect.ConnectionArgs{
			Name:          pulumi.String("tf-dx-connection"),
			Bandwidth:     pulumi.String("10Gbps"),
			Location:      pulumi.String("EqDA2"),
			RequestMacsec: pulumi.Bool(true),
		})
		if err != nil {
			return err
		}
		return nil
	})
}

using System.Collections.Generic;
using System.Linq;
using Pulumi;
using Aws = Pulumi.Aws;

return await Deployment.RunAsync(() => 
{
    var example = new Aws.DirectConnect.Connection("example", new()
    {
        Name = "tf-dx-connection",
        Bandwidth = "10Gbps",
        Location = "EqDA2",
        RequestMacsec = true,
    });

});

package generated_program;

import com.pulumi.Context;
import com.pulumi.Pulumi;
import com.pulumi.core.Output;
import com.pulumi.aws.directconnect.Connection;
import com.pulumi.aws.directconnect.ConnectionArgs;
import java.util.List;
import java.util.ArrayList;
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 Connection("example", ConnectionArgs.builder()
            .name("tf-dx-connection")
            .bandwidth("10Gbps")
            .location("EqDA2")
            .requestMacsec(true)
            .build());

    }
}

resources:
  example:
    type: aws:directconnect:Connection
    properties:
      name: tf-dx-connection
      bandwidth: 10Gbps
      location: EqDA2
      requestMacsec: true

Setting requestMacsec to true provisions a connection capable of MACsec encryption. MACsec is only available on dedicated connections (10Gbps and higher bandwidth). Not all Direct Connect locations support MACsec; verify availability before requesting. The connection is provisioned with MACsec capability but encryption is not yet active.

Configure encryption mode for MACsec connections

After a MACsec-capable connection reaches Available state, you configure the encryption mode to enforce or allow encryption on the physical link.

import * as pulumi from "@pulumi/pulumi";
import * as aws from "@pulumi/aws";

const example = new aws.directconnect.Connection("example", {
    name: "tf-dx-connection",
    bandwidth: "10Gbps",
    location: "EqDC2",
    requestMacsec: true,
    encryptionMode: "must_encrypt",
});

import pulumi
import pulumi_aws as aws

example = aws.directconnect.Connection("example",
    name="tf-dx-connection",
    bandwidth="10Gbps",
    location="EqDC2",
    request_macsec=True,
    encryption_mode="must_encrypt")

package main

import (
	"github.com/pulumi/pulumi-aws/sdk/v7/go/aws/directconnect"
	"github.com/pulumi/pulumi/sdk/v3/go/pulumi"
)

func main() {
	pulumi.Run(func(ctx *pulumi.Context) error {
		_, err := directconnect.NewConnection(ctx, "example", &directconnect.ConnectionArgs{
			Name:           pulumi.String("tf-dx-connection"),
			Bandwidth:      pulumi.String("10Gbps"),
			Location:       pulumi.String("EqDC2"),
			RequestMacsec:  pulumi.Bool(true),
			EncryptionMode: pulumi.String("must_encrypt"),
		})
		if err != nil {
			return err
		}
		return nil
	})
}

using System.Collections.Generic;
using System.Linq;
using Pulumi;
using Aws = Pulumi.Aws;

return await Deployment.RunAsync(() => 
{
    var example = new Aws.DirectConnect.Connection("example", new()
    {
        Name = "tf-dx-connection",
        Bandwidth = "10Gbps",
        Location = "EqDC2",
        RequestMacsec = true,
        EncryptionMode = "must_encrypt",
    });

});

package generated_program;

import com.pulumi.Context;
import com.pulumi.Pulumi;
import com.pulumi.core.Output;
import com.pulumi.aws.directconnect.Connection;
import com.pulumi.aws.directconnect.ConnectionArgs;
import java.util.List;
import java.util.ArrayList;
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 Connection("example", ConnectionArgs.builder()
            .name("tf-dx-connection")
            .bandwidth("10Gbps")
            .location("EqDC2")
            .requestMacsec(true)
            .encryptionMode("must_encrypt")
            .build());

    }
}

resources:
  example:
    type: aws:directconnect:Connection
    properties:
      name: tf-dx-connection
      bandwidth: 10Gbps
      location: EqDC2
      requestMacsec: true
      encryptionMode: must_encrypt

The encryptionMode property controls MACsec behavior. Setting it to “must_encrypt” requires all traffic to be encrypted; the connection drops unencrypted traffic. Other valid values are “should_encrypt” (prefers encryption but allows unencrypted) and “no_encrypt” (disables encryption). You can only set encryptionMode after the connection reaches Available state, and it requires MACsec-capable hardware on your side of the connection.

Beyond these examples

These snippets focus on specific connection-level features: basic connection provisioning and MACsec capability and encryption modes. They’re intentionally minimal rather than full network integrations.

The examples assume pre-existing infrastructure such as AWS Direct Connect location availability and customer network equipment at colocation facility. They focus on provisioning the connection rather than configuring the full Direct Connect setup.

To keep things focused, common connection patterns are omitted, including:

Service provider selection (providerName for hosted connections)
Connection tagging and metadata (tags)
Virtual interfaces and BGP configuration
Connection redundancy and failover

These omissions are intentional: the goal is to illustrate how each connection feature is wired, not provide drop-in networking modules. See the Direct Connect Connection resource reference for all available configuration options.

Let's create AWS Direct Connect Connections

Get started with Pulumi Cloud, then follow our quick setup guide to deploy this infrastructure.

Try Pulumi Cloud for FREE

Frequently Asked Questions

MACsec & Encryption

When can I configure the encryption mode for my connection?

You can only set encryptionMode after the connection reaches an Available state. Attempting to configure it during initial creation may fail or be ignored.

Can I use MACsec with hosted connections?

No, MAC Security (MACsec) is only available on dedicated connections. Both requestMacsec and encryptionMode require a dedicated connection type.

What encryption modes are available for MACsec connections?

Three modes are supported: no_encrypt, should_encrypt, and must_encrypt. These can only be configured on dedicated connections with MACsec enabled.

Connection Configuration

What bandwidth options are available and why does casing matter?

Bandwidth values are case-sensitive. Dedicated connections support 1Gbps, 10Gbps, 100Gbps, and 400Gbps. Hosted connections support 50Mbps, 100Mbps, 200Mbps, 300Mbps, 400Mbps, 500Mbps, 1Gbps, 2Gbps, 5Gbps, 10Gbps, and 25Gbps. Use exact casing (e.g., 1Gbps, not 1gbps).

What properties can't be changed after creation?

Five properties are immutable: bandwidth, location, name, providerName, and requestMacsec. Changing any of these requires destroying and recreating the connection.

What happens if I change the requestMacsec setting?

Changing requestMacsec after creation causes the connection to be destroyed and recreated, resulting in downtime. Plan accordingly if MACsec requirements change.

Lifecycle Management

How do I prevent my connection from being deleted during destroy operations?

Set skipDestroy to true. This removes the connection from Pulumi state without deleting it from AWS, allowing you to manage it outside of Pulumi or import it later.

How do I find valid location codes for my connection?

Use the AWS Direct Connect DescribeLocations API to retrieve available location codes. Specify the locationCode value in the location property.

Using a different cloud?

Explore networking guides for other cloud providers:

Azure Guides GCP Guides