Создание домена в Yandex Cloud и его проксирование

ru/personal-domain-ya-cloud.md

@@ -0,0 +1,191 @@
+# Настройка личного домена и его проксирование.
+
+## Создание репозитория в Diplodoc
+
+Быстрый старт («Quick Start») — сервис, который поможет создать репозиторий и привязать его к внешнему сервису Diplodoc.
+
+Для создания базовой документации:
+
+1. Откройте [Быстрый старт](https://diplodoc.com/quickstart/).
+1. В шаге №1 авторизуйтесь в Github.
+1. В шаге №2 нажмите **Создать** и создайте репозиторий в Github. В результате будет создан проект с именем «diplodoc-example», предзаполненный командой Diplodoc.
+1. В шаге №3 нажмите **Создать** и создайте проект в Diplodoc.
+1. После выполнения пошаговой инструкции вы получите сообщение:
+
+    ```
+    Ключи от каталога с документацией в S3.
+    Идентификатор ключа:
+    ***********************
+    Секретный ключ:
+    ***********************
+
+    Сохраните идентификатор и ключ. После закрытия диалога значение ключа будет недоступно. Ключ будет добавлен в созданный репозиторий автоматически.
+    ```
+
+1. Дождитесь завершения релиза, проект будет доступен по ссылке в шаге №3 на странице [Быстрого старта](https://diplodoc.com/quickstart).
+
+## Подготовка Yandex Cloud для привязки домена
+
+### Создание API-шлюза
+
+1. Зарегистрируйте домен (можно воспользоваться [доменным регистратором](https://yandex.ru/search/?text=доменнный+регистратор)).
+1. Авторизуйтесь или создайте аккаунт в [Yandex Cloud](https://yandex.cloud/).
+
+    {% note warning %}
+
+    На странице [Биллинг](https://billing.yandex.cloud/accounts) убедитесь, что у вас подключен [платежный аккаунт](https://yandex.cloud/ru/docs/billing/concepts/billing-account) и находится в статусе `ACTIVE` или `TRIAL_ACTIVE`. Если платежного аккаунта нет, [создайте его](https://yandex.cloud/ru/docs/billing/quickstart/#create_billing_account).
+
+    {% endnote %}
+
+1. Перейдите в [консоль Yandex Cloud](https://console.yandex.cloud/folders/).
+1. Откройте **Все сервисы** → **API Gateway**.
+
+    {% note info %}
+
+    API Gateway — упрощенный сервер в Yandex Cloud, который позволяет обслуживать внешние запросы. Настраивается с помощью OpenAPI спецификации.
+
+    {% endnote %}
+
+1. Нажмите кнопку **Создать API-шлюз**.
+
+1. Заполните поля **Имя\*** и описание. Поле со звездочкой обязательно для заполнения.
+
+1. В поле **Сеть** выберите `default` или свой вариант.
+
+1. Заполните поле **Спецификация**: можно воспользоваться своей OpenAPI спецификацией или примером.
+
+    {% cut "Пример OpenAPI спецификации" %}
+
+    {% note warning %}
+
+    Вы можете использовать пример OpenAPI спецификации, но не забудьте изменить некоторые важные параметры, такие как: адрес внешнего домена или путь, на который должна проксироваться документация.
+
+    {% endnote %}
+
+    #### OpenAPI Спецификация
+
+    ```
+    openapi: 3.0.0
+    info:
+      title: Proxy Example
+      version: 1.0.0
+    servers:
+    - url: https://d5dj3947rd2qu5g1lbak.apigw.yandexcloud.net
+    - url: example-for-your-domain.net
+    paths:
+      /путь/{path+}:
+        get:
+          x-yc-apigateway-integration:
+            headers:
+              x-real-host: example-for-your-domain.net
+              x-docs-proxy-base: docs
+              x-docs-project-name: diplodoc-platform--docs
+            http_method: get
+            query:
+              '*': '*'
+            type: http
+            url: https://diplodoc-platform--docs.viewer.diplodoc.com/{path}
+          parameters:
+            - name: path
+              in: path
+              required: false
+              schema:
+                type: string
+    ```
+
+    #### Описание параметров OpenAPI спецификации
+
+    #|
+    || Параметр | Описание параметра ||
+    || `servers` | Настройка вложенных параметров `url` раздела `servers` позволит указать, по какому адресу необходимо проксировать документацию.
+    Для проксирования документации на ваш домен настройте вложенные параметры:
+
+    - Первый параметр `url` содержит адрес, на котором работает API Gateway, — оставьте значение по умолчанию.
+    - Для второго параметра `url` укажите внешний домен, на который нужно проксировать документацию. ||
+    || `paths` | Содержит вложенное правило, которое позволяет конфигурировать ответ для параметра `url` из раздела `servers`. Параметр `/путь/{path+}:`, вложенный в раздел `paths`, указывает, по какому пути должна располагаться документация. 
+
+    {% note info %}
+
+    Если вы используете пример OpenAPI спецификации, то документация будет расположена по пути `example-for-your-domain.net/docs`.
+
+    {% endnote %}||
+
+    || `get` | Вложенное правило, которое обрабатывает все get-запросы. ||
+    || `headers` | Раздел содержит служебные заголовки. Для настройки служебных заголовков:
+
+    1\. В параметре `x-real-host:` укажите адрес домена.
+    2\. В параметре `x-docs-proxy-base:` укажите каталог, на котором будет размещаться документация.
+    3\. В параметре `x-docs-project-name:`укажите название проекта.||
+    || `url` | Параметр, вложенный в правило `get`, содержит адрес, на который перенаправляется документация.
+
+    {% note info %} 
+
+    Если вы используете пример OpenAPI спецификации, то документация будет перенаправляться на домен диплодока.
+
+    {% endnote %}||
+
+    || `parameters` | Раздел обрабатывает параметр `path` по заданному правилу. ||  
+    |#
+
+    {% note warning %}
+
+    Для размещения в корне домена в OpenAPI-конфигурации измените:
+
+    1. У параметра `x-docs-proxy-base` значение на `' '`.
+    1. У параметра `paths:` значение на `{path+}:`.
+
+    {% endnote %}
+
+    {% endcut %}
+
+1. Нажмите **Создать**.
+1. Если платежный аккаунт не привязан, нажмите **Привязать**.
+1. В результате должен появиться API-шлюз со статусом `active`.
+1. Теперь Yandex Cloud может проксировать документацию на свой url.
+1. Чтобы заработало проксирование на внешний домен, [создайте новый или загрузите личный сертификат]((#cert-creating)).
+
+### Создание/загрузка сертификата {#cert-creating}
+
+Для создания или загрузки личного сертификата:
+
+1. Перейдите в [консоль](https://console.yandex.cloud/folders/).
+1. Откройте **Все сервисы** → **Certificate Manager**.
+1. Нажмите **Создать сертификат**.
+1. На странице выберите **Добавить сертификат** → **Сертификат от Let's Encrypt**.
+
+    {% note info %}
+
+    Если у вас уже есть сертификат, который зарегистрирован во внешнем сервисе, вы можете использовать его, для этого в выпадающем меню выберите **Пользовательский сертификат**.
+
+    {% endnote %}
+
+1. Заполните поля **Имя\*** и описание. Поле со звездочкой обязательно для заполнения.
+1. Укажите **Домены\***, для которых необходимо добавить сертификат. Поле обязательно для заполнения.
+1. Выберите в поле **Тип проверки** — DNS.
+1. Созданный сертификат будет ожидать подтверждения со статусом `Validating`.
+1. [Подтвердите](#cert-validating), что вы являетесь владельцем домена.
+
+### Подтверждение сертификата {#cert-validating}
+
+Для подтверждения прав на владение доменом:
+
+1. Перейдите в [консоль](https://console.yandex.cloud/folders/).
+1. Откройте **Все сервисы** → **Certificate Manager**.
+1. Выберите созданный или добавленный сертификат.
+1. Подтвердите права на владение доменом, используя один из предложенных способов.
+1. Права на владение домена подтверждены.
+1. [Подключите домен](#connect-domain).
+
+## Привязка домена к Yandex Cloud
+
+### Подключение домена {#connect-domain}
+
+Для завершения привязки домена к Yandex Cloud:
+
+1. Откройте **Все сервисы** → **API Gateway**.
+1. Выберите созданный API-шлюз.
+1. В левом меню нажмите **домены** → **Подключить**.
+1. Выберите созданный сертификат.
+1. Укажите домен.
+1. Нажмите **Подключить**.
+1. Настройка проксирования на личный домен завершена.

ru/toc.yaml

@@ -33,6 +33,8 @@ items:
     href: about.md
   - name: Быстрый старт
     href: quickstart.md
+  - name: Настройка личного домена
+    href: personal-domain-ya-cloud.md
   - name: Yandex Flavored Markdown
     expanded: true
     href: index-yfm.md
@@ -143,4 +145,4 @@ items:
         href: vacancy.md
   - name: Yandex Open Source Jam 2024
     hidden: true
-    href: jam.md
+    href: jam.md