The MeshExternalService API from Kuma — 2 operation(s) for meshexternalservice.
openapi: 3.1.0
info:
title: Kuma Dataplane MeshExternalService API
description: Kuma API
version: v1alpha1
x-ref-schema-name: DataplaneOverview
security:
- BasicAuth: []
- BearerAuth: []
- {}
tags:
- name: MeshExternalService
paths:
/meshes/{mesh}/meshexternalservices/{name}:
get:
operationId: getMeshExternalService
summary: Returns MeshExternalService entity
tags:
- MeshExternalService
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 MeshExternalService
responses:
'200':
$ref: '#/components/responses/MeshExternalServiceItem'
'404':
$ref: '#/components/responses/NotFound'
put:
operationId: putMeshExternalService
summary: Creates or Updates MeshExternalService entity
tags:
- MeshExternalService
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 MeshExternalService
requestBody:
description: Put request
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/MeshExternalServiceItem'
responses:
'200':
$ref: '#/components/responses/MeshExternalServiceCreateOrUpdateSuccessResponse'
'201':
$ref: '#/components/responses/MeshExternalServiceCreateOrUpdateSuccessResponse'
delete:
operationId: deleteMeshExternalService
summary: Deletes MeshExternalService entity
tags:
- MeshExternalService
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 MeshExternalService
responses:
'200':
$ref: '#/components/responses/MeshExternalServiceDeleteSuccessResponse'
'404':
$ref: '#/components/responses/NotFound'
/meshes/{mesh}/meshexternalservices:
get:
operationId: getMeshExternalServiceList
summary: Returns a list of MeshExternalService in the mesh.
tags:
- MeshExternalService
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/MeshExternalServiceList'
components:
schemas:
MeshExternalServiceItem:
type: object
description: MeshExternalService represents external services (outside the mesh) that mesh services can communicate with securely. It enables mesh services to reach external APIs, databases, or third-party services by defining endpoints, ports, protocols, and optional TLS configuration for secure outbound connections with hostname-based routing support.
required:
- type
- name
- spec
properties:
type:
description: the type of the resource
type: string
enum:
- MeshExternalService
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_extsvc_default_zone-east_kuma-system_myresource1_
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 MeshExternalService resource.
properties:
endpoints:
description: Endpoints defines a list of destinations to send traffic to.
items:
properties:
address:
description: Address defines an address to which a user want to send a request. Is possible to provide `domain`, `ip`.
example: example.com
minLength: 1
type: string
port:
description: Port of the endpoint
format: int32
maximum: 65535
minimum: 1
type: integer
priority:
description: 'Priority maps to Envoy''s priority levels to enable endpoint failover.
Lower values have higher priority (0 is the default/primary).
When the primary endpoints become unhealthy, traffic fails over to the next priority level.'
format: int32
maximum: 128
minimum: 0
type: integer
required:
- address
- port
type: object
type: array
extension:
description: Extension struct for a plugin configuration, in the presence of an extension `endpoints` and `tls` are not required anymore - it's up to the extension to validate them independently.
properties:
config:
description: Config freeform configuration for the extension.
x-kubernetes-preserve-unknown-fields: true
type:
description: Type of the extension.
type: string
required:
- type
type: object
match:
description: Match defines traffic that should be routed through the sidecar.
properties:
port:
description: Port defines a port to which a user does request.
format: int32
maximum: 65535
minimum: 1
type: integer
protocol:
default: tcp
description: 'Protocol defines a protocol of the communication. Possible values: `tcp`, `grpc`, `http`, `http2`.'
enum:
- tcp
- grpc
- http
- http2
type: string
type:
default: HostnameGenerator
description: Type of the match, only `HostnameGenerator` is available at the moment.
enum:
- HostnameGenerator
type: string
required:
- port
type: object
tls:
description: Tls provides a TLS configuration when proxy is resposible for a TLS origination
properties:
allowRenegotiation:
default: false
description: 'AllowRenegotiation defines if TLS sessions will allow renegotiation.
Setting this to true is not recommended for security reasons.'
type: boolean
enabled:
default: false
description: Enabled defines if proxy should originate TLS.
type: boolean
verification:
description: Verification section for providing TLS verification details.
properties:
caCert:
description: CaCert defines a certificate of CA.
properties:
inline:
description: Data source is inline bytes.
format: byte
type: string
inlineString:
description: Data source is inline string`
type: string
secret:
description: Data source is a secret with given Secret key.
type: string
type: object
clientCert:
description: ClientCert defines a certificate of a client.
properties:
inline:
description: Data source is inline bytes.
format: byte
type: string
inlineString:
description: Data source is inline string`
type: string
secret:
description: Data source is a secret with given Secret key.
type: string
type: object
clientKey:
description: ClientKey defines a client private key.
properties:
inline:
description: Data source is inline bytes.
format: byte
type: string
inlineString:
description: Data source is inline string`
type: string
secret:
description: Data source is a secret with given Secret key.
type: string
type: object
mode:
default: Secured
description: Mode defines if proxy should skip verification, one of `SkipSAN`, `SkipCA`, `Secured`, `SkipAll`. Default `Secured`.
enum:
- SkipSAN
- SkipCA
- Secured
- SkipAll
type: string
serverName:
description: ServerName overrides the default Server Name Indicator set by Kuma.
type: string
subjectAltNames:
description: SubjectAltNames list of names to verify in the certificate.
items:
properties:
type:
default: Exact
description: 'Type specifies matching type, one of `Exact`, `Prefix`. Default: `Exact`'
enum:
- Exact
- Prefix
type: string
value:
description: Value to match.
type: string
required:
- value
type: object
type: array
type: object
version:
description: Version section for providing version specification.
properties:
max:
default: TLSAuto
description: Max defines maximum supported version. One of `TLSAuto`, `TLS10`, `TLS11`, `TLS12`, `TLS13`.
enum:
- TLSAuto
- TLS10
- TLS11
- TLS12
- TLS13
type: string
min:
default: TLSAuto
description: Min defines minimum supported version. One of `TLSAuto`, `TLS10`, `TLS11`, `TLS12`, `TLS13`.
enum:
- TLSAuto
- TLS10
- TLS11
- TLS12
- TLS13
type: string
type: object
type: object
required:
- match
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'
status:
description: Status is the current status of the Kuma MeshExternalService resource.
properties:
addresses:
description: Addresses section for generated domains
items:
properties:
hostname:
type: string
hostnameGeneratorRef:
properties:
coreName:
type: string
required:
- coreName
type: object
origin:
type: string
type: object
type: array
hostnameGenerators:
items:
properties:
conditions:
description: Conditions is an array of hostname generator conditions.
items:
properties:
message:
description: 'message is a human readable message indicating details about the transition.
This may be an empty string.'
maxLength: 32768
type: string
reason:
description: 'reason contains a programmatic identifier indicating the reason for the condition''s last transition.
Producers of specific condition types may define expected values and meanings for this field,
and whether the values are considered a guaranteed API.
The value should be a CamelCase string.
This field may not be empty.'
maxLength: 1024
minLength: 1
pattern: ^[A-Za-z]([A-Za-z0-9_,:]*[A-Za-z0-9_])?$
type: string
status:
description: status of the condition, one of True, False, Unknown.
enum:
- 'True'
- 'False'
- Unknown
type: string
type:
description: type of condition in CamelCase or in foo.example.com/CamelCase.
maxLength: 316
pattern: ^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*/)?(([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9])$
type: string
required:
- message
- reason
- status
- type
type: object
type: array
x-kubernetes-list-map-keys:
- type
x-kubernetes-list-type: map
hostnameGeneratorRef:
properties:
coreName:
type: string
required:
- coreName
type: object
required:
- hostnameGeneratorRef
type: object
type: array
vip:
description: Vip section for allocated IP
properties:
ip:
description: Value allocated IP for a provided domain with `HostnameGenerator` type in a match section.
type: string
type: object
type: object
readOnly: true
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
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 `<app>:trace:<correlation_id>`.
'
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'
responses:
NotFound:
description: Not Found
content:
application/problem+json:
schema:
$ref: '#/components/schemas/NotFoundError'
MeshExternalServiceItem:
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/MeshExternalServiceItem'
MeshExternalServiceDeleteSuccessResponse:
description: Successful response
content:
application/json:
schema:
type: object
MeshExternalServiceCreateOrUpdateSuccessResponse:
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
MeshExternalServiceList:
description: List
content:
application/json:
schema:
type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/MeshExternalServiceItem'
total:
type: number
description: The total number of entities
next:
type: string
description: URL to the next page
securitySchemes:
BasicAuth:
type: http
scheme: basic
BearerAuth:
type: http
scheme: bearer