Policy Exceptions
Read the Kyverno policy exceptions that Nirmata Control Hub tracks across your clusters, and the resources each exception covers.
All paths are relative to /policies/api/v1. See Policies API v1 for authentication and conventions.
Endpoints
| Operation | Method | Path |
|---|---|---|
| List policy exceptions | GET | /policy-exceptions |
| Count policy exceptions | GET | /policy-exceptions/count |
| Find policy exceptions for a policy on a cluster | GET | /policy-exceptions/search |
| Get policy exception summary | GET | /policy-exceptions/summary |
| Get a policy exception | GET | /policy-exceptions/{id} |
| List policy exceptions for a cluster | GET | /policy-exceptions/by-cluster/{clusterId} |
| List policy exceptions by kind | GET | /policy-exceptions/by-kind/{kind} |
| List policy exceptions in a namespace | GET | /policy-exceptions/by-namespace/{namespace} |
| List resources excepted by a policy exception | GET | /policy-exceptions/{id}/excepted-resources |
Reference
List policy exceptions
GET /policies/api/v1/policy-exceptions
Returns all Kyverno policy exceptions in the tenant, paginated in memory with limit/offset.
Roles: admin
Query parameters
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
limit | integer | No | 50 | Maximum items to return |
offset | integer | No | 0 | Number of items to skip |
Response 200 (application/json)
Paginated: {items: PolicyException[], total, limit, offset}
| Field | Type | Description |
|---|---|---|
id | string | Policy exception ID |
apiVersion | string | Kyverno API version of the PolicyException resource |
kind | string | Resource kind (e.g. PolicyException) |
name | string | Policy exception name |
namespace | string | Kubernetes namespace of the exception |
uid | string | Kubernetes UID |
resourceVersion | string | Kubernetes resource version |
clusterRef | object | Reference to the cluster: {service, modelIndex, id} |
exceptions | array<object> | Excepted policies/rules: {policyName, ruleNames, namespace, policyUID, kind, policyRef} |
exceptedResources | array<object> | Resources currently excepted: {apiVersion, kind, name, namespace, fieldPath, resourceVersion, uid, resourceRef} |
yaml | string | Full YAML of the PolicyException resource |
requestDetails | string | JSON-encoded string with details of the originating exception request, if any |
Errors
500— Failed to retrieve policy exceptions401— Missing or invalid credentials403— Caller’s role is not permitted
Count policy exceptions
GET /policies/api/v1/policy-exceptions/count
Returns the total number of policy exceptions in the tenant.
Roles: admin
Response 200 (application/json)
{count: integer}
| Field | Type | Description |
|---|---|---|
count | integer | Number of policy exceptions |
Errors
500— Failed to count policy exceptions401— Missing or invalid credentials403— Caller’s role is not permitted
Find policy exceptions for a policy on a cluster
GET /policies/api/v1/policy-exceptions/search
Returns lightweight records of policy exceptions on a cluster that except the named policy, optionally restricted to a namespace.
Roles: Any role with permission for this resource. See Roles.
Query parameters
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
clusterId | string | Yes | — | Cluster ID |
policy | string | Yes | — | Exact policy name to match in the exception’s policy list |
namespace | string | No | — | Restrict to exceptions in this namespace |
Response 200 (application/json)
Array of {id, name, namespace}
| Field | Type | Description |
|---|---|---|
id | string | Policy exception ID |
name | string | Name (empty string if unset) |
namespace | string | Namespace (empty string if unset) |
Errors
400— clusterId or policy query parameter missing500— Failed to search policy exceptions401— Missing or invalid credentials403— Caller’s role is not permitted
Example
curl -H 'Authorization: NIRMATA-API <token>' 'https://<host>/policies/api/v1/policy-exceptions/search?clusterId=<id>&policy=disallow-privileged-containers'
Get policy exception summary
GET /policies/api/v1/policy-exceptions/summary
Returns counts of policy exceptions in the tenant: total, those with excepted resources, those listing policies, and empty ones.
Roles: Any role with permission for this resource. See Roles.
Response 200 (application/json)
{total, withExceptedResources, withPolicyExceptions, empty}
| Field | Type | Description |
|---|---|---|
total | integer | Total policy exceptions |
withExceptedResources | integer | Exceptions that currently match at least one resource |
withPolicyExceptions | integer | Exceptions that list at least one policy |
empty | integer | Approximate count of exceptions without policies/resources |
Errors
500— Failed to get policy exceptions summary401— Missing or invalid credentials403— Caller’s role is not permitted
Get a policy exception
GET /policies/api/v1/policy-exceptions/{id}
Returns a single policy exception by ID. Users with own-scope access can only read exceptions they requested.
Roles: Any role with permission for this resource. See Roles.
Path parameters
| Name | Type | Description |
|---|---|---|
id | string | Policy exception ID |
Response 200 (application/json)
PolicyException
| Field | Type | Description |
|---|---|---|
id | string | Policy exception ID |
apiVersion | string | Kyverno API version of the PolicyException resource |
kind | string | Resource kind (e.g. PolicyException) |
name | string | Policy exception name |
namespace | string | Kubernetes namespace of the exception |
uid | string | Kubernetes UID |
resourceVersion | string | Kubernetes resource version |
clusterRef | object | Reference to the cluster: {service, modelIndex, id} |
exceptions | array<object> | Excepted policies/rules: {policyName, ruleNames, namespace, policyUID, kind, policyRef} |
exceptedResources | array<object> | Resources currently excepted: {apiVersion, kind, name, namespace, fieldPath, resourceVersion, uid, resourceRef} |
yaml | string | Full YAML of the PolicyException resource |
requestDetails | string | JSON-encoded string with details of the originating exception request, if any |
Errors
404— Policy exception not found500— Failed to retrieve policy exception401— Missing or invalid credentials403— Caller’s role is not permitted
List policy exceptions for a cluster
GET /policies/api/v1/policy-exceptions/by-cluster/{clusterId}
Returns all policy exceptions belonging to the given cluster. Not paginated.
Roles: Any role with permission for this resource. See Roles.
Path parameters
| Name | Type | Description |
|---|---|---|
clusterId | string | Cluster ID |
Response 200 (application/json)
PolicyException[] (plain array)
| Field | Type | Description |
|---|---|---|
id | string | Policy exception ID |
apiVersion | string | Kyverno API version of the PolicyException resource |
kind | string | Resource kind (e.g. PolicyException) |
name | string | Policy exception name |
namespace | string | Kubernetes namespace of the exception |
uid | string | Kubernetes UID |
resourceVersion | string | Kubernetes resource version |
clusterRef | object | Reference to the cluster: {service, modelIndex, id} |
exceptions | array<object> | Excepted policies/rules: {policyName, ruleNames, namespace, policyUID, kind, policyRef} |
exceptedResources | array<object> | Resources currently excepted: {apiVersion, kind, name, namespace, fieldPath, resourceVersion, uid, resourceRef} |
yaml | string | Full YAML of the PolicyException resource |
requestDetails | string | JSON-encoded string with details of the originating exception request, if any |
Errors
500— Lookup failed401— Missing or invalid credentials403— Caller’s role is not permitted
List policy exceptions by kind
GET /policies/api/v1/policy-exceptions/by-kind/{kind}
Returns all policy exceptions whose resource kind exactly matches the given value (e.g. PolicyException). Not paginated.
Roles: Any role with permission for this resource. See Roles.
Path parameters
| Name | Type | Description |
|---|---|---|
kind | string | Resource kind |
Response 200 (application/json)
PolicyException[] (plain array)
| Field | Type | Description |
|---|---|---|
id | string | Policy exception ID |
apiVersion | string | Kyverno API version of the PolicyException resource |
kind | string | Resource kind (e.g. PolicyException) |
name | string | Policy exception name |
namespace | string | Kubernetes namespace of the exception |
uid | string | Kubernetes UID |
resourceVersion | string | Kubernetes resource version |
clusterRef | object | Reference to the cluster: {service, modelIndex, id} |
exceptions | array<object> | Excepted policies/rules: {policyName, ruleNames, namespace, policyUID, kind, policyRef} |
exceptedResources | array<object> | Resources currently excepted: {apiVersion, kind, name, namespace, fieldPath, resourceVersion, uid, resourceRef} |
yaml | string | Full YAML of the PolicyException resource |
requestDetails | string | JSON-encoded string with details of the originating exception request, if any |
Errors
500— Lookup failed401— Missing or invalid credentials403— Caller’s role is not permitted
List policy exceptions in a namespace
GET /policies/api/v1/policy-exceptions/by-namespace/{namespace}
Returns all policy exceptions whose namespace exactly matches the given value. Not paginated.
Roles: Any role with permission for this resource. See Roles.
Path parameters
| Name | Type | Description |
|---|---|---|
namespace | string | Kubernetes namespace name |
Response 200 (application/json)
PolicyException[] (plain array)
| Field | Type | Description |
|---|---|---|
id | string | Policy exception ID |
apiVersion | string | Kyverno API version of the PolicyException resource |
kind | string | Resource kind (e.g. PolicyException) |
name | string | Policy exception name |
namespace | string | Kubernetes namespace of the exception |
uid | string | Kubernetes UID |
resourceVersion | string | Kubernetes resource version |
clusterRef | object | Reference to the cluster: {service, modelIndex, id} |
exceptions | array<object> | Excepted policies/rules: {policyName, ruleNames, namespace, policyUID, kind, policyRef} |
exceptedResources | array<object> | Resources currently excepted: {apiVersion, kind, name, namespace, fieldPath, resourceVersion, uid, resourceRef} |
yaml | string | Full YAML of the PolicyException resource |
requestDetails | string | JSON-encoded string with details of the originating exception request, if any |
Errors
500— Lookup failed401— Missing or invalid credentials403— Caller’s role is not permitted
List resources excepted by a policy exception
GET /policies/api/v1/policy-exceptions/{id}/excepted-resources
Returns the Kubernetes resources currently matched (excepted) by the given policy exception.
Roles: Any role with permission for this resource. See Roles.
Path parameters
| Name | Type | Description |
|---|---|---|
id | string | Policy exception ID |
Response 200 (application/json)
{exceptedResources: object[], count: integer}
| Field | Type | Description |
|---|---|---|
exceptedResources | array<object> | {apiVersion, kind, name, namespace, fieldPath, resourceVersion, uid, resourceRef} |
count | integer | Number of excepted resources |
Errors
404— Policy exception not found500— Failed to get excepted resources401— Missing or invalid credentials403— Caller’s role is not permitted
Feedback
Was this page helpful?
Glad to hear it! Please tell us how we can improve.
Sorry to hear that. Please tell us how we can improve.