# Terraform with Gyro: state in Gyro storage, secrets, add-ons and the CLI profile

https://www.gyrohosting.com/en/knowledgebase/article/terraform-state-ve-ileri-ozellikler

- **What you will learn**: keep the Terraform state locked and versioned in Gyro storage, manage container secrets without writing them to the state, create a new server with its Network Firewall add-on in one `apply`, and let the provider read the API key from a `gyro` CLI profile (OS key store included).
- **Time**: 10 minutes

## 1. Keeping the state in Gyro storage

The Terraform `s3` backend works with both Gyro storage products. The difference is **state locking** (`use_lockfile`), which needs conditional writes (`If-None-Match: *`) on the server.

|  | Endpoint | `use_lockfile` | Old state versions |
| --- | --- | --- | --- |
| **Protected Storage** (recommended) | `https://s3-kilit.gyrohosting.com` | works: a second `apply` stops with "Error acquiring the state lock" | kept (versioning is always on) |
| Object Storage | `https://s3.gyrohosting.com` | **not enforced**: do not use it | not kept |

```
terraform {
  backend "s3" {
    bucket    = "gyro-proje-tfstate"
    key       = "prod/terraform.tfstate"
    region    = "tr-ist-1"
    endpoints = { s3 = "https://s3-kilit.gyrohosting.com" }

    use_path_style              = true
    use_lockfile                = true
    skip_credentials_validation = true
    skip_region_validation      = true
    skip_requesting_account_id  = true
    skip_metadata_api_check     = true
    skip_s3_checksum            = true
  }
}
```

Give the access key as environment variables: `export AWS_ACCESS_KEY_ID=…` and `export AWS_SECRET_ACCESS_KEY=…` (from the **Access keys** tab of your Protected Storage service, with read and write permission on the bucket). Then `terraform init`.

> **Warning**
> 
> On Object Storage `use_lockfile` does not fail but does not lock either; two runs can write the state at the same time. Use Object Storage only when a single CI job applies, and without `use_lockfile`.

> **Note**
> 
> If you add an object lock rule to the bucket, keep the retention short: the state is rewritten on every `apply` and locked versions cannot be deleted until they expire.

## 2. Secrets without writing them to the state

The values of `gyro_container_service.secrets` stay in the state. With Terraform 1.11 or later use the **write-only** argument: the values never enter the plan or the state.

```
resource "gyro_container_service" "worker" {
  service_id         = gyro_container_environment.app.id
  name               = "worker"
  image              = "ghcr.io/gyro-proje/worker:1.0"
  secrets_wo         = { DB_PASSWORD = var.db_password, RABBITMQ_URL = var.rabbitmq_url }
  secrets_wo_version = 1
}
```

- The values are sent when the service is created and every time `secrets_wo_version` changes. Bump the version (1 → 2) to push new values.
- Keys you drop from the map are deleted; the **names** sent are listed in `secrets_wo_keys` (never the values).
- `secrets` and `secrets_wo` cannot be used on the same service. Moving keys from `secrets` to `secrets_wo` does not delete them in between.
- On an imported service the first `apply` sends `secrets_wo` once.

## 3. New server + Network Firewall in one apply

`gyro_firewall` and `gyro_server_security_groups` need the **Network Firewall** add-on on the server. `gyro_server_addon` buys it and waits until it is active:

```
resource "gyro_server_addon" "firewall" {
  service_id = tonumber(gyro_server.db.id)
  addon      = "Network Firewall"     # the add-on name as listed for your account language, or addon_id / option_id
}

resource "gyro_firewall" "db" {
  server_id      = tonumber(gyro_server.db.id)
  default_action = "deny"
  rule {
    action   = "allow"
    protocol = "tcp"
    port     = "22"
    source   = "203.0.113.10/32"
  }
  depends_on = [gyro_server_addon.firewall]
}
```

- On prepaid services (Gyro Cloud Istanbul, Containers) the add-on is charged hourly from the balance; `destroy` removes it at once and the charge stops.
- On invoiced services the invoice is paid from the balance; `destroy` cannot cancel the add-on through the API and only removes it from Terraform (cancel it in the panel).
- List the add-ons you can buy with `gyro service addons available <id>`; ids (`addon_id` / `option_id`) do not depend on the language.

> **Note**
> 
> If the same configuration turns on a VPC gateway (`gateway_enabled = true`), the account needs a prepaid Istanbul server first: add `depends_on = [gyro_server.<name>]` to the `gyro_vpc`.

## 4. API key from a gyro CLI profile

Instead of the `GYRO_TOKEN` environment variable the provider can use a profile saved by the `gyro` CLI:

```
provider "gyro" {
  profile = "default"   # profile in ~/.config/gyro/config.toml
}
```

- The profile is created with `gyro auth login` or `gyro configure`. If the key is kept in the OS key store (macOS Keychain, Windows Credential Manager, Linux Secret Service), the provider reads it from there.
- Order: `token` in the provider > `GYRO_TOKEN` > `profile` (or `GYRO_PROFILE`, else the CLI default profile).

## 5. Other small features in 0.37.0

| Resource | New |
| --- | --- |
| `gyro_vpc` | `first_subnet_name`, `first_subnet_cidr`: name and range of the subnet created with the VPC (create only) |
| `gyro_port_forward` | `name`: a label for the forward (changed in place, the gateway is not touched) |
| `gyro_service_label` | `manage_nickname = false`: manages only the tags; the nickname stays with `gyro_container_environment.name` / `gyro_storage.name` |
| `gyro_server_agent` | keeps the guest agent current (needed on older servers for private networks and turning the public IP off) |
| `gyro_container_registry_policy` | image registry clean-up policy (`keep`, `untagged_days`) |

## 6. Frequently asked questions

**Can I keep the state in Object Storage?**

Yes, but the lock is not enforced. If more than one `apply` can run at the same time, use Protected Storage.

**Can I go back to an older state?**

On Protected Storage every write keeps the previous version; restore a broken state from the bucket's versions.

**Why does secrets_wo need Terraform 1.11?**

Write-only arguments arrived in Terraform 1.11. With older versions use `secrets` and keep the state in a backend with restricted access.

**Can gyro_server_addon buy the add-on twice?**

No. Every `apply` sends one request with a unique Idempotency-Key, and the add-on is not bought again while the resource is in the state.

## Next step

- Basics: [Terraform with Gyro Cloud servers](https://www.gyrohosting.com/en/knowledgebase/article/terraform-ile-gyro-bulut)
- Command line: [Install the gyro CLI](https://www.gyrohosting.com/en/knowledgebase/article/gyro-cli-kurulum)
