title: ApisixUpstream keywords:
ApisixUpstream
is a Kubernetes CRD object that abstracts out a Kubernetes service and makes it richer by adding load balancing, health check, retry, and timeouts. It is designed to have the same name as the Kubernetes service.
See reference for the full API documentation.
The example below shows how you can configure load balacing in ApisixUpstream
object using ewma:
apiVersion: apisix.apache.org/v2 kind: ApisixUpstream metadata: name: httpbin spec: loadbalancer: type: ewma --- apiVersion: v1 kind: Service metadata: name: httpbin spec: selector: app: httpbin ports: - name: http port: 80 targetPort: 8080
If you require sticky sessions, algorithms like consistent hashing can be used for load balancing. The example below uses the User-Agent
header for hashing:
apiVersion: apisix.apache.org/v2 kind: ApisixUpstream metadata: name: httpbin spec: loadbalancer: type: chash hashOn: header key: "user-agent"
kubelet provides probes for health check. But if more features like passive feedback is required, a powerful health check mechanism is needed.
The example below shows how you can configure a passive health checker to detect unhealthy endpoints. Once there are three consecutive requests with the unhealthy status codes, the endpoint will be marked as unhealthy and requests will not be forwarded to it until it is healthy again.
The active health checker checks these unhealthy endpoints continuously for healthy status codes. Requests are forwarded to these endpoints again after they are healthy.
apiVersion: apisix.apache.org/v2 kind: ApisixUpstream metadata: name: httpbin spec: healthCheck: passive: unhealthy: httpCodes: - 500 - 502 - 503 - 504 httpFailures: 3 timeout: 5s active: type: http httpPath: /healthz timeout: 5s host: www.foo.com healthy: successes: 3 interval: 2s httpCodes: - 200 - 206
:::note
The active health check configuration is mandatory if using the healthCheck
feature in ApisixUpstream
.
:::
You can configure APISIX to retry requests to tolerate network errors. By default, retries
is 1
.
The example below configures 3
retries.
apiVersion: apisix.apache.org/v2 kind: ApisixUpstream metadata: name: httpbin spec: retries: 3
:::note
If an error or timeout occurs while transferring a response to a client, it would not retry.
:::
You can also change the timeouts to fit your applications. The default connect, read, and send timeout is 60s
.
apiVersion: apisix.apache.org/v2 kind: ApisixUpstream metadata: name: httpbin spec: timeout: connect: 5s read: 10s send: 10s
A Kubernetes service can expose multiple ports to provide distinct functions (like different protocols). For each of the ports, a different Upstream configuration might be required.
In the example below, the foo
service exposes two ports, one using HTTP and the other gRPC. The Upstream service is configured to use the correct scheme for the respective ports:
apiVersion: apisix.apache.org/v2 kind: ApisixUpstream metadata: name: foo spec: loadbalancer: type: roundrobin portLevelSettings: - port: 7000 scheme: http - port: 7001 scheme: grpc --- apiVersion: v1 kind: Service metadata: name: foo spec: selector: app: foo ports: - name: http port: 7000 targetPort: 7000 - name: grpc port: 7001 targetPort: 7001