Ресурс openssl_x509_certificate

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

Страница справочника по ресурсам

Используйте ресурс 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
  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
  action                   Symbol # defaults to :create if not specified
end

где:

• openssl_x509_certificate — это ресурс.
• name — это имя, присвоенное блоку ресурса.
• action определяет, какие действия выполнит Chef Infra Client, чтобы привести узел в желаемое состояние.
• 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 Client.

Свойства

Ресурс 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 Client (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 InfraClient.

Уведомления

notifies

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

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

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

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

: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