Istio VirtualService API

openapi: 3.2.0
info:
  title: Istio Networking Virtual Service API
  description: The Istio Networking API (networking.istio.io) provides configuration resources for traffic management within an Istio service mesh.
  version: v1
  contact:
    name: Istio
    url: https://istio.io/
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
servers:
- url: https://{cluster}/apis/networking.istio.io/v1
  description: Kubernetes API server endpoint for Istio Networking v1
  variables:
    cluster:
      default: kubernetes.default.svc
      description: Kubernetes API server hostname
tags:
- name: VirtualService
  description: HTTP/TCP routing rules for traffic management
  externalDocs:
    url: https://istio.io/latest/docs/reference/config/networking/virtual-service/
paths:
  /namespaces/{namespace}/virtualservices:
    get:
      operationId: listVirtualServices
      summary: Istio List VirtualServices
      description: List all VirtualService resources in the specified namespace. A VirtualService defines a set of traffic routing rules to apply when a host is addressed, enabling features such as HTTP route matching, retries, timeouts, fault injection, and traffic mirroring.
      tags:
      - VirtualService
      parameters:
      - $ref: '#/components/parameters/namespace'
      - $ref: '#/components/parameters/labelSelector'
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/continue'
      responses:
        '200':
          description: Successful response containing list of VirtualServices
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VirtualServiceList'
        '401':
          description: Unauthorized
    post:
      operationId: createVirtualService
      summary: Istio Create a VirtualService
      description: Create a new VirtualService resource in the specified namespace.
      tags:
      - VirtualService
      parameters:
      - $ref: '#/components/parameters/namespace'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VirtualService'
      responses:
        '201':
          description: VirtualService created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VirtualService'
        '401':
          description: Unauthorized
        '409':
          description: Conflict - resource already exists
  /namespaces/{namespace}/virtualservices/{name}:
    get:
      operationId: getVirtualService
      summary: Istio Get a VirtualService
      description: Read the specified VirtualService resource.
      tags:
      - VirtualService
      parameters:
      - $ref: '#/components/parameters/namespace'
      - $ref: '#/components/parameters/name'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VirtualService'
        '401':
          description: Unauthorized
        '404':
          description: Not found
    put:
      operationId: replaceVirtualService
      summary: Istio Replace a VirtualService
      description: Replace the specified VirtualService resource.
      tags:
      - VirtualService
      parameters:
      - $ref: '#/components/parameters/namespace'
      - $ref: '#/components/parameters/name'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VirtualService'
      responses:
        '200':
          description: VirtualService replaced
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VirtualService'
        '401':
          description: Unauthorized
        '404':
          description: Not found
    delete:
      operationId: deleteVirtualService
      summary: Istio Delete a VirtualService
      description: Delete the specified VirtualService resource.
      tags:
      - VirtualService
      parameters:
      - $ref: '#/components/parameters/namespace'
      - $ref: '#/components/parameters/name'
      responses:
        '200':
          description: VirtualService deleted
        '401':
          description: Unauthorized
        '404':
          description: Not found
components:
  parameters:
    labelSelector:
      name: labelSelector
      in: query
      description: A selector to restrict the list of returned objects by their labels
      schema:
        type: string
    name:
      name: name
      in: path
      required: true
      description: The resource name
      schema:
        type: string
    limit:
      name: limit
      in: query
      description: Maximum number of resources to return
      schema:
        type: integer
    continue:
      name: continue
      in: query
      description: Continue token for paginated list requests
      schema:
        type: string
    namespace:
      name: namespace
      in: path
      required: true
      description: The Kubernetes namespace
      schema:
        type: string
  schemas:
    VirtualService:
      type: object
      properties:
        apiVersion:
          type: string
          enum:
          - networking.istio.io/v1
        kind:
          type: string
          enum:
          - VirtualService
        metadata:
          $ref: '#/components/schemas/ObjectMeta'
        spec:
          type: object
          properties:
            hosts:
              type: array
              items:
                type: string
              description: The destination hosts to which traffic is being sent. Can be a DNS name with wildcard prefix or an IP address.
            gateways:
              type: array
              items:
                type: string
              description: The names of gateways that should apply these routes. A VirtualService with no gateway list will apply to sidecars only.
            http:
              type: array
              items:
                $ref: '#/components/schemas/HTTPRoute'
              description: An ordered list of route rules for HTTP traffic.
            tls:
              type: array
              items:
                type: object
              description: An ordered list of route rules for TLS and HTTPS traffic.
            tcp:
              type: array
              items:
                type: object
              description: An ordered list of route rules for TCP traffic.
            exportTo:
              type: array
              items:
                type: string
              description: A list of namespaces to which this virtual service is exported.
    HTTPRoute:
      type: object
      properties:
        name:
          type: string
          description: Name assigned to the route for debugging purposes.
        match:
          type: array
          items:
            type: object
            properties:
              uri:
                type: object
                description: URI match condition
              headers:
                type: object
                description: Header match conditions
              method:
                type: object
                description: HTTP method match condition
          description: Match conditions to be satisfied for the rule to be activated.
        route:
          type: array
          items:
            type: object
            properties:
              destination:
                type: object
                properties:
                  host:
                    type: string
                    description: The name of a service from the service registry.
                  port:
                    type: object
                    properties:
                      number:
                        type: integer
                  subset:
                    type: string
                    description: The name of a subset within the service.
              weight:
                type: integer
                description: Weight for traffic distribution.
          description: Route destinations with optional traffic weight.
        timeout:
          type: string
          description: Timeout for HTTP requests in duration format (e.g. 5s).
        retries:
          type: object
          properties:
            attempts:
              type: integer
            perTryTimeout:
              type: string
            retryOn:
              type: string
          description: Retry policy for HTTP requests.
        fault:
          type: object
          description: Fault injection policy.
        mirror:
          type: object
          description: Mirror HTTP traffic to another destination for testing.
        mirrorPercentage:
          type: object
          properties:
            value:
              type: number
          description: Percentage of traffic to mirror.
    VirtualServiceList:
      type: object
      properties:
        apiVersion:
          type: string
        kind:
          type: string
          enum:
          - VirtualServiceList
        metadata:
          $ref: '#/components/schemas/ListMeta'
        items:
          type: array
          items:
            $ref: '#/components/schemas/VirtualService'
    ListMeta:
      type: object
      properties:
        resourceVersion:
          type: string
        continue:
          type: string
    ObjectMeta:
      type: object
      properties:
        name:
          type: string
          description: Name of the resource
        namespace:
          type: string
          description: Namespace of the resource
        labels:
          type: object
          additionalProperties:
            type: string
          description: Map of string keys and values for organizing resources
        annotations:
          type: object
          additionalProperties:
            type: string
          description: Unstructured key-value map for storing arbitrary metadata
        creationTimestamp:
          type: string
          format: date-time
          description: Timestamp representing the server time when this object was created
        resourceVersion:
          type: string
          description: An opaque value that represents the internal version of this object
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: Kubernetes API server bearer token authentication
externalDocs:
  description: Istio Networking Configuration Reference
  url: https://istio.io/latest/docs/reference/config/networking/