Filtering

The Controlplane can be deployed with a Dynamic Filtering blueprint, enabling you to use the dynamic filtering features described in the Filtering overview.

Configuration Reference

Before you start configuring the Dynamic Filtering blueprint, it is highly recommended that you familiarize yourself with Dynamic Filtering.

The most basic form of the Dynamic Filtering blueprint can be deployed by setting enabled to true inside the dynamic node. It's also helpful to make sure the deployment is identified by a unique name, which the NATS mesh can use to uniquely identify each NATS cluster in the mesh.

name: controlplane_dynamicfilter

dynamic:
  enabled: true

Parameters which you can use to further configure the Dynamic Filtering blueprint:

Parameter	Type	Default	Description
`enabled`	`boolean`	`false`	If `true`, enable dynamic filtering blueprint
`admin`	Admin		Configuration of the Admin component (including the GUI & API)
`deviceRegister`	Device Register		Configuration of Device Register in `consumer` mode
`ipmapper`	IP Mapper		Configuration of IP Mapper, if Radius Listener is enabled in the Controlplane scope
`postgres`	Postgres Configuration		Configuration of the Postgres database
`radiusListener`	Radius Listener		Configuration of Radius Listener to consume RADIUS messages in the Controlplane scope
`redis`	Redis Configuration		Configuration of the Redis read-write cluster from which Userplanes will replicate

Admin

The Admin plays a central role in a Dynamic Filtering blueprint. Offering both a GUI and API, it allows you to control & analyze many aspects of the dynamic filtering deployment across all Userplanes connected to this Controlplane.

To configure the Admin, you can use the following example:

name: controlplane_dynamicfilter

dynamic:
  enabled: true

  admin:
    tls:
      enabled: true
      certSecretName: my-admin-certificate

    serviceHTTPS:
      type: LoadBalancer
      annotations:
        metallb.universe.tf/address-pool: name_of_pool

    tokens:
      - name: "token1"
      - name: "token2"

In the above example, you will have a Service named dynamic-admin-https for which a LoadBalancer will be provisioned and it will have TLS enabled using the certificate stored in Secret my-admin-certificate. To interact with the API you will have 2 tokens available named: token1 and token2. The actual values you can use as X-API-Key header when interacting with the Admin API will be stored in Secrets named after those tokens.

The full list of parameters which you can use to configure the Admin:

Parameter	Type	Default	Description
`adminSecretName`	`string`	`""`	Name of a pre-provisioned Secret containing the password for the `admin` user which has Administrative privileges in the Admin GUI. If this is not supplied a random password is generated for the `admin` user
`adminSecretPasswordKey`	`string`	`"admin_password"`	Name of the item in the Secret specified by `adminSecretName` which contains the desired password of the `admin` user
`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"`
`bootstrap`	`dictionary`	`enabled: true`	If `enabled` is set to `false`, disable bootstrapping the Admin deployment with the default filtering policies, fixtures, etc.
`categoryOverridesFeed`	HTTP API Feed	`{}`	Configuration of the `Category Overrides` HTTP API Downloader feed which is automatically provisioned along with the Dynamic Filtering blueprint. Note: You cannot modify the `upstream` parameter as it is automatically set by Cloud Control
`containerSecurityContext`	`k8s:`SecurityContext	`allowPrivilegeEscalation: false readOnlyRootFilesystem: true seccompProfile: type: RuntimeDefault capabilities: drop: - "ALL"`	SecurityContext applied to each container
`csrfOrigins`	List of `string`	`[]`	If you wish to have traffic to the Admin checked against the `Origin` header for CSRF protection, provide a list of Origins which should be allowed. Note: Each origin should include both the protocol and the port
`domainListsFeed`	HTTP API Feed	`{}`	Configuration of the `Domain Lists` HTTP API Downloader feed which is automatically provisioned along with the Dynamic Filtering blueprint. Note: You cannot modify the `upstream` parameter as it is automatically set by Cloud Control
`hostNetwork`	`boolean`	`false`	Use host networking for pods
`ingress`	`k8s:`IngressSpec	`{}`	Ingress configuration
`nodeSelector`	`k8s:`NodeSelector	`{}`	Kubernetes pod nodeSelector
`oauthBackend`	`string`		Name of a `userBackend` with type `oauth2` (See: User Backends)
`oauthScopes`	List of `string`	`[]`	Scopes which must be available to the users who wish to interact with the API if `oauthBackend` is configured
`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 Admin should be calculated in seconds
`replicas`	`integer`	`2`	Default number of replicas in a Deployment
`resources`	`k8s:`Resources	`limits: cpu: 500m memory: 512Mi`	Resources allocated to the admin container if `resourceDefaults` (global) is `true`
`service`	Service	`type: ClusterIP`	Service configuration
`serviceHTTPS`	Service	`type: ClusterIP`	HTTPS Service configuration Note: Only created when `tls.enabled = true`
`serviceLabels`	`k8s:`Labels	`{}`	Labels to be added to each service
`tls`	Inbound TLS	`enabled: false`	TLS configuration for inbound HTTPS traffic
`tokens`	List of Token	`[]`	Tokens to be provisioned on Admin for API access
`tolerations`	List of `k8s:`Tolerations	`[]`	Kubernetes pod Tolerations
`topologySpreadConstraints`	List of `k8s:`TopologySpreadConstraint	`[]`	Kubernetes pod topology spread constraints

Tokens

You can configure Admin to deploy with tokens available to use when communicating with the Admin API. Configuring tokens look as follows:

dynamic:
  enabled: true

  admin:
    tokens:
      - name: "token1"
        friendlyName: "The first token"
      - name: "token2"

In the above example, you will end up with 2 API tokens, named token1 and token2. token1 will have a friendly name displayed in the Admin GUI as The first token. The value you can use as X-API-Key header in your API calls will be stored in a Secret named `dynamic-admin-token-[Token Name].

The full list of configuration options for tokens:

Parameter	Type	Required	Default	Description
`friendlyName`	`string`			Friendly name of the token displayed in the Admin GUI
`name`	`string`	`yes`		Name of the token

Inbound TLS

Parameters to configure TLS for inbound traffic. When enabled is set to true and a certificate source is configured, an additional Service with the name suffix -https will be created. An example:

dynamic:
  enabled: true

  admin:
    tls:
      enabled: true
      certSecretName: my-admin-certificate

In the above example the certificate present in Secret my-admin-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: - `dynamic-admin-https` - `dynamic-admin-https.[Namespace]` - `dynamic-admin-https.[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:

dynamic:
  enabled: true

  admin:
    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"`