Get started with Terraform

Terraform replaces manual steps in the Gcore Customer Portal with repeatable configuration files, allowing the same configuration to provision identical infrastructure every time. Getting started requires only a Gcore 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.

Windows

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:

1. Open developer.hashicorp.com/terraform/install.
2. Under Windows, select AMD64 and click Download.
3. Extract the ZIP archive to a permanent folder, for example C:\tools\terraform\.
4. 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.
5. Open a new PowerShell window and run terraform version to verify.

macOS

Homebrew is a package manager for macOS. If Homebrew is already installed, run:

brew tap hashicorp/tap
brew install hashicorp/tap/terraform

Verify the installation:

terraform version

Expected output:

Terraform v1.x.x
on darwin_arm64

Linux

For Debian and Ubuntu:

wget -O - https://apt.releases.hashicorp.com/gpg | sudo gpg --dearmor -o /usr/share/keyrings/hashicorp-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/hashicorp-archive-keyring.gpg] https://apt.releases.hashicorp.com $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/hashicorp.list
sudo apt update && sudo apt install terraform

Verify the installation:

terraform version

Expected output:

Terraform v1.x.x
on linux_amd64

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 Gcore API token

The Gcore provider v2 authenticates with An API token. To generate one:

1. Open the Customer Portal and go to Profile > API Tokens.
2. Click Create API token.
3. Set an expiration date and assign the required permissions.
4. Copy the token — it is shown only once.

Store the API token securely. Anyone with the token can authenticate and perform actions in the Gcore API.

Step 4. Configure the Gcore 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 Gcore 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:

Windows

$env:GCORE_API_KEY = "YOUR_API_KEY"

macOS

export GCORE_API_KEY="YOUR_API_KEY"

Linux

export 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 Gcore 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 Gcore 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 Gcore 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.