Sign in
Services

Upsert a Service

Create or Update Service using ID or name.

put/v2/control-planes/{controlPlaneId}/core-entities/services/{ServiceId}

Request body

ca_certificatesstring[] nullable

Array of CA Certificate object UUIDs that are used to build the trust store while verifying upstream server's TLS certificate. If set to null when Nginx default is respected. If default CA list in Nginx are not specified and TLS verification is enabled, then handshake with upstream server will always fail (because no CA are trusted).

connect_timeoutinteger nullable

The timeout in milliseconds for establishing a connection to the upstream server.

created_atinteger nullable

Unix epoch when the resource was created.

enabledboolean nullable

Whether the Service is active. If set to false, the proxy behavior will be as if any routes attached to it do not exist (404). Default: true.

hoststring required

The host of the upstream server. Note that the host value is case sensitive.

idstring nullable

A string representing a UUID (universally unique identifier).

namestring nullable

The Service name.

pathstring nullable

The path to be used in requests to the upstream server.

portinteger nullable

The upstream server port.

protocol'grpc' | 'grpcs' | 'http' | 'https' | 'tcp' | 'tls' | 'tls_passthrough' | 'udp' | 'ws' | 'wss' nullable

The protocol used to communicate with the upstream.

read_timeoutinteger nullable

The timeout in milliseconds between two successive read operations for transmitting a request to the upstream server.

retriesinteger nullable

The number of retries to execute upon failure to proxy.

tagsstring[] nullable

An optional set of strings associated with the Service for grouping and filtering.

tls_verifyboolean nullable

Whether to enable verification of upstream server TLS certificate. If set to null, then the Nginx default is respected.

tls_verify_depthinteger nullable

Maximum depth of chain while verifying Upstream server's TLS certificate. If set to null, then the Nginx default is respected.

updated_atinteger nullable

Unix epoch when the resource was last updated.

urlstring nullable

Helper field to set protocol, host, port and path using a URL. This field is write-only and is not returned in responses.

write_timeoutinteger nullable

The timeout in milliseconds between two successive write operations for transmitting a request to the upstream server.

Example request

{
  "host": "example.internal",
  "id": "49fd316e-c457-481c-9fc7-8079153e4f3c",
  "name": "example-service",
  "path": "/",
  "port": 80,
  "protocol": "http"
}

Response

Successfully upserted Service

ca_certificatesstring[] nullable

Array of CA Certificate object UUIDs that are used to build the trust store while verifying upstream server's TLS certificate. If set to null when Nginx default is respected. If default CA list in Nginx are not specified and TLS verification is enabled, then handshake with upstream server will always fail (because no CA are trusted).

connect_timeoutinteger nullable

The timeout in milliseconds for establishing a connection to the upstream server.

created_atinteger nullable

Unix epoch when the resource was created.

enabledboolean nullable

Whether the Service is active. If set to false, the proxy behavior will be as if any routes attached to it do not exist (404). Default: true.

hoststring required

The host of the upstream server. Note that the host value is case sensitive.

idstring nullable

A string representing a UUID (universally unique identifier).

namestring nullable

The Service name.

pathstring nullable

The path to be used in requests to the upstream server.

portinteger nullable

The upstream server port.

protocol'grpc' | 'grpcs' | 'http' | 'https' | 'tcp' | 'tls' | 'tls_passthrough' | 'udp' | 'ws' | 'wss' nullable

The protocol used to communicate with the upstream.

read_timeoutinteger nullable

The timeout in milliseconds between two successive read operations for transmitting a request to the upstream server.

retriesinteger nullable

The number of retries to execute upon failure to proxy.

tagsstring[] nullable

An optional set of strings associated with the Service for grouping and filtering.

tls_verifyboolean nullable

Whether to enable verification of upstream server TLS certificate. If set to null, then the Nginx default is respected.

tls_verify_depthinteger nullable

Maximum depth of chain while verifying Upstream server's TLS certificate. If set to null, then the Nginx default is respected.

updated_atinteger nullable

Unix epoch when the resource was last updated.

urlstring nullable

Helper field to set protocol, host, port and path using a URL. This field is write-only and is not returned in responses.

write_timeoutinteger nullable

The timeout in milliseconds between two successive write operations for transmitting a request to the upstream server.

Example response

{
  "host": "example.internal",
  "id": "49fd316e-c457-481c-9fc7-8079153e4f3c",
  "name": "example-service",
  "path": "/",
  "port": 80,
  "protocol": "http"
}

Changes

Changed in 7 of the 52 revisions of this API.281248

  • f03059016622112See the full diff
    • ▲

      the id request property's minLength was increased from 0 to 1

      request-property-min-length-increased

    • ●

      the connect_timeout request property's max was set to 2147483646.00

      request-property-max-set

    • ●

      the port request property's max was set to 65535.00

      request-property-max-set

    • ●

      the read_timeout request property's max was set to 2147483646.00

      request-property-max-set

    • ●

      the retries request property's max was set to 32767.00

      request-property-max-set

    • ●

      the tls_verify_depth request property's max was set to 64.00

      request-property-max-set

    • ●

      the write_timeout request property's max was set to 2147483646.00

      request-property-max-set

    • ●

      the connect_timeout request property's min was set to 1.00

      request-property-min-set

    • ●

      the port request property's min was set to 0.00

      request-property-min-set

    • ●

      the read_timeout request property's min was set to 1.00

      request-property-min-set

    • ●

      the retries request property's min was set to 0.00

      request-property-min-set

    • ●

      the tls_verify_depth request property's min was set to 0.00

      request-property-min-set

    • ●

      the write_timeout request property's min was set to 1.00

      request-property-min-set

  • 96118a9cd7f4317See the full diff
    • ▲

      the response property tls_sans/dnsnames became nullable for the status 200

      response-property-became-nullable

    • ▲

      the response property tls_sans/uris became nullable for the status 200

      response-property-became-nullable

    • ▲

      the response property url became nullable for the status 200

      response-property-became-nullable

    • ○

      the request property tls_sans/dnsnames became nullable

      request-property-became-nullable

    • ○

      the request property tls_sans/uris became nullable

      request-property-became-nullable

    • ○

      the request property url became nullable

      request-property-became-nullable

    • ○

      the connect_timeout request property default value 60000 was added

      request-property-default-value-added

    • ○

      the enabled request property default value true was added

      request-property-default-value-added

    • ○

      the port request property default value 80 was added

      request-property-default-value-added

    • ○

      the protocol request property default value http was added

      request-property-default-value-added

    • ○

      the read_timeout request property default value 60000 was added

      request-property-default-value-added

    • ○

      the retries request property default value 5 was added

      request-property-default-value-added

    • ○

      the write_timeout request property default value 60000 was added

      request-property-default-value-added

    • ○

      the connect_timeout response's property default value 60000 was added for the status 200

      response-property-default-value-added

    • ○

      the enabled response's property default value true was added for the status 200

      response-property-default-value-added

    • ○

      the port response's property default value 80 was added for the status 200

      response-property-default-value-added

    • ○

      the protocol response's property default value http was added for the status 200

      response-property-default-value-added

    • ○

      the read_timeout response's property default value 60000 was added for the status 200

      response-property-default-value-added

    • ○

      the retries response's property default value 5 was added for the status 200

      response-property-default-value-added

    • ○

      the write_timeout response's property default value 60000 was added for the status 200

      response-property-default-value-added

    This revision also has 7 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • 2c77aeaee5fb11See the full diff
    • ▲

      the response property tags became nullable for the status 200

      response-property-became-nullable

    • ○

      the request property tags became nullable

      request-property-became-nullable

  • dbc2de5f26632See the full diff
    • ○

      added the new optional request property tls_sans

      new-optional-request-property

    • ○

      added the optional property tls_sans to the response with the 200 status

      response-optional-property-added

  • fc6abbc537f3610See the full diff
    • ▲

      the response property created_at became nullable for the status 200

      response-property-became-nullable

    • ▲

      the response property port became nullable for the status 200

      response-property-became-nullable

    • ▲

      the response property protocol became nullable for the status 200

      response-property-became-nullable

    • ▲

      the response property updated_at became nullable for the status 200

      response-property-became-nullable

    • ▲

      the response property port became optional for the status 200

      response-property-became-optional

    • ▲

      the response property protocol became optional for the status 200

      response-property-became-optional

    • ○

      the request optional property created_at became not read-only

      request-optional-property-became-not-read-only

    • ○

      the request optional property updated_at became not read-only

      request-optional-property-became-not-read-only

    • ○

      the request property created_at became nullable

      request-property-became-nullable

    • ○

      the request property port became nullable

      request-property-became-nullable

    • ○

      the request property protocol became nullable

      request-property-became-nullable

    • ○

      the request property updated_at became nullable

      request-property-became-nullable

    • ○

      the request property port became optional

      request-property-became-optional

    • ○

      the request property protocol became optional

      request-property-became-optional

    • ○

      the response optional property created_at became not read-only for the status 200

      response-optional-property-became-not-read-only

    • ○

      the response optional property updated_at became not read-only for the status 200

      response-optional-property-became-not-read-only

    This revision also has 7 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • 4266633316551See the full diff
    • ▲

      the request property tags became not nullable

      request-property-became-not-nullable

  • 08ead66e9ebb1618See the full diff
    • ▲

      the request property host became required

      request-property-became-required

    • ▲

      the request property port became required

      request-property-became-required

    • ▲

      the request property protocol became required

      request-property-became-required

    • ▲

      the response property ca_certificates became nullable for the status 200

      response-property-became-nullable

    • ▲

      the response property client_certificate became nullable for the status 200

      response-property-became-nullable

    • ▲

      the response property connect_timeout became nullable for the status 200

      response-property-became-nullable

    • ▲

      the response property enabled became nullable for the status 200

      response-property-became-nullable

    • ▲

      the response property id became nullable for the status 200

      response-property-became-nullable

    • ▲

      the response property name became nullable for the status 200

      response-property-became-nullable

    • ▲

      the response property path became nullable for the status 200

      response-property-became-nullable

    • ▲

      the response property read_timeout became nullable for the status 200

      response-property-became-nullable

    • ▲

      the response property retries became nullable for the status 200

      response-property-became-nullable

    • ▲

      the response property tags became nullable for the status 200

      response-property-became-nullable

    • ▲

      the response property tls_verify became nullable for the status 200

      response-property-became-nullable

    • ▲

      the response property tls_verify_depth became nullable for the status 200

      response-property-became-nullable

    • ▲

      the response property write_timeout became nullable for the status 200

      response-property-became-nullable

    • ○

      the request optional property id became not read-only

      request-optional-property-became-not-read-only

    • ○

      the request property ca_certificates became nullable

      request-property-became-nullable

    • ○

      the request property client_certificate became nullable

      request-property-became-nullable

    • ○

      the request property connect_timeout became nullable

      request-property-became-nullable

    • ○

      the request property enabled became nullable

      request-property-became-nullable

    • ○

      the request property id became nullable

      request-property-became-nullable

    • ○

      the request property name became nullable

      request-property-became-nullable

    • ○

      the request property path became nullable

      request-property-became-nullable

    • ○

      the request property read_timeout became nullable

      request-property-became-nullable

    • ○

      the request property retries became nullable

      request-property-became-nullable

    • ○

      the request property tags became nullable

      request-property-became-nullable

    • ○

      the request property tls_verify became nullable

      request-property-became-nullable

    • ○

      the request property tls_verify_depth became nullable

      request-property-became-nullable

    • ○

      the request property write_timeout became nullable

      request-property-became-nullable

    • ○

      the response optional property id became not read-only for the status 200

      response-optional-property-became-not-read-only

    • ○

      the response property host became required for the status 200

      response-property-became-required

    • ○

      the response property port became required for the status 200

      response-property-became-required

    • ○

      the response property protocol became required for the status 200

      response-property-became-required

    This revision also has 88 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog