Installation requirements

Hardware requirements

You must meet the following minimum hardware requirements for a highly available infrastructure in a production grade environment.

The following video gives you high-level sizing guidance for your installation:

For all installation scenarios described in Installation topologies, the following tables list the minimum hardware requirements for the installation components.

In these tables the hard disk requirements are in addition to the hard disk space required by the operating system. Depending on your applications and network traffic, your installation might require more or fewer resources than listed below.

Installation Component RAM CPU Minimum hard disk
Cassandra 16GB 8-core 250GB local storage with SSD supporting 2000 IOPS
Message Processor/Router on same machine 16GB 8-core 100GB
Message Processor (standalone) 16GB 8-core 100GB
Router (standalone) 16GB 8-core 100GB
Analytics - Postgres/Qpid on same server 16GB* 8‑core* 500GB - 1TB** network storage***, preferably with SSD backend, supporting 1000 IOPS or higher*
Analytics - Postgres master or standby (standalone) 16GB* 8-core* 500GB - 1TB** network storage***, preferably with SSD backend, supporting 1000 IOPS or higher*
Analytics - Qpid standalone 8GB 4-core 30GB - 50GB local storage with SSD

The default Qpid queue size is 1 GB, which can be increased to 2 GB. If you need more capacity, add additional Qpid nodes.

OpenLDAP/UI/Management Server 8GB 4-core 60GB
UI/Management Server 4GB 2-core 60GB
OpenLDAP (standalone) 4GB 2-core 60GB

* Adjust Postgres system requirements based on throughput:

  • Less than 250 TPS: 8GB, 4-core can be considered with managed network storage*** supporting 1000 IOPS or higher
  • Greater than 250 TPS: 16GB, 8-core, managed network storage*** supporting 1000 IOPS or higher
  • Greater than 1000 TPS: 16GB, 8-core, managed network storage*** supporting 2000 IOPS or higher
  • Greater than 2000 TPS: 32GB, 16-core, managed network storage*** supporting 2000 IOPS or higher
  • Greater than 4000 TPS: 64GB, 32-core, managed network storage*** supporting 4000 IOPS or higher

** The Postgres hard disk value is based on the out of the box analytics captured by Edge. If you add custom values to the analytics data, then these values should be increased accordingly. Use the following formula to estimate the required storage:

bytes of storage needed =

  (# bytes of analytics data/request) *

  (requests/second) *

  (seconds/hour) *

  (hours of peak usage/day) *

  (days/month) *

  (months of data retention)

For example:

(2K bytes) * (100 req/sec) * (3600 secs/hr) * (18 peak hours/day) * (30 days/month) * (3 months retention)

= 1,194,393,600,000 bytes or 1194.4 GB of storage needed

*** Network Storage is recommended for Postgresql database because:

  • It gives the ability to dynamically scale up the storage size if and when required.
  • Network IOPS can be adjusted on the fly in most of today's environment/Storage/Network subsystems.
  • Storage level snapshots can be enabled as part of backup and recovery solutions.

In addition, the following lists the hardware requirements if you want to install the Monetization Services (not supported on All-in-One installation):

Component with Monetization RAM CPU Hard disk
Management Server (with Monetization Services) 8GB 4‑core 60GB
Analytics - Postgres/Qpid on same server 16GB 8-core 500GB - 1TB network storage, preferably with SSD backend, supporting 1000 IOPS or higher, or use the rule from the table above.
Analytics - Postgres master or standby standalone 16GB 8-core 500GB - 1TB network storage, preferably with SSD backend, supporting 1000 IOPS or higher, or use the rule from the table above.
Analytics - Qpid standalone 16GB 8-core 40GB - 500GB local storage with SSD or fast HDD

For installations greater than 250 TPS, HDD with local storage supporting 1000 IOPS is recommended.

Operating system and third-party software requirements

These installation instructions and the supplied installation files have been tested on the operating systems and third-party software listed in Supported software and supported versions.

Java

You need a supported version of Java 1.8 installed on each machine prior to the installation. Supported JDKs are listed in Supported software and supported versions.

Ensure that the JAVA_HOME environment variable points to the root of the JDK for the user performing the installation.

SELinux

Depending on your settings for SELinux, Edge can encounter issues with installing and starting Edge components. If necessary, you can disable SELinux or set it to permissive mode during installation, and then re-enable it after installation. See Install the Edge apigee-setup utility for more.

Creating the 'apigee' user

The installation procedure creates a Unix system user named 'apigee'. Edge directories and files are owned by 'apigee', as are Edge processes. That means Edge components run as the 'apigee' user. If necessary, you can run components as a different user.

Installation directory

By default, the installer writes all files to the /opt/apigee directory. You cannot change this directory location. While you cannot change this directory, you can create a symlink to map /opt/apigee to another location, as described in Creating a symlink from /opt/apigee.

In the instructions in this guide, the installation directory is noted as /opt/apigee.

Before you create the symlink, you must first create a user and group named "apigee". This is the same group and user created by the Edge installer.

To create the symlink, perform these steps before downloading the bootstrap_4.51.00.sh file. You must perform all of these steps as root:

  1. Create the "apigee" user and group:
    groupadd -r apigee > useradd -r -g apigee -d /opt/apigee -s /sbin/nologin -c "Apigee platform user" apigee
  2. Create a symlink from /opt/apigee to your desired install root:
    ln -Ts /srv/myInstallDir /opt/apigee

    Where /srv/myInstallDir is the desired location of the Edge files.

  3. Change ownership of the install root and symlink to the "apigee" user:
    chown -h apigee:apigee /srv/myInstallDir /opt/apigee

Network setting

Apigee recommendeds that you check the network setting prior to the installation. The installer expects that all machines have fixed IP addresses. Use the following commands to validate the setting:

  • hostname returns the name of the machine
  • hostname -i returns the IP address for the hostname that can be addressed from other machines.

Depending on your operating system type and version, you may need to edit /etc/hosts and /etc/sysconfig/network if the hostname is not set correctly. See the documentation for your specific operating system for more information.

If a server has multiple interface cards, the "hostname -i" command returns a space-separated list of IP addresses. By default, the Edge installer uses the first IP address returned, which might not be correct in all situations. As an alternative, you can set the following property in the installation configuration file:

ENABLE_DYNAMIC_HOSTIP=y

With that property set to "y", the installer prompts you to select the IP address to use as part of the install. The default value is "n". See Edge Configuration File Reference for more.

TCP Wrappers

TCP Wrappers can block communication of some ports and can affect OpenLDAP, Postgres, and Cassandra installation. On those nodes, check /etc/hosts.allow and /etc/hosts.deny to ensure that there are no port restrictions on the required OpenLDAP, Postgres, and Cassandra ports.

iptables

Validate that there are no iptables policies preventing connectivity between nodes on the required Edge ports. If necessary, you can stop iptables during installation using the command:

sudo/etc/init.d/iptables stop

On CentOS 7.x:

systemctl stop firewalld

Directory access

The following table lists directories on Edge nodes that have special requirements from Edge processes:

Service Directory Description
Router /etc/rc.d/init.d/functions

The Edge Router uses the NGINX router and requires read access to /etc/rc.d/init.d/functions.

If your security process requires you to set permissions on /etc/rc.d/init.d/functions, do not set them to 700 or else the Router will fail to start.

You can set permissions to 744 to allow read access to /etc/rc.d/init.d/functions.

Zookeeper /dev/random The Zookeeper client library requires read access to the random number generator /dev/random. If /dev/random is blocked on read, then the Zookeeper service might fail to start up.

Cassandra

All Cassandra nodes must be connected to a ring. Cassandra stores data replicas on multiple nodes to ensure reliability and fault tolerance. The replication strategy for each Edge keyspace determines the Cassandra nodes where replicas are placed. For more, see About Cassandra replication factor and consistency level.

Cassandra automatically adjusts its Java heap size based on the available memory. For more, see Tuning Java resources in the event of a performance degradation or high memory consumption.

After installing the Edge for Private Cloud, you can check that Cassandra is configured correctly by examining the /opt/apigee/apigee-cassandra/conf/cassandra.yaml file. For example, ensure that the Edge for Private Cloud installation script set the following properties:

  • cluster_name
  • initial_token
  • partitioner
  • seeds
  • listen_address
  • rpc_address
  • snitch

PostgreSQL database

After you install Edge, you can adjust the following PostgreSQL database settings based on the amount of RAM available on your system:

conf_postgresql_shared_buffers = 35% of RAM      # min 128kB
conf_postgresql_effective_cache_size = 45% of RAM
conf_postgresql_work_mem = 512MB       # min 64kB

To set these values:

  1. Edit the postgresql.properties file:
    vi /opt/apigee/customer/application/postgresql.properties

    If the file does not exist, create it.

  2. Set the properties listed above.
  3. Save your edits.
  4. Restart the PostgreSQL database:
    /opt/apigee/apigee-service/bin/apigee-service apigee-postgresql restart

System limits

Ensure that you have set the following system limits on Cassandra and Message Processor nodes:

  • On Cassandra nodes, set soft and hard memlock, nofile, and address space (as) limits for installation user (default is "apigee") in /etc/security/limits.d/90-apigee-edge-limits.conf as shown below:
    apigee soft memlock unlimited
    apigee hard memlock unlimited
    apigee soft nofile 32768
    apigee hard nofile 65536
    apigee soft as unlimited
    apigee hard as unlimited
    apigee soft nproc 32768
    apigee hard nproc 65536

    For more information, see Recommended production settings in the Apache Cassandra documentation.

  • On Message Processor nodes, set the maximum number of open file descriptors to 64K in /etc/security/limits.d/90-apigee-edge-limits.conf as shown below:
    apigee soft nofile 32768
    apigee hard nofile 65536

    If necessary, you can raise that limit. For example, if you have a large number of temporary files open at any one time.

  • If you ever see the following error in a Router or Message Processor system.log, your file descriptor limits may be set too low:

    "java.io.IOException: Too many open files"

    You can check your user limits by running:

    # su - apigee
    $ ulimit -n
    100000
    

    If you are still reaching the open files limits after setting the file descriptor limits to 100000, open a ticket with Apigee Edge Support for further troubleshooting.

Network Security Services (NSS)

Network Security Services (NSS) is a set of libraries that supports development of security-enabled client and server applications. You should ensure that you have installed NSS v3.19, or later.

To check your current version:

yum info nss

To update NSS:

yum update nss

See this article from RedHat for more information.

Disable DNS lookup on IPv6 when using NSCD (Name Service Cache Daemon)

If you have installed and enabled NSCD (Name Service Cache Daemon), the Message Processors make two DNS lookups: one for IPv4 and one for IPv6. You should disable DNS lookup on IPv6 when using NSCD.

To disable the DNS lookup on IPv6:

  1. On every Message Processor node, edit /etc/nscd.conf
  2. Set the following property:
    enable-cache hosts no

Disable IPv6 on Google Cloud Platform for RedHat/CentOS 7

If you are installing Edge on RedHat 7 or CentOS 7 on Google Cloud Platform, then you must disable IPv6 on all Qpid nodes.

See the RedHat or CentOS documentation of your specific OS version for instructions on disabling IPv6. For example, you can:

  1. Open /etc/hosts in an editor.
  2. Insert a "#" character in column one of the following line to comment it out:
    #::1 localhost localhost.localdomain localhost6 localhost6.localdomain6
  3. Save the file.

AWS AMI

If you are installing Edge on an AWS Amazon Machine Image (AMI) for Red Hat Enterprise Linux 7.x, you must first run the following command:

yum-config-manager --enable rhui-REGION-rhel-server-extras rhui-REGION-rhel-server-optional

Tools

The installer uses the following UNIX tools in the standard version as provided by EL5 or EL6.

awk

expr

libxslt

rpm

unzip

basename

grep

lua-socket

rpm2cpio

useradd

bash

hostname

ls

sed

wc

bc

id

net-tools

sudo

wget

curl

libaio

perl (from procps)

tar

xerces-c

cyrus-sasl libdb4 pgrep (from procps) tr yum

date

libdb-cxx

ps

uuid

chkconfig

dirname libibverbs pwd uname  
echo librdmacm python    

ntpdate

Apigee recommends that your servers' times are synchronized. If not already configured, the ntpdate utility could serve this purpose, which verifies whether servers are time synchronized. You can use yum install ntp to install the utility. This is particularly useful for replicating OpenLDAP setups. Note that you set up server time zone in UTC.

openldap 2.4

The on-premises installation requires OpenLDAP 2.4. If your server has an Internet connection, then the Edge install script downloads and installs OpenLDAP. If your server does not have an Internet connection, you must ensure that OpenLDAP is already installed before running the Edge install script. On RHEL/CentOS, you can run yum install openldap-clients openldap-servers to install the OpenLDAP.

For 13-host installations, and 12-host installations with two data centers, OpenLDAP replication is required because there are multiple nodes hosting OpenLDAP.

Firewalls and virtual hosts

The term virtual commonly gets overloaded in the IT arena, and so it is with an Apigee Edge for Private Cloud deployment and virtual hosts. To clarify, there are two primary uses of the term virtual:

  • Virtual machines (VM): Not required, but some deployment use VM technology to create isolated servers for their Apigee components. VM hosts, like physical hosts, can have network interfaces and firewalls.
  • Virtual hosts: Web endpoints, analogous to an Apache virtual host.

A router in a VM can expose multiple virtual hosts (as long as they differ from one another in their host alias or in their interface port).

Just as a naming example, a single physical server A might be running two VMs, named "VM1" and "VM2". Let's assume "VM1" exposes a virtual Ethernet interface, which gets named "eth0" inside the VM, and which is assigned IP address 111.111.111.111 by the virtualization machinery or a network DHCP server; and then assume VM2 exposes a virtual Ethernet interface also named "eth0" and it gets assigned an IP address 111.111.111.222.

We might have an Apigee router running in each of the two VMs. The routers expose virtual host endpoints as in this hypothetical example:

The Apigee router in VM1 exposes three virtual hosts on its eth0 interface (which has some specific IP address), api.mycompany.com:80, api.mycompany.com:443, and test.mycompany.com:80.

The router in VM2 exposes api.mycompany.com:80 (same name and port as exposed by VM1).

The physical host's operating system might have a network firewall; if so, that firewall must be configured to pass TCP traffic bound for the ports being exposed on the virtualized interfaces (111.111.111.111:{80, 443} and 111.111.111.222:80). In addition, each VM's operating system may provide its own firewall on its eth0 interface and these too must allow ports 80 and 443 traffic to connect.

The basepath is the third component involved in routing API calls to different API proxies that you may have deployed. API proxy bundles can share an endpoint if they have different basepaths. For example, one basepath can be defined as http://api.mycompany.com:80/ and another defined as http://api.mycompany.com:80/salesdemo.

In this case, you need a load balancer or traffic director of some kind splitting the http://api.mycompany.com:80/ traffic between the two IP addresses (111.111.111.111 on VM1 and 111.111.111.222 on VM2). This function is specific to your particular installation, and is configured by your local networking group.

The basepath is set when you deploy an API. From the above example, you can deploy two APIs, mycompany and testmycompany, for the organization mycompany-org with the virtual host that has the host alias of api.mycompany.com and the port set to 80. If you do not declare a basepath in the deployment, then the router does not know which API to send incoming requests to.

However, if you deploy the API testmycompany with the base URL of /salesdemo, then users access that API using http://api.mycompany.com:80/salesdemo. If you deploy your API mycompany with the base URL of / then your users access the API by the URL http://api.mycompany.com:80/.

Licensing

Each installation of Edge requires a unique license file that you obtain from Apigee. You will need to provide the path to the license file when installing the management server, for example /tmp/license.txt.

The installer copies the license file to /opt/apigee/customer/conf/license.txt.

If license file is valid, the management server validates the expiry and allowed Message Processor (MP) count. If any of the license settings is expired, you can find the logs in the following location: /opt/apigee/var/log/edge-management-server/logs. In this case you can contact Apigee Edge Support for migration details.

If you do not yet have a license, contact Apigee Sales.