{"id":18794151,"url":"https://github.com/yandex-cloud-examples/yc-s3-private-endpoint","last_synced_at":"2025-09-02T06:32:28.115Z","repository":{"id":230059921,"uuid":"769057066","full_name":"yandex-cloud-examples/yc-s3-private-endpoint","owner":"yandex-cloud-examples","description":"Организация масштабируемого подключения к Object Storage (S3) из VPC Yandex Cloud.","archived":false,"fork":false,"pushed_at":"2025-06-06T11:43:38.000Z","size":246,"stargazers_count":3,"open_issues_count":0,"forks_count":1,"subscribers_count":10,"default_branch":"main","last_synced_at":"2025-06-06T12:38:15.920Z","etag":null,"topics":["object-storage","terraform","vpc","yandex-cloud","yandexcloud"],"latest_commit_sha":null,"homepage":"","language":"HCL","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/yandex-cloud-examples.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"security.tf","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-03-08T08:56:32.000Z","updated_at":"2025-06-06T11:43:37.000Z","dependencies_parsed_at":"2024-03-27T16:51:05.588Z","dependency_job_id":"a8c5729c-39a6-4741-8aa6-7763fa18a0d6","html_url":"https://github.com/yandex-cloud-examples/yc-s3-private-endpoint","commit_stats":null,"previous_names":["yandex-cloud-examples/yc-s3-private-endpoint"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/yandex-cloud-examples/yc-s3-private-endpoint","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yandex-cloud-examples%2Fyc-s3-private-endpoint","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yandex-cloud-examples%2Fyc-s3-private-endpoint/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yandex-cloud-examples%2Fyc-s3-private-endpoint/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yandex-cloud-examples%2Fyc-s3-private-endpoint/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yandex-cloud-examples","download_url":"https://codeload.github.com/yandex-cloud-examples/yc-s3-private-endpoint/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yandex-cloud-examples%2Fyc-s3-private-endpoint/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273244301,"owners_count":25070958,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-02T02:00:09.530Z","response_time":77,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["object-storage","terraform","vpc","yandex-cloud","yandexcloud"],"created_at":"2024-11-07T21:28:22.887Z","updated_at":"2025-09-02T06:32:27.812Z","avatar_url":"https://github.com/yandex-cloud-examples.png","language":"HCL","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Подключение к Object Storage из VPC\r\n\r\n## Содержание\r\n- [Описание решения](#описание-решения)\r\n- [Рекомендации по развертыванию решения в продуктивной среде](#рекомендации-по-развертыванию-решения-в-продуктивной-среде)\r\n- [Подготовка к развертыванию](#подготовка-к-развертыванию)\r\n- [Развертывание Terraform сценария](#развертывание-terraform-сценария)\r\n- [Проверка работоспособности](#проверка-работоспособности)\r\n- [Удаление созданных ресурсов](#удаление-созданных-ресурсов)\r\n\r\n## Описание решения\r\n\r\nПодключиться к [Yandex Object Storage](https://cloud.yandex.ru/docs/storage/) в Yandex Cloud можно через соответствующий [API Endpoint](https://cloud.yandex.ru/docs/api-design-guide/concepts/endpoints/), FQDN которого потом преобразуется в публичный IP-адрес с помощью службы DNS.\r\n\r\nВ данном сценарии вы развернете в Yandex Cloud облачную инфраструктуру для организации доступа к Object Storage для ресурсов, которые размещены в облачной сети [VPC](https://cloud.yandex.ru/docs/vpc/concepts/) и не имеют публичных IP-адресов или выхода в интернет через [NAT-шлюз](https://cloud.yandex.ru/docs/vpc/concepts/gateways).\r\n\r\n\u003cimg src=\"./images/s3-hld.svg\" alt=\"Схема решения\" /\u003e\r\n\r\nПосле развертывания решения в Yandex Cloud будут созданы следующие компоненты:\r\n\r\n| Название | Описание |\r\n| ---- | ---- |\r\n| `s3-vpc` `*` | Облачная сеть с ресурсами, для которых организуется доступ к Object Storage. |\r\n| `s3-nlb` | Внутренний сетевой балансировщик обеспечивает прием трафика к Object Storage. Балансировщик принимает TCP трафик с портом назначения 443 и распределяет его по ресурсам (ВМ) в целевой группе. |\r\n| `s3-nat-group` | Целевая группа балансировщика с виртуальными машинами, на которых включена функция NAT. |\r\n| `nat-a1-vm`, `nat-a2-vm`, `nat-b1-vm`, `nat-b2-vm` | Виртуальные машины с NAT в зонах `ru-central1-a` и `ru-central1-b` для передачи трафика к Object Storage и обратно с трансляцией IP-адресов источников и получателей трафика. | \r\n| `pub-ip-a1`, `pub-ip-a2`, `pub-ip-b1`, `pub-ip-b2` | Публичные IP-адреса ВМ, в которые облачная сеть VPC транслирует их внутренние IP-адреса. | \r\n| `DNS зона и A-запись` | Внутренняя DNS зона `storage.yandexcloud.net.` в сети `s3-vpc` с ресурсной `A` записью, сопоставляющей доменное имя `storage.yandexcloud.net` c IP-адресом внутреннего сетевого балансировщика. |\r\n| `s3-bucket-\u003c...\u003e` | Бакет в Object Storage. |\r\n| `s3-subnet-a`, `s3-subnet-b` | Облачные подсети для размещения ВМ с NAT в зонах `ru-central1-a` и `ru-central1-b`. |\r\n| `test-s3-vm` | Тестовая ВМ для проверки доступа к Object Storage |\r\n| `test-s3-subnet-a` | Облачная подсеть для размещения тестовой ВМ |\r\n\r\n`*` *При развертывании можно также указать существующую облачную сеть*\r\n\r\nДля облачной сети с размещаемыми ресурсами в сервисе [Cloud DNS](https://cloud.yandex.ru/docs/dns/concepts/) создается внутренняя зона `storage.yandexcloud.net.` и ресурсная `A` запись, сопоставляющая доменное имя `storage.yandexcloud.net` сервиса Object Storage c IP-адресом [внутреннего сетевого балансировщика](https://cloud.yandex.ru/docs/network-load-balancer/concepts/nlb-types). Благодаря этой записи трафик от облачных ресурсов к Object Storage будет направляться на внутренний балансировщик, который будет распределять нагрузку по виртуальным машинам с NAT. \r\n\r\nДля развертывания ВМ с NAT используется [образ из Marketplace](https://cloud.yandex.ru/marketplace/products/yc/nat-instance-ubuntu-22-04-lts), который обеспечивает трансляции IP-адресов источника и назначения, чтобы обеспечить маршрутизацию трафика до публичного IP-адреса Object Storage.\r\n\r\nРазместив ВМ с NAT в нескольких [зонах доступности](https://cloud.yandex.ru/docs/overview/concepts/geo-scope), можно получить отказоустойчивость доступа к Object Storage. Увеличивая количество ВМ с NAT, можно масштабировать решение при возрастании нагрузки. При расчете количества ВМ с NAT следует учитывать [локальность при обработке трафика внутренним балансировщиком](https://cloud.yandex.ru/docs/network-load-balancer/concepts/specifics#nlb-int-locality). \r\n\r\n[Политика доступа Object Storage](https://cloud.yandex.ru/docs/storage/concepts/policy) разрешает действия с бакетом только с публичных IP-адресов ВМ с NAT. Доступ к бакету открыт только для облачных ресурсов, использующих данное решение. Подключиться к бакету в Object Storage через публичный API Endpoint не получится. При необходимости это ограничение можно отключить с помощью параметра в Terraform.\r\n\r\n\r\n## Рекомендации по развертыванию решения в продуктивной среде\r\n\r\n- При развертывании ВМ с NAT в нескольких зонах доступности рекомендуется указывать четное число ВМ для их равномерного распределения по зонам доступности.\r\n- Выбирая количество ВМ с NAT, следует учитывать [локальность при обработке трафика внутренним балансировщиком](https://cloud.yandex.ru/docs/network-load-balancer/concepts/specifics#nlb-int-locality).\r\n- После ввода решения в эксплуатацию рекомендуется уменьшать количество ВМ с NAT или изменять список зон доступности в параметре `yc_availability_zones` только в заранее запланированный период времени. В процессе применения изменений возможны прерывания в обработке трафика.\r\n- Если при возрастании нагрузки к Object Storage внутри ВМ с NAT наблюдается большое значение метрики `CPU steal time`, то для ВМ с NAT рекомендуется включить [программно-ускоренную сеть](https://cloud.yandex.ru/ru/docs/vpc/concepts/software-accelerated-network).\r\n- По умолчанию доступ к бакету в Object Storage разрешен через консоль управления Yandex Cloud. Это разрешение можно отменить с помощью параметра `bucket_console_access = false`. \r\n- Если не указать параметр `mgmt_ip` при `bucket_private_access = true`, то развертывание решения с помощью Terraform на рабочей станции будет завершаться с ошибкой доступа к бакету.\r\n- В случае использования собственного DNS сервера в его настройках необходимо создать ресурсные `A` записи вида:\r\n\r\n    | Имя | Тип | Значение |\r\n    | ----------- | ----------- | ----------- |\r\n    | `storage.yandexcloud.net.` | `A` | `\u003cIP-адрес_внутреннего_балансировщика\u003e` |\r\n    | `\u003cимя_бакета\u003e.storage.yandexcloud.net.` | `A` | `\u003cIP-адрес_внутреннего_балансировщика\u003e` |\r\n- Сохраните приватный SSH ключ `pt_key.pem`, используемый для подключения к ВМ с NAT, в надежное место либо пересоздайте его отдельно от Terraform.\r\n- После развертывания решения доступ по SSH к ВМ c NAT будет закрыт. Для разрешения доступа к ВМ с NAT по протоколу SSH добавьте входящее правило для SSH трафика (TCP/22) в группе безопасности `s3-nat-sg`, чтобы разрешить доступ только с определенных IP-адресов рабочих мест администраторов.\r\n- После проверки работоспособности удалите тестовую ВМ и её подсеть.\r\n\r\n\r\n## Подготовка к развертыванию\r\n\r\n1. Перед выполнением развертывания нужно [зарегистрироваться в Yandex Cloud и создать платежный аккаунт](https://cloud.yandex.ru/docs/tutorials/infrastructure-management/terraform-quickstart#before-you-begin)\r\n\r\n2. [Установите Terraform](https://cloud.yandex.ru/docs/tutorials/infrastructure-management/terraform-quickstart#install-terraform)\r\n\r\n3. Проверьте наличие учетной записи в облаке с правами `admin` на каталог\r\n\r\n4. [Установите и настройте Yandex Cloud CLI](https://cloud.yandex.ru/docs/cli/quickstart)\r\n\r\n5. [Установите Git](https://github.com/git-guides/install-git)\r\n\r\n6. Проверьте квоты в облаке, чтобы была возможность развернуть ресурсы в сценарии:\r\n\r\n    \u003cdetails\u003e\r\n    \u003csummary\u003eПосмотреть справочную информацию по количеству ресурсов, создаваемых в сценарии\u003c/summary\u003e\r\n\r\n    | Ресурс | Количество |\r\n    | ----------- | ----------- |\r\n    | Виртуальные машины | 5 |\r\n    | vCPU виртуальных машин | 10 |\r\n    | RAM виртуальных машин | 10 ГБ |\r\n    | Диски | 5 |\r\n    | Объем HDD дисков | 30 ГБ |\r\n    | Объем SSD дисков | 40 ГБ |\r\n    | Сетевой балансировщик | 1 |\r\n    | Целевая группа для балансировщика | 1 |\r\n    | Сети | 1`*` |\r\n    | Подсети | 3 |\r\n    | Статические публичные IP-адреса | 4 |\r\n    | Группы безопасности | 1 |\r\n    | Зона DNS | 1 |\r\n    | Бакет | 1 |  \r\n    | Сервисный аккаунт | 2 |\r\n    | Статический ключ для сервисного аккаунта | 1 |\r\n\r\n    `*` *Если пользователь в `terraform.tfvars` не указал идентификатора существующей сети.*\r\n\r\n    \u003c/details\u003e\r\n\r\n\r\n7. Перед развёртыванием решения уже должен существовать каталог облачных ресурсов в Yandex Cloud, в котором будут размещаться компоненты решения.\r\n\r\n\r\n## Развертывание Terraform сценария\r\n\r\n1. На вашей рабочей станции склонируйте [репозиторий](https://github.com/yandex-cloud-examples/yc-s3-private-endpoint/) `yandex-cloud-examples/yc-s3-private-endpoint` из GitHub и перейдите в папку сценария `yc-s3-private-endpoint`:\r\n    ```bash\r\n    git clone https://github.com/yandex-cloud-examples/yc-s3-private-endpoint.git\r\n    \r\n    cd yc-s3-private-endpoint\r\n    ```\r\n\r\n2. Настройте окружение для развертывания ([подробности](https://cloud.yandex.ru/docs/tutorials/infrastructure-management/terraform-quickstart#get-credentials)):\r\n    ```bash\r\n    export YC_TOKEN=$(yc iam create-token)\r\n    ```\r\n\r\n3. Заполните файл `terraform.tfvars` вашими значениями. Обязательные параметры для изменения отмечены в таблице.\r\n\r\n    \u003cdetails\u003e\r\n    \u003csummary\u003eПосмотреть детальную информацию о заполняемых значениях\u003c/summary\u003e\r\n\r\n    | Название\u003cbr\u003eпараметра | Нужно\u003cbr\u003eизменение | Описание | Тип | Пример |\r\n    | --- | --- | --- | --- | --- |\r\n    | `folder_id` | да | ID каталога для размещения компонент решения. | `string` | `b1gentmqf1ve9uc54nfh` |\r\n    | `vpc_id` | - | ID облачной сети, для которой организуется доступ к Object Storage. Если не указано, то VPC будет создана. | `string` | `enp48c1ndilt42veuw4x` |\r\n    | `yc_availability_zones` | - | Список \u003ca href=\"https://cloud.yandex.ru/docs/overview/concepts/geo-scope\"\u003eзон доступности\u003c/a\u003e для развертывания ВМ с NAT.  | `list(string)` | `[\"ru-central1-a\", \"ru-central1-b\"]` |\r\n    | `subnet_prefix_list` | - | Список префиксов облачных подсетей для размещения ВМ с NAT (по одной подсети в каждой зоне доступности из списка `yc_availability_zones`, перечисленных в порядке: ru-central1-a, ru-central1-b и т.д.). | `list(string)` | `[\"10.10.1.0/24\", \"10.10.2.0/24\"]` |\r\n    | `nat_instances_count` | - | Количество разворачиваемых ВМ с NAT. Рекомендуется указывать четное число для равномерного распределения ВМ по зонам доступности. | `number` | `4` |\r\n    | `bucket_private_access` | - | Ограничить доступ к бакету только с публичных IP-адресов ВМ с NAT. Используется значение `true` для ограничения, `false` для отмены ограничения. | `bool` | `true` |\r\n    | `bucket_console_access` | - | Разрешить доступ к бакету через консоль управления Yandex Cloud. Используется значение `true` для разрешения, `false` для запрета. Требует указания, когда параметр `bucket_private_access` имеет значение `true`. | `bool` | `true` |\r\n    | `mgmt_ip` | да | Публичный IP-адрес рабочей станции, на которой происходит развертывание Terraform сценария. Используется для разрешения рабочей станции выполнять действия с бакетом в процессе развертывания Terraform. Требует указания, когда параметр `bucket_private_access` имеет значение `true`. | `string` | `A.A.A.A` |\r\n    | `trusted_cloud_nets` | да | Список агрегированных префиксов облачных подсетей, для которых разрешен доступ к Object Storage. Используется во входящем правиле групп безопасности для ВМ с NAT.  | `list(string)` | `[\"10.0.0.0/8\", \"192.168.0.0/16\"]` |\r\n    | `vm_username` | - | Имя пользователя для ВМ с NAT и тестовой ВМ. | `string` | `admin` |\r\n    | `s3_ip` | - | Публичный IP-адрес сервиса Object Storage. | `string` | `213.180.193.243` |\r\n    | `s3_fqdn` | - | Доменное имя сервиса Object Storage. | `string` | `storage.yandexcloud.net` |  \r\n    \r\n    \u003c/details\u003e\r\n\r\n4. Выполните инициализацию Terraform:\r\n    ```bash\r\n    terraform init\r\n    ```\r\n\r\n5. Проверьте список создаваемых облачных ресурсов:\r\n    ```bash\r\n    terraform plan\r\n    ```\r\n\r\n6. Создайте ресурсы:\r\n    ```bash\r\n    terraform apply\r\n    ```\r\n\r\n7. После завершения процесса `terraform apply` в командной строке будет выведен список информации для подключения к тестовой ВМ и тестирования работы с Object Storage. В дальнейшем его можно будет посмотреть с помощью команды `terraform output`:\r\n\r\n    \u003cdetails\u003e\r\n    \u003csummary\u003eПосмотреть информацию о развернутых ресурсах\u003c/summary\u003e\r\n\r\n    | Название | Описание | Пример значения |\r\n    | ----------- | ----------- | ----------- |\r\n    | `path_for_private_ssh_key` | Файл с private ключом для подключения по протоколу SSH к ВМ с NAT и тестовой ВМ. | `./pt_key.pem` |\r\n    | `vm_username` | Имя пользователя для ВМ с NAT и тестовой ВМ. | `admin` |\r\n    | `test_vm_password` | Пароль пользователя `admin` для тестовой ВМ. | `v3RСqUrQN?x)` |\r\n    | `s3_bucket_name` | Имя бакета в Object Storage. | `s3-bucket-5efzzpvmys` |\r\n    | `s3_nlb_ip_address` | IP-адрес внутреннего балансировщика. | `10.10.1.100` |\r\n    \r\n    \u003c/details\u003e\r\n\r\n\r\n## Проверка работоспособности\r\n\r\n1. В консоли Yandex Cloud в каталоге `folder_id` выберите сервис `Compute Cloud` и в списке виртуальных машин выберите ВМ `test-s3-vm`. Подключитесь к серийной консоли ВМ, введите логин `admin` и пароль из вывода команды `terraform output test_vm_password` (укажите значение без кавычек).\r\n\r\n2. В серийной консоли ВМ выполните команду `dig storage.yandexcloud.net` и убедитесь, что в ответе от DNS сервера доменному имени сервиса Object Storage соответствует IP-адрес внутреннего балансировщика. Результат вывода ресурсной `A` записи:\r\n    ```\r\n    ;; ANSWER SECTION:\r\n    storage.yandexcloud.net. 300    IN      A       10.10.1.100\r\n    ```\r\n\r\n3. Получите объект из бакета в Object Storage с помощью команды инструмента [AWS CLI](https://cloud.yandex.ru/docs/storage/tools/aws-cli). Имя бакета будет получено из переменной среды на тестовой ВМ. \r\n\r\n    ```\r\n    aws --endpoint-url=https://storage.yandexcloud.net \\\r\n    s3 cp s3://$BUCKET/s3_test_file.txt s3_test_file.txt\r\n    ```\r\n\r\n    Результат:\r\n    ```\r\n    download: s3://\u003cимя-бакета\u003e/s3_test_file.txt to ./s3_test_file.txt\r\n    ```\r\n\r\n4. Дополнительно можете выполнить несколько команд для проверки работы с Object Storage. Имя бакета будет получено из переменной среды на тестовой ВМ.\r\n   \r\n   Загрузите скачанный тестовый файл в бакет под другим именем:\r\n    ```\r\n    aws --endpoint-url=https://storage.yandexcloud.net \\\r\n    s3 cp s3_test_file.txt s3://$BUCKET/textfile.txt\r\n    ```\r\n    \r\n    Результат:\r\n    ```\r\n    upload: ./s3_test_file.txt to s3://\u003cимя-бакета\u003e/textfile.txt\r\n    ```\r\n\r\n    Получите список объектов в бакете:\r\n    ```\r\n    aws --endpoint-url=https://storage.yandexcloud.net \\\r\n    s3 ls --recursive s3://$BUCKET\r\n    ```\r\n\r\n    Результат:\r\n    ```\r\n    2023-08-16 18:24:05         53 s3_test_file.txt \\\r\n    2023-08-16 18:41:39         53 textfile.txt\r\n    ```\r\n\r\n    Удалите загруженный в бакет объект:\r\n    ```\r\n    aws --endpoint-url=https://storage.yandexcloud.net \\\r\n    s3 rm s3://$BUCKET/textfile.txt\r\n    ```\r\n\r\n    Результат:\r\n    ```\r\n    delete: s3://\u003cимя-бакета\u003e/textfile.txt\r\n    ```\r\n\r\n\r\n## Удаление созданных ресурсов\r\n\r\nЧтобы удалить ресурсы, созданные с помощью Terraform, выполните команду `terraform destroy`.\r\n\r\n\u003e **Важно**\r\n\u003e \r\n\u003e Terraform удалит все ресурсы, которые были созданы при развертывании решения, без возможности восстановления.\r\n\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyandex-cloud-examples%2Fyc-s3-private-endpoint","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyandex-cloud-examples%2Fyc-s3-private-endpoint","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyandex-cloud-examples%2Fyc-s3-private-endpoint/lists"}