Skip to content

Commit 9c94283

Browse files
AlinsRandspo
AlinsRan
authored and
dspo
committed
doc: add getting-started doc (#2450)
(cherry picked from commit a92361e)
1 parent 5106149 commit 9c94283

File tree

3 files changed

+331
-0
lines changed

3 files changed

+331
-0
lines changed

‎docs/en/latest/config.json‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
{
2+
"version": "0.3.0",
3+
"sidebar": [
4+
{
5+
"type": "doc",
6+
"id": "getting-started"
7+
},
8+
{
9+
"type": "category",
10+
"label": "Concepts",
11+
"items": [
12+
"concepts/resources",
13+
"concepts/gateway-api",
14+
"concepts/deployment-architecture"
15+
]
16+
},
17+
{
18+
"type": "doc",
19+
"id": "install"
20+
},
21+
{
22+
"type": "doc",
23+
"id": "developer-guide"
24+
},
25+
{
26+
"type": "doc",
27+
"id": "api-reference"
28+
},
29+
{
30+
"type": "doc",
31+
"id": "upgrade-guide"
32+
},
33+
{
34+
"type": "link",
35+
"label": "CHANGELOG",
36+
"href": "https://github.com/apache/apisix-ingress-controller/blob/master/CHANGELOG.md"
37+
}
38+
]
39+
}

‎docs/en/latest/install.md‎

Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
1+
---
2+
title: Install with Helm
3+
keywords:
4+
- APISIX ingress
5+
- Apache APISIX
6+
- Kubernetes ingress
7+
- kind
8+
description: Guide to install APISIX ingress controller on kind.
9+
---
10+
<!--
11+
#
12+
# Licensed to the Apache Software Foundation (ASF) under one or more
13+
# contributor license agreements. See the NOTICE file distributed with
14+
# this work for additional information regarding copyright ownership.
15+
# The ASF licenses this file to You under the Apache License, Version 2.0
16+
# (the "License"); you may not use this file except in compliance with
17+
# the License. You may obtain a copy of the License at
18+
#
19+
# http://www.apache.org/licenses/LICENSE-2.0
20+
#
21+
# Unless required by applicable law or agreed to in writing, software
22+
# distributed under the License is distributed on an "AS IS" BASIS,
23+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
24+
# See the License for the specific language governing permissions and
25+
# limitations under the License.
26+
#
27+
-->
28+
29+
Helm is a package manager for Kubernetes that automates the release and management of software on Kubernetes.
30+
31+
This document guides you through installing the APISIX ingress controller using Helm.
32+
33+
## Prerequisites
34+
35+
Before installing APISIX ingress controller, ensure you have:
36+
37+
1. A working Kubernetes cluster (version 1.26+)
38+
- Production: TKE, EKS, AKS, or other cloud-managed clusters
39+
- Development: minikube, kind, or k3s
40+
2. [kubectl](https://kubernetes.io/docs/tasks/tools/) installed and configured to access your cluster
41+
3. [Helm](https://helm.sh/) (version 3.8+) installed
42+
43+
Make sure to update the Helm repositories:
44+
45+
```bash
46+
helm repo add apisix https://charts.apiseven.com
47+
helm repo add bitnami https://charts.bitnami.com/bitnami
48+
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:
86+
87+
```bash
88+
# Set the access address and adminkey for apisix
89+
helm install apisix-ingress-controller \
90+
--create-namespace \
91+
-n ingress-apisix \
92+
--set gatewayProxy.createDefault=true \
93+
--set gatewayProxy.provider.controlPlane.auth.adminKey.value=edd1c9f034335f136f87ad84b625c8f1 \
94+
--set apisix.adminService.namespace=apisix-ingress \
95+
--set apisix.adminService.name=apisix-admin \
96+
--set apisix.adminService.port=9180 \
97+
apisix/apisix-ingress-controller
98+
```

‎docs/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` | |

0 commit comments

Comments
 (0)