> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gcore.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Get started with Terraform
Terraform replaces manual steps in the [Gcore Customer Portal](https://portal.gcore.com) 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](https://developer.hashicorp.com/terraform/install) 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.
[Chocolatey](https://chocolatey.org) is a free package manager for Windows. If Chocolatey is already installed, run the following from an elevated PowerShell session:
```powershell theme={null}
choco install terraform
```
Verify the installation:
```powershell theme={null}
terraform version
```
Expected output:
```
Terraform v1.x.x
on windows_amd64
```
If Chocolatey is not installed, use the manual binary method below.
1. Open [developer.hashicorp.com/terraform/install](https://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 verify:
```powershell theme={null}
terraform version
```
Expected output:
```
Terraform v1.x.x
on windows_amd64
```
[Homebrew](https://brew.sh) is a package manager for macOS. If Homebrew is already installed, run:
```bash theme={null}
brew tap hashicorp/tap
brew install hashicorp/tap/terraform
```
Verify the installation:
```bash theme={null}
terraform version
```
Expected output:
```
Terraform v1.x.x
on darwin_arm64
```
For Debian and Ubuntu:
```bash theme={null}
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:
```bash theme={null}
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:
```bash theme={null}
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](/account-settings/api-tokens). 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.
```hcl theme={null}
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](https://registry.terraform.io/providers/G-Core/gcore/latest) 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:
```powershell theme={null}
$env:GCORE_API_KEY = "YOUR_API_KEY"
```
```bash theme={null}
export GCORE_API_KEY="YOUR_API_KEY"
```
When `GCORE_API_KEY` is set, remove the `api_key` line from the provider block:
```hcl theme={null}
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.
```bash theme={null}
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:
```hcl theme={null}
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.
```bash theme={null}
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:
```bash theme={null}
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.