Cloud Control API

Cloud Control API can be used to inspect Userplane deployments and perform management activities. Currently supported functionality of the API:

State inspection: Detailed insight into all instance sets and corresponding deployments & pods
Cache management: Perform controlled flushing of cache of multiple products

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

To enable the default deployment of the API, you can use the following in your Userplane 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
A statefulset named nats which runs NATS and serves as the communication channel between the API and the agents in each component's pod.

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

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

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

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