# Lenses Resource Names (LRNs)

Use an LRN to specify a resource across all of Lenses, unambiguously:

* To add topic permissions for a team in IAM permissions.
* To share a consumer-group reference with a colleague.

## LRN format

A canonical LRN has 3 parts called **segments**. A colon `:` separates them:

```
service:resource-type:resource-id
```

When you use LRNs as **resource patterns** in IAM, Lenses also accepts shorter patterns like `*` and `service:*`. See [IAM overview](/latest/devx/6.1/user-guide/iam/overview.md).

### service

`service` is the namespace of the Lenses service that manages a set of resource types.

e.g. `kafka` for things like topics and consumer groups.

### resource-type

`resource-type` is the type of resources that are served by a service.

e.g. `topic` for a Kafka topic, `consumer-group` for a Kafka consumer group. They both belong to the `kafka` service.

### resource-id

`resource-id` is the unique name or path that identifies a resource. The resource ID is specific to a service and resource type. The resource ID can be:

* a single resource name, e.g.:
  * `lucy.clearview@lenses.io` for a user resource name.
  * The full LRN would be `iam:user:lucy.clearview@lenses.io`.
* a nested resource path that contains slashes `/`, e.g.:
  * `dev-environment/kafka/my-topic` for a Kafka topic.
  * The full LRN would be `kafka:topic:dev-environment/kafka/my-topic`.

### Examples

IAM user

```
iam:user:lucy.clearview@lenses.io
```

Kafka topic

```
kafka:topic:dev-environment/kafka/my-topic
```

Kafka consumer group

```
kafka:consumer-group:dev-environment/kafka/my-consumer-group
```

Schema Registry schema

```
schemas:schema:dev-environment/schema-registry/my-topic-value
```

Kafka Connect connector

```
kafka-connect:connector:dev-environment/connect-cluster-1/my-s3-sink
```

### Allowed characters

LRNs separate top-level segments with a colon `:` and resource path segments with a slash `/`.

Character rules depend on the segment:

* `service` and `resource-type` use `a-z`, `A-Z`, `0-9`, and `-`.
* `resource-id` is resource-specific.
  * It must not contain `:` (reserved for top-level segments).
  * It may contain `/` to form a resource path.
  * It may contain `*` when used as a wildcard pattern (see below).

## Using wildcards

Use the wildcard asterisk `*` to express catch-all LRNs.

### Rules

* No wildcards are allowed in `service` (except the global `*` pattern).
* No partial wildcards are allowed in `resource-type`.
  * Use `service:*` to match all resource types for a service.
* Wildcards in `resource-id` can be:
  * a full path segment: `*`
  * a suffix inside a segment: `prefix*`
* If a `resource-id` segment is `*`, remaining segments are assumed `*` too.
  * Example: `kafka:topic:my-env/*` expands to `kafka:topic:my-env/*/*`.

### Good examples

{% hint style="success" %}
Use these examples to express multiple resources easily.
{% endhint %}

| Wildcard pattern                                | LRN Example                                            | Definition                                                                                          | Example means…                                                                           |
| ----------------------------------------------- | ------------------------------------------------------ | --------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| `*`                                             | `*`                                                    | Global wildcard. Captures all resources that Lenses manages.                                        | *"Everything"*                                                                           |
| `service:*`                                     | `kafka:*`                                              | Service wildcard. Captures all resources for a service.                                             | *"All Kafka resources in all environments"*                                              |
| `service:resource-type:*`                       | `kafka:topic:*`                                        | Resource-type wildcard. Captures all resources for a resource type.                                 | *"All Kafka topics in all environments"*                                                 |
| `service:resource-type:parent/*/grandchild`     | `kafka-connect:connector:dev-environment/*/my-s3-sink` | Path segment wildcard. Captures a part of the resource path.                                        | *"All connectors named 'my-s3-sink' in all Connect clusters under 'dev-environment'"*    |
| `service:resource-type:resourcePa*`             | `kafka:topic:dev-environment/kafka/red-*`              | Prefix match. Captures resources whose `resource-id` starts with the given path prefix.             | *"All Kafka topics in 'dev-environment' whose name starts with 'red-'"*                  |
| `service:resource-type:paren*/chil*/grandchil*` | `kafka-connect:connector:dev*/sinks*/s3*`              | Segment prefix match. Captures resources where different path segments start with certain prefixes. | *"All connectors in envs starting 'dev', clusters starting 'sinks', name starting 's3'"* |

### Bad examples

{% hint style="danger" %}
Avoid these examples because they are ambiguous. Lenses does not allow them.
{% endhint %}

| Wildcard pattern                    | LRN Example                                  | Restriction                                                                       | Better alternative                                        |
| ----------------------------------- | -------------------------------------------- | --------------------------------------------------------------------------------- | --------------------------------------------------------- |
| `servic*:resource-type:resource-id` | `kafk*:topic:dev-environment/kafka/my-topic` | No wildcards allowed in `service`. A service must be its full string.             | Global wildcard `*`                                       |
| `service:resource-typ*:resource-id` | `kafka:topi*:dev-environment/*`              | No wildcards allowed in `resource-type`. A resource type must be its full string. | Service wildcard `service:*`                              |
| `service:*:resource-id`             | `kafka:*:dev-environment/kafka/my-topic`     | If `resource-type` is `*`, you must not set `resource-id`.                        | `kafka:*` or `kafka:topic:dev-environment/kafka/my-topic` |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.lenses.io/latest/devx/6.1/user-guide/lrn.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.