Skip to content
0850 554 5439 [email protected]

How can we help?

Search our guides and tutorials, or browse the categories below.

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

Developers: API, CLI, Terraform 74 views Step-by-step guide Last verified: Markdown
What you will learnkeep 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).
Time10 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
hcl
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.

hcl
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:

hcl
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:

hcl
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

Was this helpful?

Thanks for your feedback!

Still Need Help?

Our support team is here around the clock for anything you can't find above.