Kubernetes Autoscaling API

openapi: 3.2.0
info:
  title: Kubernetes Autoscaling API
  description: The Kubernetes API lets you query and manipulate the state of objects in Kubernetes.
  version: v1.32.0
  contact:
    name: Kubernetes Community
    url: https://kubernetes.io/community/
  termsOfService: https://www.apache.org/licenses/LICENSE-2.0
servers:
- url: https://kubernetes.default.svc
  description: In-cluster Kubernetes API Server
security:
- bearerAuth: []
- clientCertificate: []
tags:
- name: Autoscaling
  description: Autoscaling resources including HorizontalPodAutoscalers for automatically scaling workloads based on observed metrics.
paths:
  /apis/autoscaling/v2/namespaces/{namespace}/horizontalpodautoscalers:
    get:
      operationId: listNamespacedHorizontalPodAutoscalers
      summary: Kubernetes List HorizontalPodAutoscalers in a namespace
      description: Returns a list of all HorizontalPodAutoscalers (HPAs) in the specified namespace. HPAs automatically scale the number of pod replicas based on observed CPU utilization, memory usage, or custom metrics.
      tags:
      - Autoscaling
      parameters:
      - $ref: '#/components/parameters/NamespaceParam'
      - $ref: '#/components/parameters/LabelSelector'
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Watch'
      responses:
        '200':
          description: List of HPAs
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HorizontalPodAutoscalerList'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createNamespacedHorizontalPodAutoscaler
      summary: Kubernetes Create a HorizontalPodAutoscaler
      description: Creates a new HorizontalPodAutoscaler in the specified namespace. Configure target resource utilization thresholds and min/max replica bounds to enable automatic workload scaling.
      tags:
      - Autoscaling
      parameters:
      - $ref: '#/components/parameters/NamespaceParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HorizontalPodAutoscaler'
      responses:
        '201':
          description: HPA created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HorizontalPodAutoscaler'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    Status:
      type: object
      description: Status is a return value for calls that don't return other objects. It is used to convey error messages, reasons, and codes for both success and failure responses.
      properties:
        apiVersion:
          type: string
        kind:
          type: string
          const: Status
        code:
          type: integer
          description: HTTP status code.
        message:
          type: string
          description: Human-readable description of the status.
        reason:
          type: string
          description: Machine-readable description of why the operation is in this status.
        status:
          type: string
          enum:
          - Success
          - Failure
          description: Outcome of the operation.
    HorizontalPodAutoscalerList:
      type: object
      description: A list of HPAs returned by list operations.
      required:
      - items
      properties:
        apiVersion:
          type: string
        kind:
          type: string
          const: HorizontalPodAutoscalerList
        metadata:
          $ref: '#/components/schemas/ListMeta'
        items:
          type: array
          items:
            $ref: '#/components/schemas/HorizontalPodAutoscaler'
    OwnerReference:
      type: object
      description: Reference to an owning resource that manages this object's lifecycle via garbage collection.
      required:
      - apiVersion
      - kind
      - name
      - uid
      properties:
        apiVersion:
          type: string
          description: API version of the owner resource.
        kind:
          type: string
          description: Kind of the owner resource.
        name:
          type: string
          description: Name of the owner resource.
        uid:
          type: string
          description: UID of the owner resource.
        controller:
          type: boolean
          description: Whether this reference points to the managing controller.
    ListMeta:
      type: object
      description: Metadata that all list responses include, containing pagination state and the resource version of the list.
      properties:
        resourceVersion:
          type: string
          description: Resource version of the list for use in watch operations.
        continue:
          type: string
          description: Token used to retrieve the next page of results in a paginated list request.
        remainingItemCount:
          type: integer
          description: Number of items remaining in the list if pagination is in effect.
    HorizontalPodAutoscaler:
      type: object
      description: A HorizontalPodAutoscaler automatically scales the number of pod replicas in a workload based on observed resource metrics (CPU, memory) or custom metrics from external sources.
      properties:
        apiVersion:
          type: string
          const: autoscaling/v2
        kind:
          type: string
          const: HorizontalPodAutoscaler
        metadata:
          $ref: '#/components/schemas/ObjectMeta'
        spec:
          type: object
          properties:
            scaleTargetRef:
              type: object
              description: Reference to the resource being scaled.
              required:
              - kind
              - name
              properties:
                apiVersion:
                  type: string
                kind:
                  type: string
                name:
                  type: string
            minReplicas:
              type: integer
              minimum: 1
              description: Minimum replica count. Defaults to 1.
            maxReplicas:
              type: integer
              description: Maximum replica count. Must be greater than minReplicas.
        status:
          type: object
          properties:
            currentReplicas:
              type: integer
              description: Current replica count.
            desiredReplicas:
              type: integer
              description: Desired replica count as computed by the autoscaler.
            lastScaleTime:
              type: string
              format: date-time
              description: Timestamp of the last scaling action.
    ObjectMeta:
      type: object
      description: Standard Kubernetes object metadata included on all persistent resources. Contains identifying information, ownership references, and system-managed fields like resourceVersion and uid.
      properties:
        name:
          type: string
          description: Unique name of the object within a namespace or cluster scope.
        namespace:
          type: string
          description: Namespace that scopes the resource name. Not all resource types are namespaced.
        uid:
          type: string
          description: Unique identifier generated by the server for this object. Remains constant for the lifetime of the object.
        resourceVersion:
          type: string
          description: Opaque string that identifies an internal server version of the object. Used for optimistic concurrency control and watch operations.
        generation:
          type: integer
          description: Sequence number representing the generation of the desired state. Incremented by the server on spec changes.
        creationTimestamp:
          type: string
          format: date-time
          description: Timestamp when the object was created.
        deletionTimestamp:
          type: string
          format: date-time
          description: Time at which the object will be deleted. Set by the server when a delete is requested.
        labels:
          type: object
          additionalProperties:
            type: string
          description: Map of string keys and values to organize and select resources. Labels are queryable via label selectors.
        annotations:
          type: object
          additionalProperties:
            type: string
          description: Map of non-identifying metadata. Annotations may contain arbitrary data and are not queryable by the API.
        ownerReferences:
          type: array
          description: List of objects that own this object. Garbage collection will delete this object when all owners are deleted.
          items:
            $ref: '#/components/schemas/OwnerReference'
  parameters:
    Watch:
      name: watch
      in: query
      description: Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion to watch from a specific version.
      schema:
        type: boolean
    NamespaceParam:
      name: namespace
      in: path
      required: true
      description: The namespace name to scope the request to.
      schema:
        type: string
    Limit:
      name: limit
      in: query
      description: Maximum number of resources to return in a single response. Use with the continue parameter to paginate through large result sets.
      schema:
        type: integer
        minimum: 1
        maximum: 500
    LabelSelector:
      name: labelSelector
      in: query
      description: 'Selector expression to filter resources by label. Supports equality (=, ==, !=), set-based (in, notin, exists) operations. Example: app=nginx,tier=frontend'
      schema:
        type: string
  responses:
    BadRequest:
      description: Bad request — invalid resource specification
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Status'
    Unauthorized:
      description: Unauthorized — missing or invalid authentication credentials
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Status'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Kubernetes service account token or user token issued by the cluster's authentication provider. Include in the Authorization header as 'Bearer <token>'.
    clientCertificate:
      type: mutualTLS
      description: Client certificate authentication using a TLS certificate issued by the cluster's certificate authority.
externalDocs:
  description: Kubernetes API Reference Documentation
  url: https://kubernetes.io/docs/reference/kubernetes-api/