> ## Documentation Index
> Fetch the complete documentation index at: https://artie.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# AWS VPC Lattice

> In BYOC deployments, connect Artie to databases spread across multiple AWS accounts and VPCs through VPC Lattice resource configurations, without peering, NLBs, or a PrivateLink endpoint service per VPC.

> [!NOTE]
>
> VPC Lattice connections are in early access and available for BYOC deployments, where Artie runs in a dedicated AWS account and VPC that you provision. Contact us through [Slack](https://artie.com/slack) or [email](mailto:hi@artie.com) to enable them. For Artie-hosted data planes, use [AWS PrivateLink](/docs/connection-options/privatelink.md).

## How VPC Lattice works

```mermaid theme={null}
flowchart LR
  subgraph "Artie account (BYOC)"
    direction TB
    A[Artie data plane] --> R1[Resource endpoint]
    A --> R2[Resource endpoint]
    A --> R3[Resource endpoint]
  end

  R1 -->|VPC Lattice| B
  R2 -->|VPC Lattice| B
  R3 -->|VPC Lattice| E

  subgraph "Workload account A"
    direction TB
    B[Resource gateway] --> C[("Database")]
    B --> D[("Database")]
  end

  subgraph "Workload account B"
    direction TB
    E[Resource gateway] --> F[("Database")]
  end
```

In each VPC that contains a database, you create a **resource gateway**, plus a **resource configuration** for each database you want Artie to replicate. You then share the resource configurations with your Artie account through AWS Resource Access Manager (RAM). Artie creates a **resource endpoint** for each shared database in the Artie VPC and connects through it, without VPC peering, a Transit Gateway, or a load balancer in your VPCs.

Connections only go one way. Artie can open connections to the hosts and ports in your resource configurations, and nothing else in your VPC is reachable. Your database sees traffic coming from the resource gateway's private IP addresses inside its own VPC.

## When to use VPC Lattice

The [AWS Well-Architected Framework](https://docs.aws.amazon.com/wellarchitected/latest/security-pillar/sec_securely_operate_multi_accounts.html) recommends separating workloads and environments into separate AWS accounts (best practice **SEC01-BP01, Separate workloads using accounts**). Accounts are a strong boundary for security, billing, and access. A BYOC deployment follows the same practice by running Artie in its own account. Your databases often end up spread across many other accounts, in VPCs that aren't peered with each other or with the Artie VPC.

[AWS PrivateLink](/docs/connection-options/privatelink.md) needs an endpoint service and a Network Load Balancer in every VPC that contains a database. VPC Lattice replaces those with a resource gateway and a resource configuration for each database, which you can deploy the same way in every account.

Use VPC Lattice when:

* Your databases are in AWS accounts other than your Artie account, or in VPCs that aren't connected to the Artie VPC.
* You want each workload account to control exactly which databases Artie can reach, through its own RAM share.
* Your databases are on Amazon RDS or Aurora, and you want connections to keep working through failover without maintaining NLB target groups.

## What you'll need

* A BYOC deployment of Artie, and the account ID of your Artie account
* Databases in the same AWS region as the Artie VPC. Resource configurations in another region can't be reached from the Artie VPC.
* Permission to create VPC Lattice resource gateways, resource configurations, and AWS RAM resource shares in each workload account
* A subnet in at least one of the Artie VPC's availability zone IDs, in every VPC that contains a database

## Setting up a VPC Lattice connection

Repeat steps 1 to 4 in each workload account that contains databases you want to replicate.

**1. Create a resource gateway**

In the AWS console, go to **VPC > PrivateLink and Lattice > Resource gateways** and create a resource gateway in the VPC that contains your databases. Select subnets in as many availability zones as possible, and include at least one subnet in an availability zone ID that the Artie VPC also uses. Without a shared availability zone, connections from Artie time out. See [Verify availability zone IDs overlap](#verify-availability-zone-ids-overlap).

Attach a security group that allows outbound TCP traffic to your databases on their ports (e.g. `5432` for PostgreSQL or `3306` for MySQL).

**2. Allow the resource gateway in your database security group**

Add an inbound rule to each database's security group that allows TCP traffic on the database port from the resource gateway's security group. Without this rule, connections from Artie time out.

**3. Create a resource configuration for each database**

Go to **VPC > PrivateLink and Lattice > Resource configurations** and create one resource configuration for each database, associated with the resource gateway from step 1.

* For Amazon RDS and Aurora, use the **ARN** type and select the database. The database has to be private. VPC Lattice rejects a resource configuration for a publicly accessible database. Artie can then connect with your usual RDS endpoint hostname, and the connection keeps working through failover.
* For other databases, such as a self-managed database on EC2, use the **Single** type with the database's domain name or private IP address and port.

Artie connects through resource endpoints and doesn't use service networks, so you can turn off association with shareable service networks.

**4. Share the resource configurations with your Artie account**

Go to **Resource Access Manager > Create resource share**. Add the resource configurations from step 3 and add your Artie account ID as a principal.

If resource sharing with AWS Organizations is turned on in RAM, the share is available immediately. Otherwise, your Artie account receives an invitation, and we accept it.

**5. Send us the resource configuration ARNs**

Reach out to us through [Slack](https://artie.com/slack) or [email](mailto:hi@artie.com) with the ARN of each resource configuration and the database it represents. We create a resource endpoint for each one in the Artie VPC and confirm when it is ready.

**6. Create your pipeline**

Once we confirm the connection, create a pipeline. For ARN resource configurations, use your database's RDS endpoint hostname as the source address. For other resource configurations, we will send you the hostname to use.

### Example: Terraform for one workload account

If you manage many accounts, define these resources once and deploy them to every workload account with Terraform or [CloudFormation StackSets](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/what-is-cfnstacksets.html). This example uses the AWS provider 5.85.0 and later, and shares one private RDS PostgreSQL instance with an Artie account in the same AWS Organization.

```hcl theme={null}
terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = ">= 5.85.0"
    }
  }
}

data "aws_db_instance" "orders" {
  db_instance_identifier = "orders-prod"
}

resource "aws_security_group" "artie_resource_gateway" {
  name   = "artie-resource-gateway"
  vpc_id = "vpc-0a1b2c3d4e5f67890"

  egress {
    from_port   = 5432
    to_port     = 5432
    protocol    = "tcp"
    cidr_blocks = ["10.20.0.0/16"]
  }
}

# Allow the resource gateway to reach the database.
resource "aws_vpc_security_group_ingress_rule" "orders_from_artie" {
  security_group_id            = "sg-0d4c3b2a1f0e98765" # the database's security group
  referenced_security_group_id = aws_security_group.artie_resource_gateway.id
  ip_protocol                  = "tcp"
  from_port                    = 5432
  to_port                      = 5432
}

resource "aws_vpclattice_resource_gateway" "artie" {
  name               = "artie"
  vpc_id             = "vpc-0a1b2c3d4e5f67890"
  subnet_ids         = ["subnet-0aa11bb22cc33dd44", "subnet-0ee55ff66aa77bb88", "subnet-0cc99dd00ee11ff22"]
  security_group_ids = [aws_security_group.artie_resource_gateway.id]
}

resource "aws_vpclattice_resource_configuration" "orders" {
  name                                           = "artie-orders-prod"
  resource_gateway_identifier                    = aws_vpclattice_resource_gateway.artie.id
  type                                           = "ARN"
  allow_association_to_shareable_service_network = false

  resource_configuration_definition {
    arn_resource {
      arn = data.aws_db_instance.orders.db_instance_arn
    }
  }
}

resource "aws_ram_resource_share" "artie" {
  name                      = "artie"
  allow_external_principals = false
}

resource "aws_ram_resource_association" "orders" {
  resource_arn       = aws_vpclattice_resource_configuration.orders.arn
  resource_share_arn = aws_ram_resource_share.artie.arn
}

resource "aws_ram_principal_association" "artie" {
  principal          = "210987654321" # your Artie account
  resource_share_arn = aws_ram_resource_share.artie.arn
}

# Send these values to Artie.
output "artie_resource_share_arn" {
  description = "RAM resource share that contains the resource configurations"
  value       = aws_ram_resource_share.artie.arn
}

output "artie_resource_configurations" {
  description = "One entry per database: the resource configuration ARN and the hostname to use as the source address"
  value = {
    (aws_vpclattice_resource_configuration.orders.name) = {
      resource_configuration_arn = aws_vpclattice_resource_configuration.orders.arn
      hostname                   = data.aws_db_instance.orders.address
      port                       = data.aws_db_instance.orders.db_instance_port
    }
  }
}
```

After you run `terraform apply`, send us the `artie_resource_share_arn` and `artie_resource_configurations` values from `terraform output -json`.

## Troubleshooting

> **Advanced debugging: connection is timing out**
>
> Work through these checks in order.
>
> ### Verify availability zone IDs overlap
>
> VPC Lattice requires at least one availability zone in common between the resource endpoint in the Artie VPC and your resource gateway. If there is no overlap, traffic has no path and the connection will time out.
>
> > [!WARNING]
> >
> > Compare **AZ IDs** (e.g. `use1-az1`), not AZ names (e.g. `us-east-1a`). AWS maps the same AZ name to different physical zones in each account, so names alone are unreliable.
>
> ### Check both security groups
>
> The resource gateway's security group needs an outbound rule to the database port, and the database's security group needs an inbound rule from the resource gateway's security group. Your database sees connections coming from the resource gateway's IP addresses, not from the Artie VPC, so rules that only allow the Artie VPC's CIDR won't match.
>
> ### Check how the resource gateway resolves DNS
>
> If a **Single** resource configuration uses a domain name that resolves through a Route 53 private hosted zone or your own DNS server, the resource gateway's DNS resolution must be set to `IN_VPC`. This setting can only be chosen when you create the resource gateway.

## Frequently asked questions

### Which region is VPC Lattice available in?

VPC Lattice connections are available in the region of your Artie VPC. Reach out to us if your databases are in a different region.

### Do I need a resource gateway for every database?

No. You need one resource gateway per VPC. Every resource configuration in that VPC can use the same resource gateway.

### How do I add another database later?

Create a resource configuration for the database, add it to your existing resource share, and send us its ARN. We add a resource endpoint for it. You don't need to change the resource gateway unless the database is in a new VPC.

### How do I connect to my read-only database for backfills?

Create a resource configuration for the read replica, add it to the same resource share, and send us its ARN. See [Backfills](/docs/pipelines/backfill.md) for how Artie uses a read replica.

### How is VPC Lattice billed?

AWS bills each resource endpoint by the hour, plus a charge per GB of data processed, in your Artie account. See [AWS PrivateLink pricing](https://aws.amazon.com/privatelink/pricing/) for current rates.

### Can I use VPC Lattice and PrivateLink together?

Yes. They are separate connection methods, and each pipeline uses one of them. For example, you can keep an existing [PrivateLink](/docs/connection-options/privatelink.md) connection for one database and use VPC Lattice for databases in other accounts.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.