Getting started with Terraform

Terraform allows you to quickly create a cloud infrastructure in Yandex Cloud and manage it using configuration files. Configuration files store the infrastructure description in the HashiCorp Configuration Language (HCL). Terraform and its providers are distributed under the Business Source License.

For more information about the provider resources, see the documentation on the Terraform website or the mirror.

If you change the configuration files, Terraform automatically detects which part of your configuration is already deployed, and what should be added or removed.

To create your first infrastructure in Yandex Cloud using Terraform:

1. Prepare your cloud.
2. Install Terraform.
3. Get the authentication data
4. Create a Terraform configuration file.
5. Configure a provider.
6. Prepare an infrastructure plan.
7. Check and format your configuration files.
8. Create resources.

If you no longer need the resources, delete them.

Prepare your cloudPrepare your cloud

Sign up for Yandex Cloud and create a billing account:

1. Go to the management console and log in to Yandex Cloud or create an account if you do not have one yet.
2. On the Yandex Cloud Billing page, make sure you have a billing account linked and it has the ACTIVE or TRIAL_ACTIVE status. If you do not have a billing account, create one.

If you have an active billing account, you can go to the cloud page to create or select a folder for your infrastructure to operate in.

Learn more about clouds and folders.

Required paid resourcesRequired paid resources

The cost of resources created with Terraform includes:

• Fee for continuously running virtual machines (see Yandex Compute Cloud pricing).
• Fee for using a dynamic public IP address (see Yandex Virtual Private Cloud pricing).

Install TerraformInstall Terraform

From a mirrorFrom a mirror

You can download a Terraform distribution for your platform from a mirror. When the download is complete, add the path to the folder with the executable to the PATH variable:

export PATH=$PATH:/path/to/terraform

From the HashiCorp websiteFrom the HashiCorp website

Get the authentication credentialsGet the authentication credentials

Use a service account to manage the Yandex Cloud infrastructure using Terraform. It will help you flexibly configure access permissions to resources.

You can also use Terraform under your Yandex account or a federated account, but this method is less secure. For more information, see the end of this section.

1. If you do not have the Yandex Cloud command line interface, install it.

2. If you do not have a service account, create one:

   Management console

   CLI

   API

   1. In the management console, select the folder where you want to create a service account.

   2. In the list of services, select Identity and Access Management.

   3. Click Create service account.

   4. Enter a name for the service account.

      The name format requirements are as follows:

      • The name must be from 3 to 63 characters long.
      • It may contain lowercase Latin letters, numbers, and hyphens.
      • The first character must be a letter and the last character cannot be a hyphen.

   5. Click Create.

   The folder specified in the CLI profile is used by default. You can specify a different folder using the --folder-name or --folder-id parameter.

   Run the following command to create a service account:

   yc iam service-account create --name <service_account_name>
   

   Where name is the service account name in the following format:

   • The name must be from 3 to 63 characters long.
   • It may contain lowercase Latin letters, numbers, and hyphens.
   • The first character must be a letter and the last character cannot be a hyphen.

   Result:

   id: ajehr0to1g8b********
   folder_id: b1gv87ssvu49********
   created_at: "2022-09-14T09:03:11.665153755Z"
   name: sa-terraform
   

   To create a service account, use the ServiceAccountService/Create gRPC API call or the create REST API method for the ServiceAccount resource.

3. Assign, to the service account, the following roles needed to manage Yandex Cloud resources:

   You can assign roles to a service account for any resources in any cloud if these resources belong to the same organization as the service account. You can also assign roles to a service account for the organization.

   Management console

   CLI

   API

   To assign to a service account a role for the folder:

   1. In the management console, select the appropriate folder.
   2. Go to the Access bindings tab.
   3. Click Configure access.
   4. In the window that opens, select Service accounts.
   5. Select a service account from the list or use the search.
   6. Click Add role and select the role in the folder.
   7. Click Save.

   1. Find out the ID of the service account (the ID column) you want to assign the role to:

      yc iam service-account list
      

      Result:

      +----------------------+--------------+
      |          ID          |     NAME     |
      +----------------------+--------------+
      | aje6ij7qvdhb******** | sa-terraform |
      +----------------------+--------------+
      

   2. Assign the role for the resource to the service account:

      yc <service-name> <resource> add-access-binding <resource-name>|<resource-id> \
        --role <role-id> \
        --subject serviceAccount:<service-account-id>
      

      Where:

      • <service-name>: Name of the service for whose resource you want to assign the role, e.g., resource-manager.
      • <resource>: Resource category, e.g., cloud to assign a role for the entire cloud, or folder to assign a role for a folder.
      • <resource-name>: Resource name. You can specify a resource by its name or ID (cloud or folder name).
      • <resource-id>: Resource ID (cloud or folder ID).
      • <role-id>: Role being assigned, e.g., resource-manager.clouds.owner.
      • <service-account-id>: ID of the service account getting the role.

      Example:

      yc resource-manager folder add-access-binding **********9n9hi2qu --role editor --subject serviceAccount:**********qhi2qu
      

      Result:

      done (1s)
      

   To assign the service account a role for a cloud or folder, use the updateAccessBindings REST API method for the Cloud or Folder resource:

   1. Select the role to assign to the service account. You can find the description of the roles in the Yandex Identity and Access Management documentation in the Yandex Cloud role reference.

   2. Get the ID of the service accounts folder.

   3. Get an IAM token required for authorization in the Yandex Cloud API.

   4. Get a list of folder service accounts to find out their IDs:

      export FOLDER_ID=b1gvmob95yys********
      export IAM_TOKEN=CggaATEVAgA...
      curl \
        --header "Authorization: Bearer ${IAM_TOKEN}" \
        "https://iam.api.cloud.yandex.net/iam/v1/serviceAccounts?folderId=${FOLDER_ID}"
      

      Result:

      {
       "serviceAccounts": [
        {
         "id": "ajebqtreob2d********",
         "folderId": "b1gvmob95yys********",
         "createdAt": "2018-10-18T13:42:40Z",
         "name": "my-robot",
         "description": "my description"
        }
       ]
      }
      

   5. Create the request body, e.g., in the body.json file. Set the action property to ADD and roleId to the appropriate role, such as editor, and specify the serviceAccount type and service account ID in the subject property:

      body.json:

      {
        "accessBindingDeltas": [{
          "action": "ADD",
          "accessBinding": {
            "roleId": "editor",
            "subject": {
              "id": "ajebqtreob2d********",
              "type": "serviceAccount"
            }
          }
        }]
      }
      

   6. Assign a role to a service account. For example, for a folder with the b1gvmob95yys******** ID:

      export FOLDER_ID=b1gvmob95yys********
      export IAM_TOKEN=CggaAT********
      curl \
        --request POST \
        --header "Content-Type: application/json" \
        --header "Authorization: Bearer ${IAM_TOKEN}" \
        --data '@body.json' \
        "https://resource-manager.api.cloud.yandex.net/resource-manager/v1/folders/${FOLDER_ID}:updateAccessBindings"
      

4. Set up the CLI profile to run operations on behalf of the service account:

   CLI

   1. Create an authorized key for your service account and save the file:

      yc iam key create \
        --service-account-id <service_account_ID> \
        --folder-name <service_account_folder_name> \
        --output key.json
      

      Where:

      • service-account-id: Service account ID.
      • folder-name: Name of the folder in which the service account was created.
      • output: Name of the file with the authorized key.

      Result:

      id: aje8nn871qo4********
      service_account_id: ajehr0to1g8********
      created_at: "2022-09-14T09:11:43.479156798Z"
      key_algorithm: RSA_2048
      

   2. Create a CLI profile to run operations on behalf of the service account. Name the profile:

      yc config profile create <profile_name>
      

      Result:

      Profile 'sa-terraform' created and activated
      

   3. Set the profile configuration:

      yc config set service-account-key key.json
      yc config set cloud-id <cloud_ID>
      yc config set folder-id <folder_ID>
      

      Where:

      • service-account-key: File with the service account authorized key.
      • cloud-id: Cloud ID.
      • folder-id: Folder ID.

5. Add the credentials to the environment variables:

   Bash

   PowerShell

   export YC_TOKEN=$(yc iam create-token)
   export YC_CLOUD_ID=$(yc config get cloud-id)
   export YC_FOLDER_ID=$(yc config get folder-id)
   

   Where:

   • YC_TOKEN: IAM token.
   • YC_CLOUD_ID: Cloud ID.
   • YC_FOLDER_ID: Folder ID.

   $Env:YC_TOKEN=$(yc iam create-token)
   $Env:YC_CLOUD_ID=$(yc config get cloud-id)
   $Env:YC_FOLDER_ID=$(yc config get folder-id)
   

   Where:

   • YC_TOKEN: IAM token.
   • YC_CLOUD_ID: Cloud ID.
   • YC_FOLDER_ID: Folder ID.

   Note

   The IAM token lifetime does not exceed 12 hours; however, we recommend requesting it more often, such as once per hour.

export YC_TOKEN=$(yc iam create-token)
export YC_CLOUD_ID=$(yc config get cloud-id)
export YC_FOLDER_ID=$(yc config get folder-id)

$Env:YC_TOKEN=$(yc iam create-token)
$Env:YC_CLOUD_ID=$(yc config get cloud-id)
$Env:YC_FOLDER_ID=$(yc config get folder-id)

Create a Terraform configuration fileCreate a Terraform configuration file

1. Create a new directory with any name, for example, cloud-terraform. It stores the configuration files and saved states for Terraform and your infrastructure.

   Warning

   Each configuration must be in a separate directory.

2. Create a configuration file with the .tf extension in this directory, such as main.tf.

Configure a providerConfigure a provider

1. If you previously configured a provider from the HashiCorp registry, save its settings:

   Linux/macOS

   Windows

   mv ~/.terraformrc ~/.terraformrc.old
   

   mv $env:APPDATA/terraform.rc $env:APPDATA/terraform.rc.old
   

2. Specify the source the provider will be installed from.

   Linux/macOS

   Windows

   Open the Terraform CLI configuration file:

   nano ~/.terraformrc
   

   Note

   The .terraformrc file must be in the user's home root folder, e.g., /home/user/ or /User/user/.

   Open the Terraform CLI configuration file named terraform.rc in your user's %APPDATA% folder.

   To find out the absolute path to the %APPDATA% folder, run the echo %APPDATA% command for cmd or the $env:APPDATA command for PowerShell.

   Add the following section to the file:

   provider_installation {
     network_mirror {
       url = "https://terraform-mirror.yandexcloud.net/"
       include = ["registry.terraform.io/*/*"]
     }
     direct {
       exclude = ["registry.terraform.io/*/*"]
     }
   }
   

   For more information about setting up mirrors, see the documentation.

3. Add the following sections at the top of the .tf configuration file:

   terraform {
     required_providers {
       yandex = {
         source = "yandex-cloud/yandex"
       }
     }
     required_version = ">= 0.13"
   }
   
   provider "yandex" {
     zone = "<default_availability_zone>"
   }
   

   Where:

   • source: Provider's global source address.
   • required_version: Minimum Terraform version the provider is compatible with.
   • provider: Provider name.
   • zone: Availability zone where all cloud resources will be created by default.

4. Run the terraform init command in the folder containing the .tf configuration file. This command initializes the providers specified in the configuration files and allows you to work with the provider resources and data sources.

If the provider installation failed, create a support request stating provider name and version.

If you used the .terraform.lock.hcl file, prior to the initialization, run the terraform providers lock command specifying the URL of the mirror to upload the provider from and the platforms the configuration will run on:

terraform providers lock -net-mirror=https://terraform-mirror.yandexcloud.net -platform=<platform_1_name> -platform=<platform_2_name> yandex-cloud/yandex

Where:

• -net-mirror: Address of the mirror to upload the provider from.
• -platform: Platforms to use the configuration on. The possible values include:
  • windows_amd64: 64-bit Windows
  • linux_amd64: 64-bit Linux
  • darwin_arm64: 64-bit macOS

If you used the Terraform modules, first run terraform init, then delete the lock file. After that, run the terraform providers lock command.

For more information about the terraform providers lock command, see the Terraform documentation.

Prepare an infrastructure planPrepare an infrastructure plan

Using Terraform in Yandex Cloud, you can create cloud resources of any type, such as VMs, disks, and images. For more information about the resources you can create with Terraform, see the provider documentation.

To create a resource, specify a set of required and optional parameters that define the resource properties. Such resource descriptions make up an infrastructure plan.

The plan includes creating two VMs: terraform1 and terraform2, as well as a cloud network called network-1 with a subnet named subnet-1.

Resource names must meet the following requirements:

• The name must be from 3 to 63 characters long.
• It may contain lowercase Latin letters, numbers, and hyphens.
• The first character must be a letter and the last character cannot be a hyphen.

The VMs will have different vCPU and memory configurations: 2 vCPUs and 2 GB of RAM for terraform1 and 4 vCPUs and 4 GB of RAM for terraform2. The VMs will be automatically assigned public and private IP addresses from the 192.168.10.0/24 range in subnet-1 located in the ru-central1-a availability zone and belonging to the network-1 cloud network. The VMs will run Ubuntu OS and host the public part of the key to enable SSH access to the VMs.

In the VM configuration, you will need to specify the boot disk image ID. You can get a list of available public images using this CLI command:

yc compute image list --folder-id standard-images

To access the VMs over SSH, generate an SSH key pair and include the public key to the VM in the ssh-keys parameter in the metadata section.

Resource configurations are specified immediately after the provider's configuration:

terraform {
  required_providers {
    yandex = {
      source = "yandex-cloud/yandex"
    }
  }
}

provider "yandex" {
  zone = "<default availability zone>"
}

resource "yandex_compute_instance" "vm-1" {
  name = "terraform1"
}

terraform {
  required_providers {
    yandex = {
      source = "yandex-cloud/yandex"
    }
  }
}

provider "yandex" {
  zone      = var.zone
}

resource "yandex_vpc_network" "default" {
  name = var.network
}

resource "yandex_vpc_subnet" "default" {
  network_id     = yandex_vpc_network.default.id
  name           = var.subnet
  v4_cidr_blocks = var.subnet_v4_cidr_blocks
  zone           = var.zone
}

data "yandex_compute_image" "default" {
  family = var.image_family
}

data "template_file" "default" {
  template = file("${path.module}/init.ps1")
  vars = {
    user_name  = var.user_name
    user_pass  = var.user_pass
    admin_pass = var.admin_pass
  }
}

resource "yandex_compute_instance" "default" {
  name     = var.name
  hostname = var.name
  zone     = var.zone

  resources {
    cores  = var.cores
    memory = var.memory
  }

  boot_disk {
    initialize_params {
      image_id = data.yandex_compute_image.default.id
      size     = var.disk_size
      type     = var.disk_type
    }
  }

  network_interface {
    subnet_id = yandex_vpc_subnet.default.id
    nat       = var.nat
  }

  metadata = {
    user-data = data.template_file.default.rendered
  }

  timeouts {
    create = var.timeout_create
    delete = var.timeout_delete
  }
}

output "name" {
  value = yandex_compute_instance.default.name
}

output "address" {
  value = yandex_compute_instance.default.network_interface.0.nat_ip_address
}

Create usersCreate users

#ps1
# ^^^ 'ps1' is only for cloudbase-init, some sort of sha-bang in linux

# logging
Start-Transcript -Path "$ENV:SystemDrive\provision.txt" -IncludeInvocationHeader -Force
"Bootstrap script started" | Write-Host

# inserting value's from terraform
$MyUserName = "${ user_name }"
$MyPlainTextPassword = "${ user_pass }"
if (-not [string]::IsNullOrEmpty($MyUserName) -and -not [string]::IsNullOrEmpty($MyPlainTextPassword)) {
    "Create user" | Write-Host
    $MyPassword = $MyPlainTextPassword | ConvertTo-SecureString -AsPlainText -Force
    $MyUser = New-LocalUser -Name $MyUserName -Password $MyPassword -PasswordNeverExpires -AccountNeverExpires
    $MyUser | Add-LocalGroupMember -Group 'Administrators'
    $MyUser | Add-LocalGroupMember -Group 'Remote Management Users'
}

# inserting value's from terraform
$MyAdministratorPlainTextPassword = "${ admin_pass }"
if (-not [string]::IsNullOrEmpty($MyAdministratorPlainTextPassword)) {
    "Set local administrator password" | Write-Host
    $MyAdministratorPassword = $MyAdministratorPlainTextPassword | ConvertTo-SecureString -AsPlainText -Force
    # S-1-5-21domain-500 is a well-known SID for Administrator
    # https://docs.microsoft.com/en-us/troubleshoot/windows-server/identity/security-identifiers-in-windows
    $MyAdministrator = Get-LocalUser | Where-Object -Property "SID" -like "S-1-5-21-*-500"
    $MyAdministrator | Set-LocalUser -Password $MyAdministratorPassword
}

"Bootstrap script ended" | Write-Host

Check and format the configuration filesCheck and format the configuration files

1. Check the configuration using this command:

   terraform validate
   

   If the configuration is valid, you will get this message:

   Success! The configuration is valid.
   

2. Format the configuration files in the current folder and subfolders:

   terraform fmt
   

   Result:

   main.tf
   variables.tf
   

Create resourcesCreate resources

1. After checking the configuration, run the command:

   terraform plan
   

   The terminal will display a list of resources with parameters. This is a test step; no resources will be created. If the configuration contains any errors, Terraform will point them out.

   Alert

   You will be charged for all the resources created with Terraform. Check the pricing plan carefully.

2. To create resources, run the command:

   terraform apply
   

3. Confirm creating the resources: type yes in the terminal and press Enter.

   Terraform will create all the required resources and the terminal will display the IP addresses of the created VMs. You can check the new resources and their configuration using the management console.

How to delete the resources you createdHow to delete the resources you created

To delete the resources created with Terraform:

1. Run this command:

   terraform destroy
   

   Alert

   Terraform will delete all the resources you created in the current configuration, such as clusters, networks, subnets, and VMs.

   After the command is executed, the terminal will display a list of resources to be deleted.

2. Type yes and press Enter.

You can use the management console to check that the resources have been deleted.

See alsoSee also

• Uploading Terraform states to Yandex Object Storage.
• Locking Terraform states using Yandex Managed Service for YDB.