The Kubernetes Ingress API manages external HTTP and HTTPS access to services within a cluster, providing load balancing, SSL termination, and name-based virtual hosting. Traffic routing is controlled by rules defined on the Ingress resource and fulfilled by an Ingress controller.
openapi: 3.1.0
info:
title: Kubernetes Services Kubernetes Ingress API
description: >-
The Kubernetes Ingress API manages external HTTP and HTTPS access to
services within a cluster, providing load balancing, SSL/TLS termination,
and name-based virtual hosting. Traffic routing is controlled by rules
defined on the Ingress resource and fulfilled by an Ingress controller
such as nginx-ingress, Traefik, or a cloud provider's ingress controller.
version: v1.32.0
contact:
name: Kubernetes Community
url: https://kubernetes.io/community/
termsOfService: https://www.apache.org/licenses/LICENSE-2.0
externalDocs:
description: Kubernetes Ingress API Reference
url: https://kubernetes.io/docs/reference/kubernetes-api/service-resources/ingress-v1/
servers:
- url: https://kubernetes.default.svc
description: In-cluster Kubernetes API Server
tags:
- name: Ingress
description: >-
Ingress resources defining HTTP and HTTPS routing rules from external
traffic to cluster services, with TLS termination support.
- name: IngressClass
description: >-
IngressClass resources identifying which ingress controller
should fulfill an Ingress resource.
- name: IngressStatus
description: >-
Status subresource for Ingress objects, reporting load balancer
IP or hostname assignments from the ingress controller.
security:
- bearerAuth: []
- clientCertificate: []
paths:
/apis/networking.k8s.io/v1/namespaces/{namespace}/ingresses:
get:
operationId: listNamespacedIngresses
summary: Kubernetes Services List Ingresses in a namespace
description: >-
Returns a list of all Ingress objects in the specified namespace.
Each Ingress defines HTTP/HTTPS routing rules that an ingress
controller translates into proxy configuration.
tags:
- Ingress
parameters:
- $ref: '#/components/parameters/NamespaceParam'
- $ref: '#/components/parameters/LabelSelector'
- $ref: '#/components/parameters/FieldSelector'
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/Continue'
- $ref: '#/components/parameters/Watch'
responses:
'200':
description: List of Ingress objects
content:
application/json:
schema:
$ref: '#/components/schemas/IngressList'
'401':
$ref: '#/components/responses/Unauthorized'
post:
operationId: createNamespacedIngress
summary: Kubernetes Services Create an Ingress
description: >-
Creates a new Ingress in the specified namespace. The Ingress spec
defines host-based and path-based routing rules, optional TLS
configuration, and a default backend for unmatched requests.
tags:
- Ingress
parameters:
- $ref: '#/components/parameters/NamespaceParam'
- $ref: '#/components/parameters/DryRun'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Ingress'
responses:
'201':
description: Ingress created
content:
application/json:
schema:
$ref: '#/components/schemas/Ingress'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'409':
$ref: '#/components/responses/Conflict'
/apis/networking.k8s.io/v1/namespaces/{namespace}/ingresses/{name}:
get:
operationId: getNamespacedIngress
summary: Kubernetes Services Get an Ingress
description: >-
Returns the specified Ingress including its routing rules, TLS
configuration, associated IngressClass, and load balancer status
from the ingress controller.
tags:
- Ingress
parameters:
- $ref: '#/components/parameters/NamespaceParam'
- $ref: '#/components/parameters/NameParam'
responses:
'200':
description: Ingress details
content:
application/json:
schema:
$ref: '#/components/schemas/Ingress'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
put:
operationId: replaceNamespacedIngress
summary: Kubernetes Services Replace an Ingress
description: >-
Replaces the full specification of the specified Ingress. The ingress
controller will reconfigure its proxy rules to match the updated
routing configuration.
tags:
- Ingress
parameters:
- $ref: '#/components/parameters/NamespaceParam'
- $ref: '#/components/parameters/NameParam'
- $ref: '#/components/parameters/DryRun'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Ingress'
responses:
'200':
description: Ingress updated
content:
application/json:
schema:
$ref: '#/components/schemas/Ingress'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
patch:
operationId: patchNamespacedIngress
summary: Kubernetes Services Patch an Ingress
description: >-
Applies a partial update to the specified Ingress using strategic
merge patch or JSON merge patch semantics.
tags:
- Ingress
parameters:
- $ref: '#/components/parameters/NamespaceParam'
- $ref: '#/components/parameters/NameParam'
requestBody:
required: true
content:
application/merge-patch+json:
schema:
type: object
responses:
'200':
description: Ingress patched
content:
application/json:
schema:
$ref: '#/components/schemas/Ingress'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
delete:
operationId: deleteNamespacedIngress
summary: Kubernetes Services Delete an Ingress
description: >-
Deletes the specified Ingress. The ingress controller will remove
the corresponding proxy rules and any associated TLS configuration.
tags:
- Ingress
parameters:
- $ref: '#/components/parameters/NamespaceParam'
- $ref: '#/components/parameters/NameParam'
responses:
'200':
description: Ingress deleted
content:
application/json:
schema:
$ref: '#/components/schemas/Ingress'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/apis/networking.k8s.io/v1/namespaces/{namespace}/ingresses/{name}/status:
get:
operationId: getNamespacedIngressStatus
summary: Kubernetes Services Get Ingress status
description: >-
Returns the status subresource for the specified Ingress, including
the load balancer IP addresses or hostnames assigned by the ingress
controller.
tags:
- IngressStatus
parameters:
- $ref: '#/components/parameters/NamespaceParam'
- $ref: '#/components/parameters/NameParam'
responses:
'200':
description: Ingress status
content:
application/json:
schema:
$ref: '#/components/schemas/Ingress'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
put:
operationId: replaceNamespacedIngressStatus
summary: Kubernetes Services Replace Ingress status
description: >-
Replaces the status subresource of the specified Ingress. Used by
ingress controllers to report assigned load balancer IPs and
hostnames.
tags:
- IngressStatus
parameters:
- $ref: '#/components/parameters/NamespaceParam'
- $ref: '#/components/parameters/NameParam'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Ingress'
responses:
'200':
description: Ingress status updated
content:
application/json:
schema:
$ref: '#/components/schemas/Ingress'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/apis/networking.k8s.io/v1/ingresses:
get:
operationId: listIngressesAllNamespaces
summary: Kubernetes Services List Ingresses across all namespaces
description: >-
Returns all Ingress objects cluster-wide. Useful for auditing ingress
rules, identifying conflicting host rules, and monitoring TLS
certificate coverage across namespaces.
tags:
- Ingress
parameters:
- $ref: '#/components/parameters/LabelSelector'
- $ref: '#/components/parameters/FieldSelector'
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/Watch'
responses:
'200':
description: List of Ingresses across all namespaces
content:
application/json:
schema:
$ref: '#/components/schemas/IngressList'
'401':
$ref: '#/components/responses/Unauthorized'
/apis/networking.k8s.io/v1/ingressclasses:
get:
operationId: listIngressClasses
summary: Kubernetes Services List IngressClasses
description: >-
Returns a list of all IngressClass resources in the cluster. Each
IngressClass identifies an ingress controller implementation and its
parameters. Ingress objects reference an IngressClass to select their
controller.
tags:
- IngressClass
parameters:
- $ref: '#/components/parameters/LabelSelector'
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/Watch'
responses:
'200':
description: List of IngressClass resources
content:
application/json:
schema:
$ref: '#/components/schemas/IngressClassList'
'401':
$ref: '#/components/responses/Unauthorized'
post:
operationId: createIngressClass
summary: Kubernetes Services Create an IngressClass
description: >-
Creates a new IngressClass resource. IngressClasses are cluster-scoped
and define a mapping between Ingress resources and the controller
responsible for fulfilling them.
tags:
- IngressClass
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/IngressClass'
responses:
'201':
description: IngressClass created
content:
application/json:
schema:
$ref: '#/components/schemas/IngressClass'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
/apis/networking.k8s.io/v1/ingressclasses/{name}:
get:
operationId: getIngressClass
summary: Kubernetes Services Get an IngressClass
description: >-
Returns the specified IngressClass including the controller name and
any controller-specific parameters reference.
tags:
- IngressClass
parameters:
- $ref: '#/components/parameters/NameParam'
responses:
'200':
description: IngressClass details
content:
application/json:
schema:
$ref: '#/components/schemas/IngressClass'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
delete:
operationId: deleteIngressClass
summary: Kubernetes Services Delete an IngressClass
description: >-
Deletes the specified IngressClass. Existing Ingress objects that
reference this IngressClass will no longer be fulfilled by any
controller unless another IngressClass is configured.
tags:
- IngressClass
parameters:
- $ref: '#/components/parameters/NameParam'
responses:
'200':
description: IngressClass deleted
content:
application/json:
schema:
$ref: '#/components/schemas/IngressClass'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: Kubernetes service account or user bearer token.
clientCertificate:
type: mutualTLS
description: Client TLS certificate signed by the cluster CA.
parameters:
NamespaceParam:
name: namespace
in: path
required: true
description: Namespace name to scope the request.
schema:
type: string
NameParam:
name: name
in: path
required: true
description: Name of the resource.
schema:
type: string
LabelSelector:
name: labelSelector
in: query
description: Label selector to filter resources.
schema:
type: string
FieldSelector:
name: fieldSelector
in: query
description: Field selector to filter resources by field values.
schema:
type: string
Limit:
name: limit
in: query
description: Maximum number of items to return.
schema:
type: integer
minimum: 1
Continue:
name: continue
in: query
description: Pagination continuation token.
schema:
type: string
Watch:
name: watch
in: query
description: If true, stream watch events instead of returning a list.
schema:
type: boolean
DryRun:
name: dryRun
in: query
description: If 'All', validates without persisting the change.
schema:
type: string
enum:
- All
responses:
BadRequest:
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
Unauthorized:
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
NotFound:
description: Not found
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
Conflict:
description: Conflict
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
schemas:
IngressBackend:
type: object
description: >-
Reference to the backend service or resource that an Ingress routing
rule should forward traffic to.
properties:
service:
type: object
description: Service backend reference for routing.
required:
- name
- port
properties:
name:
type: string
description: Name of the referenced Service in the same namespace.
port:
type: object
description: Port on the referenced Service to forward traffic to.
properties:
number:
type: integer
minimum: 1
maximum: 65535
description: Numeric port number.
name:
type: string
description: Named port as defined in the Service spec.
resource:
type: object
description: >-
Reference to a custom resource backend in the same namespace.
Mutually exclusive with service.
properties:
apiGroup:
type: string
description: API group of the referenced resource.
kind:
type: string
description: Kind of the referenced resource.
name:
type: string
description: Name of the referenced resource.
HTTPIngressPath:
type: object
description: >-
A mapping of an HTTP path to a backend service. Used within Ingress
rules to route specific paths to different services.
required:
- pathType
- backend
properties:
path:
type: string
description: >-
URL path to match. Must begin with '/'. Required for Exact and
Prefix pathTypes.
pattern: '^/'
pathType:
type: string
enum:
- Exact
- Prefix
- ImplementationSpecific
description: >-
How the path is matched. Exact requires a case-sensitive exact
match; Prefix matches paths sharing a '/' delimited prefix;
ImplementationSpecific defers to the IngressClass controller.
backend:
$ref: '#/components/schemas/IngressBackend'
IngressRule:
type: object
description: >-
A host-based routing rule mapping HTTP requests to backend services
based on hostname and path prefix matching.
properties:
host:
type: string
description: >-
Fully-qualified domain name to match. Wildcard prefixes like
*.example.com are supported. If unspecified, all hosts match.
http:
type: object
description: HTTP-specific routing configuration for this rule.
required:
- paths
properties:
paths:
type: array
description: >-
List of path-to-backend mappings for this rule. At least one
path must be specified.
minItems: 1
items:
$ref: '#/components/schemas/HTTPIngressPath'
IngressTLS:
type: object
description: >-
TLS configuration for an Ingress, specifying a Secret containing the
certificate and key for terminating HTTPS connections on port 443.
properties:
hosts:
type: array
description: >-
Hosts covered by the TLS certificate. Must match hosts defined
in the certificate's Subject Alternative Names.
items:
type: string
secretName:
type: string
description: >-
Name of the Secret in the same namespace containing the TLS
certificate (tls.crt) and key (tls.key).
IngressSpec:
type: object
description: >-
Specification of the desired behavior of an Ingress, including the
routing rules, TLS configuration, default backend, and reference to
the ingress controller via the IngressClass.
properties:
ingressClassName:
type: string
description: >-
Name of the IngressClass cluster resource that selects which
ingress controller handles this Ingress.
defaultBackend:
$ref: '#/components/schemas/IngressBackend'
tls:
type: array
description: TLS configuration for HTTPS termination.
items:
$ref: '#/components/schemas/IngressTLS'
rules:
type: array
description: >-
List of host rules for HTTP traffic routing. If no rules match
a request, the defaultBackend is used.
items:
$ref: '#/components/schemas/IngressRule'
IngressStatus:
type: object
description: >-
Most recently observed status of an Ingress, reporting the load
balancer IPs or hostnames assigned by the ingress controller.
properties:
loadBalancer:
type: object
description: LoadBalancer status for the ingress.
properties:
ingress:
type: array
description: List of load balancer ingress points.
items:
type: object
properties:
ip:
type: string
description: IP address assigned to this ingress point.
hostname:
type: string
description: Hostname assigned to this ingress point.
ports:
type: array
items:
type: object
properties:
port:
type: integer
protocol:
type: string
error:
type: string
Ingress:
type: object
description: >-
An Ingress manages external access to the services in a cluster,
typically HTTP/HTTPS. It provides load balancing, SSL termination,
and name-based virtual hosting based on routing rules.
properties:
apiVersion:
type: string
const: networking.k8s.io/v1
kind:
type: string
const: Ingress
metadata:
$ref: '#/components/schemas/ObjectMeta'
spec:
$ref: '#/components/schemas/IngressSpec'
status:
$ref: '#/components/schemas/IngressStatus'
IngressList:
type: object
description: A list of Ingress objects.
required:
- items
properties:
apiVersion:
type: string
kind:
type: string
const: IngressList
metadata:
$ref: '#/components/schemas/ListMeta'
items:
type: array
items:
$ref: '#/components/schemas/Ingress'
IngressClass:
type: object
description: >-
An IngressClass is a cluster-scoped resource that represents an
ingress controller implementation. Ingress objects reference an
IngressClass by name to select which controller fulfills them.
properties:
apiVersion:
type: string
const: networking.k8s.io/v1
kind:
type: string
const: IngressClass
metadata:
$ref: '#/components/schemas/ObjectMeta'
spec:
type: object
description: IngressClass specification.
properties:
controller:
type: string
description: >-
Name of the controller that handles Ingresses of this class.
Example: ingress.controller.example.com/nginx
parameters:
type: object
description: >-
Reference to a custom resource containing controller-specific
parameters for this IngressClass.
IngressClassList:
type: object
description: A list of IngressClass resources.
required:
- items
properties:
apiVersion:
type: string
kind:
type: string
const: IngressClassList
metadata:
$ref: '#/components/schemas/ListMeta'
items:
type: array
items:
$ref: '#/components/schemas/IngressClass'
ObjectMeta:
type: object
description: Standard Kubernetes object metadata.
properties:
name:
type: string
description: Name of the object.
namespace:
type: string
description: Namespace of the object.
uid:
type: string
description: Unique server-assigned identifier.
resourceVersion:
type: string
description: Internal version for optimistic concurrency.
creationTimestamp:
type: string
format: date-time
description: Creation timestamp.
labels:
type: object
additionalProperties:
type: string
description: Key-value label pairs.
annotations:
type: object
additionalProperties:
type: string
description: Non-identifying metadata.
ListMeta:
type: object
description: Metadata for list responses.
properties:
resourceVersion:
type: string
continue:
type: string
remainingItemCount:
type: integer
Status:
type: object
description: Error or result status returned by the API.
properties:
code:
type: integer
message:
type: string
reason:
type: string
status:
type: string
enum:
- Success
- Failure