Начало работы с Terraform

Terraform позволяет быстро создать облачную инфраструктуру в Yandex Cloud и управлять ею с помощью файлов конфигураций. В файлах конфигураций хранится описание инфраструктуры на языке HCL (HashiCorp Configuration Language). При изменении файлов конфигураций Terraform автоматически определяет, какая часть вашей конфигурации уже развернута, что следует добавить или удалить.

Terraform распространяется под лицензией Business Source License, а провайдер Yandex Cloud для Terraform — под лицензией MPL-2.0.

Подробную информацию о ресурсах провайдера смотрите в документации на сайте Terraform или в зеркале.

Чтобы создать вашу первую инфраструктуру в Yandex Cloud с помощью Terraform:

1. Подготовьте облако к работе.
2. Установите Terraform.
3. Получите данные для аутентификации.
4. Создайте файл конфигурации Terraform.
5. Настройте провайдер.
6. Подготовьте план инфраструктуры.
7. Проверьте и отформатируйте файлы конфигурации.
8. Создайте ресурсы.

Если ресурсы больше вам не нужны, удалите их.

Подготовьте облако к работеПодготовьте облако к работе

Зарегистрируйтесь в Yandex Cloud и создайте платежный аккаунт:

1. Перейдите в консоль управления, затем войдите в Yandex Cloud или зарегистрируйтесь.
2. На странице Yandex Cloud Billing убедитесь, что у вас подключен платежный аккаунт, и он находится в статусе ACTIVE или TRIAL_ACTIVE. Если платежного аккаунта нет, создайте его и привяжите к нему облако.

Если у вас есть активный платежный аккаунт, вы можете создать или выбрать каталог, в котором будет работать ваша инфраструктура, на странице облака.

Подробнее об облаках и каталогах.

Необходимые платные ресурсыНеобходимые платные ресурсы

В стоимость поддержки инфраструктуры, разворачиваемой через Terraform в этом руководстве, входят:

• Плата за постоянно запущенные виртуальные машины (см. тарифы Yandex Compute Cloud).
• Плата за использование динамических публичных IP-адресов (см. тарифы Yandex Virtual Private Cloud).

Установите TerraformУстановите Terraform

Из зеркалаИз зеркала

Вы можете скачать дистрибутив Terraform для вашей платформы из зеркала. После загрузки добавьте путь к папке, в которой находится исполняемый файл, в переменную PATH:

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

С сайта HashiCorpС сайта HashiCorp

Получите данные для аутентификацииПолучите данные для аутентификации

Чтобы управлять инфраструктурой Yandex Cloud с помощью Terraform, используйте сервисный аккаунт. Это позволит гибко настраивать права доступа к ресурсам.

Также вы можете использовать Terraform от имени аккаунта на Яндексе или федеративного аккаунта, однако этот способ является менее безопасным. Подробности см. в конце раздела.

1. Если у вас еще нет интерфейса командной строки Yandex Cloud, установите его.

2. Если у вас еще нет сервисного аккаунта, создайте его:

   Консоль управления

   CLI

   API

   1. В консоли управления выберите каталог, в котором хотите создать сервисный аккаунт.

   2. В списке сервисов выберите Identity and Access Management.

   3. Нажмите кнопку Создать сервисный аккаунт.

   4. Введите имя сервисного аккаунта.

      Требования к формату имени:

      • длина — от 3 до 63 символов;
      • может содержать строчные буквы латинского алфавита, цифры и дефисы;
      • первый символ — буква, последний — не дефис.

   5. Нажмите кнопку Создать.

   По умолчанию используется каталог, указанный в профиле CLI. Вы можете указать другой каталог с помощью параметра --folder-name или --folder-id.

   Выполните команду для создания сервисного аккаунта:

   yc iam service-account create --name <имя_сервисного_аккаунта>
   

   Где name — имя сервисного аккаунта в формате:

   • длина — от 3 до 63 символов;
   • может содержать строчные буквы латинского алфавита, цифры и дефисы;
   • первый символ — буква, последний — не дефис.

   Результат:

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

   Чтобы создать сервисный аккаунт, воспользуйтесь вызовом gRPC API ServiceAccountService/Create или методом create для ресурса ServiceAccount REST API.

3. Назначьте сервисному аккаунту роли, необходимые для управления ресурсами Yandex Cloud:

   Сервисному аккаунту можно назначать роли на любые ресурсы в любом облаке, если эти ресурсы относятся к той же организации, что и сервисный аккаунт. Также сервисному аккаунту можно назначать роли на саму организацию.

   Консоль управления

   CLI

   API

   Чтобы назначить сервисному аккаунту роль на каталог:

   1. В консоли управления выберите каталог.
   2. Перейдите на вкладку Права доступа.
   3. Нажмите кнопку Настроить доступ.
   4. В открывшемся окне выберите раздел Сервисные аккаунты.
   5. Выберите сервисный аккаунт из списка или воспользуйтесь поиском.
   6. Нажмите кнопку Добавить роль и выберите роль в каталоге.
   7. Нажмите кнопку Сохранить.

   1. Узнайте идентификатор сервисного аккаунта (столбец ID), которому нужно назначить роль:

      yc iam service-account list
      

      Результат:

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

   2. Назначьте сервисному аккаунту роль на ресурс:

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

      Где:

      • <service-name> — название сервиса, на чей ресурс назначается роль, например resource-manager.
      • <resource> — категория ресурса, например cloud — для назначения роли на все облако или folder — для назначения роли на каталог.
      • <resource-name> — имя ресурса. Вы можете указать ресурс по имени или идентификатору (имя облака или каталога).
      • <resource-id> — идентификатор ресурса (идентификатор облака или каталога).
      • <role-id> — назначаемая роль, например resource-manager.clouds.owner.
      • <service-account-id> — идентификатор сервисного аккаунта, которому назначается роль.

      Пример:

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

      Результат:

      done (1s)
      

   Чтобы назначить сервисному аккаунту роль на облако или каталог, воспользуйтесь методом REST API updateAccessBindings для ресурса Cloud или Folder:

   1. Выберите роль, которую хотите назначить сервисному аккаунту. Описание ролей можно найти в документации Yandex Identity and Access Management в справочнике ролей Yandex Cloud.

   2. Узнайте ID каталога с сервисными аккаунтами.

   3. Получите IAM-токен для авторизации в API Yandex Cloud.

   4. Получите список сервисных аккаунтов в каталоге, чтобы узнать их идентификаторы:

      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}"
      

      Результат:

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

   5. Сформируйте тело запроса, например в файле body.json. В свойстве action укажите ADD, в свойстве roleId — нужную роль, например editor, а в свойстве subject — тип serviceAccount и идентификатор сервисного аккаунта:

      body.json:

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

   6. Назначьте роль сервисному аккаунту. Например, на каталог с идентификатором b1gvmob95yys********:

      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. Настройте профиль CLI для выполнения операций от имени сервисного аккаунта:

   CLI

   1. Создайте авторизованный ключ для сервисного аккаунта и запишите его файл:

      yc iam key create \
        --service-account-id <идентификатор_сервисного_аккаунта> \
        --folder-name <имя_каталога_с_сервисным_аккаунтом> \
        --output key.json
      

      Где:

      • service-account-id — идентификатор сервисного аккаунта.
      • folder-name — имя каталога, в котором создан сервисный аккаунт.
      • output — имя файла с авторизованным ключом.

      Результат:

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

   2. Создайте профиль CLI для выполнения операций от имени сервисного аккаунта. Укажите имя профиля:

      yc config profile create <имя_профиля>
      

      Результат:

      Profile 'sa-terraform' created and activated
      

   3. Задайте конфигурацию профиля:

      yc config set service-account-key key.json
      yc config set cloud-id <идентификатор_облака>
      yc config set folder-id <идентификатор_каталога>
      

      Где:

      • service-account-key — файл с авторизованным ключом сервисного аккаунта.
      • cloud-id — идентификатор облака.
      • folder-id — идентификатор каталога.

5. Добавьте аутентификационные данные в переменные окружения:

   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)
   

   Где:

   • YC_TOKEN — IAM-токен.
   • YC_CLOUD_ID — идентификатор облака.
   • YC_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)
   

   Где:

   • YC_TOKEN — IAM-токен.
   • YC_CLOUD_ID — идентификатор облака.
   • YC_FOLDER_ID — идентификатор каталога.

   Примечание

   Время жизни IAM-токена — не больше 12 часов, но рекомендуется запрашивать его чаще, например каждый час.

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)

Создайте файл конфигурации TerraformСоздайте файл конфигурации Terraform

1. Создайте новую директорию с произвольным названием, например cloud-terraform. В ней будут храниться конфигурационные файлы и сохраненные состояния Terraform и инфраструктуры.

   Важно

   Каждая конфигурация должна находиться в отдельной директории.

2. Создайте в новой директории конфигурационный файл с расширением .tf, например main.tf.

Настройте провайдерНастройте провайдер

1. Если раньше у вас был настроен провайдер из реестра HashiCorp, сохраните его настройки:

   Linux/macOS

   Windows

   mv ~/.terraformrc ~/.terraformrc.old
   

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

2. Укажите источник, из которого будет устанавливаться провайдер.

   Linux/macOS

   Windows

   Откройте файл конфигурации Terraform CLI:

   nano ~/.terraformrc
   

   Примечание

   Файл .terraformrc должен располагаться в корне домашней папки пользователя, например, /home/user/ или /User/user/.

   Откройте файл конфигурации Terraform CLI terraform.rc в папке %APPDATA% вашего пользователя.

   Чтобы узнать абсолютный путь к папке %APPDATA%, выполните команду echo %APPDATA% для cmd или $env:APPDATA для PowerShell.

   Добавьте в него следующий блок:

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

   Подробнее о настройках зеркал см. в документации.

3. В начале конфигурационного файла .tf добавьте следующие блоки:

   terraform {
     required_providers {
       yandex = {
         source = "yandex-cloud/yandex"
       }
     }
     required_version = ">= 0.13"
   }
   
   provider "yandex" {
     zone = "<зона_доступности_по_умолчанию>"
   }
   

   Где:

   • source — глобальный адрес источника провайдера.
   • required_version — минимальная версия Terraform, с которой совместим провайдер.
   • provider — название провайдера.
   • zone — зона доступности, в которой по умолчанию будут создаваться все облачные ресурсы.

4. Выполните команду terraform init в папке с конфигурационным файлом .tf. Эта команда инициализирует провайдеров, указанных в конфигурационных файлах, и позволяет работать с ресурсами и источниками данных провайдера.

Если провайдер не установился, создайте обращение в поддержку с именем и версией провайдера.

Если вы использовали файл .terraform.lock.hcl, перед инициализацией выполните команду terraform providers lock, указав адрес зеркала, откуда будет загружаться провайдер, и платформы, на которых будет использоваться конфигурация:

terraform providers lock -net-mirror=https://terraform-mirror.yandexcloud.net -platform=<название_платформы_1> -platform=<название_платформы_2> yandex-cloud/yandex

Где:

• -net-mirror — адрес зеркала, откуда будет загружаться провайдер.
• -platform — платформы, на которых будет использоваться конфигурация. Возможные значения:
  • windows_amd64 — 64-bit Windows.
  • linux_amd64 — 64-bit Linux.
  • darwin_arm64 — 64-bit macOS.

Если вы использовали модули Terraform, сначала выполните terraform init, затем удалите lock-файл, а затем выполните команду terraform providers lock.

Более подробную информацию о команде terraform providers lock см. в документации Terraform.

Подготовьте план инфраструктурыПодготовьте план инфраструктуры

С помощью Terraform в Yandex Cloud можно создавать облачные ресурсы всех типов: ВМ, диски, образы и т. д. Подробную информацию о ресурсах, создающихся с помощью Terraform, см. в документации провайдера.

Для создания ресурса необходимо указать набор обязательных и опциональных параметров, определяющих свойства ресурса. Такие описания ресурсов составляют план инфраструктуры.

По плану будут созданы две ВМ: terraform1 и terraform2, а также облачная сеть network-1 с подсетью subnet-1.

Имена ресурсов должны соответствовать следующим требованиям:

• длина — от 3 до 63 символов;
• может содержать строчные буквы латинского алфавита, цифры и дефисы;
• первый символ — буква, последний — не дефис.

У ВМ будут разные количества ядер и объемы памяти: 2 ядра и 2 ГБ оперативной памяти у terraform1 и 4 ядра и 4 ГБ оперативной памяти у terraform2. ВМ автоматически получат публичные и приватные IP-адреса из диапазона 192.168.10.0/24 в подсети subnet-1, находящейся в зоне доступности ru-central1-d и принадлежащей облачной сети network-1. На ВМ будет установлена операционная система Ubuntu и размещена публичная часть ключа для доступа к ВМ по SSH.

В конфигурации ВМ вам потребуется указать идентификатор образа загрузочного диска. Список доступных публичных образов можно получить командой CLI:

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

Для доступа к ВМ через SSH сгенерируйте пару SSH-ключей и передайте публичную часть ключа на ВМ в параметре ssh-keys блока metadata.

Конфигурации ресурсов задаются сразу после конфигурации провайдера:

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

provider "yandex" {
  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
}

Создайте пользователейСоздайте пользователей

#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

Проверьте и отформатируйте файлы конфигурацийПроверьте и отформатируйте файлы конфигураций

1. Проверьте конфигурацию командой:

   terraform validate
   

   Если конфигурация является допустимой, появится сообщение:

   Success! The configuration is valid.
   

2. Отформатируйте файлы конфигураций в текущем каталоге и подкаталогах:

   terraform fmt
   

   Результат:

   main.tf
   variables.tf
   

Создайте ресурсыСоздайте ресурсы

1. После проверки конфигурации выполните команду:

   terraform plan
   

   В терминале будет выведен список ресурсов с параметрами. Это проверочный этап: ресурсы не будут созданы. Если в конфигурации есть ошибки, Terraform на них укажет.

   Внимание

   Все созданные с помощью Terraform ресурсы тарифицируются. Внимательно проверьте план.

2. Чтобы создать ресурсы, выполните команду:

   terraform apply
   

3. Подтвердите создание ресурсов: введите в терминал слово yes и нажмите Enter.

   Terraform создаст все требуемые ресурсы, а в терминале будут указаны IP-адреса созданных виртуальных машин. Проверить появление ресурсов и их настройки можно в консоли управления.

Как удалить созданные ресурсыКак удалить созданные ресурсы

Чтобы удалить ресурсы, созданные с помощью Terraform:

1. Выполните команду:

   terraform destroy
   

   Внимание

   Terraform удалит все ресурсы, созданные в текущей конфигурации: кластеры, сети, подсети, виртуальные машины и т. д.

   После выполнения команды в терминал будет выведен список удаляемых ресурсов.

2. Введите слово yes и нажмите Enter.

Проверить удаление ресурсов можно в консоли управления.

См. такжеСм. также

• Загрузка состояний Terraform в Object Storage.
• Блокировка состояний Terraform с помощью Managed Service for YDB.
• Использование модулей Yandex Cloud в Terraform.
• Источники данных Terraform.
• IaC: Terraform — обучающий курс по управлению инфраструктурой в облаке с помощью Terraform.