Coming from an IaC tool to Encore

Encore is a backend development platform. You define APIs and services with its TypeScript or Go SDK and declare the infrastructure they use in the same application code. Encore derives an application model from those declarations and uses it throughout development and deployment.

When you deploy with Encore Cloud, Encore provisions supported resources in AWS or GCP. For self-hosted environments, your existing infrastructure tooling continues to provision them.

Supported resources include SQL databases, Pub/Sub, object storage, caches, cron jobs, and secrets. They are declared in application code using TypeScript or Go.

You do not need to replace your existing infrastructure configuration at once. Encore can manage supported application resources while your current IaC tool continues to manage shared, organization-level, or unsupported infrastructure.

Resource declarations

An Encore declaration identifies the logical resource the application uses without selecting its cloud implementation. For example, this declaration defines an orders database and its migration directory:


import { SQLDatabase } from "encore.dev/storage/sqldb";

const db = new SQLDatabase("orders", { migrations: "./migrations" });


import "encore.dev/storage/sqldb"

var db = sqldb.NewDatabase("orders", sqldb.DatabaseConfig{
	Migrations: "./migrations",
})

The logical resource is the named database used by the application. Its physical implementation may be local Postgres, a database provisioned by Encore Cloud, or a supported existing database connected to the environment.

With Encore Cloud, deployment properties are configured separately for each environment. When self-hosting, an infra config file maps each logical resource to infrastructure provisioned by your existing tooling.

Choose the deployment model

First decide whether the environment will use Encore Cloud or be self-hosted. With Encore Cloud, choose one of the following paths for each supported resource:

Resource path	Approach
Managed by Encore Cloud	Declare the resource in application code and configure its deployment properties per environment.
Already provisioned	Follow the resource-specific import guide to connect an Encore declaration to the physical resource and determine which settings Encore manages afterward.
Managed by your IaC tool	Keep shared and unsupported infrastructure in the existing configuration and connect to it as an external dependency.

Encore-managed resources can coexist with imported and external infrastructure. The ownership boundary can also change as services are migrated.

Importing connects a logical declaration to an existing physical resource. Do not continue applying changes from the IaC tool unless the resource's import guide says that ownership remains there.

For self-hosted environments, your IaC tool provisions all physical infrastructure. The infra config file maps supported Encore declarations to those resources.

How the concepts map

IaC concept	Encore equivalent
Resource declaration	A typed resource declaration in TypeScript or a package-level declaration in Go
Provider configuration	The cloud provider and infrastructure settings selected for an Encore Cloud environment
Infrastructure and deployment variables	Per-environment infrastructure configuration
Secret variables	Encore secrets for TypeScript or Go
Other application configuration	Application code or an external configuration service; Encore has no general-purpose non-secret configuration primitive
Explicit resource dependencies	Relationships derived from resource usage and service calls in the application model for application model
Modules	No direct equivalent; Encore services organize application code and the resources it uses
`count`, `for_each`, or generated resources	No direct equivalent for Encore resources; declarations must be statically discoverable
State file	The application model is derived from source; Encore Cloud keeps a separate record of the physical infrastructure managed for each environment
Plan	No direct equivalent; builds validate the application model, and Encore Cloud provides infrastructure change workflows
Apply	Encore Cloud applies managed infrastructure changes during deployment; for self-hosted environments, the existing IaC workflow provisions infrastructure

Use existing infrastructure

Encore Cloud can connect to selected existing resources instead of recreating them. Supported imports include:

AWS RDS and Google Cloud SQL instances
Amazon S3 and Google Cloud Storage buckets
Amazon SNS and Google Cloud Pub/Sub topics

At the environment level, Encore Cloud can also deploy into an existing GKE cluster or Google Cloud project.

Terraform can also reference infrastructure provisioned by Encore. The Encore Terraform Provider exposes Encore resources as read-only data sources, allowing an existing Terraform configuration to reference an Encore database, cache, or Pub/Sub topic.

What usually remains in IaC

Existing infrastructure configuration commonly continues to manage:

organization-level networking and account configuration
DNS and third-party providers
infrastructure without an Encore primitive
resources shared with systems outside the Encore application
resources whose number or identity is determined at runtime

Connect these resources to the application as external dependencies and store sensitive connection details in secrets for TypeScript or Go.

An external dependency remains outside Encore's provisioning lifecycle. Application code connects to it using its normal client or SDK, while your existing tooling continues to manage the resource.

Plan an incremental migration

Start with one service and list the infrastructure it uses. Then:

Inventory the resources used by the application and record which systems depend on them.
Map supported application resources to Encore primitives.
Decide whether the environment will use Encore Cloud or be self-hosted.
For Encore Cloud environments, decide which resources Encore should provision, connect to as existing resources, or leave under the current IaC workflow.
Run and test the migrated service locally with encore run and encore test.
For Encore Cloud, create an environment and follow the relevant import workflow for existing resources. For self-hosting, provision the physical resources and create the infra config mapping.
Deploy the service and verify its resource connections before migrating another service.

See Development workflow for local, preview, and production environments. For details about how Encore discovers resources and their relationships, see the application model for application model.

For strategies to migrate an existing backend one service at a time or through a catch-all handler, see Migrating an existing system to Encore.

Tool-specific guides

Terraform: map resources, modules, state, imports, and plan/apply workflows.
Pulumi: map projects, stacks, configuration, outputs, and Pulumi state.
OpenTofu: plan ownership boundaries, imports, and coexistence with existing OpenTofu configuration.
AWS CDK: map constructs, stacks, CloudFormation resources, and CDK deployment workflows.