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