Configuring Proxy Settings for All Apps

This topic describes how to globally configure proxy settings for all apps in your Pivotal Platform deployment. Some environments restrict access to the Internet by requiring traffic to pass through an HTTP or HTTPS proxy. Pivotal Platform operators can use the Cloud Foundry Command Line Interface (cf CLI) to provide the proxy settings to all apps, including system apps and service brokers.

Not: Incorrectly configuring proxy settings can prevent apps from connecting to the Internet or accessing required resources. They can also cause errands to fail and break system apps and service brokers. Although errands, system apps, and service brokers do not need to connect to the Internet, they often need to access other resources on Pivotal Platform. Incorrect proxy settings can break these connections.

Set Environment Variables

To globally configure proxy settings for Pivotal Platform apps, perform the following steps to set three environment variables for both the staging environment variable group and the running environment variable group.

For more information about variable groups, see the Environment Variable Groups section of the Cloud Foundry Environment Variables topic.

This procedure explains how to set proxy information for both staging and running apps. However, you can set proxy settings for only staging or only running apps.

  1. Target your Cloud Controller with the cf CLI. If you have not installed the cf CLI, see Installing the cf CLI.

    $ cf api api.YOUR-SYSTEM-DOMAIN
    Setting api endpoint to api.YOUR-SYSTEM-DOMAIN...
    OK
    API endpoint:   https://api.YOUR-SYSTEM-DOMAIN (API version: 2.54.0)
    Not logged in. Use 'cf login' to log in.
    

  2. Log in with your UAA administrator credentials. To retrieve these credentials, navigate to the Pivotal Application Service (PAS) tile in the Ops Manager Installation Dashboard and click Credentials. Under UAA, click Link to Credential next to Admin Credentials and record the password.

    $ cf login
    API endpoint: https://api.YOUR-SYSTEM-DOMAIN

    Email> admin Password> Authenticating... OK

  3. To configure proxy access for apps that are staging, run the following command, replacing the placeholder values:

    $ cf set-staging-environment-variable-group '{"http_proxy": "http://YOUR-PROXY:8080/", "https_proxy": "http://YOUR-PROXY:8080/", "no_proxy": "NO-PROXY.EXAMPLE.COM"}'

    • http_proxy: Set this value to the proxy to use for HTTP requests.
    • https_proxy: Set this value to the proxy to use for HTTPS requests. In most cases, this is the same as http_proxy.
    • no_proxy: Set this value to a comma-separated list of DNS names or IP addresses that can be accessed without passing through the proxy. This value may not be needed, because it depends on your proxy configuration. From now on, the proxy settings are applied to staging apps.
  4. To configure proxy access for apps that are running, run the following command, replacing the placeholder values as above:

    $ cf set-running-environment-variable-group '{"http_proxy": "http://YOUR-PROXY:8080/", "https_proxy": "http://YOUR-PROXY:8080/", "no_proxy": "NO-PROXY.EXAMPLE.COM"}'
    To configure proxy settings for Java-based apps, use the following command instead, replacing the placeholder values. For http.nonProxyHosts, use a pipe-separated list rather than a comma-separated list.
    $ cf set-running-environment-variable-group '{"JAVA_OPTS": "-Dhttp.proxyHost=YOUR-PROXY -Dhttp.proxyPort=8080 -Dhttp.nonProxyHosts=NO-PROXY.EXAMPLE.COM"}'
    For more information about these Java proxy settings, see Java Networking and Proxies in the Oracle documentation.

  5. To apply the proxy configuration for the running environment variable group, you must restart each app that you want to use the new configuration.

Troubleshooting

If an app fails after you apply the global proxy settings, try the following solutions.

Exclude an App From Global Proxy Settings

If your app fails, try instructing the app to ignore the global proxy settings. To manually unset the proxy environment variables for the failing app:

  1. Set the proxy environment variables for http_proxy to an empty value:

    $ cf set-env YOUR-APP http_proxy ''

  2. Set the proxy environment variables for https_proxy to an empty value:

    $ cf set-env YOUR-APP https_proxy ''

  3. Set the proxy environment variables for no_proxy to an empty value:

    $ cf set-env YOUR-APP no_proxy ''

Change Case of HTTP

Your app and language runtime may be case-sensitive. Try performing the steps in Set Environment Variables using uppercase for HTTP_PROXY, HTTPS_PROXY, and NO_PROXY instead of lowercase, as in the following example:

$ cf set-staging-environment-variable-group '{"HTTP_PROXY": "http://YOUR-PROXY:8080/", "HTTPS_PROXY": "http://YOUR-PROXY:8080/"}'.

Check Proxy Settings

If you have set up your proxy so that it can only send traffic to the Internet, a request to an internal resource like Pivotal Platform fails. You must set no_proxy so that traffic destined for Pivotal Platform and other internal resources is sent directly and does not go through the proxy. For instance, setting no_proxy to include your system and app domains will ensure that requests destined for those domains are sent directly.

Verify Interpretation

The interpretation of no_proxy depends on the app and the language runtime. Most support no_proxy, but the specific implementation may vary. For example, some match DNS names that end with the value set in no_proxy: example.com would match test.example.com. Others support the use of the asterisk as a wildcard to provide basic pattern matching in DNS names: *.example.com would match test.example.com. Most apps and language runtimes do not support pattern matching and wildcards for IP addresses.