Configuring the Agent

A C19 agent has 3 parts (layers): agent, state and connection.

We will go into details about each layer in the Architecture chapter, but for now all you need to know is that the agent layer is responsible for communicating with your app, the connection layer is responsible for communicating with other C19 agents and the state layer is responsible for holding your data.

A C19 configuration file is a YAML formatted file. Let's prepare ours:

version: 0.1
spec:
  agent:
    kind: Default
    port: 3097
  state:
    kind: Default
    ttl: null
    purge_interval: 60000
  connection:
    kind: Default
    port: 4097
    push_interval: 1000
    pull_interval: 60000
    r0: 3
    timeout: 1000
    peer_provider:
      kind: K8s
      selector:
        c19: getting-started
      namespace: default

As you can see, we have our 3 layer configurations: agent, state and connection. Every section starts with the kind configuration which tells C19 which kind of agent/state/connection to load. As you will learn, there can be different types of layer implementations, each would suit different needs.

Agent

kind - We will use the "Default" agent layer. For now, it's enough for you to know that the "Default" agent provides a HTTP server which accepts a JSON formatted calls for getting and setting values to the state.

port - The port to use for the agent HTTP server. The default value, if unspecified, is 3097.

State

kind - Same as the Agent, we will use the "Default" state implementation. The "Default" state implementation provides a key-value store with an option to set a TTL for each key.

ttl - The TTL to use (in milliseconds). If left out there will be no default TTL set for keys. In any case, as you will learn, you can always set a TTL for a key when setting a value to the state. Default value is no ttl.

purge_interval - The Default state will always filter out expired keys, but will still hold them in memory until purged. This setting controls the interval (in milliseconds) in which expired keys will be purged. Default value is 1 minute.

Connection

kind - We will use the "Default" connection layer implementation. The "Default" connection uses HTTP to exchange the state with other C19 peers. It randomly chooses peers to connect to and exchanges the state at a specified interval.

port - The port to use when connecting to other peers and allowing other peers to connect to this C19 agent. Default port is 4097.

push_interval - Controls the interval (in milliseconds) in which the connection layer will connect and push the state to a random set of C19 peers. Default value is 1 second. Setting this value higher will speed up propagation of the state in the system, but would come at the expense of CPU usage.

pull_interval - Controls the interval (in milliseconds) in which the connection layer will connect and pull the state from a random set of C19 peers. Default value is 60 seconds. The connection layer will specify its own state version when pulling the state from other peers. If the state versions match then no state will be exchanged. This is to optimize redundant state exchanges. If the versions do not match then the full state will be returned by the connected peer.

r0: Controls how many peers should this connection layer connect to at each publish interval. Setting this value higher will speed up propagation of the state in the system, but would come at the expense of network load. (connecting to more peers). Default value is 3.

timeout - Controls the connection timeout (in milliseconds) when exchanging state with each peer. Default value is 1 second.

peer_provider - At each publish_interval, the connection layer will query the peer provider for a full list of available peers to choose from. There are different types of peer providers. For example: Kubernetes peer provider that queries for pod endpoints based on a label selector and a static peer provider which allows specifying a predefined list of peer endpoints. Since we will be deploying to a Kubernetes cluster we will be using the K8s peer provider.

K8s Peer Provider

kind - Controls the type of peer provider to use. Default value is K8s

selector - Sets the Kubernetes pod label selector which will form a C19 group. Default value is none which means all pods will be used for the same C19 group. This option allows you to have many different C19 groups. Each group will have its own isolated state shared.

namespace - The Kubernetes namespace to use. Defaults to the default namespace. Can also be set to :all (mind the :) to specify that all namespaces should be used.

Applying the Configuration

You specify the configuration file to use when running a C19 agent by using the --config <filename> flag.