Использование модулей Yandex Cloud в Terraform

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

На этой странице рассказано, как подключить модули и использовать их для создания тестовой инфраструктуры: облачной сети с тремя подсетями Yandex Virtual Private Cloud и кластера Yandex Managed Service for Kubernetes.

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

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

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

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

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

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

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

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

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

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

• Плата за высокодоступный мастер Managed Service for Kubernetes (см. тарифы Managed Service for Kubernetes).
• Плата за постоянно запущенные виртуальные машины в группе узлов Managed Service for Kubernetes (см. тарифы Yandex Compute Cloud).
• Плата за использование динамических публичных IP-адресов (см. тарифы 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. Введите имя сервисного аккаунта.

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

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

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

   По умолчанию используется каталог, указанный при создании профиля CLI. Чтобы изменить каталог по умолчанию, используйте команду yc config set folder-id <идентификатор_каталога>. Также для любой команды вы можете указать другой каталог с помощью параметров --folder-name или --folder-id.

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

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

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

   • длина — от 2 до 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-yc-vpc — с его помощью можно управлять сетевой инфраструктурой вашего облака: сетями, подсетями, шлюзами и другими объектами Virtual Private Cloud. Создайте тестовую сеть с тремя подсетями в разных зонах доступности:

module "yc-vpc" {
  source              = "github.com/terraform-yc-modules/terraform-yc-vpc.git"
  network_name        = "test-module-network"
  network_description = "Test network created with module"
  private_subnets = [{
    name           = "subnet-1"
    zone           = "ru-central1-a"
    v4_cidr_blocks = ["10.10.0.0/24"]
  },
  {
    name           = "subnet-2"
    zone           = "ru-central1-b"
    v4_cidr_blocks = ["10.11.0.0/24"]
  },
  {
    name           = "subnet-3"
    zone           = "ru-central1-d"
    v4_cidr_blocks = ["10.12.0.0/24"]
  }
  ]
}

Подключите модуль Managed Service for KubernetesПодключите модуль Managed Service for Kubernetes

Добавьте в конфигурацию модуль terraform-yc-vpc и конфигурацию кластера Managed Service for Kubernetes с высокодоступным мастером и двумя группами узлов:

module "kube" {
  source     = "github.com/terraform-yc-modules/terraform-yc-kubernetes.git"
  network_id = "${module.yc-vpc.vpc_id}"

  master_locations  = [
    for s in module.yc-vpc.private_subnets:
      {
        zone      = s.zone,
        subnet_id = s.subnet_id
      }
    ]

  master_maintenance_windows = [
    {
      day        = "monday"
      start_time = "23:00"
      duration   = "3h"
    }
  ]

  node_groups = {
    "yc-k8s-ng-01"  = {
      description   = "Kubernetes nodes group 01"
      fixed_scale   = {
        size = 3
      }
      node_labels   = {
        role        = "worker-01"
        environment = "testing"
      }
    },

    "yc-k8s-ng-02"  = {
      description   = "Kubernetes nodes group 02"
      auto_scale    = {
        min         = 2
        max         = 4
        initial     = 2
      }
      node_labels   = {
        role        = "worker-02"
        environment = "dev"
      }

      max_expansion   = 1
      max_unavailable = 1
    }
  }
}

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

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.
• Загрузка состояний Terraform в Object Storage.
• Блокировка состояний Terraform с помощью Managed Service for YDB.
• Источники данных Terraform.