chef_search.md

+++ title = "About Search" draft = false gh_repo = "chef-web-docs" aliases = ["/chef_search.html", "essentials_search.html"] product = ["client", "server", "workstation"]

[menu] [menu.infra] title = "Search" identifier = "chef_infra/features/chef_search.md Search" parent = "chef_infra/features" weight = 70 +++

{{< readfile file="content/reusable/md/search.md" >}}

Many of the examples in this section use knife, but the search indexes and search query syntax can be used in many locations, including from within recipes and when using the Chef Infra Server API.

Search Indexes

A search index is a full-text list of objects that are stored on the Chef Infra Server, against which search queries can be made. The following search indexes are built:

Search Index Name	Description
client	API client
DATA_BAG_NAME	A data bag is a global variable that is stored as JSON data and is accessible from a Chef Infra Server. The name of the search index is the name of the data bag. For example, if the name of the data bag was "admins" then a corresponding search query might look something like search(:admins, "*:*").
environment	An environment is a way to map an organization's real-life workflow to what can be configured and managed when using Chef Infra Server.
node	A node is any server or virtual server that is configured to be maintained by a Chef Infra Client.
role	A role is a way to define certain patterns and processes that exist across nodes in an organization as belonging to a single job function.

Using Knife

{{< readfile file="content/workstation/reusable/md/knife_search_summary.md" >}}

Search by platform ID

{{< readfile file="content/workstation/reusable/md/knife_search_by_platform_ids.md" >}}

Search by instance type

{{< readfile file="content/workstation/reusable/md/knife_search_by_platform_instance_type.md" >}}

Search by recipe

{{< readfile file="content/workstation/reusable/md/knife_search_by_recipe.md" >}}

Search by cookbook, then recipe

{{< readfile file="content/workstation/reusable/md/knife_search_by_cookbook.md" >}}

Search by node

{{< readfile file="content/workstation/reusable/md/knife_search_by_node.md" >}}

Search by node and environment

{{< readfile file="content/workstation/reusable/md/knife_search_by_node_and_environment.md" >}}

Search for nested attributes

{{< readfile file="content/workstation/reusable/md/knife_search_by_nested_attribute.md" >}}

Search for multiple attributes

{{< readfile file="content/workstation/reusable/md/knife_search_by_query_for_many_attributes.md" >}}

Search for nested attributes using a search query

{{< readfile file="content/workstation/reusable/md/knife_search_by_query_for_nested_attribute.md" >}}

Use a test query

{{< readfile file="content/workstation/reusable/md/knife_search_test_query_for_ssh.md" >}}

Query Syntax

{{< readfile file="content/reusable/md/search_query_syntax.md" >}}

{{< note >}}

Search queries may not contain newlines.

{{< /note >}}

Filter Search Results

{{< readfile file="content/reusable/md/infra_lang_method_search_filter_result.md" >}}

Keys

{{< readfile file="content/reusable/md/search_key.md" >}}

Nested Fields

{{< readfile file="content/reusable/md/search_key_nested.md" >}}

Examples

{{< readfile file="content/reusable/md/search_key_name.md" >}}

{{< readfile file="content/reusable/md/search_key_wildcard_question_mark.md" >}}

{{< readfile file="content/reusable/md/search_key_wildcard_asterisk.md" >}}

{{< readfile file="content/reusable/md/search_key_nested_starting_with.md" >}}

{{< readfile file="content/reusable/md/search_key_nested_range.md" >}}

Patterns

{{< readfile file="content/reusable/md/search_pattern.md" >}}

Exact Matching

{{< readfile file="content/reusable/md/search_pattern_exact.md" >}}

{{< readfile file="content/reusable/md/search_pattern_exact_key_and_item.md" >}}

{{< readfile file="content/reusable/md/search_pattern_exact_key_and_item_string.md" >}}

Wildcard Matching

{{< readfile file="content/reusable/md/search_pattern_wildcard.md" >}}

{{< readfile file="content/reusable/md/search_pattern_wildcard_any_node.md" >}}

{{< readfile file="content/reusable/md/search_pattern_wildcard_node_contains.md" >}}

Range Matching

{{< readfile file="content/reusable/md/search_pattern_range.md" >}}

{{< readfile file="content/reusable/md/search_pattern_range_in_between.md" >}}

{{< readfile file="content/reusable/md/search_pattern_range_exclusive.md" >}}

Fuzzy Matching

{{< readfile file="content/reusable/md/search_pattern_fuzzy.md" >}}

{{< readfile file="content/reusable/md/search_pattern_fuzzy_summary.md" >}}

Operators

{{< readfile file="content/reusable/md/search_boolean_operators.md" >}}

{{< readfile file="content/reusable/md/search_boolean_operators_andnot.md" >}}

AND

{{< readfile file="content/reusable/md/search_boolean_and.md" >}}

NOT

{{< readfile file="content/reusable/md/search_boolean_not.md" >}}

OR

{{< readfile file="content/reusable/md/search_boolean_or.md" >}}

Special Characters

{{< readfile file="content/reusable/md/search_special_characters.md" >}}

Targets

A search target is any object that has been indexed on the Chef Infra Server, including roles (and run-lists), nodes, environments, data bags, and any API client.

Roles in Run-lists

A search query can be made for roles that are at the top-level of a run-list and also for a role that is part of an expanded run-list.

{{< note >}}

The roles field is updated with each Chef Infra Client run; changes to a run-list will not affect roles until the next Chef Infra Client run on the node.

{{< /note >}}

Role Location	Description
Top-level	To find a node with a role in the top-level of its run-list, search within the role field (and escaping any special characters with the slash symbol) using the following syntax: role:ROLE_NAME where role (singular!) indicates the top-level run-list.
Expanded	To find a node with a role in an expanded run-list, search within the roles field (and escaping any special characters with the slash symbol) using the following syntax: roles:ROLE_NAME where roles (plural!) indicates the expanded run-list.

To search a top-level run-list for a role named load_balancer use the knife search subcommand from the command line or the search method in a recipe. For example:

knife search node role:load_balancer

and from within a recipe:

search(:node, 'role:load_balancer')

To search an expanded run-list for all nodes with the role load_balancer use the knife search subcommand from the command line or the search method in a recipe. For example:

knife search node roles:load_balancer

and from within a recipe:

search(:node, 'roles:load_balancer')

Nodes

A node can be searched from a recipe by using the following syntax:

search(:node, "key:attribute")

A wildcard can be used to replace characters within the search query.

Expanded lists of roles (all of the roles that apply to a node, including nested roles) and recipes to the role and recipe attributes on a node are saved on the Chef Infra Server. The expanded lists of roles allows for searching within nodes that run a given recipe, even if that recipe is included by a role.

{{< note >}}

The recipes field is with each Chef Infra Client run; changes to a run-list will not affect recipes until the next Chef Infra Client run on the node.

{{< /note >}}

Node Location	Description
In a specified recipe	To find a node with a specified recipe in the run-list, search within the run_list field (and escaping any special characters with the slash symbol) using the following syntax: search(:node, 'run_list:recipe\[foo\:\:bar\]') where recipe (singular!) indicates the top-level run-list. Variables can be interpolated into search strings using the Ruby alternate quoting syntax: search(:node, %Q{run_list:"recipe[#{the_recipe}]"} )
In an expanded run-list	To find a node with a recipe in an expanded run-list, search within the recipes field (and escaping any special characters with the slash symbol) using the following syntax: recipes:RECIPE_NAME where recipes (plural!) indicates to search within an expanded run-list.

If you just want to use each result of the search and do not care about the aggregate result you can provide a code block to the search method. Each result is then passed to the block:

# Print every node matching the search pattern
search(:node, "*:*").each do |matching_node|
  puts matching_node.to_s
end

API Clients

An API client is any machine that has permission to use the Chef Infra Server API to communicate with the Chef Infra Server. An API client is typically a node (that runs Chef Infra Client) or a workstation (that runs knife), but can also be any other machine configured to use the Chef Infra Server API.

Sometimes when a role is not fully defined (or implemented), it may be necessary for a machine to connect to a database, search engine, or some other service within an environment by using the settings located on another machine, such as a host name, IP address, or private IP address. The following example shows a simplified settings file:

username: "mysql"
password: "MoveAlong"
host:     "10.40.64.202"
port:     "3306"

where host is the private IP address of the database server. Use the following knife query to view information about the node:

knife search node "name:name_of_database_server" --long

To access these settings as part of a recipe that is run on the web server, use code similar to:

db_server = search(:node, "name:name_of_database_server")
private_ip = "#{db_server[0][:rackspace][:private_ip]}"
puts private_ip

where the "[0]" is the 0 (zero) index for the db_server identifier. A single document is returned because the node is being searched on its unique name. The identifier private_ip will now have the value of the private IP address of the database server (10.40.64.202) and can then be used in templates as a variable, among other possible uses.

Environments

{{< readfile file="content/reusable/md/environment.md" >}}

{{< readfile file="content/reusable/md/search_environment.md" >}}

Data Bags

{{< readfile file="content/reusable/md/data_bag.md" >}}

{{< readfile file="content/reusable/md/search_data_bag.md" >}}