Edge Agent

Warrant Enterprise Only

The Warrant Edge Agent is a lightweight service which can process Warrant check requests. It can be deployed in any cloud environment to provide high availability in the unlikely scenario that Warrant's check API suffers an outage. The Edge Agent serves requests from a local cache and connects to the Warrant API to keep its access rules up-to-date in the background. Although quick to update as changes take place, the Edge Agent does not offer the same real-time consistency guarantees that the Warrant API does. As a result, it is only recommended for applications with strict availability requirements and looser consistency requirements.

Deploy the Edge Agent

Agents can be deployed on Docker or Kubernetes, with support for more platforms coming soon. Select a deployment option below and follow the steps to get the agent running. If there's a platform you'd like us to support, drop us a note.

Docker

1. Pull the Docker image

docker pull warrantdev/edge-agent

2. Configure the agent properties

Create a file named agent.properties to configure the agent. Add the following properties, filling out your own values for each:

# agent.properties
API_KEY=[your api key]
DATASTORE=[memory | redis]

Supported options for the DATASTORE property are redis and memory (default). It's not recommended to run the edge agent with the memory option in production.

For more information on the properties, take a look at the properties reference.

3. Start the docker container

From the directory where you created agent.properties, start the docker container with the following command, using the --env-file flag to pass in the properties file:

docker run --name edge-agent --env-file agent.properties warrantdev/edge-agent

Local Testing

To run the agent image locally with a local Redis instance, set REDIS_HOSTNAME in your properties file to host.docker.internal.

If you are running the agent on your local machine, map the container's port to the host port:

docker run --name edge-agent --env-file agent.properties -p 3000:3000 warrantdev/edge-agent

If you are running the agent on Apple Silicon, include the --platform linux/amd64 flag:

docker run --name edge-agent --env-file agent.properties --platform linux/amd64 warrantdev/edge-agent

Kubernetes

1. Create a deployment config

Create a deployment.yaml file with the following configuration, replacing each environment variable's value with the appropriate values

apiVersion: apps/v1
kind: Deployment
metadata:
  name: warrant-edge
  labels:
    app: warrant-edge
spec:
  replicas: 1
  selector:
    matchLabels:
      name: warrant-edge
  template:
    metadata:
      labels:
        name: warrant-edge
    spec:
      containers:
        - name: agent
          image: warrantdev/edge-agent:latest
          imagePullPolicy: IfNotPresent
          ports:
            - containerPort: 3000
          env:
            - name: API_KEY
              value: REPLACE_ME
            - name: DATASTORE
              value: REPLACE_ME
            - name: REDIS_HOSTNAME
              value: REPLACE_ME
            - name: REDIS_PORT
              value: REPLACE_ME
            - name: REDIS_PASSWORD
              value: REPLACE_ME

For more information on the properties, take a look at our reference.

2. Apply the deployment.yaml configuration to your Kubernetes cluster

kubectl apply -f deployment.yaml

Once deployed, the edge agent will take a few moments to initialize its local cache and connect to stream.warrant.dev to receive updates as your access model changes. After the agent is initialized, it will be able to serve requests at /v2/authorize.

Configure the SDK

Configure the Warrant server-side SDK you're using to send access check requests to a your Edge Agent by overriding the authorize endpoint.

Go

client := warrant.NewClient(warrant.ClientConfig{
    ApiKey: "your-api-key",
    AuthorizeEndpoint: "your-edge-agent-address", // ex: http://localhost:3000
})

Node.js

require 'warrant'

Warrant.api_key = "your-api-key"
Warrant.authorize_endpoint = "your-edge-agent-address" # ex: http://localhost:3000

Ruby

import { Client as Warrant } from "@warrantdev/warrant-node";

const warrant = new Warrant({
  apiKey: "your-api-key",
  authorizeEndpoint: "your-edge-agent-address", // ex: http://localhost:3000
});

After configuring the authorization endpoint, all access check requests made by the Warrant server-side SDK will go to your agent.

Caching Options

The Edge Agent must be configured with a datastore in which it can cache access rules. The agent currently supports redis and a default in-memory cache.

In-memory (default)

The default in-memory cache is great for setting up and trying out the edge agent locally but is not suitable for production usage.

Redis

The agent can be configured to cache access rules using Redis. To configure the agent to use Redis, set the DATASTORE property to redis and provide the following properties:

REDIS_HOSTNAME
REDIS_PASSWORD (optional)
REDIS_PORT (optional)
REDIS_DATABASE (optional)

Update Strategy

You can also configure the strategy the Edge Agent uses to keep its local cache up-to-date with the Warrant API.

Polling

By default, the Edge Agent uses the POLLING update strategy to keep itself up-to-date, polling the Warrant API at a configurable frequency to fetch updates.

Configure the Edge Agent to use the POLLING update strategy by setting the UPDATE_STRATEGY property:

Update Strategy - Polling

UPDATE_STRATEGY=POLLING

You can optionally configure the polling frequency (in seconds) by setting the POLLING_FREQUENCY property (must be >= 10):

Configure Polling Frequency

POLLING_FREQUENCY=60 # Set polling frequency to 60s (1 minute)

Streaming

The Edge Agent can also be configured to connect to stream.warrant.dev and receive incremental updates as they occur.

Configure the Edge Agent to use the STREAMING update strategy by setting the UPDATE_STRATEGY property:

Update Strategy - Streaming

UPDATE_STRATEGY=STREAMING

Read-Only Mode

Edge Agents can also be run in read-only mode. An Edge Agent running in read-only mode can serve check requests from its configured datastore but will not fetch updates or otherwise perform any modifications to the datastore. This makes it possible to run a cluster of Edge Agents in which one of the agents is responsible for keeping the local datastore up-to-date and the others are able to serve check requests.

Configure the Edge Agent to run in read-only mode using the READ_ONLY property:

Read-Only Mode

READ_ONLY=true

Properties Reference

---

API_KEY

Your Warrant API key.

---

READ_ONLY, optional

If true runs the Edge Agent in read-only mode. Defaults to false.

---

DATASTORE, optional

The type of datastore the agent should use. Defaults to memory.

---

UPDATE_STRATEGY, optional

The update strategy the Edge Agent should use. Can be either POLLING or STREAMING. Defaults to POLLING.

---

POLLING_FREQUENCY, optional

The frequency (in seconds) at which the Edge Agent should poll the Warrant API to fetch updates. Defaults to 10. Must be greater than or equal to 10.

---

REDIS_HOSTNAME, required if DATASTORE is redis

The IP address or host name of the Redis cluster.

---

REDIS_PORT, optional

The port on which Redis is listening. Defaults to 6379.

---

REDIS_PASSWORD, optional

The password to use when connecting to the Redis cluster.

---

REDIS_DATABASE, optional

The database number to use in the configured Redis cluster. Must be a value from 0 to 15.

---