# 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

The top-level format has 3 parts called **segments**. A semi-colon `:` separates them:

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

### 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 `/`.

A segment may have:

* Alphanumeric characters: `a-z, A-Z, 0-9`
* Hyphen symbols only: `-`

## Using wildcards

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

### Good examples

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

| Wildcard pattern                                | LRN Example                                            | Definition                                                                                                                                                                                                                        | Example means…                                                                                                                                                   |
| ----------------------------------------------- | ------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `*`                                             | `*`                                                    | <p>Global wildcard.</p><p>Capture all the resources that Lenses manages.</p>                                                                                                                                                      | *"Everything"*                                                                                                                                                   |
| `service:*`                                     | `kafka:*`                                              | <p>Service-specific wildcard.</p><p>Capture all the resources for a service.</p>                                                                                                                                                  | *"All Kafka resources in all environments, i.e. topics, consumer groups, acls and quotas"*                                                                       |
| `service:resource-type:*`                       | `kafka:topic:*`                                        | <p>Resource-type-specific wildcard.</p><p>Capture all the resources for a type of resources of a service.</p>                                                                                                                     | *"All Kafka topics in all environments"*                                                                                                                         |
| `service:resource-type:parent/*/grandchild`     | `kafka-connect:connector:dev-environment/*/my-s3-sink` | <p>Path segment wildcard.</p><p>Capture a part of the resource path.</p>                                                                                                                                                          | *"All connectors named 'my-s3-sink' in all Connect clusters under the environment 'dev-environment' "*                                                           |
| `service:resource-type:resourcePa*`             | `kafka:topic:dev-environment/kafka/red-*`              | <p>Trailing wildcard.</p><p>This wildcard is at the end of an LRN. It acts as a 'globstar' (<code>\*\*</code>) and matches against the rest of the string.</p><p>Capture the resources that start with the given path prefix.</p> | *"All Kafka topics in the environment 'dev-environment' whose name starts with 'red-' "*                                                                         |
| `service:resource-type:paren*/chil*/grandchil*` | `kafka-connect:connector:dev*/sinks*/s3*`              | <p>Path suffix wildcard.</p><p>Capture resources where different path segments start with certain prefixes.</p>                                                                                                                   | *"All connectors in all environments that start with 'dev', within any Connect cluster that starts with 'sinks' and where the connector name starts with '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` | <p><code>kafk\*:*:dev-environment/</code></p><p><br>or<br><br><code>*:topic:dev-environment/</code></p> | <p>No wildcards allowed at the service level.<br><br>A service must be its full string.</p>            | Global wildcard `*`                                                                                           |
| `service:resource-typ*:resource-id` | `kafka:topi*:dev-environment/*`                                                                         | <p>No wilcards allowed at the resource-type level.<br><br>A resource type must be its full string.</p> | <p>Service-specific wildcard <code>service:\*</code><br><br>No resource-id segments allowed in this case.</p> |