Ana içeriğe geç

Kubernetes Installation

Apinizer modules can be installed on Kubernetes using two different methods: with raw Kubernetes Manifest YAML files or with Helm chart. From the top tabs below you can select your preferred deployment method, and from the inner tabs you can select the module you want to install. Each module has its own resource requirements, environment variables and service definitions.

Installation Flow​

Follow this sequence to install Apinizer modules on Kubernetes:

MongoDB (Prerequisite)

Required for Manager metadata, deployed proxy snapshots, and Integration scheduler queue. See MongoDB Installation.

API Manager

Apinizer Management Console. API Traffic Managers and API administration operate through this application. License key is loaded via this module.

Gateway

The actual API Gateway. Must be defined as at least one environment through API Manager. Can be deployed as Managed (under Apinizer control) or Remote (external cluster).

Optional Modules​

After completing the mandatory steps above, you can optionally deploy the following modules based on your requirements:

Cache

Shared Hazelcast cache. Recommended for rate limit, JWT cache, cluster-wide state. Can be deployed as Managed or Remote. Learn more

Integration

Quartz-based task scheduler. For scheduled API calls and batch jobs. Learn more

API Portal

Developer portal for the API catalog. API consumers create tokens and discover APIs. Learn more

Elasticsearch

Recommended for indexing high-volume API traffic logs. Without it, logs are written to MongoDB. Learn more

API Manager with SSL

HTTPS termination for Manager. Learn more

Tip

Pick your preferred deployment method (Manifest YAML or Helm chart) from the tabs below; both follow the same steps.

Install Apinizer modules on a cluster step by step using raw Kubernetes Manifest (YAML) files. This method provides full control over the cluster; it applies Deployment, Service, ConfigMap, Secret, RBAC and Ingress definitions for each module as separate files. It does not use a package manager like Helm; it works directly with kubectl apply -f.

API Manager and Gateway installations are mandatory — the actual API Gateway of Apinizer is this Gateway module. Follow the steps below in order: API Manager must be up first, then at least one Gateway must be installed and defined as an environment through the Manager. Cache, Integration and API Portal modules are optional and can be installed from the tabs at the bottom of the page.

API Manager Installation​

The Apinizer Management Console (API Manager) is the component through which Apinizer is managed. API Traffic Managers, those who manage APIs, and API consumers can perform their necessary operations through this application.

Info

After Apinizer images are deployed to Kubernetes environment, you need to add the License Key provided to you by Apinizer to the database.

Pre-Installation Steps​

Warning

MongoDB installation is mandatory — you must have a running MongoDB instance before bringing up Apinizer. Manager metadata, deployed proxy snapshots, Integration scheduler queue, and audit records all live on MongoDB. This dependency does not change whichever runtime (Kubernetes, Docker, or Virtual Server) you pick.

A replica set is recommended for production; a single node is only suitable for PoC / development. For installation steps → continue at MongoDB Installation.

Note

Elasticsearch is important for API traffic log indexing and search; it is optional. Without Elasticsearch, traffic logs are written to MongoDB — Elasticsearch is recommended for high-traffic environments. For details → see Elasticsearch Installation.

Defining Kubernetes Permissions and Creating Namespaces​

Kubernetes API permissions need to be defined for Apinizer to access pods in the created Namespace.

In Kubernetes, ClusterRole and ClusterRoleBinding provide role and role assignment mechanisms at the Kubernetes cluster level. These two resources enable cluster administrators and application developers to manage access and permissions to Kubernetes resources.

If Environment management will be done through API Manager, permissions need to be defined for Apinizer to access Kubernetes APIs and perform create, delete, update and watch operations on Namespace, Deployment, Pod, Service.

If Kubernetes management is done with Apinizer​

In the following step, Roles and RoleBindings are created on Kubernetes and permissions are defined. Permission is granted for all environments that will be created in this step.

apinizer-role.yaml — Apinizer namespace + RBAC
apiVersion: v1
kind: Namespace
metadata:
  name: apinizer
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: apinizer-role-binding
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: apinizer-role
subjects:
  - apiGroup: rbac.authorization.k8s.io
    kind: Group
    name: system:serviceaccounts
---
kind: ClusterRole
apiVersion: rbac.authorization.k8s.io/v1
metadata:
  name: apinizer-role
rules:
  - apiGroups:
      - ''
    resources:
      - nodes
      - services
      - namespaces
      - pods
      - endpoints
      - pods/log
      - secrets
      - configmaps
    verbs:
      - get
      - list
      - watch
      - update
      - create
      - patch
      - delete
  - apiGroups:
      - apps
    resources:
      - deployments
      - replicasets
      - statefulsets
      - configmaps
    verbs:
      - get
      - list
      - watch
      - update
      - create
      - patch
      - delete
kubectl apply -f apinizer-role.yaml

If Kubernetes management is not done with Apinizer​

Here, permissions are set only for the manager application in the Apinizer namespace.

apinizer-manager-role.yaml — Manager-only namespace + RBAC
apiVersion: v1
kind: Namespace
metadata:
  name: apinizer
---
apiVersion: v1
kind: ServiceAccount
metadata:
  name: manager-serviceaccount
  namespace: apinizer
---
kind: Role
apiVersion: rbac.authorization.k8s.io/v1
metadata:
  name: apinizer-role
  namespace: apinizer
rules:
  - apiGroups:
      - ''
    resources:
      - services
      - namespaces
      - pods
      - endpoints
      - pods/log
      - secrets
    verbs:
      - get
      - list
      - watch
      - update
      - create
      - patch
      - delete
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: manager-serviceaccount-apinizer-role-binding
  namespace: apinizer
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: Role
  name: apinizer-role
subjects:
  - kind: ServiceAccount
    name: manager-serviceaccount
    namespace: apinizer
kubectl apply -f apinizer-manager-role.yaml

Configuration Parameters​

API Manager is a web-based management interface where APIs, Policies, Users, Credentials and configurations are defined, and API Traffic and Analytics data are viewed and analyzed. Configure the following variables according to your environment before deploying API Manager to Kubernetes.

  • APINIZER_VERSION - Parameter indicating which Apinizer version you will install. Click here to see current versions. It is recommended to always use the latest version in new installations. Click here to review release notes.
  • MONGO_DBNAME - Database URL information to be used for Apinizer configurations. It is recommended to use the name "apinizerdb" by default.
  • MONGOX_IP and MONGOX_PORT - IP and port information of MongoDB servers. MongoDB default port is 25080. Apinizer uses port 25080 by default.
  • MONGO_USERNAME and MONGO_PASSWORD - Information about the user defined for Apinizer in your MongoDB application, who is authorized on the relevant database or has the authority to create that database.
  • YOUR_LICENSE_KEY - License key sent to you by Apinizer.
  • K8S_ANY_WORKER_IP - An IP from your Kubernetes Cluster is required for you to access the Apinizer Management Console interface from any web browser after Apinizer installation is completed. This is usually preferred as one of the Kubernetes Worker servers and it is recommended to be placed behind a Load Balancer and DNS later.

Creating secret with MongoDB information​

It is recommended that your MongoDB database connection information be stored in an Encoded form in kubernetes deployments. For this, apply the following steps in the terminal of a Linux-based operating system.

DB_URL='mongodb://<MONGO_USERNAME>:<MONGO_PASSWORD>@<MONGO1_IP>:<MONGO1_PORT>,<MONGO2_IP>:<MONGO2_PORT>,<MONGO3_IP>:<MONGO3_PORT>/?authSource=admin&replicaSet=apinizer-replicaset'
DB_NAME=<MONGO_DBNAME>  # Our default recommendation for <MONGO_DBNAME> variable is the name "apinizerdb"
echo -n ${DB_URL} | base64  # We will put the output of this in place of <ENCODED_URL> variable in the next step
echo -n ${DB_NAME} | base64  # We will put the output of this in place of <ENCODED_DB_NAME> variable in the next step
vi secret.yaml

Preparing secret yaml with MongoDB information:

mongo-secret.yaml — MongoDB connection secret
apiVersion: v1
kind: Secret
metadata:
  name: mongo-db-credentials
  namespace: apinizer
type: Opaque
data:
  dbUrl: <ENCODED_URL>
  dbName: <ENCODED_DB_NAME>
kubectl apply -f secret.yaml

API Manager Kubernetes deployment​

Modify the following example yaml file according to your systems and load it to your Kubernetes Cluster.

vi apinizer-manager-deployment.yaml
apimanager-deployment.yaml — API Manager Deployment + Service
apiVersion: apps/v1
kind: Deployment
metadata:
  name: apimanager
  namespace: apinizer
spec:
  replicas: 1
  selector:
    matchLabels:
      app: apimanager
      version: v1
  strategy:
    type: Recreate
  template:
    metadata:
      labels:
        app: apimanager
        version: v1
    spec:
      containers:
      - env:
        - name: JAVA_OPTS
          value: '-XX:MaxRAMPercentage=75.0 -Dlog4j.formatMsgNoLookups=true'
        - name: SPRING_PROFILES_ACTIVE
          value: prod
        - name: WORKER_DEPLOYMENT_TIMEOUT
          value: '120'
        - name: SPRING_SERVLET_MULTIPART_MAX_FILE_SIZE
          value: '70MB'
        - name: SPRING_SERVLET_MULTIPART_MAX_REQUEST_SIZE
          value: '70MB'
        - name: SPRING_DATA_MONGODB_URI
          valueFrom:
            secretKeyRef:
              key: dbUrl
              name: mongo-db-credentials
        - name: SPRING_DATA_MONGODB_DATABASE
          valueFrom:
            secretKeyRef:
              key: dbName
              name: mongo-db-credentials
        name: apimanager
        image: apinizercloud/apimanager:<APINIZER_VERSION>
        imagePullPolicy: IfNotPresent
        ports:
        - containerPort: 8080
          protocol: TCP
        resources:
          limits:
            cpu: 1
            memory: 3Gi
        startupProbe:
          failureThreshold: 12
          httpGet:
            path: /apinizer/management/health
            port: 8080
            scheme: HTTP
          initialDelaySeconds: 60
          periodSeconds: 10
          successThreshold: 1
          timeoutSeconds: 10
        readinessProbe:
          failureThreshold: 12
          httpGet:
            path: /apinizer/management/health
            port: 8080
            scheme: HTTP
          initialDelaySeconds: 60
          periodSeconds: 10
          successThreshold: 1
          timeoutSeconds: 10
        livenessProbe:
          failureThreshold: 12
          httpGet:
            path: /apinizer/management/health
            port: 8080
            scheme: HTTP
          initialDelaySeconds: 60
          periodSeconds: 10
          successThreshold: 1
          timeoutSeconds: 10
      dnsPolicy: ClusterFirst
      restartPolicy: Always
      hostAliases:
      - ip: "<IP_ADDRESS>"
        hostnames:
        - "<DNS_ADDRESS_1>"
        - "<DNS_ADDRESS_2>"
Info

If Environments Will Not Be Managed Through Apinizer, Manager's Deployment is Changed

To enable Deployment objects to bind to the required ServiceAccount, the serviceAccountName field is added to the spec field as follows:

spec:
  serviceAccountName: manager-serviceaccount
Info

Environment Variables

Apinizer API Manager runs on Spring Boot infrastructure. In Spring Boot, Environment variables are usually expressed using underscore (_) and uppercase. Therefore, for example, when setting spring.servlet.multipart.max-file-size and spring.servlet.multipart.max-request-size properties as environment variables, you may need to use underscore.

Example: You can define SPRING_SERVLET_MULTIPART_MAX_FILE_SIZE and SPRING_SERVLET_MULTIPART_MAX_REQUEST_SIZE as environment variables.

If you are using a proxy server like NGINX and want to increase the file upload limit, you need to add the following setting to the NGINX configuration file:

http {
  ...
  client_max_body_size 70M; # 70MB file limit
  ...
}
Info

Environment Variables

Deployment operations are performed synchronously to ensure data integrity. The WORKER_DEPLOYMENT_TIMEOUT parameter indicates how many seconds after the deploy operation performed through API Manager or Management API will timeout.

env:
  - name: WORKER_DEPLOYMENT_TIMEOUT
    value: '120'

Create Kubernetes Service for API Manager:

vi apinizer-manager-service.yaml
apimanager-service.yaml — API Manager Service
apiVersion: v1
kind: Service
metadata:
  name: apimanager
  namespace: apinizer
  labels:
    app: apimanager
spec:
  selector:
    app: apimanager
  type: NodePort
  ports:
    - name: http
      port: 8080
      nodePort: 32080
kubectl apply -f apinizer-manager-deployment.yaml
kubectl apply -f apinizer-manager-service.yaml
Info

When API Manager is deployed on Kubernetes, it creates a Kubernetes service named manager and of type NodePort. This service is necessary for accessing API Manager from outside kubernetes. However, you can delete this service and adapt it according to the structure you use for connection method in your organization, such as Ingress.

After this operation, to track the created pod and examine its log, run the first code below to get the pod name and use it in the second code.

kubectl get pods -n apinizer
kubectl logs <POD_NAME> -n apinizer
Warning

After Apinizer images are deployed to Kubernetes environment, you need to add the License Key provided to you by Apinizer to the database.

Entering API Manager license key​

The License Key provided to you by Apinizer can be updated in a .js file as follows and the license information in the database can be updated.

vi license.js
db.general_settings.updateOne(
  {"_class":"GeneralSettings"},
  { $set: { licenseKey: '<YOUR_LICENSE_KEY>'}}
)

The created license.js is run on the MongoDB server. A result showing Matched = 1 is expected.

mongosh mongodb://<MONGODB_IP>:<MONGO_PORT>/<MONGO_DBNAME> --authenticationDatabase "admin" -u "apinizer" -p '<MONGO_PASSWORD>' < license.js

If the installation process was successful, you can access Apinizer API Manager (Management Console) from the following address.

http://<K8S_ANY_WORKER_IP>:32080

Default Username: admin

Default User Password: Request help from Apinizer support team.

Warning

It is recommended that you change your password after your first login to Apinizer Management Console.

Change Password Page
Change Password page - Password change screen after first login
Note

To run Apinizer Manager with HTTPS/SSL — for TLS certificate preparation, JKS/PKCS12 conversion, K8s Secret creation, and SSL-enabled Deployment YAML examples, see the Starting API Manager with SSL tab at the bottom of the page. HTTPS is optional; TLS is recommended for production but HTTP works for PoC.

Next Step — Gateway Installation (Mandatory)​

Once API Manager installation and License Key definition are complete, you can log in to the Management Console. The next step is Gateway installation and environment definition — this step is mandatory; this module is the actual API Gateway of Apinizer and must be defined as at least one environment through the Manager.

The API Gateway is the most important component of Apinizer. It is the point where client requests are received and acts as a Policy Enforcement Point, processing incoming requests according to defined policies and routing them to the relevant Backend API/Service. Gateway installation is mandatory and at least one Gateway must be defined through the Manager.

A Gateway can be defined in two ways:

  • Managed Gateway — Apinizer manages the target Kubernetes cluster; when you create an environment via the Manager UI, Apinizer automatically handles namespace, RBAC, Deployment, Service, and secret copy operations.
  • Remote Gateway — The cluster where the Gateway runs is NOT under Apinizer's management. The operator manually deploys YAML manifests via kubectl and registers the connection addresses to Manager as a "Remote Gateway".

What is Managed Gateway?​

The model where Apinizer takes both the Management and Provisioning roles in the Kubernetes cluster. When you create a new Gateway environment from the Manager UI, Apinizer:

  • Creates the target namespace
  • Applies the required Role, ServiceAccount, and RoleBindings
  • Deploys the Gateway and (if used) Cache Deployments
  • Exposes HTTP/HTTPS Services and optional NodePorts
  • Copies the MongoDB secret to the target namespace
  • Lets you control pod count, JVM parameters, and resource limits via the UI

This model is recommended as the fastest path from PoC to production. No manual YAML preparation.

Prerequisites​

API Manager up and running

Logged into API Manager with the admin user. If Manager is not installed, continue from the API Manager Installation section above.

Apinizer Kubernetes management mode active

In System Settings → General Settings, the "Kubernetes management via Apinizer" option must be enabled. When disabled, Manager can only create Remote Gateways.

Cluster RBAC applied

For Manager to deploy to the target cluster, the apinizer-role.yaml and apinizer-manager-role.yaml (cluster-wide) from the API Manager Installation step must be applied.

Access to Docker images

The cluster must be able to pull apinizercloud/worker:<APINIZER_VERSION> and apinizercloud/cache:<APINIZER_VERSION> images (via internet or internal registry).

Creating a New Gateway​

In the Manager UI, navigate to Server Management → Gateway Runtimes and click the New button. The form has the following sections.

Managed Gateway environment creation form

1. Platform Selection​

The first step is choosing which platform the Gateway will run on.

OptionDescription
KubernetesGateway runs as a pod in a Kubernetes cluster. Can be managed by Apinizer (Managed) or by the operator (Remote).
Virtual Server / Docker (Standalone)Gateway runs as a bare-metal Linux process or Docker container. Always defined as Remote in this case.

For Managed Gateway, select Kubernetes.

2. Management Type​

OptionDescription
Managed by ApinizerThe Manager UI auto-creates all Kubernetes objects.
Remote GatewayThe operator manually deploys YAML; Manager only stores connection info.

This tab assumes Managed by Apinizer is selected.

3. Basic Information​

FieldDescriptionValidation
Environment TypeClassification such as DEV, TEST, PROD.Required
Communication Protocol TypeHTTP, HTTPS, gRPC, WebSocket. A single environment runs a single protocol; for mixed protocols, create separate environments.Required
Environment NameDisplay name of the Gateway environment. Also used as the Kubernetes namespace.a-z 0-9 and -; 3-64 chars; unique
Environment KeyUsed as the path prefix in API URLs (e.g., /test/...).a-zA-Z -; 3-24 chars; unique
Access URLPublic URL used to reach this Gateway from outside (Load Balancer / Ingress / NodePort host).Required
DescriptionOperator notes.Optional

4. Node Management (Node List)​

To restrict which Kubernetes nodes Gateway pods run on, specify a nodeSelector/nodeAffinity list. If left empty, the Kubernetes scheduler default behavior applies.

Tip

In high-traffic environments, running Gateway on dedicated nodes reduces noisy-neighbor effects.

5. Gateway Resource Configuration​

FieldDescriptionDefault
Replica CountNumber of Gateway pods running concurrently. ≥ 2 recommended for production.1
CPU LimitCPU limit per pod (cores).4
Memory LimitMemory limit per pod.4
Memory UnitMi / Gi.Gi

When the CPU value changes, Apinizer auto-computes JVM tuning parameters (tuneWorkerThreads, tuneIoThreads, etc.) and reflects them in the Additional Variables table.

6. Host Aliases​

IP ↔ hostname mappings to add to Gateway pods' /etc/hosts. Define these when the backend runs in a closed environment without DNS resolution, or when hardcoded IP/host mappings are required. This option is only available for Managed Gateway — for Remote Gateway, host aliases are configured directly in the Deployment YAML.

Publishing the Environment​

After filling out the form, click Create. Apinizer:

  1. Creates the target namespace (Environment Name = namespace name)
  2. Applies RBAC, ServiceAccount, Deployment, Service
  3. Copies the MongoDB secret to the namespace
  4. Waits for pods to become Ready
  5. Marks the environment as published

After publishing, you can see the environment on the Manager → Gateway Runtimes page and deploy API Proxies to it.

Info

For detailed Gateway Runtime management, JWT token validation key, metric monitor and diagnostics → see the Gateway Runtimes page.

Common Settings (For Both Methods)​

Independent of the Managed/Remote choice, the following form fields on the Gateway environment form in the Manager UI apply identically to both methods.

Management API Access Endpoints​

Note

This section is optional — not enforced on the form for either Managed or Remote Gateway. However, to ensure the Gateway runs correctly (proxy deployment, health checks, diagnostics), defining at least one endpoint is strongly recommended. Without it, the Manager cannot connect to Gateway pods and deployment/monitoring operations will fail.

These endpoints are the addresses that Apinizer Management Console connects to in order to push proxy deployments, run health checks, and perform diagnostics on Gateway and Cache pods. Each endpoint row in the form has three fields:

FieldDescription
NameA human-readable identifier for the endpoint (e.g., Production Cluster, DR Site, Region-EU).
Gateway Management API URLURL where the Manager reaches the Gateway pods' Management API (default port 8091).
Cache Management API URLURL where the Manager reaches the Cache pods' Management API (default port 8090).

Example values (cross-namespace Kubernetes service discovery):

Gateway Management API URL: http://worker-management-api-http-service.prod.svc.cluster.local:8091
Cache Management API URL:   http://cache-http-service.apinizer-cache.svc.cluster.local:8090

Multi-endpoint scenarios:

  • Multi-region / DR: Each region has its own endpoint row; the Manager selects the matching row using the environmentClusterName additional variable.
  • High Availability: Multiple endpoints sharing the same cluster can be registered; the Manager rotates between them.
  • Multi-cluster separation: Gateway pods and Cache pods may live in different clusters or different namespaces — each pair must be listed together.
Warning

Every endpoint row must contain both a Gateway Management API URL and a Cache Management API URL. Empty rows or rows with only one URL filled cause the publish step to fail. The Manager must also be able to reach these addresses over the network (firewalls, NetworkPolicy, cross-cluster routing must permit traffic).

Environment Publishing Access​

Restricts which Projects can deploy API Proxies, API Proxy Groups, Credentials, and Connections to this Gateway environment. Configured via the Projects multi-select field.

Selection stateBehavior
Empty (no projects selected)All projects in the system can deploy to this environment (default).
One or more projects selectedOnly the selected projects can deploy. Future newly-created projects are NOT added automatically; the operator must add them manually.
Warning

Removing a project from this list automatically undeploys all of that project's API Proxies, API Proxy Groups, Credentials, and Connections from this Gateway environment. This is a non-reversible side effect — the undeploy happens immediately on save.

Tip

When at least one project is selected, only API Proxies inside the selected projects can be deployed here. Use this for production environments where only audited projects should be allowed to ship.

API Traffic Log Connectors​

Defines the connectors where API traffic logs and extension logs of API Proxies running in this Gateway environment are written. Multiple connectors can be added; each has its own enabled/disabled toggle.

To fully benefit from Apinizer's Analytics and Monitoring capabilities, an Elasticsearch connector is recommended so that data management is also handled from Apinizer. If you will manage your API Traffic and API Analytics data with your own log systems, you can choose the connector type best suited to your environment.

Supported connector types:

Warning

If no Elasticsearch connector is assigned to this Gateway environment, the form displays a yellow warning: API Traffic logs are not sent to Elasticsearch, and Apinizer does not provide built-in log management or export. Log persistence and rotation become the operator's responsibility.

Prerequisite: The connector itself must first be defined under System Settings → Connection Management before it can be selected here.

→ For detailed assignment workflow: Adding Log Connectors

Protocol and Security Settings​

Define the network protocols (HTTP, HTTPS) and mandatory security mechanisms (mTLS, Keystore/Truststore) that the Gateway will use to accept incoming traffic.

HTTP / HTTPS / mTLS Activation​

ToggleDescription
HTTP Enabled (httpEnabled)Gateway's HTTP protocol is enabled. Selected by default.
HTTPS Enabled (httpsEnabled)Gateway's SSL/TLS protocol is enabled. When enabled, Keystore and Truststore files must be uploaded.
mTLS Enabled (mtlsEnabled)Mutual TLS — performs client certificate validation. Only selectable when HTTPS is enabled and the Communication Protocol is not gRPC.

Certificate Files (when HTTPS is enabled)​

FieldFormatDescription
Keystore.jks or .pfxGateway TLS server certificate (private key + cert chain).
Truststore.jks or .pfxTrusted client / CA certificates. Required when mTLS is enabled.
Keystore PasswordstringEncrypted, masked input.
Truststore PasswordstringEncrypted, masked input.

Kubernetes Service Configuration​

Controls which Kubernetes Service objects Apinizer creates for the Gateway. The UI calls this section Kubernetes Service Deployment (defineServiceInKubernetes).

Info

This section is only meaningful for Managed Gateway — for Remote Gateway, the operator authors the Service YAMLs manually (apinizer-worker-service.yaml) and these toggles have no effect.

Optioni18n keyDescription
Create HTTP service for Gateway Management APIcreateHttpServiceForGatewayManagementAPIExposes the Gateway pod's HTTP Management API port (8091) to internal cluster access via a dedicated ClusterIP service. Required for Manager → Gateway configuration push.
Create HTTPS service for Gateway Management APIcreateHttpsServiceForGatewayManagementAPIExposes the Gateway pod's HTTPS Management API port (8443) to internal cluster access via a dedicated ClusterIP service. Requires Keystore/Truststore.
Create NodePort for External HTTP Access to Gateway ServicecreateServiceForGatewayServiceAccessCreates a NodePort for external HTTP traffic to the Gateway service.
Create NodePort for External HTTPS Access to Gateway ServicecreateSecureServiceForGatewayServiceAccessCreates a NodePort for external HTTPS traffic to the Gateway service.

NodePort range: 30080-32767 (Kubernetes default range).

Note

For Gateway additional variables (JVM tuning, gRPC, WebSocket, CORS, security, etc.) and all Manager UI configurations (General Settings, Gateway Environments, Log Connectors, Backup, etc.), see Gateway Settings.

Optional Modules​

The following modules are optional and can be installed in the desired order. Recommended order: Cache → Integration → API Portal. For running API Manager with HTTPS/SSL, see the SSL tab at the bottom.

Apinizer Cache Installation​

API Cache Server manages the data shared by its components by storing it in distributed cache, and also provides performance improvement. It runs as a Hazelcast-based cluster; Workers connect to Cache for shared data such as quota counters, OIDC token cache, circuit breaker states, and so on.

Cache installation is optional — Apinizer can run without a dedicated Cache Server for low-traffic / single-Gateway scenarios. For production deployments with multiple Workers, Quota policies, OIDC, or circuit breakers, installing a Cache Server is strongly recommended.

A Cache can be defined in two ways:

  • Managed Cache (Apinizer-managed) — Apinizer provisions the Cache Server on the target Kubernetes cluster with a single click from the Manager UI; namespace, Deployment, Services, and MongoDB secret copy are handled automatically.
  • Remote Cache Server (Manual Deploy) — The operator deploys the Cache Server manually (via kubectl YAML or standalone), then registers its Management API URL to the Manager.
Warning

If the Cache Server is installed standalone (Docker, Virtual Server, or bare-metal Linux), you MUST select Remote Cache Server and register it with the Manager. Standalone Caches cannot be deployed by the Manager; only connection details (Cache Management API URL) are stored.

What is Managed Cache?​

The model where Apinizer automatically provisions the Cache Server on a Kubernetes cluster. When you create a new Cache Server via the Manager UI, Apinizer:

  • Creates the target namespace (or uses an existing one)
  • Applies the Cache Server Deployment (Hazelcast-based cluster)
  • Exposes HTTP (8090) and Hazelcast (5701) Services
  • Copies the MongoDB secret to the target namespace
  • Lets you control pod count, JVM parameters, and resource limits via the UI

Apinizer Workers (Gateway pods) connect to this Cache for shared data such as quota counters, OIDC token cache, circuit breaker states, etc.

Prerequisites​

API Manager up and running

Logged into Manager with the admin user.

Apinizer Kubernetes management mode active

"Kubernetes management via Apinizer" enabled under System Settings → General Settings.

Cluster RBAC applied

apinizer-role.yaml and apinizer-manager-role.yaml (cluster-wide) from the API Manager Installation step must be applied.

Docker image access

Cluster must be able to pull apinizercloud/cache:<APINIZER_VERSION>.

Creating a New Cache Server​

In the Manager UI, navigate to Server Management → Distributed Cache and click the New (+) button.

Managed Cache Server creation form

1. Type — Deployment Model​

Optioni18n KeyDescription
Managed by ApinizermanagedByApinizerApinizer creates the namespace, deployment, service, and all required K8s resources automatically.
Remote Cache ServerremoteCacheConnect to a manually-deployed Cache. (This sub-tab assumes Managed.)

2. Name​

Display name of the Cache Server. Validation: must be unique.

3. Namespace Configuration​

OptionDescription
Create New Namespace (createNewNamespace)Apinizer creates a new namespace with the given name. Validation: RFC 1123 label (3-63 chars, lowercase alphanumeric + -, must start and end with alphanumeric). Examples: my-cache-ns, prod-cache, 123-abc.
Use Existing Namespace (useExistingNamespace)Select an existing namespace from the cluster.

4. Cache Management API Access URLs​

Endpoint(s) the Manager and Gateway use to communicate with this Cache Server. Each table row:

FieldDescriptionExample
NameIdentifier for the endpointProduction, DR Site
Cache Server Access URLCache Server health-check and API endpointhttp://cache-http-service.prod.svc.cluster.local:8090
StatusAuto connectivity check — Reachable / Not Reachable / Checking...
Tip

Multiple URLs can be added for multi-cluster / DR scenarios. The form has a Test API Connection button for instant validation.

5. Cache Resource Configuration​

Fieldi18n KeyDefaultDescription
Replica CountreplicaCount1Number of Cache pods. ≥ 2 recommended for production (Hazelcast cluster).
CPUcpu1CPU limit per pod (cores).
Memorymemory1Memory limit per pod.
Memory UnitmemoryUnitGiMi / Gi.

6. Additional Variables​

Additional environment variables passed to the Cache pod. Table columns: Key and Value. Important defaults:

Tomcat Settings (for Cache HTTP Management API):

  • SERVER_TOMCAT_MAX_THREADS (1024)
  • SERVER_TOMCAT_MIN_SPARE_THREADS (512)
  • SERVER_TOMCAT_ACCEPT_COUNT (512)
  • SERVER_TOMCAT_MAX_CONNECTIONS (1024)
  • SERVER_TOMCAT_CONNECTION_TIMEOUT (20000 ms)
  • SERVER_TOMCAT_KEEPALIVE_TIMEOUT (60000 ms)
  • SERVER_TOMCAT_MAX_KEEPALIVE_REQUESTS (10000)
  • SERVER_TOMCAT_PROCESSOR_CACHE (512)

Hazelcast Cluster Settings:

  • HAZELCAST_IO_WRITE_THROUGH (false)
  • HAZELCAST_MAP_LOAD_CHUNK_SIZE (10000)
  • HAZELCAST_MAP_LOAD_BATCH_SIZE (10000)
  • HAZELCAST_CLIENT_SMART (true)
  • HAZELCAST_MAPCONFIG_BACKUPCOUNT (1)
  • HAZELCAST_MAPCONFIG_READBACKUPDATA (false)
  • HAZELCAST_MAPCONFIG_ASYNCBACKUPCOUNT (0)
  • HAZELCAST_OPERATION_RESPONSEQUEUE_IDLESTRATEGY (block)
  • HAZELCAST_MAP_WRITE_DELAY_SECONDS (5)
  • HAZELCAST_MAP_WRITE_BATCH_SIZE (100)
  • HAZELCAST_MAP_WRITE_COALESCING (true)
  • HAZELCAST_MAP_WRITE_BEHIND_QUEUE_CAPACITY (100000)

Other:

  • CACHE_QUOTA_TIMEZONE (+03:00) — for Quota policy calculation
  • JAVA_OPTS — JVM heap parameters
  • CACHE_SERVICE_NAME — Hazelcast service discovery (default: cache-hz-service)
Warning

Setting HAZELCAST_OPERATION_RESPONSEQUEUE_IDLESTRATEGY to "backoff" causes the Cache pod to constantly use 90-100% of its CPU limit. Provides 5-10% performance gain but is CPU-intensive. Use carefully in production.

7. Define the Service in Kubernetes​

Enable via the createK8sService checkbox. Strongly recommended — required for Manager and Gateway pods to reach the Cache Server.

Fieldi18n KeyDescription
Service NameserviceNameK8s Service object name (e.g., cache-http-service)
Service TypeserviceTypeCluster IP (default, in-cluster access) or Node Port (external access)
NodePortnodePortRequired only for NodePort type (30080-32767 range)
Info

ClusterIP is best for internal communication between Cache and Gateway/Manager. NodePort is usually not needed.

8. Host Alias Configuration​

IP ↔ hostname mappings added to the Cache pods' /etc/hosts. Useful when you need to resolve hostnames not in DNS. Table columns: IP Address and Host Names.

9. Node Name List Configuration​

Restrict which Kubernetes nodes the Cache pods are scheduled on via nodeSelector / nodeAffinity. If empty, the Kubernetes scheduler's default behavior applies.

Publishing​

After filling out the form, click Publish. Apinizer:

  1. Uses or creates the target namespace
  2. Copies the MongoDB secret
  3. Applies the Cache Deployment
  4. Creates the HTTP + Hazelcast Services
  5. Waits for pods to become Ready
  6. Marks the Cache Server as Published

After publishing, Gateway environments automatically start using this Cache.

Info

For detailed Cache management (monitoring, diagnostics, restart) → see the Distributed Cache page.

En son tarihinde güncellendi