[apisix-ingress-controller] branch master updated: docs: add external service discovery tutorial (#1535)

[zh...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

zhangjintao pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/apisix-ingress-controller.git


The following commit(s) were added to refs/heads/master by this push:
     new 67d60fe9 docs: add external service discovery tutorial (#1535)
67d60fe9 is described below

commit 67d60fe9858f89f0e4ad575e4e0f5ed540fe5ef5
Author: Jintao Zhang <zh...@gmail.com>
AuthorDate: Fri Dec 16 22:26:41 2022 +0800

    docs: add external service discovery tutorial (#1535)
---
 docs/en/latest/config.json                         |  4 +-
 .../latest/tutorials/external-service-discovery.md | 90 ++++++++++++++++++++++
 2 files changed, 93 insertions(+), 1 deletion(-)

diff --git a/docs/en/latest/config.json b/docs/en/latest/config.json
index bff5ed08..8b5fd410 100644
--- a/docs/en/latest/config.json
+++ b/docs/en/latest/config.json
@@ -35,7 +35,9 @@
         "tutorials/manage-ingress-certificates-with-cert-manager",
         "tutorials/enable-authentication-and-restriction",
         "tutorials/how-to-access-Apache-APISIX-Prometheus-Metrics-on-k8s",
-        "tutorials/how-to-use-go-plugin-runner-in-apisix-ingress"
+        "tutorials/how-to-use-go-plugin-runner-in-apisix-ingress",
+        "tutorials/external-service",
+        "tutorials/external-service-discovery"
       ]
     },
     {
diff --git a/docs/en/latest/tutorials/external-service-discovery.md b/docs/en/latest/tutorials/external-service-discovery.md
new file mode 100644
index 00000000..63c0b4e0
--- /dev/null
+++ b/docs/en/latest/tutorials/external-service-discovery.md
@@ -0,0 +1,90 @@
+---
+title: Using External Services Discovery In ApisixUpstream
+---
+
+<!--
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements.  See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License.  You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+-->
+
+In this tutorial, we will introduce how to configure external services discovery in the ApisixUpstream resources.
+
+APISIX already supports various service discovery components, such as DNS, consul, nacos, etc.
+Please see [Integration service discovery registry](https://apisix.apache.org/docs/apisix/discovery/) for details.
+
+## Prerequisites
+
+- An available Kubernetes cluster
+- An available APISIX and APISIX Ingress Controller installation
+
+We assume that your APISIX is installed in the `apisix` namespace.
+
+## Introduction
+
+Integration of APISIX Ingress with service discovery components is configured through the ApisixUpstream resource.
+In this case, we don't configure the `backends` field in the ApisixRoute resource.
+Instead, we will use the `upstreams` field to refer to an ApisixUpstream resources with the `discovery` field configured.
+
+For example:
+
+```yaml
+# httpbin-route.yaml
+apiVersion: apisix.apache.org/v2
+kind: ApisixRoute
+metadata:
+  name: httpbin-route
+spec:
+  http:
+  - name: rule1
+    match:
+      hosts:
+      - local.httpbin.org
+      paths:
+      - /*
+    # backends:  # We won't use the `backends` field
+    #    - serviceName: httpbin
+    #      servicePort: 80
+    upstreams:
+    - name: httpbin-upstream
+```
+
+This configuration tells the ingress controller not to resolve upstream hosts through the K8s services, but to use the configuration defined in the referenced ApisixUpstream.
+The referenced ApisixUpstream *MUST* have `discovery` field configured. For example:
+
+```yaml
+# httpbin-upstream.yaml
+apiVersion: apisix.apache.org/v2
+kind: ApisixUpstream
+metadata:
+  name: httpbin-upstream
+spec:
+  discovery:
+    type: dns
+    serviceName: httpbin.default.svc.cluster.local
+```
+
+In this yaml example, we configured `httpbin.default.svc.cluster.local` as the backend.
+The type of service discovery needs to be pre-configured in APISIX. For example:
+
+```yaml
+discovery:
+  dns:
+    servers:
+      - "10.96.0.10:53" # default kube-dns cluster IP.
+```
+
+After applying the above configuration, we can try to access `httpbin.default.svc.cluster.local` directly through APISIX.