Начало работы с API Gateway

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

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

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

Если у вас еще нет Terraform, установите его и настройте провайдер Yandex Cloud.

Чтобы создать API-шлюз:

1. Опишите в конфигурационном файле параметры ресурса yandex_api_gateway:

   • name — имя API-шлюза. Формат имени:

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

   • description — описание API-шлюза.

   • labels — метки для API-шлюза. Укажите пару ключ-значение.

   • spec — спецификация API-шлюза.

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

   resource "yandex_api_gateway" "test-api-gateway" {
     name        = "<имя_API-шлюза>"
     description = "<описание_API-шлюза>"
     labels      = {
       label       = "label"
       empty-label = ""
     }
     spec = <<-EOT
       openapi: "3.0.0"
       info:
         version: 1.0.0
         title: Test API
       paths:
         /hello:
           get:
             summary: Say hello
             operationId: hello
             parameters:
               - name: user
                 in: query
                 description: User name to appear in greetings
                 required: false
                 schema:
                   type: string
                   default: 'world'
             responses:
               '200':
                 description: Greeting
                 content:
                   'text/plain':
                     schema:
                       type: "string"
             x-yc-apigateway-integration:
               type: dummy
               http_code: 200
               http_headers:
                 'Content-Type': "text/plain"
               content:
                 'text/plain': "Hello, {user}!\n"
     EOT
   }
   

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

2. Проверьте корректность конфигурационных файлов.

   1. В командной строке перейдите в папку, где вы создали конфигурационный файл.

   2. Выполните проверку с помощью команды:

      terraform plan
      

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

3. Разверните облачные ресурсы.

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

      terraform apply
      

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

      После этого в указанном каталоге будут созданы все требуемые ресурсы. Проверить появление ресурсов и их настройки можно в консоли управления или с помощью команд CLI:

      yc serverless api-gateway get <имя_API-шлюза>
      

Чтобы создать функцию:

1. Подготовьте ZIP-архив с кодом функции:

   1. Сохраните следующий код в файл с названием index.js:

      module.exports.handler = async (event) => {
        return {
          "statusCode": 200,
          "headers": {"content-type": "application/json"},
          "body": "[0, 1, 2]"
        };
      };
      

   2. Добавьте файл index.js в ZIP-архив hello-js.zip.

2. Опишите в конфигурационном файле параметры ресурса yandex_function:

   resource "yandex_function" "test-function" {
     name               = "test-function"
     description        = "Test function"
     user_hash          = "first-function"
     runtime            = "nodejs18"
     entrypoint         = "index.handler"
     memory             = "128"
     execution_timeout  = "10"
     service_account_id = "<идентификатор_сервисного_аккаунта>"
     tags               = ["my_tag"]
     content {
       zip_filename = "<путь_к_ZIP-архиву>"
     }
   }
   

   Где:

   • name — имя функции.
   • description — текстовое описание функции.
   • user_hash — произвольная строка, определяющая версию функции. При изменениях функции необходимо менять и эту строку. Функция обновится при изменении этой строки.
   • runtime — среда выполнения функции.
   • entrypoint — имя функции в исходном коде, которая будет служить точкой входа в приложения.
   • memory — объем памяти в мегабайтах, отведенный для выполнения функции.
   • execution_timeout — таймаут выполнения функции.
   • service_account_id — идентификатор сервисного аккаунта, от имени которого будет запускаться функция.
   • tags — теги функции.
   • content — исходный код функции.
   • content.0.zip_filename — путь к ZIP-архиву, содержащему исходный код функции.

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

3. Проверьте корректность конфигурационных файлов.

   1. В командной строке перейдите в папку, где вы создали конфигурационный файл.

   2. Выполните проверку с помощью команды:

      terraform plan
      

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

4. Разверните облачные ресурсы.

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

      terraform apply
      

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

      После этого в указанном каталоге будут созданы все требуемые ресурсы. Проверить появление ресурсов и их настройки можно в консоли управления или с помощью команд CLI:

      yc serverless function list
      

Чтобы добавить в спецификацию API-шлюза информацию о функции:

1. Откройте файл конфигурации Terraform и добавьте метод /numbers, который с помощью расширения x-yc-apigateway-integration типа cloud_functions вызывает функцию по идентификатору. В блок spec измените спецификацию api-шлюза, указав следующие параметры:

   • function_id — идентификатор функции.
   • service_account_id — идентификатор сервисного аккаунта с правами на вызов функции.

   Расширенная спецификация api-шлюза:

   ...
   
     spec = <<-EOT
       openapi: "3.0.0"
       info:
         version: 1.0.0
         title: Test API
       paths:
         /hello:
           get:
             summary: Say hello
             operationId: hello
             parameters:
               - name: user
                 in: query
                 description: User name to appear in greetings.
                 required: false
                 schema:
                   type: string
                   default: 'world'
             responses:
               '200':
                 description: Greeting
                 content:
                   'text/plain':
                     schema:
                       type: "string"
             x-yc-apigateway-integration:
               type: dummy
               http_code: 200
               http_headers:
                 'Content-Type': "text/plain"
               content:
                 'text/plain': "Hello again, {user}!\n"
         /numbers:
           get:
             summary: List some numbers
             operationId: listNumbers
             responses:
               '200':
                 description: Another example.
                 content:
                   'application/json':
                     schema:
                       type: "array"
                       items:
                         type: "integer"
             x-yc-apigateway-integration:
               type: cloud_functions
               function_id: <идентификатор_функции>
               service_account_id: <идентификатор_сервисного_аккаунта>
     EOT
   }
   

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

2. Проверьте корректность конфигурационных файлов.

   1. В командной строке перейдите в папку, где вы создали конфигурационный файл.

   2. Выполните проверку с помощью команды:

      terraform plan
      

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

3. Разверните облачные ресурсы.

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

      terraform apply
      

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

      После этого в указанном каталоге будут созданы все требуемые ресурсы. Проверить появление ресурсов и их настройки можно в консоли управления или с помощью команд CLI:

      yc serverless api-gateway get <имя_API-шлюза>