Get an upstream in a service on a gateway group

GET /apisix/admin/services/{service_id}/upstreams/{upstream_id}

Get an upstream in a service on a gateway group

Get one upstream in a service through an APISIX Admin API compatible endpoint under /apisix/admin/. The response uses APISIX-style upstream structure. Required IAM Permission: Action gateway:GetPublishedService, Resource arn:api7:gateway:gatewaygroup/%s/service/%s

Parameters

• service_id (path, string, required): The unique identifier of the service.
• upstream_id (path, string, required): The unique identifier of the upstream.
• gateway_group_id (query, string, required): Gateway group ID. Optional when using the gateway group admin key to authenticate.
• with_publish_info (query, boolean, optional): If true, include publish information in the response, such as apisix_route_id, route_version_id, and service_version_id. The additional information is only useful for the Dashboard and not for API users.

Responses

• 200: Successfully retrieved the upstream configuration.
• allOf variant 1
• value (object, optional): The specific resource.
• allOf variant 2
• value (object, optional): The upstream model.
• allOf variant 1
• oneOf variant 1: HTTP Upstream
• value.name (string, optional): The upstream name.
• value.scheme (string, optional): The protocol that is used for communicating with the backend service when the service type is http.
• value.desc (string, optional): The object description.
• value.labels (object, optional): Key-value pairs of labels.
• value.type (string, optional): Load balancing algorithm to distribute traffic.
• value.hash_on (string, optional): Type of value to hash on when type is chash.
• value.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.
• value.retries (integer, optional): The number of retries while passing the request to an upstream.
• value.keepalive_pool (object, optional): Upstream keepalive connection pool.
• value.keepalive_pool.size (integer, optional): The number of idle keepalive connections per worker to upstream servers.
• value.keepalive_pool.idle_timeout (number, optional): Time an idle keepalive connection remains open before being closed, in seconds.
• value.keepalive_pool.requests (integer, optional): The number of requests a single keepalive connection can handle before closing.
• value.timeout (object, optional): Timeout settings for connecting to, sending, and receiving messages from the upstream, in seconds.
• value.timeout.connect (number, optional): Connection timeout in seconds.
• value.timeout.send (number, optional): Sending timeout in seconds.
• value.timeout.read (number, optional): Receiving timeout in seconds.
• value.retry_timeout (number, optional): Timeout to continue with retries. Setting this to 0 disables the retry timeout.
• value.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.

• value.upstream_host (string, optional): Value to rewrite the host header to. Only used if pass_host is rewrite.
• value.nodes (array, optional): The upstream endpoints.
• value.nodes[].host (string, required): Upstream host.
• value.nodes[].port (integer, required): Upstream port.
• value.nodes[].weight (integer, required): Upstream weight.
• value.nodes[].priority (integer, optional): Node priority. A higher value corresponds to a higher priority.
• value.service_name (string, optional): Service name in the service registry. Only valid for service discovery.
• value.discovery_type (string, optional): Type of service discovery. Only valid for service discovery.
• value.discovery_args (object, optional): Service discovery arguments. Only valid for service discovery.
• value.discovery_args.metadata (object, optional):
• value.tls (object, optional): Replace with client_certificate and ca_certificates
• oneOf variant 1
• value.tls.client_cert (string, required): The certificate in PEM format.
• value.tls.client_key (string, required): The private key in PEM format.
• oneOf variant 2
• value.tls.client_cert_id (string, required): The object ID.
• value.client_certificate (string, optional): The object ID.
• value.ca_certificates (array, optional): CA certificates.
• value.tls_verify (boolean, optional): If true, verify TLS.
• value.checks (object, optional): Health check configurations.
• anyOf variant 1: Active Check
• value.checks.active (object, required): Active health check configurations.
• value.checks.active.type (string, optional): Active check probing type.
• value.checks.active.timeout (number, optional): Active check timeout in seconds.
• value.checks.active.concurrency (integer, optional): The number of targets to be checked at the same time during the active check.
• value.checks.active.host (string, optional): The HTTP host.
• value.checks.active.port (integer, optional): By default, the port is the same as the one defined in the upstream target.
• value.checks.active.http_path (string, optional): The HTTP path in HTTP probe requests.
• value.checks.active.https_verify_certificate (boolean, optional): Whether to verify the target's TLS certificate.
• value.checks.active.req_headers (array, optional): The request headers.
• value.checks.active.healthy (object, optional): Active health check healthy configurations.
• value.checks.active.healthy.interval (integer, optional): Time interval of checking healthy targets in seconds.
• value.checks.active.healthy.http_statuses (array, optional): A list of HTTP response status codes which are considered healthy.
• value.checks.active.healthy.successes (integer, optional): The number of successful probes to define a healthy target.
• value.checks.active.unhealthy (object, optional): Active health check unhealthy configurations.
• value.checks.active.unhealthy.interval (integer, optional): Time interval of checking unhealthy targets in seconds.
• value.checks.active.unhealthy.http_statuses (array, optional): A list of HTTP response status codes which are considered unhealthy.
• value.checks.active.unhealthy.http_failures (integer, optional): The number of HTTP-related failures to define an unhealthy target.
• value.checks.active.unhealthy.tcp_failures (integer, optional): The number of TCP-related failures to define an unhealthy target.
• value.checks.active.unhealthy.timeouts (integer, optional): The number of probe timeouts to define an unhealthy target.
• anyOf variant 2: Passive Check
• value.checks.active (object, required): Active health check configurations.
• value.checks.active.type (string, optional): Active check probing type.
• value.checks.active.timeout (number, optional): Active check timeout in seconds.
• value.checks.active.concurrency (integer, optional): The number of targets to be checked at the same time during the active check.
• value.checks.active.host (string, optional): The HTTP host.
• value.checks.active.port (integer, optional): By default, the port is the same as the one defined in the upstream target.
• value.checks.active.http_path (string, optional): The HTTP path in HTTP probe requests.
• value.checks.active.https_verify_certificate (boolean, optional): Whether to verify the target's TLS certificate.
• value.checks.active.req_headers (array, optional): The request headers.
• value.checks.active.healthy (object, optional): Active health check healthy configurations.
• value.checks.active.healthy.interval (integer, optional): Time interval of checking healthy targets in seconds.
• value.checks.active.healthy.http_statuses (array, optional): A list of HTTP response status codes which are considered healthy.
• value.checks.active.healthy.successes (integer, optional): The number of successful probes to define a healthy target.
• value.checks.active.unhealthy (object, optional): Active health check unhealthy configurations.
• value.checks.active.unhealthy.interval (integer, optional): Time interval of checking unhealthy targets in seconds.
• value.checks.active.unhealthy.http_statuses (array, optional): A list of HTTP response status codes which are considered unhealthy.
• value.checks.active.unhealthy.http_failures (integer, optional): The number of HTTP-related failures to define an unhealthy target.
• value.checks.active.unhealthy.tcp_failures (integer, optional): The number of TCP-related failures to define an unhealthy target.
• value.checks.active.unhealthy.timeouts (integer, optional): The number of probe timeouts to define an unhealthy target.
• value.checks.passive (object, required): Passive health check configurations.
• value.checks.passive.type (string, optional): Active check probing type.
• value.checks.passive.healthy (object, optional): Passive health check healthy configurations.
• value.checks.passive.healthy.http_statuses (array, optional): A list of HTTP response status codes which are considered healthy.
• value.checks.passive.healthy.successes (integer, optional): The number of successful probes to define a healthy target.
• value.checks.passive.unhealthy (object, optional): Passive health check unhealthy configurations.
• value.checks.passive.unhealthy.http_statuses (array, optional): A list of HTTP response status codes which are considered unhealthy.
• value.checks.passive.unhealthy.tcp_failures (integer, optional): The number of TCP-related failures to define an unhealthy target.
• value.checks.passive.unhealthy.timeouts (integer, optional): The number of probe timeouts to define an unhealthy target.
• value.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 Upstream
• value.name (string, optional): The object name.
• value.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.
• value.desc (string, optional): The object description.
• value.labels (object, optional): Key-value pairs of labels.
• value.type (string, optional): Load balancing algorithm to distribute traffic.
• value.hash_on (string, optional): Type of value to hash on when type is chash.
• value.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.
• value.retries (integer, optional): The number of retries while passing the request to an upstream using the underlying Nginx mechanism.
• value.retry_timeout (number, optional): Timeout to continue with retries. Setting this to 0 disables the retry timeout.
• value.timeout (object, optional): Timeout settings for connecting to, sending, and receiving messages from the upstream, in seconds.
• value.timeout.connect (number, optional): Connection timeout in seconds.
• value.timeout.send (number, optional): Sending timeout in seconds.
• value.timeout.read (number, optional): Receiving timeout in seconds.
• value.nodes (array, optional): The upstream endpoints.
• value.nodes[].host (string, required): Upstream host.
• value.nodes[].port (integer, required): Upstream port.
• value.nodes[].weight (integer, required): Upstream weight.
• value.nodes[].priority (integer, optional): Node priority. A higher value corresponds to a higher priority.
• value.checks (object, optional): Health check configurations.
• anyOf variant 1: Active Check
• value.checks.active (object, required): Active health check configurations.
• value.checks.active.type (string, optional): Active check probing type.
• value.checks.active.timeout (number, optional): Active check timeout in seconds.
• value.checks.active.concurrency (integer, optional): The number of targets to be checked at the same time during the active check.
• value.checks.active.host (string, optional): The HTTP host.
• value.checks.active.port (integer, optional): By default, the port is the same as the one defined in the upstream target.
• value.checks.active.http_path (string, optional): The HTTP path in HTTP probe requests.
• value.checks.active.https_verify_certificate (boolean, optional): Whether to verify the target's TLS certificate.
• value.checks.active.req_headers (array, optional): The request headers.
• value.checks.active.healthy (object, optional): Active health check healthy configurations.
• value.checks.active.healthy.interval (integer, optional): Time interval of checking healthy targets in seconds.
• value.checks.active.healthy.http_statuses (array, optional): A list of HTTP response status codes which are considered healthy.
• value.checks.active.healthy.successes (integer, optional): The number of successful probes to define a healthy target.
• value.checks.active.unhealthy (object, optional): Active health check unhealthy configurations.
• value.checks.active.unhealthy.interval (integer, optional): Time interval of checking unhealthy targets in seconds.
• value.checks.active.unhealthy.http_statuses (array, optional): A list of HTTP response status codes which are considered unhealthy.
• value.checks.active.unhealthy.http_failures (integer, optional): The number of HTTP-related failures to define an unhealthy target.
• value.checks.active.unhealthy.tcp_failures (integer, optional): The number of TCP-related failures to define an unhealthy target.
• value.checks.active.unhealthy.timeouts (integer, optional): The number of probe timeouts to define an unhealthy target.
• anyOf variant 2: Passive Check
• value.checks.active (object, required): Active health check configurations.
• value.checks.active.type (string, optional): Active check probing type.
• value.checks.active.timeout (number, optional): Active check timeout in seconds.
• value.checks.active.concurrency (integer, optional): The number of targets to be checked at the same time during the active check.
• value.checks.active.host (string, optional): The HTTP host.
• value.checks.active.port (integer, optional): By default, the port is the same as the one defined in the upstream target.
• value.checks.active.http_path (string, optional): The HTTP path in HTTP probe requests.
• value.checks.active.https_verify_certificate (boolean, optional): Whether to verify the target's TLS certificate.
• value.checks.active.req_headers (array, optional): The request headers.
• value.checks.active.healthy (object, optional): Active health check healthy configurations.
• value.checks.active.healthy.interval (integer, optional): Time interval of checking healthy targets in seconds.
• value.checks.active.healthy.http_statuses (array, optional): A list of HTTP response status codes which are considered healthy.
• value.checks.active.healthy.successes (integer, optional): The number of successful probes to define a healthy target.
• value.checks.active.unhealthy (object, optional): Active health check unhealthy configurations.
• value.checks.active.unhealthy.interval (integer, optional): Time interval of checking unhealthy targets in seconds.
• value.checks.active.unhealthy.http_statuses (array, optional): A list of HTTP response status codes which are considered unhealthy.
• value.checks.active.unhealthy.http_failures (integer, optional): The number of HTTP-related failures to define an unhealthy target.
• value.checks.active.unhealthy.tcp_failures (integer, optional): The number of TCP-related failures to define an unhealthy target.
• value.checks.active.unhealthy.timeouts (integer, optional): The number of probe timeouts to define an unhealthy target.
• value.checks.passive (object, required): Passive health check configurations.
• value.checks.passive.type (string, optional): Active check probing type.
• value.checks.passive.healthy (object, optional): Passive health check healthy configurations.
• value.checks.passive.healthy.http_statuses (array, optional): A list of HTTP response status codes which are considered healthy.
• value.checks.passive.healthy.successes (integer, optional): The number of successful probes to define a healthy target.
• value.checks.passive.unhealthy (object, optional): Passive health check unhealthy configurations.
• value.checks.passive.unhealthy.http_statuses (array, optional): A list of HTTP response status codes which are considered unhealthy.
• value.checks.passive.unhealthy.tcp_failures (integer, optional): The number of TCP-related failures to define an unhealthy target.
• value.checks.passive.unhealthy.timeouts (integer, optional): The number of probe timeouts to define an unhealthy target.
• value.checks.passive.unhealthy.http_failures (integer, optional): The number of HTTP-related failures to define an unhealthy target.
• allOf variant 2
• value.id (string, optional): The object ID.
• value.gateway_group_id (string, optional): The gateway group ID.
• value.apisix_service_id (string, optional): The service ID.
• 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 GET '$API_BASE_URL/apisix/admin/services/{service_id}/upstreams/{upstream_id}'