Create a service on a gateway group

POST /apisix/admin/services

Create a service on a gateway group

Create a service through an APISIX Admin API compatible endpoint under /apisix/admin/. The payload follows APISIX conventions while operating on the same underlying service resource managed by dashboard APIs. Required IAM Permission: Action gateway:CreatePublishedService, Resource arn:api7:gateway:gatewaygroup/%s/service/*

Parameters

• gateway_group_id (query, string, required): Gateway group ID. Optional when using the gateway group admin key to authenticate.

Request body

Content type: application/json

• allOf variant 1

• oneOf variant 1: HTTP

• allOf variant 1

• name (string, optional): The object name.

• labels (object, optional): Key-value pairs of labels.

• desc (string, optional): The object description.

• type (string, optional): Type of service. http corresponds to L7 service and stream corresponds to L4 service.

• allOf variant 2

• type (string, required):

• hosts (array, optional): The hosts of the service to accept incoming requests.

• path_prefix (string, optional): The listening path prefix of the service.

• strip_path_prefix (boolean, optional): If true, strip the path prefix when proxying the request to the upstream.

• plugins (object, optional): Key-value pairs of plugins and their configurations on the object.

• allOf variant 3

• upstream (object, optional): The upstream contains necessary information for the gateway to proxy request to the backend service.

• upstream.name (string, optional): The upstream name.

• upstream.scheme (string, optional): The protocol that is used for communicating with the backend service when the service type is http.

• upstream.desc (string, optional): The object description.

• upstream.labels (object, optional): Key-value pairs of labels.

• upstream.type (string, optional): Load balancing algorithm to distribute traffic.

• upstream.hash_on (string, optional): Type of value to hash on when type is chash.

• upstream.key (string, optional): The key is used when type is chash. The corresponding upstream ID is determined based on the hash_on and key values. - When hash_on is set to vars, key is required and supports built-in variables. - When hash_on is set to vars_combinations, key is required and supports a combination of built-in variables. - When hash_on is set to header, key is required and should be the name of the header. - When hash_on is set to cookie, key is required and should be the name of the cookie. - When hash_on is set to consumer, key is not required, as the hash algorithm uses the authenticated consumer name.

• upstream.retries (integer, optional): The number of retries while passing the request to an upstream.

• upstream.keepalive_pool (object, optional): Upstream keepalive connection pool.

• upstream.keepalive_pool.size (integer, optional): The number of idle keepalive connections per worker to upstream servers.

• upstream.keepalive_pool.idle_timeout (number, optional): Time an idle keepalive connection remains open before being closed, in seconds.

• upstream.keepalive_pool.requests (integer, optional): The number of requests a single keepalive connection can handle before closing.

• upstream.timeout (object, optional): Timeout settings for connecting to, sending, and receiving messages from the upstream, in seconds.

• upstream.timeout.connect (number, optional): Connection timeout in seconds.

• upstream.timeout.send (number, optional): Sending timeout in seconds.

• upstream.timeout.read (number, optional): Receiving timeout in seconds.

• upstream.retry_timeout (number, optional): Timeout to continue with retries. Setting this to 0 disables the retry timeout.

• upstream.pass_host (string, optional): The approach to decide the host header before forwarding requests to an upstream.

• pass uses the host specified in the service.
• node uses the host specified in the upstream.
• rewrite uses custom host.

• upstream.upstream_host (string, optional): Value to rewrite the host header to. Only used if pass_host is rewrite.
• upstream.nodes (array, optional): The upstream endpoints.
• upstream.nodes[].host (string, required): Upstream host.
• upstream.nodes[].port (integer, required): Upstream port.
• upstream.nodes[].weight (integer, required): Upstream weight.
• upstream.nodes[].priority (integer, optional): Node priority. A higher value corresponds to a higher priority.
• upstream.service_name (string, optional): Service name in the service registry. Only valid for service discovery.
• upstream.discovery_type (string, optional): Type of service discovery. Only valid for service discovery.
• upstream.discovery_args (object, optional): Service discovery arguments. Only valid for service discovery.
• upstream.discovery_args.metadata (object, optional):
• upstream.tls (object, optional): Replace with client_certificate and ca_certificates
• oneOf variant 1
• upstream.tls.client_cert (string, required): The certificate in PEM format.
• upstream.tls.client_key (string, required): The private key in PEM format.
• oneOf variant 2
• upstream.tls.client_cert_id (string, required): The object ID.
• upstream.client_certificate (string, optional): The object ID.
• upstream.ca_certificates (array, optional): CA certificates.
• upstream.tls_verify (boolean, optional): If true, verify TLS.
• upstream.checks (object, optional): Health check configurations.
• anyOf variant 1: Active Check
• upstream.checks.active (object, required): Active health check configurations.
• upstream.checks.active.type (string, optional): Active check probing type.
• upstream.checks.active.timeout (number, optional): Active check timeout in seconds.
• upstream.checks.active.concurrency (integer, optional): The number of targets to be checked at the same time during the active check.
• upstream.checks.active.host (string, optional): The HTTP host.
• upstream.checks.active.port (integer, optional): By default, the port is the same as the one defined in the upstream target.
• upstream.checks.active.http_path (string, optional): The HTTP path in HTTP probe requests.
• upstream.checks.active.https_verify_certificate (boolean, optional): Whether to verify the target's TLS certificate.
• upstream.checks.active.req_headers (array, optional): The request headers.
• upstream.checks.active.healthy (object, optional): Active health check healthy configurations.
• upstream.checks.active.healthy.interval (integer, optional): Time interval of checking healthy targets in seconds.
• upstream.checks.active.healthy.http_statuses (array, optional): A list of HTTP response status codes which are considered healthy.
• upstream.checks.active.healthy.successes (integer, optional): The number of successful probes to define a healthy target.
• upstream.checks.active.unhealthy (object, optional): Active health check unhealthy configurations.
• upstream.checks.active.unhealthy.interval (integer, optional): Time interval of checking unhealthy targets in seconds.
• upstream.checks.active.unhealthy.http_statuses (array, optional): A list of HTTP response status codes which are considered unhealthy.
• upstream.checks.active.unhealthy.http_failures (integer, optional): The number of HTTP-related failures to define an unhealthy target.
• upstream.checks.active.unhealthy.tcp_failures (integer, optional): The number of TCP-related failures to define an unhealthy target.
• upstream.checks.active.unhealthy.timeouts (integer, optional): The number of probe timeouts to define an unhealthy target.
• anyOf variant 2: Passive Check
• upstream.checks.active (object, required): Active health check configurations.
• upstream.checks.active.type (string, optional): Active check probing type.
• upstream.checks.active.timeout (number, optional): Active check timeout in seconds.
• upstream.checks.active.concurrency (integer, optional): The number of targets to be checked at the same time during the active check.
• upstream.checks.active.host (string, optional): The HTTP host.
• upstream.checks.active.port (integer, optional): By default, the port is the same as the one defined in the upstream target.
• upstream.checks.active.http_path (string, optional): The HTTP path in HTTP probe requests.
• upstream.checks.active.https_verify_certificate (boolean, optional): Whether to verify the target's TLS certificate.
• upstream.checks.active.req_headers (array, optional): The request headers.
• upstream.checks.active.healthy (object, optional): Active health check healthy configurations.
• upstream.checks.active.healthy.interval (integer, optional): Time interval of checking healthy targets in seconds.
• upstream.checks.active.healthy.http_statuses (array, optional): A list of HTTP response status codes which are considered healthy.
• upstream.checks.active.healthy.successes (integer, optional): The number of successful probes to define a healthy target.
• upstream.checks.active.unhealthy (object, optional): Active health check unhealthy configurations.
• upstream.checks.active.unhealthy.interval (integer, optional): Time interval of checking unhealthy targets in seconds.
• upstream.checks.active.unhealthy.http_statuses (array, optional): A list of HTTP response status codes which are considered unhealthy.
• upstream.checks.active.unhealthy.http_failures (integer, optional): The number of HTTP-related failures to define an unhealthy target.
• upstream.checks.active.unhealthy.tcp_failures (integer, optional): The number of TCP-related failures to define an unhealthy target.
• upstream.checks.active.unhealthy.timeouts (integer, optional): The number of probe timeouts to define an unhealthy target.
• upstream.checks.passive (object, required): Passive health check configurations.
• upstream.checks.passive.type (string, optional): Active check probing type.
• upstream.checks.passive.healthy (object, optional): Passive health check healthy configurations.
• upstream.checks.passive.healthy.http_statuses (array, optional): A list of HTTP response status codes which are considered healthy.
• upstream.checks.passive.healthy.successes (integer, optional): The number of successful probes to define a healthy target.
• upstream.checks.passive.unhealthy (object, optional): Passive health check unhealthy configurations.
• upstream.checks.passive.unhealthy.http_statuses (array, optional): A list of HTTP response status codes which are considered unhealthy.
• upstream.checks.passive.unhealthy.tcp_failures (integer, optional): The number of TCP-related failures to define an unhealthy target.
• upstream.checks.passive.unhealthy.timeouts (integer, optional): The number of probe timeouts to define an unhealthy target.
• upstream.checks.passive.unhealthy.http_failures (integer, optional): The number of HTTP-related failures to define an unhealthy target.
• oneOf variant 1: Use Upstream Nodes
• oneOf variant 2: Use Service Registry
• oneOf variant 2: Stream
• allOf variant 1
• name (string, optional): The object name.
• labels (object, optional): Key-value pairs of labels.
• desc (string, optional): The object description.
• type (string, optional): Type of service. http corresponds to L7 service and stream corresponds to L4 service.
• allOf variant 2
• type (string, required): Type of service. stream corresponds to L4 service.
• plugins (object, optional): Key-value pairs of plugins and their configurations on the object.
• allOf variant 3
• upstream (object, optional): Upstream configurations.
• upstream.name (string, optional): The object name.
• upstream.scheme (string, optional): The protocol that is used for communicating with the backend service when the service type is stream. Use tls to make the gateway establish a TLS session with the backend service. The gateway does not verify the backend certificate for a stream upstream.
• upstream.desc (string, optional): The object description.
• upstream.labels (object, optional): Key-value pairs of labels.
• upstream.type (string, optional): Load balancing algorithm to distribute traffic.
• upstream.hash_on (string, optional): Type of value to hash on when type is chash.
• upstream.key (string, optional): The key is used when type is chash. The corresponding upstream ID is determined based on the hash_on and key values. - When hash_on is set to vars, key is required and supports built-in variables. - When hash_on is set to vars_combinations, key is required and supports a combination of built-in variables. - When hash_on is set to header, key is required and should be the name of the header. - When hash_on is set to cookie, key is required and should be the name of the cookie. - When hash_on is set to consumer, key is not required, as the hash algorithm uses the authenticated consumer name.
• upstream.retries (integer, optional): The number of retries while passing the request to an upstream using the underlying Nginx mechanism.
• upstream.retry_timeout (number, optional): Timeout to continue with retries. Setting this to 0 disables the retry timeout.
• upstream.timeout (object, optional): Timeout settings for connecting to, sending, and receiving messages from the upstream, in seconds.
• upstream.timeout.connect (number, optional): Connection timeout in seconds.
• upstream.timeout.send (number, optional): Sending timeout in seconds.
• upstream.timeout.read (number, optional): Receiving timeout in seconds.
• upstream.nodes (array, optional): The upstream endpoints.
• upstream.nodes[].host (string, required): Upstream host.
• upstream.nodes[].port (integer, required): Upstream port.
• upstream.nodes[].weight (integer, required): Upstream weight.
• upstream.nodes[].priority (integer, optional): Node priority. A higher value corresponds to a higher priority.
• upstream.checks (object, optional): Health check configurations.
• anyOf variant 1: Active Check
• upstream.checks.active (object, required): Active health check configurations.
• upstream.checks.active.type (string, optional): Active check probing type.
• upstream.checks.active.timeout (number, optional): Active check timeout in seconds.
• upstream.checks.active.concurrency (integer, optional): The number of targets to be checked at the same time during the active check.
• upstream.checks.active.host (string, optional): The HTTP host.
• upstream.checks.active.port (integer, optional): By default, the port is the same as the one defined in the upstream target.
• upstream.checks.active.http_path (string, optional): The HTTP path in HTTP probe requests.
• upstream.checks.active.https_verify_certificate (boolean, optional): Whether to verify the target's TLS certificate.
• upstream.checks.active.req_headers (array, optional): The request headers.
• upstream.checks.active.healthy (object, optional): Active health check healthy configurations.
• upstream.checks.active.healthy.interval (integer, optional): Time interval of checking healthy targets in seconds.
• upstream.checks.active.healthy.http_statuses (array, optional): A list of HTTP response status codes which are considered healthy.
• upstream.checks.active.healthy.successes (integer, optional): The number of successful probes to define a healthy target.
• upstream.checks.active.unhealthy (object, optional): Active health check unhealthy configurations.
• upstream.checks.active.unhealthy.interval (integer, optional): Time interval of checking unhealthy targets in seconds.
• upstream.checks.active.unhealthy.http_statuses (array, optional): A list of HTTP response status codes which are considered unhealthy.
• upstream.checks.active.unhealthy.http_failures (integer, optional): The number of HTTP-related failures to define an unhealthy target.
• upstream.checks.active.unhealthy.tcp_failures (integer, optional): The number of TCP-related failures to define an unhealthy target.
• upstream.checks.active.unhealthy.timeouts (integer, optional): The number of probe timeouts to define an unhealthy target.
• anyOf variant 2: Passive Check
• upstream.checks.active (object, required): Active health check configurations.
• upstream.checks.active.type (string, optional): Active check probing type.
• upstream.checks.active.timeout (number, optional): Active check timeout in seconds.
• upstream.checks.active.concurrency (integer, optional): The number of targets to be checked at the same time during the active check.
• upstream.checks.active.host (string, optional): The HTTP host.
• upstream.checks.active.port (integer, optional): By default, the port is the same as the one defined in the upstream target.
• upstream.checks.active.http_path (string, optional): The HTTP path in HTTP probe requests.
• upstream.checks.active.https_verify_certificate (boolean, optional): Whether to verify the target's TLS certificate.
• upstream.checks.active.req_headers (array, optional): The request headers.
• upstream.checks.active.healthy (object, optional): Active health check healthy configurations.
• upstream.checks.active.healthy.interval (integer, optional): Time interval of checking healthy targets in seconds.
• upstream.checks.active.healthy.http_statuses (array, optional): A list of HTTP response status codes which are considered healthy.
• upstream.checks.active.healthy.successes (integer, optional): The number of successful probes to define a healthy target.
• upstream.checks.active.unhealthy (object, optional): Active health check unhealthy configurations.
• upstream.checks.active.unhealthy.interval (integer, optional): Time interval of checking unhealthy targets in seconds.
• upstream.checks.active.unhealthy.http_statuses (array, optional): A list of HTTP response status codes which are considered unhealthy.
• upstream.checks.active.unhealthy.http_failures (integer, optional): The number of HTTP-related failures to define an unhealthy target.
• upstream.checks.active.unhealthy.tcp_failures (integer, optional): The number of TCP-related failures to define an unhealthy target.
• upstream.checks.active.unhealthy.timeouts (integer, optional): The number of probe timeouts to define an unhealthy target.
• upstream.checks.passive (object, required): Passive health check configurations.
• upstream.checks.passive.type (string, optional): Active check probing type.
• upstream.checks.passive.healthy (object, optional): Passive health check healthy configurations.
• upstream.checks.passive.healthy.http_statuses (array, optional): A list of HTTP response status codes which are considered healthy.
• upstream.checks.passive.healthy.successes (integer, optional): The number of successful probes to define a healthy target.
• upstream.checks.passive.unhealthy (object, optional): Passive health check unhealthy configurations.
• upstream.checks.passive.unhealthy.http_statuses (array, optional): A list of HTTP response status codes which are considered unhealthy.
• upstream.checks.passive.unhealthy.tcp_failures (integer, optional): The number of TCP-related failures to define an unhealthy target.
• upstream.checks.passive.unhealthy.timeouts (integer, optional): The number of probe timeouts to define an unhealthy target.
• upstream.checks.passive.unhealthy.http_failures (integer, optional): The number of HTTP-related failures to define an unhealthy target.
• allOf variant 2
• status (integer, optional): The object status. 1 means the object is active while 0 means it's inactive.

Responses

• 200: Service created successfully.
• allOf variant 1
• value (object, optional): The specific resource.
• allOf variant 2
• value (object, optional): The service with management fields.
• allOf variant 1
• allOf variant 1
• value.name (string, optional): The object name.
• value.labels (object, optional): Key-value pairs of labels.
• value.desc (string, optional): The object description.
• value.type (string, optional): Type of service. http corresponds to L7 service and stream corresponds to L4 service.
• allOf variant 2
• value.id (string, optional): The object ID.
• value.last_published (integer, optional): The object timestamp.
• value.published_gateway_groups_count (integer, optional):
• value.created_at (integer, optional): The object created timestamp.
• value.updated_at (integer, optional): The object updated timestamp.
• 400: Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.
• value (object, optional): The specific resource.
• error_msg (string, optional): The error message.

cURL

curl -X POST '$API_BASE_URL/apisix/admin/services'