Входы Chef InSpec

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

Что такое входы?

Входы — это «ручки», которые вы можете использовать для настройки поведения профилей Chef InSpec. Если профиль поддерживает входы, вы можете установить входы различными способами, что обеспечивает гибкость. Профили, включающие другие профили, могут устанавливать входы в включенном профиле, что позволяет использовать многоуровневый подход к настройке профилей.

Простой пример

Предположим, у вас есть профиль с именем rock_critic. В его файле метаданных (inspec.yml):

# Optionally declare inputs in the profile metadata# This lets you set up things like type checking, etc.inputs:- name:amplifier_max_volumedescription:How loud the amplifiers can gotype:numeric# More options, including value: and priority: are possible here

В коде управления профилем:

# Set a default value for an input.  This is optional.
input('amplifier_max_volume', value: 10)

control 'Big Rock Show' do
  describe input('amplifier_max_volume') do    # This line reads the value of the input
    it { should cmp 11 } # The UK'S LOUDEST BAND
  end
end

Когда вышеуказанный профиль выполняется с использованием inspec exec rock_critic, вы увидите что-то вроде:

  ×  Big Rock Show: 10
     ×  10 is expected to cmp == 11

     expected: 11
          got: 10

     (compared using `cmp` matcher)
Profile Summary: 0 successful controls, 1 control failure, 0 controls skipped

Этот результат явно не подойдет. Давайте переопределим значение входа по умолчанию.

Теперь мы можем запустить этот профиль с помощью inspec exec rock_critic --input amplifier_max_volume=11.

  ✔  Big Rock Show: 11
     ✔  11 is expected to cmp == 11

Profile Summary: 1 successful control, 0 control failures, 0 controls skipped

Какие профили поддерживают входы?

Лучший способ для профиля указать, что он поддерживает входы, — перечислить их в файле метаданных, inspec.yml. Любой профиль, который имеет раздел inputs (или устаревший раздел attributes) в своем файле метаданных inspec.yml настраивает входы.

Однако любой профиль, использующий ключевое слово DSL input() (или устаревшее ключевое слово attribute()) в коде управления, поддерживает входы. Эти профили считывают (и, возможно, устанавливают) значения входов и используют их для принятия решений.

Как установить входы?

В установленной версии (без специализированных плагинов) Chef InSpec поддерживает несколько способов установки входов:

• В строку кода управления, используя input('input_name', value: 42).
• В файлы метаданных профилей inspec.yml.
• Используя параметр командной строки --input name1=value1 name2=value2..., чтобы считывать напрямую из командной строки.
• Используя параметр командной строки --input-file somefile.yaml, чтобы считывать входы из файлов.
• В kitchen-inspec, используя настройки verifier/inputs.

Кроме того, Chef InSpec поддерживает плагины входов, которые могут предоставить дополнительные интеграции со специфическими хранилищами пар «ключ-значение».

Как работает приоритет входов?

Простой приоритет

Вкратце:

встроенный DSL < метаданные < (cli-input-file или kitchen-inspec) < cli –input

Кроме того, для унаследованных профилей:

метаданные зависимого профиля < метаданные профиля-оболочки

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

Подробности о приоритете входов

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

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

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

inputs:- name:very_important_inputvalue:12priority:50

Чтобы задать приоритет в DSL, используйте:

input('also_important', value: 42, priority: 45)

В поставке Chef InSpec используются следующие значения приоритета:

Что случилось с «Атрибутами»?

При первоначальном представлении механизм входов назывался Атрибутами. Это название было проблематичным, потому что:

• Инструмент Chef Infra использует то же самое слово для описания своей системы параметризации.
• Атрибуты Chef Infra имеют совершенно другую и гораздо более сложную систему приоритетов.
• Это вызывало путаницу относительно передачи атрибутов Chef Infra в InSpec при использовании кулинарной книги аудита и kitchen-inspec.

В связи с этими проблемами атрибуты InSpec были переименованы во входы InSpec в Chef InSpec v4.

Поддержка использования ключевого слова DSL attribute(), поля метаданных attributes:, и соответствующих значений kitchen-inspec и кулинарной книги аудита ожидается продолжить в Chef InSpec v5.

Работа с входами в коде управления

Область действия входов

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

# some_controls.rb

input('outer_input', value: 1) # here

control 'control-1' do
  input('control_dsl_input', value: 2) # here too
  describe some_resource do
    input('test_dsl_input', value: 3) # even here
    it { should cmp input('expectation_dsl_input') } # and yes here too
  end
end

Установка входов в DSL управления

Когда вы пишете input('some_name', value: 'some_value'), вы устанавливаете значение входа в DSL. Поскольку опция value: присутствует, будет установлено новое значение. Вы также можете передать любые другие опции, указанные в справочнике по опциям входов.

Чтение входов в DSL управления

Когда вы вызываете input('some_name'), с дополнительными или без дополнительных опций, значение входа будет разрешено и возвращено. Обратите внимание, что этот процесс может включать извлечение значения из другого поставщика, использование значения, заданного в DSL, или переопределение значения, заданного в том же вызове.

# You can use the value in a Ruby variable
some_var = input('some_input_name')

# Or more directly in a resource parameter
describe file(input('important_path')) do
  it { should exist }
end

# Or as the resource itself (this could be a string, here)
describe input('some_setting') do
  it { should cmp 'correct_value' }
end

# Or as the expected value
describe file('/etc/httpd/httpd.conf') do
  its('owner') { should_not cmp input('webserver_user') }
end

Возвращенное значение можно использовать везде, где используется значение Ruby.

Настройка входов в метаданных профиля

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

name:my_profileinputs:- name:webserver_user # Name is the only required field- name:favorite_fruitvalue:banana        # You can set a value; priority is 30 for metadata- name:meaning_of_lifetype:Numericvalue:42required:truepriority:70sensitive:true

Все опции входов поддерживаются в файлах метаданных.

Существует две основные преимущества определения входов в метаданных профиля:

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

Использование входов с наследованием профилей

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

# child inspec.ymlname:childinputs:- name:favorite_foodvalue:pizza

# wrapper inspec.ymlname:wrapperdepends:- name:childpath:../childinputs:- name:favorite_foodvalue:broccoliprofile:child      # <----- REQUIRED to override the value in InSpec 4

В Chef InSpec 4+ каждый вход имеет пространство имен. Например, у вас может быть вход с именем wrapper/favorite_food и один с именем child/favorite_food. Если в файле метаданных профиля wrapper нет явной опции профиля, то wrapper считается профилем.

Установка значений входов с помощью --input-file

Вы также можете предоставить входы и значения через файлы YAML в командной строке. Формат показан ниже:

an_input:a_valueanother_input:another_value

Входы CLI-input-file-set имеют приоритет 40.

По состоянию на Chef InSpec 4.3.2 у этого механизма есть следующие ограничения:

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

Установка значений входов с помощью --input

Вы также можете предоставить входы и значения напрямую в командной строке:

inspec exec my_profile --input input_name=input_value

Чтобы установить несколько входов, скажем:

inspec exec my_profile --input input_name1=input_value1 name2=value2

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

inspec exec my_profile --input amplifier_volume=-11inspec exec my_profile --input water_depth=11.5

Вы можете устанавливать входы со сложными значениями, такими как массивы и хэши, используя синтаксис YAML или JSON. Просто убедитесь, что вы защищаете строку от оболочки, используя одинарные кавычки.

inspec exec my_profile --input alphabet='[a,b,c]'inspec exec my_profile --input fruits='{a: apples, b: bananas, c: cantelopes}'inspec exec my_profile --input json_fruit='{"a": "apples", "g": ["grape01", "grape02"] }'

Не повторяйте флаг --input; это переопределит предыдущую установку.

Входы CLI-set имеют приоритет 50.

По состоянию на Chef InSpec 4.12 у этого механизма есть следующие ограничения:

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

Установка значений входов с помощью плагинов

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

Отключение кэширования для входов

Особенно с плагинами может быть желательно переоценивать входы каждый раз и не кэшировать их. По умолчанию существующее значение входа повторно используется, что может привести к проблемам, если ожидается изменение извлекаемых значений. Пример этого — использование kitchen-inspec с плагинами входов для подключения к серверу Vault для получения паролей.

Чтобы отключить кэширование входов, вы можете отключить кэш из своего кода Ruby:

Inspec::InputRegistry.instance.cache_inputs = false

Справочник по опциям входов

Имя

Обязательная String. Эта опция идентифицирует вход.

Допустимо во всех случаях. При использовании в DSL и метаданных имя уникально в рамках текущего профиля. При использовании в файлах входов CLI и kitchen-inspec вход копируется во все профили с тем же именем.

Описание

Необязательная String. Человекопонятное объяснение входа.

Допустимо в DSL и метаданных.

Значение

Необязательно, любой тип Ruby или YAML. Это значение, которое будет доступно при чтении входных данных. Дополнительную информацию см. в разделе Чтение входных данных.

Разрешено в: Все

Тип

Необязательно, String. Это значение должно быть одним из String, Numeric, Regexp, Array, Hash, Boolean, или Any. Если указано, значение входных данных будет проверено на соответствие указанному типу. Обратите внимание, что Regexp означает, что значение входных данных должно быть регулярным выражением, а не что оно должно соответствовать какому-либо конкретному регулярному выражению.

Разрешено в: DSL, Метаданные

Обязательное

Необязательно, true или false. Если true, управление с использованием входных данных будет завершено неудачей, если при чтении значения не задано.

Разрешено в: DSL, Метаданные

Приоритет

Необязательно, Integer, от 0 до 100. Более высокие значения придают этому назначению более высокий приоритет. Это расширенная функция.

Разрешено в: DSL, Метаданные

Профиль

Необязательно, String. Позволяет задать входные данные в другом профиле из вашего профиля.

Разрешено в: DSL, Метаданные

Конфиденциальные данные

Необязательно, true или false. Если true, значение входных данных будет использоваться обычно во время exec выполнения, но значение будет скрыто как «***» в разделе «inputs» или «attributes» любого Отчетчика, который явно перечисляет входные данные (отчетчик json является одним из таких отчётчиков). Обратите внимание, что это не будет скрывать значения входных данных, используемые в качестве результатов тестов.

Разрешено в: Метаданные

Шаблон

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

Разрешено в: DSL, Метаданные

Дополнительные темы

Отладка входных данных с помощью журнала событий

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

Сначала используйте метод DSL input_object(). Этот метод похож на input(), так как он ищет входные данные, но вместо оценки текущего значения он возвращает базовую Inspec::Input объектную структуру.

puts input_object('troublesome_input').diagnostic_string

# Or
require 'pp'
pp input_object('troublesome_input').events

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

Журнал событий содержит записи для каждого случая изменения значения, а также одну запись при первом создании входных данных. Если возможно, используется зондирование стека для определения номеров файла и строки. Самое главное, вы увидите номера приоритетов; помните, что побеждает наивысший приоритет; порядок имеет значение только для разрыва ничьей.