Controlplane

Controlplane allows for the deployment of components which facilitate management and control of Userplane deployments. It also allows for the centralization of components which are not necessary to deploy in each userplane.

Components

Currently, the Controlplane allows for the deployment of components which aid in the following areas:

Reporting: Gain insight into DNS traffic and generate reports
Security: DNS traffic filtering

Installation

Installation of the Controlplane can be done via a single Helm Chart named controlplane. The full path to the Helm Chart is as follows:

controlplane: oci://registry.open-xchange.com/cloudcontrol/controlplane

Before using the Helm Chart, make sure your helm is authenticated against the OX registry:

helm registry login registry.open-xchange.com --username=<REGISTRY_USERNAME> --password=<REGISTRY_PASSWORD>

You can then either install directly from the OX registry:

helm install <RELEASE> --namespace=<NAMESPACE> oci://registry.open-xchange.com/cloudcontrol/controlplane --version <VERSION>

Or you can download the Helm Chart for offline usage:

helm pull oci://registry.open-xchange.com/cloudcontrol/controlplane --version <VERSION>

This should result in a file named controlplane-<VERSION>.tgz which you can use to install from:

helm install <RELEASE> --namespace=<NAMESPACE> controlplane-<VERSION>.tgz

Since Cloud Control Helm Charts are modular and highly configurable, you need to define and configure the components which you would like to deploy. The definition and configuration should be passed into the helm install command via the --values argument. To install directly from the OX registry with a YAML file named myenvironment.yaml you can use this command:

helm install <RELEASE> --namespace=<NAMESPACE> oci://registry.open-xchange.com/cloudcontrol/controlplane --version <VERSION> --values=myenvironment.yaml

Configuration Reference

Controlplane uses the same concepts as Userplane to define and configure components. To deploy a component, it must be defined by providing a key-value pair under the proper root node. For example to configure a set of instances of dstoredist and commandsource:

dstoredists:
  mydstoredist:
    < dstoredist configuration >

commandSources:
  mycmdsource:
    < commandsource configuration >

You can also use this format to define multiple sets of instances of the same component, for example:

commandSources:
  mycmdsource:
    < commandsource configuration >
  anothercmdsource:
    < commandsource configuration >

Parameters which can be used to configure Controlplane are shown in the below table.

Parameter	Type	Default	Description
`commandSources`	Map of commandSource	`{}`	Command Source instance sets
`containerSecurityContext`	`k8s:`SecurityContext		SecurityContext applied to all containers. Default: Specified on the component level. See configuration reference for the corresponding component to see the defaults.
`dstoredists`	Map of dstoredist	`{}`	dstoredist instance sets
`dynamic`	DynamicFiltering	`{}`	Dynamic filtering configuration
`global`	Global		Configuration options for important global usage within the Cloud Control Helm Charts
`name`	`string`		Name of the deployment, primarily used when part of a NATS mesh. Should be a string without spaces or special characters and unique amongst all deployments part of a NATS mesh. If not provided this defaults to the name of the Namespace in which it is deployed
`podAnnotations`	`k8s:`Annotations	`{}`	Annotations to be added to all pods. `podAnnotations` explicitly configured on an instance set takes precedence over this
`podDisruptionBudget`	`k8s:`PodDisruptionBudgetSpec	`{}`	Spec of PodDisruptionBudget to be applied to all deployments. `podDisruptionBudget` explicitly configured on an instance set takes precedence over this
`podLabels`	`k8s:`Labels	`{}`	Labels to be added to all pods. `podLabels` explicitly configured on an instance set takes precedence over this
`podPreemptionPolicy`	`string`		Policy for preempting pods with lower priority. `podPreemptionPolicy` explicitly configured on an instance set takes precedence over this
`podPriorityClassName`	`string`		Name of PriorityClass to be assigned to all pods. `podPriorityClassName` explicitly configured on an instance set takes precedence over this
`podRuntimeClassName`	`string`		Name of RuntimeClass to be assigned to all pods. `podRuntimeClassName` explicitly configured on an instance set takes precedence over this
`podSchedulerName`	`string`		Name of scheduler responsible for dispatching pods. `podSchedulerName` explicitly configured on an instance set takes precedence over this
`podSecurityContext`	`k8s:`PodSecurityContext		SecurityContext to be applied to all pods. `podSecurityContext` explicitly configured on an instance set takes precedence over this. Default: Specified on the component level
`podTerminationGracePeriodSeconds`	`integer`		Duration after which terminating pods are stopped immediately if they do not exit gracefully. `podTerminationGracePeriodSeconds` explicitly configured on an instance set takes precedence over this
`prometheus`	Prometheus		Configuration options for automatic Prometheus scraping if the Prometheus Operator is available
`resourceDefaults`	`boolean`	`false`	If true, apply default resource limits to each container
`serviceLabels`	`k8s:`Labels	`{}`	Labels to be added to all services
`tolerations`	List of `k8s:`Tolerations		Tolerations to be applied to all pods
`topns`	Map of topn	`{}`	TopN Reporter instance sets
`userBackends`	Map of UserBackend		Configuration options for user backends

Global

Global options for this Helm Chart allow for the configuration of:

Image pull secrets to configure access to the OX registry or a private cache/intermediary
Compatibility mode for supported non-standard Kubernetes platforms

Example of using global to configure a private registry where you stored copies of the Cloud Control container images:

global:
  image:
    registry: "myregistry.local:8085"
    repository: "myrepository"

Or to configure Cloud Control to use a pre-existing Secret containing your registry credentials named my-registry-credentials:

global:
  imagePullSecretsList:
    - my-registry-credentials

Parameters which can be used:

Parameter	Type	Default	Description
`image`	ImageOverrides	`{}`	Overrides to configure where container images are pulled from. Default: The OX registry
`imagePullSecrets`	Map of ImagePullSecret	`{}`	Image pull secrets for which Secrets should be created and then used by the service accounts to pull container images from the registry. Recommendation: pre-provision the actual Secrets in your namespace and reference them using `imagePullSecretsList`
`imagePullSecretsList`	List of `string`	`[]`	List of names of Secrets which should be used by service accounts to pull container images from the registry
`openshift`	OpenShift	`{}`	Configuration of OpenSHift compatibility mode. Default: disabled

Image Overrides

You can configure the Helm Chart to ensure Kubernetes pulls container images from a different location than the OX registry. For example:

global:
  image:
    registry: "myregistry.local:8085"
    repository: "myrepository"

Parameters which can be used:

Parameter	Type	Default	Description
`registry`	`string`	`registry.open-xchange.com`	Override the base hostname of the URI from where container images are pulled
`repository`	`string`		Override the repository from which the container images are pulled. Default: Varies based on the type of component
`pullPolicy`	`string`	`"IfNotPresent"`	Force an image pull policy for all containers

Image Pull Secret

You can configure the Helm Chart to create Secrets for one or more sets of credentials to use to authenticate against a registry. Each entry should be a key-value pair, with:

key: Name of the secret
value: Dictionary holding the configuration of the secret

For example, to have an image pull secret with the name myIPSSecret to authenticate against the OX registry:

global:
  imagePullSecrets:
    myIPSSecret:
      registry: registry.open-xchange.com
      username: <USERNAME>
      password: <PASSWORD>
      email: admin@example.com

Parameters which can be used:

Parameter	Type	Required	Description
`registry`	`string`	`yes`	Base URI of the registry
`username`	`string`	`yes`	Username to authenticate with
`password`	`string`	`yes`	Password for authentication
`email`	`string`	`yes`	Email address to satisfy Kubernetes requirements for an image pull secrets in the desired format. Can contain dummy data as long as it satisfies the standard format of an email address

OpenShift

OpenShift requires some specific default settings in Cloud Control to be adjusted to satisfy the platform's requirements. You can configure this Helm Chart to deploy in OpenShift compatibility mode using the following example:

global:
  openshift:
    enabled: true

Argo CD

Cloud Control Helm Charts can be configured to create artifacts fully compatible with Argo CD. You can configure this Helm Chart to deploy in Argo CD compatibility mode using the following example:

global:
  argocd:
    enabled: true

Prometheus

If you have the Prometheus Operator installed (either yourself or via the Monitoring Helm Chart), you can enable Cloud Control to automatically deploy the necessary PodMonitor objects to automate metric scraping. You can configure this Helm Chart to deploy the PodMonitor objects using the following example:

prometheus:
  operator:
    available: true

You can also influence the labels of the generated metrics via the following options:

Parameter	Type	Default	Description
`environment`	`string`		If set, this value will be added to each metric in a label named `environment`. This optional label can be used on the bundled Grafana dashboards to distinguish between different classes of environment, such as `production` or `acceptance`.
`relabelings`	List of RelabelConfig	`[]`	Relabeling configuration for all metrics, only applicable if these metrics are scraped by a Prometheus Operator.
`service`	`string`		If set, this value will be added to each metric in a label named `service`. This optional label can be used on the bundled Grafana dashboards to allow selecting metrics based on the functional usage of this environment.
`site`	`string`		If set, this value will be added to each metric in a label named `site`. This optional label can be used on the bundled Grafana dashboards to distinguish between different locations if data is aggregated/federated from multiple Prometheus instances into a centralized instance.

For example, you could configure these as follows:

prometheus:
  site: "eu-central-1"
  environment: "acceptance"
  service: "Recursive DNS"

  relabelings:
    - action: replace
      replacement: somevalue
      targetLabel: mylabel

  operator:
    available: true

This will result in metrics being generated with the following labels:

site: eu-central-1
environment: acceptance
service: Recursive DNS

And if the Prometheus Operator is used to discover & scrape these metrics, Prometheus will be instructed to ensure the following extra label is present after scraping:

mylabel: somevalue