---
title: "Creates or Updates MeshExternalService entity"
method: PUT
path: "/v1/mesh/control-planes/{cpId}/api/meshes/{mesh}/meshexternalservices/{name}"
tags: ["MeshExternalService"]
---

# Creates or Updates MeshExternalService entity

`PUT /v1/mesh/control-planes/{cpId}/api/meshes/{mesh}/meshexternalservices/{name}`

## Request

- Base URL: `https://global.api.konghq.com`
- URL: `https://global.api.konghq.com/v1/mesh/control-planes/{cpId}/api/meshes/{mesh}/meshexternalservices/{name}`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer
  - HTTP bearer
  - HTTP bearer

## Path parameters

- `mesh` string, required
- `name` string, required

## Request body

- MeshExternalServiceItem: 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.
  - `type` 'MeshExternalService', required: the type of the resource
  - `mesh` string: Mesh is the name of the Kuma mesh this resource belongs to. It may be omitted for cluster-scoped resources.
  - `kri` string: 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
  - `snis` object[]: List of SNIs (Server Name Indication) advertised by xDS for this destination, one entry per port, sorted by port ascending. Present for MeshService, MeshMultiZoneService and MeshExternalService.
    - `port` integer, required: The destination port this SNI corresponds to.
    - `sni` string, required: The SNI string advertised by xDS for this port.
  - `name` string, required: Name of the Kuma resource
  - `labels` object: The labels to help identity resources
  - `spec` object, required: Spec is the specification of the Kuma MeshExternalService resource.
    - `endpoints` object[]: Endpoints defines a list of destinations to send traffic to.
      - `address` string, required: Address defines an address to which a user want to send a request. Is possible to provide `domain`, `ip`.
      - `port` integer, required: Port of the endpoint
      - `priority` integer: 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.
    - `extension` object: 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.
      - `config` unknown
      - `type` string, required: Type of the extension.
    - `match` object, required: Match defines traffic that should be routed through the sidecar.
      - `port` integer, required: Port defines a port to which a user does request.
      - `protocol` 'tcp' | 'grpc' | 'http' | 'http2': Protocol defines a protocol of the communication. Possible values: `tcp`, `grpc`, `http`, `http2`.
      - `type` 'HostnameGenerator': Type of the match, only `HostnameGenerator` is available at the moment.
    - `tls` object: Tls provides a TLS configuration when proxy is resposible for a TLS origination
      - `allowRenegotiation` boolean: AllowRenegotiation defines if TLS sessions will allow renegotiation. Setting this to true is not recommended for security reasons.
      - `enabled` boolean: Enabled defines if proxy should originate TLS.
      - `verification` object: Verification section for providing TLS verification details.
        - `caCert` object: CaCert defines a certificate of CA.
          - `inline` string, byte: Data source is inline bytes.
          - `inlineString` string: Data source is inline string`
          - `secret` string: Data source is a secret with given Secret key.
        - `clientCert` object: ClientCert defines a certificate of a client.
          - `inline` string, byte: Data source is inline bytes.
          - `inlineString` string: Data source is inline string`
          - `secret` string: Data source is a secret with given Secret key.
        - `clientKey` object: ClientKey defines a client private key.
          - `inline` string, byte: Data source is inline bytes.
          - `inlineString` string: Data source is inline string`
          - `secret` string: Data source is a secret with given Secret key.
        - `mode` 'SkipSAN' | 'SkipCA' | 'Secured' | 'SkipAll': Mode defines if proxy should skip verification, one of `SkipSAN`, `SkipCA`, `Secured`, `SkipAll`. Default `Secured`.
        - `serverName` string: ServerName overrides the default Server Name Indicator set by Kuma.
        - `subjectAltNames` object[]: SubjectAltNames list of names to verify in the certificate.
          - `type` 'Exact' | 'Prefix': Type specifies matching type, one of `Exact`, `Prefix`. Default: `Exact`
          - `value` string, required: Value to match.
      - `version` object: Version section for providing version specification.
        - `max` 'TLSAuto' | 'TLS10' | 'TLS11' | 'TLS12' | 'TLS13': Max defines maximum supported version. One of `TLSAuto`, `TLS10`, `TLS11`, `TLS12`, `TLS13`.
        - `min` 'TLSAuto' | 'TLS10' | 'TLS11' | 'TLS12' | 'TLS13': Min defines minimum supported version. One of `TLSAuto`, `TLS10`, `TLS11`, `TLS12`, `TLS13`.
  - `creationTime` string, date-time: Time at which the resource was created
  - `modificationTime` string, date-time: Time at which the resource was updated
  - `status` object: Status is the current status of the Kuma MeshExternalService resource.
    - `addresses` object[]: Addresses section for generated domains
      - `hostname` string
      - `hostnameGeneratorRef` object
        - `coreName` string, required
      - `origin` string
    - `hostnameGenerators` object[]
      - `conditions` object[]: Conditions is an array of hostname generator conditions.
        - `message` string, required: message is a human readable message indicating details about the transition. This may be an empty string.
        - `reason` string, required: 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.
        - `status` 'True' | 'False' | 'Unknown', required: status of the condition, one of True, False, Unknown.
        - `type` string, required: type of condition in CamelCase or in foo.example.com/CamelCase.
      - `hostnameGeneratorRef` object, required
        - `coreName` string, required
    - `vip` object: Vip section for allocated IP
      - `ip` string: Value allocated IP for a provided domain with `HostnameGenerator` type in a match section.

## Response `200`

Successful response

- object
  - `warnings` string[]: 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.

## Other responses

- `201`: Successful response

## Changes

- **2026-08-18** `658ffb748f95`: 1 info
  - added the new optional request property `spec/endpoints/items/priority`
- **2025-10-02** `ecce2daf9de6`: 2 breaking
  - the `spec/endpoints/items/port` request property format changed from no format to `int32`
  - the `spec/match/port` request property format changed from no format to `int32`
- **2025-08-12** `b2800570b3e2`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/kong/apis/konnect-api-beta/changes/v1/mesh/control-planes/:cpId/api/meshes/:mesh/meshexternalservices/:name/put.md)

---

[API](https://skmtc.dev/kong/apis/konnect-api-beta.md) - [All operations](https://skmtc.dev/kong/apis/konnect-api-beta/llms.txt) - [OpenAPI document](https://skmtc.dev/kong/apis/konnect-api-beta/revisions/cef0f947e9c9?raw)