Skip to content

Commit a92361e

Browse files
AlinsRanAlinsRan
authored
doc: add getting-started doc (#2450)
1 parent 14c29cc commit a92361e

File tree

3 files changed

+238
-4
lines changed

3 files changed

+238
-4
lines changed

‎docs/en/latest/config.json‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,10 @@
11
{
22
"version": "0.3.0",
33
"sidebar": [
4+
{
5+
"type": "doc",
6+
"id": "getting-started"
7+
},
48
{
59
"type": "category",
610
"label": "Concepts",

‎docs/en/latest/getting-started.md‎

Lines changed: 194 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,194 @@
1+
---
2+
title: Getting started
3+
keywords:
4+
- APISIX ingress
5+
- Apache APISIX
6+
- Kubernetes ingress
7+
description: Guide to get started with Apache APISIX ingress controller.
8+
---
9+
<!--
10+
#
11+
# Licensed to the Apache Software Foundation (ASF) under one or more
12+
# contributor license agreements. See the NOTICE file distributed with
13+
# this work for additional information regarding copyright ownership.
14+
# The ASF licenses this file to You under the Apache License, Version 2.0
15+
# (the "License"); you may not use this file except in compliance with
16+
# the License. You may obtain a copy of the License at
17+
#
18+
# http://www.apache.org/licenses/LICENSE-2.0
19+
#
20+
# Unless required by applicable law or agreed to in writing, software
21+
# distributed under the License is distributed on an "AS IS" BASIS,
22+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
23+
# See the License for the specific language governing permissions and
24+
# limitations under the License.
25+
#
26+
-->
27+
28+
import Tabs from '@theme/Tabs';
29+
import TabItem from '@theme/TabItem';
30+
31+
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.
32+
33+
APISIX Ingress Controller can be configured using the native Kubernetes Ingress or Gateway API, as well as with APISIX’s own declarative and easy-to-use custom resources. The controller translates these resources into APISIX configuration.
34+
35+
## Quick Start
36+
37+
Get started with APISIX Ingress Controller in a few simple steps.
38+
39+
### Prerequisites
40+
41+
Before installing APISIX Ingress Controller, ensure you have:
42+
43+
1. A working Kubernetes cluster (version 1.26+)
44+
2. [Helm](https://helm.sh/) (version 3.8+) installed
45+
46+
### Install APISIX and APISIX Ingress Controller
47+
48+
Install the Gateway API CRDs, APISIX, and APISIX Ingress Controller using the following commands:
49+
50+
```bash
51+
helm repo add apisix https://charts.apiseven.com
52+
helm repo add bitnami https://charts.bitnami.com/bitnami
53+
helm repo update
54+
55+
helm install apisix \
56+
--namespace ingress-apisix \
57+
--create-namespace \
58+
--set ingress-controller.enabled=true \
59+
--set ingress-controller.apisix.adminService.namespace=ingress-apisix \
60+
--set ingress-controller.gatewayProxy.createDefault=true \
61+
apisix/apisix
62+
```
63+
64+
### Set Up a Sample Upstream
65+
66+
Install the httpbin example application to test the configuration:
67+
68+
```bash
69+
https://raw.githubusercontent.com/apache/apisix-ingress-controller/refs/heads/v2.0.0/examples/httpbin/deployment.yaml
70+
```
71+
72+
### Configure a Route
73+
74+
Install an ApisixRoute or Ingress resource to route traffic to httpbin:
75+
76+
> The examples below show how these differ. Both the examples configure a Route in APISIX that routes to an httpbin service as the Upstream.
77+
78+
<Tabs
79+
groupId="resources"
80+
defaultValue="apisix"
81+
values={[
82+
{label: 'APISIX Ingress CRD', value: 'apisix'},
83+
{label: 'Kubernetes Ingress API', value: 'ingress'},
84+
]}>
85+
86+
<TabItem value="apisix">
87+
88+
```yaml title="httpbin-route.yaml"
89+
apiVersion: apisix.apache.org/v2
90+
kind: ApisixRoute
91+
metadata:
92+
name: httpbin-route
93+
spec:
94+
ingressClassName: apisix
95+
http:
96+
- name: route-1
97+
match:
98+
hosts:
99+
- local.httpbin.org
100+
paths:
101+
- /*
102+
backends:
103+
- serviceName: httpbin
104+
servicePort: 80
105+
```
106+
107+
</TabItem>
108+
109+
<TabItem value="ingress">
110+
111+
```yaml title="httpbin-route.yaml"
112+
apiVersion: networking.k8s.io/v1
113+
kind: Ingress
114+
metadata:
115+
name: httpbin-route
116+
spec:
117+
ingressClassName: apisix
118+
rules:
119+
- host: local.httpbin.org
120+
http:
121+
paths:
122+
- backend:
123+
service:
124+
name: httpbin
125+
port:
126+
number: 80
127+
path: /
128+
pathType: Prefix
129+
```
130+
131+
</TabItem>
132+
</Tabs>
133+
134+
:::note
135+
136+
More details on the installation can be found in the [Installation guide](./install.md).
137+
138+
:::
139+
140+
### Verify Route Configuration
141+
142+
Let's verify the configuration. In order to access APISIX locally, we can use `kubectl port-forward` command to forward traffic from the specified port at your local machine to the specified port on the specified service.
143+
144+
```bash
145+
kubectl port-forward -n ingress-apisix svc/apisix-gateway 9080:80
146+
```
147+
148+
Run curl command in a APISIX pod to see if the routing configuration works.
149+
150+
```bash
151+
curl http://127.0.0.1:9080/headers -H 'Host: local.httpbin.org'
152+
```
153+
154+
## Features
155+
156+
To summarize, APISIX ingress controller has the following features:
157+
158+
- Declarative configuration with CRDs.
159+
- Supports native Kubernetes Ingress v1 and Gateway API.
160+
- Supports service discovery through Kubernetes Service.
161+
- Supports load balancing based on pods (Upstream nodes).
162+
- 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.
163+
164+
## Get involved
165+
166+
You can contribute to the development of APISIX ingress controller. See [Development guide](./developer-guide.md) for instructions on setting up the project locally.
167+
168+
See the [Contribute to APISIX](https://apisix.apache.org/docs/general/contributor-guide/) section for details on the contributing flow.
169+
170+
## Compatibility with APISIX
171+
172+
The table below shows the compatibility between APISIX ingress controller and the APISIX proxy.
173+
174+
:::note
175+
176+
APISIX Ingress Controller 2.0.0+ support the [APISIX Standalone API-driven Mode](https://apisix.apache.org/docs/apisix/deployment-modes/#api-driven-experimental), but require APISIX 3.13+.
177+
178+
:::
179+
180+
| APISIX ingress controller | Supported APISIX versions | Recommended APISIX version |
181+
| ------------------------- | ------------------------- | -------------------------- |
182+
| `master` | `>=3.0` | `3.13` |
183+
| `2.0.0` | `>=3.0` | `3.13` |
184+
| `1.6.0` | `>= 2.15`, `>=3.0` | `2.15`, `3.0` |
185+
| `1.5.0` | `>= 2.7` | `2.15` |
186+
| `1.4.0` | `>= 2.7` | `2.11` |
187+
| `1.3.0` | `>= 2.7` | `2.10` |
188+
| `1.2.0` | `>= 2.7` | `2.8` |
189+
| `1.1.0` | `>= 2.7` | `2.7` |
190+
| `1.1.0` | `>= 2.7` | `2.7` |
191+
| `1.0.0` | `>= 2.7` | `2.7` |
192+
| `0.6` | `>= 2.6` | `2.6` |
193+
| `0.5` | `>= 2.4` | `2.5` |
194+
| `0.4` | `>= 2.4` | |

‎docs/en/latest/install.md‎

Lines changed: 40 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -40,15 +40,51 @@ Before installing APISIX ingress controller, ensure you have:
4040
2. [kubectl](https://kubernetes.io/docs/tasks/tools/) installed and configured to access your cluster
4141
3. [Helm](https://helm.sh/) (version 3.8+) installed
4242

43-
## Install APISIX Ingress Controller
44-
45-
The APISIX ingress controller can be installed using the Helm chart provided by the Apache APISIX project. The following steps will guide you through the installation process.
43+
Make sure to update the Helm repositories:
4644

47-
```shell
45+
```bash
4846
helm repo add apisix https://charts.apiseven.com
4947
helm repo add bitnami https://charts.bitnami.com/bitnami
5048
helm repo update
49+
```
50+
51+
## Install APISIX and APISIX Ingress Controller
52+
53+
The script below installs APISIX and APISIX Ingress Controller:
54+
55+
```bash
56+
helm install apisix \
57+
--namespace ingress-apisix \
58+
--create-namespace \
59+
--set ingress-controller.enabled=true \
60+
--set ingress-controller.apisix.adminService.namespace=ingress-apisix \
61+
--set ingress-controller.gatewayProxy.createDefault=true \
62+
apisix/apisix
63+
```
64+
65+
## Install APISIX and APISIX Ingress Controller (Standalone API-driven mode)
66+
67+
To run APISIX in [APISIX Standalone API-driven mode](https://apisix.apache.org/docs/apisix/deployment-modes/#api-driven-experimental), use the following script to install APISIX and the APISIX Ingress Controller:
68+
69+
```bash
70+
helm install apisix \
71+
--namespace ingress-apisix \
72+
--create-namespace \
73+
--set apisix.deployment.role=traditional \
74+
--set apisix.deployment.role_traditional.config_provider=yaml \
75+
--set etcd.enabled=false \
76+
--set ingress-controller.enabled=true \
77+
--set ingress-controller.config.provider.type=apisix-standalone \
78+
--set ingress-controller.apisix.adminService.namespace=ingress-apisix \
79+
--set ingress-controller.gatewayProxy.createDefault=true \
80+
apisix/apisix
81+
```
82+
83+
## Install APISIX Ingress Controller
84+
85+
The script below installs APISIX Ingress Controller:
5186

87+
```bash
5288
# Set the access address and adminkey for apisix
5389
helm install apisix-ingress-controller \
5490
--create-namespace \

0 commit comments

Comments
 (0)