VK Object Storage

В статье приведены примеры создания и настройки бакетов и объектов VK Object Storage при помощи Terraform.

При создании сетей используются ресурсы (resource):

• aws_s3_bucket — создание бакета;
• aws_s3_object — создание объекта;
• aws_s3_bucket_lifecycle_configuration — управление жизненным циклом объектов бакета;
• aws_s3_bucket_acl — управление доступом к бакету для других пользователей или проектов;
• aws_s3_bucket_cors_configuration — управление правилами кросс-доменного использования ресурсов (CORS).

Подробное описание ресурсов — в документации провайдера.

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

   При необходимости увеличьте квоты.

2. Установите Terraform, если это еще не сделано.

3. (Опционально) Включите политики доступа, чтобы настраивать правила доступа через Terraform.

4. Настройте провайдер:

   1. Создайте директорию, из которой будете работать с платформой, и перейдите в нее.

   2. Создайте файл aws_provider.tf и добавьте в него содержимое:

       
      terraform {    required_providers {        aws = {    source = "hashicorp/aws"    version = "< 5.85.0"        }    }}provider "aws" {    region                      = "<РЕГИОН>"    access_key                  = "<ПУБЛИЧНЫЙ_КЛЮЧ_ДОСТУПА>"    secret_key                  = "<СЕКРЕТНЫЙ_КЛЮЧ>"    skip_credentials_validation = true    skip_metadata_api_check     = true    skip_requesting_account_id  = true    skip_region_validation      = true    endpoints {        s3 = "<ДОМЕН>"    }}

      Здесь:

      • <РЕГИОН> — регион размещения сервиса VK Object Storage. Настройка должна соответствовать региону аккаунта:

        • ru-msk — регион Москва;
        • kz-ast — регион Казахстан.

      • <ПУБЛИЧНЫЙ_КЛЮЧ_ДОСТУПА>, <СЕКРЕТНЫЙ_КЛЮЧ> — идентификатор ключа и секретный ключ доступа к объектному хранилищу.

      • <ДОМЕН> — URL для доступа к хранилищу, который зависит от региона аккаунта. Возможные значения:

        • https://hb.ru-msk.vkcloud-storage.ru — домен региона Москва;
        • https://hb.kz-ast.bizmrg.com — домен региона Казахстан.

5. Выполните команду для инициализации Terraform:

    
   terraform init

   Будут созданы дополнительные файлы, необходимые для работы Terraform.

В примере ниже создается бакет example-bucket, в который будут добавлены объекты object-one и object-two.

Создайте файл конфигурации Terraform main.tf с содержимым:

 
# Создание бакетаresource "aws_s3_bucket" "example-bucket" {    bucket = "example-bucket"    force_destroy = true}# Создание объектовresource "aws_s3_object" "object-one" {  bucket = aws_s3_bucket.example-bucket.bucket  key    = "object-one"  source = "docs/readme.md"  acl = "private"  etag = filemd5("docs/readme.md")}resource "aws_s3_object" "object-two" {  bucket = aws_s3_bucket.example-bucket.bucket  key    = "tmp/object-two"  source = "docs/video.mp4"  acl = "private"  source_hash = filemd5("docs/video.mp4")}

Здесь:

• bucket — имя бакета:

  • bucket = "example-bucket" — бакет будет создан с именем example-bucket. Требования к имени:

    • содержит от 4 до 63 символов;
    • начинается и заканчивается буквой или цифрой;
    • состоит только из латинских букв нижнего регистра (строчных), цифр и символов: ., -;
    • уникально в рамках всей платформы VK Cloud во всех регионах.

    Имя бакета содержится в URL-адресах находящихся в нем объектов, поэтому не используйте в имени конфиденциальную информацию.

    Если вы создаете бакет для хостинга, не рекомендуется использовать в имени:

    • IP-адреса и схожее с ними форматирование (например, 192.168.5.4), так как может возникнуть путаница между именем бакета и IP-адресом сайта.
    • xn-- в начале: все, что идет после, будет воспринято браузером как паникод.

  • bucket = aws_s3_bucket.example-bucket.bucket — при создании объекта указывается ресурс, который создает бакет. В это примере объект будет помещен в бакет example-bucket, который будет создан ресурсом aws_s3_bucket.

• (Опционально) force_destroy — параметр разрешает удаление бакета, даже если в нем будут объекты. Доступные значения true и false. По умолчанию — false.

• key— ключ объекта. Имя объекта, когда он будет загружен в бакет.

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

• acl — настройки ACL для объекта. Доступные значения: private, public-read, auth-read.

• etag — идентификатор версии объекта. Устанавливается с помощью filemd5("path/to/source"). Используйте этот параметр только для объектов меньше 16 МБ. Для объектов больше 16 МБ используйте source_hash, потому что они будут загружаться методом составной загрузки (multipart).

• source_hash — идентификатор версии объекта. Параметр аналогичен etag, но без ограничений по размеру объекта. Устанавливается с помощью filemd5("path/to/source").

В примере ниже будет добавлено правило автоматического удаления (lifecycle) объектов с префиксом tmp из бакета через один день.

Добавьте следующее содержимое в файл main.tf:

 
resource "aws_s3_bucket_lifecycle_configuration" "example-bucket-lifecyle" {  bucket = aws_s3_bucket.example-bucket.id  rule {    id = "tmp"    filter {      prefix = "tmp/"    }    expiration {      days = 1    }    status = "Enabled"  }}

Здесь:

• id — идентификатор правила. Допустимы только цифры, латинские буквы и символы -, _, .. Идентификатор должен быть уникальным в рамках бакета.

• prefix — префикс ключа объекта: правило будет применяться только для объектов с указанными префиксными ключами. Фильтр может содержать только один ключ. Примеры префиксных ключей: image/, pre/, image/photo.

• expiration — в параметре указывается количество дней, через которые будут удалены объекты.

• status — статус правила:

  • "Enabled" — правило действует;
  • "Disabled" — правило не действует.

В примере ниже будут предоставлены права на чтение ACL бакета по ID пользователя и ID проекта.

Добавьте следующее содержимое в файл main.tf:

 
data "aws_canonical_user_id" "current" {}resource "aws_s3_bucket_acl" "example-bucket-acl" {  bucket = aws_s3_bucket.example-bucket.id  access_control_policy {    # Oбязательная часть: определяет полные права доступа для текущего пользователя (владельца бакета)    owner {      id = data.aws_canonical_user_id.current.id    }    grant {       grantee {         id   = data.aws_canonical_user_id.current.id         type = "CanonicalUser"       }       permission = "FULL_CONTROL"    }    # Права доступа к бакету выдаются по ID пользователя    grant {      grantee {        id   = "1f417590-xxxx-xxxx-xxxx-edacf23b1f96"        type = "CanonicalUser"      }      permission = "READ_ACP"    }    # Права доступа к бакету выдаются по ID проекта    grant {      grantee {        email_address = "mcs1234567890"        type          = "AmazonCustomerByEmail"      }      permission = "READ_ACP"    }  }}

Здесь:

• data "aws_canonical_user_id" "current" {} — источник данных получает канонический идентификатор (Canonical User ID) текущего пользователя.
• id = "1f417590-xxxx-xxxx-xxxx-edacf23b1f96" — канонический идентификатор пользователя (Canonical User ID), которому выдаются права доступа к бакету. Чтобы узнать канонический идентификатор пользователя, получите ACL бакета или объекта, к которому пользователь уже имеет права доступа.
• email_address = "mcs1234567890" — PID (идентификатор проекта), которому выдаются права доступа к бакету. Как узнать PID.
• permission — тип прав доступа. Доступные значения: READ, WRITE, READ_ACP, WRITE_ACP, FULL_CONTROL.

В примере ниже будут настроены правила CORS.

Добавьте следующее содержимое в файл main.tf:

 
resource "aws_s3_bucket_cors_configuration" "example-bucket-cors" {  bucket = aws_s3_bucket.example-bucket.id  cors_rule {    allowed_headers = ["*"]    allowed_methods = ["PUT", "POST"]    allowed_origins = ["https://example-website.com"]    expose_headers  = ["etag"]    max_age_seconds = 3000  }  cors_rule {    allowed_methods = ["GET"]    allowed_origins = ["*"]  }}

Здесь:

• (Опционально) allowed_headers — список разрешенных заголовков в запросе к объектам бакета. Можно использовать символ * для определения шаблона.
• allowed_methods — список разрешенных методов в запросе к объектам бакета. Доступные значения: GET, PUT, HEAD, POST, DELETE.
• allowed_origins — список URL, с которых разрешен доступ к бакету. Можно использовать символ * для определения шаблона.
• (Опционально) expose_headers — список заголовков в ответе, к которому пользователи смогут получить доступ из своих приложений. Указывается в нижнем регистре.
• (Опционально) max_age_seconds — время в секундах, в течение которого ваш браузер кеширует ответ для указанного URL.

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

   • aws_provider.tf;
   • network.tf.

2. Перейдите в эту директорию.

3. Убедитесь, что конфигурационные файлы корректны и содержат нужные изменения:

    
   terraform validate && terraform plan

4. Примените изменения:

    
   terraform apply

   При запросе подтверждения введите yes.

5. Дождитесь завершения операции.

Убедитесь, что бакет и объекты были успешно созданы, конфигурация настроена:

1. Подключитесь к VK Object Storage через AWS CLI.

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

    
   aws s3 ls s3://example-bucket/ --endpoint-url https://hb.ru-msk.vkcloud-storage.ru

   Здесь:

   • example-bucket — имя бакета, который был создан через Terraform.

   • endpoint-url — домен сервиса VK Object Storage, должен соответствовать региону аккаунта:

     • https://hb.ru-msk.vkcloud-storage.ru — домен региона Москва;
     • https://hb.kz-ast.bizmrg.com — домен региона Казахстан.

   В ответе вернется созданный бакет и список добавленных в него объектов.

3. Проверьте, что для бакета настроены правила автоматической очистки. Выполните команду:

    
   aws s3api get-bucket-lifecycle-configuration \ --endpoint-url https://hb.ru-msk.vkcloud-storage.ru \ --bucket example-bucket

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

    
   aws s3api get-bucket-acl \ --endpoint-url https://hb.ru-msk.vkcloud-storage.ru \ --bucket example-bucket

5. Проверьте, что для бакета настроены правила CORS:

    
   aws s3api get-bucket-cors \ --endpoint-url https://hb.ru-msk.vkcloud-storage.ru \ --bucket example-bucket

Если созданные с помощью Terraform ресурсы вам больше не нужны, удалите их:

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

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

    
   terraform destroy

   При запросе подтверждения введите yes.

3. Дождитесь завершения операции.