Словарь пользовательских ресурсов

[править на GitHub]

Словарь пользовательских ресурсов клиента Chef Infra

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

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

action_class

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

Пример

У вас есть шаблон, которому необходимы 'yes' или 'no', записанные как String, но вы хотели бы, чтобы пользователь использовал true или false для удобства. Чтобы предоставить доступ к этому методу как действиям :add, так и действиям :remove, поместите этот метод в блок action_class.

property :example, [true, false], default: true

action :add do
  template "file.conf" do
    source 'file.conf.erb'
    variables(
      chocolate: bool_to_string(new_resource.example)
    )
    action :create
  end
end

action :remove do
  template "file.conf" do
    source 'file.conf.erb'
    variables(
      chocolate: bool_to_string(new_resource.example)
    )
    action :delete
  end
end

action_class do
  def bool_to_string(b)
    b ? 'yes' : 'false'
  end
end

converge_if_changed

Используйте метод converge_if_changed внутри блока action в пользовательском ресурсе, чтобы сравнить желаемые значения свойств с текущими значениями свойств (загруженными методом load_current_value). Используйте метод converge_if_changed для обеспечения того, что обновления происходят только тогда, когда значения свойств на системе не соответствуют желаемым значениям свойств, и чтобы в противном случае предотвратить слияние ресурса.

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

action :some_action do
  converge_if_changed do
    # some property
  end
end

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

property :path, String
property :content, String
property :mode, String

# Load the current value for content and mode
load_current_value do |new_resource|
  if ::File.exist?(new_resource.path)
    content IO.read(new_resource.path)
    mode ::File.stat(new_resource.path).mode
  end
end

action :create do
  # If the value of content has changed
  # write file
  converge_if_changed :content do
    IO.write(new_resource.path, new_resource.content)
  end

  # If the value of mode has changed then
  # chmod file
  converge_if_changed :mode do
    ::File.chmod(new_resource.mode, new_resource.path)
  end
end

Клиент Chef Infra Client обновит только те значения свойств, которые требуют обновления, и не внесет изменения, если значения свойств уже соответствуют желаемому состоянию.

default_action

По умолчанию действие по умолчанию в пользовательском ресурсе — это первое перечисленное действие в пользовательском ресурсе. Например, действие aaaaa является ресурсом по умолчанию:

property :property_name, RubyType, default: 'value'

...

action :aaaaa do
 # the first action listed in the custom resource
end

action :bbbbb do
 # the second action listed in the custom resource
end

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

property :property_name, RubyType, default: 'value'

# Define bbbbb aas the default action
default_action :bbbbb

action :aaaaa do
 # the first action listed in the custom resource
end

action :bbbbb do
 # the second action listed in the custom resource
end

load_current_value

Используйте метод load_current_value для загрузки указанных значений свойств с узла и затем используйте эти значения при слиянии ресурса. Этот метод может принимать аргумент блока.

property :path, String
property :content, String
property :mode, String

load_current_value do |new_resource|
  if ::File.exist?(new_resource.path)
    content IO.read(new_resource.path)
    mode ::File.stat(new_resource.path).mode
  end
end

Используйте метод load_current_value для защиты от замены значений свойств. Например:

property :homepage, String
property :page_not_found, String

load_current_value do
  if ::File.exist?('/var/www/html/index.html')
    homepage IO.read('/var/www/html/index.html')
  end

  if ::File.exist?('/var/www/html/404.html')
    page_not_found IO.read('/var/www/html/404.html')
  end
end

Это гарантирует, что значения для homepage и page_not_found не изменятся на значения по умолчанию при конфигурации узла клиентом Chef Infra Client.

current_value_does_not_exist!

При использовании блока load_current_value используйте current_value_does_not_exist! для обозначения того, что значение не существует, и что current_resource следует поэтому nil.

load_current_value do |new_resource|
    port_data = powershell_exec(%Q{Get-WmiObject -Class Win32_TCPIPPrinterPort -Filter "Name='#{new_resource.port_name}'"}).result

    if port_data.empty?
      current_value_does_not_exist!
    else
      ipv4_address port_data["HostAddress"]
    end
  endo
end

new_resource.property

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

Например:

property :command, String, name_property: true
property :version, String

# Useful properties from the `execute` resource
property :cwd, String
property :environment, Hash, default: {}
property :user, [String, Integer]
property :sensitive, [true, false], default: false

prefix = '/opt/languages/node'

load_current_value do
  current_value_does_not_exist! if node.run_state['nodejs'].nil?
  version node.run_state['nodejs'][:version]
end

action :run do
  execute 'execute-node' do
    cwd cwd
    environment environment
    user user
    sensitive sensitive
    # gsub replaces 10+ spaces at the beginning of the line with nothing
    command <<-CODE.gsub(/^ {10}/, '')
      #{prefix}/#{new_resource.version}/#{command}
    CODE
  end
end

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

• property :cwd
• property :environment
• property :user
• property :sensitive

Поскольку как пользовательские свойства, так и свойства execute идентичны, это приведет к сообщению об ошибке, подобному:

ArgumentError
-------------
wrong number of arguments (0 for 1)

Чтобы предотвратить это поведение, используйте new_resource. для указания клиенту Chef Infra Client обрабатывать свойства из основного ресурса вместо свойств в пользовательском ресурсе. Например:

property :command, String, name_property: true
property :version, String

# Useful properties from the `execute` resource
property :cwd, String
property :environment, Hash, default: {}
property :user, [String, Integer]
property :sensitive, [true, false], default: false

prefix = '/opt/languages/node'

load_current_value do
  current_value_does_not_exist! if node.run_state['nodejs'].nil?
  version node.run_state['nodejs'][:version]
end

action :run do
  execute 'execute-node' do
    cwd new_resource.cwd
    environment new_resource.environment
    user new_resource.user
    sensitive new_resource.sensitive
    # gsub replaces 10+ spaces at the beginning of the line with nothing
    command <<-CODE.gsub(/^ {10}/, '')
      #{prefix}/#{new_resource.version}/#{new_resource.command}
    CODE
  end
end

где:

• cwd new_resource.cwd
• environment new_resource.environment
• user new_resource.user
• sensitive new_resource.sensitive

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

property

Используйте метод property для определения свойств пользовательского ресурса. Синтаксис:

property :property_name, ruby_type, default: 'value', parameter: 'value'

где

• :property_name — имя свойства
• ruby_type — необязательный тип Ruby или массив типов, например String, Integer, true, или false
• default: 'value' — необязательное значение по умолчанию, загружаемое в ресурс
• parameter: 'value' — необязательные параметры

Например, следующие свойства определяют свойства username и password без указанных значений по умолчанию:

property :username, String
property :password, String

ruby_type

Свойство ruby_type является позиционным параметром.

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

• true
• false
• nil
• String
• Array
• Hash
• Integer
• Symbol

Использование массива классов Ruby позволяет значению быть более чем одного типа. Например:

property :aaaa, String
property :bbbb, Integer
property :cccc, Hash
property :dddd, [true, false]
property :eeee, [String, nil]
property :ffff, [Class, String, Symbol]
property :gggg, [Array, Hash]

sensitive

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

validators

{{ dsl/property_validation_parameter }}

desired_state

Добавьте desired_state: для установки свойства желаемого состояния для ресурса.

• При true, состояние свойства определяется состоянием системы
• При false, значение свойства влияет на выполнение ресурса, но не определяется состоянием системы.

Например, если вы хотите написать ресурс для создания томов на поставщике облачных услуг, вам необходимо определить свойства, такие как volume_name, volume_size, и volume_region. Состояние этих свойств определит, требуется ли вашему ресурсу слияние или нет. Для работы ресурса вам также необходимо определить свойства, такие как cloud_login и cloud_password. Это необходимые свойства для взаимодействия с поставщиком облачных услуг, но их состояние не влияет на решение о слиянии ресурса, поэтому вы установите desired_state в false для этих свойств.

property :volume_name, String
property :volume_size, Integer
property :volume_region, String
property :cloud_login, String, desired_state: false
property :cloud_password, String, desired_state: false

run_context

Chef загружает и отслеживает текущее выполнение в объекте контекста выполнения.

root_context

property_is_set?

Используйте метод property_is_set? для проверки, было ли значение для свойства передано в ресурс.

Синтаксис:

property_is_set?(:property_name)

Метод property_is_set? вернет true, если свойство установлено.

Например, следующий пользовательский ресурс создаёт и/или обновляет свойства пользователя, но не его пароль. Метод property_is_set? проверяет, указал ли пользователь пароль, и затем сообщает Chef Infra Client, что делать, если пароль не идентичен:

action :create do
  converge_if_changed do
    shell_out!("rabbitmqctl create_or_update_user #{username} --prop1 #{prop1} ... ")
  end

  if property_is_set?(:password)
    if shell_out("rabbitmqctl authenticate_user #{username}#{password}").error?
      converge_by "Updating password for user #{username} ..." do
        shell_out!("rabbitmqctl update_user #{username} --password #{password}")
      end
    end
  end
end

provides

Представлено

Используйте метод provides для связывания нескольких файлов пользовательских ресурсов с одним именем ресурса. Например:

# Provide my_custom_resource to Redhat 7 and above
provides :my_custom_resource, platform: 'redhat' do |node|
  node['platform_version'].to_i >= 7
end

# Provide my_custom_resource to all Redhat platforms
provides :my_custom_resource, platform: 'redhat'

# Provide my_custom_resource to the RedHat platform family
provides :my_custom_resource, platform_family: 'rhel'

# Provide my_custom_resource to all linux machines
provides :my_custom_resource, os: 'linux'

# Provide my_custom_resource, useful if your resource file is not named the same as the resource you want to provide
provides :my_custom_resource

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

Прецедент

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

1. provides :my_custom_resource, platform_version: ‘0.1.2’
2. provides :my_custom_resource, platform: ‘platform_name’
3. provides :my_custom_resource, platform_family: ‘platform_family’
4. provides :my_custom_resource, os: ‘operating_system’
5. provides :my_custom_resource

reset_property

Используйте метод reset_property для сброса значения свойства так, как будто оно никогда не было установлено, и затем используйте значение по умолчанию. Например, для сброса значения свойства с именем password:

reset_property(:password)

coerce

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

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

Здесь мы преобразуем true/false в yes, no для шаблона позже.

property :browseable,
        [true, false, String],
        default: true,
        coerce: proc { |p| p ? 'yes' : 'no' },

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

имя_ресурса

Представлено: 12.5 Обновлено: 16.0

Используйте метод resource_name вверху пользовательского ресурса, чтобы объявить пользовательское имя для этого ресурса. Например:

resource_name :my_resource_name

resource_name используется только в качестве имени по умолчанию для отображения.

Предпочтительный способ указания имени ресурса — оператор provides.

В Chef Infra Client 16 и более поздних версиях первый provides в объявлении ресурса также задаёт значение по умолчанию resource_name, поэтому мы не рекомендуем пользователям устанавливать resource_name.

Устаревание целых ресурсов

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

Устарейте ресурс foo_bar в кулинарной книге

deprecated 'The foo_bar resource has been deprecated and will be removed in the next major release of this cookbook scheduled for 25/01/2021!'

property :thing, String, name_property: true

action :create do
 # Chef resource code
end

Устаревание свойства

Устарейте свойство badly_named в ресурсе:

property :badly_named, String, deprecated: 'The badly_named property has been deprecated and will be removed in the next major release of this cookbook scheduled for 12/25/2021!'

Устаревание и алиасирование

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

deprecated_property_alias 'badly_named', 'really_well_named', 'The badly_named property was renamed really_well_named in the 2.0 release of this cookbook. Please update your cookbooks to use the new property name.'

unified_mode