Get started with Terraform
Terraform replaces manual steps in the CDB Technical Web Portal with repeatable configuration files, allowing the same configuration to provision identical infrastructure every time. Getting started requires only a CDB account, an API token, and a terminal — no prior Terraform experience required.
Step 1. Install Terraform
Terraform is a command-line tool for Windows, macOS, and Linux. After installation, all interaction happens through a terminal window — there is no application to launch.
The fastest way to install Terraform is through a package manager; if one is not available, download the binary manually from the tabs below.
The fastest way to install on Windows is with Chocolatey. Run the following from an elevated PowerShell session:
choco install terraform
Verify the installation:
terraform version
Expected output:
Terraform v1.x.x
on windows_amd64
If Chocolatey is not available, download the binary manually:
- Open developer.hashicorp.com/terraform/install.
- Under Windows, select AMD64 and click Download.
- Extract the ZIP archive to a permanent folder, for example
C:\tools\terraform\. - Add that folder to the PATH:
- Open Start and search for Edit the system environment variables.
- Click Environment Variables.
- Under User variables, select Path and click Edit.
- Click New and paste the path
C:\tools\terraform\. - Click OK to save.
- Open a new PowerShell window and run
terraform versionto verify.
Step 2. Create a project directory
Each Terraform project lives in its own directory. Terraform stores the infrastructure state per directory, so different projects must stay in separate folders.
Create a new directory and navigate into it:
mkdir gcore-terraform
cd gcore-terraform
All subsequent commands in this guide run from inside this directory.
Step 3. Get a CDB API token
The CDB provider v2 authenticates with An API token. To generate one:
- Open the Customer Portal and go to Profile > API Tokens.
- Click Create API token.
- Set an expiration date and assign the required permissions.
- Copy the token — it is shown only once.
Store the API token securely. Anyone with the token can authenticate and perform actions in the CDB API.
Step 4. Configure the CDB provider
Create a file named main.tf in the project directory. This file declares which provider Terraform should use and how to authenticate.
terraform {
required_version = ">= 1.11"
required_providers {
gcore = {
source = "G-Core/gcore"
version = "~> 2.0"
}
}
}
provider "gcore" {
api_key = "YOUR_API_KEY"
}
Replace YOUR_API_KEY with the token copied in Step 3.
Provider block fields
| Field | Purpose |
|---|---|
required_version | Minimum Terraform CLI version this configuration requires. |
required_providers | Declares external providers Terraform must download. |
source = "G-Core/gcore" | Registry address of the CDB provider (namespace/name). |
version | Provider version constraint. The = prefix pins to an exact release — required for pre-release versions since ~> does not apply to them. |
provider "gcore" | Configures the provider instance — here, the API key for authentication. |
Use an exact version pin (=) for pre-release versions, as the ~> constraint does not apply to them. Check Terraform Registry for the current version number.
Keep the API key out of source files
Hardcoding credentials in .tf files is a security risk. Use an environment variable instead:
$env:GCORE_API_KEY = "YOUR_API_KEY"
When GCORE_API_KEY is set, remove the api_key line from the provider block:
provider "gcore" {
# api_key is read from the GCORE_API_KEY environment variable
}
Add .terraform/ and *.tfstate to .gitignore when working with version control to avoid committing provider binaries and state files that may contain sensitive data.
Step 5. Initialize the provider
Run terraform init from the project directory. This command downloads the CDB provider plugin from Terraform Registry and prepares the working directory.
terraform init
Expected output:
Initializing provider plugins...
- Finding g-core/gcore versions matching "~> 2.0"...
- Installing g-core/gcore v2.0.0...
- Installed g-core/gcore v2.0.0 (signed by a HashiCorp partner)
Terraform has been successfully initialized!
After initialization, two items appear in the project folder:
| Item | Purpose |
|---|---|
.terraform/ | Contains the downloaded provider binary. Not committed to version control. |
.terraform.lock.hcl | Records the exact provider version installed. Commit this file to lock the version for the whole team. |
Step 6. Add a resource or data source
A resource creates or manages infrastructure — a virtual machine, a network, a DNS record. A data source reads existing infrastructure without changing it.
The following example reads an existing CDB project by name — a safe first step that queries the API without touching any infrastructure:
data "gcore_cloud_project" "default" {
find_one_by = {
name = "Default"
}
}
output "project_id" {
value = data.gcore_cloud_project.default.id
}
Add this to main.tf after the provider block.
The output block at the bottom prints the result after terraform apply. It references the data source as data.gcore_cloud_project.default.id — gcore_cloud_project is the type, default is the local name from the block above, and id is the attribute to read.
Step 7. Preview changes
Run terraform plan to see what Terraform intends to do. No changes are applied at this step — it is safe to run at any time.
terraform plan
Expected output:
data.gcore_cloud_project.default: Reading...
data.gcore_cloud_project.default: Read complete after 1s [name=Default]
Changes to Outputs:
+ project_id = 1186668
You can apply this plan to save these new output values to the Terraform
state, without changing any real infrastructure.
The + prefix marks a new output value being recorded — the project ID will be saved to state on apply.
Step 8. Apply the configuration
Run terraform apply to execute the plan. Terraform prints the same summary as plan, asks for confirmation, then applies:
terraform apply
Expected output:
Apply complete! Resources: 0 added, 0 changed, 0 destroyed.
Outputs:
project_id = 1186668
Terraform has successfully queried the CDB API and returned the project ID.
Terraform state
After terraform apply, a terraform.tfstate file appears in the project directory. This is the state file — Terraform's record of what resources it manages and their current attributes.
On each subsequent terraform apply, Terraform compares the desired state described in .tf files against the recorded state and applies only the difference, so running the same configuration multiple times always produces the same result.
Do not edit terraform.tfstate manually. If the state becomes inconsistent, use terraform state subcommands (list, show, rm, mv) to inspect and correct it.