KB
Kubernetes
Provider Setup

Connect Kubernetes

ConfigTrace connects to a Kubernetes cluster with a read-only kubeconfig and monitors the configuration that determines your cluster's security posture — workload privilege, RBAC, network exposure, and admission policy. This is configuration-security monitoring, not runtime threat detection: ConfigTrace never execs into pods, reads logs, or inspects Secret contents.

On this page
  1. Prerequisites
  2. Connection model
  3. Step 1 — Prepare read-only access
  4. Step 2 — Connect Kubernetes in ConfigTrace
  5. Step 3 — Run your first sync
  6. What ConfigTrace monitors
  7. What ConfigTrace never reads
  8. Known limitations
  9. Troubleshooting

Prerequisites

  • →A Kubernetes cluster you administer, with API server access
  • →Permission to create a ServiceAccount, ClusterRole, and ClusterRoleBinding (or an equivalent read-only credential)
  • →A ConfigTrace workspace (owner or admin role)

Connection model

ConfigTrace connects using a standard kubeconfig with a bearer token or client certificate bound to a read-only ServiceAccount. ConfigTrace does not support kubeconfigs that rely on exec-based or auth-provider-based authentication plugins (for example, cloud CLI credential helpers) — use a static token or certificate credential instead.

Step 1 — Prepare read-only access

Create a dedicated ServiceAccount scoped to read-only get/list/watch verbs across the resource types ConfigTrace monitors (see below). A minimal read-only ClusterRole covering workloads, RBAC objects, networking, and admission resources is recommended — avoid binding cluster-admin or any role with write verbs.

⚠
Do not grant create, update, patch, delete, exec, or portforward verbs. ConfigTrace only needs get, list, and watch on the resource types it reads.

Step 2 — Connect Kubernetes in ConfigTrace

  1. 1
    Open Integrations
    In the ConfigTrace sidebar, click Integrations, then click Connect on the Kubernetes card.
  2. 2
    Paste the kubeconfig
    Paste the kubeconfig for the read-only ServiceAccount (token or certificate-based). ConfigTrace encrypts it before storage and never displays it again.
  3. 3
    Save integration
    Click Save integration. ConfigTrace performs a read-only validation call against the cluster API server to confirm access.

Step 3 — Run your first sync

Click Sync Now. The first sync captures workload, RBAC, networking, and admission configuration across accessible namespaces as a baseline snapshot — this becomes the reference point for all future diffs.

What ConfigTrace monitors

✓ Reads (configuration metadata)
  • ✓Workload security context: privileged flags, host namespace / host networking posture, image references
  • ✓RBAC: Roles, ClusterRoles, RoleBindings, ClusterRoleBindings, ServiceAccounts, and privilege-escalation paths
  • ✓Services, Ingress, and Gateway API exposure configuration
  • ✓NetworkPolicy coverage and namespace isolation posture
  • ✓Admission webhooks and Pod Security Admission configuration
  • ✓ResourceQuota and LimitRange objects
✕ Never reads
  • ✕Secret or ConfigMap contents
  • ✕Pod logs, exec, attach, or port-forward sessions
  • ✕Container image contents
  • ✕Runtime, syscall, vulnerability, or malware scan data
  • ✕Audit log events
  • ✕API server flags or node configuration

What ConfigTrace never reads

⚠
ConfigTrace monitors configuration, not runtime behavior. It never reads Secret or ConfigMap contents, never execs into or port-forwards to a workload, and never performs vulnerability or malware scanning. This is configuration-security posture monitoring, not a runtime threat-detection tool.

For a full breakdown across all providers, see the Data Access & Permissions reference.

Known limitations

  • →kubeconfigs using exec or auth-provider authentication plugins (cloud CLI credential helpers) are not supported — use a static bearer token or client certificate
  • →Gateway API resources are reported as "unsupported" rather than flagged invalid when the Gateway API CRDs are not installed on the cluster
  • →ReferenceGrant, API server flags, and node-level configuration are not currently monitored
  • →No runtime, syscall, vulnerability, or malware scanning — configuration and RBAC posture only

Troubleshooting

  • →"Unsupported authentication method" on save: Your kubeconfig likely uses an exec or auth-provider plugin. Generate a static ServiceAccount token or client certificate instead.
  • →Forbidden errors during sync: The bound ClusterRole is missing get/list/watch on one of the monitored resource types. Check the sync error detail for the exact resource and verb.
  • →Gateway API section is empty: The cluster does not have the Gateway API CRDs installed — this is reported as unsupported, not an error.
  • →To revoke access: Delete the ServiceAccount, ClusterRole, and ClusterRoleBinding from the cluster, or disconnect the integration from ConfigTrace. ConfigTrace stops reading immediately.

For other issues, see the general Troubleshooting guide.