Command Source

Command Source is a feed generator which executes a custom script at set intervals and exposes the resulting feed over HTTP.

The main functionality is captured in the below diagram:

Image title — Overview of Command Source

In the diagram you can see the main 2 components:

commandsource container is responsible for running the script and storing the resulting feed in the "feed storage"
webserver container is responsible for exposing the feed stored in "feed storage"

Script

Requirements

For Command Source to be able to interpret the output of the script as data for a feed, the script must produce the following:

Feed codes file (JSON)
Feed snapshot file (TSV)
Metadata (JSON)

Feed codes file

The feed codes file is commonly referred to as feed-codes.json. In this file the categories are defined and assigned a code (an ID which we can use in filtering rules). Example of the contents of this file:

{
  "v": 1,
  "codes": [
    {"code": 1, "title": "documentation"},
    {"code": 2, "title": "examples"},
    {"code": 3, "title": "netherlands"},
  ]
}

The above example feed-codes.json defines numerical codes for 3 categories. This includes a documentation category, with code 1.

The format to which this file has to adhere is as follows:

# (Required) Internal version field, currently must be set to 1
v: integer

# (Optional) Indicates if a codename should be used instead of the numeric code.
# This defaults to false, which is recommended for most feeds.
# Do not turn this on unless you fully understand the implications.
named_codes: boolean

# (Required) A list of objects describing each code
codes: list of code objects

Where "code objects" must adhere to:

# (Required) The code-number of this category (1-65535).
# Classification codes do not have to be consecutive.
code: uint16

# (Required) The title for this category (should be concise)
title: string

# (Optional) Description for this code (can be verbose)
desc: string

# (Optional) String name to be used for code when named_codes is set
codename: string

Feed snapshot file

The feed snapshot file is a tab-separated file which contains the DomainPaths and which categories they should belong to. Example of the contents of this file (note: The \t characters represent a tab since this is a tab-separated file):

doc.powerdns.com\t1
example.com\t2
example.co.uk\t2
example.net\t2
example.nl\t2,3

The above (combined with the previous chapter's feed codes example) ends up with the following DomainPath to Category mapping:

Category Code	Category Title	DomainPaths
`1`	`documentation`	`doc.powerdns.com`
`2`	`examples`	`example.com` `example.co.uk` `example.net` `example.nl`
`3`	`netherlands`	`example.nl`

Notes about this file format:

Empty lines are allowed
Lines starting with a # can be used for comments
The same DomainPath is allowed to appear multiple times. All the codes discovered this way are combined and appear in the generated feed

Metadata JSON

When the Feed codes & snapshot files have been generated, the Command Source engine needs to be informed about it so they can be processed before they are served by the webserver. Minimalistic example of the contents of this metadata:

{
  "v": 1,
  "codes_file": "/tmp/feed-codes.json",
  "csv_file": "/tmp/feed-snapshot.tsv",
}

The format to which this metadata has to adhere is as follows:

# (Required) Internal version field, currently must be set to 1
v: integer

# (Required) Path to the feed codes file (JSON)
codes_file: string

# (Required) Path to the feed snapshot file (TSV)
# Required
csv_file: string

# (Optional) Version field which can be used by Command Source to quickly determine whether
# a generated set of data needs to lead to the feed being rebuilt. A script can 
# access the `OXFEED_LAST_VERSION` environment variable to see the version 
# returned by the previous iteration of the script execution.
# This can potentially be used to create logic to prevent attempting to generate large feeds
# more often than necessary. For example, when loading feed codes and snapshots from a database
# you could use this to check whether or not the contents of the database have changed and
# hence require generating an updated feed
version: string

Command Source response

When the Feed codes & snapshot files are ready and the metadata has been constructed, Command Source needs to be informed. This is done by having the script output a line of text to the stdout in a specific format. This line should be as follows:

OXFEED_GENERATOR_RESULT: <Metadata JSON>

Using our example from the previous chapters, we should output this:

OXFEED_GENERATOR_RESULT: {"v": 1, "codes_file": "/tmp/feed-codes.json", "csv_file": "/tmp/feed-snapshot.tsv"}

Note: This must be one line and will only be read if the script exits with code 0

Execution Environment

Currently Command Source provides support for the following script execution engines:

Python 3
Shell script (sh)

Scripts executed by Command Source have access to the following:

All files contained within the Configmap referenced by scriptConfigMap can be accessed by the script inside the directory stored in environment variable named CC_SCRIPT_DIR (/script)
All items inside the secret referenced by scriptSecretName can be accessed by the script inside the directory stored in environment variable named CC_SECRETS_DIR (/script_secrets)
A writable local volume is accessible by the script, the path of which is stored in environment variable named CC_TEMP_DIR (/tmp)

Script Example

Below is an example Python3 script which will generate the feed used in the above chapters:

import json, tempfile

# Write feed codes JSON file
codes = {
  "v": 1,
  "codes": [
    {"code": 1, "title": "documentation"},
    {"code": 2, "title": "examples"},
    {"code": 3, "title": "netherlands"},
  ]
}

_, codes_path = tempfile.mkstemp()
with open(codes_path, 'w') as f:
  json.dump(codes, f)

# Write feed snapshot TSV file
_, snapshot_path = tempfile.mkstemp()
with open(snapshot_path, 'w') as f:
  print("doc.powerdns.com\t1", file=f)
  print("example.com\t2", file=f)
  print("example.co.uk\t2", file=f)
  print("example.net\t2", file=f)
  print("example.nl\t2,3", file=f)

# Construct metadata JSON
result = {
  "v": 1,
  "csv_file": snapshot_path,
  "codes_file": codes_path,
}

# Output for Command Source to be informed of updated feed
print("OXFEED_GENERATOR_RESULT: {}".format(json.dumps(result)))

To make the above script available, we need to deploy it in a ConfigMap. This could look as follows:

apiVersion: v1
kind: ConfigMap
metadata:
  name: my-cmdsource-configmap
data:
  script.py: |
    import json, tempfile

    # Write feed codes JSON file
    codes = {
      "v": 1,
      "codes": [
        {"code": 1, "title": "documentation"},
        {"code": 2, "title": "examples"},
        {"code": 3, "title": "netherlands"},
      ]
    }

    _, codes_path = tempfile.mkstemp()
    with open(codes_path, 'w') as f:
      json.dump(codes, f)

    # Write feed snapshot TSV file
    _, snapshot_path = tempfile.mkstemp()
    with open(snapshot_path, 'w') as f:
      print("doc.powerdns.com\t1", file=f)
      print("example.com\t2", file=f)
      print("example.co.uk\t2", file=f)
      print("example.net\t2", file=f)
      print("example.nl\t2,3", file=f)

    # Construct metadata JSON
    result = {
      "v": 1,
      "csv_file": snapshot_path,
      "codes_file": codes_path,
    }

    # Output for Command Source to be informed of updated feed
    print("OXFEED_GENERATOR_RESULT: {}".format(json.dumps(result)))

We can now use the above ConfigMap in our Controlplane deployment:

commandSources:
  mycmdsource:
    scriptConfigMap: my-cmdsource-configmap
    scriptName: script.py

Configuration Reference

Instance Sets

Instances of Command Source can be defined under the root node commandSources. Each instance set should be a key-value pair, with:

key: Name of the instance set
value: Dictionary holding the configuration of the instance set

commandSources:
  mycmdsource:
    < Command Source configuration >

In a minimal configuration you will need to specify at least the name of a configmap holding a script and the name of the script which should be run.

For example:

commandSources:
  mycmdsource:
    scriptConfigMap: my-script-configmap
    scriptName: myscript.py

In the above example Command Source will mount the my-script-configmap to a local volume and attempt to run the myscript.py script using Python3 each iteration.

It can also be helpful to have more control over the frequency at which the script is executed. You can do this as follows:

commandSources:
  mycmdsource:
    scriptConfigMap: my-script-configmap
    scriptName: myscript.py
    interval: 15s
    timeout: 2m

In the above example the script will be executed with 15 second intervals between executions. If an execution is not finished within 2 minutes it will be stopped.

Parameters which can be used to further configure Command Source instances for a specific instance set are shown in the below table.

Parameter	Type	Default	Description
`affinity`	`k8s:`Affinity		pod affinity (Kubernetes docs: Affinity and anti-affinity). If unset, a default anti-affinity is applied using `antiAffinityPreset` to spread pods across nodes
`agentLogLevel`	`string`	`"info"`	Verbosity of logging for the agent container. Available options: `"debug"` `"info"` `"warn"` `"error"`
`agentLogFormat`	`string`	`"text"`	Format of logging for the agent container. Available options: `"text"` `"json"`
`agentResources`	`k8s:`Resources	`limits: cpu: 250m memory: 256Mi`	Resources allocated to the agent container if `resourceDefaults` (global) is `true`
`antiAffinityPreset`	`string`	`"preferred"`	pod anti affinity preset. Available options: `"preferred"` `"required"`
`containerSecurityContext`	`k8s:`SecurityContext	`allowPrivilegeEscalation: false readOnlyRootFilesystem: true seccompProfile: type: RuntimeDefault capabilities: drop: - "ALL"`	SecurityContext applied to each container
`executor`	`string`	`"python3"`	Execution engine for script. Available options: `"python3"` `"sh"`
`hostNetwork`	`boolean`	`false`	Use host networking for pods
`ingress`	`k8s:`IngressSpec	`{}`	Ingress configuration
`interval`	`go:`DurationString	`60s`	Interval between script executions
`logFormat`	`string`	`"human"`	Format of logging. Available options: `"human"` `"json"`
`logLevel`	`string`	`"info"`	Level of logging. Available options: `"debug"` `"info"` `"warn"` `"error"`
`nodeSelector`	`k8s:`NodeSelector	`{}`	Kubernetes pod nodeSelector
`podAnnotations`	`k8s:`Annotations	`{}`	Annotations to be added to each pod
`podDisruptionBudget`	`k8s:`PodDisruptionBudgetSpec	`{}`	Spec of PodDisruptionBudget to be applied to deployment
`podLabels`	`k8s:`Labels	`{}`	Labels to be added to each pod
`podSecurityContext`	`k8s:`PodSecurityContext	`fsGroup: 953 runAsUser: 953 runAsGroup: 953 runAsNonRoot: true`	SecurityContext applied to each pod
`readyInterval`	`integer`	`5`	How often readiness of the Command Source should be calculated in seconds
`resources`	`k8s:`Resources	`limits: cpu: 1 memory: 2Gi`	Resources allocated to the commandsource container if `resourceDefaults` (global) is `true`
`scriptConfigMap`	`string`		Name of the configmap containing a script
`scriptName`	`string`		Name of the data item within `scriptConfigMap` which contains the script which should be executed
`scriptSecretName`	`string`		Name of a Secret which should be mounted to the commandsource container. Items stored in the Secret are available as files (name of item in secret = name of file) in the folder `/script_secrets`
`service`	Service	`type: ClusterIP`	Service configuration
`serviceLabels`	`k8s:`Labels	`{}`	Labels to be added to each service
`timeout`	`go:`DurationString	`10m`	Maximum duration of an execution. If it exceeds this duration the attempt will be stopped
`tolerations`	List of `k8s:`Tolerations	`[]`	Kubernetes pod Tolerations
`topologySpreadConstraints`	List of `k8s:`TopologySpreadConstraint	`[]`	Kubernetes pod topology spread constraints
`unreadyAfterNoSuccessPeriod`	`integer`	`0`	If Command Source has not successfully ran for this many seconds, mark the pod as Unready. Disabled if 0 (default)
`webserverResources`	`k8s:`Resources	`limits: cpu: 250m memory: 256Mi`	Resources allocated to the webserver container if `resourceDefaults` (global) is `true`
`webserverSecretName`	`string`		Name of a secret containing `username: base64_password` pairs to be granted access to the feed. `base64_password` should be the base64 encoded representation of the actual password
`webserverUsers`	List of `string`	`["csuser"]`	List of usernames for which a password should be generated and allowed access to the feed. By default a user named `csuser` will be created with a randomized password which can be obtained from the corresponding secret. Note: The generated passwords are stored in base64 encoded form in the secret. Make sure you decode them

Service Configuration

Parameters to configure the service object for this deployment. For example:

commandSources:
  mycmdsource:
    scriptConfigMap: my-script-configmap
    scriptName: myscript.py
    service:
      type: LoadBalancer
      annotations:
        metallb.universe.tf/address-pool: name_of_pool

Parameter	Type	Default	Description
`allocateLoadBalancerNodePorts`	`boolean`	`true`	If true, services with type `LoadBalancer` automatically assign NodePorts. Can be set to `false` if the LoadBalancer provider does not rely on NodePorts
`annotations`	`k8s:`Annotations	`{}`	Annotations for the service
`clusterIP`	`string`		Static cluster IP, must be in the cluster's range of cluster IPs and not in use. Randomly assigned when not specified.
`clusterIPs`	List of `string`		List of static cluster IPs, must be in the cluster's range of cluster IPs and not in use.
`externalIPs`	List of `string`		List of IP addresses for which nodes in the cluster will also accept traffic for this service. These IPs are not managed by Kubernetes and must be user-defined on the cluster's nodes
`externalTrafficPolicy`	`string`	`Cluster`	Can be set to `Local` to let nodes distribute traffic received on one of the externally-facing addresses (`NodePort` and `LoadBalancer`) solely to endpoints on the node itself
`healthCheckNodePort`	`integer`		For services with type `LoadBalancer` and externalTrafficPolicy `Local` you can configure this value to choose a static port for the NodePort which external systems (LoadBalancer provider mainly) can use to determine which node holds endpoints for this service
`internalTrafficPolicy`	`string`	`Cluster`	Can be set to `Local` to let nodes distribute traffic received on the `ClusterIP` solely to endpoints on the node itself
`loadBalancerIP`	`string`		Deprecated Kubernetes feature, available for backwards compatibility: IP address to attempt to claim for use by this LoadBalancer. Replaced by `annotations` specific to each LoadBalancer provider
`loadBalancerSourceRanges`	List of `string`		If supported by the LoadBalancer provider, restrict traffic to this LoadBalancer to these ranges
`loadBalancerClass`	`string`		Used to select a non-default type of LoadBalancer class to ensure the appropriate LoadBalancer provisioner attempt to manage this LoadBalancer service
`publishNotReadyAddresses`	`boolean`	`false`	Service is populated with endpoints regardless of readiness state
`sessionAffinity`	`string`	`None`	Can be set to `ClientIP` to attempt to maintain session affinity.
`sessionAffinityConfig`	`k8s:`SessionAffinityConfig	`{}`	Configuration of session affinity
`type`	`string`	`ClusterIP`	Type of service. Available options: `"ClusterIP"` `"LoadBalancer"` `"NodePort"`