> ## Documentation Index
> Fetch the complete documentation index at: https://cdktn.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Providers - CDK Terrain
> Providers allow Terraform to communicate with external APIs. Learn to define providers in a CDK Terrain application.
export const PluginOverviewDiagram = () => {
return ;
};
A [provider](https://developer.hashicorp.com/terraform/language/providers) is a plugin that lets Terraform manage an external API. In your CDK Terrain (CDKTN) application, you use your preferred programming language to define the [resources](/concepts/resources) you want Terraform to manage on one or more providers.
You can install pre-built providers packaged with the required code bindings for your language or add providers to the [`cdktf.json`](/create-and-deploy/configuration-file) file and generate code bindings manually. To use providers in your application, you can import them from the Terraform Registry or the [OpenTofu Registry](https://search.opentofu.org/), or from your local machine.
## What Are Providers?
Provider plugins like the [AWS provider](https://registry.terraform.io/providers/hashicorp/aws/latest) or the [cloud-init provider](https://registry.terraform.io/providers/hashicorp/cloudinit/latest/docs) act as a translation layer that allows Terraform to communicate with many different cloud providers, databases, and services.
Terraform uses providers to provision [resources](https://developer.hashicorp.com/terraform/language/resources), which describe one or more infrastructure objects like virtual networks and compute instances. Each provider on the [Terraform Registry](https://registry.terraform.io/) (also available on the [OpenTofu Registry](https://search.opentofu.org/)) has documentation detailing available resources and their configuration options.
## Install Pre-Built Providers
It can take several minutes for CDKTN to generate the code bindings for providers with very large schemas, so we offer several popular providers as pre-built packages. Pre-built providers are a completely optional performance optimization, and you may prefer to generate the code bindings for these providers yourself. For example, you may want to use a different version of that provider than the one in the pre-built package. The [Terraform CDK Providers](https://github.com/orgs/cdktn/repositories?q=cdktn-provider-) page has a complete list, but available pre-built providers include the following options:
* [AWS Provider](https://cdk.tf/provider/aws)
* [Google Provider](https://cdk.tf/provider/google)
* [Azure Provider](https://cdk.tf/provider/azurerm)
* [Kubernetes Provider](https://cdk.tf/provider/kubernetes)
* [Docker Provider](https://cdk.tf/provider/docker)
* [Github Provider](https://cdk.tf/provider/github)
* [Null Provider](https://cdk.tf/provider/null)
We regularly publish these packages to NPM / PyPi, and you can treat them like any other dependency. The following example shows how to install the AWS provider in TypeScript / Node.
```
npm install @cdktn/provider-aws
```
When you use `npm install` to install a pre-built provider, you should not define that provider again in your `cdktf.json` file. If you receive errors while running `cdktn synth` because of duplicate providers, remove the duplicates from your `cdktf.json` file, delete `tsbuildinfo.json`, and run `cdktn synth` again.
## Add Providers with CLI
Use the [`provider add` command](/cli-reference/commands#provider-add) to automatically install a pre-built provider if available. If a pre-built provider is not available, CDKTN uses local provider bindings.
## Import Providers
CDK Terrain lets you import Terraform [providers](https://developer.hashicorp.com/terraform/language/providers) to your project.
This TypeScript example project has a `main.ts` file that defines AWS resources.
```ts TypeScript theme={null}
import { Construct } from "constructs";
import { TerraformStack, TerraformVariable, Token } from "cdktn";
import { AwsProvider } from "./.gen/providers/aws/provider";
import { Instance } from "./.gen/providers/aws/instance";
export class ProvidersStack extends TerraformStack {
constructor(scope: Construct, id: string) {
super(scope, id);
new AwsProvider(this, "aws", {
region: "us-east-1",
});
const instance = new Instance(this, "Hello", {
ami: "ami-2757f631",
instanceType: "t2.micro",
});
}
}
```
```java Java theme={null}
import software.constructs.Construct;
import io.cdktn.cdktn.App;
import io.cdktn.cdktn.TerraformStack;
import imports.aws.provider.AwsProvider;
import imports.aws.provider.AwsProviderConfig;
import imports.aws.instance.Instance;
import imports.aws.instance.InstanceConfig;
public class MainImportProviders extends TerraformStack {
public MainImportProviders(Construct scope, String id){
super(scope, id);
new AwsProvider(this, "aws", AwsProviderConfig.builder()
.region("us-east-1")
.build()
);
new Instance(this, "hello", InstanceConfig.builder()
.ami("ami-2757f631")
.instanceType("t2.micro")
.build()
);
}
public static void main(String[] args) {
final App app = new App();
new MainImportProviders(app, "hello-terraform");
app.synth();
}
}
```
```python Python theme={null}
from constructs import Construct
from cdktn import App, TerraformStack
from imports.aws.provider import AwsProvider
from imports.aws.instance import Instance
class SimpleProviderStack(TerraformStack):
def __init__(self, scope: Construct, id: str):
super().__init__(scope, id)
AwsProvider(self, "aws",
region = "us-east-1",
)
Instance(self, "hello",
ami = "ami-2757f631",
instance_type = "t2.micro",
)
app = App()
SimpleProviderStack(app, "provider-stack")
app.synth()
```
```csharp C# theme={null}
using System;
using System.IO;
using System.Collections.Generic;
using System.Linq;
using Constructs;
using Io.Cdktn;
using aws.Provider;
using aws.Instance;
namespace Examples
{
class ProviderStack : TerraformStack
{
public ProviderStack(Construct scope, string name) : base(scope, name)
{
// Add this to your project's .csproj file:
//
//
//
new AwsProvider(this, "aws", new AwsProviderConfig
{
Region = "eu-central-1"
});
new Instance(this, "instance", new InstanceConfig
{
Ami = "ami-2757f631",
InstanceType = "t2.micro"
});
}
}
}
```
```go Go theme={null}
import (
"github.com/aws/constructs-go/constructs/v10"
"github.com/aws/jsii-runtime-go"
"github.com/open-constructs/cdk-terrain-go/cdktn"
"github.com/open-constructs/cdk-terrain/examples/go/documentation/generated/hashicorp/aws/instance"
aws "github.com/open-constructs/cdk-terrain/examples/go/documentation/generated/hashicorp/aws/provider"
)
func NewProvidersStack(scope constructs.Construct, name string) cdktn.TerraformStack {
stack := cdktn.NewTerraformStack(scope, &name)
aws.NewAwsProvider(stack, jsii.String("aws"), &aws.AwsProviderConfig{
Region: jsii.String(("us-east-1")),
})
instance := instance.NewInstance(stack, jsii.String("hello"), &instance.InstanceConfig{
Ami: jsii.String("ami-2757f631"),
InstanceType: jsii.String("t2.micro"),
})
return stack
}
```
### Add Provider to `cdktf.json`
To use a new provider, first add it to the `"terraformProviders"` array in the [`cdktf.json` file](/create-and-deploy/configuration-file).
The following example adds the [DNS Simple](https://registry.terraform.io/providers/dnsimple/dnsimple/latest/docs) provider.
```json theme={null}
{
"language": "typescript",
"app": "npm run --silent compile && node main.js",
"terraformProviders": ["aws@~> 2.0", "dnsimple/dnsimple"]
}
```
### Generate Classes
Go to the working directory and run `cdktn get` to create the appropriate TypeScript classes for the provider automatically.
```bash theme={null}
cdktn get
⠋ downloading and generating providers...
```
```bash theme={null}
Generated typescript constructs in the output directory: .gen
```
### Import Classes
Import and use the generated classes in your application. The following example imports the `DnsimpleProvider` and `Record` resources from `./.gen/providers/dnsimple` and defines them.
```ts TypeScript theme={null}
import { Construct } from "constructs";
import { TerraformStack, TerraformVariable, Token } from "cdktn";
import { AwsProvider } from "./.gen/providers/aws/provider";
import { Instance } from "./.gen/providers/aws/instance";
import { DnsimpleProvider } from "./.gen/providers/dnsimple/provider";
import { ZoneRecord } from "./.gen/providers/dnsimple/zone-record";
export class ProvidersStack extends TerraformStack {
constructor(scope: Construct, id: string) {
super(scope, id);
new AwsProvider(this, "aws", {
region: "us-east-1",
});
const instance = new Instance(this, "Hello", {
ami: "ami-2757f631",
instanceType: "t2.micro",
});
const dnsimpleToken = new TerraformVariable(this, "dnsimpleToken", {
type: "string",
description: "dnsimple token",
sensitive: true,
});
const dnsimpleAccount = new TerraformVariable(this, "dnsimpleAccount", {
type: "string",
description: "dnsimple account",
sensitive: true,
});
new DnsimpleProvider(this, "dnsimple", {
token: dnsimpleToken.stringValue,
account: dnsimpleAccount.stringValue,
});
new ZoneRecord(this, "web-www", {
zoneName: "example.com",
name: "web",
value: instance.publicIp,
type: "A",
});
}
}
```
```java Java theme={null}
import io.cdktn.cdktn.TerraformVariableConfig;
import software.constructs.Construct;
import io.cdktn.cdktn.TerraformStack;
import io.cdktn.cdktn.TerraformVariable;
import imports.aws.instance.Instance;
import imports.aws.instance.InstanceConfig;
import imports.aws.provider.AwsProvider;
import imports.aws.provider.AwsProviderConfig;
import imports.dnsimple.provider.DnsimpleProvider;
import imports.dnsimple.provider.DnsimpleProviderConfig;
import imports.dnsimple.zone_record.ZoneRecord;
import imports.dnsimple.zone_record.ZoneRecordConfig;
public class MainImportClasses extends TerraformStack {
public MainImportClasses(Construct scope, String id){
super(scope, id);
new AwsProvider(this, "aws", AwsProviderConfig.builder()
.region("us-east-1")
.build()
);
Instance instance = new Instance(this, "Hello", InstanceConfig.builder()
.ami("ami-2757f631")
.instanceType("t2.micro")
.build()
);
TerraformVariable dnsimpleToken = new TerraformVariable(this, "dnsimpleToken", TerraformVariableConfig.builder()
.type("string")
.description("dnsimple token")
.sensitive(true)
.build()
);
TerraformVariable dnsimpleAccount = new TerraformVariable(this, "dnsimpleAccount", TerraformVariableConfig.builder()
.type("string")
.description("dnsimple account")
.sensitive(true)
.build()
);
new DnsimpleProvider(this, "dnsimple", DnsimpleProviderConfig.builder()
.token(dnsimpleToken.getStringValue())
.account(dnsimpleAccount.getStringValue())
.build()
);
new ZoneRecord(this, "web-www", ZoneRecordConfig.builder()
.zoneName("example.com")
.name("web")
.value(instance.getPublicIp())
.type("A")
.build()
);
}
public static void main(String[] args) {
final App app = new App();
new MainImportClasses(app, "hello-terraform");
app.synth();
}
}
```
```python Python theme={null}
import os
from constructs import Construct
from cdktn import App, TerraformStack, TerraformVariable, Token
from imports.aws.provider import AwsProvider
from imports.dnsimple.provider import DnsimpleProvider
from imports.dnsimple.zone_record import ZoneRecord
class ProviderStack(TerraformStack):
def __init__(self, scope: Construct, id: str):
super().__init__(scope, id)
AwsProvider(self, "aws",
region = "us-east-1",
)
instance = Instance(self, "Hello",
ami = "ami-2757f631",
instance_type = "t2.micro",
)
dnsimpleToken = TerraformVariable(self, "dnsimpleToken",
type = "string",
description = "dnsimple token",
sensitive = True
)
dnsimpleAccount = TerraformVariable(self, "dnsimpleAccount",
type = "string",
description = "dnsimple account",
sensitive = True
)
DnsimpleProvider(self, "dnsimple",
token = dnsimpleToken.string_value,
account = dnsimpleAccount.string_value
)
ZoneRecord(self, "web-www",
zone_name = "example.com",
name = "web",
value = instance.public_ip,
type = "A"
)
app = App()
ProviderStack(app, "provider-stack")
app.synth()
```
```csharp C# theme={null}
using System;
using System.IO;
using System.Collections.Generic;
using System.Linq;
using Constructs;
using Io.Cdktn;
using aws.Provider;
using aws.Instance;
using dnsimple.Provider;
using dnsimple.ZoneRecord;
namespace Examples
{
class ProviderClassesStack : TerraformStack
{
public ProviderClassesStack(Construct scope, string name) : base(scope, name)
{
// Add this to your project's .csproj file:
//
//
//
//
//
//
new AwsProvider(this, "aws", new AwsProviderConfig
{
Region = "eu-east-1"
});
Instance instance = new Instance(this, "instance", new InstanceConfig
{
Ami = "ami-2757f631",
InstanceType = "t2.micro"
});
TerraformVariable dnsimpleToken = new TerraformVariable(this, "dnsimpleToken", new TerraformVariableConfig
{
Type = "string",
Description = "dnsimple token",
Sensitive = true
});
TerraformVariable dnsimpleAccount = new TerraformVariable(this, "dnsimpleAccount", new TerraformVariableConfig
{
Type = "string",
Description = "dnsimple account",
Sensitive = true
});
new DnsimpleProvider(this, "dnsimple", new DnsimpleProviderConfig
{
Token = dnsimpleToken.StringValue,
Account = dnsimpleAccount.StringValue
});
new ZoneRecord(this, "web-www", new ZoneRecordConfig
{
ZoneName = "example.com",
Name = "web",
Value = instance.PublicIp,
Type = "A"
});
}
}
}
```
```go Go theme={null}
import (
"github.com/aws/constructs-go/constructs/v10"
"github.com/aws/jsii-runtime-go"
"github.com/open-constructs/cdk-terrain-go/cdktn"
dnsimple "github.com/open-constructs/cdk-terrain/examples/go/documentation/generated/dnsimple/dnsimple/provider"
"github.com/open-constructs/cdk-terrain/examples/go/documentation/generated/dnsimple/dnsimple/zonerecord"
"github.com/open-constructs/cdk-terrain/examples/go/documentation/generated/hashicorp/aws/instance"
aws "github.com/open-constructs/cdk-terrain/examples/go/documentation/generated/hashicorp/aws/provider"
)
func NewProvidersStack(scope constructs.Construct, name string) cdktn.TerraformStack {
stack := cdktn.NewTerraformStack(scope, &name)
aws.NewAwsProvider(stack, jsii.String("aws"), &aws.AwsProviderConfig{
Region: jsii.String(("us-east-1")),
})
instance := instance.NewInstance(stack, jsii.String("hello"), &instance.InstanceConfig{
Ami: jsii.String("ami-2757f631"),
InstanceType: jsii.String("t2.micro"),
})
dnsimpleToken := cdktn.NewTerraformVariable(stack, jsii.String("dnsimpleToken"), &cdktn.TerraformVariableConfig{
Type: jsii.String("string"),
Description: jsii.String("dnsimple token"),
Sensitive: jsii.Bool(true),
})
dnsimpleAccount := cdktn.NewTerraformVariable(stack, jsii.String("dnsimpleAccount"), &cdktn.TerraformVariableConfig{
Type: jsii.String("string"),
Description: jsii.String("dnsimple account"),
Sensitive: jsii.Bool(true),
})
dnsimple.NewDnsimpleProvider(stack, jsii.String("dnsimple"), &dnsimple.DnsimpleProviderConfig{
Token: dnsimpleToken.StringValue(),
Account: dnsimpleAccount.StringValue(),
})
zonerecord.NewZoneRecord(stack, jsii.String("web-www"), &zonerecord.ZoneRecordConfig{
ZoneName: jsii.String("example.com"),
Name: jsii.String("web"),
Value: instance.PublicIp(),
Type: jsii.String("A"),
})
return stack
}
```
Use the `synth` command to convert your code into a JSON Terraform configuration file.
```bash theme={null}
cdktn synth --json
```
```json theme={null}
{
"//": {
"metadata": {
"version": "0.0.11-pre.8757404fa25b6e405f1a51eac11b96943ccb372e",
"stackName": "vpc-example"
}
},
"terraform": {
"required_providers": {
"aws": "~> 2.0",
"dnsimple": "undefined"
}
},
"provider": {
"aws": [
{
"region": "us-east-1"
}
],
"dnsimple": [
{
"account": "hello@example.com",
"token": "xxxxxxxxxx"
}
]
},
"resource": {
"aws_instance": {
"vpcexample_Hello_279554CB": {
"ami": "ami-2757f631",
"instance_type": "t2.micro",
"//": {
"metadata": {
"path": "vpc-example/Hello",
"uniqueId": "vpcexample_Hello_279554CB",
"stackTrace": [
.....
]
}
}
}
},
"dnsimple_record": {
"vpcexample_webwww_477C7150": {
"domain": "example.com",
"name": "web",
"type": "A",
"value": "${aws_instance.vpcexample_Hello_279554CB.public_ip}",
"//": {
"metadata": {
"path": "vpc-example/web-www",
"uniqueId": "vpcexample_webwww_477C7150",
"stackTrace": [
.....
]
}
}
}
}
}
}
```
## Provider Caching
Caching prevents CDK Terrain from re-downloading providers between each CLI command. It is also useful when you need to remove the `cdktf.out` folder and re-synthesize your configuration. Finally, caching is necessary when you use multiple [stacks](/concepts/stacks) within one application.
### Set the Caching Directory
Refer to the Terraform documentation about [how to configure your plugin cache](/terraform/cli/config/config-file#provider-plugin-cache). Otherwise, CDKTN automatically sets the `TF_PLUGIN_CACHE_DIR` environment variable to `$HOME/.terraform.d/plugin-cache` when you use `cdktn` cli commands.
To disable this behavior, set `CDKTF_DISABLE_PLUGIN_CACHE_ENV` to a non null value, like `CDKTF_DISABLE_PLUGIN_CACHE_ENV=1`. You may want to do this when a different cache directory is configured via a `.terraformrc` configuration file.
## Use a Local Provider
Terraform needs to know the location of local providers to enable CDKTN to generate the appropriate type bindings. You can configure this in two ways:
* [Implied Local Mirrors](/terraform/cli/config/config-file#implied-local-mirror-directories)
* [Development Overrides](/terraform/cli/config/config-file#development-overrides-for-provider-developers)
Once configured properly, you can reference these providers in the `cdktf.json` file the same way that you reference providers from the Terraform Registry. Refer to the [project configuration documentation](/create-and-deploy/configuration-file) for more details about the `cdktf.json` specification.