Apigee Edge Private Cloud Operations Guide V4
User Manual:
Open the PDF directly: View PDF 
.
Page Count: 163
| Download | |
| Open PDF In Browser | View PDF |
TM
Apigee
Apigee Edge for Private Cloud
v4.16.05
May 31, 2015
Operations Guide
Confidential and Proprietary information of Apigee, Inc. Not to be disclosed except under NonDisclosure Agreement.
Apigee Edge Operations Guide
Page 2
Copyright (c) 2016 Apigee Corporation. All rights reserved.
(TM)
Apigee
and the Apigee logo are trademarks or registered trademarks of Apigee Corp. or its subsidiaries. All
other trademarks are the property of their respective owners. All specifications are subject to change without
notice.
THE CONTENTS OF THIS PUBLICATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND,
EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR NONINFRINGEMENT OF
INTELLECTUAL PROPERTY.
APIGEE CORPORATION SHALL NOT UNDER ANY CIRCUMSTANCES BE LIABLE TO ANY PERSON FOR
ANY SPECIAL, INCIDENTAL, INDIRECT OR CONSEQUENTIAL DAMAGES, INCLUDING WITHOUT
LIMITATION, DAMAGES RESULTING FROM THE USE OF OR RELIANCE ON THE INFORMATION IN THIS
PUBLICATION, LOSS OF PROFITS, REVENUE OR DATA, EVEN IF APIGEE CORPORATION HAS BEEN
PREVIOUSLY ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
Contact Information
INDIA
USA
UK
No.17/2, 2B Cross, 7th Main, 2 & 3
Floor, Off 80 Feet Road, 3rd Block
Koramangala, Bangalore 560034
10 Almaden Boulevard,
16th Floor, San Jose
CA 95113
Call +91 80 67696800
www.apigee.com
Call +1 (408) 3437300
www.apigee.com
3 Sheldon Square
London W2 6HY
Call: +44 (0) 750 123 2390
www.apigee.com/
Confidential and proprietary information of Apigee, Inc. Not to be disclosed except under nondisclosure agreement.
Apigee Edge Operations Guide
Contents
Overview
Access the Apigee Community for your questions
Apigee Edge Architecture Overview
Component Descriptions
Components required for API processing
Components not required for API processing but for system services
Components not required for API processing
About Planets, Regions, Pods, Organizations, Environments and Virtual Hosts
About Planets
About Regions
About Pods
About Organizations
About Environments
About Virtual Hosts
Creating your first organization, environment, and virtual host
Apigee Installation File System
Installation directory
File System Structure
Important Data to Remember From the Installation Process
How to Configure Edge
How to use .properties files
Location of .properties files
Determining the current value of a token
Setting tokens in .properties files
Locating a token
Setting a token that is currently commented out
Using the apigeeadminapi.sh utility
Confidential and proprietary information of Apigee, Inc. Not to be disclosed except under nondisclosure agreement.
Page 3
Apigee Edge Operations Guide
Installing apigeeadminapi.sh
apigeeadminapi.sh syntax
Setting parameters using commandline switches and environment variables
Passing a file to the apigeeadminapi.sh utility
Displaying debug and API information
Scaling Edge for Private Cloud
Adding a Router or Message Processor node
Add a Router
Add a Message Processor
Add both a Router and a Message Processor
Adding Cassandra nodes
Existing Edge configuration
Modifying the config file to add the three new Cassandra nodes
Configure Edge
Reconfigure the existing Cassandra nodes
Install Cassandra on the new nodes
Reconfigure the Management Server
Adding ZooKeeper nodes
Existing Edge configuration
Modifying the config file to add the three new ZooKeeper nodes
Configure Edge
Install ZooKeeper on the new nodes
Reconfigure the existing ZooKeeper nodes
Restart all Zookeeper nodes
Reconfigure the Management Server node
Reconfigure all the Routers
Reconfigure all the Message Processors
Reconfigure all Qpid nodes
Confidential and proprietary information of Apigee, Inc. Not to be disclosed except under nondisclosure agreement.
Page 4
Apigee Edge Operations Guide
Reconfigure all Postgres nodes
Validate the installation
Adding a data center
Considerations before adding a data center
Updating the existing data center
Creating the configuration files
Procedure to add a new data center
Moving Apigee Servers
Changing the IP Address of a Cassandra Node
For configurations with a single Cassandra node
For configurations with multiple Cassandra nodes (ring)
Update datastore registrations
Changing the IP Address of a ZooKeeper Node
Change the IP Address and restart the ZooKeeper ensemble (for multinode ensemble
configurations only)
Inform the Apigee nodes of the changed configuration
Changing the IP Address of a LDAP Server (OpenLDAP)
Changing the IP Address of Other Apigee Node Types
PostInstallation Tasks
Resetting Passwords
Reset OpenLDAP Password
Reset System Admin Password
Reset Organization User Password
Sys Admin and Organization User Password Rules
Resetting Cassandra password
Managing the Default LDAP Password Policy for API Management
Configuring the Default LDAP Password Policy
To configure the default LDAP password policy:
Default LDAP Password Policy Attributes
Confidential and proprietary information of Apigee, Inc. Not to be disclosed except under nondisclosure agreement.
Page 5
Apigee Edge Operations Guide
Unlocking a User Account
Setting the Session Timeout in the Edge UI
Enabling/Disabling Server (Message Processor/Router) Reachability
Enabling reachability on a node
Disabling reachability on a node
Checking reachability status
Removing a Server (Management Server/Message Processor/Router)
Setting Server Autostart
Troubleshooting autostart
Starting, Stopping, and Restarting Apigee Edge
Starting, Stopping and Restarting an Individual Service
Uninstalling Edge
Viewing Pod Details
Setting the port number of the Edge UI
Handling a PostgresSQL Database Failover
Customizing Edge Email Templates
Configuring the Edge SMTP server
Configuring SMTP for the Apigee BaaS SMTP Server
Modifying Java Settings
Setting HTTP request/response header limits
Setting the URL of the Developer Services portal
Allowing the Trace Tool Access to Local IP Addresses
Replacing the Edge license file
Allow custom reports longer than 31 days in the Edge UI
Configuring the Router to retry connections to a Message Processor
Setting log file location
Set the expiration time for user activation links in activation emails
Enable access to OAuth 2.0 tokens by user ID and app ID
Confidential and proprietary information of Apigee, Inc. Not to be disclosed except under nondisclosure agreement.
Page 6
Apigee Edge Operations Guide
APIs to retrieve and revoke OAuth 2.0 access tokens by user ID and app ID
Procedure for enabling token access
Step 1: Enable token access support for an organization
Step 2: Set permissions for opsadmin role in the organization
Step 3: Set the oauth_max_search_limit property
Step 4: Configure the OAuth 2.0 policy that generates tokens to include end user ID
Configuring SSL
Creating a JKS file
Generating an obfuscated password
Configuring SSL between a Router and a Message Processor
Configuring SSL for the management API
Ensure that your SSL port is open
Configure SSL
Configuring SSL for the management UI
Ensure that your SSL port is open
Configure SSL
Recurring Edge Services Maintenance Tasks
Maintenance Tool Set
Apache Cassandra Maintenance Tasks
AntiEntropy Maintenance
Log File Maintenance
Apache Zookeeper Maintenance Tasks
FourLetter Commands
Removing Old Snapshot Files
Log File Maintenance
OpenLDAP Maintenance Tasks
Recurring Analytics Services Maintenance Tasks
Pruning Analytics Data
Confidential and proprietary information of Apigee, Inc. Not to be disclosed except under nondisclosure agreement.
Page 7
Apigee Edge Operations Guide
Organization and Environment Maintenance
Checking Status of Users, Organization and Environment
About using config files
About setting up a virtual host
Options when you do not have a DNS entry for the virtual host
Creating an Organization, Environment, and Virtual Host
Create an Organization
Create an organization by using API calls
Create an Environment
Create an environment by using API calls
Create a Virtual Host
Deleting a Virtual Host/Environment/Organization
Delete a Virtual Host
Delete an Environment
Disassociate an Environment from Message Processor
Cleanup analytics
Delete the environment
Delete an Organization
Disassociate an Organization from Pod
Delete the organization
Managing Users, Roles, and Permissions
Adding a user
Assigning the user to a role in an organization
Adding a system administrator
Specifying the email domain of a system administrator
Deleting a user
Backup and Restore
What to Backup
Confidential and proprietary information of Apigee, Inc. Not to be disclosed except under nondisclosure agreement.
Page 8
Apigee Edge Operations Guide
Recovery time objective (RTO) vs. Recovery point objective (RPO)
Before You Start: Useful Facts
How to Perform a Backup
How to Perform a Restore
How to Restore a Component to an Existing Environment
Apache ZooKeeper
Restore one standalone node
Restore one cluster node
Restore a complete cluster
Apache Cassandra
Restore one standalone node
Restore one cluster node
Restore a complete cluster
PostgreSQL database
PosgreSQL running standalone or as Master
PosgreSQL running as Standby
Postgres Server
Qpidd database
Qpid Server
OpenLDAP
Management Server
Message Processor
Router
Edge UI
How to Reinstall and Restore Components
Apache ZooKeeper
Restore one standalone node
Restore one cluster node
Confidential and proprietary information of Apigee, Inc. Not to be disclosed except under nondisclosure agreement.
Page 9
Apigee Edge Operations Guide
Restore a complete cluster
Apache Cassandra
Restore one standalone node
Restore one cluster node
Restore a complete cluster
PostgreSQL database
PosgreSQL running standalone or as Master
PosgreSQL running as Standby
Postgres Server
Qpid Server and Qpidd
OpenLDAP
Management Server
Message Processor
Router
Edge UI
Complete Site Recovery
Restore a complete site
Monitoring
What to Monitor
System health checks
Processes/Application checks
APIlevel checks
Message flow checks
How to Monitor
Enabling JMX authentication and setting the JMX password
Management Server
Using JConsole – monitor system health check and process information
Using Edge Application – API checks
Confidential and proprietary information of Apigee, Inc. Not to be disclosed except under nondisclosure agreement.
Page 10
Apigee Edge Operations Guide
Using Edge Application – Users, organization and deployment checks
Router
Message Processor
Using JConsole – monitor system health check and process information
Using Edge Application – API checks
Using JMX – Message flow checks
Qpid Server
Using JConsole – monitor system health check and process information
Using Edge Application – API checks
Postgres Server
Using JConsole – monitor system health check and process information
Using Edge Application – API checks
Using Edge Application – organization and environment checks
Using Edge Application – axstatus check
PostgresSQL Database
Using Script – check_postgres.pl
DB Checks
API check – health status of postgres process
Postgres Resources
Apache Cassandra
Using JConsole – monitor task statistics
Using nodetool utility – manage cluster nodes
Cassandra Monitoring (UI)
Cassandra Resource
Apache ZooKeeper
Checking ZooKeeper status
Using ZooKeeper Four Letter Words
OpenLDAP
Confidential and proprietary information of Apigee, Inc. Not to be disclosed except under nondisclosure agreement.
Page 11
Apigee Edge Operations Guide
LDAP Level Test
Monitoring Best Practices
Monitoring Alerts
Setting Alert Thresholds
Criteria for Setting Systemlevel Alerts
Checking on Apigeespecific and Thirdparty Ports
Viewing Logs
Enabling debug logs for the Message Processor and Edge UI
Monitoring Tools
Managing LDAP Resources
Create an LDAP resource
Example
List all LDAP Resources
Get the Details of an LDAP Resource
Update an LDAP resource
Delete an LDAP Resource
Confidential and proprietary information of Apigee, Inc. Not to be disclosed except under nondisclosure agreement.
Page 12
Apigee Edge Operations Guide
Page 13
Overview
This document provides instructions on how to perform key operational tasks for the Apigee Edge for Private
Cloud.
The information is arranged according to the specific operational area being covered, with subsections for
each key Apigee subsystem – Edge Services and Analytics.
This version of this document has details specific to v
ersion 4.16.01
. Any references that are specific to
previous versions are oversights and should be reported as bugs.
Access the Apigee Community for your questions
The
Apigee Community
is a free resource where you can contact Apigee as well as other Apigee customers
with questions, tips, and other issues. Before posting to the community, be sure to first search existing posts to
see if your question has already been answered.
Confidential and proprietary information of Apigee, Inc. Not to be disclosed except under nondisclosure agreement.
Apigee Edge Operations Guide
Page 14
Apigee Edge Architecture Overview
The following diagram illustrates the Apigee Edge architecture and how Edge components interact.
Figure 1:
Conceptual Component Interactions
Component Descriptions
Components required for API processing
The following components must be up and running to process API requests:
●
The
Apigee
Router
receives requests from a load balancer, determines which organization and
environment the request is to be routed to, and sends the request to a Message Processor configured
to handle requests for that organization and environment.
●
The
Apigee
Message Processor
processes API requests. The Message Processor evaluates an
incoming request, executes any Apigee policies, and calls the backend systems and other systems to
retrieve data. Once those responses have been received, the Message Processor formats a response
and returns it to the initial client.
Confidential and proprietary information of Apigee, Inc. Not to be disclosed except under nondisclosure agreement.
Apigee Edge Operations Guide
●
Page 15
Apache Cassandra
is the runtime data repository for Apigee API processing. It is an eventually
consistent, distributed database.
Components not required for API processing but for system services
The following components are not required for processing API requests, but are required to start the required
Router, Message Processor, and Cassandra components:
●
Apache Zookeeper
is a configuration database, which holds information about the location and
configuration of the various Apigee components. It is an instantly consistent, distributed database.
Components not required for API processing
The following components are not required for processing API requests but are necessary to enable additional
Edge functionality:
●
Apache Qpid
is a queuing system that accepts analytics data from the Message Processors and writes
the data to the PostgreSQL database.
●
The
Apigee
Postgres Server
manages the PostgresSQL analytics database.
●
The
Apigee Management Server
is the endpoint for Management API requests. The Management
Server also interacts with the Enterprise User Interface to display Analytics reporting requests.
●
The
Apigee Edge User Interface
is the management UI for the Apigee system. This UI can be used
to define and deploy APIs, manage developer and application definitions, and manage Apigee system
users.
●
The LDAP repository (
OpenLDAP
) contains Apigee UI user, role, and permission definitions.
Confidential and proprietary information of Apigee, Inc. Not to be disclosed except under nondisclosure agreement.
Apigee Edge Operations Guide
Page 16
About Planets, Regions, Pods, Organizations, Environments
and Virtual Hosts
An onpremises installation of Edge Private Cloud, or an Edge i
nstance,consists of multiple Edge components
installed on a set of server nodes. The following image shows the relationship among the planet, regions,
pods, organizations, environments, and virtual hosts that make up an Edge instance:
The following table describes these relationships:
Contains
Associated with
Default
Planet
One or more
regions
n/a
Region
One or more pods
"dc1"
Pod
One or more Edge
components
"central"
"gateway"
"analytics
"
Confidential and proprietary information of Apigee, Inc. Not to be disclosed except under nondisclosure agreement.
Apigee Edge Operations Guide
Page 17
Organization
One or more
environments
One or more pods containing Message
Processors, and a user acting as the org
admin
none
Environment
One or more virtual
hosts
One or more Message Processors in a pod
associated with the parent organization
none
Virtual Host
One or more host
aliases
none
About Planets
A
planet
represents an entire Edge hardware and software environment and can contain one or more regions.
In Edge, a planet is a logical grouping of regions — you do not explicitly create or configure a planet as part of
installing Edge.
About Regions
A
region
is a grouping of one or more pods. By default, when you install Edge, the installer creates a single
region named "dc1" containing three pods, as the following table shows:
Region
Pods in the region
"dc1"
"gateway", "central",
"analytics"
The following image shows the default regions:
Confidential and proprietary information of Apigee, Inc. Not to be disclosed except under nondisclosure agreement.
Apigee Edge Operations Guide
Page 18
This image shows the load balancer directing traffic to the "gateway" pod. The "gateway" pod contains the
Edge Router and Message Processor components that handle API requests. Unless you define multiple data
centers, you should not have to create additional regions.
In a more complex installation, you can create two or more regions. One reason to create multiple regions is to
organize machines geographically, which minimizes network transit time. In this scenario, you host API
endpoints so that they are geographically “close” to the consumers of those APIs.
In Edge, each region is referred to as a
data center.A data center in the Eastern US can then handle requests
arriving from Boston, Massachusetts, while a data center in Singapore can handle requests originating from
devices or computers in Asia.
For example, the following image shows two regions, corresponding to two data centers:
About Pods
A
pod
is a grouping of one or more Edge components and Cassandra datastores. The Edge components can
be installed on the same node, but are more commonly installed on different nodes. A Cassandra datastore is
a data repository used by the Edge components in the pod.
By default, when you install Edge, the installer creates three pods and associates the following Edge
components and Cassandra datastores with each pod:
Pod
Edge components
"gateway"
Router, Message Processor
Cassandra datastores
cachedatastore
counterdatastore
dcdatastore
keyvaluemapdatastore
kmsdatastore
Confidential and proprietary information of Apigee, Inc. Not to be disclosed except under nondisclosure agreement.
Apigee Edge Operations Guide
Page 19
"central"
Management Server, Zookeeper,
LDAP, UI
applicationdatastore
apimodeldatastore
auditdatastore
authdatastore
managementserver
usersettingsdatastore
"analytics"
Postgres, Qpid
analyticsdatastore
reportcruddatastore
The Edge components and Cassandra datastores in the "gateway" pod are required for API processing. These
components and datastores must be up and running to process API requests. The components and datastores
in the "central" and "analytics" pods are not required to process APIs, but add additional functionality to Edge.
The following image shows the components in each pod:
You can add additional pods for Message Processors and Routers to the three that are created by default. You
can also add additional Edge components to an existing pod. For example, you can add additional Routers and
Message Processors to the "gateway" pod to handle increased traffic loads.
Notice that the "gateway" pod contains the Edge Router and Message Processor components. Routers only
send requests to Message Processors in the same pod and not to Message Processors in other pods.
Confidential and proprietary information of Apigee, Inc. Not to be disclosed except under nondisclosure agreement.
Apigee Edge Operations Guide
Page 20
You can use the following API call to view server registration details at the end of the installation for each pod.
This is a useful monitoring tool.
curl u
adminEmail:pwordhttp://<
ms_IP
>:8080/v1/servers?pod=
podName
where
ms_IP
is the IP address or DNS name of the Management Server, and
podName i
s either:
●
gateway
●
central
●
analytics
For example, for the "gateway" pod:
> curl u
adminEmail:pwordhttp://<
ms_IP
>:8080/v1/servers?pod=
gateway
You see output in the form:
[{
"externalHostName" : "localhost",
"externalIP" : "192.168.1.11",
"internalHostName" : "localhost",
"internalIP" : "192.168.1.11",
"isUp" : true,
"pod" : "gateway",
"reachable" : true,
"region" : "dc1",
"tags" : {
"property" : [ {
"name" : "jmx.rmi.port",
"value" : "1101"
}, ... ]
},
"type" : [ "messageprocessor" ],
"uUID" : "276bc2507dd046a5a583fd11eba786f8"
},
{
"internalIP" : "192.168.1.11",
"isUp" : true,
Confidential and proprietary information of Apigee, Inc. Not to be disclosed except under nondisclosure agreement.
Apigee Edge Operations Guide
Page 21
"pod" : "gateway",
"reachable" : true,
"region" : "dc1",
"tags" : {
"property" : [ ]
},
"type" : [ "dcdatastore", "managementserver", "cachedatastore",
"keyvaluemapdatastore", "counterdatastore", "kmsdatastore" ],
"uUID" : "13cee956d3a745778f0f1694564179e4"
},
{
"externalHostName" : "localhost",
"externalIP" : "192.168.1.11",
"internalHostName" : "localhost",
"internalIP" : "192.168.1.11",
"isUp" : true,
"pod" : "gateway",
"reachable" : true,
"region" : "dc1",
"tags" : {
"property" : [ {
"name" : "jmx.rmi.port",
"value" : "1100"
}, ... ]
},
"type" : [ "router" ],
"uUID" : "de8a0200e40543a3a5f9eabafdd990e2"
}]
The
type
attribute lists the component type. Note that it lists the Cassandra datastores registered in the pod.
While Cassandra nodes are installed in the "gateway" pod, you will see Cassandra datastores registered with
all pods.
Confidential and proprietary information of Apigee, Inc. Not to be disclosed except under nondisclosure agreement.
Apigee Edge Operations Guide
Page 22
About Organizations
An
organization
is a container for all the objects in an Apigee account, including APIs, API products, apps, and
developers. An organization is associated with one or more pods, where each pod must contain one or more
Message Processors.
Note
: In the default installation, where you only have a single "gateway" pod that contains all the Message
Processors, you only associate an org with the "gateway" pod.
In an onpremises installation of Edge Private Cloud, there are no organizations by default. When you create
an organization, you specify two pieces of information:
1. A user who functions as the organization administrator. That user can then add additional users to the
organization, and set the role of each user.
2. The "gateway" pod, the pod containing the Message Processors.
An organization can contain one or more environments. The default Edge installation procedure prompts you
to create two environments: "test" and "prod". However, you can create more environments as necessary, such
as "staging", "experiments", etc.
Organization provides scope for some Apigee capabilities. For example, keyvaluemap (KVM) data is
available at the organization level, meaning from all environments. Other capabilities, such as caching, are
scoped to a specific environment. Apigee analytics data is partitioned by a combination of organization and
environment.
Shown below are the major objects of an organization, including those defined globally in the organization, and
those defined specifically to an environment:
Confidential and proprietary information of Apigee, Inc. Not to be disclosed except under nondisclosure agreement.
Apigee Edge Operations Guide
Page 23
About Environments
An
environment
is a runtime execution context for the API proxies in an organization. You must deploy an API
proxy to an environment before it can be accessed. You can deploy an API proxy to a single environment or to
multiple environments.
An organization can contain multiple environments. For example, you might define a "dev", "test", and "prod"
environment in an organization.
When you create an environment, you associate it with one or more Message Processors. You can think of an
environment as a named set of Message Processors on which API proxies run. Every environment can be
associated with the same Message Processors, or with different ones.
To create an environment, specify two pieces of information:
1. The organization containing the environment.
2. The Message Processors that handle API proxy requests to the environment. These Message
Processors must be in a pod associated with the environment's parent organization.
By default, when you create an environment, Edge associates all available Message Processors in the
"gateway" pod with the environment. Alternatively, you can specify a subset of the available Message
Processors so that different Message Processors handle requests to different environments.
A Message Processor can be associated with multiple environments. For example, your Edge installation
contains two Message Processors: A and B. You then create three environments in your organization: "dev",
"test", and "prod":
●
For the "dev" environment, you associate Message Processor A because you do not expect a large
volume of traffic.
●
For the "test" environment, you associate Message Processor B because you do not expect a large
volume of traffic.
●
For the "prod" environment, you associate both Message Processors A and B to handle the
productionlevel volume.
The Message Processors assigned to an environment can all be from the same pod, or can be from multiple
pods, spanning multiple regions and data centers. For example, you define the environment "global" in your
organization that includes Message Processors from three regions, meaning three different data centers: US,
Japan, and Germany.
Deploying an API proxy to the "global" environment causes the API proxy to run on Message Processors in all
of three data centers. API traffic arriving at a Router in any one of those data centers would be directed only to
Message Processors in that data center because Routers only direct traffic to Message Processors in the
same pod.
Confidential and proprietary information of Apigee, Inc. Not to be disclosed except under nondisclosure agreement.
Apigee Edge Operations Guide
Page 24
About Virtual Hosts
A
virtual host
defines the port on the Edge Router on which an API proxy is exposed, and, by extension, the
URL that apps use to access the API proxy. Every environment must define at least one virtual host.
Ensure that the port number specified by the virtual host is open on the Router node. You can then access an
API proxy by making a request to:
http://:/{proxybasepath}/{resourcename}
https://:/{proxybasepath}/{resourcename}
where:
●
http
or
https
: If the virtual host is configured to supports SSL, use HTTPS. If the virtual host does
not support SSL, use HTTP.
●
:
is the IP address and port number of the virtual host.
●
{proxybasepath}
and
{resourcename}
are defined when you create the API proxy.
Typically, you do not publish your APIs to customers with an IP address and port number. Instead, you define
a DNS entry for the Router and port. For example:
http://
myAPI.myCo.com
/{proxybasepath}/{resourcename}
https://
myAPI.myCo.com
/{proxybasepath}/{resourcename}
You also must create a
host alias
for the virtual host that matches the domain name of the DNS entry. From
the example above, you would specify a host alias of m
yAPI.myCo.com
. If you do not have a DNS entry, set
the host alias to the IP address of the Router and port of the virtual host, as
:port
.
For more, see
http://apigee.com/docs/apiservices/content/virtualhosts
.
Creating your first organization, environment, and virtual host
After you complete the Edge installation process, your first action is typically to create an organization,
environment, and virtual host through the "onboarding" process. To perform onboarding, run the following
command on the Edge Management Server node:
//apigee/apigeeservice/bin/apigeeservice apigeeprovision
setuporg f
configFile
This command takes as input a config file that defines a user, organization, environment, and virtual host.
For example, you create:
●
A user of your choosing to function as the organization administrator
●
An organization named
example
●
An environment in the organization named p
rod
that is associated with all Message Processors in the
"gateway" pod
Confidential and proprietary information of Apigee, Inc. Not to be disclosed except under nondisclosure agreement.
Apigee Edge Operations Guide
●
A virtual host in the environment named
default
that allows HTTP access on port 9001
●
Host alias for the virtual host
Page 25
After running that script, you can access your APIs by using a URL in the form:
http://:9001/{proxybasepath}/{resourcename}
You can later add any number of organizations, environments, and virtual hosts.
For more information on onboarding, see h
ttp://docs.apigee.com/apiservices/content/onboardorganization
.
Confidential and proprietary information of Apigee, Inc. Not to be disclosed except under nondisclosure agreement.
Apigee Edge Operations Guide
Page 26
Apigee Installation File System
As part of the installation process, several directories are created which contain programs, scripts and tools
that you may find useful in your daytoday operation of the system.
Installation directory
By default, the installer writes all files to the
//apigee
directory.
In the instructions in this guide, the installation directory is noted as /
/apigee
, where
/
is
/opt
.
File System Structure
Under the
//apigee
directory are a number of directories, including one directory for each
Edge component. Each directory is prefixed by:
●
apigee
a thirdparty component used by Edge. For example, a
pigeecassandra
.
●
edge
an Edge component from Apigee. For example, e
dgemanagementserver
.
●
edgemint
a Monetization component. For example e
dgemintmanagementserver
.
●
baas
an API BaaS component. For example b
aasusergrid
.
Additional directories under the
//apigee
directory include:
●
customer/application
To configure Edge components after installation, you edit .properties files
in the
customer/application
directory. Changes to .properties files require you to restart the
affected Edge component.
Each component has its own .properties file in that directory. For example, r
outer.properties
and
managementserver.properties
. The .properties files are not installed by default. Typically, you
create them only when setting properties on a component.
●
data
Data associated with each component. If you create a local mirror of the Edge repo, it is stored
in the
data
directory.
●
var/log
Log files for each component. For example, v
ar/log/edgemanagementserver
contains the log files for the Edge Management Server.
Warning:
Only modify .properties files under the c
ustomer/application
directory. Modifying any files
under an Edge component's directory, under the /
/apigee/etc
directory, and under the
//apigee/token
directory is not supported and will result in an inoperable system. Please
contact
Apigee Support
if modification is required.
Confidential and proprietary information of Apigee, Inc. Not to be disclosed except under nondisclosure agreement.
Apigee Edge Operations Guide
Page 27
Important Data to Remember From the Installation Process
Before you can perform any maintenance tasks, you need to know a few things about your Apigee Edge
environment that are set during the system installation process. Be sure that you have the following
information available to your operations team:
●
Gateway pod name (default "gateway")
●
Central pod name (default "central")
●
Analytics pod name (default "analytics")
●
Region name (default "dc1")
●
Administrative user ID and password
Other important information, such as the Apigee version number or the unique identifiers (UUIDs) of an Apigee
component, can be found as follows:
●
Use the following command to display the status of all Edge components installed on the node:
> //apigee/apigeeservice/bin/apigeeall status
●
Use the following command to display the version numbers of all Edge components installed on the
node:
> //apigee/apigeeservice/bin/apigeeall version
●
Use the following API call to display the UUID of install Edge components:
> curl http://<
ms_IP
>:<
port_num
>/v1/servers/self u $ADMINEMAIL:$PW
where
ms_IP
is the IP address or DNS name of the Management server node, and
port_num
is:
o
8081 for the Router
o
8082 for the Message Processor
o
8083 for Qpid
o
8084 for Postgres
Confidential and proprietary information of Apigee, Inc. Not to be disclosed except under nondisclosure agreement.
Apigee Edge Operations Guide
Page 28
How to Configure Edge
To configure Edge after installation, you use a combination of .
properties
files and Edge utilities. For
example, to configure SSL on the Edge UI, you edit
.properties
files to set the necessary properties.
Changes to
.properties
files require you to restart the affected Edge component.
Apigee refers to the technique of editing .
properties
files as
code with config.Essentially, c
ode with config
is a key/value lookup tool based on settings in the
.properties
files. In code with config, the keys are
referred to as
tokens
. Therefore, to configure Edge, you set
tokens
in
.properties
files.
Code with config allows Edge components to set default values that are shipped with the product, lets the
installation team override those settings based on the installation topology, and then lets customers override
any properties they choose.
If you think of it as a hierarchy, then the settings are arranges as follows with customer settings having the
highest priority to override any settings from the installer team or Apigee:
1. Customer
2. Installer
3. Apigee
How to use .properties files
As a customer, you can only modify the
.properties
files in the
//apigee/customer/application
directory. Each component has its own .
properties
file in that directory. For example,
router.properties
and m
anagementserver.properties
.
Note
: If you have not set any properties for a component, the
//apigee/customer/application
directory might not contain a .
properties
file for the
component. In that case, create one. The only requirement on a
.properties
file is that it must be
accessible or readable by the "apigee" user. For example, to create a .
properties
file:
1. Create the file in an editor as any user.
2. Chown the owner of the file to
apigee:apigee
or, if you changed the user running the Edge service
from the
apigee
user, chown the file to the user who is running the Edge service.
To set a property for a component, edit the corresponding
.properties
file to set a token, and then restart
the component:
> //apigee/apigeeservice/bin/apigeeservice
componentrestart
For example, after editing
router.properties
, restart the Router:
> //apigee/apigeeservice/bin/apigeeservice edgerouter restart
When you upgrade Edge, the
.properties
files in the
//apigee/customer/application
directory are read. That means the upgrade will retain
any properties that you set on the component.
Confidential and proprietary information of Apigee, Inc. Not to be disclosed except under nondisclosure agreement.
Apigee Edge Operations Guide
Page 29
Location of .properties files
There are three toplevel directories for .
properties
files for Edge components: installation owner, and
customers. The default locations are shown in the following table:
Warning:
Edge customers can only modify the
.properties
files under
/apigee/customer
. While you can view files under the component and installation
directories, do not modify any files.
Owner
Default Token Root Directory
Component
/apigee/<
prefix
><
component
>/conf
where /<
prefix
><
component>
identifies the component, such as edgerouter or
apigeecassandra.
Installation
/apigee/token
Customer
/apigee/customer
Determining the current value of a token
Before you set a token in the
.properties
file for the component, you can first determine its current value by
using the following command:
> //apigee/apigeeservice/bin/apigeeservice
compconfigure search
token
where
comp
is the name of the component, and t
oken
is the token to inspect.
This command searches the hierarchy of
.properties
files to determine the current value of the token.
For example, to check the current value of the
conf_router_HTTP.request.line.limit
token for the
Router:
> //apigee/apigeeservice/bin/apigeeservice edgerouter configure
search conf_router_HTTP.request.line.limit
You should see output in the form:
Found key conf_router_HTTP.request.line.limit, with value, 4k, in
/opt/apigee/edgerouter/token/default.properties
Setting tokens in .properties files
To override the value of a token:
Confidential and proprietary information of Apigee, Inc. Not to be disclosed except under nondisclosure agreement.
Apigee Edge Operations Guide
Page 30
1. Edit the
.properties
file for the component to set the token value. If the file does not exist, then
create it.
2. Restart the component.
3. Check the token value.
For example, to set the request line limit for the Edge Router:
1. Edit the
//apigee/customer/application/router.properties
file to set the
conf_router_HTTP.request.line.limit
token:
conf_router_HTTP.request.line.limit=8k
2. Restart the Edge Router:
> //apigee/apigeeservice/bin/apigeeservice edgerouter
restart
3. Check the value of the token:
> //apigee/apigeeservice/bin/apigeeservice edgerouter
configure search conf_router_HTTP.request.line.limit
Locating a token
In most cases, the tokens you need to set are identified in this guide. However, if you need to determine the
token used to override a property, perform a g
rep
in the
source
folder of the component.
For example, if you know that in a previous release of Edge you set the
session.maxAge
property and want
to know the token value used to set it, then
grep
for the property in the
//apigee/edgeui/source
directory:
> grep ri "session.maxAge" //apigee/edgeui/source
You should see a result in the form:
//apigee/edgeui/source/conf/application.conf:session.maxAge
={T}conf_
application_session.maxage{/T}
The string between the
{T}{/T}
tags is the token that you set in the .
properties
file.
Setting a token that is currently commented out
Some tokens are commented out in the Edge configuration files. If you try to set a token that is commented
out, the setting is ignored.
To set a token that is commented out, you use a special syntax, in the form:
conf/
file.extension
+
propertyName
=propertyValue
Confidential and proprietary information of Apigee, Inc. Not to be disclosed except under nondisclosure agreement.
Apigee Edge Operations Guide
Page 31
For example, you want to set the property named H
TTPClient.proxy.host
on the Message Processor.
You then
grep
for the property to determine its token:
> cd /opt/apigee/edgemessageprocessor
> grep ri "HTTPClient.proxy.host" *
The
grep
command returns results in the form that includes the token value. Notice how the property name is
commented out, as indicated by the
#
prefix on the property name:
source/conf/http.properties:
#HTTPClient.proxy.host
={T}conf_http_HTTPClient.proxy
.host{/T}
token/default.properties:conf_http_HTTPClient.proxy.host=
conf/http.properties:
#HTTPClient.proxy.host
=
To set the property, edit
/opt/apigee/customer/application/messageprocessor.properties
to set the property as:
conf/http.properties+HTTPClient.proxy.host=myhost.name.com
Notice how the property name is prefixed by
conf/http.properties+
, the location and name of the
configuration file containing the property followed by "+".
After you restart the Message Processor, examine the file
/opt/apigee/edgemessageprocessor/conf/http.properties
:
> cat /opt/apigee/edgemessageprocessor/conf/http.properties
At the end of the file, you will see the property set, in the form:
conf/http.properties:HTTPClient.proxy.host=yhost.name.com
Confidential and proprietary information of Apigee, Inc. Not to be disclosed except under nondisclosure agreement.
Apigee Edge Operations Guide
Page 32
Using the apigeeadminapi.sh utility
Use the
apigeeadminapi.sh
utility to perform the same Edge configuration tasks that you perform by
making calls to the Edge management API. The advantage to the
apigeeadminapi.sh
utility is that it:
●
●
●
●
Use a simple commandline interface
Implements tabbased command completion
Provides help and usage information
Can display the corresponding API call if you decide to try the API
The
apigeeadminapi.sh
utility is not a replacement for the
apigeeprovision
utility. The
apigeeprovision
utility actually uses the a
pigeeadminapi.sh
utility to perform its tasks.
The main differences between the two are:
●
The
apigeeadminapi.sh
utility performs atomic functions that replace individual Edge API calls.
For example, to create an organization, environment, and virtual host requires three separate
apigeeadminapi.sh
commands corresponding to three API calls.
●
The
apigeeprovision
utility is designed to perform a complete highlevel operation in a single
command. For example, you can create an organization, environment, and virtual host with a single
apigeeprovision
command by passing a config file with all necessary information.
The Edge documentation uses both utilities where appropriate.
Installing apigeeadminapi.sh
The
apigeeadminapi.sh
utility is automatically installed when you install the a
pigeeprovision
or the
apigeevalidate
utility.
The utility is installed in the following location:
/opt/apigee/apigeeadminapi/bin/apigeeadminapi.sh
apigeeadminapi.sh syntax
The
apigeeadminapi.sh
utility uses a simple command line syntax. At any time, use the tab key to display
a prompt that lists the available command options.
To see all possible commands, invoke the utility with no options:
> apigeeadminapi.sh
If you press the tab key after typing
apigeeadminapi.sh
, you will see the list of possible options:
analytics classification logsessions
regions
securityprofile userroles
buildinfo GET
runtime
servers
orgs
users
The tab key displays options based on the context of the command. If you enter the tab key after typing:
Confidential and proprietary information of Apigee, Inc. Not to be disclosed except under nondisclosure agreement.
Apigee Edge Operations Guide
Page 33
> apigeeadminapi.sh orgs
You will see the possible options for completing the
orgs
command:
add apis apps delete envs list pods userroles
Use the
h
option to display help for any command. For example, if you use the
h
option as shown below:
> apigeeadminapi.sh orgs h
The utility displays complete help information for all possible options to the
orgs
command. The first item in
the output shows the help for the
"orgs add"
command:
+++++++++++++++++++++++++++++++++++++++++++
orgs add
Required:
o ORG Organization name
Optional:
H HEADER add http header in request
admin ADMIN_EMAIL admin email address
pwd ADMIN_PASSWORD admin password
host EDGE_SERVER edge server to make request to
port EDGE_PORT port to use for the http request
ssl set EDGE_PROTO to https, defaults to http
debug ( set in debug mode, turns on verbose in curl )
h
Displays Help
Setting parameters using commandline switches and environment variables
You must enter all parameters to a command by using either commandline switches, or by using environment
variables. Prefix the command line switches with a single dash () or double dash () as required.
Note
: If you omit the sys admin password when entering a command, the a
pigeeadminapi.sh
utility will
promt you for it. It will not prompt you for any other parameters.
For example, from the help show above for the the "
orgs add"
command, you can specify the organization
name by either:
●
Using the
o
command line switch:
> apigeeadminapi.sh orgs o testOrg
Confidential and proprietary information of Apigee, Inc. Not to be disclosed except under nondisclosure agreement.
Apigee Edge Operations Guide
●
Page 34
Setting an environment variable named O
RG
:
> export ORG=testOrg
> apigeeadminapi.sh orgs
Note
: You typically use environment variables to set
ADMIN_EMAIL
and
EDGE_SERVER
, and optionally
ADMIN_PASSWORD
. These parameters are used by most commands. The concern with setting other params,
such as
ORG
, by using environment variables is that the setting might be correct for one command but could be
incorrect for a subsequent command. For example, if you forget to reset the environment variable, you might
inadvertently pass the wrong value to the next command.
If you omit any required parameters to the command, the utility displays an error message describing the
missing parameters. For example, if you omit the
host
or
EDGE_SERVER
environment variable specifying
the Edge Management Server when creating an org, you see the following error message:
Error with required variable or parameter
ADMIN_PASSWORD....OK
ADMIN_EMAIL....OK
EDGE_SERVER....null
Two common parameters that you often set as environment variables are the sys admin email address and IP
address of the Management Server:
> export ADMIN_EMAIL=foo@bar.com
> export EDGE_SERVER=192.168.56.101
Passing a file to the apigeeadminapi.sh utility
Some
apigeeadminapi.sh
utility commands correspond to PUT and POST API calls that take a request
body. For example, creating a virtual host corresponds to a POST API call that requires information about the
virtual host in the request body.
When using the
apigeeadminapi.sh
utility to create a virtual host, or any command that takes a request
body, you can pass all of the necessary information on the command line as shown below:
> apigeeadminapi.sh orgs envs virtual_hosts add e prod o testOrg host
localhost admin foo@bar.com v myVHostUtil p 9005 a 192.168.56.101:9005
Or, you can pass a file containing the same information as would be contained in the request body of the
POST. For example, the following command takes a file defining the virtual host:
> apigeeadminapi.sh orgs envs virtual_hosts add e prod o testOrg host
localhost admin foo@bar.com f vhostcreate
where the file
vhostcreate
contains the POST body of the call. In this example, it is a XMLformatted
request body:
192.168.56.101:9005
Confidential and proprietary information of Apigee, Inc. Not to be disclosed except under nondisclosure agreement.
Apigee Edge Operations Guide
Page 35
9005
Displaying debug and API information
Use the
debug
option to the
apigeeadminapi.sh
utility to display detailed information about the
command. This infomration includes the cURL command generated by the
apigeeadminapi.sh
utility to
perform the operation.
For example, this command uses the
debug
option:
> apigeeadminapi.sh orgs add o testOrg2 admin foo@bar.com host localhost
debug
And displays the following output, including the generated cURL command:
curl H ContentType: application/xml v X POST
s k w \n==> %{http_code}
u ***oo@bar.com:*****
http://localhost:8080/v1/o d /apigee/apigeesetup/bin/setup.sh p r f
configFile
The “p r” option specifies to install the Router. See
http://docs.apigee.com/apiservices/latest/installedgecomponentsnode
for information on creating a
configFile
.
3. When the installation completes, the script displays the UUID of the Router.
If you need to determine the UUID later, use the following cURL command on the host where you
installed the Router:
> curl http://:8081/v1/servers/self
4. To check the configuration, you can run the following cURL command:
> curl v u
adminEmail:pword
"http://:8080/v1/servers?pod="
where
pod_name
is
gateway
or your custom pod name. You should see the UUIDs of all Routers,
including the Router that you just added.
If the Router UUID does not appear in the output, run the following cURL command to add it:
> curl v u
adminEmail:pword X POST
"http://<
ms_IP
>:8080/regions//pods/<
pod_name
>/servers d
Confidential and proprietary information of Apigee, Inc. Not to be disclosed except under nondisclosure agreement.
Apigee Edge Operations Guide
Page 37
"action=add&uuid={
router_UUID
}&type=router"
Replace
ms_IP
with the IP address of the Management Server,
region_name
with the default region
name of
dc1
or your custom region name, and p
od_name
with
gateway
or your custom pod name.
5. To test the router, you should be able to make requests to your APIs through the IP address or DNS
name of the Router. For example:
http://:/v1/apiPath
For example, if you completed the first tutorial where you created the weather API:
http://:/v1/weather/forecastrss?w=12797282
Add a Message Processor
After you install Edge on the node, use the following procedure to add a Message Processor:
1. Install Edge on the node using the internet or non internet procedure as described in the E
dge
Installation
manual.
2. At the command prompt, run the
apigeesetup.sh
script:
> //apigee/apigeesetup/bin/setup.sh p mp f
configFile
The “p mp” option specifies to install the Message Processor. See
http://docs.apigee.com/apiservices/latest/installedgecomponentsnode
for information on creating a
configFile
.
3. When the installation completes, the script displays the UUID of the Message Processor. Note that
UUID as you need it to complete the configuration process.
If you need to determine the UUID, use the following cURL command on the host where you installed
the Message Processor:
> curl http://:8082/v1/servers/self
4. For each environment in each organization in your installation, use the following cURL command to
associate the Message Processor with the environment:
> curl v u
adminEmail:pword
H "ContentType: application/xwwwformurlencoded" X POST
"http://<
ms_IP
>:8080/v1/o/{
org_name
}/e/{
env_name
}/servers" d
"action=add&uuid={
mp_UUID
}"
Confidential and proprietary information of Apigee, Inc. Not to be disclosed except under nondisclosure agreement.
Apigee Edge Operations Guide
Page 38
Replace
ms_IP
with the IP address of the Management Server and
org_name
and
env_name
with the
organization and environment associated with the Message Processor.
5. To check the configuration, you can run the following cURL command:
> curl v u
adminEmail:pword
"http://<
ms_IP
>:8080/v1/o/{
org_name
}/e/{
env_name
}/servers"
where
org_name
is the name of your organization, and e
nv_name
is the environment. You should see
the UUIDs of all Message Processors associated with the organization and environment, including the
Message Processor that you just added.
Add both a Router and a Message Processor
After you install Edge on the node, us the following procedure to add a router and Message Processor at the
same time:
1. At the command prompt, run the
apigeesetup
script:
> //apigee/apigeesetup/bin/setup.sh p rmp f
configFile
The “p rmp” option specifies to install the Router and Message Processor. See
t
http://docs.apigee.com/apiservices/latest/installedgecomponentsnode
for information on creating a
configFile
.
2. Follow the procedures above to configure the Router and Message Processor.
Adding Cassandra nodes
This document describes how to add three new Cassandra nodes to an existing Edge for Private Cloud
installation.
While you can add one or two Cassandra nodes to an existing Edge installation, Apigee recommends that you
add three nodes at a time.
Existing Edge configuration
All the supported Edge topologies for a production system specify to use three Cassandra nodes. The three
nodes are specified to the
CASS_HOSTS
property in the config file as shown below:
IP1=10.10.0.1
IP2=10.10.0.2
IP3=10.10.0.3
HOSTIP=$(hostname i)
ADMIN_EMAIL=opdk@apigee.com
APIGEE_ADMINPW=Secret123
Confidential and proprietary information of Apigee, Inc. Not to be disclosed except under nondisclosure agreement.
Apigee Edge Operations Guide
Page 39
LICENSE_FILE=/tmp/license.txt
MSIP=$IP1
USE_LDAP_REMOTE_HOST=n
LDAP_TYPE=1
APIGEE_LDAPPW=secret
BIND_ON_ALL_INTERFACES=y
MP_POD=gateway
REGION=dc1
ZK_HOSTS="$IP1 $IP2 $IP3"
ZK_CLIENT_HOSTS="$IP1 $IP2 $IP3"
CASS_HOSTS="$IP1:1,1 $IP2:1,1 $IP3:1,1"
SKIP_SMTP=n
SMTPHOST=smtp.example.com
SMTPUSER=smtp@example.com
SMTPPASSWORD=smtppwd
Note that the
REGION
property specifies the region name as "dc1". You need that information when adding
the new Cassandra nodes.
Modifying the config file to add the three new Cassandra nodes
In this example, the three new Cassandra nodes are at the following IP addresses:
●
●
●
10.10.0.14
10.10.0.15
10.10.0.16
You must first update Edge configuration file to add the new nodes:
IP1=10.10.0.1
IP2=10.10.0.2
IP3=10.10.0.3
# Add the new node IP addresses.
IP14=10.10.0.14
IP15=10.10.0.15
IP16=10.10.0.16
HOSTIP=$(hostname i)
ADMIN_EMAIL=opdk@apigee.com
...
# Update CASS_HOSTS to add each new node after an existing nodes.
CASS_HOSTS="
$IP1:1,1
$IP14:1,1$IP2:1,1
$IP15:1,1$IP3:1,1
$IP16:1,1"
Important
: Add each new Cassandra node to C
ASS_HOSTS
after an existing node.
Confidential and proprietary information of Apigee, Inc. Not to be disclosed except under nondisclosure agreement.
Apigee Edge Operations Guide
Page 40
This ensure that the existing nodes retain their initial token settings, and the initial token of each new node is
between the token values of the existing nodes.
Configure Edge
After editing the config file, you must:
● Reconfigure the existing Cassandra nodes
● Install Cassandra on the new nodes
● Reconfigure the Management Server
Reconfigure the existing Cassandra nodes
On the existing Cassandra nodes:
1. Rerun the
setup.sh
with the "p c" profile and the new config file:
> /opt/apigee/apigeesetup/bin/setup.sh p c f
updatedConfigFile
Install Cassandra on the new nodes
On each new Cassandra node:
1. Install Cassandra on the three nodes:
a. Install
apigeesetup
on the first node as described in the E
dge Installation Guide.
b. Install Cassandra on the first node by using the updated config file:
> /opt/apigee/apigeesetup/bin/setup.sh p c f
updatedConfigFile
c. Repeat steps a and b for the remaining new Cassandra nodes.
2. Rebuild the three new Cassandra nodes, specifying the region name set in the config file by the
REGION
property. In this example, it is "dc1":
a. On the first node, run:
> /opt/apigee/apigeecassandra/bin/nodetool h
nodeIPrebuild
dc1
where
nodeIP
is the IP address of the Cassandra node.
b. Repeat step a on the remaining new Cassandra nodes.
Reconfigure the Management Server
On a ManagementServer node
1. Update the
apigeecassandraclient
component on the Management Server node:
> /opt/apigee/apigeeservice/bin/apigeeservice apigeecassandraclient
update
2. Rerun
setup.sh
to update the Management Server for the newly added Cassandra nodes:
> /opt/apigee/apigeesetup/bin/setup.sh p ms f
updatedConfigFile
Confidential and proprietary information of Apigee, Inc. Not to be disclosed except under nondisclosure agreement.
Apigee Edge Operations Guide
Page 41
Adding ZooKeeper nodes
This document describes how to add three new ZooKeeper nodes to an existing Edge for Private Cloud
installation.
You can add one or two ZooKeeper nodes to an existing Edge installation, however, you must make sure that
you always have an odd number of ZooKeeper voter nodes, as described below..
Existing Edge configuration
All the supported Edge topologies for a production system specify to use three ZooKeeper nodes. The three
nodes are specified to the
ZK_HOSTS
and Z
K_CLIENT_HOSTS
properties in the config file as shown below:
IP1=10.10.0.1
IP2=10.10.0.2
IP3=10.10.0.3
HOSTIP=$(hostname i)
ADMIN_EMAIL=opdk@apigee.com
APIGEE_ADMINPW=Secret123
LICENSE_FILE=/tmp/license.txt
MSIP=$IP1
USE_LDAP_REMOTE_HOST=n
LDAP_TYPE=1
APIGEE_LDAPPW=secret
BIND_ON_ALL_INTERFACES=y
MP_POD=gateway
REGION=dc1
ZK_HOSTS="$IP1 $IP2 $IP3"
ZK_CLIENT_HOSTS="$IP1 $IP2 $IP3"
CASS_HOSTS="$IP1:1,1 $IP2:1,1 $IP3:1,1"
SKIP_SMTP=n
SMTPHOST=smtp.example.com
SMTPUSER=smtp@example.com
SMTPPASSWORD=smtppwd
where:
● ZK_HOSTS
specifies the IP addresses or DNS names of the ZooKeeper nodes. The IP addresses or
DNS names must be listed in the same order on all ZooKeeper nodes. In a multidata center
environment, list all ZooKeeper nodes from both data centers.
●
ZK_CLIENT_HOSTS
specifies the IP addresses or DNS names of the ZooKeeper nodes used by this
data center. The IP addresses or DNS names must be listed in the same order on all ZooKeeper
nodes.
Confidential and proprietary information of Apigee, Inc. Not to be disclosed except under nondisclosure agreement.
Apigee Edge Operations Guide
Page 42
In a single data center installation, these are the same nodes as specified by Z
K_HOSTS
. In a multidata
center environment, list only the ZooKeeper nodes in this data center.
Modifying the config file to add the three new ZooKeeper nodes
In this example, the three new ZooKeeper nodes are at the following IP addresses:
●
●
●
10.10.0.14
10.10.0.15
10.10.0.16
You must first update Edge configuration file to add the new nodes:
IP1=10.10.0.1
IP2=10.10.0.2
IP3=10.10.0.3
# Add the new node IP addresses.
IP14=10.10.0.14
IP15=10.10.0.15
IP16=10.10.0.16
HOSTIP=$(hostname i)
ADMIN_EMAIL=opdk@apigee.com
...
# Update ZK_HOSTS to add each new node after an existing nodes.
ZK_HOSTS="
$IP1 $IP2 $IP3
$IP14 $IP15 $IP16:observer"
# Update ZK_Client_HOSTS to add each new node after an existing nodes.
ZK_CLIENT_HOSTS="
$IP1 $IP2 $IP3
$IP14 $IP15 $IP16"
Mark the last node in
ZK_HOSTS
with the with “:observer” modifier. Nodes without the “:observer” modifier are
called "voters". You must have an odd number of "voters" in your configuration. Therefore, in this configuration,
you have 5 ZooKeeper voters and one observer.
Note
: While you can configure three observers and three voters, Apigee recommends that you use five voters.
Make sure to add the nodes to both
ZK_HOSTS
and Z
K_CLIENT_HOSTS
in the same order. However, omit the
“:observer” modifier when setting
ZK_CLIENT_HOSTS
.
Configure Edge
After editing the config file, you must perform all of the following tasks.
Install ZooKeeper on the new nodes
Install Zookeeper on the new nodes:
Confidential and proprietary information of Apigee, Inc. Not to be disclosed except under nondisclosure agreement.
Apigee Edge Operations Guide
Page 43
1. Install
apigeesetup
on the first node as described in the E
dge Installation Guide.
2. Install ZooKeeper on the first node by using the following commands:
> /opt/apigee/apigeeservice/bin/apigeeservice apigeezookeeper install
> /opt/apigee/apigeeservice/bin/apigeeservice apigeezookeeper setup f
updatedConfigFile
3. Repeat steps 1 and 2 for the remaining new ZooKeeper nodes.
Reconfigure the existing ZooKeeper nodes
On the existing ZooKeeper nodes:
1. Rerun the
setup.sh
with the "p c" profile and the new config file:
> /opt/apigee/apigeeservice/bin/apigeeservice apigeezookeeper setup f
updatedConfigFile
Restart all Zookeeper nodes
On all ZooKeeper nodes:
1. Restart the node:
> /opt/apigee/apigeeservice/bin/apigeeservice apigeezookeeper restart
You must restart all ZooKeeper nodes, but order of restart does not matter.
Reconfigure the Management Server node
On the Management Server node:
1. Run the setup command:
> /opt/apigee/apigeeservice/bin/apigeeservice edgemanagementserver
setup f
updatedConfigFile
2. Restart the Management Server:
> /opt/apigee/apigeeservice/bin/apigeeservice edgemanagementserver
restart
Reconfigure all the Routers
On all Router nodes:
1. Run the setup command:
Confidential and proprietary information of Apigee, Inc. Not to be disclosed except under nondisclosure agreement.
Apigee Edge Operations Guide
Page 44
> /opt/apigee/apigeeservice/bin/apigeeservice edgerouter setup f
updatedConfigFile
2. Restart the Router:
> /opt/apigee/apigeeservice/bin/apigeeservice edgerouter restart
Reconfigure all the Message Processors
On all Message Processor nodes:
1. Run the setup command:
> /opt/apigee/apigeeservice/bin/apigeeservice edgemessageprocessor
setup f
updatedConfigFile
2. Restart the Message Processor:
> /opt/apigee/apigeeservice/bin/apigeeservice edgemessageprocessor
restart
Reconfigure all Qpid nodes
On all Qpid nodes:
1. Run the setup command:
> /opt/apigee/apigeeservice/bin/apigeeservice edgeqpidserver setup f
updatedConfigFile
2. Restart Qpid:
> /opt/apigee/apigeeservice/bin/apigeeservice edgeqpidserver restart
Reconfigure all Postgres nodes
On all Postgres nodes:
1. Run the setup command:
> /opt/apigee/apigeeservice/bin/apigeeservice edgepostgresserver setup
f
updatedConfigFile
2. Restart Postgres:
> /opt/apigee/apigeeservice/bin/apigeeservice edgepostgresserver
restart
Validate the installation
You can validate the installation of the new ZooKeeper nodes by sending commands to port 2181 using netcat
(nc) or telnet. For more info on ZooKeeper commands, see:
http://zookeeper.apache.org/doc/r3.1.2/zookeeperAdmin.html#sc_zkCommands
Confidential and proprietary information of Apigee, Inc. Not to be disclosed except under nondisclosure agreement.
Apigee Edge Operations Guide
Page 45
To validate:
1. If it is not installed on the ZooKeeper node, install nc:
> sudo yum install nc
2. Run the following nc command:
> echo stat | nc localhost 2181
3. Repeat steps 1 and 2 on each ZooKeeper node.
In the
Mode
line of the output for the nodes, one node should be designated as observer, one node as
leader, and the rest as followers.
Adding a data center
You can add a data center (also called a r
egion)to an existing data center.
Considerations before adding a data center
Before you install add a data center, you must understand how to configure OpenLDAP, ZooKeeper,
Cassandra, and Postgres servers across the data centers. You must also ensure that the necessary ports are
open between the nodes in the two data centers.
●
OpenLDAP
Each data center has its own OpenLDAP server configured with replication enabled. When you install
the new data center, you must configure OpenLDAP to use replication, and you must reconfigure the
OpenLDAP server in the existing data center to use replication.
●
ZooKeeper
For the
ZK_HOSTS
property for both data centers, specify the IP addresses or DNS names of all
ZooKeeper nodes from both data centers, in the same order, and mark any nodes with the with
“:observer” modifier. Nodes without the “:observer” modifier are called "voters". You must have an odd
number of "voters" in your configuration.
In this topology, the ZooKeeper host on host 9 is the observer:
In the example configuration file shown below, node 9 is tagged with the “:observer” modifier so that
you have five voters: Nodes 1, 2, 3, 7, and 8.
Confidential and proprietary information of Apigee, Inc. Not to be disclosed except under nondisclosure agreement.
Apigee Edge Operations Guide
Page 46
For the
ZK_CLIENT_HOSTS
property for each data center, specify the IP addresses or DNS names of
only the ZooKeeper nodes in the data center, in the same order, for all ZooKeeper nodes in the data
center.
●
Cassandra
All data centers must to have the same number of Cassandra nodes.
For
CASS_HOSTS
for each data center, ensure that you specify all Cassandra IP addresses or DNS
names for both data centers. For data center 1, list the Cassandra nodes in that data center first. For
data center 2, list the Cassandra nodes in that data center first. List the Cassandra nodes in the same
order for all Cassandra nodes in the data center.
All Cassandra nodes must have a suffix ':,', for example ':1,1 = data center 1 and
rack/availability zone 1 and ':2,1 = data center 2 and rack/availability zone 1.
For example, "192.168.124.201:1,1 192.168.124.202:1,1 192.168.124.203:1,1 192.168.124.204:2,1
192.168.124.205:2,1 192.168.124.206:2,1"
The first node in rack/availability zone 1 of each data center will be used as the seed server.
In this deployment model, Cassandra setup will look like this:
●
Postgres
By default, Edge installs all Postgres nodes in master mode. However, when you have multiple data
centers, you configure Postgres nodes to use masterstandby replication so that if the master node
fails, the standby node can continue to server traffic. Typically, you configure the master Postgres
server in one data center, and the standby server in the second data center.
If the existing data center is already configured to have two Postgres nodes running in master/standby
mode, then as part of this procedure, deregister the existing standby node and replace it with a standby
node in the new data center.
The following table shows the before and after Postgres configuration for both scenarios:
Before
After
Single Master Postgres node in
dc1
Master Postgres node in
dc1
Standby Postgres node in
dc2
Master Postgres node in
dc1
Standby Postgres node in
dc1
Master Postgres node in
dc1
Standby Postgres node in
dc2
Deregister old Standby Postgres node in
dc1
Confidential and proprietary information of Apigee, Inc. Not to be disclosed except under nondisclosure agreement.
Apigee Edge Operations Guide
●
Page 47
Port requirements
You must ensure that the necessary ports are open between the nodes in the two data centers. For a
port diagram, see the
Edge Installation Guide.
Updating the existing data center
Adding a data center requires you to perform the steps to install and configure the new data center nodes, but
it also requires you to update nodes in the original data center. These modifications are necessary because
you are adding new Cassandra and ZooKeeper nodes in the new data center that have to be accessible to the
existing data center, and you have to reconfigure OpenLDAP to use replication.
Creating the configuration files
Shown below are the silent configuration files for the two data centers, where each data center has 6 nodes.
Notice that the config file for dc1 adds additional settings to:
●
Configure OpenLDAP with replication across two OpenLDAP nodes.
●
Add the new Cassandra and ZooKeeper nodes from dc2 to the config file for dc1.
# Datacenter 1
IP1=
IPorDNSnameOfNode1
IP2=
IPorDNSnameOfNode2
IP3=
IPorDNSnameOfNode3
IP7=
IPorDNSnameOfNode7
IP8=
IPorDNSnameOfNode8
IP9=
IPorDNSnameOfNode9
HOSTIP=$(hostname i)
MSIP=$IP1
ADMIN_EMAIL=opdk@apigee.com
APIGEE_ADMINPW=Secret123
LICENSE_FILE=/tmp/license.txt
USE_LDAP_REMOTE_HOST=n
LDAP_TYPE=2
LDAP_SID=1
LDAP_PEER=$IP7
APIGEE_LDAPPW=secret
BIND_ON_ALL_INTERFACES=y
MP_POD=gateway1
REGION=dc1
ZK_HOSTS="$IP1 $IP2 $IP3 $IP7 $IP8
$IP9:observer"
ZK_CLIENT_HOSTS="$IP1 $IP2 $IP3"
CASS_HOSTS="$IP1:1,1 $IP2:1,1 $IP3:1,1
$IP7:2,1 $IP8:2,1 $IP9:2,1"
# Datacenter 2
IP1=
IPorDNSnameOfNode1
IP2=
IPorDNSnameOfNode2
IP3=
IPorDNSnameOfNode3
IP7=
IPorDNSnameOfNode7
IP8=
IPorDNSnameOfNode8
IP9=
IPorDNSnameOfNode9
HOSTIP=$(hostname i)
MSIP=$IP7
ADMIN_EMAIL=opdk@apigee.com
APIGEE_ADMINPW=Secret123
LICENSE_FILE=/tmp/license.txt
USE_LDAP_REMOTE_HOST=n
LDAP_TYPE=2
LDAP_SID=2
LDAP_PEER=$IP1
APIGEE_LDAPPW=secret
BIND_ON_ALL_INTERFACES=y
MP_POD=gateway2
REGION=dc2
ZK_HOSTS="$IP1 $IP2 $IP3 $IP7 $IP8
$IP9:observer"
ZK_CLIENT_HOSTS="$IP7 $IP8 $IP9"
CASS_HOSTS="$IP7:2,1 $IP8:2,1 $IP9:2,1
$IP1:1,1 $IP2:1,1 $IP3:1,1"
Confidential and proprietary information of Apigee, Inc. Not to be disclosed except under nondisclosure agreement.
Apigee Edge Operations Guide
SKIP_SMTP=n
SMTPHOST=smtp.example.com
SMTPUSER=smtp@example.com
SMTPPASSWORD=smtppwd
SMTPSSL=n
SMTPPORT=25
Page 48
SKIP_SMTP=n
SMTPHOST=smtp.example.com
SMTPUSER=smtp@example.com
SMTPPASSWORD=smtppwd
SMTPSSL=n
SMTPPORT=25
Procedure to add a new data center
In this procedure, the data centers are named:
● dc1
: the existing data center
● dc2
: the new data center
1. On dc2
, install
apigeesetup
on all nodes. See the E
dge Installation Guide
for more info.
2. On dc2
, install Cassandra and ZooKeeper on the appropriate nodes:
/opt/apigee/apigeesetup/bin/setup.sh p ds f
configFile2
3. On dc1
, rerun
setup.sh
on the original Cassandra nodes with the new dc1 confiig file that includes
the Cassandra nodes from dc2:
/opt/apigee/apigeesetup/bin/setup.sh p ds f
configFile1
4. On dc1
, rerun
setup.sh
on the Management Server node:
> /opt/apigee/apigeesetup/bin/setup.sh p ms f
configFile1
5. On dc2
, run the rebuild command on all Cassandra nodes, specifying the region name of dc1:
> /opt/apigee/apigeecassandra/bin/nodetool h
cassIPrebuild dc1
6. On dc2
, install the Management Server on the appropriate node:
> /opt/apigee/apigeesetup/bin/setup.sh p ms f
configFile2
7. On dc2
, install the Routes and Message Processors on the appropriate nodes:
> /opt/apigee/apigeesetup/bin/setup.sh p rmp f
configFile2
8. On dc2
, install Qpid on the appropriate nodes:
Confidential and proprietary information of Apigee, Inc. Not to be disclosed except under nondisclosure agreement.
Apigee Edge Operations Guide
Page 49
> /opt/apigee/apigeesetup/bin/setup.sh p qs f
configFile2
9. On dc2
, install Postgres on the appropriate node:
> /opt/apigee/apigeesetup/bin/setup.sh p ps f
configFile2
10. Setup Postgres master/standby for the Postgres nodes. The Postgres node in d
c1
is the master, and
the Postgres node in
dc2
is the standby server.
Note
: If
dc1
is already configured to have two Postgres nodes running in master/standby mode, then
as part of this procedure, use the e
xisting master Postgres node in dc1
as the master, and the
Postgres node in dc2
as the standby server. Later in this procedure, you will deregister the existing
Postgres standby server in
dc1
.
a. On the master node in d
c1
, edit the config file to set:
PG_MASTER=
IPorDNSofNewMaster
PG_STANDBY=
IPorDNSofOldMaster
b. Enable replication on the new master:
> /opt/apigee/apigeeservice/bin/apigeeservice apigeepostgresql
setupreplicationonmaster f
configFIle
c. On the standby node in
dc2
, edit the config file to set:
PG_MASTER=
IPorDNSofNewMaster
PG_STANDBY=
IPorDNSofOldMaster
d. On the standby node in
dc2
, stop the server and then delete any existing Postgres data:
> /opt/apigee/apigeeservice/bin/apigeeservice apigeepostgresql
stop
> rm rf /opt/apigee/data/apigeepostgresql/
Note
: If necessary, you can backup this data before deleting it.
e. Configure the standby node in d
c2
:
> /opt/apigee/apigeeservice/bin/apigeeservice apigeepostgresql
setupreplicationonstandby f
configFile
11. On dc1
, update analytics configuration and configure the organizations.
a. On the Management Server node of dc1, g
et the UUID of the Postgres node:
> apigeeadminapi.sh servers list r dc1 p analytics t
Confidential and proprietary information of Apigee, Inc. Not to be disclosed except under nondisclosure agreement.
Apigee Edge Operations Guide
Page 50
postgresserver admin
adminEmailpwd
adminPwordhost localhost
The UUID appears at the end of the returned data. Save that value.
Note
: If
dc1
is configured to have two Postgres nodes running in master/standby mode, you
see two IP addresses and UUIDs in the output. Save both UUIDs. From the IPs, you should be
able to determine which UUID is for the master and which is for the standby node.
b. On the Management Server node of dc2, g
et the UUID of the Postgres node as shown in the
previous step. Save that value.
c. On the Management Server node of dc1, d
etermine the name of the analytics and consumer
groups. Many of the commands below require that information.
By default, the name of the analytics group is
axgroup001
, and the name of the consumer
group is
consumergroup001
. In the silent config file for a region, you can set the name of
the analytics group by using the A
XGROUP
property.
If you are unsure of the names of the analytics and consumer groups, use the following
command to display them:
> apigeeadminapi.sh analytics groups list admin
adminEmailpwd
adminPwordhost localhost
This command returns the analytics group name in the
name
field, and the consumer group
name in the
consumergroups
field.
d. On the Management Server node of dc1, r
emove the existing Postgres server from the
analytics group:
i.
Remove the Postgres node from the consumergroup:
> apigeeadminapi.sh analytics groups consumer_groups
datastores remove g axgroup001 c consumergroup001 u
UUID
Y admin
adminEmailpwd
adminPwordhost localhost
If
dc1
is configured to have two Postgres nodes running in master/standby mode,
remove both:
> apigeeadminapi.sh analytics groups consumer_groups
datastores remove g axgroup001 c consumergroup001 u
UUID_1,UUID_2Y admin
adminEmailpwd
adminPwordhost
localhost
Confidential and proprietary information of Apigee, Inc. Not to be disclosed except under nondisclosure agreement.
Apigee Edge Operations Guide
ii.
Page 51
Remove the Postgres node from the analytics group:
> apigeeadminapi.sh analytics groups postgres_server remove g
axgroup001 u
UUIDY admin
adminEmailpwd
adminPword
host localhost
If
dc1
is configured to have two Postgres nodes running in master/standby mode,
remove both:
> apigeeadminapi.sh analytics groups consumer_groups
datastores remove g axgroup001 c consumergroup001 u
UUID1,UUID2Y admin
adminEmailpwd
adminPwordhost
localhost
e. On the Management Server node of dc1, a
dd the new master/standby Postgres servers to
the analytics group:
i.
Add both Postgres servers to the analytics group:
> apigeeadminapi.sh analytics groups postgres_server add g
axgroup001 u "
UUID_1
,
UUID_2
" admin
adminEmailpwd
adminPwordhost localhost
where
UUID_1
corresponds to the master Postgres node in d
c1
, and
UUID_2
corresponds to the standby Postgres node in
dc2.
ii.
Add the PG servers to the consumergroup as master/standby:
> apigeeadminapi.sh analytics groups consumer_groups
datastores add g axgroup001 c consumergroup001 u
"
UUID_1
,
UUID_2
" admin
adminEmailpwd
adminPwordhost
localhost
f.
Add the Qpid servers from
dc2
to the analytics group:
i.
On the MS node of dc1, g
et the UUIDs of the Qpid nodes in d
c2
:
> apigeeadminapi.sh servers list r
dc2p central t
qpidserver admin
adminEmailpwd
adminPwordhost localhost
ii.
The UUIDs appear at the end of the returned data. Save those values.
On the Management Server node of dc1, a
dd the Qpid nodes to the analytics group:
> apigeeadminapi.sh analytics groups qpid_server add g
axgroup001 u
UUID_1,UUID_2admin
adminEmailpwd
adminPword
Confidential and proprietary information of Apigee, Inc. Not to be disclosed except under nondisclosure agreement.
Apigee Edge Operations Guide
Page 52
host localhost
iii.
On the Management Server node of dc1, a
dd the Qpid nodes to the consumer group:
> apigeeadminapi.sh analytics groups consumer_groups consumers
add g axgroup001 c consumergroup001 u
UUID_1,UUID_2
admin
adminEmailpwd
adminPwordhost localhost
g. Deregister and delete the old Postgres standby server from
dc1
:
i.
Deregister the existing d
c1
Postgres standby server:
> apigeeadminapi.sh servers deregister u
UUIDr dc1 p
analytics t postgresserver Y admin
adminEmailpwd
adminPwordhost
localhost
where
UUID
is the old standby Postgres node in d
c1
.
ii.
Delete the existing dc1 Postgres standby server:
Note
: This command does not uninstall the Postgres server node. It only removes it from
the list of Edge nodes. You can later uninstall Postgres from the node, if necessary.
> apigeeadminapi.sh servers delete u
UUIDadmin
adminEmail
pwd
adminPwordhost
localhost
12. For each organization and for each environment that you want to support across data centers:
a. On the Management Server node of dc1, a
dd the new MP_POD to the Organization:
> apigeeadminapi.sh orgs pods add o
orgNamer dc2 p
gateway2
admin
adminEmailpwd
adminPwordhost localhost
where
gateway2
is the name of the gateway pod as defined by the M
P_POD
property in the
dc2 config file.
b. Add the new Message Processors to the org and environment:
i.
On the Management Server node of dc2, g
et the UUIDs of the Message Processor
nodes in
dc2
:
> apigeeadminapi.sh servers list r dc2 p
gateway2t
messageprocessor admin
adminEmailpwd
adminPwordhost
localhost
Confidential and proprietary information of Apigee, Inc. Not to be disclosed except under nondisclosure agreement.
Apigee Edge Operations Guide
Page 53
The UUIDs appear at the end of the returned data. Save those values.
ii.
On the Management Server node of dc1, f
or each Message Processor in dc2, add
the Message Processor to an environment for the org:
> apigeeadminapi.sh orgs envs servers add o
orgNamee
envName
u
UUIDadmin
adminEmailpwd
adminPwordhost localhost
c. On the Management Server node of dc1, c
heck the organization:
> apigeeadminapi.sh orgs apis deployments o
orgNamea
apiProxyName
admin
adminEmailpwd
adminPwordhost localhost
where
apiProxyName
is the name of an API proxy deployed in the organization.
Confidential and proprietary information of Apigee, Inc. Not to be disclosed except under nondisclosure agreement.
Apigee Edge Operations Guide
Page 54
Moving Apigee Servers
Apigee components use IP addresses to communicate with each other. Moving components from one machine
to another may cause a configuration mismatch. To fix configuration mismatches, follow the relevant
instructions below.
Changing the IP Address of a Cassandra Node
To change the IP address of a Cassandra node, perform the following steps:
For configurations with a single Cassandra node
1. Edit
//apigee/customer/application/cassandra.properties
on the
system being modified. If the file does not exist, create it.
2. Change the following parameters:
●
Set the
conf_cassandra_seeds
and c
onf_cassandra_listen_address
parameters to
specify the system’s new IP address.
●
Change the
conf_cassandra_rpc_address
to use either the new IP address or 0.0.0.0 (which
allows Cassandra Thrift to listen on all interfaces).
3. Open
//apigee/apigeecassandra/conf/cassandratopology.properties
in
an editor.
You should see the old IP address and default setting in the form:
192.168.56.101=dc1:ra1
default=dc1:ra1
Save that information.
4. Edit
//apigee/customer/application/cassandra.properties
to change the
old IP address specified to the new IP address:
conf_cassandratopology_topology=192.168.56.103=dc1:ra1\ndefault=dc1:ra
1\n
Ensure that you insert “\n” after the IP address, and specify the same default settings as you found
above in Step 3.
5. Restart Cassandra:
> //apigee/apigeeservice/bin/apigeeservice apigeecassandra
restart
Confidential and proprietary information of Apigee, Inc. Not to be disclosed except under nondisclosure agreement.
Apigee Edge Operations Guide
Page 55
6. If necessary also repair ZooKeeper (see below), else restart every Apigee platform component starting
with Management Server.
For configurations with multiple Cassandra nodes (ring)
1. If the node being changed is a seed node, edit
//apigee/customer/application/cassandra.properties
file on each
system in the ring, and change the c
onf_cassandra_seeds
parameter to include the modified
system’s new IP. If the
cassandra.properties
file does not exist, create it.
2. Edit
//apigee/customer/application/cassandra.properties
on the
system being modified, and change the following parameters:
●
Set the
conf_cassandra_listen_address
to use the new IP address.
●
Set the
conf_cassandra_rpc_address
to use either the new IP address or 0.0.0.0 (which
allows Cassandra Thrift to listen on all interfaces).
3. Open
//apigee/apigeecassandra/conf/cassandratopology.properties
in
an editor.
You should see all Cassandra IP addresses and default setting in the form:
192.168.56.101=dc1:ra1
192.168.56.102=dc1:ra1
192.168.56.103=dc1:ra1
default=dc1:ra1
Save that information.
4. Edit
//apigee/customer/application/cassandra.properties
to change the
old IP address specified to the new IP address:
conf_cassandratopology_topology=192.168.56.101=dc1:ra1\n192.168.56.102=
dc1:ra1\
n192.168.56.104
=dc1:ra1\ndefault=dc1:ra1\n
Ensure that you insert “\n” after each IP address, and use the same default settings as you recorded
above in Step 3.
5. Restart Cassandra on the modified system. If the modified system is a seed node, also restart each
system that used the modified seed node.
> //apigee/apigeeservice/bin/apigeeservice apigeecassandra
restart
6.Run the
nodetool ring
command on the modified node to ensure that the ring is complete. The
utility can be found at
/apigee/apigeecassandra/bin
.
> nodetool h localhost ring
Confidential and proprietary information of Apigee, Inc. Not to be disclosed except under nondisclosure agreement.
Apigee Edge Operations Guide
Page 56
7.Run
nodetool repair
on the modified node. Note that this process may take some time, so it is
highly recommended that this not be done during peak API traffic hours.
> nodetool h localhost repair
8. If necessary, repair ZooKeeper (see below), then restart every Apigee platform component starting with
Management Server
Update datastore registrations
1. Find the UUIDs of datastore registrations specifying the old IP address by using the commands below.
Take note of the "type" and "UUID" parameters:
●
curl u $ADMINEMAIL:$PW "http://$MSIP:$port/v1/servers?pod=central" |
egrep i '(type|internalip|uuid|region)'
●
curl u $ADMINEMAIL:$PW "http://$MSIP: $port/v1/servers?pod=gateway" |
egrep i '(type|internalip|uuid|region)'
●
curl u $ADMINEMAIL:$PW "http://$MSIP :$port/v1/servers?pod=analytics"
| egrep i '(type|internalip|uuid|region)'
2. Register the new IP addresses using one of the commands below. The command needed will depend
on the type of the changed node.
Note
: The
REGION
parameter below refers to the datacenter that the cluster is in. For example, for high
availability you would generally have a cluster in dc1 (Dater Center 1) and a cluster in dc2 (Data
Center 2). This parameter is defined at installation time. The default value is dc1.
●
For type="applicationdatastore":
curl u $ADMINEMAIL:$PW "http://$MSIP:$port/v1/servers d
"Type=applicationdatastore&Type=auditdatastore&InternalIP=${NEWIP}&re
gion=${REGION}&pod=central" H 'contenttype:
application/xwwwformurlencoded' X POST
●
For type="kmsdatastore":
curl u $ADMINEMAIL:$PW "http://$MSIP:$port/v1/servers d
"Type=kmsdatastore&Type=dcdatastore&Type=keyvaluemapdatastore&Type=c
ounterdatastore&Type=cachedatastore
&InternalIP=${NEWIP}®ion=${REGION}&pod=${GATEWAY_POD}" H
'contenttype: application/xwwwformurlencoded' X POST
●
For type="reportcruddatastore":
curl u $ADMINEMAIL:$PW "http://$MSIP:$port/v1/servers" d
"Type=reportcruddatastore&InternalIP=${NEW_IP}®ion=${REGION}&pod=an
alytics" H 'contenttype: application/xwwwformurlencoded' X POST
Confidential and proprietary information of Apigee, Inc. Not to be disclosed except under nondisclosure agreement.
Apigee Edge Operations Guide
Page 57
3. Delete old registrations for the UUID of the system on which the IP address was changed
●
For each of these UUIDs issue:
curl u $ADMINEMAIL:$PW "http://$MSIP:$port/v1/servers/${OLD_UUID}" X
DELETE
Changing the IP Address of a ZooKeeper Node
Follow the steps below to change the IP address of a ZooKeeper node:
Change the IP Address and restart the ZooKeeper ensemble (for multinode ensemble
configurations only)
1. Open
//apigee/apigeezookeeper/conf/zoo.cfg
in an editor.
You should see all ZooKeeper IP addresses and default setting in the form:
server.1=192.168.56.101:2888:3888
server.2=192.168.56.102:2888:3888
server.3=192.168.56.103:2888:3888
Save that information.
2.On each ZooKeeper node, edit the file
//apigee/customer/application/zookeeper.properties
file to set the
conf_zoo_quorum
property to the correct IP addresses. If the file does not exist, create it.
conf_zoo_quorum=server.1=192.168.56.101:2888:3888\nserver.2=192.168.56.102
:2888:3888\nserver.3=192.168.56.
104
:2888:3888\n
Ensure that you insert “\n” after each IP address and that entries are in the same order on every node.
3. Find the leader of the ZooKeeper ensemble by using the following command (replace
with the
IP address of the Zookeeper machine):
echo srvr | nc 2181
The
Mode
line in the output should say "leader".
4. Restart one ZooKeeper after the other starting with the leader and ending with the node on which the IP
address was changed. If more than one zookeeper node changed IP addresses it may be necessary to
restart all nodes.
> //apigee/apigeeservice/bin/apigeeservice apigeezookeeper
restart
5. Use the
echo
command described above to verify each ZooKeeper node.
Confidential and proprietary information of Apigee, Inc. Not to be disclosed except under nondisclosure agreement.
Apigee Edge Operations Guide
Page 58
Inform the Apigee nodes of the changed configuration
1. On each Router node, edit the file
//apigee/customer/application/router.properties
as follows. If the file
does not exist, create it.
●
Change the
conf_zookeeper_connection.string
parameter to include the new IP address
●
Change the
conf_zookeeper_zk1.host
parameter to include the new IP address
2. On every Message Processor node, edit the file
//apigee/customer/application/messageprocessor.properties
as follows. If the file
does not exist, create it.
●
Change the
conf_zookeeper_connection.string
parameter to include the new IP address
●
Change the
conf_zookeeper_zk1.host
parameter to include the new IP address
3. On the Management Server node, edit the file
//apigee/customer/application/managementserver.properties
as follows. If the file
does not exist, create it.
●
Change the
conf_zookeeper_connection.string
parameter to include the new IP address
●
Change the
conf_zookeeper_zk1.host
parameter to include the new IP address
4. Restart all Apigee platform component by running the following command on each node:
//apigee/apigeeservice/bin/apigeeall restart
Changing the IP Address of a LDAP Server (OpenLDAP)
To change the IP address of an OpenLDAP node, do the following:
1. On the Management Server node, edit the file
//apigee/customer/application/managementserver.properties
file. If the file does
not exist, create it.
2. In the
managementserver.properties
file, set the
conf_security_ldap.server.host
parameter to the new IP address.
3. Restart the Management Server:
> //apigee/apigeeservice/bin/apigeeservice
edgemanagementserver restart
Changing the IP Address of Other Apigee Node Types
To change the IP address of any of these node types (Router, Message Processor, Postgres Server (not
postgresql) and Qpid Server (not qpidd):
Confidential and proprietary information of Apigee, Inc. Not to be disclosed except under nondisclosure agreement.
Apigee Edge Operations Guide
Page 59
1. Use the following cURL command to register the new internal and external IP address:
curl u $ADMINEMAIL:$PW X PUT http://$MSIP:8080/v1/servers/ d
ExternalIP=
curl u $ADMINEMAIL:$PW X PUT http://$MSIP:8080/v1/servers/ d
InternalIP=
where
uuid
is the UUID of the node.
If you do not know the UUID of the node, you can use the following command to display it:
●
Router:
curl http://:8081/v1/servers/self
●
Message Processor:
curl http://:8082/v1/servers/self
●
Qpid:
curl http://:8083/v1/servers/self
●
Postgres:
curl http://:8084/v1/servers/self
Confidential and proprietary information of Apigee, Inc. Not to be disclosed except under nondisclosure agreement.
Apigee Edge Operations Guide
Page 60
PostInstallation Tasks
This section discusses tasks or additional configuration steps which can best be accomplished after the
primary site installation is complete.
Resetting Passwords
You can reset the OpenLDAP, Apigee Edge system administrator, Edge organization user, and Cassandra
passwords after the installation is complete.
Reset OpenLDAP Password
Depending on your Edge configuration, OpenLDAP can be installed as:
●
A single instance of OpenLDAP installed on the Management Server node. For example, in a 2node,
5node, or 9node Edge configuration.
●
Multiple OpenLDAP instances installed on Management Server nodes, configured with OpenLDAP
replication. For example, in a 12node Edge configuration.
●
Multiple OpenLDAP instances installed on their own nodes, configured with OpenLDAP replication. For
example, in a 13node Edge configuration.
The way you reset the OpenLDAP password depends on your configuration.
For a single instance of OpenLDAP installed on the Management Server, perform the following:
1)On the Management Server node, run the following command to create the new OpenLDAP password:
> //apigee/apigeeservice/bin/apigeeservice apigeeopenldap
changeldappassword o
oldPword
n
newPword
2)Run the following command to store the new password for access by the Management Server:
> //apigee/apigeeservice/bin/apigeeservice
edgemanagementserver store_ldap_credentials p
newPword
This command restarts the Management Server.
In an
OpenLDAP replication setup with OpenLDAP installed on Management Server nodes
, follow the
above steps on both Management Server nodes to update the password.
Note:
You must set
identical new password o
n both LDAP servers in order to achieve successful OpenLDAP
replication.
In an
OpenLDAP replication setup with OpenLDAP being on a node other than Management Server
,
ensure that you first change the password on both OpenLDAP nodes, then on both Management Server
nodes.
Confidential and proprietary information of Apigee, Inc. Not to be disclosed except under nondisclosure agreement.
Apigee Edge Operations Guide
Page 61
Reset System Admin Password
Resetting the system admin password requires you to reset the password in two places:
●
Management Server
●
UI
Note
: You cannot reset the system admin password from the Edge UI. You must use the procedure below to
reset it.
Warning
: You should stop the Edge UI before resetting the system admin password. Because you reset the
password first on the Management Server, there can be a short period of time when the UI is still using the old
password. If the UI makes more than three calls using the old password, the OpenLDAP server locks out the
system admin account for three minutes.
To reset the system admin password:
1) On the UI node, stop the Edge UI:
> //apigee/apigeeservice/bin/apigeeservice edgeui stop
2) On the Management Server, run the following command to reset the password:
> //apigee/apigeeservice/bin/apigeeservice
edgemanagementserver change_sysadmin_password o
currentPWn
newPW
3)Edit the silent config file that you used to install the Edge UI to set the following properties:
APIGEE_ADMINPW=newPW
SMTPHOST=smtp.gmail.com
SMTPPORT=465
SMTPUSER=foo@gmail.com
SMTPPASSWORD=bar
SMTPSSL=y
Note that you have to include the SMTP properties when passing the new password because all
properties on the UI are reset.
4)Use the
apigeesetup
utility to reset the password on the Edge UI from the config file:
> //apigee/apigeesetup/bin/setup.sh p ui f configFile
5) Start the Edge UI on the UI node:
> //apigee/apigeeservice/bin/apigeeservice edgeui start
Confidential and proprietary information of Apigee, Inc. Not to be disclosed except under nondisclosure agreement.
Apigee Edge Operations Guide
Page 62
In an
OpenLDAP replication
environment with multiple Management Servers, resetting the password on one
Management Server updates the other Management Server automatically. However, you have to update all
Edge UI nodes separately.
Reset Organization User Password
To reset the password for an organization user, use the a
pigeeservce
utility to invoke
apigeesetup
:
//apigee/apigeeservice/bin/apigeeservice apigeesetup
reset_user_password
[h]
[u USER_EMAIL]
[p USER_PWD]
[a ADMIN_EMAIL]
[P APIGEE_ADMINPW]
[f configFile]
For example:
> //apigee/apigeeservice/bin/apigeeservice apigeesetup
reset_user_password u user@myCo.com p foo12345 a admin@myCo.com P
adminPword
Note
: If you omit the admin email, then it uses the default admin email set at installation time. If you omit the
admin password, then the script prompts for it. All other parameters must be set on the command line, or in a
config file.
Shown below is an example config file that you can use with the "f" option:
USER_NAME=
user@myCo.com
USER_PWD=
"
foo12345"
APIGEE_ADMINPW=
adminPword
You can also use the following curl command to invoke the Edge API to change the user password:
curl u : X POST \
http://:8080/v1/users/{userEmail} \
d '
{newPW}
{firstName}
{lastName}
{userEmail}
' \
H "ContentType: application/xml"
where
userEmail
is the email address of the organization user.
Confidential and proprietary information of Apigee, Inc. Not to be disclosed except under nondisclosure agreement.
Apigee Edge Operations Guide
Page 63
Sys Admin and Organization User Password Rules
Use this section to enforce a desired level of password length and strength for your API management users.
The settings use a series of preconfigured (and uniquely numbered) regular expressions to check password
content (such as uppercase, lowercase, numbers, and special characters). Write these settings to
//apigee/customer/application/managementserver.properties
file. If that file
does not exist, create it.
After editing
managementserver.properties
, restart the management server:
> //apigee/apigeeservice/bin/apigeeservice edgemanagementserver
restart
You can then set password strength ratings by grouping different combinations of regular expressions. For
example, you can determine that a password with at least one uppercase and one lowercase letter gets a
strength rating of "3", but that a password with at least one lowercase letter and one number gets a stronger
rating of "4".
Table 5:
Password Validation managementserver.properties
Properties
Description
conf_security_password.validation.minimum.
password.length=8
Use these to determine the overall
characteristics of valid passwords. The default
minimum rating for password strength
(described later in the table) is 3.
conf_security_password.validation.default.rating=2
conf_security_password.validation.minimum.
rating.required=3
Notice that the
password.validation.default.ratin
g=2
is lower than the minimum rating
required, which means that if a password
entered falls outside of the rules you
configure, the password is rated a 2 and is
therefore invalid (below the minimum rating of
3).
Following are regular expressions that identify password characteristics. Note that each one is numbered.
For example, "password.validation.regex.
5
=…" is expression number 5. You’ll use these numbers in a later
section of the file to set different combinations that determine overall password strength.
conf_security_password.validation.regex.1=^(.)\\1+$
1 – All characters repeat
conf_security_password.validation.regex.2=^.*[az]+.*$
2 – At least one lowercase letter
Confidential and proprietary information of Apigee, Inc. Not to be disclosed except under nondisclosure agreement.
Apigee Edge Operations Guide
Page 64
conf_security_password.validation.regex.3=^.*[AZ]+.*$
3 – At least one uppercase letter
conf_security_password.validation.regex.4=^.*[09]+.*$
4 – At least one digit
conf_security_password.validation.regex.5=^.*[^azAz09
]+.*$
5 – At least one special character (not
including underscore _)
conf_security_password.validation.regex.6=^.*[_]+.*$
6 – At least one underscore
conf_security_password.validation.regex.7=^.*[az]{2,}.*$
7 – More than one lowercase letter
conf_security_password.validation.regex.8=^.*[AZ]{2,}.*$
8 – More than one uppercase letter
conf_security_password.validation.regex.9=^.*[09]{2,}.*$
9 – More than one digit
conf_security_password.validation.regex.10=^.*[^azAz0
9]{2,}.*$
10 – More than one special character (not
including underscore)
conf_security_password.validation.regex.11=^.*[_]{2,}.*$
11 – More than one underscore
The following rules determine password strength based on password content. Each rule includes one or
more regular expressions from the previous section and assigns a numeric strength to it. The numeric
strength of a password is compared to the
conf_security_password.validation.minimum.rating.required
number at the top of this
file to determine whether or not a password is valid.
conf_security_password.validation.rule.1=1,AND,0
conf_security_password.validation.rule.2=2,3,4,AND,4
conf_security_password.validation.rule.3=2,9,AND,4
Each rule is numbered. For example,
"password.validation.rule.
3
=…" is rule number
3.
conf_security_password.validation.rule.4=3,9,AND,4
Each rule uses the following format (right of
the equals sign):
conf_security_password.validation.rule.5=5,6,OR,4
,,
conf_security_password.validation.rule.6=3,2,AND,3
regexindexlist
is the list of regular
expressions (by number from the previous
section), along with an A
ND|OR
operator
(meaning, consider all or any of the
expressions listed).
conf_security_password.validation.rule.7=2,9,AND,3
conf_security_password.validation.rule.8=3,9,AND,3
Confidential and proprietary information of Apigee, Inc. Not to be disclosed except under nondisclosure agreement.
Apigee Edge Operations Guide
Page 65
rating
is the numeric strength rating given to
each rule.
For example, rule 5 means that any password
with at least one special character OR one
underscore gets a strength rating of 4. With
password.validation.minimum.
rating.required=3 at the top of the file, a
password with a 4 rating is valid.
conf_security_rbac.password.validation.enabled=true
Set rolebased access control password
validation to false when single signon (SSO)
is enabled. Default is true.
Resetting Cassandra password
By default, Cassandra ships with authentication disabled. If you enable authentication, it uses a predefined
user named '
cassandra
' with a password of '
cassandra
'. You can use this account, set a different
password for this account, or create a new Cassandra user. Add, remove, and modify users by using the
Cassandra CREATE/ALTER/DROP USER statements.
For information on how to enable Cassandra authentication, see
http://docs.apigee.com/apiservices/latest/enablecassandraauthentication
.
To reset the Cassandra password, you have to:
●
Set the password on each Cassandra node
●
Update the Edge configuration files on each node with the new password
For more information, see
http://www.datastax.com/documentation/cql/3.0/cql/cql_reference/cqlCommandsTOC.html
.
To reset the Cassandra password:
1. Log in to the first Cassandra node.
2.
Log into Cassandra using the
cqlsh
tool and the default credentials:
> //apigee/apigeecassandra/bin/cqlsh cassIP cassPort u
cassandra p cassandra
Where:
● cassIP
is the IP address of the Cassandra node.
● cassPort
is the Cassandra port, which by default is 9160.
● The default user is
cassandra
.
Confidential and proprietary information of Apigee, Inc. Not to be disclosed except under nondisclosure agreement.
Apigee Edge Operations Guide
●
Page 66
The default password is
cassandra
. If you changed the password previously, use the current
password.
3. Run the following command as the
cqlsh>
prompt to update the password:
cqlsh> ALTER USER cassandra WITH PASSWORD 'NEW_PASSWORD';
4. Exit the
cqlsh
tool:
cqlsh> exit
5. Repeat on all Cassandra nodes, ensuring that you use the same password on all nodes.
6. On the Management Server node, run the following command:
> //apigee/apigeeservice/bin/apigeeservice
edgemanagementserver store_cassandra_credentials u
CASS_USERNAMEp
CASS_PASSWORD
Optionally, you can pass a file to the command containing the new username and password:
> apigeeservice edgemanagementserver store_cassandra_credentials f
configFile
Where the
configFile
contains the following:
conf_credentials_cassandra.user=
CASS_USERNAME
conf_credentials_cassandra.password=
CASS_PASSWROD
This command automatically restarts the Management Server.
7. Repeat this process on the:
●
●
●
●
All Message Processors
All Routers
All Qpid servers (edgeqpidserver)
Postgres servers (edgepostgresserver)
The Cassandra password is now changed.
Managing the Default LDAP Password Policy for API Management
The Apigee system uses OpenLDAP to authenticate users in your API management environment. OpenLDAP
makes this LDAP password policy functionality available.
Confidential and proprietary information of Apigee, Inc. Not to be disclosed except under nondisclosure agreement.
Apigee Edge Operations Guide
Page 67
This section describes how to configure the delivered default LDAP password policy. Use this password policy
to configure various password authentication options, such as the number of consecutive failed login attempts
after which a password can no longer be used to authenticate a user to the directory.
This section also describes how to use a couple of APIs to unlock user accounts that have been locked
according to attributes configured in the default password policy.
Configuring the Default LDAP Password Policy
To configure the default LDAP password policy:
1. Connect to your LDAP server using an LDAP client, such as Apache Studio or ldapmodify. By default
OpenLDAP server listens on port 10389 on the OpenLDAP node.
To connect, specify the Bind DN or user of c
n=manager,dc=apigee,dc=com
and the OpenLDAP
password that you set at the time of Edge installation.
2. Use the client to navigate to the password policy attributes for:
a. Edge users:
cn=default,ou=pwpolicies,dc=apigee,dc=com
b. Edge sysadmin:
cn=sysadmin,ou=pwpolicies,dc=apigee,dc=com
3. Edit the password policy attribute values as desired.
4. Save the configuration.
Default LDAP Password Policy Attributes
Attribute
Description
Default
pwdExpireWarning
The maximum number of seconds before a password is
due to expire that expiration warning messages will be
returned to a user who is authenticating to the directory.
604800
Number of seconds after which old consecutive failed
bind attempts are purged from the failure counter.
300
pwdFailureCountInterval
(Equivalent to
7 days)
In other words, this is the number of seconds after which
the count of consecutive failed login attempts is reset.
If
pwdFailureCountInterval
is set to
0
, only a
successful authentication can reset the counter.
If
pwdFailureCountInterval
is set to >0, the
attribute defines a duration after which the count of
Confidential and proprietary information of Apigee, Inc. Not to be disclosed except under nondisclosure agreement.
Apigee Edge Operations Guide
Page 68
consecutive failed login attempts is automatically reset,
even if no successful authentication has occurred.
We suggest that this attribute be set to the same value
as the
pwdLockoutDuration
attribute.
pwdInHistory
Maximum number of used, or past, passwords for a user
that will be stored in the p
wdHistory
attribute.
3
When changing her password, the user will be blocked
from changing it to any of her past passwords.
pwdLockout
If
TRUE
, specifies to lock out a user when their password
expires so that the user can no longer log in.
False
pwdLockoutDuration
Number of seconds during which a password cannot be
used to authenticate the user due to too many
consecutive failed login attempts.
300
In other words, this is the length of time during which a
user account will remain locked due to exceeding the
number of consecutive failed login attempts set by the
pwdMaxFailure
attribute.
If
pwdLockoutDuration
is set to
0
, the user account
will remain locked until a system administrator unlocks it.
See
Unlocking a User Account
.
If
pwdLockoutDuration
is set to >0, the attribute
defines a duration for which the user account will remain
locked. When this time period has elapsed, the user
account will be automatically unlocked.
We suggest that this attribute be set to the same value
as the
pwdFailureCountInterval
attribute.
pwdMaxAge
Number of seconds after which a user (nonsysadmin)
password expires. A value of 0 means passwords do not
expire. The default value of 2592000 corresponds to 30
days from the time the password was created.
user: 2592000
sysadmin: 0
Confidential and proprietary information of Apigee, Inc. Not to be disclosed except under nondisclosure agreement.
Apigee Edge Operations Guide
Page 69
pwdMaxFailure
Number of consecutive failed login attempts after which
a password may not be used to authenticate a user to
the directory.
3
pwdMinLength
Specifies the minimum number of characters required
when setting a password.
8
Unlocking a User Account
A user’s account may be locked due to attributes set in the password policy. A user with the s
ysadmin
Apigee
role assigned can use the following API call to unlock the user’s account. Replace values in curly braces with
actual values.
To unlock a user:
/v1/users/{userEmail}/status?action=unlock X POST u {adminEmail}:{password}
Note:
To ensure that only system administrators can call this API, the/users/*/status
path is included in
the
conf_security_rbac.restricted.resources
property for the Management Server:
> cd /opt/apigee/edgemanagementserver
> grep ri "conf_security_rbac.restricted.resources" *
The output contains the following:
token/default.properties:conf_security_rbac.restricted.resources=/environments,
/environments/*,/environments/*/virtualhosts,/environments/*/virtualhosts/*,/po
ds,/environments/*/servers,/rebuildindex,
/users/*/status
Setting the Session Timeout in the Edge UI
By default, a session in the Edge UI expires one day after login. That means Edge UI users have to log in
again after the session expires.
You can configure the session timeout be setting the
conf_application_session.maxAge
property in
the
//apigee/customer/application/ui.properties
file. To set this property:
1. Open the
ui.properties
file in an editor. If the file does not exist, create it:
> vi //apigee/customer/application/ui.properties
2. Set
conf_application_session.maxAge
as a time value and time unit. Time units can be:
●
m
, minute, minutes
●
h
, hour, hours
Confidential and proprietary information of Apigee, Inc. Not to be disclosed except under nondisclosure agreement.
Apigee Edge Operations Guide
●
Page 70
d
, day, days
For example, set
conf_application_session.maxAge
as:
30m
,
12h
,
2d
.
3. Save your changes.
4. Restart the Edge UI:
> //apigee/apigeeservice/bin/apigeeservice edgeui restart
Enabling/Disabling Server (Message Processor/Router) Reachability
It is a good practice to set reachability to false on a server during maintenance, such as for a server restart or
upgrade. When reachability is false, no traffic is directed to the server. For example, when reachability is false
on a Message Processor, Routers will not direct any traffic to that Message Processor.
To upgrade a Message Processor, you can use the following procedure:
1) Set reachability to false on the Message Processor.
2) Wait a few seconds for the Message Processor to finish any current requests.
3) Upgrade the Message Processor and restart it.
4) Set reachability to true on the Message Processor.
Note
: In some configurations there may be a number of Routers behind a Load Balancer (ELB). The ELB
might be configured to monitor the reachability flag of the Routers, in which case setting reachability to false on
a Router would allow you to restart the Router.
The following API call allows load balancers to configure a node as reachable or unreachable. Note that it does
not remove the server physically in a setup:
> curl u
adminEmail:pWordX POST "http://<
ms_IP
>:8080/v1/servers/
UUID
" d
"reachable=
true|false
"
where
UUID
is the UUID of the Message Processor or Router, and r
eachable
is set to either true or false.
If you need to determine the UUID of the Router, use the following cURL command:
> curl http://:8081/v1/servers/self
If you need to determine the UUID of the Message Processor, use the following cURL command:
> curl http://:8082/v1/servers/self
Enabling reachability on a node
To enable any node (Router/Message Processor):
> curl u
adminEmail:pWordX POST "http://<
ms_IP
>:8080/v1/servers/
UUID
" d
"reachable=true"
Confidential and proprietary information of Apigee, Inc. Not to be disclosed except under nondisclosure agreement.
Apigee Edge Operations Guide
Page 71
Disabling reachability on a node
To disable any node (Router/Message Processor):
> curl u
adminEmail:pWordX POST "http://<
ms_IP
>:8080/v1/servers/
UUID
" d
"reachable=false"
Checking reachability status
To get reachable status of any node (Router/Message Processor):
> curl u
adminEmail:pWord"http://<
ms_IP
>:8080/v1/servers/
UUID
/reachable"
Removing a Server (Management Server/Message Processor/Router)
Follow the steps below to remove a server from an onpremises installation of Apigee Edge for Private Cloud.
1) (Message Processor only)
Deregister Message Processor from the organization's environments
curl X POST
http://:8080/v1/o//e//servers
d "uuid={uuid}®ion={regionName}&pod={podName}&action=remove"
2) Deregister server’s type
curl http://:8080/v1/servers X POST d
"type={messageprocessor|router|managementserver}®ion={regionName}&pod
={podName}&uuid={uuid}&action=remove"
3) Delete the server
curl http://:8080/v1/servers/{uuid} X DELETE
Setting Server Autostart
An onpremises installation of Edge Private does not restart automatically during a reboot. You can use the
following commands to enable/disable autostart on any node.
For all components on the node:
●
//apigeeservice/bin/apigeeall enable_autostart
●
//apigeeservice/bin/apigeeall disable_autostart
For a specific component:
●
//apigeeservice/bin/apigeeservice
compenable_autostart
●
//apigeeservice/bin/apigeeservice
compdisable_autostart
The script only affects the node on which you run it. If you want to configure all nodes for autostart, run the
script on all nodes.
Confidential and proprietary information of Apigee, Inc. Not to be disclosed except under nondisclosure agreement.
Apigee Edge Operations Guide
Page 72
Note
: If you run into issues where the OpenLDAP server does not start automatically on reboot, try disabling
SELinux or setting it to permissive mode.
Note that the order of starting the components is very important:
1) First start ZooKeeper, Cassandra, LDAP (OpenLDAP)
If ZooKeeper and Cassandra are installed as cluster, the complete cluster must be up and running
before starting any other Apigee component.
2) Then, any Apigee component (Management Server, Router, UI, etc.)
For Postgres Server first start
postgresql
and for Qpid Server first start
qpidd
.
Implications:
●
For a complete restart of an Apigee Edge environment, the nodes with ZooKeeper and Cassandra
need to be booted completely prior to any other node.
●
If any other Apigee component is running on one or more ZooKeeper and Cassandra nodes, it is not
recommended to use autostart. Instead, start the components in the order described below in
Starting,
Stopping, and Restarting Apigee Edge
.
Troubleshooting autostart
If you configure autostart, and Edge encounters issues with starting the OpenLDAP server, you can try
disabling SELinux or setting it to permissive mode on all nodes. To configure SELinux:
1. Edit the
/etc/sysconfig/selinux
file:
> sudo vi /etc/sysconfig/selinux
2. Set
SELINUX=disabled
or S
ELINUX=permissive
3. Save your edits.
4. Restart the machine and then restart Edge:
> //apigee/bin/allstart.sh
Starting, Stopping, and Restarting Apigee Edge
The order of stopping and starting the subsystems is important. Start and stop scripts are provided that take
care of that for you for Edge components running on the same node.
Stop order
: If you install Edge on multiple nodes, then you should s
top
Edge components on those nodes in
the following order:
1. Apigee UI
2. Management Server
3. Router
4. Message Processor
Confidential and proprietary information of Apigee, Inc. Not to be disclosed except under nondisclosure agreement.
Apigee Edge Operations Guide
Page 73
5. Qpid Server
6. Postgres Server
7. OpenLDAP
8. Qpidd
9. PostgreSQL database
10. Cassandra
11. ZooKeeper
Start order
: If you install Edge on multiple nodes, then you should s
tart
Edge components on those nodes in
the following order:
1. ZooKeeper
2. Cassandra
3. OpenLDAP
4. Qpidd
5. PostgreSQL database
6. Management Server
7. Router
8. Message Processor
9. Qpid Server
10. Postgres Server
11. Apigee UI
The following scripts detect the Apigee components configured to run on the system on which the script is
executed, and will start or stop only those components in the correct order for that node.
●
To stop Apigee Edge, Apache Cassandra, and Apache ZooKeeper:
//apigee/apigeeservice/bin/apigeeall stop
●
To start Apache ZooKeeper, Apache Cassandra, and Apigee Edge:
//apigee/apigeeservice/bin/apigeeall start
●
To check if the server is running:
//apigee/apigeeservice/bin/apigeeall status
Starting, Stopping and Restarting an Individual Service
You can use the following tool to start/stop/restart an individual Apigee service on any specific server.
//apigee/apigeeservice/bin/apigeeservice
Confidential and proprietary information of Apigee, Inc. Not to be disclosed except under nondisclosure agreement.
Apigee Edge Operations Guide
Page 74
where:
●
is one of the following:edgemanagementserver, edgeui, edgerouter,
edgemessageprocessor, apigeeqpidserver, apigeepostgresserver,
apigeezookeeper, apigeecassandra, apigeeopenldap, apigeeqpidd,
apigeepostgresql
●
is one of the following
: start, stop, restart
For example, to start or stop or restart Management Server, run the following commands:
apigeeservice edgemanagementserver start
apigeeservice edgemanagementserver stop
apigeeservice edgemanagementserver restart
You can also check the status of an individual Apigee service by using the following command:
apigeeservice edgemanagementserver status
Uninstalling Edge
To uninstall a component, use the
apigeeservice
utility in the form:
> //apigee/apigeeservice/bin/apigeeservice
compNameuninstall
For example, to uninstall the Edge UI:
> //apigee/apigeeservice/bin/apigeeservice edgeui uninstall
To uninstall all Apigee components on the node, uninstall the
apigeeservice
utility:
> /opt/apigee/apigeeservice/bin/apigeeservice apigeeservice uninstall
This command does not delete any data or log files. It only deletes the components.
If you want to completely remove Edge from your system:
1. Stop all Edge services running on the machine:
> /opt/apigee/apigeeservice/bin/apigeeall stop
2. Clear the yum cache:
> sudo yum clean all
3. Remove all the Apigee RPMs:
> sudo rpm e $(rpm qa | egrep "(apigee|edge|baas)")
4. Remove the installation root directory:
> sudo rm rf /opt/apigee
Confidential and proprietary information of Apigee, Inc. Not to be disclosed except under nondisclosure agreement.
Apigee Edge Operations Guide
Page 75
Viewing Pod Details
You can use the following API call to view server registration details at the end of the installation for each pod.
This is a useful monitoring tool.
curl u
adminEmail:pwordhttp://<
ms_IP
>:8080/v1/servers?pod=
podName
where
ms_IP
is the IP address or DNS name of the Management Server, and
podName i
s either:
●
gateway
●
central
●
analytics
For example, for the "gateway" pod:
> curl u
adminEmail:pwordhttp://<
ms_IP
>:8080/v1/servers?pod=
gateway
You see output in the form:
[{
"externalHostName" : "localhost",
"externalIP" : "192.168.1.11",
"internalHostName" : "localhost",
"internalIP" : "192.168.1.11",
"isUp" : true,
"pod" : "gateway",
"reachable" : true,
"region" : "dc1",
"tags" : {
"property" : [ {
"name" : "jmx.rmi.port",
"value" : "1101"
}, ... ]
},
"type" : [ "messageprocessor" ],
"uUID" : "276bc2507dd046a5a583fd11eba786f8"
},
{
Confidential and proprietary information of Apigee, Inc. Not to be disclosed except under nondisclosure agreement.
Apigee Edge Operations Guide
Page 76
"internalIP" : "192.168.1.11",
"isUp" : true,
"pod" : "gateway",
"reachable" : true,
"region" : "dc1",
"tags" : {
"property" : [ ]
},
"type" : [ "dcdatastore", "managementserver", "cachedatastore",
"keyvaluemapdatastore", "counterdatastore", "kmsdatastore" ],
"uUID" : "13cee956d3a745778f0f1694564179e4"
},
{
"externalHostName" : "localhost",
"externalIP" : "192.168.1.11",
"internalHostName" : "localhost",
"internalIP" : "192.168.1.11",
"isUp" : true,
"pod" : "gateway",
"reachable" : true,
"region" : "dc1",
"tags" : {
"property" : [ {
"name" : "jmx.rmi.port",
"value" : "1100"
}, ... ]
},
"type" : [ "router" ],
"uUID" : "de8a0200e40543a3a5f9eabafdd990e2"
}]
Confidential and proprietary information of Apigee, Inc. Not to be disclosed except under nondisclosure agreement.
Apigee Edge Operations Guide
Page 77
Setting the port number of the Edge UI
By default, the Edge UI listens on port 9000 of the Edge node on which it is installed. Use the following
procedure to change the port number:
1. Ensure that the desired port number is open on the Edge node.
2. Open
//apigee/customer/edgeui.d/ui.sh
in an editor. If the file and directory
does not exist, create it.
3. Set the following propertty in
ui.sh
:
export JAVA_OPTS="Dhttp.address=
IPDhttp.port=
PORT
"
Where IP is the IP address of the Edge UI node, and PORT is the new port number.
4. Save the file.
5. Restart the Edge UI:
//apigee/apigeeservice/bin/apigeeservice edgeui restart
You can now access the Edge UI on the new port number.
Handling a PostgresSQL Database Failover
Perform the following during a PostgreSQL database failover:
1) Stop
apigeepostgresql
on the current master if it is still running:
> //apigee/apigeeservice/bin/apigeeservice apigeepostgresql
stop
2) Go to standby node and invoke the following command to make it the master:
> //apigee/apigeeservice/bin/apigeeservice apigeepostgresql
promotestandbytomaster
IPorDNSofOldMaster
If old master is restored at some time in the future, make it a standby node:
1) On the current master, edit the config file to set:
PG_MASTER=
IPorDNSofNewMaster
PG_STANDBY=
IPorDNSofOldMaster
2) Enable replication on the new master:
Confidential and proprietary information of Apigee, Inc. Not to be disclosed except under nondisclosure agreement.
Apigee Edge Operations Guide
Page 78
> //apigee/apigeeservice/bin/apigeeservice apigeepostgresql
setupreplicationonmaster f
configFIle
3) On the old master, edit the config file to set:
PG_MASTER=
IPorDNSofNewMaster
PG_STANDBY=
IPorDNSofOldMaster
4) On the old master, clean out any old Postgres data:
> rm rf //apigee/data/apigeepostgresql/
Note
: If necessary, you can backup this data before deleting it.
5) Configure the old master as a standby:
> //apigee/apigeeservice/bin/apigeeservice apigeepostgresql
setupreplicationonstandby f
configFile
6) On completion of replication, verify the replication status by issuing the following scripts on both
servers. The system should display identical results on both servers to ensure a successful replication:
a. On the master node, run:
> //apigee/apigeeservice/bin/apigeeservice
apigeepostgresql postgrescheckmaster
Validate that it says it is the master.
b. On the standby node:
> //apigee/apigeeservice/bin/apigeeservice
apigeepostgresql postgrescheckstandby
Validate that it says it is the standby.
Customizing Edge Email Templates
Edge automatically sends emails in response to certain events. For each of these events, Edge defines a
default email template in
//apigee/edgeui/emailtemplates
. To customize these
emails, you can edit the default templates.
Note
: These events are triggered when modifying users in the Edge management UI. If you use a script to add
or modify a user, no email is sent.
The events where an email is sent, and the default template file for the generated email, are:
Confidential and proprietary information of Apigee, Inc. Not to be disclosed except under nondisclosure agreement.
Apigee Edge Operations Guide
●
New user is added:
useraddednew.html
●
Existing user requests a password reset:
passwordreset.html
●
A user is added to an organization: u
seraddedexisting.html
Page 79
Note:
The next installation of Edge overwrites these files, so make sure to backup any customizations that you
make.
The "From" field of the email can be customized by setting the
conf_apigee_apigee.mgmt.mailfrom
property in
//apigee/customer/application/ui.properties
(if that file does not
exist, create it). For example:
conf_apigee_apigee.mgmt.mailfrom="My Company "
The email subjects are customizable by editing the following properties in
//apigee/customer/application/ui.properties
(if that file does not exist, create it):
●
conf_apigeebase_apigee.emails.passwordreset.subject
●
conf_apigeebase_apigee.emails.useraddedexisting.subject
●
conf_apigeebase_apigee.emails.useraddednew.subject
Several email properties reference the
{companyNameShort}
placeholder, which defaults to a value of
"Apigee". You can set the value of the placeholder by using the
conf_apigee_apigee.branding.companynameshort
property in
ui.properties
. For example:
conf_apigee_apigee.branding.companynameshort="My Company"
After setting any properties in
//apigee/customer/application/ui.properties
, you
must restart the Edge UI:
> //apigee/apigeeservice/bin/apigeeservice edgeui restart
Configuring the Edge SMTP server
An SMTP server allows the Edge UI to send emails. For example, the Edge UI can send an email to assist a
user in recovering their UI password.
At install time, you can specify the SMTP information. To change the SMTP information, or if you deferred
SMTP configuration at the time of installation, you can use the a
pigeesetup
utility to modify the SMTP
configuration.
You can change any or all of the following information:
●
SMTP host, such as
smtp.gmail.com
●
SMTP port, such as 465 if you are using SSL
●
SMTP username and password
To update the SMTP information:
Confidential and proprietary information of Apigee, Inc. Not to be disclosed except under nondisclosure agreement.
Apigee Edge Operations Guide
Page 80
1.Edit the configuration file that you used to install Edge, or create a new configuration file with the
following information:
SKIP_SMTP=n
SMTPHOST=smtp.example.com
SMTPUSER=smtp@example.com # 0 for no username
SMTPPASSWORD=smtppwd
# 0 for no password
SMTPSSL=n
SMTPPORT=25
2. Run the
apigeesetup
utility on all the Edge UI nodes to update the SMTP settings:
> //apigee/apigeesetup/bin/setup.sh p ui f
configFile
The
apigeesetup
utility restarts the Edge UI.
Configuring SMTP for the Apigee BaaS SMTP Server
Apigee BaaS requires that you configure an SMTP server. When you install the Apigee BaaS API Backend
Stack, you enter the SMTP information, including the password of the SMTP user. That password is then
encrypted before it is stored.
If you later want to change the SMTP information, edit
//apigee/customer/application/usergrid.properties
on all BaaS Stack nodes
.
To encrypted a new password so you can set it in
usergrid.properties
, use the
apigeeservice
utility:
> //apigee/apigeeservice/bin/apigeeservice baasusergrid
newPword
To change SMTP information:
1. Open
//apigee/customer/application/usergrid.properties
in an editor. Create this file
if it does not exist.
2. Set the following properties as necessary:
# SMTP Properties
usergriddeployment_mail.smtp.host=smtp.gmail.com
usergriddeployment_mail.smtp.port=465
usergriddeployment_mail.smtp.auth=true
usergriddeployment_mail.smtp.username=your@email.com
usergriddeployment_mail.smtp.password=SECURE:74c57edacd3242f0ba1b1413890e17c22a5
usergriddeployment_mail.smtp.quitwait=false
# SMTPS Properties
usergriddeployment_mail.smtps.host=smtp.gmail.com
usergriddeployment_mail.smtps.port=465
usergriddeployment_mail.smtps.auth=true
usergriddeployment_mail.smtps.username=your@email.com
Confidential and proprietary information of Apigee, Inc. Not to be disclosed except under nondisclosure agreement.
Apigee Edge Operations Guide
Page 81
usergriddeployment_mail.smtps.password=SECURE:74c57edacd3242f0ba1b1413890e17c22a52
usergriddeployment_mail.smtps.quitwait=false
3. After editing this information, you must restart the API Backend Stack by using the command:
> //apigee/apigeeservice/bin/apigeeservice baasusergrid
restart
4. Repeat on all API BaaS Stack nodes.
Modifying Java Settings
Depending on your traffic and processing requirements you may need to increase the heap size for one or
more Apigee components.
To change the heap settings, edit the properties file for the component. If the component is installed on
multiple machines, such as the Edge Router, then edit the properties file on all machines hosting the
component.
To set these values, set the following properties:
●
bin_setenv_min_mem
set the minimum heap size. The default is 256 MB.
●
bin_setenv_max_mem
set the maximum heap size. The default is 512 MB.
●
bin_setenv_max_permsize
set the maximum permgen size. The default is 128 MB. On the
Message Processor, Apigee recommends that you set this value to 256 MB or 512 MB, depending on
your traffic.
Set these properties for each component on the machine. For example, for the Router, set them in the
//apigee/customer/application/router.properties
file. For the Message
Processor, set them in the
//apigee/customer/application/messageprocessor.properties
file.
After setting the values, restart the component:
> //apigee/apigeeservice/bin/apigeeservice
comprestart
For example:
> //apigee/apigeeservice/bin/apigeeservice edgerouter restart
Setting HTTP request/response header limits
The Edge Router and Message Processor have predefined limits to the size of request/response headers and
to the line size.
For the Router, which handles incoming requests from your APIs, edit the following properties in
//apigee/customer/application/
router.properties
to change these default values:
Confidential and proprietary information of Apigee, Inc. Not to be disclosed except under nondisclosure agreement.
Apigee Edge Operations Guide
Page 82
conf_router_HTTP.request.line.limit=4k
conf_router_HTTP.request.header.limit =8k
conf_router_HTTP.response.line.limit=4k
conf_router_HTTP.response.header.limit =8k
If that file does not exist, create it.
You must restart the Router after changing these properties:
> //apigee/apigeeservice/bin/apigeeservice edgerouter restart
For the Message Processor, which handles outgoing requests to your backend services, edit the following
properties in
//apigee/customer/application/messageprocessor
.properties
to
change these default values:
conf/http.properties+HTTPRequest.line.limit=7k
conf/http.properties+HTTPRequest.headers.limit=25k
conf/http.properties+HTTPResponse.line.limit=2k
conf/http.properties+HTTPResponse.headers.limit=25k
Note
: The syntax is slightly different for the Message Processor because the properties are commented out by
default.
If that file does not exist, create it.
You must restart the Message Processor after changing these properties:
> //apigee/bin/apigeeservice messageprocessor restart
Setting the URL of the Developer Services portal
Apigee provides you with a Developer Services portal that you can use to build and launch your own
customized website to provide all of these services to your development community. Edge customers can
create their own developer portal, either in the cloud or onprem. See
What is a developer portal?
for more
information.
The Edge UI displays the
DevPortal
button on the
Publish > Developers
page that, when clicked, opens the
portal associated with an organization. By default, that button opens the following URL:
http://live{orgname).devportal.apigee.com
where
{orgname}
is the name of the organization.
You can set this URL to a different URL, for example if your portal has a DNS record, or disable the button
completely. Use the following properties of the organization to control the button:
●
features.devportalDisabled
: Set to false (default) to enable the button and to true to disable it.
●
f
eatures.devportalUrl
: Set to the URL of the developer portal.
You set these properties separately for each organization. To set these properties, you first use the following
API call to determine the current property settings on the organization:
Confidential and proprietary information of Apigee, Inc. Not to be disclosed except under nondisclosure agreement.
Apigee Edge Operations Guide
Page 83
curl H "ContentType:application/json" \
u
adminEmail:pwordX GET \
http://:8080/v1/organizations/{
orgname
}
This call returns an object describing the organization in the form:
{
"createdAt" : 1428676711119,
"createdBy" : "me@my.com",
"displayName" : "orgname",
"environments" : [ "prod" ],
"lastModifiedAt" : 1428692717222,
"lastModifiedBy" : "me@my.com",
"name" : "organme",
"properties" : {
"property" : [{
"name" : "foo",
"value" : "bar"}]
}
,
"type" : "paid"
}
Note any existing properties in the
properties
area of the object. When you set properties on the
organization, the value in
properties
overwrites any current properties. Therefore, if you want to set
features.devportalDisabled
or
features.devportalUrl
in the organization, make sure you copy
any existing properties when you set them.
Use the following PUT call to set
properties
on the organization:
curl H "ContentType:application/json" \
u
adminEmail:pwordX PUT \
http://:8080/v1/organizations/{
orgname
}\
d '{
"displayName" : "orgname",
"name" : "orgname",
"properties" : {
"property" : [ {
"name" : "foo",
"value" : "bar"},
{
"name": "features.devportalUrl",
"value": http://devorgname.devportal.apigee.com/},
{
"name": "features.devportalDisabled",
"value": "false"}]
}
}'
Confidential and proprietary information of Apigee, Inc. Not to be disclosed except under nondisclosure agreement.
Apigee Edge Operations Guide
Page 84
In the PUT call, you only have to specify
displayName
,
name
, and p
roperties
. Note that this call incudes
the "foo" property that was originally set on the organization.
Allowing the Trace Tool Access to Local IP Addresses
The Trace tool in the Edge UI has the ability to send and receive API request to any specified URL. In certain
deployment scenarios where Edge components are cohosted with other internal services, a malicious user
may misuse the power of the Trace tool.
The
conf_apigeebase_apigee.feature.enabletraceforinternaladdresses
property is
disabled by default to prevent the Trace tool from sending requests to the following private IP addresses:
●
Loopback address (127.0.0.1 or localhost)
●
SiteLocal Addresses (For IPv4 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16)
●
Any Local Address (any address resolving to localhost).
If the Apigee Routers are reachable only over the above private IP ranges, Apigee recommends that you set
the
conf_apigeebase_apigee.feature.enabletraceforinternaladdresses
property to true.
To set the property to true:
1. Open the
ui.properties
file in an editor. If the file does not exist, create it.
> vi //apigee/customer/application/ui.properties
2. Set the following property to true:
conf_apigeebase_apigee.feature.enabletraceforinternaladdresses ="true"
3. Save your changes to
ui.properties
.
4. Restart the Edge UI:
> //apigee/apigeeservice/bin/apigeeservice edgeui restart
You can now access local IP addresses in the Trace tool.
Replacing the Edge license file
If your license expires, use the following procedure to replace it:
1. Overwrite the existing license file with the new license file:
> cp //apigee/customer/conf/license.txt
2. Change ownership of the new license file to the "apigee" user:
Confidential and proprietary information of Apigee, Inc. Not to be disclosed except under nondisclosure agreement.
Apigee Edge Operations Guide
Page 85
> chown apigee:apigee //apigee/customer/conf/license.txt
Specify a different user if you are running Edge as a user other than "apigee".
3. Restart the Edge Management Server:
> //apigee/apigeeservice/bin/apigeeservice
edgemanagementserver restart
Allow custom reports longer than 31 days in the Edge UI
By default, the Edge UI only lets you create custom reports for a maximum of 31 days.
To override this default:
1. Open the
ui.properties
file in an editor. If the file does not exist, create it.
> vi //apigee/customer/application/ui.properties
2. Set the following property to true:
conf_apigeebase_apigee.feature.enableforcerangelimit="true"
3. Save your changes to
ui.properties
.
4. Restart the Edge UI:
> //apigee/apigeeservice/bin/apigeeservice edgeui restart
Configuring the Router to retry connections to a Message Processor
The Router makes a health check to the Message Processor every five seconds to determine if the Message
Processor is able to service requests. If a Message Processor goes down, the Router automatically forwards
requests to another Message Processor.
You can configure how the Router reacts when the Message Processor goes down by setting the
conf_load_balancing_load.balancing.driver.nginx.server.retry
property on the Router.
That property takes a spacedelimited set of values that can include:
●
off
: Disable retry, the Router returns a failure code upon a request.
●
http_599
: (Default) If the Router receives an HTTP 599 response from the Message Processor, the
Router forwards the request to the next Message Processor.
HTTP 599 is a special response code that is generated by a Message Processor when it is being
shutdown. The Message Processor tries to complete all existing requests, but for any new requests it
responds with HTTP 599 to signal to the Router to retry the request on the next Message Processor.
Confidential and proprietary information of Apigee, Inc. Not to be disclosed except under nondisclosure agreement.
Apigee Edge Operations Guide
Page 86
●
error
: If an error occurred while establishing a connection with the Message Processor, passing a
request to it, or reading the response header from it, the Router forwards the request to the next
Message Processor.
●
timeout
: If a timeout occurs while establishing a connection with the Message Processor, passing a
request to it, or reading the response header from it, the Router forwards the request to the next
Message Processor.
●
invalid_header
: If the Message Processor returned an empty or invalid response, the Router
forwards the request to the next Message Processor.
●
http_
XXX
: If the Message Processor returned a response with HTTP code
XXX,the Router forwards
the request to the next Message Processor.
To configure the Router:
1. Edit the
//apigee/customer/application/router.properties
file (if the file
does not exist, create it).
2. Set the
conf_load_balancing_load.balancing.driver.nginx.server.retry
property.
conf_load_balancing_load.balancing.driver.nginx.server.retry
=http_599 error
3. Restart the Router:
> //apigee/apigeeservice/bin/apigeeservice edgerouter
restart
Setting log file location
By default, the log files for an Edge component are written to the
//apigee/var/log/
componentName
directory. Use the following procedure to change the
default location for all Edge components except the Edge UI:
1. Create the following file:
//apigee/etc/
componentName
.d/APIGEE_APP_LOGDIR.sh
2. Add the following property to the file:
APIGEE_APP_LOGDIR=
/foo/bar
where
/foo/bar
specifies the directory for the log files.
3. Restart the component:
> //apigee/apigeeservice/bin/apigeeservice
compNamerestart
Confidential and proprietary information of Apigee, Inc. Not to be disclosed except under nondisclosure agreement.
Apigee Edge Operations Guide
Page 87
Set the expiration time for user activation links in activation emails
When a user registers a new account, or requests to reset a password, they receive an email that contain an
activation link. By default, that activation link expires after 600 seconds, or ten minutes.
You can configre the exiration time by setting the
conf_apigee_apigee.forgotpassword.emaillinkexpiryseconds
token in the
ui.properties
file.
To set the expiry time:
1. On the Edge UI node, edit
//apigee/customer/application/ui.properties
. If that file does not exist,
create it.
2. Add the following property to the file to set the expiry time in seconds:
conf_apigee_apigee.forgotpassword.emaillinkexpiryseconds=
timeInSeconds
3. Restart the Edge UI:
> //apigee/apigeeservice/bin/apigeeservice edgeui restart
Enable access to OAuth 2.0 tokens by user ID and app ID
This section describes how to enable retrieval and revocation of OAuth 2.0 access tokens by end user ID, app
ID, or both.
App IDs are automatically added to an OAuth access token. Therefore, after you use the procedure below to
enable token access for an organization, you can access tokens by app ID.
To retrieve and revoke OAuth 2.0 access tokens by end user ID, an end user ID must be present in the access
token. The procedure below describes how add an end user ID to an existing token or to new tokens.
By default, when Edge generates an OAuth 2.0 access token, the token has the format:
{
"issued_at" : "1421847736581",
"application_name" : "a68d01f8b15c4be3b800ceae8c456f5a",
"scope" : "READ",
"status" : "approved",
"api_product_list" : "[PremiumWeatherAPI]",
"expires_in" : "3599",
"developer.email" : "tesla@weathersample.com",
"organization_id" : "0",
"token_type" : "BearerToken",
"client_id" : "k3nJyFJIA3p62DWOkLO6OJNi87GYXFmP",
Confidential and proprietary information of Apigee, Inc. Not to be disclosed except under nondisclosure agreement.
Apigee Edge Operations Guide
Page 88
"access_token" : "7S22UqXGJDTuUADGzJzjXzXSaGJL",
"organization_name" : "myorg",
"refresh_token_expires_in" : "0",
"refresh_count" : "0"
}
Note the following:
●
The
application_name
field contains the UUID of the app associated with the token. If you enable
retrieval and revocation of OAuth 2.0 access tokens by app ID, this is the app ID you use.
●
The
access_token
field contains the OAuth 2.0 access token value.
To enable retrieval and revocation of OAuth 2.0 access tokens by end user ID, configure the OAuth 2.0 policy
to include the user ID in the token, as described in the procedure below.
The end user ID is the string that Edge uses as the developer ID, not the developer's email address. You can
determine the developer's ID from the developer's email address by using the
Get Developer API
call.
After you configure Edge to include the end user ID in the token, it is included as the
app_enduser
field, as
shown below:
{
"issued_at" : "1421847736581",
"application_name" : "a68d01f8b15c4be3b800ceae8c456f5a",
"scope" : "READ",
"app_enduser" : "6ZG094fgnjNf02EK",
"status" : "approved",
"api_product_list" : "[PremiumWeatherAPI]",
"expires_in" : "3599",
"developer.email" : "tesla@weathersample.com",
"organization_id" : "0",
"token_type" : "BearerToken",
"client_id" : "k3nJyFJIA3p62DWOkLO6OJNi87GYXFmP",
"access_token" : "7S22UqXGJDTuUADGzJzjXzXSaGJL",
"organization_name" : "myorg",
"refresh_token_expires_in" : "0",
"refresh_count" : "0"
}
APIs to retrieve and revoke OAuth 2.0 access tokens by user ID and app ID
Use the following APIs to access OAuth tokens by user ID, app ID, or both:
●
Get OAuth 2.0 Access Token by End User ID or App ID
●
Revoke OAuth 2.0 Access Token by End User ID or App ID
Confidential and proprietary information of Apigee, Inc. Not to be disclosed except under nondisclosure agreement.
Apigee Edge Operations Guide
Page 89
Procedure for enabling token access
Use the following procedure to enable retrieval and revocation of OAuth 2.0 access tokens by end user ID and
app ID.
Step 1: Enable token access support for an organization
You must enable token access for each organization separately. Call the PUT API below for each organization
on which you want to enable the retrieval and revocation of OAuth 2.0 access tokens by end user ID or app ID.
The user making the following call must be in the role
orgadmin
or o
psadmin
for the organization. Replace
the values in
{curly braces}
with your orgspecific values:
> curl H "Contenttype:text/xml" X POST \
https://:8080/v1/organizations/{
org_name
}\
d '
true
true
' \
u {userEmail}:{mypassword}
Step 2: Set permissions for opsadmin role in the organization
Only the
orgadmin
and
opsadmin
roles in an organization should be given permissions to retrieve (HTTP
GET) and revoke (HTTP PUT) OAuth 2.0 tokens based on user ID or app ID. To control access, set get and
put permissions on the
/oauth2
resource for an organization. That resource has a URL in the form:
https://:8080/v1/organizations/{org_name}/oauth2
The
orgadmin
role should already have the necessary permissions. For the o
psadmin
role for the
/oauth2
resource, the permissions should look like this:
get
put
You can use the
Get Permission for a Single Resource
API call to see which roles have permissions for the
/oauth2
resource.
Based on the response, you can use the
Add Permissions for Resource to a Role
and
Delete Permission for
Resource
API calls to make any necessary adjustments to the /oauth2 resource permissions.
Use the following cURL command to give the
opsadmin
role
get
and
put
permissions for the
/oauth2
resource. Replace the values in {
curly braces
} with your orgspecific values:
Confidential and proprietary information of Apigee, Inc. Not to be disclosed except under nondisclosure agreement.
Apigee Edge Operations Guide
Page 90
> curl X POST H 'Contenttype:application/xml' \
http://:8080/v1/organizations/{org}/userroles/opsadmin/permissions \
d '
get
put
' \
u {USEREMAIL}:{PWD}
Use the following cURL command to revoke
get
and
put
permissions for the /
oauth2
resource from roles
other than
orgadmin
and
opsadmin
. Replace the values in {
curly braces
} with your orgspecific values:
> curl X DELETE H 'Contenttype:application/xml' \
http://:8080/v1/organizations/{orgname}/userroles/{roles}/permissions \
d '
' \
u {USEREMAIL}:{PWD}
Step 3: Set the oauth_max_search_limit property
Ensure that the
conf_keymanagement_oauth_max_search_limit
property in
customer/application/managementserver.properties
file is set to 100:
conf_keymanagement_oauth_max_search_limit = 100
If this file does not exist, create it.
This property sets the page size used when fetching tokens. Apigee recommends a value of 100, but you can
set it as you see fit.
On a new installation, the property should be already set to 100. If you have to change the value of this
property, restart the Management Server and Message Processor by using the commands:
> //apigee/apigeeservice/bin/apigeeservice edgemanagementserver
restart
> //apigee/apigeeservice/bin/apigeeservice edgemessageprocessor
restart
Step 4: Configure the OAuth 2.0 policy that generates tokens to include end user ID
Note
: This task is optional. You only need to perform it if you want to retrieve and revoke OAuth 2.0 access
tokens by end user ID.
Configure the OAuth 2.0 policy used to generate access tokens to include the end user ID in the token. By
including end user IDs in the access token, you can retrieve and revoke tokens by ID.
To configure the policy to include an end user ID in an access token, the request that creates the access token
must include the end user ID and you must specify the input variable that contains the end user ID.
Confidential and proprietary information of Apigee, Inc. Not to be disclosed except under nondisclosure agreement.
Apigee Edge Operations Guide
Page 91
The OAuth 2.0 policy below, named GenerateAccessTokenClient, generates an OAuth 2.0 access token. Note
the addition of the
tag in bold that specifies the variable containing the end user ID:
OAuth 2.0.0 1
false
GenerateAccessToken
client_credentials
request.queryparam.grant_type
request.header.appuserID 960000
You can then use the following cURL command to generate the OAuth 2.0 access token, passing the user ID
as the
appuserID
header:
> curl H "appuserID:6ZG094fgnjNf02EK" \
https://myorgtest.apigee.net/oauth/client_credential/accesstoken?grant_type=client_credentials \
X POST \
d 'client_id=k3nJyFJIA3p62TKIkLO6OJNXFmP&client_secret=gk5K5lIp943AY4'
In this example, the
appuserID
is passed as a request header. You can pass information as part of a request
in many ways. For example, as an alternative, you can:
●
Use a form parameter variable: r
equest.formparam.appuserID
●
Use a flow variable providing the end user ID
Confidential and proprietary information of Apigee, Inc. Not to be disclosed except under nondisclosure agreement.
Apigee Edge Operations Guide
Page 92
Configuring SSL
Secure Socket Layer (SSL) is a best practice for ensuring secure, encrypted messaging across your API
environment, from apps to Apigee Edge to your backend services.
Regardless of the environment configuration for your management API—for example, whether you’re using a
proxy, a router, and/or a load balancer in front of your management API (or not)— Edge lets you enable and
configure SSL, giving you control over message encryption in your onpremise API management environment.
For an onpremises installation of Edge Private Cloud, there are several places where you can configure SSL:
1. Between a Router and Message Processor
2. For access to the Edge management API
3. For access to the Edge management UI
4. For access from an app to your APIs
5. For access from Edge to your backend services
Configuring SSL for the first three items is described below. All of these procedures assume that you have
created a JKS file containing your SSL certification and private key.
To configure SSL for access from an app to your APIs, #4 above, see C
reating a virtual host for an
onpremises Edge installation
. To configure SSL for access from Edge to your backend services, #5 above,
see
Configuring SSL from Edge to the backend service
.
For a complete overview of configuring SSL on Edge, see S
SL
.
Creating a JKS file
You represent the keystore as a JKS file, where the keystore contains your SSL certificate and private key.
There are several ways to create a JKS file, but one way is to use the
openssl
and
keytool
utilities.
Note
: If you have a certificate chain, all certs in the chain must be appended in order into a single PEM file,
where the last certificate is signed by a CA.
For example, you have a PEM file named s
erver.pem
containing your SSL certificate and a PEM file named
private_key.pem
containing your private key. Use the following commands to create the PKCS12 file:
> openssl pkcs12 export clcerts in server.pem inkey private_key.pem out
keystore.pkcs12
You have to enter the passphrase for the key, if it has one, and an export password. This command creates a
PKCS12 file named
keystore.pkcs12
.
Use the following command to convert it to a JKS file named
keystore.jks
:
> keytool importkeystore srckeystore keystore.pkcs12 srcstoretype pkcs12
destkeystore keystore.jks deststoretype jks
You are prompted to enter the new password for the JKS file, and the existing password for the PKCS12 file.
Confidential and proprietary information of Apigee, Inc. Not to be disclosed except under nondisclosure agreement.
Apigee Edge Operations Guide
Page 93
Generating an obfuscated password
Some parts of the Edge SSL configuration procedure require you to enter an obfuscated password in a
configuration file. An obfuscated password is a more secure alternative to entering your password in plain text.
You can generate an obfuscated password in Java by using the Jetty .jar files installed with Edge. enerate the
obfuscated password by using a command in the form:
> java cp //apigee/edgegateway/lib/thirdparty/jettyhttp
x.y.z
.jar://apigee/edgegateway/lib/thirdparty/jettyutilx.y.z
.jar
org.eclipse.jetty.http.security.Password
yourPassword
where
x.y.z
specifies the version number of the Jetty .jar files, such as 8.0.4.v20111024. This command
returns the password in the form:
yourPassword
OBF:58fh40h61svy156789gk1saj
MD5:902fobg9d80e6043b394cb2314e9c6
Use the obfuscated password specified by O
BF
when configuring SSL.
For more information, see this
article
.
Configuring SSL between a Router and a Message Processor
By default, SSL between the Router and Message Processor is disabled.
Note
: Port 8082 on the Message Processor has to be open for access by the Router to perform health checks
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.
Use the following procedure to enable SSL encryption between a Router and the Message Processor:
1. Ensure that port 8082 on the Message Processor is accessible by the Router.
2. Generate the keystore JKS file containing your SSL certification and private key. For more, see
Creating a JKS file
.
3. Copy the keystore JKS file to the
/tmp
directory on the Message Processor server.
4. Change permissions and ownership of the JKS file:
> chown apigee:apigee /tmp/
keystore
.jks
> chmod 600 /tmp/
keystore
.jks
where
keystore
.jks
is the name of your keystore file.
Confidential and proprietary information of Apigee, Inc. Not to be disclosed except under nondisclosure agreement.
Apigee Edge Operations Guide
Page 94
5. Edit the file
//apigee/customer/application/messageprocessor.properties
. If the
file does not exist, create it.
6. Set the following properties in the
messageprocessor.properties
file:
conf_messageprocessorcommunication_local.http.ssl=true
conf_messageprocessorcommunication+local.http.port=8443
conf_messageprocessorcommunication+local.http.ssl.keystore.type=jks
conf_messageprocessorcommunication+local.http.ssl.keystore.path=/tmp/
keyStore.jks
conf_messageprocessorcommunication+local.http.ssl.keyalias=apigeedevtest
# Enter the obfuscated keystore password below.
conf_messageprocessorcommunication+local.http.ssl.keystore.password=OBF:
obsPword
where
keyStore.jks
is your keystore file, and o
bsPword i
s your obfuscated keystore and keyalias
password. See
Generating an obfuscated password
for information on generating an obfuscated
password.
7. Stop the MessageProcessors and Routers:
//apigee/apigeeservice/bin/apigeeservice
edgemessageprocessor stop
//apigee/apigeeservice/bin/apigeeservice edgerouter stop
8. On the Router, delete any files in /opt/nginx/conf.d:
> rm f /opt/nginx/conf.d/*
9. Start the MessageProcessors and Routers:
//apigee/apigeeservice/bin/apigeeservice
edgemessageprocessor start
//apigee/apigeeservice/bin/apigeeservice edgerouter start
10. Repeat for any additional Message Processors.
The following table lists all of the available properties in m
essageprocessor.properties
:
Properties
Description
conf_messageprocessorcommunication_local.http.host=
Optional. Hostname to listen on for router
connections. This will override the host
name configured at registration.
Confidential and proprietary information of Apigee, Inc. Not to be disclosed except under nondisclosure agreement.
Apigee Edge Operations Guide
Page 95
conf_messageprocessorcommunication_local.http.port=8998
Optional. Port to listen on for router
connections. Default is 8998.
conf_messageprocessorcommunication_local.http.ssl=
Set this to true to enable SSL. Default is
false. When SSL is enabled, you must set
local.http.ssl.keystore.path and
local.http.ssl.keyalias.
conf_messageprocessorcommunication_local.http.ssl.keystore.path=
Local file system path to the keystore (JKS
or PKCS12). Mandatory when
local.http.ssl=true.
conf_messageprocessorcommunication_local.http.ssl.keyalias=
Key alias from the keystore to be used for
SSL connections. Mandatory when
local.http.ssl=true.
conf_messageprocessorcommunication_local.http.ssl.
keyalias.password=
Password used for encrypting the key
inside the keystore. Use an obfuscated
password in this format: OBF:xxxxxxxxxx
conf_messageprocessorcommunication_local.http.ssl.keystore.type=jks
Keystore type. Only JKS and PKCS12 are
currently supported. Default is JKS.
conf_messageprocessorcommunication_local.http.ssl.
keystore.password=
Optional. Obfuscated password for the
keystore. Use an obfuscated password in
this format: OBF:xxxxxxxxxx
conf_messageprocessorcommunication_local.http.ssl.ciphers=
Optional. When configured, only the
ciphers listed are allowed. If omitted, use
all ciphers supported by the JDK.
Configuring SSL for the management API
By default, SSL is disabled for the management API and you access the Edge management API over HTTP by
using the IP address of the Management Server node and port 8080. For example:
http://ms_IP:8080
Alternatively, you can configure SSL access to the management API so that you can access it in the form:
https://ms_IP:8443
Confidential and proprietary information of Apigee, Inc. Not to be disclosed except under nondisclosure agreement.
Apigee Edge Operations Guide
Page 96
In this example, you configure SSL access to use port 8443. However, that port number is not required by
Edge you can configure the Management Server to use other port values. The only requirement is that your
firewall allows traffic over the specified port.
To ensure traffic encryption to and from your management API, configure the settings in the
//apigee/customer/application/managementserver.properties
file.
In addition to SSL configuration, you can also control password validation (password length and strength) by
modifying the
managementserver.properties
file.
Note:
After modifying these files, restart your management API service.
Ensure that your SSL port is open
The procedure in this section configures SSL to use port 8443 on the Management Server. Regardless of the
port that you use, you must ensure that the port is open on the Management Server. For example, you can use
the following command to open it:
$ iptables A INPUT m state state NEW m tcp p tcp dport 8443 j ACCEPT
verbose
Configure SSL
Edit the
//apigee/customer/application/managementserver.properties
file
to control SSL use on traffic to and from your management API. If this file does not exist, create it.
Use the following procedure to configure SSL access to the management UI:
1. Generate the keystore JKS file containing your SSL certification and private key. For more see C
reating
a JKS file.
2. Copy the keystore JKS file to a directory on the Management Server node, such as /tmp.
3. Change ownership of the JKS file to
apigee
:
$ chown apigee:apigee
keystore.jks
where
keystore
.jks
is the name of your keystore file.
4. Edit
//apigee/customer/application/managementserver.properties
to set the following properties. If that file does not exist, create it:
conf_webserver_ssl.enabled=true
# Set next to true if all communications should be over HTTPS.
# Not recommended because many Edge internal calls use HTTP.
conf_webserver_http.turn.off=false
conf_webserver_ssl.port=8443
conf_webserver_keystore.path=/tmp/
keystore.jks
# Enter the obfuscated keystore password below.
Confidential and proprietary information of Apigee, Inc. Not to be disclosed except under nondisclosure agreement.
Apigee Edge Operations Guide
Page 97
conf_webserver_keystore.password=OBF:
obfuscatedPassword
conf_webserver_cert.alias=apigeedevtest
where
keyStore.jks
is your keystore file, and o
bfuscatedPassword i
s your obfuscated keystore
password. See
Generating an obfuscated password f
or information on generating an obfuscated
password.
5. Restart the Edge Management Server by using the commands:
$ //apigee/apigeeservice/bin/apigeeservice edgemanagementserver
restart
The management API now supports access over SSL.
The following table lists all of the SSL properties that you can set in
managementserver.properties
:
Properties
Description
conf_webserver_http.port=8080
Default is 8080.
conf_webserver_ssl.enabled=false
To enable/disable SSL. With SSL enabled
(true), you must also set the ssl.port and
keystore.path properties.
conf_webserver_http.turn.off=true
To enable/disable http along with https. If you
want to use only HTTPS, leave the default value
to true.
conf_webserver_ssl.port=8443
These are mandatory when SSL is enabled
(ssl.enabled=true)
conf_webserver_keystore.path=
Modify the SSL port to match your server’s SSL
port, and provide the path to your keystore file.
conf_webserver_keystore.password=
Use an obfuscated password in this format:
OBF:xxxxxxxxxx
conf_webserver_cert.alias=
Optional keystore certificate alias
conf_webserver_keymanager.password=
If your key manager has a password, enter an
obfuscated version of the password in this
format: OBF:xxxxxxxxxx
Confidential and proprietary information of Apigee, Inc. Not to be disclosed except under nondisclosure agreement.
Apigee Edge Operations Guide
conf_webserver_trust.all=
conf_webserver_trust.store.path=
conf_webserver_trust.store.password=
conf_webserver_exclude.cipher.suites=
conf_webserver_include.cipher.suites=
Page 98
Configure settings for your trust store.
Determine whether you want to accept all SSL
certificates (for example, to accept
nonstandard types). The default is false.
Provide the path to your trust store, and enter
an obfuscated trust store password in this
format: OBF:xxxxxxxxxx
Indicate any cipher suites you want to include or
exclude. For example, if you discover
vulnerability in a cipher, you can exclude it here.
Separate multiple ciphers with a space.
For information on cypher suites and
cryptography architecture, see:
http://docs.oracle.com/javase/8/docs/technotes/
guides/security/SunProviders.html#SunJSSE
c
onf_webserver_ssl.session.cache.size=
conf_webserver_ssl.session.timeout=
Integers that determine:
● The SSL session cache size (in bytes)
for storing session information for
multiple clients.
● The amount of time SSL sessions can
last before they time out (in
milliseconds).
Configuring SSL for the management UI
By default, you access the Edge management UI over HTTP by using the IP address of the Management
Server node and port 9000. For example:
http://ms_IP:9000
Alternatively, you can configure SSL access to the management UI so that you can access it in the form:
https://ms_IP:9443
In this example, you configure SSL access to use port 9443. However, that port number is not required by
Edge you can configure the Management Server to use other port values. The only requirement is that your
firewall allows traffic over the specified port.
Confidential and proprietary information of Apigee, Inc. Not to be disclosed except under nondisclosure agreement.
Apigee Edge Operations Guide
Page 99
Ensure that your SSL port is open
The procedure in this section configures SSL to use port 9443 on the Management Server. Regardless of the
port that you use, you must ensure that the port is open on the Management Server. For example, you can use
the following command to open it:
$ iptables A INPUT m state state NEW m tcp p tcp dport 9443 j ACCEPT
verbose
Configure SSL
Use the following procedure to configure SSL access to the management UI:
1. Generate the keystore JKS file containing your SSL certification and private key and copy it to the
Management Server node. For more information, see Creating a JKS file.
2. Run the following command to configure SSL:
$ ///apigee/apigeeservice/bin/apigeeservice
edgeui configuressl
3. Enter the HTTPS port number, for example, 9443.
4. Specify if you want to disable HTTP access to the management UI. By default, the management UI is
accessible over HTTP on port 9000.
5. Enter the keystore algorithm. The default is JKS.
6. Enter the absolute path to the keystore JKS file.
The script copies the file to the
//apigee/customer/conf
directory on the
Management Server node, and changes the ownership of the file to a
pigee
.
7. Enter the keystore password.
8. The script then restarts the Edge management UI. After the restart, the management UI supports
access over SSL.
Confidential and proprietary information of Apigee, Inc. Not to be disclosed except under nondisclosure agreement.
Apigee Edge Operations Guide
Page 100
Recurring Edge Services Maintenance Tasks
In order to ensure optimal daytoday operation of the Apigee system, certain tasks should be performed when
the system is originally installed and/or on a periodic basis.
Maintenance Tool Set
The following tools are used to communicate with, or maintain various components of, the Apigee system. The
variable $APROOT refers to the directory in which the Apigee system is installed.
Tool
Used For
System Location
nodetool
Apache Cassandra maintenance
//apigee/apigeecassandra/bin
cassandracli
Apache Cassandra command line
//apigee/apigeecassandra/bin
zkCli.sh
Apache ZooKeeper command line utility
//apigee/apigeezookeeper/bin
nc
Arbitrary TCP/IP and UDP commands; invocation
of ZooKeeper "fourletter commands"
/usr/bin/nc or another location dependent on your
operating system
In situations where the "
nc
" or "
telnet
" commands might be considered a security risk, the following Python
script can be used:
import time
import socket
import sys
if len(sys.argv) <> 4:
print "Usage: %s address port 4lettercmd" % sys.argv[0]
else:
c = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
c.connect((sys.argv[1], int(sys.argv[2])))
c.send(sys.argv[3])
time.sleep(0.1)
print c.recv(512)
Apache Cassandra Maintenance Tasks
AntiEntropy Maintenance
The Apache Cassandra ring nodes require periodic maintenance to ensure consistency across all nodes. To
perform this maintenance, use the Cassandra "
nodetool h localhost repair
" command.
Note:
This maintenance must be run on every Cassandra node at least every ten days in order to eliminate
problems related to Cassandra "forgotten deletes". Running "nodetool h localhost repair
"
Confidential and proprietary information of Apigee, Inc. Not to be disclosed except under nondisclosure agreement.
Apigee Edge Operations Guide
Page 101
imposes a significant load on the system, so Apigee recommends that this process only be run during periods
of relatively low workload.
In a singleregion or singledatacenter Apigee installation, use the command "nodetool h localhost
repair
" on one Cassandra node to ensure consistency across all nodes in the ring. In a multiregion or
multidatacenter Apigee installation, use "
nodetool h localhost repair pr
" on every node in the
ring (across all regions or data centers).
For more information on "forgotten deletes" and Cassandra consistency, and for instructions on how to use
"
nodetool
", see:
http://wiki.apache.org/cassandra/Operations Consistency
Important Note:
Apigee does not recommend adding, moving or removing Cassandra nodes without
contacting Apigee Customer Success. The Apigee system tracks Cassandra nodes using their IP address, and
performing ring maintenance without performing corresponding updates on the Apigee environment metadata
will cause undesirable results.
Log File Maintenance
Cassandra logs are stored in the
//apigee/var/log/cassandra
directory on each node.
By default, a maximum of 50 log files, each with a maximum size of 20 MB, can be created; once this limit is
reached older logs are deleted when newer logs are created.
If you should find that Cassandra log files are taking up excessive space, you can modify the amount of space
allocated for log files by editing the log4j settings.
1. Edit
//apigee/customer/application/cassandra.properties
to set the
following properties. If that file does not exist, create it:
conf_log4jserver_log4j.appender.r.maxfilesize=20MB # max file size
conf_log4jserver_log4j.appender.r.maxbackupindex=50 # max open files
2. Restart Cassandra by using the commands:
$ //apigee/apigeeservice/bin/apigeeservice apigeecassandra restart
Apache Zookeeper Maintenance Tasks
FourLetter Commands
Apache ZooKeeper has a number of "fourletter commands" that can be helpful in determining the current
status of ZooKeeper voter and observer nodes. These commands can be invoked using "
nc
", "
telnet
" or
another utility that has the ability to send commands to a specific port. Details on the fourletter commands
can be found at:
http://zookeeper.apache.org/doc/r3.1.2/zookeeperAdmin.html#sc_zkCommands
.
Confidential and proprietary information of Apigee, Inc. Not to be disclosed except under nondisclosure agreement.
Apigee Edge Operations Guide
Page 102
Removing Old Snapshot Files
Apache ZooKeeper also requires periodic maintenance to remove old snapshot files which accumulate as
updates to the system are made. Instructions on how to clean up old snapshots can be found at
http://zookeeper.apache.org/doc/r3.1.2/zookeeperAdmin.html#sc_maintenance
.
Log File Maintenance
Apache Zookeeper log files are kept in
//apigee/var/log/zookeeper
. Normally, log file
maintenance should not be required, but if you find that there are an excessive number of ZooKeeper logs or
that the logs are very large you can modify ZooKeeper’s log4j properties to set the maximum file size and file
count.
1. Edit
//apigee/customer/application/zookeeper.properties
to set the
following properties. If that file does not exist, create it:
conf_log4j_log4j.appender.rollingfile.maxfilesize=10MB # max file size
conf_log4j_log4j.appender.rollingfile.maxbackupindex=50 # max open files
2. Restart ZooKeeper by using the commands:
$ //apigee/apigeeservice/bin/apigeeservice apigeezookeeper restart
OpenLDAP Maintenance Tasks
OpenLDAP log files are contained in the directory
//apigee/var/log
.
These files can be
periodically archived and removed in order to ensure that they do not take up excessive disk space.
Information on maintaining, archiving and removing OpenLDAP logs can be found in Section 19.2 of the
OpenLDAP manual at
http://www.openldap.org/doc/admin24/maintenance.html
.
Confidential and proprietary information of Apigee, Inc. Not to be disclosed except under nondisclosure agreement.
Apigee Edge Operations Guide
Page 103
Recurring Analytics Services Maintenance Tasks
Many Apigee Analytics Services tasks can be performed using standard Postgres utilities. The routine
maintenance tasks you would perform on the Analytics database – such as database reorganization using
VACUUM, reindexing and log file maintenance are the same as those you would perform on any PostgreSQL
database. Information on routine Postgres maintenance can be found at
http://www.postgresql.org/docs/9.1/static/maintenance.html
.
Important Note:
Apigee does not recommend moving the PostgreSQL database without contacting Apigee
Customer Success. The Apigee system PostgreSQL database servers using their IP address, and moving the
database or changing its IP address without performing corresponding updates on the Apigee environment
metadata will cause undesirable results.
For more on maintaining PostgreSQL database, see
http://www.postgresql.org/docs/9.1/static/maintenance.html
.
Note
: No pruning is required for Cassandra. Expired tokens are automatically purged after 180 days.
Pruning Analytics Data
As the amount of analytics data available within the Apigee repository increases, you may find it desirable to
"prune" the data beyond your required retention interval. Run the following command to prune data for a
specific organization and environment:
> //apigee/apigeeservice/bin/apigeeservice apigeepostgresql
pgdatapurge
This command interrogates the "childfactables" table in the "analytics" schema to determine which raw data
partitions cover the dates for which data pruning is to be performed, then drops those tables. Once the tables
are dropped, the entries in "childfactables" related to those partitions are deleted.
Childfactables are dailypartitioned fact data. Every day new partitions are created and data gets ingested into
the daily partitioned tables. So at a later point in time, when the old fact data will not be required, you can
purge the respective childfactables.
Note:
If you have configured masterstandby replication between Postgres servers, then you only need to run
this script on the Postgres master.
Confidential and proprietary information of Apigee, Inc. Not to be disclosed except under nondisclosure agreement.
Apigee Edge Operations Guide
Page 104
Organization and Environment Maintenance
This section covers various administrative operations, for example, creation, management and removal of
Apigee organizations, environments and virtual hosts in an Apigee Edge for Private Cloud installation.
For an introduction to organizations, environments, and virtual hosts, see About Regions, Pods, Organizations,
Environments and Virtual Hosts.
Checking Status of Users, Organization and Environment
Management Server plays a vital role in holding all other components together in an onpremises installation of
Edge Private Cloud. You can check for user, organization and deployment status on the Management Server
by issuing the following CURL commands:
curl u : http://localhost:8080/v1/users
curl u : http://localhost:8080/v1/organizations
curl u :
http://localhost:8080/v1/organizations/<
orgname>
/deployments
The system should display 200 HTTP status for all calls. If these fail, do the following:
1. Check the Management Server logs (at
/apigee/var/log/apigee/managementserver
) for any errors.
2. Make a call against Management Server to check whether it is functioning properly.
3. Remove the server from the ELB and then restart the Management Server.
//apigee/bin/apigeeservice managementserver restart
About using config files
The commands shown below take a config file as input. For example, you pass a config file to the
setuporg
command to define all the properties of the organization, including the environment and virtual host.
For a complete config file, and information on the properties that you can set in the config file, see
http://docs.apigee.com/apiservices/content/onboardorganization
.
About setting up a virtual host
A virtual host on Edge defines the domains and Edge Router ports on which an API proxy is exposed, and, by
extension, the URL that apps use to access an API proxy. A virtual host also defines whether the API proxy is
accessed by using the HTTP protocol, or by the encrypted HTTPS protocol.
Use the scripts and API calls shown below to create a virtual host. When you create the virtual host, you must
specify the following information:
Confidential and proprietary information of Apigee, Inc. Not to be disclosed except under nondisclosure agreement.
Apigee Edge Operations Guide
Page 105
●
The name
of the virtual host that you use to reference it in your API proxies.
●
The port
on the Router for the virtual host. Typically these ports start at 9001 and increment by one for
every new virtual host.
●
The host alias
of the virtual host. Typically the DNS name of the virtual host.
The Edge Router compares the
Host
header of the incoming request to the list of host aliases as part
of determining the API proxy that handles the request. When making a request through a virtual host,
either specify a domain name that matches the host alias of a virtual host, or specify the IP address of
the Router and the
Host
header containing the host alias.
For example, if you created a virtual host with a host alias of
myapis.apigee.net
on port
9001
, then a cURL
request to an API through that virtual host could use one of the following forms:
●
If you have a DNS entry for m
yapis.apigee.net
:
curl http://
myapis.apigee.net:9001
/{proxybasepath}/{resourcepath}
●
If you do not have a DNS entry for m
yapis.apigee.net
:
curl http
://:9001
/{proxybasepath}/{resourcepath}
H 'Host: myapis.apigee.net'
In the second form, you specify the IP address of the Router, and pass the host alias in the H
ost
header.
Note
: The curl command, most browsers, and many other utilities automatically append the H
ost
header with the domain as part of the request, so you can actually use a curl command in the form:
curl http://:9001/{proxybasepath}/{resourcepath}
Options when you do not have a DNS entry for the virtual host
One option when you do not have a DNS entry is to set the host alias to the IP address of the Router and port
of the virtual host, as
:port
. For example:
192.168.1.31:9001
When you make a curl command in the form below:
curl http://:9001/{proxybasepath}/{resourcepath}
This option is preferred because it works well with the Edge UI.
If you have multiple Routers, add a host alias for each Router, specifying the IP address of each Router and
port of the virtual host.
Alternatively, you can set the host alias to a value, such as t
emp.hostalias.com
. Then, you have to pass the
host
header on every request:
Confidential and proprietary information of Apigee, Inc. Not to be disclosed except under nondisclosure agreement.
Apigee Edge Operations Guide
Page 106
curl v http://:9001/{proxybasepath}/{resourcepath}
H 'Host: temp.hostalias.com'
Or, add the host alias to your
/etc/hosts
file. For example, add this line to/etc/hosts
:
192.168.1.31
temp.hostalias.com
Then you can make a request as if you had a DNS entry:
curl v http://myapis.apigee.net:9001/{proxybasepath}/{resourcepath}
Creating an Organization, Environment, and Virtual Host
Before you create an API proxy on Apigee Edge, you must create at least one organization and, within each
organization, one or more environments and virtual hosts.
Typically, organizations and environments are created together. To simplify the process, use the
apigeeprovision
utility. Invoke it from the command line on the Edge Management Server:
> //apigee/apigeeservice/bin/apigeeservice apigeeprovision
setuporg f
configFile
The config file contains:
APIGEE_ADMINPW=adminPword # If omitted, you are prompted for it.
NEW_USER="y"
USER_NAME=orgAdmin@myCo.com
FIRST_NAME=foo
LAST_NAME=bar
USER_PWD="userPwrod"
ORG_NAME=example # lowercase only, no spaces, underscores, or periods.
ENV_NAME=prod
VHOST_PORT=9001
VHOST_NAME=default
VHOST_ALIAS="$IP1:9001"
# Optionally configure SSL for virtual host.
# VHOST_SSL=y
# Set to "y" to enable SSL on the virtual host.
# KEYSTORE_JAR= # JAR file containing the cert and private key.
# KEYSTORE_NAME= # Name of the keystore.
# KEYSTORE_ALIAS= # The key alias.
# KEY_PASSWORD= # The key password, if it has one.
# AXGROUP=axgroup001 # Default name is axgroup001
Note:
For SSL configuration, see
Keystores and Truststores
and C
onfiguring SSL access to an API for the
Private Cloud
for more information on creating the JAR file, and other aspects of configuring SSL.
The command then:
Confidential and proprietary information of Apigee, Inc. Not to be disclosed except under nondisclosure agreement.
Apigee Edge Operations Guide
●
Page 107
Create the organization
Note
: You cannot rename an organization after you create it.
●
Associate the organization with a pod, by default is associates it with the "gateway" pod
●
Add the specified user as the org admin. If the user does not exist, you can create one.
●
Create one or more environments
●
Create one or more virtual host for each environment
●
Associate the environment with all Message Processor(s)
●
Enable analytics
For a complete silent config file, see
http://docs.apigee.com/apiservices/content/onboardorganization
.
By default, the maximum length of the organization name and environment name is 20 characters when using
the
apigeeprovision
utility. This limit does not apply if you use the Edge API directly to create the
organization or environment.
Note:
Rather than using the
apigeeprovision
utility, you can use a set of additional scripts, or the Edge
API itself, to create and configure an organization. For example, use thee scripts to add an organization and
associate it with multiple pods. The following sections describe those scripts and APIs in more detail.
Create an Organization
Use the
createorg
command to create an organization:
> //apigee/apigeeservice/bin/apigeeservice apigeeprovision
createorg f
configFile
This script creates the organization, but does not add or configure the environments and virtual hosts required
by the organization to handle API calls.
Note
: You cannot rename an organization after you create it.
The config file contains the name of the org and the email address of the org admin. The characters you can
use in the name attribute are restricted to:
az09\$%.
Do not use spaces, periods or uppercase letters in
the name:
APIGEE_ADMINPW=adminPword # If omitted, you are prompted for it.
ORG_NAME=example # lowercase only, no spaces, underscores, or periods.
ORG_ADMIN=orgAdmin@myCo.com
The command then:
●
Creates the organization
●
Associates the organization with a pod, by default is associates it with the "gateway" pod
●
Adds the specified user as the org admin. The user must already exist; otherwise the script issues an
error.
Confidential and proprietary information of Apigee, Inc. Not to be disclosed except under nondisclosure agreement.
Apigee Edge Operations Guide
Page 108
Note:
You cannot create two organizations with the same name. In that case, the second create will fail, like
this:
organizations.OrganizationAlreadyExists
Organization : test already exists
Create an organization by using API calls
Alternatively, you can use the following API calls to create an org. The first call creates the org:
curl H "ContentType:application/xml" u : \
X POST http://:8080/v1/organizations \
d ': X POST \
http://:8080/v1/organizations//pods \
d "region=default&pod=gateway"
You can make this call multiple times to associate the organization with multiple pods.
The final call adds an existing user as the org admin for the org:
curl H "ContentType:application/xml" u : \
X POST \
http://:8080/v1/organizations//users//userroles/ \
d '/apigee/apigeeservice/bin/apigeeservice apigeeprovision
addenv f
configFile
This config file contain the information necessary to create the environment and virtual host:
Confidential and proprietary information of Apigee, Inc. Not to be disclosed except under nondisclosure agreement.
Apigee Edge Operations Guide
Page 109
APIGEE_ADMINPW=adminPword # If omitted, you are prompted for it.
ORG_NAME=example # lowercase only, no spaces, underscores, or periods.
ENV_NAME=prod
VHOST_PORT=9001
VHOST_NAME=default
VHOST_ALIAS="$IP1:9001"
# Optionally configure SSL for virtual host.
# VHOST_SSL=y
# Set to "y" to enable SSL on the virtual host.
# KEYSTORE_JAR= # JAR file containing the cert and private key.
# KEYSTORE_NAME= # Name of the keystore.
# KEYSTORE_ALIAS= # The key alias.
# KEY_PASSWORD= # The key password, if it has one.
# AXGROUP=axgroup001 # Default name is axgroup001
Note:
For SSL configuration, see
Keystores and Truststores
and C
onfiguring SSL access to an API for the
Private Cloud
for more information on creating the JAR file, and other aspects of configuring SSL.
The command:
●
Creates the environment
●
Creates a single virtual host for the environment
●
Associates the environment with all Message Processor(s) in the pod associated with the organization
containing the environment.
●
Enables analytics
Note
: If you enable analytics for one environment in an organization, you must enable analytics for all
environments in the organization.
Create an environment by using API calls
Alternatively, you can use the following API calls to create an environment. The first call creates the
environment:
curl H "ContentType:application/xml" u : \
X POST http://:8080/v1/organizations//environments \
d ': X POST \
http://:8080/v1/organizations//environments//servers
Confidential and proprietary information of Apigee, Inc. Not to be disclosed except under nondisclosure agreement.
Apigee Edge Operations Guide
Page 110
\
d "action=add&uuid="
Where
"
" is the UUID of Message Processor. You can obtain the UUID by using the command:
> curl http://:8082/v1/servers/self
Where
"