Apps and Environments

Apps and environments are logical groups of resources with a meaning. They are meant to help you show resources the way your organization expects to see them.

An app is a group of resources that serve one product or service, such as payments-api. An environment is a flavor of the app’s deployment, such as prod, staging, or dev.

How It Works

Apps and environments are inferred by CloudQuery based on the sets of rules you can configure. One set to identify and name apps, another set to identify and name environments. The two sets are independent, so a resource can get an app, an environment, both, or neither.

For each set, CloudQuery Platform does this:

1. It reads the rules in order, from the top.
2. It finds the resources that each rule matches directly, by their tags or by their account name. If more than one rule matches a resource, the first of those rules names it. The later rules do not name it.
3. It gives the same name to the untagged resources that are connected to a matched resource. See Connected Resources.
4. It writes the result to the app_memberships and environment_memberships tables.

Apps and environments are linked through their resources. If a resource belongs to the app payments-api and to the environment prod, then payments-api runs in prod. One app can therefore have many environments.

When the Rules Run

The rules run:

• After each sync completes.
• When you save a change to the rules.

Rules are applied in the background.

Connected Resources

Many resources carry no tags. A disk, a network interface, or a security group is often untagged, but it belongs to the same app as the resource it is attached to.

Each rule has a Propagate to untagged neighbors (1-hop) option, which is on by default. With this option on, a matched resource also gives its app or environment name to the untagged resources that are directly connected to it, one step out. For example, if an EC2 instance carries the tag app=payments-api, the untagged disk attached to that instance also joins the app payments-api. A snapshot of that disk is two steps away, so it does not join the app.

Resources in More Than One App

The first rule wins for each resource that a rule matches directly. That decides which app name a matched resource gets. It does not limit the number of apps a resource can join.

A resource belongs to more than one app when it is untagged and it is connected to matched resources in different apps. A database that two apps share joins both of them.

The same is true of environments. Most resources get one environment, but a shared resource can get more than one.

Writing the Rules

1. In the sidebar, click your user icon and select Organization settings.
2. Open the App identification page.

The page has two sections:

Each section works the same way. Click Add rule and select a rule type. Drag the rule cards to change their order, because the first match wins. Click Save changes when you are done.

While the rules run, the page shows Applying rules across your resources…. The new names appear in the inventory when this message stops.

Rule Types

Tag Rule

Enter one or more tag keys, such as app, service, or env. A resource that carries one of these keys is named by the value of that tag. Tag keys are matched without regard to case.

The keys are also in priority order. If a resource carries two of the keys, the first key in the list is used.

Account Name Pattern

Enter a regular expression that CloudQuery Platform matches against the account name. The expression must contain a named capture group, and the captured text becomes the name.

For apps, the group is app:

(?<app>[^-]+)-.*

This matches the account prod-payments-api and gives the app prod. To skip the prefix and capture the rest, use:

[^-]+-(?<app>.+)

For environments, the group is environment:

(?<environment>prod|staging|dev).*

This matches the account prod-checkout and gives the environment prod.

env zero Environment and env zero Project

env zero environments and projects have a different meaning on env zero than on CloudQuery. Using this rule, you can specify app and environment inference from either env zero environments, or projects.

These rules need the env zero integration to be synced.

• env zero environment names the app or environment after the env zero environment that deployed the resource.
• env zero project names the app or environment after the env zero project that deployed the resource. Select Full path to use the whole project path, so a project C inside B inside A becomes the app A/B/C. Select Leaf to use only the last part, so the same project becomes the app C. Two projects with the same name under different parents then become one app.

Preview

A configured rule shows how many resources it matches, and a pattern rule also shows example matches. Use this to check a rule before you save it.

Using Apps and Environments in the Asset Inventory

Filter by App

Add an App filter in the filter bar to show only the resources of one or more apps. Select Unallocated to show the resources that belong to no app. Combine the App filter with any other filter.

Group by App

Select App in the Group by control. The inventory then shows one group for each app, with its resource count.

Resource Details

Click a resource to open the detail panel. The panel shows the app and the environment of that resource. A resource that belongs to more than one app or environment shows all of them. A resource with no app or environment shows neither field.

Asking the AI Assistant

The AI Assistant reads your apps and environments in the same way it reads your resource tables. You can therefore ask which resources run in production, or which resources belong to one app, in plain language.

Example prompts:

• Which resources are running in production?
• List the apps that have resources in staging.
• How many EC2 instances belong to payments-api?
• Which apps run in more than one environment?

The assistant answers from your rules. A resource that no rule names has no app and no environment, so the assistant does not count it. In Data Privacy mode the assistant returns the SQL for you to run. In Full Access mode it runs the query and answers directly.

Querying with SQL

Apps and environments are ClickHouse tables, so you can query them in the SQL Console and use them in reports.

Tables and Views

_cq_platform_id identifies one resource across all tables. Use it to join the membership tables to cloud_assets and to the per-resource tables.

The membership tables hold the app id, not the app name, so join to apps to get the name. Environments are names only, so environment_memberships needs no join.

List the Resources of Each App

SELECT a.name, m.resource_table, m._cq_platform_id
FROM app_memberships m
JOIN apps a ON a.id = m.app_id

Count the Resources in Each App

A resource can be reached by more than one rule, so count distinct resources:

SELECT a.name, countDistinct(m._cq_platform_id) AS resources
FROM app_memberships m
JOIN apps a ON a.id = m.app_id
GROUP BY a.name
ORDER BY resources DESC

Find the Environments of an App

SELECT name, environments, resource_count
FROM apps
WHERE name = 'payments-api'

Join to the Asset Inventory

cloud_assets holds one row for each source that reported a resource. Keep one row for each resource before you join:

SELECT e.environment, c.cloud, c.resource_type, c.name
FROM (
  SELECT _cq_platform_id, cloud, resource_type, name
  FROM cloud_assets
  ORDER BY _cq_sync_group_id DESC
  LIMIT 1 BY _cq_platform_id
) c
JOIN environment_memberships e ON e._cq_platform_id = c._cq_platform_id
WHERE e.environment = 'prod'

Find the Resources with No App

SELECT _cq_platform_id, cloud, resource_type, name
FROM cloud_assets
WHERE _cq_platform_id NOT IN (SELECT _cq_platform_id FROM app_memberships)
LIMIT 1 BY _cq_platform_id

Programmatic Access

You can read and write the rules through the Platform API, which is useful if you keep your configuration in source control.

In the asset endpoints, the reserved column _cq_app_id filters by app. For example, _cq_app_id = "<uuid>" selects one app, and _cq_app_id IS EMPTY selects the resources that belong to no app.

See the Platform API Reference for the full request and response formats.

Next Steps

• Asset Inventory - filter and group your resources by app
• SQL Console - query the membership tables directly
• AI Assistant - ask about your apps and environments in plain language
• Data Model - how CloudQuery Platform organizes your synced data
• Custom Columns - add your own columns to the inventory