---
title: Agent container image
summary: null
url: >-
  https://www.fastly.com/documentation/guides/next-gen-waf/setup-and-configuration/kubernetes/kubernetes-agent
---

The official name of the container image for the Next-Gen WAF agent (formerly known as the Signal Sciences agent) is `signalsciences/sigsci-agent`. The `sigsci-agent` container image is available on [Docker Hub](https://hub.docker.com/r/signalsciences/sigsci-agent). You can pull this image with `signalsciences/sigsci-agent:latest` (or replace `latest` with a [version tag](https://hub.docker.com/r/signalsciences/sigsci-agent/tags)). If you need to modify this image or want to build it locally, then follow the instructions below.

## Custom sigsci-agent Dockerfile

You can build on top of the existing `sigsci-agent` container image using `FROM`. However, some care needs to be taken as the Dockerfile is set up to run commands as the `sigsci` user instead of `root`. If you use the recommended Dockerfile, then you may need to change to the `root` user, then back to the `sigsci` user after any system modifications are done.

### Example: Installing an additional package

```text
# Start from the official sigsci-agent container
FROM signalsciences/sigsci-agent:latest

# Change to root to install a package, using `sl` as an example
USER root
RUN apk --no-cache add sl

# Change back to the sigsci user at the end for runtime
USER sigsci
```

## Build the agent Docker container image

Both [https://dl.security.fastly.com](https://dl.security.fastly.com/?prefix=sigsci-agent/) and [https://dl.signalsciences.net](https://dl.signalsciences.net/?prefix=sigsci-agent/) host the recommended `sigsci-agent` Dockerfile in the `sigsci-agent` distribution `.tar.gz` archive. To download and unpack the archive and then build the Docker container image, run the following commands in a terminal application:

### Dl.Security.Fastly.Com

```term copy nolinenums
$ curl -O https://dl.security.fastly.com/sigsci-agent/sigsci-agent_latest.tar.gz
$ mkdir sigsci-agent && tar zxvf sigsci-agent_latest.tar.gz -C sigsci-agent
$ cd sigsci-agent
$ make docker
```

### Dl.Signalsciences.Net

```term copy nolinenums
$ curl -O https://dl.signalsciences.net/sigsci-agent/sigsci-agent_latest.tar.gz
$ mkdir sigsci-agent && tar zxvf sigsci-agent_latest.tar.gz -C sigsci-agent
$ cd sigsci-agent
$ make docker
```

You can use a custom name for the tags by setting `IMAGE_NAME` (e.g., `make IMAGE_NAME=custom-prefix/sigsci-agent docker`).

To build manually, run the following command, replacing `YOUR-TAG` and `YOUR-VERSION`:

```term copy
$ docker build . -t your-tag:your-version
```

## Integrating the Next-Gen WAF agent

The Next-Gen WAF agent can be installed as a sidecar into each pod or as a service for some specialized needs.

To install the Next-Gen WAF agent in Kubernetes, integrate the sigsci-agent into a pod as a [sidecar](https://kubernetes.io/docs/concepts/workloads/pods/sidecar-containers/), a multi-container pod pattern that Kubernetes supports natively. This means adding the sigsci-agent as an additional container to the Kubernetes pod. As a sidecar, the agent scales with the app or service in the pod rather than scaling separately. In some situations, installing the sigsci-agent container as a service and [scaling it separately](https://www.fastly.com/documentation/guides/next-gen-waf/setup-and-configuration/kubernetes/kubernetes-agent-scaling) fits the deployment better.

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](https://kubernetes.io/docs/concepts/containers/container-lifecycle-hooks/#container-hooks) to slow the pod's shutdown and ensure drain timeouts are met.

```yaml
preStop:
  exec:
    command:
      - sleep
      - "30"
```

By default, the agent prioritizes quick start up and performance readiness for preliminary inspection. However, quick startup isn't always desirable if you only want the agent to inspect traffic after loading your rules and configuration data. If you want to delay agent startup, consider configuring a [startup probe](https://www.fastly.com/documentation/guides/next-gen-waf/setup-and-configuration/kubernetes/kubernetes-startup-probe).

## Getting and updating the agent container image

These instructions reference the `latest` version of the agent with `imagePullPolicy: Always`, which will pull the latest agent version even if one already exists locally. This is so the documentation does not fall out of date and continue using a stagnant agent.

However, this may not be what you need to keep installations consistent or on a specific version of the agent. In these cases, you should specify an [agent version](https://www.fastly.com/documentation/reference/changes/ngwaf-agent/). Images on Docker Hub are tagged with their versions and [a list of versions is available](https://hub.docker.com/r/signalsciences/sigsci-agent/tags).

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` 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, the agent pulls the latest image on startup, and it will continue to receive updates.
- Alternatively, you may choose to manually update the local cache by periodically forcing a pull instead of always pulling on startup:

  ```term copy
  $ docker pull signalsciences/sigsci-agent:latest
  ```

  Then, use `latest` with `imagePullPolicy: Never` set in the configuration so that pulls are never done on startup (only manually as above):

  ```yaml
  - name: sigsci-agent
      image: signalsciences/sigsci-agent:latest
      imagePullPolicy: Never
      ...
  ```

### Using a versioned 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.

```yaml
- name: sigsci-agent
    image: signalsciences/sigsci-agent:x.xx.x
    imagePullPolicy: IfNotPresent
    ...
```

This will pull the specified agent version and cache it locally. If you use this method, then we recommend parameterizing the agent image, using Helm or similar, so that future agent image updates are easier.

### Using a custom tag for the container image

It is also possible to apply a custom tag to a local agent image. Pull the agent image by version or using `latest`. Apply a custom tag, and 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:

```term copy nolinenums
$ docker pull signalsciences/sigsci-agent:latest
$ docker tag signalsciences/sigsci-agent:latest signalsciences/sigsci-agent:testing
```

Then use this image tag in the configuration:

```yaml
- name: sigsci-agent
    image: signalsciences/sigsci-agent:testing
    imagePullPolicy: Never
...
```

## Configuring the agent container

Agent configuration is normally done via the environment. Most configuration options are available as environment variables. By default, environment variables:

- have names that begin with `SIGSCI_`
- capitalize the option name
- change dashes (-) to underscores (\_)

For example, the [max-procs](https://www.fastly.com/documentation/reference/ngwaf/agent-config#agentcfg_max-procs) option would become the `SIGSCI_MAX_PROCS` environment variable. For more details on which options are available, see the [Agent Configuration documentation](https://www.fastly.com/documentation/reference/changes/ngwaf-agent/).

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](https://www.fastly.com/documentation/guides/next-gen-waf/setup-and-configuration/agent-management/managing-agent-keys) 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 (also known as workspace) the agent is configured for.
- **SIGSCI_SECRETACCESSKEY**: The **Agent Secret Key** is the shared secret key to authenticate and authorize the agent.

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:

```yaml
env:
  - name: SIGSCI_ACCESSKEYID
    valueFrom:
      secretKeyRef:
        # Update my-site-name-here to the correct site (workspace) name or similar identifier
        name: sigsci.my-site-name-here
        key: accesskeyid
  - name: SIGSCI_SECRETACCESSKEY
    valueFrom:
      secretKeyRef:
        # Update my-site-name-here to the correct site (workspace) name or similar identifier
        name: sigsci.my-site-name-here
        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:

```yaml
apiVersion: v1
kind: Secret
metadata:
  name: sigsci.my-site-name-here
stringData:
  accesskeyid: 12345678-abcd-1234-abcd-1234567890ab
  secretaccesskey: abcdefg_hijklmn_opqrstuvwxy_z0123456789ABCD
```

This can also be created from the command line with `kubectl` such as with the following example:

```term copy nolinenums
$ kubectl create secret generic sigsci.my-site-name-here \
  --from-literal=accesskeyid=12345678-abcd-1234-abcd-1234567890ab \
  --from-literal=secretaccesskey=abcdefg_hijklmn_opqrstuvwxy_z0123456789ABCD
```

Additional information about Kubernetes `secrets` functionality can be found in the [Kubernetes documentation](https://kubernetes.io/docs/concepts/configuration/secret/).

### 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 geolocation 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:

```yaml
volumes:
  - name: sigsci-tmp
    emptyDir: {}
```

Containers will then mount this volume at `/sigsci/tmp`:

```yaml
volumeMounts:
  - name: sigsci-tmp
    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`

## Related content

- [Kubernetes installation overview](https://www.fastly.com/documentation/guides/next-gen-waf/setup-and-configuration/kubernetes/kubernetes-intro)