title |
---|
Installing Apache APISIX |
This guide walks you through how you can build and get Apache APISIX running on your environment. Please refer the Getting Started guide for a quick walkthrough on running Apache APISIX.
Apache APISIX can be installed via the RPM package, Docker image, Helm Chart or the source release package. You can install via any one of these options.
This installation method is suitable for CentOS 7.
If the official OpenResty repository is not installed yet, the following command will help you automatically install both OpenResty and Apache APISIX repositories.
sudo yum install -y https://repos.apiseven.com/packages/centos/apache-apisix-repo-1.0-1.noarch.rpm
If the official OpenResty repository is installed, the following command will help you automatically install the repositories of Apache APISIX.
sudo yum-config-manager --add-repo https://repos.apiseven.com/packages/centos/apache-apisix.repo
Run the following commands to install the repository and Apache APISIX.
# View the information of the latest apisix package
sudo yum info -y apisix
# Will show the existing apisix packages
sudo yum --showduplicates list apisix
# Will install the latest apisix package
sudo yum install apisix
First, download Apache APISIX offline RPM package to ./apisix
folder.
sudo mkdir -p apisix
sudo yum install -y https://repos.apiseven.com/packages/centos/apache-apisix-repo-1.0-1.noarch.rpm
sudo yum clean all && yum makecache
sudo yum install -y --downloadonly --downloaddir=./apisix apisix
Then copy ./apisix
folder to the target host and run the following command to install.
sudo yum install ./apisix/*.rpm
Please refer to Installing Apache APISIX with Docker.
Please refer to Installing Apache APISIX with Helm Chart.
Follow the steps below to install Apache APISIX via the source release package.
- Create a directory named
apisix-2.12.0
.
APISIX_VERSION='2.12.0'
mkdir apisix-${APISIX_VERSION}
- Download the Apache APISIX source release package.
wget https://downloads.apache.org/apisix/${APISIX_VERSION}/apache-apisix-${APISIX_VERSION}-src.tgz
You can also download the Apache APISIX source release package from the Apache APISIX website. The website also provides source packages for Apache APISIX, APISIX Dashboard, and APISIX Ingress Controller.
- Unzip the Apache APISIX source release package.
tar zxvf apache-apisix-${APISIX_VERSION}-src.tgz -C apisix-${APISIX_VERSION}
- Install the runtime dependent Lua libraries.
# Switch to the apisix-${APISIX_VERSION} directory
cd apisix-${APISIX_VERSION}
# Create dependencies
make deps
# Install apisix command
make install
Note: If make deps
fails with "install lualdap
failed" with an error like Could not find header file for LDAP
try the solution below.
Solution: Set LDAP_DIR
with luarocks config
manually. For example luarocks config variables.LDAP_DIR /usr/local/opt/openldap/
.
-
To uninstall the Apache APISIX runtime, run:
# Uninstall apisix command make uninstall # Purge dependencies make undeps
Note: This operation will remove the files completely.
The current LTS version of Apache APISIX is 2.10.4
.
To install this version, set APISIX_VERSION
Set APISIX_VERSION
in Installation via Source Release Package to 2.10.4
and continue with the other steps.
This step is required only if you haven't installed etcd.
Run the command below to install etcd via the binary.
ETCD_VERSION='3.4.13'
wget https://github.com/etcd-io/etcd/releases/download/v${ETCD_VERSION}/etcd-v${ETCD_VERSION}-linux-amd64.tar.gz
tar -xvf etcd-v${ETCD_VERSION}-linux-amd64.tar.gz && \
cd etcd-v${ETCD_VERSION}-linux-amd64 && \
sudo cp -a etcd etcdctl /usr/bin/
nohup etcd >/tmp/etcd.log 2>&1 &
In the Apache APISIX directory, you can initialize dependencies, start service and stop service with commands. Run apisix help
to get a full list of available commands.
Run the following command to initialize the NGINX configuration file and etcd.
# initialize NGINX config file and etcd
apisix init
Run the following command to test the configuration file. APISIX will generate nginx.conf
from config.yaml
and check whether the syntax of nginx.conf
is correct.
# generate `nginx.conf` from `config.yaml` and test it
apisix test
Run the following command to start Apache APISIX.
# start Apache APISIX server
apisix start
Both apisix quit
and apisix stop
can stop Apache APISIX. The main difference is that apisix quit
stops Apache APISIX gracefully, while apisix stop
stops Apache APISIX immediately.
It is recommended to use the "gracefully stop" command apisix quit
because it ensures that Apache APISIX will complete all the requests it has received before stopping. On the other hand, apisix stop
will trigger a forced shutdown and will stop Apache APISIX immediately. This will cause the pending incoming requests to not be processed before shutdown.
To perform a graceful shutdown, run:
# stop Apache APISIX server gracefully
apisix quit
To perform a forced shutdown, run:
# stop Apache APISIX server immediately
apisix stop
You can get help and learn more about all the available operations in Apache APISIX by running the help
command as shown below.
# show a list of available operations
apisix help
To run the test cases, run the steps outlined below.
-
Install
cpanminus
, the package manager forperl
. -
Install the test-nginx dependencies via
cpanm
as shown below.
sudo cpanm --notest Test::Nginx IPC::Run > build.log 2>&1 || (cat build.log && exit 1)
- Clone the latest source code locally by using the forked out version.
git clone https://github.com/openresty/test-nginx.git
-
There are two ways to run the tests.
-
Append the current directory to the perl module directory:
export PERL5LIB=.:$PERL5LIB
and then runmake test
command. -
Specify the NGINX binary path by running
TEST_NGINX_BINARY=/usr/local/bin/openresty prove -Itest-nginx/lib -r t
.
:::note Note
Some of the tests rely on external services and system configuration modification. For a complete test environment build, you can refer to ci/linux_openresty_common_runner.sh
.
:::
The solution to the Error unknown directive "lua_package_path" in /API_ASPIX/apisix/t/servroot/conf/nginx.conf
error is as shown below.
Ensure that OpenResty is set to the default NGINX, and export the path as follows:
export PATH=/usr/local/openresty/nginx/sbin:$PATH
- Linux default installation path:
export PATH=/usr/local/openresty/nginx/sbin:$PATH
- MacOS default installation path via homebrew:
export PATH=/usr/local/opt/openresty/nginx/sbin:$PATH
- Linux default installation path:
To run a specific test case, use the command below.
prove -Itest-nginx/lib -r t/plugin/openid-connect.t
For more details on the test cases, see the testing framework document.
You can modify the Admin API key to secure your Apache APISIX deployment.
This can be done by modifying the apisix.admin_key
in conf/config.yaml
and restarting the service.
apisix:
# ... ...
admin_key
-
name: "admin"
key: abcdefghabcdefgh # Modify the original key to abcdefghabcdefgh
role: admin
Then to access the Admin API, you can use the above key.
curl http://127.0.0.1:9080/apisix/admin/routes?api_key=abcdefghabcdefgh -i
A status code of 200 in the returned result will indicate that the access was successful.
HTTP/1.1 200 OK
Date: Fri, 28 Feb 2020 07:48:04 GMT
Content-Type: text/plain
... ...
{"node":{...},"action":"get"}
If the key you entered does not match the value of apisix.admin_key
in conf/config.yaml
, a response with a status code 401 will indicate that the access failed.
curl http://127.0.0.1:9080/apisix/admin/routes?api_key=wrong-key -i
HTTP/1.1 401 Unauthorized
Date: Fri, 28 Feb 2020 08:17:58 GMT
Content-Type: text/html
... ...
{"node":{...},"action":"get"}
Some features require additional NGINX modules to be introduced into OpenResty.
If you need these features, you can build APISIX OpenResty. You can refer to the source of api7/apisix-build-tools for setting up your build environment and building APISIX OpenResty.
If you are using CentOS 7 and you installed Apache APISIX via the RPM package, the configuration file will already be in place and you can run the following command directly.
systemctl start apisix
systemctl stop apisix
If you installed Apache APISIX by other methods, please refer to the configuration file template for a modification guide and copy it to the /usr/lib/systemd/system/apisix.service
path.