docs: update "Getting started" guide (#1247)

Signed-off-by: Navendu Pottekkat <navendupottekkat@gmail.com> Co-authored-by: Jintao Zhang <zhangjintao9020@gmail.com>
apache · Aug 18, 2022 · 1a29306 · 1a29306
1 parent 2fa8a9c
commit 1a29306
Show file tree

Hide file tree

Showing 3 changed files with 174 additions and 90 deletions.
diff --git a/docs/en/latest/config.json b/docs/en/latest/config.json
@@ -5,6 +5,21 @@
       "type": "doc",
       "id": "getting-started"
     },
+    {
+      "type": "category",
+      "label": "Installation",
+      "items": [
+        "deployments/ack",
+        "deployments/aws",
+        "deployments/azure",
+        "deployments/gke",
+        "deployments/kind",
+        "deployments/kubesphere",
+        "deployments/k3s-rke",
+        "deployments/minikube",
+        "deployments/tke"
+      ]
+    },
     {
       "type": "category",
       "label": "Tutorials",
@@ -23,21 +38,6 @@
         "tutorials/how-to-use-go-plugin-runner-in-apisix-ingress"
       ]
     },
-    {
-      "type": "category",
-      "label": "Installation",
-      "items": [
-        "deployments/ack",
-        "deployments/aws",
-        "deployments/azure",
-        "deployments/gke",
-        "deployments/kind",
-        "deployments/kubesphere",
-        "deployments/k3s-rke",
-        "deployments/minikube",
-        "deployments/tke"
-      ]
-    },
     {
       "type": "category",
       "label": "References",

diff --git a/docs/en/latest/deployments/ack.md b/docs/en/latest/deployments/ack.md
@@ -1,7 +1,12 @@
 ---
-title: Install Ingress APISIX on ACK
+title: ACK (Alibaba Cloud)
+keywords:
+  - APISIX ingress
+  - Apache APISIX
+  - Kubernetes ingress
+  - Alibaba Cloud
+description: Guide to install APISIX ingress controller on Alibaba Cloud Container Service for Kubernetes (ACK).
 ---
-
 <!--
 #
 # Licensed to the Apache Software Foundation (ASF) under one or more
@@ -21,17 +26,19 @@ title: Install Ingress APISIX on ACK
 #
 -->
 
-This document explains how to install Ingress APISIX on Alibaba Cloud Container Service for Kubernetes (ACK).
+This document explains how you can install APISIX ingress on [Alibaba Cloud Container Service for Kubernetes (ACK)](https://www.alibabacloud.com/product/kubernetes).
 
 ## Prerequisites
 
-* Create an ACK Service on ali-cloud.
-* Download the kube config for your ACK, follow the [introduction](https://www.alibabacloud.com/help/zh/doc-detail/86378.html).
+Setting up APISIX ingress on ACK requires the following:
+
+* [Create an ACK service](https://www.alibabacloud.com/help/en/container-service-for-kubernetes/latest/create-an-ack-dedicated-cluster).
+* [Add the cluster credentials](https://www.alibabacloud.com/help/en/container-service-for-kubernetes/latest/connect-to-ack-clusters-by-using-kubectl) to your kube config file.
 * Install [Helm](https://helm.sh/).
 
-## Install APISIX and apisix-ingress-controller
+## Install APISIX and ingress controller
 
-As the data plane of apisix-ingress-controller, [Apache APISIX](http://apisix.apache.org/) can be deployed at the same time using Helm chart.
+The script below installs APISIX and the ingress controller:
 
 ```shell
 helm repo add apisix https://charts.apiseven.com
@@ -48,20 +55,35 @@ helm install apisix apisix/apisix \
 kubectl get service --namespace ingress-apisix
 ```
 
-Five Service resources were created.
+:::note
+
+By default, APISIX ingress controller will watch the apiVersion of `networking.k8s.io/v1`.
+
+If the target Kubernetes version is under `v1.19`, add the flag `--set ingress-controller.config.kubernetes.ingressVersion=networking/v1beta1`.
+
+Else, if your Kubernetes cluster version is under `v1.16`, set the flag `--set ingress-controller.config.kubernetes.ingressVersion=extensions/v1beta1`.
+
+:::
 
-* `apisix-gateway`, which processes the real traffic;
-* `apisix-admin`, which acts as the control plane to process all the configuration changes.
-* `apisix-ingress-controller`, which exposes apisix-ingress-controller's metrics.
-* `apisix-etcd` and `apisix-etcd-headless` for etcd service and internal communication.
+This will create the five resources mentioned below:
 
-The gateway service type is set to `LoadBalancer` (See [Access services through SLB](https://www.alibabacloud.com/help/doc-detail/182218.htm) for more details), so that clients can access Apache APISIX through a load balancer. You can find the load balancer ip by running:
+* `apisix-gateway`: dataplane the process the traffic.
+* `apisix-admin`: control plane that processes all configuration changes.
+* `apisix-ingress-controller`: ingress controller which exposes APISIX.
+* `apisix-etcd` and `apisix-etcd-headless`: stores configuration and handles internal communication.
+
+The gateway service type will be set to `LoadBalancer`. See [Use an existing SLB instance to expose an application
+](https://www.alibabacloud.com/help/en/container-service-for-kubernetes/latest/use-an-existing-slb-instance-to-expose-an-application-2) for details on using a load balancer.
+
+You can find the load balancer IP address by running:
 
 ```shell
 kubectl get service apisix-gateway --namespace ingress-apisix -o jsonpath='{.status.loadBalancer.ingress[].ip}'
 ```
 
-`ACK` PV require min_size is `20Gi`,cluster with `flexVolume` component select `alicloud-disk-ssd`,if with `helm values.yml` configure startup `apisix`,[more helm etcd configure](https://hub.kubeapps.com/charts/bitnami/etcd),configure format sample:
+ACK PersistentVolume requires the minimum size of `20Gi` using FlexVolume (select `alicloud-disk-ssd`)
+
+`ACK` PV require min_size is `20Gi`,cluster with `flexVolume` component select `alicloud-disk-ssd`. If you are using Helm, you can use this [etcd configuration file](https://hub.kubeapps.com/charts/bitnami/etcd):
 
 ```yaml
 etcd:
@@ -70,16 +92,32 @@ etcd:
     size: 20Gi
 ```
 
-Try to create some [resources](https://github.com/apache/apisix-ingress-controller/tree/master/docs/en/latest/concepts) to verify the running status. As a minimalist example, see [proxy-the-httpbin-service](../tutorials/proxy-the-httpbin-service.md) to learn how to apply resources to drive the apisix-ingress-controller.
+You should now be able to use APISIX ingress controller. You can try running this [minimal example](../tutorials/proxy-the-httpbin-service.md) to see if everything is working perfectly.
 
-### Specify The Ingress Version
-
-apisix-ingress-controller will watch apiVersion of `networking.k8s.io/v1` by default. If the target kubernetes version is under `v1.19`, add `--set ingress-controller.config.kubernetes.ingressVersion=networking/v1beta1` or `--set ingress-controller.config.kubernetes.ingressVersion=extensions/v1beta1` if your kubernetes cluster is under `v1.16`
+## Next steps
 
 ### Enable SSL
 
-The ssl config is disabled by default, add `--set gateway.tls.enabled=true` to enable tls support.
+SSL is disabled by default. You can enable it by adding the flag `--set gateway.tls.enabled=true`.
+
+### Change default keys
+
+It is recommended to change the default keys for security:
+
+```shell
+--set ingress-controller.config.apisix.adminKey=ADMIN_KEY_GENERATED_BY_YOURSELF
+```
+
+```shell
+--set admin.credentials.admin=ADMIN_KEY_GENERATED_BY_YOURSELF
+```
+
+```shell
+--set admin.credentials.viewer=VIEWER_KEY_GENERATED_BY_YOURSELF
+```
+
+:::note
 
-### Change default apikey
+The `ingress-controller.config.apisix.adminKey` and `admin.credentials.admin` must be the same. It is better if these are not same as `admin.credentials.viewer`.
 
-It's Recommended to change the default key by add `--set ingress-controller.config.apisix.adminKey=ADMIN_KEY_GENERATED_BY_YOURSELF`, `--set admin.credentials.admin=ADMIN_KEY_GENERATED_BY_YOURSELF`, `--set admin.credentials.viewer=VIEWER_KEY_GENERATED_BY_YOURSELF`, notice that `ingress-controller.config.apisix.adminKey` and `admin.credentials.admin` must be the same, and should better not same as `admin.credentials.viewer`.
+:::
diff --git a/docs/en/latest/getting-started.md b/docs/en/latest/getting-started.md
@@ -1,5 +1,10 @@
 ---
-title: Getting Started
+title: Getting started
+keywords:
+  - APISIX ingress
+  - Apache APISIX
+  - Kubernetes ingress
+description: Guide to get started with Apache APISIX ingress controller.
 ---
 
 <!--
@@ -21,68 +26,109 @@ title: Getting Started
 #
 -->
 
-## What is apisix-ingress-controller
-
-apisix-ingress-controller is yet another Ingress controller for Kubernetes using [Apache APISIX](https://apisix.apache.org) as the high performance reverse proxy.
-
-It's configured by using the declarative configurations like [ApisixRoute](./concepts/apisix_route.md), [ApisixUpstream](./concepts/apisix_upstream.md), [Ingress](https://kubernetes.io/docs/concepts/services-networking/ingress/).
-All these resources are watched and converted to corresponding resources in Apache APISIX.
-
-Service Discovery are also supported through [Kubernetes Service](https://kubernetes.io/docs/concepts/services-networking/service/),
-and will be reflected to nodes in APISIX Upstream.
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+APISIX ingress controller is a [Kubernetes ingress controller](https://kubernetes.io/docs/concepts/services-networking/ingress-controllers/) using [Apache APISIX](https://apisix.apache.org) as the high performance reverse proxy.
+
+APISIX ingress controller can be configured using native Kubernetes ingress resources as well as a declarative and easy to use custom resources provided by APISIX. The APISIX ingress controller converts these resources to APISIX configuration.
+
+The examples below show how these differ. Both the examples configure a Route in APISIX that routes to an httpbin service as the Upstream.
+
+<Tabs
+groupId="resources"
+defaultValue="apisix"
+values={[
+{label: 'APISIX Ingress custom resource', value: 'apisix'},
+{label: 'Kubernetes ingress resource', value: 'kubernetes'},
+]}>
+
+<TabItem value="apisix">
+
+```yaml title="httpbin-route.yaml"
+apiVersion: apisix.apache.org/v2
+kind: ApisixRoute
+metadata:
+  name: httpserver-route
+spec:
+  http:
+    - name: rule1
+      match:
+        hosts:
+          - local.httpbin.org
+        paths:
+          - /*
+      backends:
+        - serviceName: httpbin
+          servicePort: 80
+```
+
+</TabItem>
+
+<TabItem value="kubernetes">
+
+```yaml title="httpbin-route.yaml"
+apiVersion: networking.k8s.io/v1
+kind: Ingress
+metadata:
+  name: httpserver-ingress
+spec:
+  ingressClassName: apisix
+  rules:
+    - host: local.httpbin.org
+      http:
+        paths:
+          - backend:
+              service:
+                name: httpbin
+                port:
+                  number: 80
+            path: /
+            pathType: Prefix
+```
+
+</TabItem>
+</Tabs>
+
+APISIX ingress controller defines the CRDs [ApisixRoute](./concepts/apisix_route.md), [ApisixUpstream](./concepts/apisix_upstream.md), [ApisixTlx](concepts/apisix_tls.md), and [ApisixClusterConfig](concepts/apisix_cluster_config.md).
+
+APISIX also supports [service discovery](https://apisix.apache.org/docs/apisix/next/discovery/kubernetes/) through [Kubernetes service](https://kubernetes.io/docs/concepts/services-networking/service/) abstraction.
 
 ![scene](../../assets/images/scene.png)
 
-## Features
-
-* Declarative configuration
-* Full dynamic capabilities to delivery configurations.
-* Native Kubernetes Ingress (both v1 and v1beta1) support.
-* Service Discovery based on Kubernetes Service.
-* Out of box support for node health check.
-* Support load balancing based on Pod (upstream nodes).
-* Rich plugins support.
-* Easy to deploy and use.
+See [Design](./design.md) to learn more about how APISIX ingress controller works under the hood.
 
-## How It Works
-
-See [Design](./design.md) for more details.
-
-## Installation on Cloud
-
-apisix-ingress-controller supports to be installed on some clouds such as AWS, GCP.
+## Features
 
-* [Install Ingress APISIX on Azure AKS](https://apisix.apache.org/docs/ingress-controller/deployments/azure)
-* [Install Ingress APISIX on AWS EKS](https://apisix.apache.org/docs/ingress-controller/deployments/aws)
-* [Install Ingress APISIX on ACK](https://apisix.apache.org/docs/ingress-controller/deployments/ack)
-* [Install Ingress APISIX on Google Cloud GKE](https://apisix.apache.org/docs/ingress-controller/deployments/gke)
-* [Install Ingress APISIX on Minikube](https://apisix.apache.org/docs/ingress-controller/deployments/minikube)
-* [Install Ingress APISIX on KubeSphere](https://apisix.apache.org/docs/ingress-controller/deployments/kubesphere)
-* [Install Ingress APISIX on K3S and RKE](https://apisix.apache.org/docs/ingress-controller/deployments/k3s-rke)
+To summarize, APISIX ingress controller has the following features:
 
-## Installation on Prem
+- Declarative configuration with CRDs.
+- Fully dynamic configuration.
+- Supports native Kubernetes Ingress resource (both v1 and v1beta1).
+- Supports service discovery through Kubernetes Service.
+- Out-of-the-box node health check support.
+- Supports load balancing based on pods (Upstream nodes).
+- Rich [Plugins](https://apisix.apache.org/docs/apisix/next/plugins/batch-requests/) with [custom Plugin](https://apisix.apache.org/docs/apisix/next/plugin-develop/) support.
 
-If you want to deploy apisix-ingress-controller on Prem, we recommend you to use [Helm](https://helm.sh/). Just a few steps
+## Get involved
 
-## Get Involved to Contribute
+You can contribute to the development of APISIX ingress controller. See [Development guide](./contribute.md) for instructions on setting up the project locally.
 
-First, your supports and cooperations to make this project better are appreciated.
-But before you start, please read [How to Contribute](./contribute.md)
+See the [Contribute to APISIX](https://apisix.apache.org/docs/general/contributor-guide/) section for details on the contributing flow.
 
-## Compatibility with Apache APISIX
+## Compatibility with APISIX
 
-The following table describes the compatibility between apisix-ingress-controller and
-[Apache APISIX](https://apisix.apache.org).
+The table below shows the compatibility between APISIX ingress controller and the APISIX proxy.
 
-| apisix-ingress-controller | Apache APISIX |
-| ----:| ---:|
-| `master` | `>= 2.7`, `2.11` is recommended. |
-| `1.4.0` | `>= 2.7`, `2.11` is recommended. |
-| `1.3.0` | `>= 2.7`, `2.10` is recommended. |
-| `1.2.0` | `>= 2.7`, `2.8` is recommended. |
-| `1.1.0` | `>= 2.7`, `2.7` is recommended. |
-| `1.1.0` | `>= 2.7`, `2.7` is recommended. |
-| `1.0.0` | `>= 2.7`, `2.7` is recommended. |
-| `0.6` | `>= 2.6`, `2.6` is recommended. |
-| `0.5` | `>= 2.4`, `2.5` is recommended. |
-| `0.4` |`>= 2.4`|
+| APISIX ingress controller | Supported APISIX versions | Recommended APISIX version |
+| ------------------------- | ------------------------- | -------------------------- |
+| `master`                  | `>= 2.7`                  | `2.11`                     |
+| `1.4.0`                   | `>= 2.7`                  | `2.11`                     |
+| `1.3.0`                   | `>= 2.7`                  | `2.10`                     |
+| `1.2.0`                   | `>= 2.7`                  | `2.8`                      |
+| `1.1.0`                   | `>= 2.7`                  | `2.7`                      |
+| `1.1.0`                   | `>= 2.7`                  | `2.7`                      |
+| `1.0.0`                   | `>= 2.7`                  | `2.7`                      |
+| `0.6`                     | `>= 2.6`                  | `2.6`                      |
+| `0.5`                     | `>= 2.4`                  | `2.5`                      |
+| `0.4`                     | `>= 2.4`                  |                            |