Create AWS Direct Connect Connections

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

Direct Connect connections require coordination with AWS Direct Connect locations and colocation facilities for physical cross-connects. Virtual interfaces and BGP sessions are configured via separate resources after the connection is established. The examples are intentionally small. Combine them with your own virtual interfaces, VPN backups, and routing configuration.

Create a basic Direct Connect connection

Organizations establishing hybrid cloud connectivity start by provisioning a connection at an AWS Direct Connect location, creating the physical link between your network equipment and AWS infrastructure.

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 its location code (e.g., “EqDC2”). The bandwidth property sets the connection speed; dedicated connections support 1Gbps, 10Gbps, 100Gbps, and 400Gbps, while hosted connections support lower tiers starting at 50Mbps. After provisioning, you coordinate with the colocation facility to establish the physical cross-connect.

Request a connection with MACsec capability

Connections requiring layer-2 encryption can request MACsec capability at provisioning time, encrypting traffic between your router and the AWS Direct Connect endpoint.

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 MACsec-capable connection. MACsec is only available on dedicated connections (1Gbps and above) and requires compatible hardware on your side. Not all Direct Connect locations support MACsec; verify location capabilities before provisioning.

Configure encryption mode for MACsec connections

After a MACsec-capable connection reaches Available state, you configure the encryption enforcement policy to control whether encryption is optional, preferred, or mandatory.

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 accepts three values: “no_encrypt” (encryption disabled), “should_encrypt” (encryption preferred but optional), and “must_encrypt” (encryption required). You can only set encryptionMode after the connection transitions to Available state. This example enforces mandatory encryption for all traffic on the connection.

Beyond these examples

These snippets focus on specific connection-level features: connection provisioning and bandwidth selection, and MACsec capability and encryption modes. They’re intentionally minimal rather than full hybrid connectivity solutions.

The examples assume pre-existing infrastructure such as AWS Direct Connect location with available capacity, physical network equipment at colocation facility, and cross-connect coordination with facility and AWS. They focus on provisioning the connection rather than the surrounding network architecture.

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

Service provider selection (providerName for hosted connections)
Resource tagging and organization
Connection lifecycle management (skipDestroy)
Virtual interfaces and BGP configuration (separate resources)

These omissions are intentional: the goal is to illustrate how each connection feature is wired, not provide drop-in hybrid 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 set the encryption mode for my connection?

You can only configure encryptionMode after the connection reaches an Available state. Attempting to set it earlier will fail.

What happens if I change requestMacsec after creating the connection?

Changing requestMacsec destroys and recreates the connection. Plan this setting carefully during initial creation.

Can I use MACsec with hosted connections?

No, MACsec (both requestMacsec and encryptionMode) is only available on dedicated connections with bandwidth of 1Gbps, 10Gbps, 100Gbps, or 400Gbps.

What encryption modes are available for MACsec connections?

Three modes are supported: no_encrypt (no encryption), should_encrypt (encrypt if possible), and must_encrypt (require encryption). These only apply to dedicated connections.

Connection Configuration

What bandwidth values are supported?

Dedicated connections support 1Gbps, 10Gbps, 100Gbps, and 400Gbps. Hosted connections support 50Mbps, 100Mbps, 200Mbps, 300Mbps, 400Mbps, 500Mbps, 1Gbps, 2Gbps, 5Gbps, 10Gbps, and 25Gbps. Values are case-sensitive.

What properties can't I change after creating a connection?

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

How do I specify the Direct Connect location?

Use the location property with a location code from the AWS DescribeLocations API (e.g., EqDC2). This value is immutable after creation.

Lifecycle Management

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

Set skipDestroy to true. This removes the connection from Pulumi state without deleting it from AWS.

What's the default MACsec setting for new connections?

requestMacsec defaults to false. You must explicitly set it to true during creation if you need MACsec capability.

Using a different cloud?

Explore networking guides for other cloud providers:

Azure Guides GCP Guides