Ресурс openssl_x509_certificate

Редактировать эту страницу в репозитории Chef

Страница со всеми ресурсами Infra

Используйте ресурс openssl_x509_certificate для генерации подписанных или самоподписанных сертификатов x509 в формате PEM. Если существующий ключ не указан, ресурс автоматически сгенерирует ключ без пароля вместе с сертификатом. Если предоставлены закрытый ключ и сертификат центра сертификации (CA), сертификат будет подписан ими.

Новое в Chef Infra Client 14.4.

Синтаксис

Полный синтаксис для всех свойств, доступных ресурсу openssl_x509_certificate:

openssl_x509_certificate 'name' do
  ca_cert_file             String
  ca_key_file              String
  ca_key_pass              String
  city                     String
  common_name              String
  country                  String
  csr_file                 String
  email                    String
  expire                   Integer # default value: 365
  extensions               Hash # default value: {}
  group                    String, Integer
  key_curve                String # default value: "prime256v1"
  key_file                 String
  key_length               Integer # default value: 2048
  key_pass                 String
  key_type                 String # default value: "rsa"
  mode                     Integer, String
  org                      String
  org_unit                 String
  owner                    String, Integer
  path                     String # default value: 'name' unless specified
  renew_before_expiry      Integer
  state                    String
  subject_alt_name         Array # default value: []
  action                   Symbol # defaults to :create if not specified
end

где:

• openssl_x509_certificate — это ресурс.
• name — это имя, данное блоку ресурса.
• action определяет, какие действия выполнит клиент Chef Infra для приведения узла в желаемое состояние.
• ca_cert_file, ca_key_file, ca_key_pass, city, common_name, country, csr_file, email, expire, extensions, group, key_curve, key_file, key_length, key_pass, key_type, mode, org, org_unit, owner, path, renew_before_expiry, state, и subject_alt_name — это свойства, доступные этому ресурсу.

Действия

Ресурс openssl_x509_certificate имеет следующие действия:

:create

Генерирует файл сертификата. (по умолчанию)

:nothing

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

Свойства

Ресурс openssl_x509_certificate имеет следующие свойства:

ca_cert_file

Тип Ruby: String

Путь к сертификату CA X509 в файловой системе. Если указано свойство ca_cert_file, то должно быть указано и свойство ca_key_file, сертификат будет подписан ими.

ca_key_file

Тип Ruby: String

Путь к закрытому ключу CA в файловой системе. Если указано свойство ca_key_file, то должно быть указано и свойство ca_cert_file, сертификат будет подписан ими.

ca_key_pass

Тип Ruby: String

Пароль для закрытого ключа CA.

city

Тип Ruby: String

Значение для поля сертификата L.

common_name

Тип Ruby: String

Значение для поля сертификата CN.

country

Тип Ruby: String

Значение для поля сертификата C.

csr_file

Тип Ruby: String

Путь к запросу на сертификат X509 (CSR) в файловой системе. Если указано свойство csr_file, ресурс попытается получить CSR из этого места. Если файл CSR не найден, ресурс сгенерирует самоподписанный сертификат, и поля сертификата должны быть указаны (common_name — обязательно).

email

Тип Ruby: String

Значение для поля сертификата email.

expire

Тип Ruby: Integer | Значение по умолчанию: 365

Значение, представляющее количество дней с текущего момента, в течение которого выданный сертификат будет действителен. Сертификат истечет по истечении этого периода.

extensions

Тип Ruby: Hash | Значение по умолчанию: {}

Хэш записей расширений X509 в формате { 'keyUsage' => { 'values' => %w( keyEncipherment digitalSignature), 'critical' => true } }.

group

Тип Ruby: String, Integer

Группа владельцев, применяемая ко всем файлам, созданным ресурсом.

key_curve

Тип Ruby: String | Значение по умолчанию: prime256v1 Допустимые значения: "prime256v1", "secp384r1", "secp521r1"

Желаемая кривая сгенерированного ключа (если key_type равен 'ec'). Запустите openssl ecparam -list_curves для просмотра доступных опций.

key_file

Тип Ruby: String

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

key_length

Тип Ruby: Integer | Значение по умолчанию: 2048 Допустимые значения: 1024, 2048, 4096, 8192

Желаемая длина в битах сгенерированного ключа (если key_type равен 'rsa').

key_pass

Тип Ruby: String

Пароль для существующего ключа.

key_type

Тип Ruby: String | Значение по умолчанию: rsa Допустимые значения: "ec", "rsa"

Желаемый тип сгенерированного ключа.

mode

Тип Ruby: Integer, String

Режим разрешений, применяемый ко всем файлам, созданным ресурсом.

org

Тип Ruby: String

Значение для поля сертификата O.

org_unit

Тип Ruby: String

Значение для поля сертификата OU.

owner

Тип Ruby: String, Integer

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

path

Тип Ruby: String | Значение по умолчанию: The resource block's name

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

renew_before_expiry

Тип Ruby: Integer

Количество дней до истечения срока действия. Сертификат будет автоматически обновлен, когда будет достигнуто это значение.

Новое в Chef Infra Client 15.7

state

Тип Ruby: String

Значение для поля сертификата ST.

subject_alt_name

Тип Ruby: Array | Значение по умолчанию: []

Массив записей альтернативного имени субъекта в формате DNS:example.com или IP:1.2.3.4.

Общие функции ресурса

Ресурсы Chef включают общие свойства, уведомления и средства защиты ресурсов.

Общие свойства

Следующие свойства являются общими для каждого ресурса:

compile_time

Тип Ruby: true, false | Значение по умолчанию: false

Управление фазой, во время которой ресурс выполняется на узле. Установите значение true для выполнения во время построения коллекции ресурсов (compile phase). Установите значение false для выполнения во время настройки узла клиентом Chef Infra (converge phase).

ignore_failure

Тип Ruby: true, false, :quiet | Значение по умолчанию: false

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

retries

Тип Ruby: Integer | Значение по умолчанию: 0

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

retry_delay

Тип Ruby: Integer | Значение по умолчанию: 2

Задержка в секундах между повторными попытками.

sensitive

Тип Ruby: true, false | Значение по умолчанию: false

Убедитесь, что конфиденциальные данные ресурса не регистрируются клиентом Chef Infra.

Уведомления

notifies

Тип Ruby: Symbol, 'Chef::Resource[String]'

Ресурс может уведомлять другой ресурс о необходимости действий при изменении его состояния. Укажите 'resource[name]', :action, которое должен выполнить этот ресурс, а затем :timer для этого действия. Ресурс может уведомлять более чем один ресурс; используйте инструкцию notifies для каждого ресурса, который должен быть уведомлен.

Если указанный ресурс не существует, возникает ошибка. В отличие от этого, subscribes не завершится ошибкой, если исходный ресурс не найден.

Таймер указывает момент во время выполнения клиента Chef Infra, когда выполняется уведомление. Доступны следующие таймеры:

:before

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

:delayed

По умолчанию. Указывает, что уведомление должно быть помещено в очередь и затем выполнено в конце выполнения Chef Infra Client.

:immediate, :immediately

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

Синтаксис для notifies:

notifies :action, 'resource[name]', :timer

subscribes

Тип Ruby: Символ, 'Chef::Resource[Строка]'

Ресурс может отслеживать другой ресурс и затем выполнять действие, если состояние отслеживаемого ресурса изменится. Укажите 'resource[name]', :action действие, и :timer для этого действия.

Обратите внимание, что subscribes не применяет указанное действие к ресурсу, за которым он следит — например:

file '/etc/nginx/ssl/example.crt' do
  mode '0600'
  owner 'root'
end

service 'nginx' do
  subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end

В этом случае свойство subscribes перезагружает сервис nginx всякий раз, когда файл сертификата, расположенный по адресу /etc/nginx/ssl/example.crt, обновляется. subscribes не вносит никаких изменений в сам файл сертификата, а просто отслеживает изменения в файле и выполняет действие :reload для своего ресурса (в этом примере nginx) при обнаружении изменений.

Если другой ресурс не существует, подписка не вызовет ошибку. Это отличается от более строгих семантик notifies, которые вызовут ошибку, если другой ресурс не существует.

Таймер указывает момент во время выполнения Chef Infra Client, в котором выполняется уведомление. Доступны следующие таймеры:

:before

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

:delayed

По умолчанию. Указывает, что уведомление должно быть помещено в очередь и затем выполнено в конце выполнения Chef Infra Client.

:immediate, :immediately

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

Синтаксис для subscribes:

subscribes :action, 'resource[name]', :timer

Блокирующие условия

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

• Строка выполняется как команда оболочки. Если команда возвращает 0, блокирующее условие применяется. Если команда возвращает любое другое значение, то свойство блокирующего условия не применяется. Строковые блокирующие условия в powershell_script выполняют команды Windows PowerShell и могут возвращать true в дополнение к 0.
• Блок выполняется как код Ruby, который должен вернуть либо true либо false. Если блок возвращает true, свойство блокирующего условия применяется. Если блок возвращает false, свойство блокирующего условия не применяется.

Свойство блокирующего условия полезно для обеспечения идемпотентности ресурса, позволяя этому ресурсу проверить желаемое состояние по мере его выполнения, а затем, если желаемое состояние присутствует, Chef Infra Client ничего не делает.

Следующие свойства могут быть использованы для определения блокирующего условия, которое оценивается во время фазы выполнения Chef Infra Client:

not_if

Предотвратить выполнение ресурса, когда условие возвращает true.

only_if

Разрешить выполнение ресурса только если условие возвращает true.

Примеры

В следующих примерах демонстрируются различные подходы к использованию ресурса openssl_x509_certificate в рецептах:

Создание простого самозаверяющего файла сертификата

openssl_x509_certificate '/etc/httpd/ssl/mycert.pem' do
  common_name 'www.f00bar.com'
  org 'Foo Bar'
  org_unit 'Lab'
  country 'US'
end

Создание сертификата с дополнительными параметрами

openssl_x509_certificate '/etc/ssl_files/my_signed_cert.crt' do
  common_name 'www.f00bar.com'
  ca_key_file '/etc/ssl_files/my_ca.key'
  ca_cert_file '/etc/ssl_files/my_ca.crt'
  expire 365
  extensions(
    'keyUsage' => {
      'values' => %w(
        keyEncipherment
        digitalSignature),
      'critical' => true,
    },
    'extendedKeyUsage' => {
      'values' => %w(serverAuth),
      'critical' => false,
    }
  )
  subject_alt_name ['IP:127.0.0.1', 'DNS:localhost.localdomain']
end