391 lines
13 KiB
Markdown
391 lines
13 KiB
Markdown
---
|
||
title_tag: "Pulumi Insights: Resource search"
|
||
meta_desc: Documentation and query syntax for the Pulumi Insights search feature.
|
||
title: Resource search
|
||
h1: Resource search
|
||
meta_image: /images/docs/meta-images/docs-meta.png
|
||
menu:
|
||
pulumicloud:
|
||
parent: insights
|
||
weight: 1
|
||
aliases:
|
||
- /docs/intro/insights/search/
|
||
---
|
||
|
||
Resource Search allows you to explore your resources, stacks and projects in detail.
|
||
|
||
## Query Syntax
|
||
|
||
Resource Search supports a rich query language, described below.
|
||
|
||
### Simple Queries
|
||
|
||
The default search behavior is to return resources that match all terms in your query based on their name, URN, stack, or project.
|
||
|
||
For example, a query like
|
||
|
||
> bucket
|
||
|
||
will return resources having [types][types] like `aws:s3/bucket:Bucket` or `aws:s3/bucketobject:BucketObject`. It will also return resources in stacks named "bucket" or projects named "my-cool-bucket".
|
||
|
||
Similarly, a query for
|
||
|
||
> production
|
||
|
||
will return resources to belonging to stacks named "production".
|
||
It will also include any resources with "production" anywhere in its name.
|
||
|
||
A resource will only be returned if it matches all terms in the query.
|
||
If you search for
|
||
|
||
> foo bar
|
||
|
||
a resource named "foo" in the "bar" stack will be returned, but a resource only named "bar" will not be returned.
|
||
|
||
### Field Queries
|
||
|
||
The default search behavior is helpful for preliminary exploration but is often too broad for finer analysis.
|
||
To more precisely control _how_ your queries match resources, you can explicitly limit part or all of your query to match specific fields.
|
||
|
||
For example, searching `name:production` will only return resources that include "production" in their [logical name](/docs/concepts/resources/names/#logicalname).
|
||
|
||
In general, any column visible in the UI can be queried as a field by taking the lowercase column name and adding a `:` followed by a query term.
|
||
The colon cannot be followed by whitespace.
|
||
|
||
The complete list of available fields is below.
|
||
|
||
#### created
|
||
|
||
The UTC time when the resource was created.
|
||
|
||
Resources created _or modified_ with CLI versions below 3.60 _do not_ have `created` set.
|
||
|
||
Examples:
|
||
|
||
- _created:2023-03-31_
|
||
- _created:2023-03-31T01:02:03.456_
|
||
- _created:[2023-01-01 to 2023-03-31]_
|
||
- _created:>=2023-01-01_
|
||
|
||
#### custom
|
||
|
||
Whether the resource is a CustomResource.
|
||
|
||
Examples: _custom:true_ | _custom:false_
|
||
|
||
#### delete
|
||
|
||
Whether the resource is marked for deletion in the next update.
|
||
|
||
Typically indicates a resource that was not cleaned up due to an error.
|
||
|
||
Examples: _delete:true_ | _delete:false_
|
||
|
||
#### dependency
|
||
|
||
The [URN][urn] of another resource this resource explicitly or implicitly [depends on](/docs/concepts/resources#dependson).
|
||
|
||
A resource can have multiple dependencies. When querying, `dependency:foo` returns resources with any dependency with a URN matching `foo`.
|
||
|
||
Examples:
|
||
|
||
- _dependency:access-logs_
|
||
- _dependency:urn:my-org:my-stack::my-app::aws:s3/bucket:Bucket::access-logs_
|
||
|
||
#### id
|
||
|
||
The [physical name](/docs/concepts/resources/names/#autonaming) of the resource, as assigned by the resource’s provider. May not be set if the resource is pending creation.
|
||
|
||
Example: _id:my-bucket-d7c2fa0_
|
||
|
||
#### modified
|
||
|
||
The UTC time when the resource's state was last modified during an update, refresh or import.
|
||
|
||
Stacks modified with CLI versions below 3.60 record this for all resources as the time of the stack operation, regardless of whether the resource was modified.
|
||
After CLI version 3.60 the resource's modified time is only updated when the resource's state is modified.
|
||
|
||
Examples:
|
||
|
||
- _modified:2023-03-31_
|
||
- _modified:2023-03-31T01:02:03.456_
|
||
- _modified:[2023-01-01 to 2023-03-31]_
|
||
- _modified:>=2023-01-01_
|
||
|
||
#### name
|
||
|
||
The [logical name](/docs/concepts/resources/names/#logicalname) of the resource.
|
||
|
||
Typically the first parameter provided to the resource when it was instantiated.
|
||
|
||
Example: _name:my-bucket_
|
||
|
||
#### package
|
||
|
||
The package component of the resource's [type][types].
|
||
|
||
This is `aws` for a resource of type `aws:s3/bucket:Bucket`.
|
||
|
||
Examples:
|
||
|
||
- _package:aws_
|
||
- _package:aws-native_
|
||
- _package:gcp_
|
||
- _package:pulumi_
|
||
- _package:random_
|
||
|
||
#### parent.urn
|
||
|
||
The [URN][urn] of the resource’s parent, if it has one.
|
||
|
||
Examples:
|
||
|
||
- _parent.urn:app-production_
|
||
- _parent.urn:urn:myorg:mystack::app::pulumi:pulumi:Stack::app-production_
|
||
|
||
#### pending
|
||
|
||
The state of the resource if it is pending.
|
||
|
||
Typically indicates an operation that was interrupted due to an error, possibly needing manual intervention to resolve.
|
||
|
||
Allowed values: `creating`, `deleting`, `updating`, `reading`, `importing`.
|
||
|
||
Examples:
|
||
|
||
- _pending:creating_
|
||
- _pending:deleting_
|
||
- _pending:updating_
|
||
- _pending:reading_
|
||
- _pending:importing_
|
||
|
||
#### project
|
||
|
||
The project the resource belongs to.
|
||
|
||
Example: _project:my-cool-repo_
|
||
|
||
#### protected
|
||
|
||
Whether the resource is [protected](/docs/concepts/options/protect) from deletion.
|
||
|
||
Examples: _protected:true_ | _protected:false_
|
||
|
||
#### provider.urn
|
||
|
||
The [URN][urn] of the resource's [provider](/docs/concepts/resources/providers/).
|
||
|
||
Examples:
|
||
|
||
- _provider.urn:aws::default_5_21_1_
|
||
- _provider.urn:urn:myorg:mystack::myproject::pulumi:providers:aws::default_5_21_1::86588ad9_
|
||
|
||
#### stack
|
||
|
||
The stack the resource belongs to.
|
||
|
||
Example: _stack:my-cool-stack_
|
||
|
||
#### type
|
||
|
||
The [type][types] of the resource.
|
||
|
||
Examples:
|
||
|
||
- _type:LogGroup_
|
||
- _type:aws:cloudwatch:LogGroup_
|
||
- _type:aws:cloudwatch/logGroup:LogGroup_
|
||
|
||
#### urn
|
||
|
||
The [URN][urn] of the resource.
|
||
|
||
Examples:
|
||
|
||
- _urn:my-log-group_
|
||
- _urn:my-org:my-stack::my-project::aws:cloudwatch/logGroup:LogGroup::my-log-group_
|
||
|
||
### Exact Matching
|
||
|
||
Surrounding terms with `"double quotes"` produces an exact match query.
|
||
|
||
Only resources matching the phrase in quotes _exactly_ (including punctuation and whitespace) will be returned.
|
||
|
||
An exact match can optionally have a field associated with it.
|
||
For example, `stack:"my-cool-stack"`.
|
||
|
||
### Negation
|
||
|
||
Terms can be excluded from results by prefixing them with a `-`.
|
||
|
||
For example, `-foo` will exclude all resources that would normally match a query for `foo`.
|
||
|
||
Negation can be applied to exact matches and fields. All of `-name:foo`, `name:-foo`, `-name:"foo"`, `name:-"foo"`, and `-"foo bar"` are all valid and equivalent.
|
||
|
||
Fields can be repeated for multiple exclusions: `-name:foo -name:bar` excludes all resources with names matching `foo` and `bar`.
|
||
|
||
### Logical Combinations
|
||
|
||
All terms are implicitly combined with a logical `AND`, but terms can also be combined with `OR`.
|
||
For example, `foo OR bar` returns resources that would normally match `foo` as well as resources that would normally match `bar`.
|
||
|
||
Precedence is simple left-to-write, so `foo bar OR baz` is interpreted as `(foo AND bar) OR baz`. Parentheses are strongly recommended when combining terms with OR to prevent unexpected results. In this case, you can query for `foo (bar OR baz)` if your intent is to match `bar` or `baz`.
|
||
|
||
Parentheses and `OR` can be combined with negation, exact matches, and field queries like so:
|
||
|
||
> "S3-bucket" -(stack:prod OR stack:dev) -project:sandbox
|
||
|
||
### Range Queries
|
||
|
||
The `created` and `modified` fields can be queried for a range of values with `>`, `>=`, `<`, `<=`, and `[a to b]`.
|
||
The `[a to b]` form is inclusive on both sides.
|
||
|
||
For example, resources modified within the first quarter of 2023 (requires CLI 3.XX):
|
||
|
||
> modified:[2023-01-01 to 2023-03-31]
|
||
|
||
Ranges can also be one-sided. For example, to query everything modified after January 1, 2023:
|
||
|
||
> modified:>=2023-01-01
|
||
|
||
### Property Queries
|
||
|
||
{{% notes "info" %}}
|
||
Property search is only available to organizations using the Enterprise and Business Critical editions.
|
||
|
||
If you would like to use it, [contact us](/contact?form=sales) to upgrade.
|
||
{{% /notes %}}
|
||
|
||
Property search allows you to query resources by their inputs and outputs.
|
||
|
||
A property query is similar to a field query but it is triggered by a leading `.` followed by a _property path_:
|
||
|
||
> .\<property path>:<value?>
|
||
|
||
For example:
|
||
|
||
> .instanceType:t3.large
|
||
|
||
The specific syntax for property names matches the syntax used elsewhere in Pulumi, for example with [`ignoreChanges`](/docs/concepts/options/ignorechanges/). This makes it possible to refer to property values nested inside arrays or objects, or values with special characters.
|
||
|
||
For example, to query for a key containing spaces inside of an output object named `tags` we can write:
|
||
|
||
> .tags["name containing spaces"]:value
|
||
|
||
To query properties nested within arrays, the index can be omitted from the property path or `[*]` can be used. Resources are returned if any element in the array matches. Querying a specific array index (like `[0]`) is not supported.
|
||
|
||
An output of `{"foo": [{"bar": "baz"]}` can be queried with:
|
||
|
||
> .foo[*].bar:baz
|
||
|
||
Or, equivalently:
|
||
|
||
> .foo.bar:baz
|
||
|
||
Matching behavior is similar to field queries. Matching is non-exact by default, and surrounding a term with double quotes triggers exact matching.
|
||
|
||
For example:
|
||
|
||
- A query for `.instanceType:t3` will return resources with any `instanceType` containing "t3".
|
||
|
||
- A query for `.instanceType:"t3.large"` will return resources with an `instanceType` matching "t3.large" exactly.
|
||
|
||
In some cases a resource might have outputs that differ from its inputs, or inputs that are not also outputs. Precedence is given to outputs first when querying.
|
||
|
||
### Existence Queries
|
||
|
||
Omitting a value from a field name results in an existence query that returns all resources with a value set for that field.
|
||
|
||
For example, to find all resources with a team defined, regardless of what that team is, you can write:
|
||
|
||
> team:
|
||
|
||
Existence queries can be combined with negation to achieve non-existence queries. These can also be combined with properties.
|
||
|
||
For example, you would normally write something like `.tags.stack:production` to find resources with an output like `{"tags": {"stack": "production"}}`, but we can also find resources with _any_ tags:
|
||
|
||
> .tags:
|
||
|
||
If we want to refine this to resources with _some_ tags but no `"stack"` tag specifically, we can can write a query like so:
|
||
|
||
> .tags: -.tags.stack:
|
||
|
||
Existence queries do not return resources where the property is an empty object (`{}`), array (`[]`), or `null`. A resource with an output of `{"tags": {}}` would not be captured by an existence query for `.tags:`.
|
||
|
||
## Advanced Filtering
|
||
|
||
Expanding the "Advanced filtering" menu shows your results broken down by type, package, stack, and project.
|
||
The values shown in each column and the top values for that particular dimension, along with a count of how many resources share that value.
|
||
|
||
|
||
|
||
In the example above, the query has been restricted to the "my-stack" stack.
|
||
|
||
The counts next to each value show that this stack has 18 subnets, and 366 AWS resources in total.
|
||
|
||
Clicking "Clear filters" will remove all previously selected filters.
|
||
|
||
## Download a CSV
|
||
|
||
{{% notes "info" %}}
|
||
The CSV Export feature is only available to organizations using the Enterprise and Business Critical editions.
|
||
|
||
If you don't see it in your organization, [contact us](/contact?form=sales).
|
||
{{% /notes %}}
|
||
|
||
You can download a CSV with all resources matching your query by clicking the "Download CSV" button.
|
||
|
||
For a complete description of the CSV format returned, see the [Data Export](/docs/pulumi-cloud/insights/export/) documentation.
|
||
|
||
## API Access
|
||
|
||
Resources can also be queried programmatically. See the [Pulumi Cloud REST API](/docs/pulumi-cloud/cloud-rest-api#resource-search) for full details of the API endpoint to query resources.
|
||
|
||
## AI Assist
|
||
|
||
{{% notes "info" %}}
|
||
AI Assist is an experimental feature that lets you use natural-language prompts to generate queries for use with Resource Search.
|
||
|
||
If you don't see it in your organization, [contact us](/contact?form=sales).
|
||
{{% /notes %}}
|
||
|
||
Organizations with AI Assist enabled will see an "AI Assist" button to the right of their search bar.
|
||
|
||
After clicking "AI Assist" you can input a natural language query, for example:
|
||
|
||
> How many VPCs do I have?
|
||
|
||
You will then be re-directed to the "Syntax" tab with a pre-populated search query that attempts to answer your question. The search bar will remain empty if it's not able to generate a valid query for your question.
|
||
|
||
You may need to refine the pre-populated query slightly to capture your intent. For example, if you ask, "How many buckets do I have?" it might give you a query like
|
||
|
||
> type:"aws:s3/bucket:Bucket"
|
||
|
||
This isn't accurate if you're using Google Cloud, however. In that case you could modify the query to be
|
||
|
||
> type:"gcp:storage:Bucket"
|
||
|
||
or, if you're not sure which type is appropriate, you can use AI Assist again to clarify:
|
||
|
||
> How many gcp buckets do I have?
|
||
|
||
You may want to expand the "Advanced filtering" menu if you are interested in specific resource counts.
|
||
|
||
You do not need to query AI Assist with English:
|
||
|
||
|
||
|
||
> (type:aws:ec2/instance:Instance OR type:azure:compute:VirtualMachine OR type:gcp:compute:Instance)
|
||
|
||
## Access Controls
|
||
|
||
Resource Search is available to all members of an organization, but as a user you are only able to see and query resources that you have [permission](/docs/pulumi-cloud/projects-and-stacks/#stack-permissions) to access.
|
||
More specifically:
|
||
|
||
- Organization admins have access to all resources.
|
||
- If an organization has a default permission of read or write, then all users can query all resources.
|
||
- If an organization has no default permission, then users can only query resources they have access to via [Stack](/docs/pulumi-cloud/projects-and-stacks/#stack-permissions) or [Team](/docs/pulumi-cloud/access-management/teams/#team-permissions) permissions.
|
||
|
||
[types]: /docs/concepts/resources/names/#types
|
||
[urn]: /docs/concepts/resources/names/#urns
|