Если тело запроса или полезная нагрузка ответа могут быть одной из нескольких различных схем, можно использовать объект-дискриминатор , чтобы помочь в сериализации, десериализации и проверке. Дискриминатор — это конкретный объект в схеме, который используется для информирования потребителя о спецификации альтернативной схемы на основе связанного с ней значения.

При использовании дискриминатора встроенных схем не учитываются.

Фиксированные поля

Имя поля	Тип	Описание
имя свойства	струна	ТРЕБУЕТСЯ . Имя свойства в полезных данных, которое будет содержать значение дискриминатора.
отображение	[ строка , строка ]	Объект для хранения сопоставлений между значениями полезной нагрузки и именами схем или ссылками.

Объект дискриминатора допустим только при использовании одного из составных ключевых слов oneOf , anyOf , allOf .

В OAS 3.0 полезная нагрузка ответа МОЖЕТ быть описана как ровно один из любого количества типов:

 MyResponseType:
  один из:
  - $ref: '#/components/schemas/Cat'
  - $ref: '#/компоненты/схемы/собака'
  - $ref: '#/components/schemas/Lizard'
 

что означает, что полезная нагрузка ДОЛЖНА при проверке соответствовать ровно одной из схем, описанных Кошка , Собака или Ящерица . В этом случае дискриминатор МОЖЕТ действовать как «подсказка» для быстрой проверки и выбора соответствующей схемы, что может быть дорогостоящей операцией, в зависимости от сложности схемы. Затем мы можем точно описать, какое поле говорит нам, какую схему использовать:

 MyResponseType:
  один из:
  - $ref: '#/components/schemas/Cat'
  - $ref: '#/компоненты/схемы/собака'
  - $ref: '#/components/schemas/Lizard'
  дискриминатор:
    имя свойства: petType
 

Теперь ожидается, что свойство с именем petType ДОЛЖНО присутствовать в полезной нагрузке ответа , а его значение будет соответствовать имени схемы, определенной в документе OAS. Таким образом, полезная нагрузка ответа:

 {
  "идентификатор": 12345,
  "petType": "Кошка"
}
 

Указывает, что схема Cat должна использоваться вместе с этой полезной нагрузкой.

В сценариях, где значение поля дискриминатора не соответствует имени схемы или неявное сопоставление невозможно, необязательный сопоставление определение МОЖЕТ использоваться:

 MyResponseType:
  один из:
  - $ref: '#/components/schemas/Cat'
  - $ref: '#/компоненты/схемы/собака'
  - $ref: '#/components/schemas/Lizard'
  - $ref: 'https://gigantic-server. com/schemas/Monster/schema.json'
  дискриминатор:
    имя свойства: petType
    сопоставление:
      собака: '#/компоненты/схемы/собака'
      монстр: 'https://gigantic-server.com/schemas/Monster/schema.json'
 

Здесь дискриминатор значение из собака будет отображаться на схему #/components/schemas/Dog , а не на значение по умолчанию (неявное) Dog . Если значение дискриминатора не совпадает с неявным или явным сопоставлением, никакая схема не может быть определена, и проверка СЛЕДУЕТ завершиться ошибкой. Ключи сопоставления ДОЛЖНЫ быть строковыми значениями, но инструменты МОЖЕТ преобразовывать значения ответов в строки для сравнения.

При использовании в сочетании с конструкцией anyOf использование дискриминатора позволяет избежать неоднозначности, когда несколько схем могут удовлетворять одной полезной нагрузке.

В обоих вариантах использования oneOf и anyOf все возможные схемы ДОЛЖНЫ быть явно перечислены. Чтобы избежать избыточности, дискриминатор МОЖЕТ быть добавлен к определению родительской схемы, и все схемы, содержащие родительскую схему в конструкции allOf , могут использоваться в качестве альтернативной схемы.

Например:

 компоненты:
  схемы:
    Домашний питомец:
      тип: объект
      требуется:
      - тип питомца
      характеристики:
        тип питомца:
          тип: строка
      дискриминатор:
        имя свойства: petType
        сопоставление:
          собака Собака
    Кошка:
      все:
      - $ref: '#/components/schemas/Pet'
      - тип: объект
        # все остальные свойства, характерные для `Cat`
        характеристики:
          имя:
            тип: строка
    Собака:
      все:
      - $ref: '#/components/schemas/Pet'
      - тип: объект
        # все остальные свойства, характерные для `Dog`
        характеристики:
          лаять:
            тип: строка
    Ящерица:
      все:
      - $ref: '#/components/schemas/Pet'
      - тип: объект
        # все остальные свойства, специфичные для `Lizard`
        характеристики:
          любитRocks:
            тип: логический
 

такая полезная нагрузка:

 {
  "petType": "Кошка",
  "имя": "туманный"
}
 

будет означать, что используется схема Cat . Аналогично этой схеме:

 {
  "petType": "собака",
  «кора»: «мягкая»
}
 

будет отображаться в Dog из-за определения в элементе mappings .

Объект XML

Объект метаданных, позволяющий более точно настроить определения модели XML.

При использовании массивов имена элементов XML равны , а не (для форм единственного/множественного числа), и свойство имя СЛЕДУЕТ использовать для добавления этой информации. См. примеры ожидаемого поведения.

Фиксированные поля

Имя поля	Тип	Описание
имя	струна	Заменяет имя элемента/атрибута, используемого для описываемого свойства схемы. При определении в элементах это повлияет на имена отдельных элементов XML в списке. При определении рядом с тип является массивом (вне элементов ), это повлияет на элемент упаковки и только в том случае, если завернутый равен true . Если в оболочке равно false , это будет проигнорировано.
пространство имен	струна	URI определения пространства имен. Значение ДОЛЖНО быть в форме абсолютного URI.
префикс	струна	Префикс для имени.
атрибут	логическое значение	Указывает, преобразуется ли определение свойства в атрибут, а не в элемент. Значение по умолчанию: false .
в упаковке	логическое значение	МОЖЕТ использоваться только для определения массива. Указывает, является ли массив упакованным (например, ) или развернутым ( ). Значение по умолчанию: false . Определение вступает в силу только в том случае, если оно определено вместе с типа , являющимся массивом (вне элементов ).

Этот объект МОЖЕТ быть расширен за счет расширений спецификации.

Примеры XML-объектов

Примеры определений XML-объектов включены в определение свойства объекта схемы с образцом его XML-представления.

Нет XML-элемента

Свойство основной строки:

 {
    "животные": {
        "тип": "строка"
    }
}
 

 животных:
  тип: строка
 

 <животные>...
 

Свойство массива основных строк ( в оболочке по умолчанию false ):

 {
    "животные": {
        "тип": "массив",
        "Предметы": {
            "тип": "строка"
        }
    }
}
 

 животных:
  тип: массив
  Предметы:
    тип: строка
 

 <животные>...
<животные>...
<животные>...
 

Замена имени XML

 {
  "животные": {
    "тип": "строка",
    "xml": {
      "имя": "животное"
    }
  }
}
 

 животных:
  тип: строка
  XML:
    имя: животное
 

 <животное>. ..
 

XML-атрибут, префикс и пространство имен

В этом примере показано полное определение модели.

 {
  "Человек": {
    "тип": "объект",
    "характеристики": {
      "я бы": {
        "тип": "целое",
        "формат": "int32",
        "xml": {
          "атрибут": правда
        }
      },
      "имя": {
        "тип": "строка",
        "xml": {
          "пространство имен": "http://example.com/schema/sample",
          "префикс": "образец"
        }
      }
    }
  }
}
 

 Лицо:
  тип: объект
  характеристики:
    я бы:
      тип: целое число
      формат: int32
      XML:
        атрибут: правда
    имя:
      тип: строка
      XML:
        пространство имен: http://example.com/schema/sample
        префикс: образец
 

 <Лицо>
    пример

 

Массивы XML

Изменение имен элементов:

 {
  "животные": {
    "тип": "массив",
    "Предметы": {
      "тип": "строка",
      "xml": {
        "имя": "животное"
      }
    }
  }
}
 

 животные:
  тип: массив
  Предметы:
    тип: строка
    XML:
      имя: животное
 

 <животное>значение
<животное>значение
 

Внешнее свойство name не влияет на XML:

 {
  "животные": {
    "тип": "массив",
    "Предметы": {
      "тип": "строка",
      "xml": {
        "имя": "животное"
      }
    },
    "xml": {
      "имя": "инопланетяне"
    }
  }
}
 

 животных:
  тип: массив
  Предметы:
    тип: строка
    XML:
      имя: животное
  XML:
    Название: пришельцы
 

 <животное>значение
<животное>значение
 

Даже если массив упакован, если имя не определено явно, одно и то же имя будет использоваться как внутри, так и снаружи:

 {
  "животные": {
    "тип": "массив",
    "Предметы": {
      "тип": "строка"
    },
    "xml": {
      "завернутый": правда
    }
  }
}
 

 животных:
  тип: массив
  Предметы:
    тип: строка
  XML:
    завернутый: правда
 

 <животные>
  <животные>значение
  <животные>значение

 

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

 {
  "животные": {
    "тип": "массив",
    "Предметы": {
      "тип": "строка",
      "xml": {
        "имя": "животное"
      }
    },
    "xml": {
      "завернутый": правда
    }
  }
}
 

 животных:
  тип: массив
  Предметы:
    тип: строка
    XML:
      имя: животное
  XML:
    завернутый: правда
 

 <животные>
  <животное>значение
  <животное>значение

 

Влияет как на внутренние, так и на внешние имена:

 {
  "животные": {
    "тип": "массив",
    "Предметы": {
      "тип": "строка",
      "xml": {
        "имя": "животное"
      }
    },
    "xml": {
      "имя": "инопланетяне",
      "завернутый": правда
    }
  }
}
 

 животных:
  тип: массив
  Предметы:
    тип: строка
    XML:
      имя: животное
  XML:
    Название: пришельцы
    завернутый: правда
 

 <инопланетяне>
  <животное>значение
  <животное>значение

 

Если мы меняем внешний элемент, но не внутренние:

 {
  "животные": {
    "тип": "массив",
    "Предметы": {
      "тип": "строка"
    },
    "xml": {
      "имя": "инопланетяне",
      "завернутый": правда
    }
  }
}
 

 животных:
  тип: массив
  Предметы:
    тип: строка
  XML:
    Название: пришельцы
    завернутый: правда
 

 <инопланетяне>
  <инопланетяне>значение
  <инопланетяне>значение

 

Объект схемы безопасности

Определяет схему безопасности, которую могут использовать операции. Поддерживаемые схемы: HTTP-аутентификация, ключ API (в виде заголовка, параметра cookie или параметра запроса), общие потоки OAuth3 (неявные, пароль, учетные данные клиента и код авторизации), как определено в RFC6749, и OpenID Connect Discovery.

Фиксированные поля

Имя поля	Тип	Применяется к	Описание
тип	струна	Любой	ТРЕБУЕТСЯ . Тип схемы безопасности. Допустимые значения: "apiKey" , "http" , "oauth3" , "openIdConnect" .
описание	струна	Любой	Краткое описание схемы безопасности. Синтаксис CommonMark МОЖЕТ использоваться для форматированного текстового представления.
имя	струна	ключ API	ТРЕБУЕТСЯ . Имя используемого заголовка, запроса или файла cookie.
в	струна	ключ API	ТРЕБУЕТСЯ . Расположение ключа API. Допустимые значения: "запрос" , "заголовок" или "cookie" .
схема	струна	http	ТРЕБУЕТСЯ . Имя схемы авторизации HTTP, которая будет использоваться в заголовке авторизации, как определено в RFC7235. Используемые значения СЛЕДУЕТ зарегистрировать в реестре IANA Authentication Scheme.
форма носителя	струна	http ( "носитель" )	Подсказка клиенту определить формат токена носителя. Токены-носители обычно генерируются сервером авторизации, поэтому эта информация предназначена в первую очередь для целей документации.
потоки	Объект потоков OAuth	оаут3	ТРЕБУЕТСЯ . Объект, содержащий информацию о конфигурации для поддерживаемых типов потока.
опенидконнектурл	струна	опенидконнект	ТРЕБУЕТСЯ . URL-адрес OpenId Connect для обнаружения значений конфигурации OAuth3. Это ДОЛЖНО быть в форме URL.

Этот объект МОЖЕТ быть расширен за счет расширений спецификации.

Пример объекта схемы безопасности

Пример базовой аутентификации

 {
  "тип": "http",
  "схема": "базовая"
}
 

 тип: http
схема: базовая
 

Образец ключа API

 {
  "тип": "апиКей",
  "имя": "api_key",
  "в": "заголовок"
}
 

 тип: APIKey
имя: API_key
в: заголовок
 

Образец носителя JWT

 {
  "тип": "http",
  "схема": "носитель",
  "bearerFormat": "JWT",
}
 

 тип: http
схема: носитель
носительФормат: JWT
 

Неявный образец OAuth3

 {
  "тип": "oauth3",
  "течет": {
    "скрытый": {
      "authorizationUrl": "https://example. com/api/oauth/dialog",
      "области": {
        "write:pets": "изменить питомцев в вашем аккаунте",
        "read:pets": "читать своих питомцев"
      }
    }
  }
}
 

 тип: oauth3
потоки:
  скрытый:
    URL-адрес авторизации: https://example.com/api/oauth/dialog
    области:
      write:pets: изменить питомцев в своей учетной записи
      read:pets: читай своих питомцев
 

Объект потоков OAuth

Позволяет настраивать поддерживаемые потоки OAuth.

Фиксированные поля

Имя поля	Тип	Описание
неявный	Объект потока OAuth	Конфигурация для неявного потока OAuth
пароль	Объект потока OAuth	Конфигурация для потока пароля владельца ресурса OAuth
учетные данные клиента	Объект потока OAuth	Конфигурация потока учетных данных клиента OAuth. Ранее называвшееся приложением в OpenAPI 2. 0.
Код авторизации	Объект потока OAuth	Конфигурация потока кода авторизации OAuth. Ранее назывался accessCode в OpenAPI 2.0.

Этот объект МОЖЕТ быть расширен за счет расширений спецификации.

Объект потока OAuth

Сведения о конфигурации для поддерживаемого потока OAuth

Фиксированные поля

Имя поля	Тип	Применяется к	Описание
URL авторизации	струна	oauth3 ( "неявный" , "код авторизации" )	ТРЕБУЕТСЯ . URL-адрес авторизации, который будет использоваться для этого потока. Это ДОЛЖНО быть в форме URL.
URL-адрес токена	струна	oauth3 ( "пароль" , "учетные данные клиента" , "код авторизации" )	ТРЕБУЕТСЯ . URL-адрес токена, который будет использоваться для этого потока. Это ДОЛЖНО быть в форме URL.
URL-адрес обновления	струна	оаут3	URL-адрес, используемый для получения токенов обновления. Это ДОЛЖНО быть в форме URL.
прицелы	[ строка , строка ]	оаут3	ТРЕБУЕТСЯ . Доступные области для схемы безопасности OAuth3. Сопоставление между именем области действия и ее кратким описанием. Карта МОЖЕТ быть пустой.

Этот объект МОЖЕТ быть расширен за счет расширений спецификации.

Примеры объектов потока OAuth

 {
  "тип": "oauth3",
  "течет": {
    "скрытый": {
      "authorizationUrl": "https://example.com/api/oauth/dialog",
      "области": {
        "write:pets": "изменить питомцев в вашем аккаунте",
        "read:pets": "читать своих питомцев"
      }
    },
    "Код авторизации": {
      "authorizationUrl": "https://example. com/api/oauth/dialog",
      "tokenUrl": "https://example.com/api/oauth/токен",
      "области": {
        "write:pets": "изменить питомцев в вашем аккаунте",
        "read:pets": "читать своих питомцев"
      }
    }
  }
}
 

 тип: oauth3
потоки:
  скрытый:
    URL-адрес авторизации: https://example.com/api/oauth/dialog
    области:
      write:pets: изменить питомцев в своей учетной записи
      read:pets: читай своих питомцев
  Код авторизации:
    URL-адрес авторизации: https://example.com/api/oauth/dialog
    tokenUrl: https://example.com/api/oauth/token
    области:
      write:pets: изменить питомцев в своей учетной записи
      read:pets: читай своих питомцев
 

Security Requirement Object

Список необходимых схем безопасности для выполнения этой операции. Имя, используемое для каждого свойства, ДОЛЖНО соответствовать схеме безопасности, объявленной в схемах безопасности в объекте компонентов.

Security Requirement Объекты, которые содержат несколько схем, требуют, чтобы все схемы ДОЛЖНЫ быть удовлетворены для авторизации запроса. Это обеспечивает поддержку сценариев, в которых для передачи информации о безопасности требуется несколько параметров запроса или заголовков HTTP.

Когда список объектов требований безопасности определен для объекта OpenAPI или объекта операции, только один из объектов требований безопасности в списке должен быть удовлетворен для авторизации запроса.

Узорчатые поля

Шаблон поля	Тип	Описание
{имя}	[ строка ]	Каждое имя ДОЛЖНО соответствовать схеме безопасности, которая объявлена ​​в схемах безопасности в объекте компонентов. Если схема безопасности имеет тип "oauth3" или "openIdConnect" , то значение представляет собой список имен областей, необходимых для выполнения, и этот список МОЖЕТ быть пустым, если для авторизации не требуется указанная область. Для других типов схем безопасности массив ДОЛЖЕН быть пустым.

Примеры объектов требования безопасности

Требование безопасности без OAuth3

 {
  "апи_ключ": []
}
 

 API_key: []
 

Требование безопасности OAuth3

 {
  "зоомагазин_аутент": [
    "написать: домашние животные",
    "читать: домашние животные"
  ]
}
 

 petstore_auth:
- напиши: домашние животные
- читать: домашние животные
 

Дополнительная безопасность OAuth3

Дополнительная безопасность OAuth3, определенная в объекте OpenAPI или объекте операции:

 {
  "безопасность": [
    {},
    {
      "зоомагазин_аутент": [
        "написать: домашние животные",
        "читать: домашние животные"
      ]
    }
  ]
}
 

 безопасность:
  - {}
  - petstore_auth:
    - напиши: домашние животные
    - читать: домашние животные
 

Расширения спецификации

Хотя спецификация OpenAPI старается учесть большинство вариантов использования, в определенные моменты могут быть добавлены дополнительные данные для расширения спецификации.

Свойства расширений реализованы в виде шаблонных полей, которые всегда имеют префикс "x-" .

Расширения могут поддерживаться или не поддерживаться доступными инструментами, но они также могут быть расширены для добавления запрошенной поддержки (если инструменты являются внутренними или открытыми).

Фильтрация безопасности

Некоторые объекты в спецификации OpenAPI МОГУТ быть объявлены и оставаться пустыми или быть полностью удалены, даже если они по своей сути являются ядром документации API.

Причина в том, чтобы обеспечить дополнительный уровень контроля доступа к документации. Хотя это и не является частью самой спецификации, некоторые библиотеки МОГУТ разрешать доступ к частям документации на основе той или иной формы аутентификации/авторизации.

Два примера:

1. Объект Paths МОЖЕТ быть пустым. Это может показаться нелогичным, но это может сказать зрителю, что он попал в нужное место, но не может получить доступ к какой-либо документации. У них по-прежнему будет доступ к информационному объекту, который может содержать дополнительную информацию об аутентификации.
2. Объект элемента пути МОЖЕТ быть пустым. В этом случае зритель будет знать, что путь существует, но не сможет увидеть какие-либо его операции или параметры. Это отличается от сокрытия самого пути от объекта Paths, потому что пользователь будет знать о его существовании. Это позволяет поставщику документации точно контролировать то, что может видеть зритель.

Приложение A: История изменений

Версия	Дата	Примечания
3. 0.3	20.02.2020	Выпуск исправления спецификации OpenAPI 3.0.3
3.0.2	08.10.2018	Выпуск исправления спецификации OpenAPI 3.0.2
3.0.1	06.12.2017	Выпуск исправления спецификации OpenAPI 3.0.1
3.0.0	26.07.2017	Выпуск спецификации OpenAPI 3.0.0
3.0.0-rc2	16.06.2017	rc2 спецификации 3.0
3.0.0-rc1	27.04.2017	rc1 спецификации 3.0
3.0.0-rc0	28.02.2017	Проект реализации спецификации 3.0
2,0	31.12.2015	Пожертвование Swagger 2.0 инициативе OpenAPI
2,0	08.09.2014	Выпуск Swagger 2.0
1,2	14.03.2014	Первоначальный выпуск официального документа.
1,1	22 августа 2012 г.	Выпуск Swagger 1.1
1,0	10.08.2011	Первый выпуск спецификации Swagger

Составление спецификации | Docker Documentation

Расчетное время чтения: 85 минут

Файл Compose представляет собой файл YAML, определяющий службы, сети и тома для приложения Docker. Последние и рекомендуемые версия формата файла Compose определяется параметром Compose Технические характеристики. Спецификация Compose объединяет устаревшие Версии 2.x и 3.x, объединяющие свойства в этих форматах и ​​реализованные Compose 1.27.0+ .

В этом документе указывается формат файла Compose, используемый для определения приложений с несколькими контейнерами. Распространение данного документа не ограничено.

Ключевые слова «ДОЛЖЕН», «НЕ ДОЛЖЕН», «ТРЕБУЕТСЯ», «ДОЛЖЕН», «НЕ ДОЛЖЕН», «СЛЕДУЕТ», «НЕ ДОЛЖЕН», «РЕКОМЕНДУЕТСЯ», «МОЖЕТ» и «ДОПОЛНИТЕЛЬНО» в этом документе должны интерпретироваться, как описано в RFC 2119.

Требования и необязательные атрибуты

Спецификация Compose включает свойства, предназначенные для локальной среды выполнения контейнера OCI, предоставление конкретных параметров конфигурации ядра Linux, а также некоторых конкретных свойств контейнера Windows, а также функций облачной платформы, связанных с размещением ресурсов в кластере, распространением реплицированных приложений и масштабируемостью.

Мы признаем, что ни одна реализация Compose не должна поддерживать все атрибуты и что поддержка некоторых свойств зависит от платформы и может быть подтверждено только во время выполнения. Определение версионной схемы для управления поддерживаемыми свойства в файле Compose, установленные инструментом docker-compose, где Compose формат файла был разработан, не дает никаких гарантий того, что атрибуты конечного пользователя будут действительно реализованы.

Спецификация определяет ожидаемый синтаксис и поведение конфигурации, но, пока не указано иное, поддержка любого из них НЕОБЯЗАТЕЛЬНА.

Реализации Compose для анализа файла Compose с использованием неподдерживаемых атрибутов СЛЕДУЕТ предупреждать пользователя. Мы рекомендуем исполнителей для поддержки этих режимов работы:

• по умолчанию: предупреждать пользователя о неподдерживаемых атрибутах, но игнорировать их
• строгий: предупредить пользователя о неподдерживаемых атрибутах и ​​отклонить создание файла
• свободно: игнорировать неподдерживаемые атрибуты И неизвестные атрибуты (которые не были определены спецификацией на момент создания реализации)

Модель приложения Compose

Спецификация Compose позволяет определить приложение на основе контейнера, не зависящее от платформы. Такое приложение разработано как набор контейнеров, которые должны работать вместе с соответствующими общими ресурсами и каналами связи.

Вычислительные компоненты приложения определяются как службы. Служба — это абстрактная концепция, реализованная на платформах путем запуска одного и того же образа контейнера (и конфигурации) один или несколько раз.

Службы взаимодействуют друг с другом через Сети. В этой спецификации сеть представляет собой абстракцию возможности платформы для установления IP-маршрута между контейнерами в службах, связанных вместе. Низкоуровневые сетевые опции для конкретных платформ сгруппированы в определение сети и МОГУТ быть частично реализованы на некоторых платформах.

Службы хранят и совместно используют постоянные данные в томах. Спецификация описывает такие постоянные данные, как монтирование файловой системы высокого уровня с глобальными параметрами. Фактические детали реализации для конкретной платформы сгруппированы в определении Volumes и МОГУТ быть частично реализованы на некоторых платформах.

Для некоторых служб требуются данные конфигурации, которые зависят от среды выполнения или платформы. Для этого спецификация определяет специальную концепцию: Configs. С точки зрения сервисного контейнера конфигурации сравнимы с томами в том смысле, что они представляют собой файлы, смонтированные в контейнере. Но фактическое определение включает в себя отдельные ресурсы и службы платформы, которые абстрагируются этим типом.

Секрет — это особый вид данных конфигурации для конфиденциальных данных, которые НЕ ДОЛЖНЫ раскрываться без соображений безопасности. Секреты предоставляются службам в виде файлов, смонтированных в их контейнерах, но ресурсы для конкретных платформ для предоставления конфиденциальных данных достаточно специфичны, чтобы заслуживать отдельной концепции и определения в спецификации Compose.

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

Проект — это отдельное развертывание спецификации приложения на платформе. Название проекта используется для группировки ресурсы вместе и изолировать их от других приложений или другой установки одного и того же указанного приложения Compose с различными параметрами. Реализация Compose, создающая ресурсы на платформе, ДОЛЖНА ставить префиксы имен ресурсов по проекту и установить метку com.docker.compose.project .

Имя проекта может быть задано явным образом атрибутом имени верхнего уровня . Реализация Compose ДОЛЖНА предлагать пользователю возможность задать собственное имя проекта и переопределить это имя, чтобы один и тот же файл compose.yaml можно было дважды развернуть в одной и той же инфраструктуре без изменений, просто передав другое имя.

Наглядный пример

Следующий пример иллюстрирует концепции спецификации Compose на конкретном примере приложения. Пример ненормативный.

Рассмотрим приложение, разделенное на внешнее веб-приложение и внутреннюю службу.

Внешний интерфейс настраивается во время выполнения с файлом конфигурации HTTP, управляемым инфраструктурой, предоставляющим внешнее доменное имя и сертификат сервера HTTPS, введенный защищенным секретным хранилищем платформы.

Серверная часть хранит данные в постоянном томе.

Обе службы взаимодействуют друг с другом в изолированной сети заднего уровня, в то время как внешний интерфейс также подключен к сети переднего уровня и предоставляет порт 443 для внешнего использования.

 (внешний пользователь) --> 443 [интерфейсная сеть]
                            |
                  +--------------------+
                  | интерфейсная служба |...ro...
                  | "webapp" |...ro...<сертификат сервера> #secured
                  +--------------------+
                            |
                        [внутренняя сеть]
                            |
                  +--------------------+
                  | серверная служба | г+н ___________________
                  | "база данных" |=======(постоянный том)
                  +--------------------+ \_________________/
 

Пример приложения состоит из следующих частей:

• 2 службы, поддерживаемые образами Docker: веб-приложение и база данных
• 1 секрет (сертификат HTTPS), введенный во внешний интерфейс
• 1 конфигурация (HTTP), добавленная во внешний интерфейс
• 1 постоянный том, подключенный к серверной части
• 2 сети

 услуги:
  внешний интерфейс:
    изображение: круто/веб-приложение
    порты:
      - "443:8043"
    сети:
      - передний ярус
      - задний ярус
    конфиги:
      - httpd-конфигурация
    секреты:
      - сервер-сертификат
  серверная часть:
    изображение: круто/база данных
    тома:
      - БД-данные:/и т. д./данные
    сети:
      - задний ярус
тома:
  БД-данные:
    водитель: флокер
    driver_opts:
      размер: "10ГиБ"
конфиги:
  httpd-конфигурация:
    внешний: правда
секреты:
  сертификат сервера:
    внешний: правда
сети:
  # Наличие этих объектов достаточно для их определения
  передний уровень: {}
  задний уровень: {}
 

В этом примере показано различие между томами, конфигурациями и секретами. Пока все они все разоблачены для обслуживания контейнеров как смонтированных файлов или каталогов, только том может быть настроен для доступа на чтение и запись. Секреты и конфиги доступны только для чтения. Конфигурация тома позволяет выбрать драйвер тома и передать параметры драйвера настроить управление томами в соответствии с фактической инфраструктурой. Конфигурации и секреты полагаются на сервисы платформы, и объявлены внешними , так как они не управляются в рамках жизненного цикла приложения: реализация Compose будет использовать механизм поиска для конкретной платформы для получения значений времени выполнения.

Создать файл

Файл Compose представляет собой файл YAML, определяющий версия (УСТАРЕВШАЯ), услуги (ОБЯЗАТЕЛЬНО), сети, тома, конфиги и секреты. Путь по умолчанию для файла Compose — compose.yaml (предпочтительно) или compose.yml в рабочем каталоге. Реализации Compose ДОЛЖНЫ также поддерживать docker-compose.yaml и docker-compose.yml для обратной совместимости. Если существуют оба файла, реализации Compose ДОЛЖНЫ отдавать предпочтение каноническому compose.yaml .

Несколько файлов Compose можно объединить вместе для определения модели приложения. Комбинация файлов YAML ДОЛЖЕН быть реализован путем добавления/переопределения элементов YAML на основе порядка файлов Compose, установленного пользователем. Простой атрибуты и карты переопределяются файлом Compose самого высокого порядка, списки объединяются путем добавления. Родственник пути ДОЛЖНЫ быть разрешены на основе сначала Создавать родительскую папку файла всякий раз, когда комплементарные файлы объединенные размещаются в других папках.

Поскольку некоторые элементы файла Compose могут быть выражены как в виде отдельных строк, так и в виде сложных объектов, слияния ДОЛЖНЫ применяться к развернутая форма.

Профили

позволяют настроить модель приложения Compose для различных применений и сред. Написать реализации СЛЕДУЕТ позволять пользователю определять набор активных профилей. Точный механизм реализации специфичны и МОЖЕТ включать флаги командной строки, переменные среды и т. д.

Элемент верхнего уровня Services поддерживает атрибут profiles для определения списка именованных профилей. Услуги без набор атрибутов профилей ДОЛЖЕН быть включен всегда. Служба ДОЛЖНА игнорироваться Compose реализация, когда ни один из перечисленных профилей не соответствует активным, если только услуга не явно нацелен на команду. В этом случае его профили ДОЛЖНЫ быть добавлены в набор активных профилей. На все остальные элементы верхнего уровня не влияет профили и всегда активны.

Ссылки на другие службы (по ссылкам , расширяет или синтаксису общего ресурса service:xxx ) НЕ ДОЛЖНЫ автоматически включить компонент, который в противном случае был бы проигнорирован активными профилями. Вместо этого Реализация Compose ДОЛЖНА возвращать ошибку.

Наглядный пример

 услуги:
  фу:
    изображение: фу
  бар:
    изображение: бар
    профили:
      - тест
  баз:
    изображение: баз
    зависит от:
      - бар
    профили:
      - тест
  Зот:
    изображение: зот
    зависит от:
      - бар
    профили:
      - отлаживать
 

• Модель приложения Compose, проанализированная без включенного профиля, содержит только службу foo .
• Если профиль test включен, модель содержит сервисы bar и baz , которые включены тестовый профиль и служба foo , которая всегда включена.
• Если включен профиль debug , модель содержит службы foo и zot , но не bar и баз и поэтому модель недействительна в отношении ограничения depend_on zot .
• Если включены профили debug и test , модель содержит все сервисы: foo , bar , baz и zot .
• Если реализация Compose выполняется с полосой в качестве явной службы для запуска, она и профиль теста будет активен, даже если тест профиль не включен пользователем .
• Если реализация Compose выполняется с baz в качестве явной службы для запуска, служба baz и профиль test будет активен, а бар будет подтянут ограничением depend_on .
• Если реализация Compose выполняется с zot в качестве явной службы для запуска, модель снова будет недействительно в отношении ограничения depend_on , равного zot так как zot и бар не имеют общих профилей перечислено.
• Если реализация Compose выполняется с zot в качестве явной службы для запуска и включенным тестом профиля , профиль отладка автоматически включается, а служба bar подтягивается как зависимость, запускающая оба услуги зот и бар .

Версия элемента верхнего уровня

Верхний уровень версия определяется спецификацией для обратной совместимости, но носит только информативный характер.

Реализация Compose НЕ ДОЛЖНА использовать эту версию для выбора точной схемы для проверки файла Compose, но предпочитать самую последнюю схему на момент ее разработки.

Реализации Compose ДОЛЖНЫ проверять, могут ли они полностью анализировать файл Compose. Если некоторые поля неизвестны, обычно поскольку файл Compose был написан с полями, определенными в более новой версии спецификации, реализации Compose ДОЛЖЕН предупредить пользователя. Реализации Compose МОГУТ предлагать опции для игнорирования неизвестных полей (как определено в «свободном» режиме).

Имя элемента верхнего уровня

Имя верхнего уровня Имя определяется спецификацией как имя проекта, которое будет использоваться, если пользователь не задал его явно. Реализации Compose ДОЛЖНЫ предлагать пользователю способ переопределения этого имени и СЛЕДУЕТ определять механизм для вычисления имя проекта по умолчанию, которое будет использоваться, если элемент верхнего уровня name не установлен.

Всякий раз, когда имя проекта определяется именем верхнего уровня или каким-либо настраиваемым механизмом, оно ДОЛЖНО быть доступно для разрешение интерполяции и переменной среды как COMPOSE_PROJECT_NAME

 услуги:
  фу:
    изображение: бизибокс
    Окружающая среда:
      - COMPOSE_PROJECT_NAME
    команда: echo "Я запускаю ${COMPOSE_PROJECT_NAME}"
 

Элемент верхнего уровня службы

Служба — это абстрактное определение вычислительного ресурса в приложении, которое можно масштабировать/заменять. независимо от других компонентов. Сервисы поддерживаются набором контейнеров, управляемых платформой. в соответствии с требованиями к репликации и ограничениями по размещению. Службы поддерживаются контейнерами. образом Docker и набором аргументов времени выполнения. Все контейнеры в сервисе одинаково создаются с помощью этих аргументы.

Файл Compose ДОЛЖЕН объявлять корневой элемент services как карту, ключи которой являются строковыми представлениями имен служб, и чьи значения являются определениями службы. Определение службы содержит конфигурацию, которая применяется к каждому контейнер запущен для этой службы.

Каждая служба МОЖЕТ также включать раздел сборки, который определяет, как создать образ Docker для службы. Реализации Compose МОГУТ поддерживать создание образов Docker с использованием этого определения службы. Если не реализовано раздел Build СЛЕДУЕТ игнорировать, а файл Compose ДОЛЖЕН считаться действительным.

Поддержка сборки является НЕОБЯЗАТЕЛЬНЫМ аспектом спецификации Compose и подробно описано в документации по поддержке сборки.

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

Поддержка развертывания является НЕОБЯЗАТЕЛЬНЫМ аспектом спецификации Compose и подробно описано в документации по поддержке развертывания. Если он не реализован, раздел Deploy СЛЕДУЕТ игнорировать, а файл Compose ДОЛЖЕН считаться действительным.

сборка

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

blkio_config

blkio_config определяет набор параметров конфигурации для установки ограничений блока ввода-вывода для этой службы.

 услуги:
  фу:
    изображение: бизибокс
    blkio_config:
       вес: 300
       вес_устройство:
         - путь: /dev/sda
           вес: 400
       device_read_bps:
         - путь: /dev/sdb
           скорость: '12мб'
       device_read_iops:
         - путь: /dev/sdb
           скорость: 120
       device_write_bps:
         - путь: /dev/sdb
           скорость: '1024k'
       device_write_iops:
         - путь: /dev/sdb
           скорость: 30
 

device_read_bps, device_write_bps

Установить ограничение в байтах в секунду для операций чтения/записи на данном устройстве. Каждый элемент в списке ДОЛЖЕН иметь два ключа:

• путь : определение символического пути к затронутому устройству.
• rate : либо как целочисленное значение, представляющее количество байтов, либо как строка, выражающая значение байта.

device_read_iops, device_write_iops

Установить лимит операций в секунду для операций чтения/записи на данном устройстве. Каждый элемент в списке ДОЛЖЕН иметь два ключа:

• путь : определение символического пути к затронутому устройству.
• rate : как целочисленное значение, представляющее разрешенное количество операций в секунду.

вес

Изменить пропорцию пропускной способности, выделенной для этой службы, по сравнению с другими службами. Принимает целочисленное значение от 10 до 1000, по умолчанию — 500.

вес_устройство

Точная настройка распределения полосы пропускания по устройствам. Каждый элемент в списке должен иметь два ключа:

• путь : определение символического пути к затронутому устройству.
• вес : целое число от 10 до 1000.

число_процессоров

cpu_count определяет количество доступных ЦП для сервисного контейнера.

процессор_процент

cpu_percent определяет используемый процент доступных ЦП.

ЦП_доли

cpu_shares определяет (как целочисленное значение) относительный вес ЦП контейнера службы по сравнению с другими контейнерами.

период_процессора

cpu_period позволяют реализациям Compose настраивать период CPU CFS (Completely Fair Scheduler), когда платформа основана на ядре линукса.

ЦП_квота

cpu_quota позволяет реализациям Compose настраивать квоту ЦП CFS (Completely Fair Scheduler) на основе платформы на ядре линукса.

cpu_rt_runtime

cpu_rt_runtime настраивает параметры распределения ЦП для платформы с поддержкой планировщика реального времени. Может быть целочисленное значение, использующее микросекунды в качестве единиц измерения или длительности.

 cpu_rt_runtime: «400 мс»
 cpu_rt_runtime: `
 

cpu_rt_period

cpu_rt_period настраивает параметры распределения ЦП для платформы с поддержкой планировщика реального времени. Может быть целочисленное значение, использующее микросекунды в качестве единиц измерения или длительности.

 cpu_rt_period: '1400us'
 cpu_rt_период: 11000`
 

процессор

УСТАРЕЛО: используйте deploy.reservations.cpus

cpus определяют количество (потенциально виртуальных) процессоров, выделяемых сервисным контейнерам. Это дробное число. 0,000 означает отсутствие ограничений.

процессор

cpuset явно определяет ЦП, в которых разрешено выполнение. Может быть диапазоном 0-3 или списком 0,1

cap_add

cap_add указывает дополнительные возможности контейнера как струны.

 cap_add:
  - ВСЕ
 

cap_drop

cap_drop указывает возможности контейнера для удаления как струны.

 кап_дроп:
  - NET_ADMIN
  - SYS_АДМИН
 

cgroup_parent

cgroup_parent указывает НЕОБЯЗАТЕЛЬНУЮ родительскую cgroup для контейнера.

 cgroup_parent: m-executor-abcd
 

команда

команда переопределяет команду по умолчанию, объявленную образом контейнера (т.е. CMD Dockerfile).

: bundle exec thin -p 3000
 

: ["bundle", "exec", "thin", "-p", "3000"]
 

 услуги:
  редис:
    изображение: redis: последний
    конфиги:
      - мой_конфиг
конфиги:
  моя_конфигурация:
    файл: ./my_config.txt
  мой_другой_конфиг:
    внешний: правда
 

 услуги:
  редис:
    изображение: redis: последний
    конфиги:
      - источник: my_config
        цель: /redis_config
        ИД: "103"
        гид: "103"
        режим: 0440
конфиги:
  моя_конфигурация:
    внешний: правда
  мой_другой_конфиг:
    внешний: правда
 

 имя_контейнера: мой-веб-контейнер
 

 учетные_спецификации:
  файл: my-credential-spec. json
 

 HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Virtualization\Containers\CredentialSpecs
 

 учетные_спецификации:
  реестр: my-credential-spec
 

 услуги:
  моя служба:
    изображение: мое изображение: последнее
    Credential_spec:
      конфигурация: my_credential_spec
конфиги:
  my_credentials_spec:
    файл: ./my-credential-spec.json|
 

 услуги:
  веб:
    строить: .
    зависит от:
      - дб
      - редис
  редис:
    изображение: редис
  дБ:
    изображение: постгрес
 

 услуги:
  веб:
    строить: .
    зависит от:
      дБ:
        состояние: service_healthy
      редис:
        условие: service_started
  редис:
    изображение: редис
  дБ:
    изображение: постгрес
 

 device_cgroup_rules:
  - 'с 1:3 г'
  - 'а 7:* рмв'
 

 устройств:
  - "/dev/ttyUSB0:/dev/ttyUSB0"
  - "/dev/sda:/dev/xvda:rwm"
 

 днс: 8.8.8.8
 

 DNS:
  - 8.8.8.8
  - 9.9.9.9
 

 dns_opt:
  - использовать-VC
  - нет-TLD-запрос
 

 dns_search: example.com
 

 dns_search:
  - dc1.example.com
  - dc2.example.com
 

 точка входа: /code/entrypoint.sh
 

 точка входа:
  - пхп
  - -д
  - zend_extension=/usr/local/lib/php/extensions/no-debug-non-zts-20100525/xdebug. so
  - -д
  - memory_limit=-1
  - продавец/бен/phpunit
 

 env_file: .env
 

 env_file:
  - ./a.env
  - ./b.env
 

 # Установить среду Rails/Rack
RACK_ENV=разработка
VAR="в кавычках"
 

 среда:
  RACK_ENV: разработка
  ШОУ: "правда"
  ПОЛЬЗОВАТЕЛЬ_ВВОД:
 

 среда:
  - RACK_ENV=разработка
  - ПОКАЗАТЬ=истина
  - USER_INPUT
 

 разоблачить:
  - "3000"
  - "8000"
 

 расширяет:
  файл: common.yml
  сервис: веб-приложение
 

 услуги:
  общий:
    изображение: бизибокс
    Окружающая среда:
      TZ: UTC
      ПОРТ: 80
  Кли:
    расширяет:
      обслуживание: общее
    Окружающая среда:
      ПОРТ: 8080
 

 среда:
  ПОРТ: 8080
  TZ: UTC
изображение: бизибокс
 

 услуги:
  общий:
    изображение: бизибокс
    тома:
      - общий том:/var/lib/backup/data:rw
  Кли:
    расширяет:
      обслуживание: общее
    тома:
      - cli-volume:/var/lib/backup/data:ro
 

 изображение: занятбокс
тома:
- cli-volume:/var/lib/backup/data:ro
 

 услуги:
  база:
    изображение: бизибокс
    пользователь: корень
  общий:
    изображение: бизибокс
    расширяет:
      сервис: база
  Кли:
    расширяет:
      обслуживание: общее
 

 изображение: занятбокс
пользователь: корень
 

 услуги:
  общий:
    изображение: бизибокс
    security_opt:
      - метка: роль: РОЛЬ
  Кли:
    расширяет:
      обслуживание: общее
    security_opt:
      - метка:пользователь:ПОЛЬЗОВАТЕЛЬ
 

 изображение: занятбокс
security_opt:
- метка: роль: РОЛЬ
- метка:пользователь:ПОЛЬЗОВАТЕЛЬ
 

 внешних_ссылок:
  - редис
  - база данных: mysql
  - база данных: postgresql
 

 дополнительных_хостов:
  - "какой-то хост: 162.242.195.82"
  - "другой хост: 50.31.209.229"
 

 162.242.195.82 какой-то хост
50.31.209.229 другой хост
 

 услуги:
  моя служба:
    изображение: альпийский
    группа_добавить:
      - почта
 

 проверка здоровья:
  тест: ["CMD", "curl", "-f", "http://localhost"]
  интервал: 1м30с
  тайм-аут: 10 сек. 
  повторы: 3
  start_period: 40 с
 

 # Заходим в локальное веб-приложение
тест: ["CMD", "curl", "-f", "http://localhost"]
 

 тест: ["CMD-SHELL", "curl -f http://localhost || выход 1"]
 

: curl -f https://localhost || выход 1
 

 проверка здоровья:
  отключить: правда
 

 изображение: редис
    изображение: редис: 5
    изображение: redis@sha256:0ed5d5928d4737458944eb604cc8509e245c3e19d02ad83

 услуги:
  веб:
    изображение: альпийский: последний
    инициализация: правда
 

 ipc: "общий доступ"
    ipc: "сервис: [имя сервиса]"
 

 этикеток:
  com.example.description: "Бухгалтерское веб-приложение"
  com.example.department: "Финансы"
  com.example.label-with-empty-value: ""
 

 этикеток:
  - "com.example.description=Бухгалтерское веб-приложение"
  - "com.example.department=Финансы"
  - "com.example.label-with-empty-value"
 

 веб:
  ссылки:
    - дб
    - БД: база данных
    - редис
 

 ведение журнала:
  драйвер: системный журнал
  опции:
    syslog-адрес: "tcp://192. 168.0.42:123"
 

 network_mode: "хост"
    network_mode: "нет"
    network_mode: "сервис: [имя сервиса]"
 

 услуги:
  какой-то сервис:
    сети:
      - какая-то сеть
      - другая-сеть
 

 услуги:
  какой-то сервис:
    сети:
      какая-то сеть:
        псевдонимы:
          - псевдоним1
          - псевдоним3
      другая сеть:
        псевдонимы:
          - псевдоним2
 

В приведенном ниже примере служба 9Внешний интерфейс 0413 сможет подключиться к внутреннему сервису по адресу имя хоста серверная часть или база данных в сети заднего уровня и служба мониторинга сможет получить доступ к той же серверной службе по адресу db или mysql в сети admin .

 услуги:
  внешний интерфейс:
    изображение: круто/веб-приложение
    сети:
      - передний ярус
      - задний ярус
  мониторинг:
    изображение: круто/мониторинг
    сети:
      - администратор
  серверная часть:
    изображение: круто/бэкенд
    сети:
      задний уровень:
        псевдонимы:
          - база данных
      администратор:
        псевдонимы:
          - mysql
сети:
  передний ряд:
  задний уровень:
  администратор:
 

ipv4_адрес, ipv6_адрес

Укажите статический IP-адрес для контейнеров для этой службы при подключении к сети.

Соответствующая конфигурация сети в разделе сетей верхнего уровня ДОЛЖНА иметь Блок ipam с настройками подсети, охватывающими каждый статический адрес.

 услуги:
  внешний интерфейс:
    изображение: круто/веб-приложение
    сети:
      передний ряд:
        ipv4_адрес: 172.16.238.10
        ipv6_адрес: 2001:3984:3989::10
сети:
  передний ряд:
    IPAM:
      драйвер: по умолчанию
      конфигурация:
        - подсеть: "172. 16.238.0/24"
        - подсеть: "2001:3984:3989::/64"
 

link_local_ips

link_local_ips указывает список локальных IP-адресов. Link-local IP-адреса — это специальные IP-адреса, принадлежащие известной подсети и полностью управляются оператором, обычно в зависимости от архитектуры, в которой они находятся. развернут. Реализация зависит от платформы.

Пример:

 услуги:
  приложение:
    изображение: бизибокс
    команда: сверху
    сети:
      приложение_сеть:
        link_local_ips:
          - 57.123.22.11
          - 57.123.22.13
сети:
  приложение_сеть:
    водитель: мост
 

приоритет

приоритет указывает, в каком порядке реализации Compose СЛЕДУЕТ подключать контейнеры службы к своим сети. Если не указано, значение по умолчанию равно 0,

В следующем примере служба приложений сначала подключается к app_net_1, так как она имеет наивысший приоритет. Затем он подключается к app_net_3, затем к app_net_2, который использует значение приоритета по умолчанию 0,

 услуги:
  приложение:
    изображение: бизибокс
    команда: сверху
    сети:
      приложение_net_1:
        приоритет: 1000
      приложение_net_2:
      приложение_net_3:
        приоритет: 100
сети:
  приложение_net_1:
  приложение_net_2:
  приложение_net_3:
 

мак_адрес

mac_address устанавливает MAC-адрес для сервисного контейнера.

лимит_памяти

УСТАРЕЛО: используйте deploy.limits.memory

mem_reservation

УСТАРЕЛО: используйте deploy.reservations.memory

mem_swappiness

mem_swappiness определяет в процентах (значение от 0 до 100) для выгрузки ядра хоста анонимные страницы памяти, используемые контейнером.

• значение 0 отключает анонимный обмен страницами.
• значение 100 делает все анонимные страницы заменяемыми.

Значение по умолчанию зависит от платформы.

memswap_limit

memswap_limit определяет объем контейнера памяти, который разрешено выгружать на диск. Это модификатор атрибут, который имеет значение, только если память также установлена. Использование подкачки позволяет контейнеру записывать лишнее требования к памяти на диск, когда контейнер исчерпал всю доступную ему память. Существует потеря производительности для приложений, которые часто подкачивают память на диск.

• Если для memswap_limit задано положительное целое число, то ДОЛЖНЫ быть установлены как memory , так и memswap_limit . memswap_limit представляет собой общий объем памяти и подкачки, которые могут быть использованы, а memory управляет объемом используемой памяти без подкачки. Таким образом, если memory = «300m» и memswap_limit = «1g», контейнер может использовать 300m памяти и 700m (1g - 300m) подкачки.
• Если для параметра memswap_limit установлено значение 0, этот параметр ДОЛЖЕН игнорироваться, а значение считается неустановленным.
• Если для memswap_limit установлено то же значение, что и для memory , а для memory задано положительное целое число, контейнер не имеет доступа к подкачке. См. раздел Предотвращение использования контейнера подкачки.
• Если memswap_limit не задан, а memory установлен, контейнер может использовать столько подкачки, сколько указано в настройке memory , если в хост-контейнере настроена память подкачки. Например, если memory = «300m» и memswap_limit не установлен, контейнер может использовать в общей сложности 600 м памяти и подкачки.
• Если для memswap_limit явно установлено значение -1, контейнеру разрешено использовать неограниченный обмен до суммы, доступной в хост-системе.

oom_kill_disable

Если установлено oom_kill_disable Реализация Composite ДОЛЖНА настроить платформу так, чтобы она не убивала контейнер в случае голодания памяти.

oom_score_adj

oom_score_adj настраивает приоритет уничтожения контейнеров платформой в случае нехватки памяти. Значение ДОЛЖНО находиться в диапазоне [-1000,1000].

идентификатор

pid устанавливает режим PID для контейнера, созданного реализацией Compose. Поддерживаемые значения зависят от платформы.

pids_limit

УСТАРЕЛО: используйте deploy.reservations.pids

pids_limit настраивает ограничение PID контейнера. Установите значение -1 для неограниченного количества PID.

 pids_limit: 10
 

платформа

платформа определяет контейнеры целевой платформы для этой службы, используя синтаксис os[/arch[/variant]] . Реализация Compose ДОЛЖНА использовать этот атрибут при объявлении, чтобы определить, какая версия изображения будет извлечена. и/или на какой платформе будет выполняться сборка сервиса.

: osx
платформа: windows/amd64
платформа: линукс/arm64/v8
 

портов

Открывает контейнерные порты. Отображение портов НЕ ДОЛЖНО использоваться с network_mode: хост , и это ДОЛЖНО привести к ошибке времени выполнения.

Краткий синтаксис

Краткий синтаксис представляет собой строку, разделенную двоеточием, для установки IP-адреса хоста, порта хоста и порта контейнера. в форме:

[ХОСТ:]КОНТЕЙНЕР[/ПРОТОКОЛ] , где:

• HOST is [IP:](port | range)
• КОНТЕЙНЕР порт | диапазон
• ПРОТОКОЛ для ограничения порта указанным протоколом. значения tcp и udp определяются спецификацией, Реализации Compose МОГУТ предлагать поддержку имен протоколов для конкретных платформ.

IP-адрес хоста, если он не задан, ДОЛЖЕН быть привязан ко всем сетевым интерфейсам. Порт может быть один значение или диапазон. Хост и контейнер ДОЛЖНЫ использовать эквивалентные диапазоны.

Либо укажите оба порта ( HOST:CONTAINER ), либо только порт контейнера. В последнем случае Реализации Compose СЛЕДУЕТ автоматически выделять любой неназначенный хост-порт.

HOST:CONTAINER СЛЕДУЕТ всегда указывать в виде строки (в кавычках) во избежание конфликтов с поплавком yaml base-60.

Образцы:

 портов:
  - "3000"
  - "3000-3005"
  - "8000:8000"
  - "9090-9091:8080-8081"
  - "49100:22"
  - "127.0.0.1:8001:8001"
  - "127.0.0.1:5000-5010:5000-5010"
  - "6060:6060/удп"
 

Примечание : сопоставление IP-адресов хоста МОЖЕТ не поддерживаться на платформе, в этом случае реализациям Compose СЛЕДУЕТ отклонять файл Compose и ДОЛЖЕН сообщить пользователю, что он будет игнорировать указанный IP-адрес хоста.

Длинный синтаксис

Синтаксис длинной формы позволяет настраивать дополнительные поля, которые нельзя выражается в краткой форме.

• цель : контейнерный порт
• опубликовано : общедоступный порт. Может быть установлен как диапазон с использованием синтаксиса start-end , тогда фактический порт ДОЛЖЕН быть назначен в этом диапазоне на основе доступных портов.
• host_ip : сопоставление IP-адреса хоста, не указано, означает, что все сетевые интерфейсы ( 0.0.0.0 )
• протокол : протокол порта ( tcp или udp ), не указан означает любой протокол
• режим : хост для публикации порта хоста на каждом узле или вход для балансировки нагрузки порта.

 портов:
  - цель: 80
    host_ip: 127.0.0.1
    опубликовано: 8080
    протокол: TCP
    режим: хост
  - цель: 80
    host_ip: 127.0.0.1
    опубликовано: 8000-9000
    протокол: TCP
    режим: хост
 

привилегированный

привилегированный настраивает контейнер службы для запуска с повышенными привилегиями. Поддержка и фактические последствия зависят от платформы.

профилей

профили определяет список именованных профилей для включения службы. Если не установлено, служба всегда включена.

Если присутствует, профили ДОЛЖНЫ следовать формату регулярного выражения [a-zA-Z0-9][a-zA-Z0-9_.-]+ .

pull_policy

pull_policy определяет решения, которые будут принимать реализации Compose, когда он начнет извлекать изображения. Возможные значения:

• всегда : Реализации Compose ДОЛЖНЫ всегда извлекать образ из реестра.
• никогда : Реализации Compose НЕ ДОЛЖНЫ извлекать образ из реестра и СЛЕДУЕТ полагаться на кешированный образ платформы. Если нет кэшированного изображения, НЕОБХОДИМО сообщить об ошибке.
• отсутствует : Реализациям Compose СЛЕДУЕТ извлекать образ, только если он недоступен в кэше платформы. Это СЛЕДУЕТ использовать по умолчанию для реализации Compose без поддержки сборки. if_not_present СЛЕДУЕТ рассматривать псевдоним для этого значения для обратной совместимости
• сборка : реализациям Compose СЛЕДУЕТ создавать образ. Реализации Compose СЛЕДУЕТ перестраивать образ, если он уже существует.

Если pull_policy и сборка оба представлены, реализации Compose ДОЛЖНЫ создавать образ по умолчанию. Реализации Compose МОГУТ переопределить это поведение в цепочке инструментов.

только для чтения

read_only настраивает создание сервисного контейнера с файловой системой, доступной только для чтения.

перезагрузка

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

• нет : политика перезапуска по умолчанию. Ни при каких обстоятельствах не перезапускает контейнер.
• всегда : Политика всегда перезапускает контейнер до его удаления.
• при сбое : политика перезапускает контейнер, если код выхода указывает на ошибку.
• если не остановлено : политика перезапускает контейнер независимо от кода выхода, но останавливается перезапуск при остановке или удалении службы.

 перезапуск: "нет"
    перезапуск: всегда
    перезапуск: при сбое
    перезапуск: если не остановлен
 

время выполнения

среда выполнения указывает, какую среду выполнения следует использовать для контейнеров службы.

Значение среды выполнения зависит от реализации. Например, среда выполнения может быть именем реализации спецификации среды выполнения OCI, такой как «runc».

 веб:
  изображение: busybox: последний
  команда: правда
  время выполнения: runc
 

шкала

УСТАРЕЛО: используйте развертывание/реплики

масштаб указывает количество контейнеров по умолчанию для развертывания для этой службы.

секретов

secrets предоставляет доступ к конфиденциальным данным, определенным секретами, для каждой службы. Два поддерживаются различные варианты синтаксиса: короткий синтаксис и длинный синтаксис.

Реализации Compose ДОЛЖНЫ сообщать об ошибке, если секрет не существует на платформе или не определен в секреты раздела этого файла Compose.

Краткий синтаксис

Вариант с коротким синтаксисом указывает только секретное имя. Это дает контейнерный доступ к секрету и монтирует его как доступный только для чтения к /run/secrets/<имя_секрета> внутри контейнера. Имя источника и конечная точка монтирования установлены к секретному имени.

В следующем примере используется краткий синтаксис для предоставления внешнего интерфейса службы . доступ к секретному сертификату сервера . Значение сертификата сервера установлено к содержимому файла ./server. cert .

 услуги:
  внешний интерфейс:
    изображение: круто/веб-приложение
    секреты:
      - сервер-сертификат
секреты:
  сертификат сервера:
    файл: ./server.cert
 

Длинный синтаксис

Длинный синтаксис обеспечивает большую детализацию того, как секрет создается внутри контейнеры службы.

• источник : Имя секрета, существующее на платформе.
• цель : имя файла, который будет смонтирован в /run/secrets/ в контейнеры задач службы. По умолчанию источник , если не указано иное.
• uid и gid : числовой UID или GID, которому принадлежит файл в /run/secrets/ в контейнерах задач службы. Значение по умолчанию — запущенный контейнер USER.
• режим : Разрешения на монтирование файла в /run/secrets/ в контейнерах задач службы в восьмеричном представлении. Значение по умолчанию — права на чтение для всех (режим 0444 ). Бит записи ДОЛЖЕН игнорироваться, если он установлен. Исполняемый бит МОЖЕТ быть установлен.

В следующем примере для имени секретного файла сертификата сервера задается значение 9.0413 сервер.сертификат внутри контейнера устанавливает режим 0440 (доступно для чтения группой) и устанавливает пользователя и группу к 103 . Значение server-certificate secret предоставляется платформой через поиск и жизненный цикл секрета не управляется напрямую реализацией Compose.

 услуги:
  внешний интерфейс:
    изображение: круто/веб-приложение
    секреты:
      - источник: сертификат сервера
        цель: server.cert
        ИД: "103"
        гид: "103"
        режим: 0440
секреты:
  сертификат сервера:
    внешний: правда
 

Службам МОЖЕТ быть предоставлен доступ к нескольким секретам. Длинный и короткий синтаксис для секретов МОГУТ использоваться в тот же файл Compose. Определение секрета в секретах верхнего уровня НЕ ДОЛЖНО подразумевать предоставление доступа к нему какой-либо службе. Такое разрешение должно быть явным образом указано в спецификации службы как элемент секретной службы.

security_opt

security_opt переопределяет схему маркировки по умолчанию для каждого контейнера.

 безопасность_опт:
  - метка:пользователь:ПОЛЬЗОВАТЕЛЬ
  - метка: роль: РОЛЬ
 

размер_шм

shm_size настраивает размер общей памяти (раздел /dev/shm в Linux), разрешенный сервисным контейнером. Задается как значение байта.

stdin_open

stdin_open настраивает сервисные контейнеры для запуска с выделенным стандартным вводом.

stop_grace_period

stop_grace_period указывает, как долго реализация Compose ДОЛЖНА ждать при попытке остановить контейнер, если она не обрабатывать SIGTERM (или любой сигнал остановки, указанный с помощью stop_signal ), перед отправкой SIGKILL. Указанный как продолжительность.

 stop_grace_period: 1 с
    stop_grace_period: 1 м 30 с
 

Значение по умолчанию — 10 секунд для выхода из контейнера перед отправкой SIGKILL.

стоп_сигнал

stop_signal определяет сигнал, который ДОЛЖНА использоваться реализацией Compose для остановки сервисных контейнеров. Если неустановленные контейнеры останавливаются реализацией Compose, отправляя SIGTERM .

 стоп_сигнал: SIGUSR1
 

storage_opt

storage_opt определяет параметры драйвера хранилища для службы.

 storage_opt:
  размер: '1G'
 

системные файлы

sysctls определяет параметры ядра для установки в контейнере. sysctls может использовать либо массив, либо карту.

 системных файлов:
  net.core.somaxconn: 1024
  net.ipv4.tcp_syncookies: 0
 

 системных файлов:
  - net.core.somaxconn=1024
  - net.ipv4.tcp_syncookies=0
 

Вы можете использовать только те sysctl, пространство имен которых находится в ядре. Докер не поддержка изменения sysctl внутри контейнера, который также изменяет хост-систему. Обзор поддерживаемых sysctl см. в разделе Настройка ядра с пространством имен. параметры (sysctls) во время выполнения.

тмпфс

tmpfs монтирует временную файловую систему внутри контейнера. Может быть одним значением или списком.

 тмпфс: /выполнить
 

 тмпфс:
  - /бежать
  - /тмп
 

телетайп

tty настроить сервисный контейнер для работы с TTY.

пределов

ulimits переопределяет ulimits по умолчанию для контейнера. Либо указывает как один предел как целое число, либо мягкие/жесткие ограничения в качестве отображения.

 пределов:
  нпрок: 65535
  Нет файла:
    мягкий: 20000
    жесткий: 40000
 

пользователь

Пользователь переопределяет пользователя, используемого для запуска процесса контейнера. По умолчанию используется изображение (например, Dockerfile USER ), если не задано, root .

userns_mode

userns_mode задает пространство имен пользователя для службы. Поддерживаемые значения зависят от платформы и МОГУТ зависеть на конфигурации платформы

 userns_mode: "хост"
 

томов

тома определяет пути монтирования узлов или именованные тома, которые ДОЛЖНЫ быть доступны сервисным контейнерам.

Если монтирование является путем к хосту и используется только одной службой, оно МОЖЕТ быть объявлено как часть службы. определение вместо ключа верхнего уровня тома .

Чтобы повторно использовать том в нескольких службах, именованный том ДОЛЖЕН быть объявлен в ключе томов верхнего уровня .

В этом примере показан именованный том ( db-data ), используемый серверной службой , и монтирование привязки, определенное для одной службы

 услуги:
  серверная часть:
    изображение: круто/бэкенд
    тома:
      - тип: том
        источник: БД-данные
        цель: /данные
        объем:
          некопировать: правда
      - тип: связать
        источник: /var/run/postgres/postgres. sock
        цель: /var/run/postgres/postgres.sock
тома:
  БД-данные:
 

Краткий синтаксис

В коротком синтаксисе используется одна строка со значениями, разделенными двоеточием, для указания подключения тома. ( VOLUME:CONTAINER_PATH ) или режим доступа ( VOLUME:CONTAINER_PATH:ACCESS_MODE ).

• ТОМ : МОЖЕТ быть либо путем к хосту на платформе, на которой размещены контейнеры (привязка монтирования), либо именем тома
.
• CONTAINER_PATH : путь в контейнере, куда смонтирован том
• РЕЖИМ ДОСТУПА : представляет собой список параметров , , разделенных запятыми, и МОЖЕТ быть установлен на:
  • rw : доступ для чтения и записи (по умолчанию)
  • ro : доступ только для чтения
  • z : параметр SELinux указывает, что содержимое узла монтирования привязки используется несколькими контейнерами
  • Z : параметр SELinux указывает, что содержимое узла монтирования привязки является частным и недоступно для других контейнеров

Примечание : параметр SELinux перемаркировки привязки игнорируется на платформах без SELinux.

Примечание . Относительные пути к узлам ДОЛЖНЫ поддерживаться только реализациями Compose, развертываемыми на локальная среда выполнения контейнера. Это связано с тем, что относительный путь разрешается из родительского файла Compose. каталог, который применим только в локальном случае. Compose Реализации развертываются на нелокальном платформа ДОЛЖНА отклонять файлы Compose, которые используют относительные пути хоста с ошибкой. Во избежание неясностей относительные пути для именованных томов ДОЛЖНЫ всегда начинаться с . или .. .

Длинный синтаксис

Синтаксис длинной формы позволяет настраивать дополнительные поля, которые нельзя выражается в краткой форме.

• тип : тип крепления том , bind , tmpfs или npipe
• источник : источник монтирования, путь на хосте для монтирования привязки или имя тома, определенное в ключ верхнего уровня томов . Неприменимо для монтирования tmpfs.
• цель : путь в контейнере, где смонтирован том
• read_only : флаг для установки тома только для чтения
• bind : настроить дополнительные параметры связывания
  • распространение : режим распространения, используемый для привязки
  • create_host_path : создать каталог по исходному пути на хосте, если ничего нет. Ничего не делайте, если на пути что-то есть. Это автоматически подразумевается коротким синтаксисом для обратной совместимости с docker-compose legacy.
  • selinux : вариант перемаркировки SELinux z (общий) или Z (частный)
• том : настроить дополнительные параметры тома
  • nocopy : флаг для отключения копирования данных из контейнера при создании тома
• tmpfs : настроить дополнительные параметры tmpfs
  • размер : размер для монтирования tmpfs в байтах (либо в числовом, либо в байтовом формате)
  • режим : режим файла для монтирования tmpfs как биты разрешения Unix в виде восьмеричного числа
• согласованность : требования согласованности крепления. Доступные значения зависят от платформы

тома_от

volumes_from монтирует все тома из другого сервиса или контейнера, опционально указывая доступ только для чтения (ro) или чтение-запись (rw). Если уровень доступа не указан, то ДОЛЖНЫ использоваться чтение-запись.

Строковое значение определяет другую службу в модели приложения Compose для подключения томов. Контейнер : префикс , если он поддерживается, позволяет монтировать тома из контейнера, который не управляется Составить реализацию.

 томов_от:
  - наименование услуги
  - имя_службы:ro
  - контейнер:имя_контейнера
  - контейнер:имя_контейнера:rw
 

рабочий_каталог

work_dir переопределяет рабочий каталог контейнера, указанный в образе (т. е. Dockerfile РАБОЧИЙ КАТАЛОГ ).

Элемент верхнего уровня сети

Сети — это уровень, который позволяет службам взаимодействовать друг с другом. Сетевая модель, предоставляемая сервису ограничивается простым IP-соединением с целевыми службами и внешними ресурсами, в то время как определение сети позволяет тонкая настройка фактической реализации, предоставляемой платформой.

можно создать, указав имя сети в разделе верхнего уровня сетей . Сервисы могут подключаться к сетям, указав имя сети под сервисом сетей подраздел

В следующем примере во время выполнения будут созданы сети переднего уровня и заднего уровня , а также служба внешнего интерфейса . подключен к сети переднего уровня и сети заднего уровня .

 услуги:
  внешний интерфейс:
    изображение: круто/веб-приложение
    сети:
      - передний ярус
      - задний ярус
сети:
  передний ряд:
  задний уровень:
 

драйвер

Драйвер указывает, какой драйвер следует использовать для этой сети. Реализации Compose ДОЛЖНЫ возвращать ошибку, если Драйвер недоступен на платформе.

: оверлей
 

 услуги:
  веб:
    сети:
      хостнет: {}
сети:
  хостнет:
    внешний: правда
    имя: хозяин
 

 услуги:
  веб:
    ...
    сети:
      нонет: {}
сети:
  нонет:
    внешний: правда
    имя: нет
 

 driver_opts:
  фу: "бар"
  баз: 1
 

 сетей:
  мойнет1:
    драйвер: оверлей
    прикрепляемый: правда
 

 IP-адрес:
  драйвер: по умолчанию
  конфигурация:
    - подсеть: 172.28.0.0/16
      ip_range: 172.28.5.0/24
      шлюз: 172.28.5.254
      aux_адреса:
        хост1: 172.28.1.5
        хост2: 172.28.1.6
        хост3: 172.28.1.7
  опции:
    фу: бар
    баз: "0"
 

 этикеток:
  com.example.description: "Сеть финансовых транзакций"
  com.example.department: "Финансы"
  com.example.label-with-empty-value: ""
 

 этикеток:
  - "com. example.description=Сеть финансовых транзакций"
  - "com.example.department=Финансы"
  - "com.example.label-with-empty-value"
 

Сервисы:
  прокси:
    изображение: круто/прокси
    сети:
      - вне
      - дефолт
  приложение:
    изображение: круто/приложение
    сети:
      - дефолт
сети:
  вне:
    внешний: правда
 

 сетей:
  сеть1:
    имя: мое-приложение-сеть
 

 сетей:
  сеть1:
    внешний: правда
    имя: "${NETWORK_ID}"
 

 услуги:
  серверная часть:
    изображение: круто/база данных
    тома:
      - БД-данные:/и т.д./данные
  резервное копирование:
    изображение: служба резервного копирования
    тома:
      - БД-данные:/var/lib/резервная копия/данные
тома:
  БД-данные:
 

Запись под ключом томов верхнего уровня может быть пустой, и в этом случае она использует конфигурацию платформы по умолчанию для создание тома. Опционально можно настроить его следующими ключами:

драйвер

Укажите, какой драйвер тома следует использовать для этого тома. Значения по умолчанию и доступные значения зависят от платформы. Если драйвер недоступен, реализация Compose ДОЛЖНА вернуть ошибку и остановить развертывание приложения.

 драйвер: foobar
 

driver_opts

driver_opts указывает список параметров в виде пар ключ-значение для передачи драйверу для этого тома. Эти параметры зависят от драйвера.

 томов:
  пример:
    driver_opts:
      тип: "нфс"
      o: "addr=10.40.0.199,nolock,soft,rw"
      устройство: ":/докер/пример"
 

внешний

Если установлено значение true , external указывает, что этот том уже существует на платформе и его жизненный цикл управляется извне. того приложения. Реализации Compose НЕ ДОЛЖНЫ пытаться создать эти тома и ДОЛЖНЫ возвращать ошибку, если они не существует.

Если для external установлено значение true , Compose не управляет ресурсом. Если для external задано значение true , а в конфигурации сети установлены другие атрибуты, кроме name , то реализации Compose ДОЛЖНЫ отклонить файл Compose как недействительный.

В приведенном ниже примере вместо попытки создать том с именем {project_name}_db-data , Compose просто ищет существующий том называется БД-данные и монтирует его в контейнеры серверной службы .

 услуги:
  серверная часть:
    изображение: круто/база данных
    тома:
      - БД-данные:/и т.д./данные
тома:
  БД-данные:
    внешний: правда
 

этикетки

метки используются для добавления метаданных к томам. Вы можете использовать либо массив, либо словарь.

Рекомендуется использовать обратную DNS-нотацию, чтобы ваши метки не конфликтующие с теми, которые используются другим программным обеспечением.

 этикетки:
  com.example.description: "Том базы данных"
  com.example.department: "ИТ/эксплуатация"
  com.example.label-with-empty-value: ""
 

 этикеток:
  - "com.example.description=Объем базы данных"
  - "com.example.department=IT/Ops"
  - "com.example.label-with-empty-value"
 

Реализация Compose ДОЛЖНА устанавливать метки com. docker.compose.project и com.docker.compose.volume .

имя

имя установить пользовательское имя для этого тома. Поле имени можно использовать для ссылки на тома, содержащие специальные персонажи. Имя используется как есть и будет , а не , должны ограничиваться именем стека.

 томов:
  данные:
    имя: "данные моего приложения"
 

Его также можно использовать вместе с внешним свойством . При этом имя тома, используемого для поиска фактический объем на платформе задается отдельно от имени, используемого для ссылки на него в файле Compose:

 томов:
  БД-данные:
    внешний:
      имя: фактическое имя тома
 

Это позволяет сделать это имя поиска параметром файла Compose, чтобы идентификатор модели для тома жестко запрограммирован, но фактический идентификатор тома на платформе устанавливается во время выполнения во время развертывания:

 томов:
  БД-данные:
    внешний:
      имя: ${DATABASE_VOLUME}
 

Элемент верхнего уровня конфигурации

позволяют службам адаптировать свое поведение без необходимости перестраивать образ Docker. Конфигурации сопоставимы с томами с точки зрения службы, поскольку они монтируются в файловую систему контейнеров службы. Фактическая деталь реализации для получения конфигурации, предоставляемой платформой, может быть установлена ​​в определении конфигурации.

При предоставлении доступа к конфигурации содержимое конфигурации монтируется в виде файла в контейнере. Расположение точки монтирования внутри контейнера по умолчанию равно 9.0413 / в контейнерах Linux и C:\ в контейнерах Windows.

По умолчанию конфигурация ДОЛЖНА принадлежать пользователю, запускающему команду контейнера, но может быть переопределена конфигурацией службы. По умолчанию конфигурация ДОЛЖНА иметь права на чтение для всех (режим 0444), если служба не настроена для переопределения этого.

Службы могут получить доступ к конфигурациям только в том случае, если они явно предоставлены подразделом configs .

Высший уровень configs объявление определяет или ссылается данные конфигурации, которые могут быть предоставлены службам в этом заявление. Источником конфигурации является либо файл , либо внешний .

• файл : Конфиг создается с содержимым файла по указанному пути.
• external : если установлено значение true, указывает, что эта конфигурация уже создана. Реализация Compose не попытаться создать его, и если он не существует, возникает ошибка.
• имя : имя объекта конфигурации на платформе для поиска. Это поле можно использовать для ссылки на конфиги, содержащие специальные символы. Имя используется как есть и будет ли , а не охватывать имя проекта.

В этом примере создается http_config (как _http_config ) при развертывании приложения, и my_second_config ДОЛЖНЫ уже существовать на платформе, и значение будет получено путем поиска.

В этом примере server-http_config создается как _http_config при развертывании приложения, путем регистрации содержимого httpd. conf в качестве данных конфигурации.

 конфигов:
  http_config:
    файл: ./httpd.conf
 

В качестве альтернативы http_config можно объявить внешним, при этом реализация Compose будет искать http_config , чтобы предоставить данные конфигурации соответствующим службам.

 конфигов:
  http_config:
    внешний: правда
 

Внешний поиск конфигураций также может использовать отдельный ключ, указав имя . Следующее Пример изменяет предыдущий для поиска конфигурации с использованием параметра HTTP_CONFIG_KEY . Делает поэтому фактический ключ поиска будет установлен во время развертывания путем интерполяции переменные, но отображаются в контейнерах как жестко запрограммированный идентификатор http_config .

 конфигов:
  http_config:
    внешний: правда
    имя: "${HTTP_CONFIG_KEY}"
 

Если для external установлено значение true , Compose не управляет ресурсом. Если для external задано значение true , а в конфигурации сети установлены другие атрибуты, кроме name , то реализации Compose ДОЛЖНЫ отклонить файл Compose как недействительный.

Для создания файла необходимо явно предоставить доступ к конфигурациям соответствующим службам в приложении.

Секреты элемента верхнего уровня

— это разновидность конфигураций, ориентированных на конфиденциальные данные, с особыми ограничениями для этого использования. Поскольку реализация платформы может существенно отличаться от Конфигов, специальный раздел Секреты позволяет настраивать связанные ресурсы.

Объявление верхнего уровня secrets определяет или ссылается на конфиденциальные данные, которые могут быть предоставлены службам в этом заявление. Источником секрета является либо файл , либо внешний .

• файл : секрет создается с содержимым файла по указанному пути.
• среда : Секрет создается со значением переменной среды.
• внешний : если установлено значение true, указывает, что этот секрет уже создан. Реализация Compose делает не пытаться его создать, а если он не существует, возникает ошибка.
• name : Имя секретного объекта в Docker. Это поле можно использовать для ссылочные секреты, содержащие специальные символы. Имя используется как есть и будет ли , а не охватывать имя проекта.

В этом примере сертификат сервера секрет создается как _server-certificate при развертывании приложения, путем регистрации содержимого server.cert в качестве секрета платформы.

 секреты:
  сертификат сервера:
    файл: ./server.cert
 

В этом примере токен секрет создается как _token при развертывании приложения, путем регистрации содержимого переменной среды OAUTH_TOKEN в качестве секрета платформы.

 секретов:
  токен:
    среда: "OAUTH_TOKEN"
 

В качестве альтернативы, сертификат сервера может быть объявлен как внешний, при этом реализация Compose будет искать сертификат сервера , чтобы раскрыть секрет соответствующим службам.

 секретов:
  сертификат сервера:
    внешний: правда
 

Поиск внешних секретов также может использовать отдельный ключ, указав имя . Следующее Пример изменяет предыдущий для поиска секрета с использованием параметра CERTIFICATE_KEY . Делает поэтому фактический ключ поиска будет установлен во время развертывания путем интерполяции переменные, но отображаются в контейнерах как жестко запрограммированный идентификатор сервера сертификата сервера .

 секретов:
  сертификат сервера:
    внешний: правда
    имя: "${CERTIFICATE_KEY}"
 

Если для external установлено значение true , Compose не управляет ресурсом. Если для external задано значение true , а в конфигурации сети установлены другие атрибуты, кроме name , то реализации Compose ДОЛЖНЫ отклонить файл Compose как недействительный. Для создания файла необходимо явно предоставить доступ к секретам соответствующим службам в приложении.

Фрагменты

Можно повторно использовать фрагменты конфигурации с помощью привязок YAML.

 томов:
  БД-данные: &объем по умолчанию
    драйвер: по умолчанию
  метрики: *объем по умолчанию
 

В предыдущем примере якорь создается как том по умолчанию на основе спецификации тома db-data . Позже он повторно используется псевдонимом *default-volume для определения объема метрик . Та же логика может применяться к любому элементу в файле Compose. Якорное разрешение ДОЛЖНО иметь место перед интерполяцией переменных, поэтому переменные нельзя использовать для установки якорей или псевдонимов.

Также можно частично переопределить значения, заданные ссылкой привязки, с помощью Тип слияния YAML. В следующем примере метрик спецификация тома использует псевдоним чтобы избежать повторения, но переопределить имя атрибут:

Сервисы:
  серверная часть:
    изображение: круто/база данных
    тома:
      - БД-данные
      - метрики
тома:
  БД-данные: &объем по умолчанию
    драйвер: по умолчанию
    имя: "данные"
  показатели:
    <<: * объем по умолчанию
    название: "метрики"
 

Расширение

Специальные поля расширения могут иметь любой формат, если их имя начинается с последовательности символов x-. Их можно использовать внутри любой структуры в файле Compose. Это единственное исключение для реализаций Compose, которые молча игнорируют нераспознанные поля.

 х-пользовательский:
  фу:
    - бар
    - зот
Сервисы:
  веб-приложение:
    изображение: круто/веб-приложение
    х-фу: бар
 

Содержимое таких полей не указано в спецификации Compose и может использоваться для включения пользовательских функций. Реализация компоновки для обнаружения неизвестного поля расширения НЕ ДОЛЖНА завершаться ошибкой, но МОЖЕТ предупреждать о неизвестном поле.

Для расширений платформы настоятельно рекомендуется использовать префикс расширения по имени платформы/поставщика, так же, как браузеры добавляют поддержка пользовательских функций CSS.

 служба:
  серверная часть:
    развертывать:
      размещение:
        x-aws-role: "arn:aws:iam::XXXXXXXXXXXX:role/foo"
        x-aws-регион: "eu-west-3"
        x-azure-region: "центральная Франция"
 

Информативные исторические заметки

Этот раздел носит информативный характер. На момент написания были известны следующие префиксы:

Использование расширений в качестве фрагментов

Благодаря поддержке полей расширения файл Compose можно записать следующим образом, чтобы улучшить читаемость повторно используемых фрагментов:

 x-регистрация: & регистрация по умолчанию
  опции:
    максимальный размер: "12м"
    max-файл: "5"
  драйвер: json-файл
Сервисы:
  внешний интерфейс:
    изображение: круто/веб-приложение
    ведение журнала: * ведение журнала по умолчанию
  серверная часть:
    изображение: круто/база данных
    ведение журнала: * ведение журнала по умолчанию
 

указание значений байтов

Значение выражает значение байта в виде строки в формате {количество} {байтовая единица} : Поддерживаемые единицы: b (байты), k или kb (килобайты), m или mb (мегабайты) и g или gb (гигабайты).

 2б
    1024кб
    2048k
    300м
    1 ГБ
 

указание длительности

Значение, выражающее продолжительность в виде строки в формате {значение}{единица измерения} . Поддерживаемые единицы: us (микросекунды), ms (миллисекунды), s (секунды), m (минуты) и h (часы). Значение может объединять несколько значений и использоваться без разделителя.

 10 мс
  40-е годы
  1м30с
  1ч5м30с20мс
 

Интерполяция

Значения в файле Compose могут быть заданы переменными и интерполированы во время выполнения. Составные файлы используют Bash-подобный синтаксис ${ПЕРЕМНАЯ}

Поддерживаются синтаксис $VARIABLE и ${VARIABLE} . Значения по умолчанию могут быть определены встроенными с использованием типичного синтаксиса оболочки: последний

• ${ПЕРЕМЕННАЯ:-по умолчанию} оценивается как по умолчанию , если ПЕРЕМЕННАЯ не установлена ​​или пусто в окружающей среде.
• ${ПЕРЕМНАЯ-по умолчанию} оценивается как по умолчанию , только если ПЕРЕМЕННАЯ не установлена в окружающей среде.

Аналогично, следующий синтаксис позволяет указывать обязательные переменные:

• ${VARIABLE:?err} завершает работу с сообщением об ошибке, содержащим err , если ПЕРЕМЕННАЯ не задана или пуста в среде.
• ${VARIABLE?err} завершается с сообщением об ошибке, содержащим err , если ПЕРЕМЕННАЯ не задана в среде.

Интерполяция также может быть вложенной:

• ${ПЕРЕМНАЯ:-${FOO}}
• ${ПЕРЕМНАЯ?$FOO}
• ${ПЕРЕМЕННАЯ:-${FOO:-по умолчанию}}

Другие расширенные функции оболочки, такие как ${VARIABLE/foo/bar} , не поддерживается спецификацией Compose.

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