поиск с помощью knife

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

Индексы поиска позволяют выполнять запросы к любому типу данных, индексированному сервером Chef Infra Server, включая пакеты данных (и элементы пакетов данных), среды, узлы и роли. Определенный синтаксис запроса используется для поддержки шаблонов поиска, таких как точное совпадение, подстрока, диапазон и нечёткое соответствие. Поиск — это полнотекстовый запрос, который можно выполнить из нескольких мест, в том числе изнутри рецепта, с помощью подкоманды search в knife, метода search в языке Chef Infra, поля поиска в консоли управления Chef и с помощью конечных точек /search или /search/INDEX в API сервера Chef Infra Server. Двигатель поиска основан на Elasticsearch и работает на сервере Chef Infra Server.

Используйте подкоманду knife search для выполнения запроса поиска информации, которая индексирована на сервере Chef Infra Server.

Синтаксис

У этой подкоманды следующий синтаксис:

knife search INDEX SEARCH_QUERY

где INDEX — это client, environment, node, role, или имя пакета данных, а SEARCH_QUERY — это синтаксис запроса поиска для запроса, который будет выполнен.

INDEX подразумевается, если не указано, и будет по умолчанию node. Например:

knife search '*:*' -i

вернёт что-то подобное:

8 items found

centos-62-dev
opensuse-15
ubuntu-1804-orgtest
ubuntu-1804-ohai-test
ubuntu-1804-ifcfg-test
ohai-test
win2k19-dev

и это тот же поиск, что и:

knife search node '*:*' -i

Если SEARCH_QUERY не содержит двоеточия (:), то шаблон запроса по умолчанию — tags:*#{@query}* OR roles:*#{@query}* OR fqdn:*#{@query}* OR addresses:*#{@query}*, что означает, что следующие два запроса поиска фактически эквивалентны:

knife search ubuntu

или:

knife search node "tags:*ubuntu* OR roles:*ubuntu* OR fqdn:*ubuntu* (etc.)"

Синтаксис запроса

Запрос поиска состоит из двух частей: ключа и шаблона поиска. Запрос поиска имеет следующий синтаксис:

key:search_pattern

где key — имя поля, которое находится в JSON-описании индексируемого объекта на сервере Chef Infra Server (роль, узел, клиент, среда или пакет данных), а search_pattern определяет, что будет искаться, используя один из следующих шаблонов поиска: точное совпадение, подстрока, диапазон или нечёткое соответствие. И key, и search_pattern регистрозависимы; key имеет ограниченную поддержку поиска подстрок с использованием звёздочки («*») (и при условии, что это не первый символ).

Ключи

Пара имя/описание поля доступна в JSON-объекте. Используйте имя поля при поиске этой информации в JSON-объекте. Можно искать любое поле, которое существует в любом JSON-описании любой роли, узла, клиента Chef Infra, среды или пакета данных.

Чтобы найти доступные поля для конкретного объекта, используйте аргумент show с любой из следующих подкоманд knife: knife client, knife data bag, knife environment, knife node, или knife role. Например: knife data bag show.

Вложенные поля

Вложенное поле появляется глубже в структуре данных JSON. Например, информация о сетевом интерфейсе может быть на нескольких уровнях вложенности: node['network']['interfaces']['en1']. Когда вложенные поля присутствуют в JSON-структуре, Chef Infra Client извлечёт эти вложенные поля на верхний уровень, сглаживая их в составные поля, которые поддерживают шаблоны поиска с подстрокой.

Комбинируя подстроки с шаблонами поиска диапазонов и запросами с подстроками, можно выполнять очень мощные поиски, такие как поиск поставщика части MAC-адреса, чтобы найти все узлы, у которых сетевая карта произведена указанным поставщиком.

Рассмотрим следующий фрагмент данных JSON:

{"network":
  [
  //snipped...
    "interfaces",
      {"en1": {
        "number": "1",
        "flags": [
          "UP",
          "BROADCAST",
          "SMART",
          "RUNNING",
          "SIMPLEX",
          "MULTICAST"
        ],
        "addresses": {
          "fe80::fa1e:dfff:fed8:63a2": {
            "scope": "Link",
            "prefixlen": "64",
            "family": "inet6"
          },
          "f8:1e:df:d8:63:a2": {
            "family": "lladdr"
          },
          "192.0.2.0": {
            "netmask": "255.255.255.0",
            "broadcast": "192.168.0.255",
            "family": "inet"
          }
        },
        "mtu": "1500",
        "media": {
          "supported": {
            "autoselect": {
              "options": [

              ]
            }
          },
          "selected": {
            "autoselect": {
              "options": [

              ]
            }
          }
        },
        "type": "en",
        "status": "active",
        "encapsulation": "Ethernet"
      },
  //snipped...

Перед индексированием этих данных на сервере Chef Infra Server, вложенные поля извлекаются на верхний уровень, аналогично:

"broadcast" => "192.168.0.255",
"flags"     => ["UP", "BROADCAST", "SMART", "RUNNING", "SIMPLEX", "MULTICAST"]
"mtu"       => "1500"

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

node "broadcast:192.168.0.*"

или:

node "mtu:1500"

или:

node "flags:UP"

Эти данные также сглаживаются в различные составные поля, которые следуют той же структуре, что и JSON-иерархия, и используют нижние подчёркивания (_) для разделения уровней данных, подобно:

# ...snip...
"network_interfaces_en1_addresses_192.0.2.0_broadcast" => "192.168.0.255",
"network_interfaces_en1_addresses_fe80::fa1e:tldr_family"  => "inet6",
"network_interfaces_en1_addresses"                         => ["fe80::fa1e:tldr","f8:1e:df:tldr","192.0.2.0"]
# ...snip...

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

node "network_interfaces_en1_addresses:192.0.2.0"

Эта сглаженная структура данных также поддерживает использование составных полей с подстроками, которые позволяют пропускать уровни в структуре данных JSON, которые не важны для запроса поиска. В следующем примере звёздочка (*) используется для обозначения места, где может находиться подстрока при поиске вложенного поля:

"network_interfaces_*_flags"     => ["UP", "BROADCAST", "SMART", "RUNNING", "SIMPLEX", "MULTICAST"]
"network_interfaces_*_addresses" => ["fe80::fa1e:dfff:fed8:63a2", "192.0.2.0", "f8:1e:df:d8:63:a2"]
"network_interfaces_en0_media_*" => ["autoselect", "none", "1000baseT", "10baseT/UTP", "100baseTX"]
"network_interfaces_en1_*"       => ["1", "UP", "BROADCAST", "SMART", "RUNNING", "SIMPLEX", "MULTICAST",
                                     "fe80::fa1e:dfff:fed8:63a2", "f8:1e:df:d8:63:a2", "192.0.2.0",
                                     "1500", "supported", "selected", "en", "active", "Ethernet"]

Для каждого из примеров с подстрокой выше, возможные значения показаны в скобках. При выполнении запроса поиска, синтаксис запроса для подстрок заключается в простом пропуске имени узла (при сохранении подчёркиваний), подобно:

network_interfaces__flags

Этот запрос будет искать в узле flags, в структуре JSON, каждое из UP, BROADCAST, SMART, RUNNING, SIMPLEX, и MULTICAST.

Примеры

Чтобы увидеть доступные ключи для узла, введите следующее (для узла с именем staging):

knife node show staging -Fj | less

чтобы получить полное JSON-описание узла и просмотреть доступные ключи, на основе которых можно формировать любые запросы поиска.

Чтобы использовать вопросительный знак (?) для замены одного символа в поиске с подстрокой, введите следующее:

knife search node 'platfor?:ubuntu'

Чтобы использовать звёздочку (*) для замены нуля (или более) символов в поиске с подстрокой, введите следующее:

knife search node 'platfo*:ubuntu'

Чтобы найти все IP-адреса, находящиеся в одной сети, введите следующее:

knife search node 'ipaddress:192.168*'

где 192.168* — это сетевой адрес, для которого будет выполнен поиск.

Чтобы использовать поиск по диапазону для поиска IP-адресов в подсети, введите следующее:

knife search node 'ipaddress:[192.168.0.* TO 192.0.2.*]'

где 192.168.0.* TO 192.0.2.* определяет диапазон подсети.

О шаблонах

Шаблон поиска — это способ уточнения результатов поиска, возвращая все, что соответствует некоторому типу неполного запроса поиска. Существует четыре типа шаблонов поиска, которые можно использовать при поиске в индексах поиска на сервере Chef Infra Server: точное совпадение, подстрока, диапазон и нечёткое соответствие.

Точное соответствие

Шаблон поиска точного соответствия используется для поиска ключа с именем, которое точно соответствует запросу поиска. Если имя ключа содержит пробелы, в шаблоне поиска должны использоваться кавычки, чтобы убедиться, что запрос поиска находит ключ. Весь запрос также должен быть заключён в кавычки, чтобы предотвратить его интерпретацию оболочкой Ruby или командной строки. Лучший способ обеспечить последовательное использование кавычек — использовать одинарные кавычки (' ') для всего запроса и двойные кавычки (" ") для шаблона поиска.

Чтобы выполнить поиск в определённом пакете данных для определённого элемента пакета данных, введите следующее:

knife search admins 'id:charlie'

где admins — имя пакета данных, а charlie — имя элемента пакета данных. Что-то подобное следующему будет возвращено:

1 items found
_rev:       1-39ff4099f2510f477b4c26bef81f75b9
chef_type:  data_bag_item
comment:    Charlie the Unicorn
data_bag:   admins
gid:        ops
id:         charlie
shell:      /bin/zsh
uid:        1005

Чтобы выполнить поиск в определённом пакете данных, используя строку для поиска любого соответствующего элемента пакета данных, введите следующее:

knife search admins 'comment:"Charlie the Unicorn"'

где admins — имя пакета данных, а Charlie the Unicorn — строка, которая будет использоваться во время поиска. Что-то подобное следующему будет возвращено:

1 items found
_rev:       1-39ff4099f2510f477b4c26bef81f75b9
chef_type:  data_bag_item
comment:    Charlie the Unicorn
data_bag:   admins
gid:        ops
id:         charlie
shell:      /bin/zsh
uid:        1005

Поиск с подстрокой

Шаблон поиска с подстрокой используется для запроса совпадений подстрок, которые заменяют ноль (или более) символов в шаблоне поиска на всё, что может соответствовать заменённому символу. Существует два типа поиска с подстрокой:

Вопросительный знак (?) может быть использован для замены ровно одного символа (при условии, что этот символ не является первым в шаблоне поиска)
Звёздочка (*) может быть использована для замены любого количества символов (включая ноль)

Чтобы выполнить поиск любого узла, содержащего указанный ключ, введите следующее:

knife search node 'foo:*'

где foo — имя узла.

Чтобы выполнить поиск узла с частичным именем, введите одно из следующих:

knife search node 'name:app*'

или:

knife search node 'name:app1*.example.com'

или:

knife search node 'name:app?.example.com'

или:

knife search node 'name:app1.example.???'

чтобы вернуть app1.example.com (и любой другой узел, который соответствует любому из вышеперечисленных строковых поисков).

Поиск по диапазону

Шаблон поиска по диапазону используется для запроса значений, которые находятся в диапазоне, определённом верхними и нижними границами. Поиск по диапазону может быть включительно или исключительно относительно границ. Используйте квадратные скобки («[ ]») для обозначения включительных границ и фигурные скобки («{ }») для обозначения исключительных границ с использованием следующего синтаксиса:

boundary TO boundary

где TO требуется (и должно быть заглавным).

Пакет данных с именем sample содержит четыре элемента пакета данных: abc, bar, baz, и quz. Все элементы между bar и foo, включительно, могут быть найдены с помощью шаблона включительно поиска.

Чтобы выполнить поиск с использованием включительно диапазона, введите следующее:

knife search sample "id:[bar TO foo]"

где используются квадратные скобки ([ ]).

Пакет данных с именем sample содержит четыре элемента пакета данных: abc, bar, baz, и quz. Все элементы, которые исключительны для bar и foo, могут быть найдены с помощью шаблона исключительно поиска.

Чтобы выполнить поиск с использованием исключительно диапазона, введите следующее:

knife search sample "id:{bar TO foo}"

где фигурные скобки ({ }) используются для определения диапазона.

Нечёткий поиск

Шаблон поиска с нечёткой подгонкой используется для поиска на основе близости двух строк символов. В качестве части запроса поиска можно использовать (необязательное) целое число, чтобы более точно определить близость. Шаблон поиска с нечёткой подгонкой имеет следующий синтаксис:

"search_query"~edit_distance

где search_query — строка, которая будет использоваться при поиске, а edit_distance — близость. Тильда ("~") используется для разделения расстояния редактирования от запроса поиска.

Для использования шаблона поиска с нечёткой подгонкой введите что-то подобное:

knife search client "name:boo~"

где boo~ определяет шаблон поиска с нечёткой подгонкой. Это вернёт что-то подобное:

{
  "total": 1,
  "start": 0,
  "rows": [
    {
      "public_key": "too long didn't read",
      "name": "foo",
      "_rev": "1-f11a58043906e33d39a686e9b58cd92f",
      "json_class": "Chef::ApiClient",
      "admin": false,
      "chef_type": "client"
    }
  ]
}

Об операторах

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

Оператор	Описание
`AND`	Используется для поиска совпадения, когда оба термина существуют.
`OR`	Используется для поиска совпадения, если существует любой из терминов.
`NOT`	Используется для исключения термина после `NOT` из результатов поиска.

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

Предупреждение

Использование AND NOT вместе может вызвать ошибку. Например:

ERROR: knife search failed: invalid search query:
'datacenter%3A123%20AND%20NOT%20hostname%3Adev-%20AND%20NOT%20hostanem%3Asyslog-'
Parse error at offset: 38 Reason: Expected one of \ at line 1, column 42 (byte 42) after AND

Используйте - вместо NOT. Например:

knife search sample "id:foo AND -id:bar"

И

Для объединения запросов с помощью булевого оператора AND введите следующее:

knife search sample "id:b* AND animal:dog"

что вернёт что-то вроде:

{
  "total": 1,
  "start": 0,
  "rows": [
    {
      "comment": "an item named baz",
      "id": "baz",
      "animal": "dog"
    }
  ]
}

Или, чтобы найти все компьютеры, работающие под платформой Microsoft Windows, которые связаны с ролью с именем jenkins, введите:

knife search node 'platform:windows AND roles:jenkins'

что вернёт что-то вроде:

2 items found

Node Name:   windows-server-2012r2.domain.com
Environment: _default
FQDN:        windows-server-2012r2
IP:          0000::0000:0000:0000:0000
Run List:    role[jenkins-windows]
Roles:       jenkins-windows, jenkins
Recipes:     jenkins-client::windows, jenkins::node_windows
Platform:    windows 6.3.9600
Tags:

Node Name:   123-windows-2012r2-amd64-builder
Environment: _default
FQDN:        ABC-1234567890AB
IP:          123.45.6.78
Run List:    role[123-windows-2012r2-amd64-builder]
Roles:       123-windows-2012r2-amd64-builder, jenkins
Recipes:     jenkins::node_windows, git_windows
Platform:    windows 6.3.9600
Tags:

НЕ

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

knife search sample "(NOT id:foo)"

что вернёт что-то вроде:

{
  "total": 4,
  "start": 0,
  "rows": [
    {
      "comment": "an item named bar",
      "id": "bar",
      "animal": "cat"
    },
    {
      "comment": "an item named baz",
      "id": "baz"
      "animal": "dog"
    },
    {
      "comment": "an item named abc",
      "id": "abc",
      "animal": "unicorn"
    },
    {
      "comment": "an item named qux",
      "id": "qux",
      "animal", "penguin"
    }
  ]
}

ИЛИ

Для объединения запросов с помощью булевого оператора OR введите следующее:

knife search sample "id:foo OR id:abc"

что вернёт что-то вроде:

{
  "total": 2,
  "start": 0,
  "rows": [
    {
      "comment": "an item named foo",
      "id": "foo",
      "animal": "pony"
    },
    {
      "comment": "an item named abc",
      "id": "abc",
      "animal": "unicorn"
    }
  ]
}

Специальные символы

Специальный символ может быть использован для уточнения запроса поиска и повышения точности результатов поиска. Следующие символы могут быть включены в синтаксис запроса поиска, но каждое вхождение специального символа должно быть экранировано обратной косой чертой (\), также (/) должно быть экранировано против Elasticsearch:

+  -  &&  | |  !  ( )  { }  [ ]  ^  "  ~  *  ?  :  \  /

Например:

\(1\+1\)\:2

Параметры

Примечание

Ознакомьтесь со списком общих параметров, доступных для этой (и всех) подкоманд и плагинов knife.

У этой подкоманды есть следующие параметры:

-a ATTR, --attribute ATTR: Атрибут (или атрибуты) для отображения.
-b ROW, --start ROW: Строка, с которой начинаются возвращаемые результаты.
-f FILTER, --filter-result FILTER: Используется для фильтрации выходных данных поиска на основе шаблона, который соответствует указанному FILTER. Будут возвращены только атрибуты в FILTER. Например: \"ServerName=name, Kernel=kernel.version\.
-i, --id-only: Показать только соответствующие идентификаторы объектов.
INDEX: Имя индекса для запроса: client, environment, node, role, или DATA_BAG_NAME. По умолчанию индекс: node.
-l, --long: Отобразить все атрибуты в выводе и показать вывод в формате JSON.
-m, --medium: Отобразить обычные атрибуты в выводе и показать вывод в формате JSON.
-q SEARCH_QUERY, --query SEARCH_QUERY: Защитить запросы поиска, начинающиеся с дефиса (-). Запрос -q может быть указан в качестве аргумента или параметра, но не оба одновременно.
-r, --run-list: Показать только список запуска.
-R INT, --rows INT: Количество строк, которые должны быть возвращены.
SEARCH_QUERY: Запрос поиска, используемый для определения списка элементов на сервере Chef Infra. Этот параметр использует тот же синтаксис, что и подкоманда search.

Примеры

В следующих примерах показано, как использовать эту подкоманду knife:

Поиск по идентификатору платформы

Чтобы найти идентификаторы всех узлов, работающих под платформой Amazon EC2, введите:

knife search node 'ec2:*' -i

что вернёт что-то вроде:

4 items found

ip-0A7CA19F.ec2.internal

ip-0A58CF8E.ec2.internal

ip-0A58E134.ec2.internal

ip-0A7CFFD5.ec2.internal

Поиск по типу экземпляра

Чтобы найти тип экземпляра (размер) всех узлов, работающих под платформой Amazon EC2, введите:

knife search node 'ec2:*' -a ec2.instance_type

что вернёт что-то вроде:

4 items found

ec2.instance_type:  m1.large
id:                 ip-0A7CA19F.ec2.internal

ec2.instance_type:  m1.large
id:                 ip-0A58CF8E.ec2.internal

ec2.instance_type:  m1.large
id:                 ip-0A58E134.ec2.internal

ec2.instance_type:  m1.large
id:                 ip-0A7CFFD5.ec2.internal

Поиск по рецепту

Чтобы найти рецепты, которые используются узлом, используйте атрибут recipes для поиска имён рецептов, введите что-то вроде:

knife search node 'recipes:recipe_name'

или:

knife search node '*:*' -a recipes | grep 'recipe_name'

Поиск по кулинарной книге, затем по рецепту

Чтобы найти кулинарные книги на узле, используйте атрибут recipes после шаблона cookbook::recipe, экранируя оба символа :. Например:

knife search node 'recipes:cookbook_name\:\:recipe_name'

Поиск по узлу

Чтобы найти все узлы, работающие под Ubuntu, введите:

knife search node 'platform:ubuntu'

Поиск по узлу и среде

Чтобы найти все узлы, работающие под CentOS в среде production, введите:

knife search node 'chef_environment:production AND platform:centos'

Поиск по вложенным атрибутам

Чтобы найти вложенный атрибут, используйте шаблон, похожий на следующий:

knife search node <query_to_run> -a <main_attribute>.<nested_attribute>

Поиск по нескольким атрибутам

Чтобы создать запрос поиска для использования более чем одного атрибута, используйте подчёркивание (_) для разделения каждого атрибута. Например, следующий запрос найдёт все узлы, работающие с определённой версией Ruby:

knife search node "languages_ruby_version:2.7.0"

Поиск по вложенным атрибутам с использованием запроса поиска

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

knife search node name: <node_name> -a kernel.machine

Использование тестового запроса

Чтобы проверить запрос поиска, который будет использован в подкоманде knife ssh:

knife search node "role:web NOT name:web03"

где запрос в предыдущем примере будет искать все сервера, которые имеют роль web, но не на сервере с именем web03.

© Chef Software, Inc.
Licensed under the Creative Commons Attribution 3.0 Unported License.
The Chef™ Mark and Chef Logo are either registered trademarks/service marks or trademarks/servicemarks of Chef, in the United States and other countries and are used with Chef Inc's permission.
We are not affiliated with, endorsed or sponsored by Chef Inc.
https://docs.chef.io/workstation/knife_search/