Kubernetes Agent + Module
Last updated 2023-05-04
In this example, the Signal Sciences agent is deployed in a docker sidecar, communicating with a module deployed on the application.
Integrating the Signal Sciences agent
The Signal Sciences Agent can be installed as a sidecar into each pod or as a service for some specialized needs.
The recommended way of installing the Signal Sciences Agent in Kubernetes is by integrating the sigsci-agent
into a pod as a sidecar. This means adding the sigsci-agent
as an additional container to the Kubernetes pod. As a sidecar, the agent will scale with the app/service in the pod instead of having to do this separately. However, in some situations, it may make more sense to install the sigsci-agent
container as a service and scale it separately from the application.
The sigsci-agent
container can be configured in various ways depending on the installation type and module being used.
You can use the preStop
container hook to slow the pod's shutdown and ensure drain timeouts are met.
1preStop:2 exec:3 command:4 - sleep5 - "30"
Getting and updating the Signal Sciences agent container image
An official signalsciences/sigsci-agent
container image is available from the Signal Sciences account on Docker Hub.
Alternatively, if you want to build your own image or need to customize the image, then follow the sigsci-agent build instructions.
These instructions reference the latest
version of the agent with imagePullPolicy: Always
, which will pull the latest agent version even if one already exist locally. This is so the documentation does not fall out of date and anyone using this will not have an agent that stays stagnant. However, this may not be what if you need to keep installations consistent or on a specific version of the agent. In these cases, you should specify an agent version. Images on Docker Hub are tagged with their versions and a list of versions is available on Docker Hub.
Whether you choose to use the latest
image or a specific version, there are a few items to consider to keep the agent up-to-date.
Using the latest
Signal Sciences container image
If you do choose to use the latest
image, then you will want to consider how you will keep the agent up to date.
If you have used the
imagePullPolicy: Always
option, then the latest image will be pulled on each startup and your agent will continue to get updates.Alternatively, you may instead choose to manually update the local cache by periodically forcing a pull instead of always pulling on startup:
$ docker pull signalsciences/sigsci-agent:latestThen, use
latest
withimagePullPolicy: Never
set in the configuration so that pulls are never done on startup (only manually as above):1- name: sigsci-agent2 image: signalsciences/sigsci-agent:latest3 imagePullPolicy: Never4 ...
Using a versioned Signal Sciences container image
To use a specific version of the agent, replace latest
with the agent version (represented here by x.xx.x
). You may also want to change imagePullPolicy: IfNotPresent
in this case as the image should not change.
1- name: sigsci-agent2 image: signalsciences/sigsci-agent:x.xx.x3 imagePullPolicy: IfNotPresent4 ...
This will pull the specified agent version and cache it locally. If you use this method, then it is recommended that you parameterize the agent image, using Helm or similar, so that it is easier to update the agent images later on.
Using a custom tag for the Signal Sciences container image
It is also possible to apply a custom tag to a local agent image. To do this, pull the agent image (by version or use latest
), apply a custom tag, then use that custom tag in the configuration. You will need to specify imagePullPolicy: Never
so local images are only updated manually. After doing so, you will need to periodically update the local image to keep the agent up-to-date.
For example:
$ docker pull signalsciences/sigsci-agent:latest$ docker tag signalsciences/sigsci-agent:latest signalsciences/sigsci-agent:testing
Then use this image tag in the configuration:
1- name: sigsci-agent2 image: signalsciences/sigsci-agent:testing3 imagePullPolicy: Never4...
Configuring the Signal Sciences agent container
Agent configuration is normally done via the environment. Most configuration options are available as environment variables. Environment variables names have the configuration option name all capitalized, prefixed with SIGSCI_
and any dashes (-) changed to underscores (_). For example, the max-procs option would become the SIGSCI_MAX_PROCS
environment variable. For more details on what options are available, see the Agent Configuration documentation.
The sigsci-agent
container has a few required options that need to be configured:
- Agent credentials (Agent Access Key and Agent Secret Key).
- A volume to write temporary files.
Agent credentials
The sigsci-agent
credentials are configured with two environment variables. These variables must be set or the agent will not start.
- SIGSCI_ACCESSKEYID: The Agent Access Key identifies which site in the Signal Sciences console that the agent is configured for.
- SIGSCI_SECRETACCESSKEY: The Agent Secret Key is the shared secret key to authenticate and authorize the agent.
The credentials can be found by following these steps:
Log in to the Signal Sciences console.
From the Sites menu, select a site if you have more than one site.
Click Agents in the navigation bar. The agents page appears.
Click View agent keys. The agent keys window appears.
Copy the Agent Access Key and Agent Secret Key.
Because of the sensitive nature of these values, we recommend you use the built in secrets
functionality of Kubernetes. With this configuration, the agent will pull the values from the secrets data instead of reading hardcoded values into the deployment configuration. This also makes any desired agent credential rotation easier to manage by having to change them in only one place.
Use the valueFrom
option instead of the value
option to use the secrets
functionality. For example:
1env:2 - name: SIGSCI_ACCESSKEYID3 valueFrom:4 secretKeyRef:5 # Update my-site-name-here to the correct site name or similar identifier6 name: sigsci.my-site-name-here7 key: accesskeyid8 - name: SIGSCI_SECRETACCESSKEY9 valueFrom:10 secretKeyRef:11 # Update my-site-name-here to the correct site name or similar identifier12 name: sigsci.my-site-name-here13 key: secretaccesskey
The secrets
functionality keeps secrets in various stores in Kubernetes. This guide uses the generic secret store in its examples, however any equivalent store can be used. Agent secrets can be added to the generic secret store using YAML similar to the following example:
1apiVersion: v12kind: Secret3metadata:4 name: sigsci.my-site-name-here5stringData:6 accesskeyid: 12345678-abcd-1234-abcd-1234567890ab7 secretaccesskey: abcdefg_hijklmn_opqrstuvwxy_z0123456789ABCD
This can also be created from the command line with kubectl
such as with the following example:
1$ kubectl create secret generic sigsci.my-site-name-here \2 --from-literal=accesskeyid=12345678-abcd-1234-abcd-1234567890ab \3 --from-literal=secretaccesskey=abcdefg_hijklmn_opqrstuvwxy_z0123456789ABCD
Additional information about Kubernetes secrets
functionality can be found here.
Agent temporary volume
For added security, we recommended the sigsci-agent
container be executed with the root filesystem mounted as read only. However, the agent still needs to write some temporary files such as the socket file for RPC communication and some periodically updated files such as GeoIP data.
To accomplish this with a read only root filesystem, there needs to be a writeable volume mounted. This writeable volume can also be shared to expose the RPC socket file to other containers in the same pod.
The recommended way of creating a writeable volume is to use the builtin emptyDir
volume type. This is typically configured in the volumes
section of a deployment, as shown in the following example:
1volumes:2 - name: sigsci-tmp3 emptyDir: {}
Containers will then mount this volume at /sigsci/tmp
:
1volumeMounts:2 - name: sigsci-tmp3 mountPath: /sigsci/tmp
The default in the official agent container image is to have the temporary volume mounted at /sigsci/tmp
. If this needs to be moved for the agent container, then the following agent configuration options should also be changed from their defaults to match the new mount location:
rpc-address
defaults to/sigsci/tmp/sigsci.sock
shared-cache-dir
defaults to/sigsci/tmp/cache
Signal Sciences agent with a web application and Signal Sciences module installed
This deployment example configures the example helloworld
application to use the sigsci-agent
via RPC and deploys the sigsci-agent
container as a sidecar to process these RPC requests.
To configure Signal Sciences with this deployment type you must:
- Modify your application to add the appropriate Signal Sciences module, configured it to communicate with a
sigsci-agent
via RPC. - Add the sigsci-agent container to the pod, configured in RPC mode.
- Add an
emptyDir{}
volume as a place for thesigsci-agent
to write temporary data and share the RPC address.
Modifying and configuring the application container
The helloworld
example is a language based module (Golang) that has already been modified to enable communication to the sigsci-agent
via RPC if configured to do so. This configuration is done via arguments passed to the helloworld
example application as follows:
- Listening Address (defaults to
localhost:8000
). - Optional Signal Sciences Agent RPC Address (default is to not use the
sigsci-agent
). Other language based modules are similar. Web server based modules must have the Signal Sciences module added to the container.
For this helloworld
application to work with the sigsci-agent
it must have the sigsci-agent
address configured as the second program argument and the sigsci-tmp
volume mounted so that it can write to the socket file:
1...2 containers:3 # Example helloworld app running on port 8000 against sigsci-agent via UDP /sigsci/tmp/sigsci.sock4 - name: helloworld5 image: signalsciences/example-helloworld:latest6 imagePullPolicy: IfNotPresent7 args:8 # Address for the app to listen on9 - localhost:800010 # Address sigsci-agent RPC is listening on11 - /sigsci/tmp/sigsci.sock12 ports:13 - containerPort: 800014 volumeMounts:15 # Shared mount with sigsci-agent container where the socket is shared via emptyDir volume16 - name: sigsci-tmp17 mountPath: /sigsci/tmp
Adding and configuring the Signal Sciences agent container as a sidecar
The sigsci-agent
container will default to RPC mode with a Unix Domain Socket (UDS) file at /sigsci/tmp/sigsci.sock
. There must be a temp volume mounted at /sigsci/tmp
to capture this socket file and must be shared with the pod. The web application must be configured to communicate with the sigsci-agent
via this UDS socket. The deployment YAML must be modified from the example above by adding a second argument to specify the sigsci-agent
RPC address of /sigsci/tmp/sigsci.sock
.
NOTE
It is possible to use a TCP based listener for the sigsci-agent
RPC, but this is not recommended for performance reasons. If TCP is needed (or UDS is not available, such as in Windows), then the RPC address can be specified as ip:port
or host:port
instead of a UDS path. In this case, the volume does not have to be shared with the app, but it does need to be created for the sigsci-agent
container to have a place to write temporary data such as geodata.
Adding the sigsci-agent
container as a sidecar:
1...2 containers:3 # Example helloworld app running on port 8000 against sigsci-agent via UDP /sigsci/tmp/sigsci.sock4 - name: helloworld5 image: signalsciences/example-helloworld:latest6 imagePullPolicy: IfNotPresent7 args:8 # Address for the app to listen on9 - localhost:800010 # Address sigsci-agent RPC is listening on11 - /sigsci/tmp/sigsci.sock12 ports:13 - containerPort: 800014 volumeMounts:15 # Shared mount with sigsci-agent container where the socket is shared via emptyDir volume16 - name: sigsci-tmp17 mountPath: /sigsci/tmp18 # Signal Sciences Agent running in default RPC mode19 - name: sigsci-agent20 image: signalsciences/sigsci-agent:latest21 imagePullPolicy: Always22 env:23 - name: SIGSCI_ACCESSKEYID24 valueFrom:25 secretKeyRef:26 # This secret needs added (see docs on sigsci secrets)27 name: sigsci.my-site-name-here28 key: accesskeyid29 - name: SIGSCI_SECRETACCESSKEY30 valueFrom:31 secretKeyRef:32 # This secret needs added (see docs on sigsci secrets)33 name: sigsci.my-site-name-here34 key: secretaccesskey35 # If required (default is /sigsci/tmp/sigsci.sock for the container)36 #- name: SIGSCI_RPC_ADDRESS37 # value: /path/to/socket for UDS OR host:port if TCP38 securityContext:39 # The sigsci-agent container should run with its root filesystem read only40 readOnlyRootFilesystem: true41 volumeMounts:42 # Default volume mount location for sigsci-agent writeable data43 # NOTE: Also change `SIGSCI_SHARED_CACHE_DIR` (default `/sigsci/tmp/cache`)44 # if mountPath is changed, but best not to change.45 - name: sigsci-tmp46 mountPath: /sigsci/tmp
NOTE
The above sigsci-agent
configuration assumes that sigsci
secrets were added to the system section above.
Adding the Signal Sciences agent temp volume definition to the deployment
Finally, the agent temp volume needs to be defined for use by the other containers in the pod. This uses the builtin emptyDir: {}
volume type.
1...2 volumes:3 # Define a volume where sigsci-agent will write temp data and share the socket file,4 # which is required with the root filesystem is mounted read only5 - name: sigsci-tmp6 emptyDir: {}
Do not use this form to send sensitive information. If you need assistance, contact support. This form is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.