Cloud Control API

Cloud Control API can be used to interact with both Userplane & Controlplane deployments and perform management activities. Currently supported functionality of the API:

Feature	Description	Userplane	Controlplane
State inspection	Insight into instance sets and corresponding deployments & pods	`yes`	`yes`
Cache management	Perform controlled flushing of cache of multiple products	`yes`
Database management	Perform backup & restore activities		`yes`

The features accessible via the API automatically adopt to the type of deployment it is a part of. When deployed as part of a Userplane you will see different API endpoints exposed compared to when it is deployed as part of a Controlplane deployment.

Enabling the API

To enable the default deployment of the API, you can use the following in your Userplane and/or Controlplane configuration:

api:
  enabled: true

This will result in the following:

A deployment cc-api which runs the API
A service cc-api to access the API
A secret cc-api containing 2 tokens:
- token_access: an API key which can use the API endpoints marked: "Requires Access privileges"
- token_full: an API Key which can use all API endpoints
Automatically enables NATS to be deployed into the same namespace, to facilitate the communication between Cloud Control API and all other deployed components

Note: As with any Kubernetes secret, the tokens are stored as base64 encoded strings. Make sure you decode them before usage.

Using the API

When deployed with a service and/or ingress configuration, you will be able to access a SwaggerUI at the following location: <service/ingress endpoint>/swagger/

The SwaggerUI serves as the primary source of documentation for the API and its functionality. Example of the SwaggerUI:

Image title — SwaggerUI for Cloud Control API in a Userplane deployment

The features available on the API depend on the deployment that it is part of. The features are currently grouped in 3 categories:

Generic: Features available in both Userplane & Controlplane deployments
Controlplane: Features only available in Controlplane deployments
Userplane: Features only available in Userplane deployments

Generic features

All API deployments offer the following functionality:

Jobs: Operations to inspect the status of asynchronous jobs started by other API operations
State: Operations to inspect the state of PowerDNS components deployed in the namespace
Troubleshooting: Operations which can help troubleshooting efforts

Controlplane features

Postgres: Operations to perform Backup & Restore actions
Dynamic Filtering: Operations to reset and resynchronize data stored in Redis from the Dynamic Filtering Postgres database

Userplane features

Cache Management: Operations to flush data from cache held by dnsdist, Recursor & Authoritative server

Configuration Reference

To configure the Cloud Control API, you can use the following parameters:

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
`antiAffinityPreset`	`string`	`"preferred"`	pod anti affinity preset. Available options: `"preferred"` `"required"`
`apiLogFormat`	`string`	`"text"`	Format of logging. Available options: `"text"` `"json"`
`apiLogLevel`	`string`	`"info"`	Level of logging. Available options: `"debug"` `"info"` `"warn"` `"error"`
`apiSecurityContext`	`k8s:`SecurityContext	`allowPrivilegeEscalation: false readOnlyRootFilesystem: true seccompProfile: type: RuntimeDefault capabilities: drop: - "ALL"`	SecurityContext applied to each container
`auth`	Authentication	`{}`	Configuration of authentication via a configured User Backend
`enabled`	`boolean`	`false`	If true, deploy Cloud Control API
`hostNetwork`	`boolean`	`false`	Use host networking for pods
`ingress`	Ingress	`type: ClusterIP`	Service configuration
`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
`replicas`	`integer`	`2`	Default number of replicas in the `cc-api` deployment
`resources`	`k8s:`Resources	`limits: cpu: 250m memory: 256Mi`	Resources allocated to the cc-api container if `resourceDefaults` (global) is `true`
`service`	Service	`type: ClusterIP`	Service configuration
`serviceLabels`	`k8s:`Labels	`{}`	Labels to be added to each service
`sessionsExpireAfter`	`go:`DurationString	`4h`	Time after which tokens expire. Only applies to tokens issued for users authenticated via a backend configured via the `auth` parameter
`tolerations`	List of `k8s:`Tolerations	`[]`	Kubernetes pod Tolerations
`topologySpreadConstraints`	List of `k8s:`TopologySpreadConstraint	`[]`	Kubernetes pod topology spread constraints

Authentication

If you have a User Backend configured, you can reference it to use it for authentication. For example:

userBackends:
  mybackend:
    <backend configuration>

api:
  enabled: true
  auth:
    backend: mybackend
    accessGroups:
      - group1
      - group2

Note: Cloud Control API currently only supports the LDAP user backend type

In the above example the Cloud Control API will authenticate users against the mybackend user backend. Once authenticated, users with membership of groups group1 or group2 are granted privileges to interact with the API endpoints marked: "Requires Access privileges"

Parameters available to further configure this:

Parameter	Type	Required	Default	Description
`accessUsers`	List of `string`		`[]`	List of IDs of users who are eligible for `access` privileges
`accessGroups`	List of `string`		`[]`	List of names of groups whose members are eligible for `access` privileges
`backend`	`string`	`yes`		Name of a defined `userBackend`
`fullUsers`	List of `string`		`[]`	List of IDs of users who are eligible for `full` privileges
`fullGroups`	List of `string`		`[]`	List of names of groups whose members are eligible for `full` privileges

Ingress

Parameters to configure an Ingress for Cloud Control API. For example:

api:
  enabled: true
  ingress:
    enabled: true
    ingressClassName: "nginx"
    hosts:
      - authapi.example.local

Parameter	Type	Default	Description
`annotations`	`k8s:`Annotations	`{}`	Annotations for the ingress
`enabled`	`boolean`	`false`	If true, create an ingress object
`hosts`	List of `string`	`[]`	List of hosts for which the ingress should accept traffic (If using `tls`, this should also include the `hosts` listed on the `tls` object)
`ingressClassName`	`string`		Name of the ingress class
`tls`	List of IngressTLS	`[]`	List of ingress tls configurations

Ingress TLS

Parameters to configure TLS for an ingress. For example:

api:
  ingress:
    enabled: true
    ingressClassName: "nginx"
    hosts:
      - ccapi.example.local
    tls:
      - secretName: ccapi-ingress-cert
        hosts:
        - ccapi.example.local

The above example will result in an ingress for Cloud Control API listening for ccapi.example.local and serving the certificate contained in the secret ccapi-ingress-cert.

Note: tls is a list of configurations. Below shows the parameters which can be used for each entry in that list:

Parameter	Type	Default	Description
`hosts`	List of `string`	`[]`	List of hosts for which the ingress should accept TLS traffic
`secretName`	`string`	`""`	Name of a secret containing the certificate to be used for this ingress

Service

Parameters to configure the service object for the Cloud Control API. For example:

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