openapi: 3.1.0 info: title: Kuma Dataplane MeshHTTPRoute API description: Kuma API version: v1alpha1 x-ref-schema-name: DataplaneOverview security: - BasicAuth: [] - BearerAuth: [] - {} tags: - name: MeshHTTPRoute paths: /meshes/{mesh}/meshhttproutes/{name}: get: operationId: getMeshHTTPRoute summary: Returns MeshHTTPRoute entity tags: - MeshHTTPRoute parameters: - in: path name: mesh schema: type: string required: true description: name of the mesh - in: path name: name schema: type: string required: true description: name of the MeshHTTPRoute responses: '200': $ref: '#/components/responses/MeshHTTPRouteItem' '404': $ref: '#/components/responses/NotFound' put: operationId: putMeshHTTPRoute summary: Creates or Updates MeshHTTPRoute entity tags: - MeshHTTPRoute parameters: - in: path name: mesh schema: type: string required: true description: name of the mesh - in: path name: name schema: type: string required: true description: name of the MeshHTTPRoute requestBody: description: Put request required: true content: application/json: schema: $ref: '#/components/schemas/MeshHTTPRouteItem' responses: '200': $ref: '#/components/responses/MeshHTTPRouteCreateOrUpdateSuccessResponse' '201': $ref: '#/components/responses/MeshHTTPRouteCreateOrUpdateSuccessResponse' delete: operationId: deleteMeshHTTPRoute summary: Deletes MeshHTTPRoute entity tags: - MeshHTTPRoute parameters: - in: path name: mesh schema: type: string required: true description: name of the mesh - in: path name: name schema: type: string required: true description: name of the MeshHTTPRoute responses: '200': $ref: '#/components/responses/MeshHTTPRouteDeleteSuccessResponse' '404': $ref: '#/components/responses/NotFound' /meshes/{mesh}/meshhttproutes: get: operationId: getMeshHTTPRouteList summary: Returns a list of MeshHTTPRoute in the mesh. tags: - MeshHTTPRoute parameters: - in: query name: offset description: offset in the list of entities required: false schema: type: integer example: 0 - in: query name: size description: the number of items per page required: false schema: type: integer default: 100 maximum: 1000 minimum: 1 - in: query name: filter description: filter by labels when multiple filters are present, they are ANDed required: false schema: type: object properties: key: type: string value: type: string example: label.k8s.kuma.io/namespace: my-ns - in: path name: mesh schema: type: string required: true description: name of the mesh responses: '200': $ref: '#/components/responses/MeshHTTPRouteList' components: responses: NotFound: description: Not Found content: application/problem+json: schema: $ref: '#/components/schemas/NotFoundError' MeshHTTPRouteDeleteSuccessResponse: description: Successful response content: application/json: schema: type: object MeshHTTPRouteCreateOrUpdateSuccessResponse: description: Successful response content: application/json: schema: type: object properties: warnings: type: array readOnly: true description: 'warnings is a list of warning messages to return to the requesting Kuma API clients. Warning messages describe a problem the client making the API request should correct or be aware of. ' items: type: string MeshHTTPRouteItem: description: Successful response content: application/json: schema: $ref: '#/components/schemas/MeshHTTPRouteItem' MeshHTTPRouteList: description: List content: application/json: schema: type: object properties: items: type: array items: $ref: '#/components/schemas/MeshHTTPRouteItem' total: type: number description: The total number of entities next: type: string description: URL to the next page schemas: NotFoundError: allOf: - $ref: '#/components/schemas/Error' - type: object properties: status: type: integer enum: - 404 example: 404 description: 'The HTTP status code for NotFoundError MUST be 404. ' title: type: string example: Not Found type: type: string example: https://httpstatuses.com/404 detail: type: string example: The requested resource was not found InvalidParameters: type: object title: Invalid Parameters required: - field - reason - source properties: field: type: string description: The name of the field that caused the error. reason: type: string description: 'A short, human-readable description of the problem. _Should_ be provided as "Sentence case" for direct use in a UI. ' rule: type: string description: 'May be provided as a hint to the user to help understand the type of failure. Additional guidance may be provided in additional fields, i.e. `choices`. ' choices: type: array description: 'Optional field to provide a list of valid choices for the field that caused the error. ' items: type: string source: type: string description: 'The location of the field that caused the error. ' enum: - body - query - header - path MeshHTTPRouteItem: type: object description: 'NOTICE: This policy defines its own `GetDefault` method so that it can have the given structure for deserialization but still use the generic policy merging machinery. // MeshHTTPRoute configures how HTTP requests are routed between services in the mesh. It enables advanced traffic management including path-based routing, header matching, request/response modification, redirects, URL rewrites, traffic mirroring, and weighted load balancing across service endpoints.' required: - type - name - spec properties: type: description: the type of the resource type: string enum: - MeshHTTPRoute mesh: description: Mesh is the name of the Kuma mesh this resource belongs to. It may be omitted for cluster-scoped resources. type: string default: default kri: description: A unique identifier for this resource instance used by internal tooling and integrations. Typically derived from resource attributes and may be used for cross-references or indexing type: string readOnly: true example: kri_mhttpr_default_zone-east_kuma-demo_mypolicy1_ name: description: Name of the Kuma resource type: string labels: additionalProperties: type: string description: The labels to help identity resources type: object spec: description: Spec is the specification of the Kuma MeshHTTPRoute resource. properties: targetRef: description: 'TargetRef is a reference to the resource the policy takes an effect on. The resource could be either a real store object or virtual resource defined inplace.' properties: kind: description: Kind of the referenced resource enum: - Mesh - MeshSubset - MeshGateway - MeshService - MeshExternalService - MeshMultiZoneService - MeshServiceSubset - MeshHTTPRoute - Dataplane type: string labels: additionalProperties: type: string description: 'Labels are used to select group of MeshServices that match labels. Either Labels or Name and Namespace can be used.' type: object mesh: description: Mesh is reserved for future use to identify cross mesh resources. type: string name: description: 'Name of the referenced resource. Can only be used with kinds: `MeshService`, `MeshServiceSubset` and `MeshGatewayRoute`' type: string namespace: description: 'Namespace specifies the namespace of target resource. If empty only resources in policy namespace will be targeted.' type: string proxyTypes: description: 'ProxyTypes specifies the data plane types that are subject to the policy. When not specified, all data plane types are targeted by the policy.' items: enum: - Sidecar - Gateway type: string type: array sectionName: description: 'SectionName is used to target specific section of resource. For example, you can target port from MeshService.ports[] by its name. Only traffic to this port will be affected.' type: string tags: additionalProperties: type: string description: 'Tags used to select a subset of proxies by tags. Can only be used with kinds `MeshSubset` and `MeshServiceSubset`' type: object required: - kind type: object to: description: To matches destination services of requests and holds configuration. items: properties: hostnames: description: 'Hostnames is only valid when targeting MeshGateway and limits the effects of the rules to requests to this hostname. Given hostnames must intersect with the hostname of the listeners the route attaches to.' items: type: string type: array rules: description: 'Rules contains the routing rules applies to a combination of top-level targetRef and the targetRef in this entry.' items: properties: default: description: 'Default holds routing rules that can be merged with rules from other policies.' properties: backendRefs: items: description: BackendRef defines where to forward traffic. properties: kind: description: Kind of the referenced resource enum: - Mesh - MeshSubset - MeshGateway - MeshService - MeshExternalService - MeshMultiZoneService - MeshServiceSubset - MeshHTTPRoute - Dataplane type: string labels: additionalProperties: type: string description: 'Labels are used to select group of MeshServices that match labels. Either Labels or Name and Namespace can be used.' type: object mesh: description: Mesh is reserved for future use to identify cross mesh resources. type: string name: description: 'Name of the referenced resource. Can only be used with kinds: `MeshService`, `MeshServiceSubset` and `MeshGatewayRoute`' type: string namespace: description: 'Namespace specifies the namespace of target resource. If empty only resources in policy namespace will be targeted.' type: string port: description: Port is only supported when this ref refers to a real MeshService object format: int32 type: integer proxyTypes: description: 'ProxyTypes specifies the data plane types that are subject to the policy. When not specified, all data plane types are targeted by the policy.' items: enum: - Sidecar - Gateway type: string type: array sectionName: description: 'SectionName is used to target specific section of resource. For example, you can target port from MeshService.ports[] by its name. Only traffic to this port will be affected.' type: string tags: additionalProperties: type: string description: 'Tags used to select a subset of proxies by tags. Can only be used with kinds `MeshSubset` and `MeshServiceSubset`' type: object weight: default: 1 minimum: 0 type: integer required: - kind type: object type: array filters: items: properties: requestHeaderModifier: description: 'Only one action is supported per header name. Configuration to set or add multiple values for a header must use RFC 7230 header value formatting, separating each value with a comma.' properties: add: items: properties: name: maxLength: 256 minLength: 1 pattern: ^[a-z0-9!#$%&'*+\-.^_\x60|~]+$ type: string value: type: string required: - name - value type: object maxItems: 16 type: array x-kubernetes-list-map-keys: - name x-kubernetes-list-type: map remove: items: type: string maxItems: 16 type: array set: items: properties: name: maxLength: 256 minLength: 1 pattern: ^[a-z0-9!#$%&'*+\-.^_\x60|~]+$ type: string value: type: string required: - name - value type: object maxItems: 16 type: array x-kubernetes-list-map-keys: - name x-kubernetes-list-type: map type: object requestMirror: properties: backendRef: description: BackendRef defines where to forward traffic. properties: kind: description: Kind of the referenced resource enum: - Mesh - MeshSubset - MeshGateway - MeshService - MeshExternalService - MeshMultiZoneService - MeshServiceSubset - MeshHTTPRoute - Dataplane type: string labels: additionalProperties: type: string description: 'Labels are used to select group of MeshServices that match labels. Either Labels or Name and Namespace can be used.' type: object mesh: description: Mesh is reserved for future use to identify cross mesh resources. type: string name: description: 'Name of the referenced resource. Can only be used with kinds: `MeshService`, `MeshServiceSubset` and `MeshGatewayRoute`' type: string namespace: description: 'Namespace specifies the namespace of target resource. If empty only resources in policy namespace will be targeted.' type: string port: description: Port is only supported when this ref refers to a real MeshService object format: int32 type: integer proxyTypes: description: 'ProxyTypes specifies the data plane types that are subject to the policy. When not specified, all data plane types are targeted by the policy.' items: enum: - Sidecar - Gateway type: string type: array sectionName: description: 'SectionName is used to target specific section of resource. For example, you can target port from MeshService.ports[] by its name. Only traffic to this port will be affected.' type: string tags: additionalProperties: type: string description: 'Tags used to select a subset of proxies by tags. Can only be used with kinds `MeshSubset` and `MeshServiceSubset`' type: object weight: default: 1 minimum: 0 type: integer required: - kind type: object percentage: anyOf: - type: integer - type: string description: 'Percentage of requests to mirror. If not specified, all requests to the target cluster will be mirrored.' x-kubernetes-int-or-string: true required: - backendRef type: object requestRedirect: properties: hostname: description: 'PreciseHostname is the fully qualified domain name of a network host. This matches the RFC 1123 definition of a hostname with 1 notable exception that numeric IP addresses are not allowed. Note that as per RFC1035 and RFC1123, a *label* must consist of lower case alphanumeric characters or ''-'', and must start and end with an alphanumeric character. No other punctuation is allowed.' maxLength: 253 minLength: 1 pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$ type: string path: description: 'Path defines parameters used to modify the path of the incoming request. The modified path is then used to construct the location header. When empty, the request path is used as-is.' properties: replaceFullPath: type: string replacePrefixMatch: type: string type: enum: - ReplaceFullPath - ReplacePrefixMatch type: string required: - type type: object port: description: 'Port is the port to be used in the value of the `Location` header in the response. When empty, port (if specified) of the request is used.' format: int32 maximum: 65535 minimum: 1 type: integer scheme: enum: - http - https type: string statusCode: default: 302 description: StatusCode is the HTTP status code to be used in response. enum: - 301 - 302 - 303 - 307 - 308 type: integer type: object responseHeaderModifier: description: 'Only one action is supported per header name. Configuration to set or add multiple values for a header must use RFC 7230 header value formatting, separating each value with a comma.' properties: add: items: properties: name: maxLength: 256 minLength: 1 pattern: ^[a-z0-9!#$%&'*+\-.^_\x60|~]+$ type: string value: type: string required: - name - value type: object maxItems: 16 type: array x-kubernetes-list-map-keys: - name x-kubernetes-list-type: map remove: items: type: string maxItems: 16 type: array set: items: properties: name: maxLength: 256 minLength: 1 pattern: ^[a-z0-9!#$%&'*+\-.^_\x60|~]+$ type: string value: type: string required: - name - value type: object maxItems: 16 type: array x-kubernetes-list-map-keys: - name x-kubernetes-list-type: map type: object type: enum: - RequestHeaderModifier - ResponseHeaderModifier - RequestRedirect - URLRewrite - RequestMirror type: string urlRewrite: properties: hostToBackendHostname: description: 'HostToBackendHostname rewrites the hostname to the hostname of the upstream host. This option is only available when targeting MeshGateways.' type: boolean hostname: description: Hostname is the value to be used to replace the host header value during forwarding. maxLength: 253 minLength: 1 pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$ type: string path: description: Path defines a path rewrite. properties: replaceFullPath: type: string replacePrefixMatch: type: string type: enum: - ReplaceFullPath - ReplacePrefixMatch type: string required: - type type: object type: object required: - type type: object type: array type: object matches: description: 'Matches describes how to match HTTP requests this rule should be applied to.' items: properties: headers: items: description: 'HeaderMatch describes how to select an HTTP route by matching HTTP request headers.' properties: name: description: 'Name is the name of the HTTP Header to be matched. Name MUST be lower case as they will be handled with case insensitivity (See https://tools.ietf.org/html/rfc7230#section-3.2).' maxLength: 256 minLength: 1 pattern: ^[a-z0-9!#$%&'*+\-.^_\x60|~]+$ type: string type: default: Exact description: Type specifies how to match against the value of the header. enum: - Exact - Present - RegularExpression - Absent - Prefix type: string value: description: Value is the value of HTTP Header to be matched. type: string required: - name type: object type: array method: enum: - CONNECT - DELETE - GET - HEAD - OPTIONS - PATCH - POST - PUT - TRACE type: string path: properties: type: enum: - Exact - PathPrefix - RegularExpression type: string value: description: 'Exact or prefix matches must be an absolute path. A prefix matches only if separated by a slash or the entire path.' minLength: 1 type: string required: - type - value type: object queryParams: description: 'QueryParams matches based on HTTP URL query parameters. Multiple matches are ANDed together such that all listed matches must succeed.' items: properties: name: minLength: 1 type: string type: enum: - Exact - RegularExpression type: string value: type: string required: - name - type - value type: object type: array type: object minItems: 1 type: array required: - default - matches type: object type: array targetRef: description: 'TargetRef is a reference to the resource that represents a group of request destinations.' properties: kind: description: Kind of the referenced resource enum: - Mesh - MeshSubset - MeshGateway - MeshService - MeshExternalService - MeshMultiZoneService - MeshServiceSubset - MeshHTTPRoute - Dataplane type: string labels: additionalProperties: type: string description: 'Labels are used to select group of MeshServices that match labels. Either Labels or Name and Namespace can be used.' type: object mesh: description: Mesh is reserved for future use to identify cross mesh resources. type: string name: description: 'Name of the referenced resource. Can only be used with kinds: `MeshService`, `MeshServiceSubset` and `MeshGatewayRoute`' type: string namespace: description: 'Namespace specifies the namespace of target resource. If empty only resources in policy namespace will be targeted.' type: string proxyTypes: description: 'ProxyTypes specifies the data plane types that are subject to the policy. When not specified, all data plane types are targeted by the policy.' items: enum: - Sidecar - Gateway type: string type: array sectionName: description: 'SectionName is used to target specific section of resource. For example, you can target port from MeshService.ports[] by its name. Only traffic to this port will be affected.' type: string tags: additionalProperties: type: string description: 'Tags used to select a subset of proxies by tags. Can only be used with kinds `MeshSubset` and `MeshServiceSubset`' type: object required: - kind type: object required: - rules - targetRef type: object type: array type: object creationTime: readOnly: true type: string description: Time at which the resource was created format: date-time example: '0001-01-01T00:00:00Z' modificationTime: readOnly: true type: string description: Time at which the resource was updated format: date-time example: '0001-01-01T00:00:00Z' Error: type: object title: Error description: 'Standard error. Follows the [AIP #193 - Errors](https://kong-aip.netlify.app/aip/193/) specification. ' x-examples: Example 1: status: 404 title: Not Found type: https://kongapi.info/konnect/not-found instance: portal:trace:2287285207635123011 detail: The requested document was not found required: - status - title - instance - type - detail properties: status: type: integer description: The HTTP status code. example: 404 title: type: string description: 'A short, human-readable summary of the problem. It **should not** change between occurrences of a problem, except for localization. Should be provided as "Sentence case" for potential direct use in a UI ' example: Not Found type: type: string description: 'A unique identifier for this error. When dereferenced it must provide human-readable documentation for the problem. ' example: Not Found instance: type: string example: portal:trace:2287285207635123011 description: 'Used to return the correlation ID back to the user, in the format `:trace:`. ' detail: type: string example: The requested team was not found description: 'A human readable explanation specific to this occurrence of the problem. This field may contain request/entity data to help the user understand what went wrong. Enclose variable values in square brackets. _Should_ be provided as "Sentence case" for direct use in a UI ' invalid_parameters: type: array description: 'All 400 errors **MUST** return an `invalid_parameters` key in the response. Used to indicate which fields have invalid values when validated. ' items: $ref: '#/components/schemas/InvalidParameters' securitySchemes: BasicAuth: type: http scheme: basic BearerAuth: type: http scheme: bearer