Руководство по стилю профилей Chef InSpec

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

Это набор рекомендуемых правил Chef InSpec, которые следует использовать при написании проверок.

Файлы проверок

Размещайте файлы проверок в controls/ и заканчивайте их .rb

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

Избегайте:

• controls/ssh_config
• controls/ssh/config.rb

Используйте:

• controls/ssh_config.rb
• controls/ssh_config.rb

Избегайте controls/control в именах файлов проверок

Использование controls в имени файла создаёт ненужный беспорядок при чтении. Сохраняйте имена короткими и лаконичными.

Избегайте:

• controls/ssh_controls.rb

Используйте:

• controls/ssh.rb

Стиль кода

Избегайте ненужных скобок в матчерах

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

Избегайте:

• it { should eq(value) }

Используйте:

• it { should eq value }

Исключение составляют матчеры, требующие дополнительных аргументов или именованных аргументов.

Проверки

Избегайте обертывания проверок условными операторами

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

Избегайте:

if package('..').installed?
  control "package-test1" do
    ..
  end
end

Используйте:

control "package-test1" do
  only_if { package('..').installed? }
end

Избегайте:

case inspec.platform.name
when /centos/
  include_controls 'centos-profile'
...

Вместо этого используйте атрибут supports в inspec.yml профиля, который вы хотите включить:

supports:
  - platform-name: centos

Теперь, когда вы запускаете базовый профиль, вы можете просто include_controls 'centos-profile'. Он будет запускать только включенные профили, если платформа соответствует поддерживаемой платформе.

Избегайте динамических элементов в идентификаторах проверок

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

Избегайте:

control "test-file-#{name}" do
  ..
end

Используйте:

control "test-all-files" do
  ..
end

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

Избегайте вызовов Ruby system

Код Ruby выполняется на системе, на которой работает InSpec. Это позволяет Chef InSpec работать без Ruby и RubyGems, необходимых на удалённых целевых системах (серверах или контейнерах). Вызовы system часто используются для взаимодействия с локальной ОС или удалёнными конечными точками из локальной установки.

Однако тесты Chef InSpec предназначены для универсального исполнения на всех типах сред выполнения, включая локальное и удалённое выполнение. Мы хотим предоставить пользователям возможность взять профиль ОС и выполнить его удалённо или локально.

Избегайте использования оболочек

Избегайте:

• `ls`
• system("ls")
• IO.popen("ls")

Используйте:

• command("ls") или powershell("Get-ChildItem")

Исполнители команд Ruby будут работать только локально. Представьте себе такой тест:

describe `whoami` do
  it { should cmp "bob\n" }
end

Если вы запустите этот тест на своей локальной системе и используете учётную запись Боба, он будет успешным. Но если вы запустите его на --target alice@remote-host.com, он по-прежнему будет сообщать, что пользователь — боб, а не элис.

Вместо этого сделайте так:

describe command('whoami') do
  its('stdout') { should cmp "bob\n" }
end

Если профиль указывает на удалённый конечный пункт, ресурс command запустит его на удалённой ОС.

Избегайте использования Ruby IO для файлов

Аналогично взаимодействиям с командами, эти файлы будут читаться только локально с помощью внутренних вызовов Ruby. Если вы запустите этот тест на удалённой цели, он не будет читать файл с удалённой точки, а с локальной ОС. Используйте ресурс file для чтения файлов на целевой системе.

Избегайте:

• File.new("filename").read
• File.read("filename")
• IO.read("filename")

Используйте:

• file("filename")

В целом, старайтесь избегать вызовов Ruby IO внутри проверок Chef InSpec и вместо этого используйте ресурсы Chef InSpec.

Избегайте зависимостей от пакетов Ruby gem в проверках

Помимо избегания системных gem и модулей, следует также ограничить использование внешних зависимостей пакетами ресурсов или плагинами. Gem необходимо разрешить, установить, внедрить и защитить от конфликтов. Мы стремимся избежать этой сложности для пользователей InSpec, чтобы сделать его отличным инструментом, даже если вы не являетесь разработчиком.

Плагины должны объявлять зависимости gem в своём gemspec и затем полагаться на механизм установки плагина для установки и управления зависимостями.

Избегайте отладочных вызовов (в рабочей среде)

Один из лучших способов разработки и исследования тестов — интерактивная отладочная оболочка pry (см. [Интерактивная отладка с помощью Pry] (/inspec/dsl_inspec/#interactive-debugging-with-pry) в конце этой страницы). Однако после завершения профиля убедитесь, что больше нет включенных интерактивных операторов. Иногда интерактивные вызовы скрываются за условными операторами (if операторы), которые сложнее достичь. Эти вызовы могут легко вызвать проблемы, когда автоматизированный профиль сталкивается с интерактивным pry вызовом, который останавливает выполнение и ожидает ввода пользователя.

Избегайте:

• binding.pry в производственных профилях

Используйте:

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

Также вам может быть полезно использовать интерфейс регистрации Chef InSpec:

Inspec::Log.info('Hi')

9. Предпочитайте cmp вместо eq

Матчер cmp обрабатывает преобразования типов, сравнения без учёта регистра, преобразование строк в версии (например, '7.35.0-1ubuntu2.10') и многие другие проблемные моменты. Если вам не нужен точный результат (в этом случае используйте матчер eq), то следует использовать матчер cmp.

Например, это:

describe passwd.uids(0) do
  its('users') { should cmp 'root' }
end

предпочтительнее:

describe passwd.uids(0) do
  its('users') { should eq ['root'] }
end

См. cmp документацию по матчеру для получения дополнительных примеров.