Skip to main content

Version: 3.2.16.3

Install API7 Enterprise on OpenShift

This guide walks you through how to deploy API7 Enterprise on a OpenShift cluster.

Architecture

Overview

API7 Enterprise includes two sets of components:

  1. Control Plane: API7 Dashboard, API7 DP Manager, Database (can use RDS instead), Other Components.
  2. Data Plane: API7 Gateway

Architecture overview

High Availability Deployment Pattern

high availability deployment architectural diagram

Prerequisites

Deploy a OpenShift Cluster

Have a running OpenShift Cluster:

cluster overview

cluster machine pool

Manage Security Context Constraints (SCCs)

Security Context Constraints (SCCs) are a set of APIs on OpenShift used to manage security policy constraints for pods.

The SCCs enabled by default in OpenShift is extremely strict and requires the process in the container to be read-only for the file system. Follow the managing security context constraints doc to use a more flexible SCC nonroot-v2 for API7 Enterprise.

Configure OpenShift CLI

Install OpenShift CLI (oc) or download it from the console:

Download the OpenShift CLI (oc) on the console

Find the login command on the console:

copy login command from console

Log in to the OpenShift Cluster with your token and server address:

oc login \
--token=sha256~pesd0RAyKiKJLkkKJ4Oh2lmy4KSX9b5J6Fc24FYM2EQ \
--server=https://api.api7.93ew.p1.openshiftapps.com:6443
info

Make sure that your user account has the cluster-admin role to perform cluster management.

You should see a response similar to the following:

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

Create a project in the console:

Create a project in the OpenShift console

Alternatively, you can create a project using the CLI:

oc new-project api7-enterprise-project

The project name will be used as the Kubernetes namespace.

Switch the default project to api7-enterprise-project:

oc project api7-enterprise-project

Install API7 Enterprise

Add API7 Helm Chart Repository

Add the API7 repository https://charts.api7.ai:

Add API7 Helm chart repository

Fill in the details of the Helm chart repository

Install Control Plane

Select Api7ee3 Helm chart and create:

select the control plane Helm chart

install the control plane chart

Select the chart version:

select the chart version

Paste the following snippet to replace the default values:

# adjust the values if needed for additional customizations
postgresql:
primary:
podSecurityContext:
fsGroup: 1001020000
containerSecurityContext:
runAsUser: 1001020000
prometheus:
server:
podSecurityContext:
fsGroup: 1001020000
containerSecurityContext:
runAsUser: 1001020000

Finish by clicking Create. You should see the components installed:

Finished installation

See all the created services:

kubectl 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

Activate License in the Dashboard

Port forward the Dashboard service to localhost:7443:

kubectl port-forward svc/api7ee3-dashboard 7443:7443

If successful, you should be able to visit the dashboard at https://localhost:7443.

Log in with admin as both the username and the password:

log in with admin/admin

Then upload your license. If you do not have a license, you can request a 30-day trial license.

upload license

Select Activate:

activate the license

You should now be redirected to the Dashboard main interface.

Add Control Plane Address

Before adding more Gateway instances, first configure the connection address of the control plane.

In the same cluster, the data plane and control plane follow the format of https://{service-name}.{namespace}.svc.cluster:7943, regardless of whether they are deployed under the same namespace.

add control plane address

By default, API7 Gateway and control plane will authenticate with mTLS for verification. You should configure https://{service-name}.{namespace}.svc.cluster:7943 as the control plane address.

Install Data Plane

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.

Create a service account:

oc create serviceaccount api7-gateway

Create a role with nonroot-v2 SCC:

oc create role api7-gateway \
--verb=use \
--resource=scc
--resource-name=nonroot-v2

Bind the role to the service account:

oc create rolebinding api7-gateway \
--role=api7-gateway
--serviceaccount=api7-enterprise-project:api7-gateway

Generate and Run Deployment Script

Compared with Apache APISIX, API7 Enterprise introduces an additional logical grouping called Gateway Group, where you can manage different sets of Gateway instances with the same API7 Dashboard.

First, you should create or choose the target Gateway Group. In this guide, you will use the default gateway group:

Find the default gateway group in the Dashboard

Next, select Add Gateway Instance:

Add gateway instance

Switch to the Kubernetes tab and fill out the parameters. Once finished, click Generate to see the deployment script.

Generate deployment script

Copy the generated script and set the additional securityContext. The command should be similar to the following:

helm repo add api7 https://charts.api7.ai
helm repo update
cat > /tmp/tls.crt <<EOF
-----BEGIN CERTIFICATE-----
MIIBiDCCATqgAwIBAgICBAAwBQYDK2VwMEQxCzAJBgNVBAYTAlVTMRMwEQYDVQQI
EwpDYWxpZm9ybmlhMQ0wCwYDVQQKEwRBUEk3MREwDwYDVQQDEwhBUEk3IEluYzAe
Fw0yNDA4MDkwOTQwNDJaFw0yNTA5MDgwOTQwNDJaMDAxDTALBgNVBAoTBEFQSTcx
HzAdBgNVBAMTFmFwaTdlZTMtYXBpc2l4LWdhdGV3YXkwKjAFBgMrZXADIQBSZVOn
f8Xu63XylUmRi8jvx0G4XUtPQGoYHdSTeyLF36NkMGIwDgYDVR0PAQH/BAQDAgeA
MBMGA1UdJQQMMAoGCCsGAQUFBwMCMC0GA1UdDgQmBCRlOTcwNDRjNy0xZjM2LTQ5
OTYtOTc1NC1hZDY4OTU2Yjk3ZGMwDAYDVR0jBAUwA4ABMDAFBgMrZXADQQAnpSpi
G+X9AgBYUhY3XBe6q9c75RzDjwTf2g9rkmD0VJxYrWVtT95xRwBufiRUsnRh24WE
7NmLI3rE5aGoY0wH
-----END CERTIFICATE-----
EOF
cat > /tmp/tls.key <<EOF
-----BEGIN PRIVATE KEY-----
MC4CAQAwBQYDK2VwBCIEIAokQWsCGewdhhxAKjUFWAyJknZqJWhOCChVbJOXBspi
-----END PRIVATE KEY-----
EOF
cat > /tmp/ca.crt <<EOF
-----BEGIN CERTIFICATE-----
MIIBdTCCASegAwIBAgIQRR8k78lPFZM+mtyAUfz5rjAFBgMrZXAwRDELMAkGA1UE
BhMCVVMxEzARBgNVBAgTCkNhbGlmb3JuaWExDTALBgNVBAoTBEFQSTcxETAPBgNV
BAMTCEFQSTcgSW5jMB4XDTI0MDgwOTA2MjUxOFoXDTM0MDgwNzA2MjUxOFowRDEL
MAkGA1UEBhMCVVMxEzARBgNVBAgTCkNhbGlmb3JuaWExDTALBgNVBAoTBEFQSTcx
ETAPBgNVBAMTCEFQSTcgSW5jMCowBQYDK2VwAyEAplXlP4zxS8cq1Qa5Syd7r/ya
SaolzMQBLTMQfcKkb16jLzAtMA4GA1UdDwEB/wQEAwIChDAPBgNVHRMBAf8EBTAD
AQH/MAoGA1UdDgQDBAEwMAUGAytlcANBAJ0ezih/La2Ajc7bi1WdlzIi+T3oIPta
d/l1PkE5rDLxySMzJvowk49earvcz5rVILf2aG/k1YRc7Kc+cmnLlAs=
-----END CERTIFICATE-----
EOF
kubectl create secret generic api7-ee-3-gateway-tls --from-file=tls.crt=/tmp/tls.crt --from-file=tls.key=/tmp/tls.key --from-file=ca.crt=/tmp/ca.crt
helm upgrade --install api7-ee-3-gateway api7/gateway \
--set "etcd.auth.tls.enabled=true" \
--set "etcd.auth.tls.existingSecret=api7-ee-3-gateway-tls" \
--set "etcd.auth.tls.certFilename=tls.crt" \
--set "etcd.auth.tls.certKeyFilename=tls.key" \
--set "etcd.auth.tls.verify=true" \
--set "gateway.tls.existingCASecret=api7-ee-3-gateway-tls" \
--set "gateway.tls.certCAFilename=ca.crt" \
--set "apisix.extraEnvVars[0].name=API7_GATEWAY_GROUP_SHORT_ID" \
--set "apisix.extraEnvVars[0].value=default" \
--set "etcd.host[0]=https://api7ee3-dp-manager.api7-enterprise-project.svc.cluster.local:7943" \
--set "apisix.replicaCount=1" \
--set "serviceAccount.name=api7-gateway" \
--set "apisix.image.repository=api7/api7-ee-3-gateway" \
--set "apisix.image.tag=3.2.14.4"
--set "apisix.securityContext.runAsNonRoot=true" \
--set "apisix.securityContext.runAsUser=636"

Install API gateway instances on your cluster.

Navigating back to the default gateway group, you should see an healthy gateway instance:

See an activate gateway instance

Verify Installation

Create a Sample Service

Create a service HTTPBIN:

Create a service httpbin

Add a route to /anything endpoint and allow only the GET method:

Add a route with GET method

You should see the service now shows the created route:

Dashboard showing the service with the created route

Port Forward Gateway Service

Before you can send a request to the Gateway, you should first port forward the gateway listening port to the localhost.

First, list all Services to check the gateway service name:

kubectl get svc

The gateway service name is api7-ee-3-gateway-gateway:

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

Next, forward the gateway port 80 to localhost:9080:

kubectl port-forward svc/api7-ee-3-gateway-gateway 9080:80

Send a Request

This request receives the correct response, which means the installation is successfully.

curl "http://127.0.0.1:9080/anything" -i

You should receive an HTTP/1.1 200 OK response similar to the following:

{
"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 Next

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. See Managing APISIX Declaratively with APISIX Declarative CLI (ADC).

See Getting Started tutorials to learn more about how to work with ADC.

FAQ

How to Connect to Existing PostgreSQL?

Configure your database DSN in the Helm values file:

dashboard_configuration:
database:
dsn: "postgres://api7ee:changeme@api7-postgresql:5432/api7ee"

dp_manager_configuration:
database:
dsn: "postgres://api7ee:changeme@api7-postgresql:5432/api7ee"

API7.ai Logo

API Management for Modern Architectures with Edge, API Gateway, Kubernetes, and Service Mesh.

Product

API7 Cloud

SOC2 Type IIISO 27001HIPAAGDPRRed Herring

Copyright © APISEVEN Ltd. 2019 – 2024. Apache, Apache APISIX, APISIX, and associated open source project names are trademarks of the

Apache Software Foundation