Agent Secrets File Options

In this article, you will learn of alternate ways to provide the authentication secrets to an agent.

Secrets File

A secrets file is required to store the AGENT_ID and the short-lived authenticationToken. There are multiple ways to store the secrets. The requirements are:

• The secrets file must be writable
• The secrets file must be accessible as a file from within the container

Retrieving authentication token for agent

In order for the sensor agent to register with Analytics it requires an authentication token. The authentication token can be provided to the agent in several ways. This guide will use the direct method of specifying the token directly to the agentAuthenticationToken variable.

There are three ways to fetch an authentication token from the Analytics

• using the Analytics graphical user interface
• by calling API for a specific agentID
• or by calling the API for the tenant-wide api-key

All three methods are described below.

Fetch authentication token via Analytics UI

If using the UI, an agent definition has to be created, then select "Generate auth token"

Fetch authentication token for a specific agent via API

To use the API, POST the agentID that will be used for the agent to get a secrets file for that agentID. The agentID is a formatted UUID and can be randomly created using for example "uuidgen".

POST {{tenant-server}}/api/orchestrate/v3/agents/{{agentId}}/secrets

The response will be a JSON formatted string like below

agentConfig:
  identification:
    agentId: 9c5d66a3-abcd-efef-0123-3ea38a4fbcf3
    authenticationToken: eyJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJhY2NlZGlhbi5jb20iLCJzdWIiOiJobnlkZWxsQGFjY2VkaWFuLmNvbaa..........vU6QQ3cBsHinzLOLysOAjigqMSmnf-RY6s

Both the agentId and the authenticationToken strings need to be put in the values.yaml file, or specified on the command line when deploying the agent with helm.

Retrieve tenant-wide API key from orchestration service

The third option is to use the tenant-wide API key. This key token can be used to bootstrap many agents as it it not specific to an agent ID.
The agents will then after connection grab individual authenticationToken and update their secrets files with this.

An ‘API Key’ JWT is global for the tenant and is created by sending the below POST to the orchestration API, there is no graphical UI on Analytics for this operation:

POST {{tenant-server}}/api/orchestrate/v3/agents/api-key

EXAMPLE RETURN:
eyJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJhY2NlZGlhbi5jb20iLCJzdWIiOiJhZG1pbkBkYXRhaHViLmNvbSIsImV4csampleXVkIjoiYWNjZWRpYW4uY29tIiwidG9rZW5JRCI6NTA4LCJ0ZW5hbnRJRCI6ImFmYjEwOGQ4LTg3MDMtNDIwNy1hYmYexample1MGJiZWU5NiIsInBlcm1pc3Npb25zIjpbImRhdGEtaW5ncmVzcyJdfQ.8yjsKQWX3xKJTZlsp_dC04b9ZrSgJpc-kXhLm_22abc

Place this api-key in the values.yaml file or use on the command line when deploying the agent with helm.

Using the authentication token in docker-compose

Example docker-compose file with api-key token added

version: '3'
services:
  tcp-agent-service:
    container_name: "my-throughput-container"
    image: "gcr.io/sky-agents/agent-throughput-amd64:r23.04"
    hostname: "my-agent"
    restart: "always"
    environment:
            AGENT_MANAGEMENT_PROXY: "10.11.12.13"
            AGENT_MANAGEMENT_PROXY_PORT: "55777"
            AGENT_AUTHENTICATION_TOKEN: "eyJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJhY..."
    volumes:
      - /home/agentuser/ae311d23-5ca7-9921-fake-25example54a.yaml:/run/secrets/secrets.yaml

See API documentation for details on the call to create the api-key

The sections below will cover the following three methods of storing the secrets file:

Using a file on the host system (Docker)
Using named volumes (Docker)
Using an opaque secret (Kubernetes/OpenShift)

Secrets File on Host (Docker)

This approach is the simplest. However it does not work in all deployment environment. This is best used for single deployments like demos or smaller setups.

Works with
Docker

Does not work with
Cisco IOS-XR/XE (Docker)
Kubernetes
OpenShift
Docker Swarm

Instructions

Get the secrets file for the agent using the Sensor Orchestrate API, place it in the host filesystem where it's accessible and writable by the container environment (containerd).

POST {{tenant-server}}/api/orchestrate/v3/agents/{{agentId}}/secrets

If using docker-compose, add the following to the docker-compose.yaml file:

services:
  sensor-xyz:    
    volumes:
      - '/path/to/secrets.yaml:/run/secrets/secrets.yaml'

If using “docker run”, add the following option to the command line:

-v /path/to/secrets.yaml:/run/secrets/secrets.yaml

Named Volumes (Docker)

Named volumes are in the Docker control span and are accessible by the containers without having to manage them on the host.

Works with
Docker
Cisco IOS-XR (Docker)

Does not work with
Kubernetes
OpenShift
Docker Swarm

Instructions

Get the secrets file for the agent using the Sensor Orchestrate API, place it in the host filesystem where it's accessible by the container environment (containerd).

POST {{tenant-server}}/api/orchestrate/v3/agents/{{agentId}}/secrets

Create the named volume

docker volume create xyzsecrets

Copy the secrets file. To copy the secrets file a temporary container is required.

docker container create --name temporaryContainer -v xyzsecrets:/run/secrets skylight-agent-xyz:22.07
docker cp secrets.yaml addVolume:/run/secrets
docker rm temporaryContainer 

If using docker-compose, add the following to the docker-compose.yaml file:

services:
  sensor-xyz:  
    volumes:
      - xyzsecrets:/run/secrets
volumes:
  xyzsecrets:

If using “docker run”, add the following option to the command line:

--mount source=xyzsecrets,target=/run/secrets

Opaque Secrets (Kubernetes/OpenShift)

Kubernetes offer various methods for managing secrets. Once if them is an opaque type. Basically, it’s a base64 encoded binary that is added in the secrets definition.

Works with
Kubernetes
OpenShift
Docker Swarm

Does not work with
Docker
Cisco IOS-XR (Docker)

Instructions

Get the secrets file for the agent using the Sensor Orchestrate API, place it in the host filesystem where it's accessible by the container environment (containerd).

POST {{tenant-server}}/api/orchestrate/v3/agents/{{agentId}}/secrets

Create the named volume

oc create secret generic xyzsecret --from-file=secrets.yaml

Add the volume definition in the spec section of a deployment.

      volumes:
        - name: secrets-yaml
          secret: 
            secretName: xyzsecret

Add the volumeMounts definitions in the container definition. The mountPath is the path to the target directory in the container. The file that was added using the “oc create secrets” will be located in that folder.

          volumeMounts:
            - name: secrets-yaml
              mountPath: /var/run/secrets

The “/var/run/secrets/secrets.yaml" is the default path for the secrets file. To change location and/or filename the AGENT_SECRETS_PATH environment variable must be used.