Skip to content

Commit e9ae56b

Browse files
authored
docs: add install and developer-guide doc (#2439)
1 parent ba8910b commit e9ae56b

File tree

2 files changed

+180
-0
lines changed

2 files changed

+180
-0
lines changed

docs/en/latest/developer-guide.md

Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
---
2+
title: Developer Guide
3+
keywords:
4+
- APISIX ingress
5+
- Apache APISIX
6+
- Kubernetes ingress
7+
- Development
8+
- Contribute
9+
description: Setting up development environment for APISIX Ingress controller.
10+
---
11+
<!--
12+
#
13+
# Licensed to the Apache Software Foundation (ASF) under one or more
14+
# contributor license agreements. See the NOTICE file distributed with
15+
# this work for additional information regarding copyright ownership.
16+
# The ASF licenses this file to You under the Apache License, Version 2.0
17+
# (the "License"); you may not use this file except in compliance with
18+
# the License. You may obtain a copy of the License at
19+
#
20+
# http://www.apache.org/licenses/LICENSE-2.0
21+
#
22+
# Unless required by applicable law or agreed to in writing, software
23+
# distributed under the License is distributed on an "AS IS" BASIS,
24+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
25+
# See the License for the specific language governing permissions and
26+
# limitations under the License.
27+
#
28+
-->
29+
30+
This document walks through how you can set up your development environment to contribute to APISIX Ingress controller.
31+
32+
## Prerequisites
33+
34+
Before you get started make sure you have:
35+
36+
1. Installed [Go 1.23](https://golang.org/dl/) or later
37+
2. A Kubernetes cluster available. We recommend using [kind](https://kind.sigs.k8s.io/).
38+
3. Installed APISIX in Kubernetes using [Helm](https://github.com/apache/apisix-helm-chart).
39+
4. Installed [ADC v0.20.0+](https://github.com/api7/adc/releases)
40+
41+
## Fork and clone
42+
43+
1. Fork the repository [apache/apisix-ingress-controller](https://github.com/apache/apisix-ingress-controller) to your GitHub account
44+
2. Clone the fork to your workstation.
45+
3. Run `go mod download` to download the required modules.
46+
47+
:::tip
48+
49+
If you are in China, you can speed up the downloads by setting `GOPROXY` to `https://goproxy.cn`.
50+
51+
:::
52+
53+
## Install CRD and Gateway API
54+
55+
To install the [CRD](./concepts/resources.md#apisix-ingress-controller-crds-api) and [Gateway API](https://gateway-api.sigs.k8s.io/), run the following commands:
56+
57+
```shell
58+
make install
59+
```
60+
61+
## Build from source
62+
63+
To build APISIX Ingress controller, run the command below on the root of the project:
64+
65+
```shell
66+
make build
67+
```
68+
69+
Now you can run it by:
70+
71+
```shell
72+
# for ARM64 architecture, use the following command:
73+
# ./bin/apisix-ingress-controller_arm64 version
74+
./bin/apisix-ingress-controller_amd64 version
75+
```
76+
77+
## Building Image
78+
79+
To build a Docker image for APISIX Ingress controller, you can use the following command:
80+
81+
```shell
82+
make build-image IMG=apache/apisix-ingress-controller:dev
83+
```
84+
85+
## Running tests
86+
87+
### Unit Tests
88+
89+
To run unit tests:
90+
91+
```shell
92+
make unit-test
93+
```
94+
95+
### e2e Tests
96+
97+
To run end-to-end tests, you need to install [kind](https://kind.sigs.k8s.io/).
98+
99+
Launch a kind cluster with the following command:
100+
101+
```shell
102+
make kind-up
103+
```
104+
105+
To run end-to-end e2e-tests against any changes, you need to load the built Docker images into the Kubernetes cluster:
106+
107+
```shell
108+
# build docker image for APISIX Ingress controller
109+
make build-image
110+
# load the image into kind cluster
111+
make kind-load-images
112+
```
113+
114+
Currently, we use Kind version `0.26.0` and Kubernetes version `1.26+` for running the tests.
115+
116+
```shell
117+
make e2e-test
118+
```

docs/en/latest/install.md

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
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+
## 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.
46+
47+
```shell
48+
helm repo add apisix https://charts.apiseven.com
49+
helm repo add bitnami https://charts.bitnami.com/bitnami
50+
helm repo update
51+
52+
# Set the access address and adminkey for apisix
53+
helm install apisix-ingress-controller \
54+
--create-namespace \
55+
-n ingress-apisix \
56+
--set gatewayProxy.createDefault=true \
57+
--set gatewayProxy.provider.controlPlane.auth.adminKey.value=edd1c9f034335f136f87ad84b625c8f1 \
58+
--set apisix.adminService.namespace=apisix-ingress \
59+
--set apisix.adminService.name=apisix-admin \
60+
--set apisix.adminService.port=9180 \
61+
apisix/apisix-ingress-controller
62+
```

0 commit comments

Comments
 (0)