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 `: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' 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