Словарь Chef InSpec

[редактировать на GitHub]

Этот документ поможет вам ознакомиться с терминологией, используемой в проекте Chef InSpec.

Его можно использовать двумя способами:

• С текстовым словарем. Узнайте значение встретившегося слова.
• С визуальным словарем. Посмотрите примеры и посмотрите, как обозначены части. Затем вы можете использовать текстовый словарь для получения подробностей каждого понятия.

Визуальный словарь

Пример мотивации

Предположим, нас интересует аудит автомобилей. Допустим, у нас есть два ресурса Chef InSpec для аудита: cars, который ищет и фильтрует группы автомобилей, и car, который выполняет подробный аудит одного автомобиля.

Основной синтаксис

Давайте рассмотрим несколько простых примеров.

Пример ресурса единственного числа

describe car(owner: 'Tony Clifton') do
    it { should exist }
    its('license_plate') { should cmp 'MOONMAN' }
    it { should be_classy }
    it { should_not have_check_engine_light_on }
end

describe car(owner: ‘Tony Clifton’) do

car — это ресурс. Поскольку мы говорим только об одном автомобиле, это ресурс единственного числа.

describe car(owner: ‘Tony Clifton’)

owner — это параметр ресурса, а ‘Tony Clifton’ — это значение параметра ресурса.

it { should exist }

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

its('license_plate') { should cmp ‘MOONMAN’ }

license_plate — это свойство, принадлежащее ресурсу. Свойства предоставляют проверяемую информацию о ресурсе. Некоторые свойства являются числами, некоторые (например, это) являются текстом, некоторые являются списками, а некоторые являются более сложными объектами. Свойства всегда используются с универсальными соответствиями.

its(‘license_plate’) { should cmp ‘MOONMAN’ }

cmp — это универсальное соответствие. cmp — это очень гибкий, слабо типизированный оператор равенства; здесь он проверяет, совпадает ли текст номерного знака с текстом ‘MOONMAN’. Обратите внимание, что тест выполняется над текстом номерного знака (значением свойства), а не над ресурсом. Полный список поддерживаемых универсальных соответствий можно найти на странице Универсальное соответствие.

its(‘license_plate’) { should cmp ‘MOONMAN’ }

‘MOONMAN’ — это ожидаемый результат. Некоторые соответствия принимают ожидаемый результат; другие — нет.

it { should be_classy }

be_classy — это специфичное для ресурса соответствие. Он возвращает значение «да» или «нет», в зависимости от того, является ли автомобиль Тони элегантным или нет. (Да. Тони — элегантный человек.)

it { should_not have_check_engine_light_on }

should_not указывает, что это отрицательный тест. Таким образом, этот тест проходит, если соответствие говорит «нет».

Пример ресурса множественного числа

describe cars.where(color: /^b/) do
  it { should exist }
  its('manufacturers') { should include 'Cadillac' }
  its('count') { should be >= 10 }
end

describe cars.where(color: /^b/) do

cars — это ресурс. Поскольку мы потенциально говорим о многих автомобилях, это ресурс множественного числа.

describe cars.where(color: /^b/) do

where(color: /^b/) — это утверждение фильтра. Без утверждения фильтра cars просто выбирает все автомобили в мире.

describe cars.where(color: /^b/) do

color — это критерий фильтра вместе со значением фильтра, /^b/. Здесь критерий выражает, что мы хотим выбрать все автомобили, цвет которых начинается с буквы «б» — синий, коричневый, бордовый и т. д.

it { should exist }

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

Для ресурсов множественного числа exist имеет особое значение: совпало ли что-нибудь с фильтром?

its('manufacturers') { should include ‘Cadillac’ }

manufacturers — это свойство ресурса. Свойства предоставляют проверяемую информацию о ресурсе. Для ресурсов множественного числа свойства почти всегда являются именами во множественном числе и почти всегда возвращают список значений. Здесь тест возвращает список имен производителей автомобилей. Некоторые свойства списков дедублицируются; например, у вас может быть 10 автомобилей, но если все они Subaru и Cadillac, в свойстве manufacturers возвращаются только две записи. Обязательно проверяйте документацию для своего ресурса.

its(‘manufacturers’) { should include ‘Cadillac’ }

include — это универсальное соответствие. include работает со списками и проверяет, присутствует ли ожидаемый результат. Здесь он проверяет, содержит ли список производителей запись с текстом ‘Cadillac’. Обратите внимание, что он работает со списком производителей (значением свойства), а не с ресурсом. Полный список поддерживаемых универсальных соответствий можно найти на странице Универсальное соответствие.

its(‘manufacturers’) { should include ‘Cadillac’ }

‘Cadillac’ — это ожидаемый результат. Некоторые соответствия принимают ожидаемый результат; другие — нет.

its(‘count’) { should be >= 10 }

be >= — это соответствие оператора. Оно позволяет выполнять числовые сравнения. Все ресурсы множественного числа имеют свойство count.

Текстовый словарь

Атрибут

Устаревшее название для ввода.

Управление

Блок управления

Ключевое слово control используется для объявления control block. Здесь слово «управление» означает «регуляторный контроль, рекомендация или требование» — не конструкцию программной инженерии. У control block есть имя (которое обычно относится к назначенному идентификатору регуляторной рекомендации, которую он реализует), метаданные, такие как описания, ссылки и теги, и, наконец, он объединяет связанные блоки describe для реализации проверок.

Базовый ресурс

Ресурс, который входит в InSpec; вам не нужно устанавливать дополнительные плагины или полагаться на набор ресурсов для использования ресурса.

Пользовательский ресурс

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

Описать

Блок describe

Ключевое слово describe используется с describe block для ссылки на ресурс Chef InSpec. Вы используете ключевое слово describe вместе с именем ресурса, чтобы заключить в него связанные тесты, которые применяются к ресурсу. Несколько блоков describe обычно группируются в управлении, но вы также можете использовать их вне управления.

control 'Rule 1.1 - Color restrictions' do
  # Count only blue cars
  describe cars.where(color: 'blue') do
    its('count') { should eq 20 }
  end
end

DSL

DSL — это аббревиатура от Domain Specific Language. Она относится к расширениям языка, которые Chef InSpec предоставляет для упрощения создания ресурсов и контролей. Хотя файлы контролей Chef InSpec используют Ruby, Control DSL упрощает написание контролей без знания Ruby, предоставляя ключевые слова DSL, такие как describe, control, it и its. Подробные сведения о ключевых словах, доступных авторам контролей, см. на странице Страница языка Chef InSpec.

Для авторов пользовательских ресурсов доступен дополнительный DSL — см. страницу Язык ресурсов.

Ожидаемый результат

При использовании соответствия expected result — это значение, с которым соответствие будет сравнивать свойство, к которому осуществляется доступ.

В этом примере используется соответствие cmp для сравнения свойства color с ожидаемым результатом ‘черный’.

describe car(owner: 'Bruce Wayne') do
  its('color') { should cmp 'black' }
end

Утверждение фильтра

При использовании ресурса множественного числа используется filter statement для выбора отдельных объектов тестирования с использованием критериев фильтра. Утверждение фильтра почти всегда обозначается ключевым словом where, и может быть повторено с помощью цепочки методов.

Утверждение фильтра может использовать синтаксис вызова метода (который позволяет выполнять базовые операции с критериями, такие как равенство, сопоставление с регулярными выражениями и сравнение ruby ===) или синтаксис блока (который позволяет использовать произвольный код).

В этом примере where(...) — это утверждение фильтра.

# Count only blue cars
describe cars.where(color: 'blue') do
  its('count') { should eq 20 }
end

Критерий фильтра

Критерии фильтра

При использовании ресурса множественного числа используется filter criterion для выбора отдельных объектов тестирования в рамках утверждения фильтра. Вы можете использовать несколько filter criteria в одном утверждении фильтра.

Когда используется синтаксис вызова метода с оператором фильтра, вы предоставляете критерии фильтра в виде хэша, где имена критериев фильтра — это ключи, а условия — значения хэша. Вы можете указать значения для проверки, true/false или числа, в этом случае выполняется сравнение на равенство; или вы можете указать регулярное выражение, в этом случае выполняется проверка соответствия.

Здесь (color: blue) — один критерий фильтра, используемый с оператором фильтра в синтаксисе вызова метода.

# Count only blue cars
describe cars.where(color: 'blue') do
  its('count') { should eq 20 }
end

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

Здесь { engine_cylinders >= 6 } — оператор фильтра со синтаксисом блока, относящийся к одному критерию фильтра.

# Vroom!
describe cars.where { engine_cylinders >= 6 } do
  its('city_mpg_ratings') { should_not include '4-star' }
end

Входные данные

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

Входные данные ранее назывались attributes. Входные данные Chef InSpec не связаны с атрибутами Chef Infra.

Синтаксис командной строки для входных данных документирован в команде inspec exec.

Входные данные подробно документированы в документации по вводу данных.

Он

Внутри блока describe, it объявляет отдельный тест напрямую по отношению к ресурсу (в отличие от проверки по одному из свойств ресурса, как делает its). Хотя можно использовать универсальные матчеры с it, гораздо чаще используются специфичные для ресурса матчеры.

it может использоваться с should, или с отрицанием с помощью should_not.

Здесь it { should ... } объявляет тест, вызывая матчер classy? на автомобиле Тони Клифтона.

describe car(owner: 'Tony Clifton') do
  it { should be_classy }
end

Его

Внутри блока describe, its объявляет отдельный тест по отношению к свойству ресурса (в отличие от проверки напрямую по самому ресурсу, как делает it). Вы должны использовать универсальные матчеры с its; вы не можете использовать специфичные для ресурса матчеры.

its может использоваться с should, или с отрицанием с помощью should_not.

Доступное свойство передается как единственный строковый аргумент в its. В качестве расширенного использования, если свойство имеет интересующие вас методы, вы можете вызвать их, используя «.» в строке; возможны ещё более продвинутые схемы вызовов — см. документацию rspec-its.

Здесь its('fuzzy_dice') { should ... } объявляет тест, проверяя свойство fuzzy_dice автомобиля Тони Клифтона. Предположим, учитывая природу Тони, что fuzzy_dice вернёт массив.

describe car(owner: 'Tony Clifton') do
  its('fuzzy_dice') { should_not be_empty }
  its('fuzzy_dice.count') { should be >= 2 }
  its('fuzzy_dice.first.fuzziness') { should cmp 'outlandishly so' }
end

Матчер

matcher выполняет фактические проверки по отношению к ресурсам или свойствам ресурсов. Матчеры всегда возвращают значение true/false. Матчеры делятся на две категории:

• специфичные для ресурса матчеры, которые работают непосредственно с ресурсом, используются с it и, как правило, сильно адаптированы к потребностям аудита ресурса
• универсальные матчеры, которые работают со свойствами ресурса, используются с its и, как правило, очень универсальны, работая с текстом, числами и списками

Некоторые матчеры принимают параметры, называемые ожидаемыми результатами.

Для получения информации о том, как матчеры RSpec связаны с матерами Chef InSpec, см. Chef InSpec и RSpec.

Здесь be_classy — специфичный для ресурса матчер, работающий напрямую с car, а cmp — универсальный матчер, работающий со свойством manufacturer.

describe car(owner: 'Tony Clifton') do
  it { should be_classy }
  its('manufacturer') { should cmp 'Cadillac' }
end

Матчер оператора

Матчер оператора позволяет использовать операторы для сравнения числовых ожидаемых результатов со свойством. Все ресурсы во множественном числе имеют свойство count.

Например:

describe cars do
  its('count') { should be >= 10 }
end

Операторы включают:

• ==
• >=
• <=
• >
• <

ресурс во множественном числе

plural resource — это ресурс, который специализируется на выполнении поиска и представляет собой несколько вхождений ресурса на платформе целевой платформы. Ресурсы во множественном числе используются для аудита количества, проверки свойств групп и имеют уникальную возможность применять отрицательные тесты («ничего подобного не должно существовать»), часто требуемые нормами соответствия. Ресурсы во множественном числе не предназначены для глубокого аудита отдельного элемента; для этого используйте ресурсы в единственном числе.

Ресурсы во множественном числе почти всегда имеют имя, оканчивающееся на 's': processes, aws_security_groups, cars. Ресурсы во множественном числе обычно не имеют специфичных для ресурса матчеров. Если у них есть свойства, они почти всегда представляют собой свойства списка, что означает, что они возвращают список значений, которые могут быть или не быть дедублицированы.

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

Здесь cars — ресурс во множественном числе.

describe cars.where(color: 'blue') do
  its('count') { should eq 20 }
  its('license_plates') { should include 'AUTOAZUL' }

  # License plates are unique, should have 20
  its('license_plates.count') { should cmp 20 }

  # Manufacturers are de-duplicated
  its('manufacturers') { should include 'Subaru' }
  its('manufacturers.count') { should be < 10 }
end

Профиль

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

Профили могут быть распространены локально как древовидная структура каталогов, как tarball или zipfile по URL-адресу, как git-репозиторий и несколькими другими способами. Профили содержат метаданные, включая версионирование, и могут устанавливать зависимости с другими профилями.

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

Свойство

Факт о ресурсе. Обычно вы используете ключевое слово its для доступа к свойству и создаёте тест внутри блока describe, а затем используете универсальный матчер для утверждений о значении свойства.

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

Здесь manufacturer — это свойство ресурса car.

describe car(owner: 'Tony Clifton') do
  its('manufacturer') { should cmp 'Cadillac' }
end

Отчётчик

Формат вывода для команды inspec exec командной строки. Доступны несколько отчётчиков, включая JSON и JUnit; см. документацию inspec exec.

Ресурс

resource представляет категорию элементов на целевой платформе, которые вы хотите проверить. Например, для проверки существования и прав доступа к файлу используется ресурс file. Chef InSpec предлагает десятки различных ресурсов, от узкоспециализированных (например, aws_security_group, который проверяет правила брандмауэра в AWS) до очень общих (например, command, который выполняет команду и позволяет проверить её вывод).

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

Ресурсы используются в блоке describe для выполнения тестов.

Здесь car — это ресурс.

describe car(owner: 'Tony Clifton') do
  it { should be_classy }
end

Пакет ресурсов

Пакет ресурсов — это тип профиля, используемый для распространения пользовательских ресурсов. Этот специализированный тип профиля не содержит контролей, но содержит директорию libraries внутри которой Ruby-файлы определяют пользовательские ресурсы.

Параметр ресурса

resource parameters — это информация, передаваемая ресурсу при его объявлении. Обычно параметры ресурса предоставляют идентификационную информацию или информацию о подключении. Параметры ресурса не являются оператором фильтра.

Параметры ресурсов различаются в зависимости от ресурса; обратитесь к документации по ресурсам для получения подробностей.

Здесь owner: 'Tony Clifton' — это параметр ресурса.

describe car(owner: 'Tony Clifton') do
  it { should be_classy }
end

Матчер, специфичный для ресурса

Матчер, который работает непосредственно с ресурсом, в отличие от работы со свойством, как это делает универсальный матчер.

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

Например, гипотетический ресурс car определяет метод classy?, который доступен как матчер be_classy в тестах Chef InSpec.

describe car(owner: 'Tony Clifton') do
  it { should be_classy }
end

Ресурс в единственном числе

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

Целевой объект

target — это операционная система или API, на котором Chef InSpec выполняет проверки. В Chef InSpec 1.x это всегда был целевой объект операционной системы (голая машина, виртуальная машина или контейнер). В Chef InSpec 2.x и более поздних версиях это может быть целевой объект ОС или API, включая облачные поставщики, такие как AWS. Chef InSpec — это бездополнительный агент, что означает, что код и профили Chef InSpec остаются на вашем рабочем столе, а целевой объект удалённо проверяется без установки чего-либо.

Тест

test — это отдельное утверждение о состоянии ресурса или одного из его свойств. Все тесты начинаются с ключевого слова it или its. Тесты сгруппированы в блоке describe.

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

Универсальное соответствие — это соответствие, которое можно использовать для свойств любого типа ресурса. Например, вы можете использовать соответствие cmp для проверки значения свойств, не беспокоясь о преобразовании типов в Ruby. Универсальные соответствия почти всегда используются с ключевым словом its.

Универсальные соответствия документированы на странице Универсальные соответствия.

Здесь мы получаем свойство «цвет», а затем используем универсальное соответствие cmp для сравнения свойства с ожидаемым результатом «чёрный» ожидаемый результат.

describe car(owner: 'Bruce Wayne') do
  its('color') { should cmp 'black' }
end