Network policy, security identities, and FQDN/DNS policy
openapi: 3.1.0
info:
title: Cilium BGP Policy API
description: The Cilium REST API provides access to the Cilium daemon and agent endpoints for managing Kubernetes network policy, security, and connectivity. The API is served by the cilium-agent process over a local Unix domain socket and HTTP interface. It covers endpoint management, identity management, policy configuration, IP address management, service configuration, BGP operations, and daemon health status.
version: v1beta1
contact:
name: Cilium Community
url: https://cilium.io/get-help/
termsOfService: https://cilium.io/privacy/
servers:
- url: http://localhost/v1
description: Local Cilium Agent (Unix socket or HTTP)
tags:
- name: Policy
description: Network policy, security identities, and FQDN/DNS policy
paths:
/identity:
get:
operationId: listIdentities
summary: Cilium List security identities
description: Returns a list of all security identities known to the Cilium agent, each consisting of a numeric ID and the associated label set used to derive that identity for policy enforcement.
tags:
- Policy
parameters:
- $ref: '#/components/parameters/LabelsParam'
responses:
'200':
description: List of identities
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Identity'
'400':
description: Invalid label format
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/identity/{id}:
get:
operationId: getIdentity
summary: Cilium Get identity by ID
description: Returns the security identity corresponding to the given numeric identity ID, including its associated label set.
tags:
- Policy
parameters:
- $ref: '#/components/parameters/IdentityIDParam'
responses:
'200':
description: Identity details
content:
application/json:
schema:
$ref: '#/components/schemas/Identity'
'400':
description: Invalid identity ID
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Identity not found
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/identity/endpoints:
get:
operationId: getLocalEndpointIdentities
summary: Cilium List local endpoint identities
description: Returns the set of numeric security identities that are currently in use by local endpoints managed by this Cilium agent.
tags:
- Policy
responses:
'200':
description: Local endpoint identity list
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Identity'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/policy/selectors:
get:
operationId: getPolicySelectors
summary: Cilium Get policy selectors
description: Returns all policy selectors and the set of security identities that each selector currently matches, useful for debugging policy enforcement.
tags:
- Policy
responses:
'200':
description: Policy selector list
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/SelectorCache'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/fqdn/cache:
get:
operationId: getFQDNCache
summary: Cilium Get FQDN DNS cache
description: Returns the current DNS lookup cache used by Cilium for FQDN-based network policy enforcement, including resolved IP addresses and TTL information for each DNS name.
tags:
- Policy
parameters:
- $ref: '#/components/parameters/MatchPatternParam'
- $ref: '#/components/parameters/CIDRParam'
- $ref: '#/components/parameters/SourceParam'
responses:
'200':
description: FQDN cache entries
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/DNSLookup'
'400':
description: Invalid filter parameters
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
delete:
operationId: deleteFQDNCache
summary: Cilium Clear FQDN DNS cache
description: Removes entries from the FQDN DNS cache. Can delete all entries or filter by pattern. This forces re-resolution of DNS names on next policy evaluation.
tags:
- Policy
parameters:
- $ref: '#/components/parameters/MatchPatternParam'
responses:
'200':
description: Cache entries deleted
'400':
description: Invalid filter pattern
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/fqdn/names:
get:
operationId: getFQDNNames
summary: Cilium Get FQDN selector names
description: Returns all DNS names currently tracked by Cilium FQDN selectors, including the selectors that reference each name and the current set of IP addresses associated with each name.
tags:
- Policy
responses:
'200':
description: FQDN name list
content:
application/json:
schema:
$ref: '#/components/schemas/NameManager'
'400':
description: Request error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
components:
parameters:
LabelsParam:
name: labels
in: query
required: false
description: Filter by label selector (key=value pairs).
schema:
type: array
items:
type: string
MatchPatternParam:
name: matchpattern
in: query
required: false
description: FQDN name match pattern (shell-style glob).
schema:
type: string
IdentityIDParam:
name: id
in: path
required: true
description: Numeric security identity ID.
schema:
type: string
SourceParam:
name: source
in: query
required: false
description: Filter by DNS entry source (e.g., dns, connection).
schema:
type: string
CIDRParam:
name: cidr
in: query
required: false
description: Filter by CIDR network range.
schema:
type: string
schemas:
SelectorCache:
type: object
description: A policy selector and the identities it currently matches.
properties:
selector:
type: string
description: Label selector expression.
users:
type: integer
description: Number of policy rules using this selector.
identities:
type: array
items:
type: integer
description: List of identity IDs currently matched by this selector.
NameManager:
type: object
description: FQDN name manager state including all tracked DNS names.
properties:
FQDNs:
type: array
items:
type: object
properties:
fqdn:
type: string
description: DNS name being tracked.
ips:
type: array
items:
type: string
description: Current IP addresses for this name.
description: List of tracked FQDN entries.
Identity:
type: object
description: A Cilium security identity, derived from the set of labels associated with a workload and used for policy enforcement decisions.
properties:
id:
type: integer
format: int64
description: Unique numeric identity ID.
labels:
type: array
items:
type: string
description: Labels that define this identity.
labelsSHA256:
type: string
description: SHA256 hash of the label set for change detection.
Error:
type: string
description: Human-readable error message.
DNSLookup:
type: object
description: A DNS lookup entry in the FQDN cache.
properties:
fqdn:
type: string
description: Fully qualified domain name.
ips:
type: array
items:
type: string
description: IP addresses resolved for this FQDN.
lookupTime:
type: string
format: date-time
description: Time when this DNS lookup was performed.
ttl:
type: integer
description: DNS TTL in seconds.
expirationTime:
type: string
format: date-time
description: Time when this cache entry expires.
externalDocs:
description: Cilium API Documentation
url: https://docs.cilium.io/en/stable/api/