Kubernetes Data Collector Agent

Overview

The K8s Agent (Data Collector) is a lightweight, non-intrusive component designed to provide comprehensive visibility into your containerized infrastructure. By deploying the agent, you bridge the gap between raw cluster telemetry and actionable operational insights.

• K8s Agent: The K8s Agent (Data Collector) is a lightweight component running inside your Kubernetes cluster (or with kubeconfig pointing to it). It discovers cluster topology, collects metrics and process/network data, and sends this data to the Cloudamize data collector over HTTPS.

• Data Collector: A Cloudamize-hosted API that receives agent payloads, authenticates them using a Customer Key unique to your Cloudamize Account.

• Customer Key is the single secret from the Cloudamize Dashboard. It is used for Authentication and Encryption.

  One Customer Key can serve multiple clusters; each cluster is identified by a unique Cluster Name and optional Cluster ID.

Installation Prerequisites

• The agent pod requires outbound HTTPS access to:

  • The collector endpoint COLLECTOR_BASE_URL, default: <https://collector.cloudamize.com> on port 443.

  • The Kubernetes API server (in-cluster via service account, or external kubeconfig).

  • The metrics-server in-cluster API (optional; used for CPU/memory metrics).
    

• Permissions the Agent Needs (RBAC)

The agent runs under a dedicated ServiceAccount and requires a ClusterRole with read-only access to the listed resources, bound via a ClusterRoleBinding.

Below is the full ClusterRole:

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: cmz-k8s-agent-reader
rules:
- apiGroups: [""]
  resources:
    - nodes
    - pods
    - services
    - endpoints
    - namespaces
    - persistentvolumes
    - persistentvolumeclaims
    - configmaps
  verbs: ["get", "list", "watch"]
- apiGroups: ["apps"]
  resources:
    - deployments
    - replicasets
    - daemonsets
    - statefulsets
  verbs: ["get", "list", "watch"]
- apiGroups: ["networking.k8s.io"]
  resources:
    - networkpolicies
    - ingresses
  verbs: ["get", "list", "watch"]
- apiGroups: ["discovery.k8s.io"]
  resources:
    - endpointslices
  verbs: ["get", "list", "watch"]
- apiGroups: ["policy"]
  resources:
    - podsecuritypolicies
    - poddisruptionbudgets
  verbs: ["get", "list", "watch"]
- apiGroups: ["rbac.authorization.k8s.io"]
  resources:
    - roles
    - rolebindings
    - clusterroles
    - clusterrolebindings
  verbs: ["get", "list", "watch"]
- apiGroups: ["storage.k8s.io"]
  resources:
    - storageclasses
  verbs: ["get", "list", "watch"]
- apiGroups: ["metrics.k8s.io"]
  resources:
    - nodes
    - pods
  verbs: ["get", "list"]

Key points:

• Principle of least privilege: Only get, list, and watch verbs are granted. No create, update, patch, or delete permissions are needed or granted.

• Metrics are optional: If you do not run a metrics-server or do not want to expose it, omit the metrics.k8s.io block; the agent still sends discovery and other data but node/pod CPU/memory usage will be missing.

• Namespace: The agent deploys in a dedicated namespace (cmz-k8s-agent by default) with a ClusterRoleBinding binding the ClusterRole to the agent's ServiceAccount.

• Pod security: The agent pod runs as a non-root user, with a read-only root filesystem, all Linux capabilities dropped, and no privilege escalation allowed.

How to Deploy the K8s Agent

Prerequisites

• Customer Key from the Cloudamize Dashboard.

• kubectl is configured for your cluster.

• Sufficient permissions to create a namespace, ServiceAccount, ClusterRole/ClusterRoleBinding, and Deployment (cluster admin or equivalent).

• Outbound HTTPS (port 443) access from the cluster to the Cloudamize collector URL.

Option A — Helm (recommended):

The agent is published as a Helm chart on Amazon ECR Public. No helm repo add step is needed. Helm handles RBAC creation automatically.

Prerequisites: Helm 3.8+ (OCI support is built-in).

Step 1 — Install

Always-latest (easiest):

helm install cloudamize-agent \
  oci://public.ecr.aws/m5z6i3j5/cloudamize/helm/cloudamize-agent \
  --set customerKey=YOUR_KEY_FROM_DASHBOARD \ # Replace with your customer key
  --set clusterName=my-cluster # update the name of the cluster

Using a Kubernetes Secret instead of inlining the key (recommended for production):

kubectl create namespace cloudamize-agent
kubectl create secret generic cloudamize-agent-secret \
  --from-literal=CUSTOMER_KEY="your-customer-key" \
  -n cloudamize-agent
helm install cloudamize-agent \
  oci://public.ecr.aws/m5z6i3j5/cloudamize/helm/cloudamize-agent \
  --set existingSecret=cloudamize-agent-secret \
  --set clusterName=my-cluster # update the name of the cluster

Step 2 — Verify

kubectl get pods -n cloudamize-agent
kubectl logs -f deployment/cloudamize-agent -n cloudamize-agent

Upgrade

helm upgrade cloudamize-agent \
  oci://public.ecr.aws/m5z6i3j5/cloudamize/helm/cloudamize-agent \
  --reuse-values

Uninstall

helm uninstall cloudamize-agent

Option B — Plain manifests (kubectl fallback):

Manifests are published to Amazon ECR Public as OCI artifacts alongside the Helm chart.

Requires Oras (OCI Registry As Storage CLI).

Step 1 — Apply RBAC

Unlike Helm, the plain manifest path requires you to apply RBAC manually before deploying the agent:

kubectl apply -f - <<'EOF'
apiVersion: v1
kind: Namespace
metadata:
  name: cmz-k8s-agent
  labels:
    name: cmz-k8s-agent
    app.kubernetes.io/name: cmz-data-collector-k8s-agent
---
apiVersion: v1
kind: ServiceAccount
metadata:
  name: cmz-k8s-agent
  namespace: cmz-k8s-agent
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: cmz-k8s-agent-reader
rules:
- apiGroups: [""]
  resources:
    - nodes
    - pods
    - services
    - endpoints
    - namespaces
    - persistentvolumes
    - persistentvolumeclaims
  verbs: ["get", "list", "watch"]
- apiGroups: ["apps"]
  resources:
    - deployments
    - replicasets
    - daemonsets
    - statefulsets
  verbs: ["get", "list", "watch"]
- apiGroups: ["networking.k8s.io"]
  resources:
    - networkpolicies
    - ingresses
  verbs: ["get", "list", "watch"]
- apiGroups: ["storage.k8s.io"]
  resources:
    - storageclasses
  verbs: ["get", "list", "watch"]
- apiGroups: ["metrics.k8s.io"]
  resources:
    - nodes
    - pods
  verbs: ["get", "list"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: cmz-k8s-agent-reader
subjects:
- kind: ServiceAccount
  name: cmz-k8s-agent
  namespace: cmz-k8s-agent
roleRef:
  kind: ClusterRole
  name: cmz-k8s-agent-reader
  apiGroup: rbac.authorization.k8s.io
EOF

This creates:
| Resource | Name | Purpose |
|---|---|---|
| `Namespace` | `cmz-k8s-agent` | Dedicated namespace for the agent |
| `ServiceAccount` | `cmz-k8s-agent` | Identity the agent pod runs as |
| `ClusterRole` | `cmz-k8s-agent-reader` | Read-only access to the Kubernetes resources listed in section 3 |
| `ClusterRoleBinding` | `cmz-k8s-agent-reader` | Binds the ClusterRole to the ServiceAccount |

Verify:

kubectl get namespace cmz-k8s-agent
kubectl get serviceaccount cmz-k8s-agent -n cmz-k8s-agent
kubectl get clusterrolebinding cmz-k8s-agent-reader

Step 2 — Pull the manifests

Always-latest:

oras pull public.ecr.aws/m5z6i3j5/cloudamize/manifests/cloudamize-agent:latest

Pinned to a specific release:

oras pull public.ecr.aws/m5z6i3j5/cloudamize/manifests/cloudamize-agent:0.0.10

Both produce a single file: cloudamize-agent-manifests.yaml.

Step 3 — Configure and deploy

Edit the two placeholder values in cloudamize-agent-manifests.yaml:

- name: CUSTOMER_KEY
  value: "YOUR_KEY_FROM_DASHBOARD"   # <-- Required, customer key
- name: CLUSTER_NAME
  value: "my-cluster"                # <-- Required

Then apply:

kubectl apply -f cloudamize-agent-manifests.yaml

For production, store the key in a Kubernetes Secret instead of inlining it:

kubectl create secret generic cmz-agent-secrets \
  --from-literal=CUSTOMER_KEY="your-customer-key" \
  -n cmz-k8s-agent

Then reference it in the manifest:

- name: CUSTOMER_KEY
  valueFrom:
    secretKeyRef:
      name: cmz-agent-secrets
      key: CUSTOMER_KEY

Verify

kubectl get pods -n cmz-k8s-agent
kubectl logs -f deployment/cmz-k8s-agent -n cmz-k8s-agent
kubectl port-forward svc/cmz-k8s-agent 8080:8080 -n cmz-k8s-agent
curl http://localhost:8080/health
curl http://localhost:8080/ready

Container image

The agent image is hosted on Amazon ECR Public and does not require authentication to pull:

The :latest tag always points to the latest release. For reproducible deployments, pin to a specific image digest or SHA tag (Cloudamize uses the Git commit SHA as the image tag in CI).

Your cluster needs outbound access to public.ecr.aws on port 443 to pull the image on first deploy and on updates.

Environment variables reference

Multiple clusters

Use the same Customer Key for all clusters. Assign each cluster a unique CLUSTER_NAME (and optionally CLUSTER_ID) so the collector can differentiate them. For example:

# Cluster 1 – prod US East
- name: CUSTOMER_KEY
  value: "your-customer-key"
- name: CLUSTER_NAME
  value: "prod-us-east"
# Cluster 2 – staging
- name: CUSTOMER_KEY
  value: "your-customer-key"   # same key
- name: CLUSTER_NAME
  value: "staging"

Kubernetes APIs and Resources the Agent Uses

The agent only reads from the Kubernetes API; it does not create, update, or delete resources. Below are the accessed API groups and resources.

Core API (K8S)

Apps API (apps)

Networking API (networking.k8s.io)

Discovery API (discovery.k8s.io)

Policy API (policy)

RBAC API (rbac.authorization.k8s.io)

Storage API (storage.k8s.io)

Metrics API (metrics.k8s.io)

Other

• Server version: The agent calls the Kubernetes API server's version endpoint to discover cluster version.

• APIService (metrics): On startup, the agent checks that the v1beta1.metrics.k8s.io APIService is registered and metrics-server is reachable. It logs a warning if not but continues without metrics.

Note: The agent does not read secrets or other sensitive resources by default. Minimal RBAC deployments may omit some resources (e.g., configmaps, policy, rbac), resulting in reduced metadata collection.

If you have any questions or encounter any issues, please contact our support team at helpdesk@cloudamize.com.