diff --git a/docs/en/latest/config.json b/docs/en/latest/config.json index f60a79686b..7725f0176f 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 2632df2f1d..df26464d9b 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). --- - -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 c950c86a39..a9b7789d34 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. --- -## 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. + + + + + +```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 +``` + + + + + +```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 +``` + + + + +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` | |