Satellites require keys to authenticate and communicate with Lightstep. You need to create a Satellite key when you install and configure Satellites. Satellite keys expire after a year, and you’ll need to generate a new one when they do.

Only users with the Admin role can generate Satellite keys.

Create Satellite Keys

You need to create a Satellite key when you install and configure your Satellite. You can use one key for multiple Satellites or create separate keys. In general, we recommend using a unique key for each logical pool of satellites, but not a unique key per satellite instance.

To create a Satellite key:

  1. From the left-hand navigation, select Account > Account Settings.

  2. Select the Satellite Keys tab and click Create New Satellite Key.

  3. Enter a description for the key and click Create Key. Use this field to describe where this key will be used or deployed (such as a pool name or a region), or other identifying characteristics. You can’t edit the description after creating the key, so if you need to change it, create a new key with the correct description and revoke the original.

    Your key is shown, along with the ID, expiration date, and other information.

  4. Copy the key to your clipboard by clicking Copy & Close. You should paste it to a safe place, as you can’t view the key again later.

    This key can’t be shown again (for security purposes), so copy this key and paste it in a safe place before moving on to the next step.

  5. Paste the key as the value for the api_key configuration parameter:

    • Docker: Update the COLLECTOR_API_KEY environment variable (in a cloud-based cluster this could be a change in an AWS task definition, or in a Kubernetes configuration map) to the newly generated Satellite key. If using Docker with a config.yml file, update the api_key variable in the .yaml file.

    • Debian: Modify /etc/lightstep/collector.yaml on the machine by setting the api_key variable to the newly generated Satellite key.

    • AMI/AWS: Modify User Data in EC2 by setting the api_key environment variable to a newly generated Satellite key.

Update a Satellite Key

Satellite keys expire after a year. Lightstep will notify you by email when the key is about to expire. If your Satellite Key is expiring soon, generate a new Satellite Key and update your Satellite configuration to continue sending data to Lightstep. Once you’ve updated the Satellite, you can revoke the previous key.

Revoke a Satellite Key

You can revoke a Satellite key if needed.

To revoke a Satellite key:

  1. From the left-hand navigation, select Account > Account Settings.

  2. In the Satellite Keys area, find the Satellite key and click Revoke Key.

    Revoking a Satellite key immediately disables your Satellite. It will no longer be able to communicate with Lightstep.