Installation Requirements

Edge for Private Cloud v. 4.17.01

Hardware Requirements

You must meet the following minimum hardware requirements for a highly available infrastructure in a production grade environment. 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.

In addition, the following lists the hardware requirements if you wish to install the Monetization Services:

The following lists the hardware requirements if you wish to install API BaaS:

Note:

• If the root file system is not large enough for the installation, it is recommended to place the data onto a larger disk.
• If an older version of Apigee Edge for Private Cloud was installed on the machine, ensure that you delete the folder /tmp/java before a new installation.
• The system wide temporary folder /tmp needs execute permissions in order to start Cassandra.
• If user “apigee” was created prior to the installation, ensure that “/home/apigee” exists as home directory and is owned by “apigee:apigee”.

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 here: https://apigee.com/docs/api-services/reference/supported-software.

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. See "Binding the Router to a protected port" in Install Edge components on a node for an example.

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 below.

In the instructions in this guide, the installation directory is noted as /<inst_root>/apigee, where /<inst_root> is /opt by default.

Creating a symlink from /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.17.01.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

Java

You need a supported version of Java1.8 installed on each machine prior to the installation. Supported JDKs are listed here:

https://apigee.com/docs/api-services/reference/supported-software

Ensure that JAVA_HOME 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-enabling it after installation. See Install the Edge apigee-setup utility for more.

Network Setting

It is recommended to 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 might have 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.

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

Ensure Edge Router can access /etc/rc.d/init.d/functions

The Edge Router and BaaS Portal nodes use the Nginx router and require 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. Permissions can be set to 744 to allow read access to /etc/rc.d/init.d/functions.

Cassandra

All Cassandra nodes have to 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 /<inst_root>/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

Warning: Do not edit this file.

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 postgresql.properties:
   > vi /<inst_root>/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:
   > /<inst_root>/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
  
• 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.

jsvc

"jsvc" is a prerequisite for using API BaaS. Version 1.0.15-dev is installed when you install the API BaaS.

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 makes 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 for your specific OS version for instructions on disabling IPv6.

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.

Note:

• The executable for the tool ‘useradd’ is located in /usr/sbin and for chkconfig in /sbin.
• With sudo access you can gain access over the environment of the calling user, for example, usually you would call “sudo <command>” or “sudo PATH=$PATH:/usr/sbin:/sbin <command>”.
• Ensure that you have “patch” tool installed prior to a service pack (patch) installation.

ntpdate – It is recommended to have the servers time synchronized. If not already configured, ‘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, you require OpenLDAP replication 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/.

Edge port requirements

The need to manage the firewall goes beyond just the virtual hosts; both VM and physical host firewalls must allow traffic for the ports required by the components to communicate with each other.

The following image shows the ports requirements for each Edge component:

Notes on this diagram:

• *Port 8082 on the Message Processor only has to be open for access by the Router when you configure TLS/SSL between the Router and Message Processor. If you do not configure TLS/SSL between the Router and Message Processor, the default configuration, port 8082 still must be open on the Message Processor to manage the component, but the Router does not require access to it.
• The ports prefixed by "M" are ports used to manage the component and must be open on the component for access by the Management Server.
• The following components require access to port 8080 on the Management Server: Router, Message Processor, UI, Postgres, and Qpid.
• A Message Processor must open port 4528 as its management port. If you have multiple Message Processors, they must all be able to access each other over port 4528 (indicated by the loop arrow in the diagram above for port 4528 on the Message Processor). If you have multiple Data Centers, the port must be accessible from all Message Processors in all Data Centers.
• While it is not required, you can open port 4527 on the Router for access by any Message Processor. Otherwise, you might see error messages in the Message Processor log files.
• A Router must open port 4527 as its management port. If you have multiple Routers, they must all be able to access each other over port 4527 (indicated by the loop arrow in the diagram above for port 4527 on the Router).
• The Edge UI requires access to the Router, on the ports exposed by API proxies, to support the Send button in the trace tool.
• The Management Server requires access to the JMX port on the Cassandra nodes.
• Access to JMX ports can be configured to require a username/password. See How to Monitor for more information.
• You can optionally configure TLS/SSL access for certain connections, which can use different ports. See TLS/SSL for more.
• If configuring two Postgres nodes to use master-standby replication, you must open port 22 on each node for ssh access. You can optionally open ports on individual nodes to allow ssh access.
• You can configure the Management Server and Edge UI to send emails through an external SMTP server. If you do, you must ensure that the Management Server and UI can access the necessary port on the SMTP server. For non-TLS SMTP, the port number is typically 25. For TLS-enabled SMTP, it is often 465, but check with your SMTP provider.

The table below shows the ports need to be opened in firewalls, by Edge component:

> curl -v http://<routerIP>:15999/v1/servers/self/reachable

The next table shows the same ports, listed numerically, with the source and destination components:

A message processor keeps a dedicated connection pool open to Cassandra, which is configured to never timeout. When a firewall is between a message processor and Cassandra server, the firewall can time out the connection. However, the message processor is not designed to reestablish connections to Cassandra.

To prevent this situation, Apigee recommends that the Cassandra server, message processor, and routers be in the same subnet so that a firewall is not involved in the deployment of these components.

If a firewall is between the router and message processors, and has an idle tcp timeout set, our recommendations is to:

1. Set net.ipv4.tcp_keepalive_time = 1800 in sysctl settings on Linux OS, where 1800 should be lower than the firewall idle tcp timeout. This setting should keep the connection in an established state so that the firewall does not disconnect the connection.
2. On all Message Processors, edit /<inst_root>/apigee/customer/application/message-processor.properties to add the following property. If the file does not exist, create it.
   conf_system_cassandra.maxconnecttimeinmillis=-1
3. Restart the Message Processor:
   > /opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart
4. On all Routers, edit /<inst_root>/apigee/customer/application/router.properties to add the following property. If the file does not exist, create it.
   conf_system_cassandra.maxconnecttimeinmillis=-1
5. Restart the Router:
   > /opt/apigee/apigee-service/bin/apigee-service edge-router restart

If you install the 12 host clustered configuration with two Data Centers, ensure that the nodes in the two Data Centers can communicate over the ports shown below:

API BaaS port requirements

If you opt to install the API BaaS, you add the API BaaS Stack and API BaaS Portal components. These components use the ports shown in the figure below:

Notes on this diagram:

• The API BaaS Portal never makes requests directly to a BaaS Stack node. When a developer logs into the Portal, the Portal app is downloaded to the browser. The Portal app running in the browser then makes requests to the BaaS Stack nodes.
• A production installation of API BaaS uses a load balancer between the API BaaS Portal node and API BaaS Stack nodes. When configuring the Portal, and when making BaaS API calls, you specify the IP address or DNS name of the load balancer, not of the Stack nodes.
• All Stack nodes must open port 2551 for access from all other Stack nodes (indicated by the loop arrow in the diagram above for port 2551 on the Stack nodes). If you have multiple Data Centers, the port must be accessible from all Stack nodes in all Data Centers.
• You must configure all Baas Stack nodes to send emails through an external SMTP server. For non-TLS SMTP, the port number is typically 25. For TLS-enabled SMTP, it is often 465, but check with your SMTP provider.
• The Cassandra nodes can be dedicated to API BaaS, or can be shared with Edge.

The table below shows the default ports that need to be opened in firewalls, by component:

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 /<inst_root>/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: /<inst_root>/apigee/var/log/edge-management-server/logs. In this case you can contact Apigee Support for migration details.

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