Report API

Report API can be used to retrieve reports about events related to DNS filtering from Elastic/Opensearch.

Configuration Reference

Instance Sets

Instances of Report API can be defined under the root node reportAPIs. 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

reportAPIs:
  myreportapi:
    < Report API configuration >

In a minimal configuration you will need to have at least the elasticsearch backend configured:

reportAPIs:
  myreportapi:
    elasticsearch:
      addr: https://elasticsearch.example.local:9200/
      index: "myreports-*"

Above configuration will ensure Report API is able to pull the desired reports out of the backend where other dstore components have stored them.

Parameters which can be used to configure Report API 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
`disableSticky`	`boolean`	`false`	If `true`, disable the operator-controlled selection of a primary pod to handle all inbound traffic
`elasticsearch`	Elastic Search	`{}`	Configuration of Elastic / Opensearch backend
`hostNetwork`	`boolean`	`false`	Use host networking for pods
`ingress`	`k8s:`IngressSpec	`{}`	Ingress configuration
`logLevel`	`string`	`"info"`	Level of logging. Available options: `"debug"` `"info"` `"warn"` `"error"`
`nodeSelector`	`k8s:`NodeSelector	`{}`	Kubernetes pod nodeSelector
`oauthBackend`	`string`		Name of a `userBackend` with type `oauth2` (See: User Backends)
`oauthRequiredScopes`	List of `string`	`[]`	If specified, which scopes must be attached to a user for authorization
`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 Event Forwarder should be calculated in seconds
`replicas`	`integer`	`2`	Default number of replicas in a Deployment
`resources`	`k8s:`Resources	`limits: cpu: 250m memory: 256Mi`	Resources allocated to the event forwarder container if `resourceDefaults` (global) is `true`
`service`	Service	`type: ClusterIP`	Service configuration
`serviceLabels`	`k8s:`Labels	`{}`	Labels to be added to each service
`tls`	Inbound TLS	`enabled: false`	TLS configuration for inbound traffic
`tolerations`	List of `k8s:`Tolerations	`[]`	Kubernetes pod Tolerations
`topologySpreadConstraints`	List of `k8s:`TopologySpreadConstraint	`[]`	Kubernetes pod topology spread constraints

Elastic Search

Configuration of the Elastic / Opensearch backend, for example:

reportAPIs:
  myreportapi:
    elasticsearch:
      addr: https://elasticsearch.example.local:9200/
      index: "myreports-*"

Parameter	Type	Required	Default	Description
`addr`	`string`	`yes`		Base URL of Elastic instance
`api_key`	`string`			Alternative auth method
`cloud_id`	`string`			Alternative auth method
`credentialsSecretName`	`string`			Name of a pre-existing Kubernetes Secret containing a username & password for authentication with Elastic
`credentialsSecretPasswordKey`	`string`		`"username"`	If `credentialsSecretName` is specified: name of the item inside the Secret which holds the username
`credentialsSecretUsernameKey`	`string`		`"password"`	If `credentialsSecretName` is specified: name of the item inside the Secret which holds the password
`index`	`string`	`yes`	`""`	Pattern of the elasticsearch index to retrieve events from, e.g. `myreports-*`
`password`	`string`			Password to use for authentication
`readiness_interval`	`go:`DurationString			How often to check the Elasticsearch connection for readiness
`startup_retries`	`integer`		`100`	On startup, how many times to retry connecting to Elasticsearch
`tlsconfig`	Elastic TLS			TLS configuration for connection towards Elastic / Opensearch
`user`	`string`			Username to use for authentication
`wait_interval`	`go:`DurationString		`500ms`	On startup, how long to wait for an Elasticsearch connection to succeed before giving up

Elastic Search TLS Config

Parameters to configure TLS options, these should be child attributes of the tlsconfig node. For example:

reportAPIs:
  myreportapi:
    elasticsearch:
      addr: https://elasticsearch.example.local:9200/
      index: "myreports-*"
      tlsconfig:
        insecure_skip_verify: true

Parameter	Type	Default	Description
`ca`	`string`		CA in PEM format to use for validation
`caSecretName`	`string`		Name of a pre-existing Kubernetes Secret with a data item named `ca.crt` containing the CA in PEM format to use for validation
`insecure_skip_verify`	`boolean`	`false`	Skip validation of the storage backend's certificate chain and hostname

Inbound TLS

Parameters to configure TLS for inbound traffic. An example:

reportAPIs:
  myreportapi:
    tls:
      enabled: true
      certSecretName: my-reportapi-certificate

In the above example the certificate present in Secret my-reportapi-certificate will be attempted to be used to start a TLS-enabled listener.

Parameter	Type	Default	Description
`certSecretName`	`string`		Name of a Secret object containing a certificate (must contain the `tls.key`, `tls.crt` items)
`certManager`	`boolean`	`false`	Toggle to have a request created for Certmanager to provision a certificate. By default, this will request for a Certificate covering the following: - `reportapi-[Name of instance set]` - `reportapi-[Name of instance set].[Namespace]` - `reportapi-[Name of instance set].[Namespace].svc` Additional entries can be configured using `extraDNSNames`
`enabled`	`boolean`	`false`	Toggle to enable TLS If set to `true`, a `certSecretName` must be set or `certManager` must be set to `true` to ensure a valid certificate is available
`extraDNSNames`	List of `string`	`[]`	List of additional entries to be added to the Certificate requested from Certmanager
`issuerGroup`	`string`	`"cert-manager.io"`	Group to which issuer specified under `issuerKind` belongs Default value is inherited from the global `certManager` configuration
`issuerKind`	`string`	`"ClusterIssuer"`	Type of Certmanager issuer to request a Certificate from Default value is inherited from the global `certManager` configuration
`issuerName`	`string`	`""`	Name of the issuer from which to request a Certificate Default value is inherited from the global `certManager` configuration
`certSpecExtra`	CertificateSpec	`{}`	Extra configuration to be injected into the Certmanager Certificate object's `spec` field. Disallowed options: `"secretName"` `"commonName"` `"dnsNames"` `"issuerRef"` (These are configured automatically and/or via other options)
`certLabels`	`k8s:`Labels	`{}`	Extra labels for the Certmanager Certificate object
`certAnnotations`	`k8s:`Annotations	`{}`	Extra annotations for the Certmanager Certificate object

Service Configuration

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

reportAPIs:
  myreportapi:
    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
`ipv4`	`boolean`	`false`	If true, force the Service to include support for IPv4, ignoring globally configured IP Family settings and/or cluster defaults. If `ipv4` is set to `true` and `ipv6` remains `false`, the result will be an `ipv4`-only SingleStack Service. If both are `false`, global settings and/or cluster defaults are used. If both are `true`, a PreferDualStack Service is created
`ipv6`	`boolean`	`false`	If true, force the Service to include support for IPv6, ignoring globally configured IP Family settings and/or cluster defaults. If `ipv6` is set to `true` and `ipv4` remains `false`, the result will be an `ipv6`-only SingleStack Service. If both are `false`, global settings and/or cluster defaults are used. If both are `true`, a PreferDualStack Service is created
`labels`	`k8s:`Labels	`{}`	Labels to be added to the service
`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"`