This document describes how to install the Edge UI for Apigee Edge for Private Cloud. The Edge UI is the next generation of UI for Edge.
To try out the new Edge UI in an Apigee Edge for Private Cloud installation, you must:
- Install the Edge UI on its own node. You cannot install it on a node that
contains other Edge components, including the node on which the existing Classic UI resides.
Doing so will cause users to be unable to log in to the Classic UI.
The Edge UI's node must meet the following requirements:
- JAVA 1.8
- 4 GBytes of RAM
- 60GB disk space
- You must first install the 4.19.06 version of the
apigee-setuputility on the node as described at Install the Edge apigee-setup utility.
- Port 3001 must be open. This is the default port used for requests to the Edge UI. If you change the port by using the properties described in New UE configuration file, make sure that port is open.
- Enable an external IDP on Edge. The Edge UI supports SAML or LDAP as the authentication mechanism.
- (SAML IDP only) The Edge UIonly supports TLS v1.2. Because you connect to the SAML IDP over TLS, if you use SAML, your IDP must therefore support TLS v1.2.
For more on the Edge UI, see The new Edge UI for Private Cloud.
At a high level, the process for installing the Edge UI for Apigee Edge for Private Cloud is as follows:
- Add a new node to your cluster
- Log in to the new node
- Download the
- Create a configuration file and modify it with your settings
- Execute the
- Log in and test to new UE
When executed on the new node, the
- Installs the base Classic UI, called shoehorn, and configures the Classic UI to use an external IDP to authenticate with Edge.
- Installs the new Edge UI, and configures the Edge UI to use your external IDP to authenticate with Edge.
Considerations before installing the new Edge UI
As described above in the prerequisites, the Edge UI requires that you enable an external IDP on Edge. That means user authentication is controlled by the IDP, where you configure it to use email addresses as the user ID. All Edge UI users must therefore be registered in the IDP.
The Classic UI, the default UI you installed with Apigee Edge for Private Cloud, does not require an external IDP. It can use either an IDP or Basic authentication. That means you can either:
- Enable external IDP support on Edge and on both the Classic UI and the Edge UI.
In this scenario, all Classic UI and Edge UI users are registered in the IDP. For information on adding new users to the IDP, see Register new Edge users.
- Enable external IDP support on Edge, but leave Basic authentication enabled. The Edge UI
uses the IDP and the Classic UI still uses Basic authentication.
In this scenario, all Classic UI users log in with Basic authentication credentials, where their credentials are stored in the Edge OpenLDAP database. Edge UI users are registered in the IDP and log in by using either SAML or LDAP.
However, a Classic UI user cannot log in to the Edge UI until you have added that user to the IDP as described in Register new Edge users.
Installation configuration changes from previous releases
Be aware of the following changes to the installation procedure from the Beta releases of the Edge UI.
Installation configuration changes from Edge 4.18.05
The Edge 4.19.06 release of the Edge UI contains the following changes to the configuration file from the Edge 4.18.05 release:
That property has a predefined value of 0.5 (30 minutes) and cannot be changed.
|You can now use properties to enable TLS on the Edge UI. See Configuring TLS for the Edge UI for more.
Installation configuration changes from Edge 4.18.01
The Edge 4.19.06 release of the Edge UI contains the following changes to the configuration file from the Edge 4.18.01 release:
# Shoehorn/Classic UI configurations. SHOEHORN_SCHEME SHOEHORN_IP SHOEHORN_PORT # Classic UI configurations. CLASSIC_UI_SCHEME CLASSIC_UI_IP CLASSIC_UI_PORT # Information about Edge SSO module. MANAGEMENT_UI_SKIP_VERIFY
New Edge UI configuration file
The following configuration file contains all the information necessary to install and configure the new Edge UI. You can use the same configuration file to install and configure both the shoehorn/Classic UI and the Edge UI.
# IP of the Edge Management Server. # This node also hosts the Apigee SSO module and the current, or Classic, UI. IP1=management_server_IP # IP of the Edge UI node. IP2=edge_UI_server_IP # Edge sys admin credentials. ADMIN_EMAILfirstname.lastname@example.org APIGEE_ADMINPW=your_password # If omitted, you are prompted for it. # Edge Management Server information. APIGEE_PORT_HTTP_MS=8080 MSIP=$IP1 MS_SCHEME=http # # Edge UI configuration. # # Enable the Edge UI. EDGEUI_ENABLE_UNIFIED_UI=y # Specify IP and port for the Edge UI. # The management UI port must be open for requests to the Edge UI MANAGEMENT_UI_PORT=3001 MANAGEMENT_UI_IP=$IP2 # Set to 'OPDK' to specify a Private Cloud deployment. MANAGEMENT_UI_APP_ENV=OPDK # Disable TLS on the Edge UI. MANAGEMENT_UI_SCHEME=http # Location of Edge UI. MANAGEMENT_UI_PUBLIC_URIS=$MANAGEMENT_UI_SCHEME://$MANAGEMENT_UI_IP:$MANAGEMENT_UI_PORT MANAGEMENT_UI_SSO_REGISTERED_PUBLIC_URIS=$MANAGEMENT_UI_PUBLIC_URIS MANAGEMENT_UI_SSO_CSRF_SECRET=YOUR_CSRF_SECRET # Duration of CSRF token. MANAGEMENT_UI_SSO_CSRF_EXPIRATION_HOURS=24 # Defaults to 8760 hours, or 365 days. MANAGEMENT_UI_SSO_STRICT_TRANSPORT_SECURITY_AGE_HOURS=8760 ## SSO configuration for the Edge UI. MANAGEMENT_UI_SSO_ENABLED=y # Only required if MANAGEMENT_UI_SSO_ENABLED is 'y' MANAGEMENT_UI_SSO_CLIENT_OVERWRITE=y MANAGEMENT_UI_SSO_CLIENT_ID=newueclient MANAGEMENT_UI_SSO_CLIENT_SECRET=your_client_sso_secret # # Shoehorn UI configuration # # Set to http even if you enable TLS on the Edge UI. SHOEHORN_SCHEME=http SHOEHORN_IP=$MANAGEMENT_UI_IP SHOEHORN_PORT=9000 # # Edge Classic UI configuration. # Some settings are for the Classic UI, but are still required to configure the Edge UI. # # These settings assume that Classic UI is installed on the Management Server. CLASSIC_UI_IP=$MSIP CLASSIC_UI_PORT=9000 CLASSIC_UI_SCHEME=http EDGEUI_PUBLIC_URIS=$CLASSIC_UI_SCHEME://$CLASSIC_UI_IP:$CLASSIC_UI_PORT # Information about publicly accessible URL for Classic UI. EDGEUI_SSO_REGISTERED_PUBLIC_URIS=$EDGEUI_PUBLIC_URIS # Enable SSO EDGEUI_SSO_ENABLED=y # The name of the OAuth client used to connect to apigee-sso. # The default client name is 'edgeui'. # Apigee recommends that you use the same settings as you used # when enabling your IDP on the Classic UI. EDGEUI_SSO_CLIENT_NAME=edgeui # Oauth client password using uppercase, lowercase, number, and special chars. EDGEUI_SSO_CLIENT_SECRET=ssoClient123 # If set, existing EDGEUI client will deleted and new one will be created. EDGEUI_SSO_CLIENT_OVERWRITE=y # Apigee SSO Component configuration # Externally accessible IP or DNS of Edge SSO module. SSO_PUBLIC_URL_HOSTNAME=$IP1 SSO_PUBLIC_URL_PORT=9099 # Default is http. Set to https if you enabled TLS on the Apigee SSO module. # If Apigee SSO uses a self-signed cert, you must also set MANAGEMENT_UI_SKIP_VERIFY to "y". SSO_PUBLIC_URL_SCHEME=http # MANAGEMENT_UI_SKIP_VERIFY=y # SSO admin credentials as set when you installed Apigee SSO module. SSO_ADMIN_NAME=ssoadmin SSO_ADMIN_SECRET=your_sso_admin_secret # ## SSO Configuration (define external IDP) # # # Use one of the following configuration blocks to # # define your IDP settings: # # - SAML configuration properties # # - LDAP Direct Binding configuration properties # # - LDAP Indirect Binding configuration properties # INSERT_IDP_CONFIG_BLOCK_HERE (SAML, LDAP direct, or LDAP indirect) ## SMTP Configuration (required) # SKIP_SMTP=n # Skip now and configure later by specifying "y". SMTPHOST=smtp.gmail.com SMTPUSERemail@example.com SMTPPASSWORD=your_email_password SMTPSSL=y SMTPPORT=465 # If no SSL, use a different port, such as 25. SMTPMAILFROM="My Company firstname.lastname@example.org"
Install the Edge UI
After you create and modify the configuration file, you can install the new Edge UI on that new node.
To install the Edge UI:
- Add a new node to your cluster.
- Log in to the new node as an administrator.
- Install the 4.19.06 version of the
apigee-setuputility on the node, as described at Install the Edge apigee-setup utility.
- Clean all cached information with Yum by executing the following command:
sudo yum clean all
- Create the configuration file as described in New
Edge UI configuration file and ensure that it is owned by the "apigee" user:
chown apigee:apigee configFile
Be sure that you make the following edits to the configuration file:
- Change the value of the
MANAGEMENT_UI_SSO_CSRF_SECRETproperty in the configuration file to your CSRF secret.
- Configure Edge to use one of the following (the new Edge UI requires an external IDP):
For more information, see Overview of external IDPs authentication.
- Change the value of the
- Configure your external IDP with the users that you want to have access to the Edge UI. For more information, see Register new Edge users.
- On the new node, execute the following command:
/opt/apigee/apigee-setup/bin/setup.sh -p ue -f configFile
apigee-setuputility installs the Classic UI. On top of the Classic UI, the installer then installs the Edge UI.
- Log in to the Edge UI by opening the following URL in a browser:
Where new_edge_UI_IP is the IP address of the node hosting the new Edge UI.
Edge prompts you for your external IDP credentials.
- Enter your credentials.
The new Edge UI appears. For information on using the Edge UI, see The new Edge UI for Private Cloud.
If the Edge UI does not display, then be sure that port 3001 is open for external connections.
Uninstall the Classic UI
To uninstall the Classic UI from its node, you must uninstall both the new Edge UI and the base Classic UI (shoehorn) that was installed on the node during the UI installation process.
To uninstall the new Edge UI:
/opt/apigee/apigee-service/bin/apigee-service edge-management-ui uninstall
To uninstall the base Classic UI (shoehorn):
/opt/apigee/apigee-service/bin/apigee-service edge-ui uninstall
To remove all Edge components from the node:
- Stop all Edge services running on the machine:
- Clear the yum cache:
sudo yum clean all
- Remove all the Apigee RPMs:
sudo rpm -e $(rpm -qa | egrep "(apigee-|edge-)")
- Remove the installation root directory:
sudo rm -rf /opt/apigee