Manage lenses with the API

Manage lenses with the Insights API to keep a team's lenses in version control, or to set up the same views across several Hub installs. A lens you create through the API appears in the Console's Lenses panel like any other.

Before you begin

• A hub kubectl context. See Configure kubectl for the Hub.
• Any signed-in user can create lenses, and only a lens's owner can change or delete it. See the Roles reference.
• A search term or filter expression that returns what you want. Test it first with Query resources with the API.

Hub doesn't serve patch, so change lenses with kubectl replace rather than kubectl apply or kubectl edit. See Use Hub APIs with kubectl.

Create a lens

1. Write the lens.

   team-a-pods.yaml

   apiVersion: inventory.hub.upbound.io/v1beta1
   kind: Lens
   metadata:
     name: team-a-pods
   spec:
     displayName: Team A pods
     description: Pods the platform team owns.
     target:
       apiVersion: inventory.hub.upbound.io/v1beta1
       kind: Resource
     filter:
       expression: 'kind == "Pod" && labels["team"] == "a"'
     sort:
       - field: createdAt
         direction: desc

2. Create it.

   kubectl --context=hub create -f team-a-pods.yaml

3. Confirm it exists.

   kubectl --context=hub get lenses.inventory.hub.upbound.io

   The list includes your lens, the lenses others shared, and the built-in lenses.

The new lens is private. Open it in the Console from the Lenses panel on the page its target names.

Share a lens

Set the hub.upbound.io/shared annotation to "true" and replace the lens:

kubectl --context=hub get lenses.inventory.hub.upbound.io team-a-pods -o yaml > team-a-pods.yaml

team-a-pods.yaml

metadata:
  name: team-a-pods
  annotations:
    hub.upbound.io/shared: "true"

kubectl --context=hub replace -f team-a-pods.yaml

To make a lens private again, remove the annotation and replace it.

Change a lens

Read the lens, edit the file, and replace it:

kubectl --context=hub get lenses.inventory.hub.upbound.io team-a-pods -o yaml > team-a-pods.yaml
# Edit spec in team-a-pods.yaml.
kubectl --context=hub replace -f team-a-pods.yaml

Replacing a lens replaces its whole definition, so start from the current object rather than from an older file.

Delete a lens

kubectl --context=hub delete lenses.inventory.hub.upbound.io team-a-pods

Lens fields

Field	Required	Description
spec.displayName	Yes	The name the Console shows.
spec.description	No	A longer description.
spec.target	Yes	The list the lens applies to. apiVersion is inventory.hub.upbound.io/v1beta1, and kind is Resource, TypeDefinition, or CrossplanePackage.
spec.filter.search	One of the two	A free-text search, as in the list's search parameter.
spec.filter.expression	One of the two	A filter expression for the target, at most 2048 bytes. Hub checks it against the target's fields when you save.
spec.sort	No	A list of field and direction (asc or desc) pairs, applied in order. Fields are the target's sortable fields.
status.createdBy	Set by Hub	The owner. Only this user can change or delete the lens.
status.lastUpdatedBy, status.lastUpdatedAt	Set by Hub	Who last changed the lens, and when.

Hub keeps three annotations and drops any others when you save:

Annotation	Meaning
hub.upbound.io/shared	"true" shares the lens with everyone who signs in to Hub.
hub.upbound.io/source	upbound on built-in lenses.
hub.upbound.io/display	The Console's columns and layout. The Console owns its format, so leave it as the Console wrote it.

Troubleshoot

Symptom	Cause
403 when you change or delete a lens	You don't own it. Built-in lenses belong to Hub, and shared lenses belong to the user who created them. Create your own copy.
405 from kubectl apply or kubectl edit	Hub doesn't serve patch. Use kubectl replace.
400 naming spec.filter	The lens has neither a search nor an expression, or the expression is invalid for the target. See Errors.
400 naming spec.target	The target isn't one of Resource, TypeDefinition, or CrossplanePackage in inventory.hub.upbound.io/v1beta1.
A custom annotation disappears	Hub keeps only the three lens annotations.

Next steps

• Lenses
• Use lenses in the Console