Using KEDA autoscaler with groundcover

groundcover can be used as a Prometheus datasource for KEDA autoscaler. Any metric stored in groundcover can be queried and used to automatically make decisions about scaling your infrastructure.

In the following example we will be controlling the replica count of a Kubernetes deployment. This common example can be extended and used to query any type of metrics, and we suggest experimenting with it to fit your own use cases.

Prometheus Endpoint for KEDA

groundcover provides a Prometheus-compatible API endpoint that can be used with KEDA:

URL: https://app.groundcover.com/api/prometheus Authentication: Bearer token

groundcover exposes APIs to query data stored in the platform from outside the UI. For KEDA integration, we use the Prometheus-compatible API endpoint: https://app.groundcover.com/api/prometheus

API Key Setup

Querying the groundcover API requires setting up a dedicated API key for authentication. API keys provide secure, programmatic access to the API on behalf of a service account and inherit that account's permissions.

For detailed information about creating and managing API keys, see the API Keys documentation.

Key points:

Only Admins can create API keys
Keys are shown only once during creation - store them securely
API keys authenticate using Bearer token format
Keys inherit permissions from their parent service account

We will be referring to this API key below as api-key.

Setting up KEDA Authentication with groundcover

KEDA requires access to the api-key so it can add it to the Prometheus requests as a Bearer token. We will set up two Kubernetes objects for this purpose - a Secret object and a ClusterTriggerAuthentication object.

Defining the Secret Object

We will be using a simple static Secret object, but any type can be used, including external secrets. Make sure to replace the <api-key> placeholder with the API key previously created.

apiVersion: v1
kind: Secret 
metadata:
  name: groundcover-bearer-token
  namespace: keda
stringData:
  bearerToken: <api-key> # API key generated for querying the API

Defining the ClusterTriggerAuthentication Object

Now that we have the secret object defined, we need to tell KEDA how to use it. groundcover requires the api-key to be used as a Bearer token in the Authorization header.

apiVersion: keda.sh/v1alpha1
kind: ClusterTriggerAuthentication
metadata:
  name: groundcover-trigger-auth
spec:
  secretTargetRef: # this is a cluster-scoped resource. Assumes ref is to a secret in the same namespace as keda controller
    - parameter: bearerToken
      name: groundcover-bearer-token
      key: bearerToken

Defining the Auto-scaled Object

Now that we have set up KEDA to properly authenticate with groundcover, we can define our first auto-scaling behavior.

We will be defining a Prometheus trigger, querying the groundcover_kube_deployment_status_replicas_ready metric which indicates the amount of ready replicas for our deployment. Note that we apply the deployment="bookapi" filter, to query the metric specifically for our example deployment.

apiVersion: keda.sh/v1alpha1
kind: ScaledObject
metadata:
  name: bookapi-scaler
  namespace: books
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: bookapi
  minReplicaCount: 1
  maxReplicaCount: 10
  pollingInterval: 30
  triggers:
    - type: prometheus
      metadata:
        serverAddress: https://app.groundcover.com/api/prometheus
        threshold: "0.8"
        query: groundcover_kube_deployment_status_replicas_ready{deployment="bookapi"}
        authModes: bearer
      authenticationRef:
        name: groundcover-trigger-auth
        kind: ClusterTriggerAuthentication

Additional Scaling Examples

CPU-based Autoscaling

Scale based on average CPU usage across all pods in a deployment:

apiVersion: keda.sh/v1alpha1
kind: ScaledObject
metadata:
  name: cpu-based-scaler
  namespace: production
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: web-api
  minReplicaCount: 2
  maxReplicaCount: 50
  pollingInterval: 30
  triggers:
    - type: prometheus
      metadata:
        serverAddress: https://app.groundcover.com/api/prometheus
        threshold: "70"
        query: avg(groundcover_cpu_usage_percent{deployment="web-api"})
        authModes: bearer
      authenticationRef:
        name: groundcover-trigger-auth
        kind: ClusterTriggerAuthentication

Request Rate Autoscaling

Scale based on HTTP request rate:

apiVersion: keda.sh/v1alpha1
kind: ScaledObject
metadata:
  name: request-rate-scaler
  namespace: api
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: api-server
  minReplicaCount: 3
  maxReplicaCount: 100
  pollingInterval: 30
  triggers:
    - type: prometheus
      metadata:
        serverAddress: https://app.groundcover.com/api/prometheus
        threshold: "1000"
        query: sum(rate(groundcover_http_requests_total{deployment="api-server"}[5m]))
        authModes: bearer
      authenticationRef:
        name: groundcover-trigger-auth
        kind: ClusterTriggerAuthentication

Testing Your KEDA Configuration

Validate Metrics Query

Test your PromQL query before deploying:

curl 'https://app.groundcover.com/api/prometheus/api/v1/query?query=groundcover_kube_deployment_status_replicas_ready%7Bdeployment%3D%22bookapi%22%7D' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer <your-api-key>'

Check KEDA Logs

Monitor KEDA controller logs to ensure proper authentication and metric retrieval:

kubectl logs -n keda -l app=keda-operator

Verify Scaling Behavior

Test scaling by generating load or manually adjusting metric values and observing pod scaling.

API Keys - API key creation and management
KEDA Documentation - Official KEDA autoscaler documentation

Last updated 5 days ago