Troubleshoot

Troubleshoot Policy Controller

This page shows you how to resolve issues with Policy Controller.

Constraint not enforced

The following section provides troubleshooting guidance if you suspect or know your constraints aren’t being enforced.

Check if your constraint is enforced

If you’re concerned that your constraint is not enforced, you can check the spec.status of your constraint and the constraint template. To check the status, run the following command:

kubectl describe _CONSTRAINT_TEMPLATE_NAME_ _CONSTRAINT_NAME_

Replace the following:

  • **CONSTRAINT_TEMPLATE_NAME**: the name of the constraint template that you want to check. For example, K8sNoExternalServices.
  • **CONSTRAINT_NAME**: the Name of the constraint that you want to check.

If needed, run kubectl get constraint to see which constraint templates and constraints are installed on your system.

In the output of the kubectl describe command, take note the values in the metadata.generation and status.byPod.observedGeneration fields. In the following example these values are bolded:

apiVersion: constraints.gatekeeper.sh/v1beta1
kind: K8sPodsRequireSecurityContext
metadata:
  annotations:
    bundleDescription: >-
      Use the CIS Kubernetes Benchmark 1.5.1 policy bundle with Policy
      Controller to evaluate the compliance of your cluster resources against
      the CIS Kubernetes Benchmark, which is a set of recommendations for
      configuring Kubernetes to support a robust security posture.
    bundleDisplayName: CIS Kubernetes Benchmark v1.5.1
    constraintDescription: Requires that Pods define `securityContext`.
    constraintRemediation: >-
      Containers cannot run without a `securityContext` defined. Set your
      containers `securityContext: `. See "Set the security context for a Pod"
      for more information:
      https://kubernetes.io/docs/tasks/configure-pod-container/security-context/#set-the-security-context-for-a-pod
    distribution: mks
  creationTimestamp: '2025-09-03T04:55:59Z'
  generation: 1
  labels:
    bundleName: cis-k8s-v1.5.1
    enforcementAction: dryrun
    severity: UNSPECIFIED
  managedFields:
    - apiVersion: constraints.gatekeeper.sh/v1beta1
      fieldsType: FieldsV1
      fieldsV1:
        f:metadata:
          f:annotations:
            f:argocd.argoproj.io/installation-id: {}
            f:argocd.argoproj.io/sync-options: {}
            f:argocd.argoproj.io/sync-wave: {}
            f:argocd.argoproj.io/tracking-id: {}
            f:bundleDescription: {}
            f:bundleDisplayName: {}
            f:constraintDescription: {}
            f:constraintRemediation: {}
            f:distribution: {}
          f:labels:
            f:bundleName: {}
            f:enforcementAction: {}
            f:severity: {}
        f:spec:
          f:enforcementAction: {}
          f:match:
            f:excludedNamespaces: {}
            f:kinds: {}
      manager: argocd-controller
      operation: Apply
      time: '2025-09-08T08:20:12Z'
    - apiVersion: constraints.gatekeeper.sh/v1beta1
      fieldsType: FieldsV1
      fieldsV1:
        f:status:
          .: {}
          f:auditTimestamp: {}
          f:byPod: {}
          f:totalViolations: {}
          f:violations: {}
      manager: gatekeeper
      operation: Update
      subresource: status
      time: '2025-09-09T06:00:45Z'
  name: cis-k8s-v1.5.1-pods-require-security-context
  resourceVersion: '3258467'
  uid: 254282db-1326-4a3a-9457-20acc1d58f2b
spec:
  enforcementAction: dryrun
  match:
    excludedNamespaces:
      - kube-system
    kinds:
      - apiGroups:
          - ''
        kinds:
          - Pod
status:
  auditTimestamp: '2025-09-09T06:00:42Z'
  byPod:
    - constraintUID: 254282db-1326-4a3a-9457-20acc1d58f2b
      enforced: true
      id: gatekeeper-audit-68bfd4fdc8-qlvqm
      observedGeneration: 1
      operations:
        - audit
        - generate
        - status
    - constraintUID: 254282db-1326-4a3a-9457-20acc1d58f2b
      enforced: true
      id: gatekeeper-controller-manager-65c48d6b9b-8d9ct
      observedGeneration: 1
      operations:
        - webhook
    - constraintUID: 254282db-1326-4a3a-9457-20acc1d58f2b
      enforced: true
      id: gatekeeper-controller-manager-65c48d6b9b-b4d7p
      observedGeneration: 1
      operations:
        - webhook
    - constraintUID: 254282db-1326-4a3a-9457-20acc1d58f2b
      enforced: true
      id: gatekeeper-controller-manager-65c48d6b9b-vdzz2
      observedGeneration: 1
      operations:
        - webhook
  totalViolations: 3
  violations:
    - enforcementAction: dryrun
      group: ''
      kind: Pod
      message: securityContext must be defined for all Pod containers
      name: nginx-alb-5cfdfc9c-wmqdm
      namespace: default
      version: v1
    - enforcementAction: dryrun
      group: ''
      kind: Pod
      message: securityContext must be defined for all Pod containers
      name: nginx-alb-5cfdfc9c-lsc7w
      namespace: default
      version: v1
    - enforcementAction: dryrun
      group: ''
      kind: Pod
      message: securityContext must be defined for all Pod containers
      name: nginx-alb-5cfdfc9c-dvp6z
      namespace: default
      version: v1

If you see every Policy Controller Pod with an observedGeneration value equal to the metadata.generation value (which is the case in the preceding example), then your constraint is likely enforced. However, if these values match, but you are still experiencing problems with your constraint being enforced, see the following section for tips. If you notice that there are only some values that match, or some Pods aren’t listed, then the status of your constraint is unknown. The constraint might be inconsistently enforced across Policy Controller’s Pods, or not enforced at all. If there are no values that match, then your constraint is not enforced.

Constraint not enforced, but audit results reported

If the observedGeneration check described in the preceding section had matching values and there are audit results reported on the constraint that show expected violations (for pre-existing objects, not for inbound requests), but the constraint is still not enforced then the problem is likely to do with the webhook. The webhook might be experiencing one of the following issues:

  • The Policy Controller webhook Pod might not be operational. Kubernetes debugging techniques might help you to resolve issues with the webhook Pod.
  • There could be a firewall between the API server and the webhook service. Refer to your firewall provider’s documentation for details on how to fix the firewall.

Check the constraint template syntax

If you wrote your own constraint template , and it’s not enforced, there might be an error in the constraint template syntax.

You can review the template by using the following command:

kubectl describe constrainttemplate CONSTRAINT_TEMPLATE_NAME

Replace CONSTRAINT_TEMPLATE_NAME with the name of the template that you want to investigate. Errors should be reported in the status field.

Edit this page on GitHub

← Import EKS Cluster using Terraform
References →