Kubernetes
Background
This guide explains how to deploy API7 Enterprise 3.2.9.5 in OpenShift Cluster.
Architecture
Overview
API7 Enterprise includes two sets of components:
- Control Plane: API7 Dashboard, API7 DP Manager, Database (can use RDS instead), Other Components.
- Data Plane: API7 Gateway
High Availability Deployment Pattern
OpenShift Cluster Overview
Prerequisite
SCC (Security Context Constraints) is a set of APIs in Kubernetes used to define security policy constraints for Pods. The SCC enabled by default in OpenShift is extremely strict and requires the process in the container to be read-only for the file system. You should follow the next steps to authorize the API7 Enterprise Edition to use a more flexible SCC nonroot-v2 (https://docs.openshift.com/dedicated/authentication/managing-security-context-constraints.html):
Configure OC
Download the OC command line tool and complete the Auth to connect to OpenShift Cluster with the admin-cluster permission.
Copy your login command, and run the following commands:
#NOTE: Please use your OpenShift Login Command
$ ./oc login --token=sha256~pesd0RAyKiKJLkkKJ4Oh2lmy4KSX9b5J6Fc24FYM2EQ --server=https://api.api7.93ew.p1.openshiftapps.com:6443
Logged into "https://api.api7.93ew.p1.openshiftapps.com:6443" as "admin" using the token provided.
You have access to 102 projects, the list has been suppressed. You can list all projects with 'oc projects'
Using project "default".
Create a Project
In this guidance, one project called api7-enterprise-project is already created. In OpenShift, the project name is the same as the namespace name.
API7 Enterprise Installation
Step 1: Add API7 Helm Chart Repository
Please add API7 repository: https://charts.api7.ai/
Step 2: Install Control Plane
Please use Chart v0.12.2 and copy the following snippet to replace the default values:
# If you need customizations, please adjust accordingly.
postgresql:
primary:
podSecurityContext:
fsGroup: 1001020000
containerSecurityContext:
runAsUser: 1001020000
prometheus:
server:
podSecurityContext:
fsGroup: 1001020000
containerSecurityContext:
runAsUser: 1001020000
List all created Services:
$ kubectl -n api7-enterprise-project get svc -owide -l app.kubernetes.io/name=api7ee3
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE SELECTOR
api7ee3-dashboard ClusterIP 172.30.249.55 <none> 7080/TCP 28m app.kubernetes.io/component=dashboard,app.kubernetes.io/instance=api7ee3,app.kubernetes.io/name=api7ee3
api7ee3-dp-manager ClusterIP 172.30.43.83 <none> 7900/TCP,7943/TCP 28m app.kubernetes.io/component=dp-manager,app.kubernetes.io/instance=api7ee3,app.kubernetes.io/name=api7ee3
Expose Dashboard to localhost:7080:
$ kubectl -n api7-enterprise-project port-forward svc/api7ee3-dashboard 7080:7080
Forwarding from 127.0.0.1:7080 -> 7080
Forwarding from [::1]:7080 -> 7080
Step 3: Visit the Dashboard and Activate License
Please visit http://localhost:7080, login with admin as username and password (by default) and upload your License. You can request one 30 days license from here: https://api7.ai/try?product=enterprise.
Step 4: Configure Control Plane Address
Before adding more API Gateway instances, you need to configure the connection address of the control plane. In the same cluster, the data plane and control plane can use the format of http://{service-name}.{namespace}.svc.cluster:7900 regardless of whether they are deployed under the same namespace.
mTLS (Optional)
By default, API7 Gateway and Control Plane will be authenticated through Token. If you prefer to use mTLS for verification, you need to enable the mTLS option and using this address: http://{service-name}.{namespace}.svc.cluster:7943
Step 5: Generate Data Plane Installation Script
Configure SCC for API7 Gateway
API7 Gateway needs to generate local files at runtime, including nginx.conf, logs, and cached files. The nonroot-v2 SCC is sufficient with the required permissions.
$ ./oc create serviceaccount api7-gateway -n api7-enterprise-project
$ ./oc create role api7-gateway --verb=use --resource=scc --resource-name=nonroot-v2 -n api7-enterprise-project
$ ./oc create rolebinding api7-gateway --role=api7-gateway --serviceaccount=api7-enterprise-project:api7-gateway
Compared with Apache APISIX, API7 Enterprise adds the ability of Gateway Group, which means that you can manage different API Gateway instances by deploying only one set of API7 Dashboard. First, you should create or choose the target Gateway Group. In this guidance, you will use the default gateway group.
Second, click Add Gateway Instance, and switch to the Kubernetes tab.
After filling in necessary fields, click Generate.
Finally, please copy the generated script to install API gateway instances on your Kubernetes.
Now you have updated the permission policy and you can continue API7 installation.
$ helm repo add api7 https://charts.api7.ai
$ helm repo update
$ helm install -n api7-enterprise-project --create-namespace api7-ee-3-gateway api7/gateway \
--set "apisix.extraEnvVars[0].name=API7_CONTROL_PLANE_TOKEN" \
--set "apisix.extraEnvVars[0].value=a7ee-AoPh2G125X970K9u5I0Y6KVu63WK9SzfVE1422E6Sl28o9F7j94db315147f094182aabc37be0b0a470e" \
--set "apisix.image.repository=api7/api7-ee-3-gateway" \
--set "apisix.image.tag=3.2.9.5" \
--set "etcd.host[0]=http://api7ee3-dp-manager.api7-enterprise-project.svc.cluster.local:7900" \
--set "apisix.replicaCount=1" \
--set "serviceAccount.name=api7-gateway" \
--set "apisix.securityContext.runAsNonRoot=true" \
--set "apisix.securityContext.runAsUser=636"
Go back to the default gateway group, there has one active gateway instance:
Step 6: Validation
Proxy Gateway Port to Localhost
First, list all Services in the api7-enterprise-project namespace:
$ kubectl -n api7-enterprise-project get svc
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
api7-ee-3-gateway-gateway NodePort 172.30.211.30 <none> 80:31649/TCP 3m51s
api7-postgresql ClusterIP 172.30.215.68 <none> 5432/TCP 56m
api7-postgresql-hl ClusterIP None <none> 5432/TCP 56m
api7-prometheus-server ClusterIP 172.30.3.68 <none> 9090/TCP 56m
api7ee3-dashboard ClusterIP 172.30.249.55 <none> 7080/TCP 56m
api7ee3-dp-manager ClusterIP 172.30.43.83 <none> 7900/TCP,7943/TCP 56m
Second, proxy the gateway port (80 by default) to localhost:9080:
$ kubectl -n api7-enterprise-project port-forward svc/api7-ee-3-gateway-gateway 9080:80
Forwarding from 127.0.0.1:9080 -> 9080
Forwarding from [::1]:9080 -> 9080
Handling connection for 9080
Create a Service
Publish the Service
Send a Request
This request receives the correct response, which means our installation is successfully.
$ curl localhost:9080/anything -i
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 378
Connection: keep-alive
Date: Wed, 20 Mar 2024 07:29:53 GMT
Access-Control-Allow-Origin: *
Access-Control-Allow-Credentials: true
Server: API7/3.2.9.5
{
"args": {},
"data": "",
"files": {},
"form": {},
"headers": {
"Accept": "*/*",
"Host": "localhost",
"User-Agent": "curl/8.4.0",
"X-Amzn-Trace-Id": "Root=1-65fa9071-7506ab7b0e98d7546e3c0845",
"X-Forwarded-Host": "localhost"
},
"json": null,
"method": "GET",
"origin": "::1, 3.1.235.149",
"url": "http://localhost/anything"
}
What's More
In addition to publishing services through the Dashboard UI, API7 provides a command line tool that can operate declarative configuration, so you can integrate API7 Operations with internal GitOps. Please refer to: https://api7.ai/blog/managing-apisix-declaratively
Download ADC: https://run.api7.ai/adc/release/adc_0.7.3_linux_amd64.tar.gz
FAQ
How to Connect to Existing PostgreSQL?
Please refer to https://github.com/api7/api7-helm-chart/blob/main/charts/api7/values.yaml and set your database connection for the following parameters:
dashboard_configuration:
database:
dsn: "postgres://api7ee:changeme@api7-postgresql:5432/api7ee"
dp_manager_configuration:
database:
dsn: "postgres://api7ee:changeme@api7-postgresql:5432/api7ee"