You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@apisix.apache.org by zh...@apache.org on 2022/08/18 07:11:42 UTC
[apisix-ingress-controller] branch master updated: docs: update "Getting started" guide (#1247)
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 1a293064 docs: update "Getting started" guide (#1247)
1a293064 is described below
commit 1a2930646ea6127d41fcf12236b3a0e5fb180dda
Author: Navendu Pottekkat <na...@gmail.com>
AuthorDate: Thu Aug 18 12:41:36 2022 +0530
docs: update "Getting started" guide (#1247)
Signed-off-by: Navendu Pottekkat <na...@gmail.com>
Co-authored-by: Jintao Zhang <zh...@gmail.com>
---
docs/en/latest/config.json | 30 ++++----
docs/en/latest/deployments/ack.md | 80 ++++++++++++++------
docs/en/latest/getting-started.md | 154 +++++++++++++++++++++++++-------------
3 files changed, 174 insertions(+), 90 deletions(-)
diff --git a/docs/en/latest/config.json b/docs/en/latest/config.json
index f60a7968..7725f017 100644
--- 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
index 2632df2f..df26464d 100644
--- 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
index c950c86a..a9b7789d 100644
--- 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.
-## 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` | |