Pivotal Knowledge Base

Follow

How to set proxy settings for all applications running on PCF®

Environment

Product Version
Pivotal Cloud Foundry® (PCF) 1.5.x, 1.6.x and 1.7.x

Purpose

In some environments, access to the Internet or other network resources are prohibited.  To get around this, some companies offer access to select resources by going through an HTTP proxy.  This allows a company to monitor and restrict access to network resources on a very granular level.

This article describes how to globally configure proxy settings for all applications running on PCF by using a staging environment variable group and a running environment variable group.

Procedure

  1. Log on as an admin user using the cf cli.
  2. Locate your proxy settings. This would include http proxy, https proxy, and any domains or IP addresses that should not go through the proxy (more on this in the Additional Information below).  Pivotal cannot provide this information as it is specific to each customer's environment. If you are unsure about what settings to use, contact your network administrator before proceeding.
  3. To configure proxy access for applications that are staging on the platform (staging is the process where the build pack runs), run the command
     cf set-staging-environment-variable-group '{"http_proxy": "http://your-proxy:8080/", "https_proxy": "http://your-proxy:8080/", "no_proxy": "some.domain.com"}'
    Insert your proxy information, http_proxy, https_proxy and no_proxy, into the JSON blob being passed into the command. Changes to the staging environment variable group will take effect the next time you stage an application.
  4. To configure proxy access for applications that are running on the platform, run the command
     cf set-running-environment-variable-group '{"http_proxy": "http://your-proxy:8080/", "https_proxy": "http://your-proxy:8080/", "no_proxy": "some.domain.com"}'
    Insert your proxy information, http_proxy, https_proxy and no_proxy, into the JSON blob being passed into the command.  Changes to the running environment variable group will take effect when you restart your application.

In general, you would run step #3 and step #4 with the same proxy information.  This enables the proxy settings for build packs during staging and also for applications at runtime.  However, you can choose to run only step #3 or step #4 to be more restrictive and only set the proxy information at staging or runtime.

Impact/Risks

Please be careful when applying proxy settings using this method as they will be globally applied to all applications on the platform, including system applications and service brokers. Incorrectly configuring proxy settings can not only result in customer applications being unable to connect to the Internet or access required resources, but it can also cause errands to fail and break system applications and service brokers.  While errands, system applications, and service brokers do not need to connect to the Internet, they do often need to talk to other resources on PCF and incorrect proxy settings can break these connections.

If you find that an application breaks because of the proxy settings, it is possible to instruct that application to ignore the global proxy settings by using cf set-env to manually unset the proxy environment variables for the failing application.  

For example:

cf set-env my-application http_proxy ''
cf set-env my-application https_proxy ''
cf set-env my-application no_proxy ''

Additional Information

The commands listed above are not doing anything magical. They are simply setting three environment variables, http_proxy, https_proxy and no_proxy, globally across all applications on PCF. The first instructs which proxy to use for HTTP requests, the second instructs which proxy to use for HTTPS requests and the third instructs which DNS names should not be sent through the proxy (i.e. should be sent direct).  

In most cases, http_proxy and https_proxy will be the same, which sends both types of requests to the same proxy. The no_proxy variable may or may not be needed; it depends on your proxy configuration. When unsure, please contact your network administrator. If it's not needed, you can omit it. If it's needed, it takes the format of a comma separated list of DNS names or IP address.

While PCF will guarantee that these environment variables are set across all of your applications, it is up to the application itself to detect and utilize these environment variables. Most well-behaved applications and language runtimes will honor these environment variables, no additional work required. There are a few caveats to consider, though.

  • Most of the time, case does not matter. Setting http_proxy is generally the same as setting HTTP_PROXY. However, this behavior is dependent on the application and language runtime.  You may choose to set both upper and lower case variants to provide greater compatibility.
  • If your proxy can only send traffic to the Internet then you need to set no_proxy such that traffic destined for PCF itself and other internal resources does not go out to through the proxy. You can prevent traffic destined for PCF from going out through the proxy by setting no_proxy to contain your system and apps domains.
  • Interpretation of no_proxy varies from application to application and from language runtime to language runtime. Most support no_proxy, but exactly how that is supported varies. For example, some match DNS names that end with the value set in no_proxy (i.e. my-domain.com matches test.my-domain.com) and others support wildcards (the asterisk character) to provide basic pattern matching in DNS names. Pattern matching and wildcards are not generally supported for IP addresses.
  • The Java Version Manager (JVM) has a completely different way of configuring proxy settings. If you're trying to configure proxy settings globally for a JVM-based application, then you need to use the following command instead of #4 above.
    cf set-running-environment-variable-group '{"JAVA_OPTS": "-Dhttp.proxyHost=your-proxy -Dhttp.proxyPort=8080 -Dhttp.nonProxyHosts=my.system.domain"}'

    If you want to set proxy settings globally for both JVM-based apps and other apps, then you can merge the two commands, like this:

    cf set-running-environment-variable-group '{"http_proxy": "http://your-proxy:8080/", "https_proxy": "http://your-proxy:8080/", "no_proxy": "my.system.domain","JAVA_OPTS": "-Dhttp.proxyHost=your-proxy -Dhttp.proxyPort=8080 -Dhttp.nonProxyHosts=my.system.domain"}'

    Please also note that http.nonProxyHosts is a pipe-delimited field instead of comma-delimited like no_proxy. For more details on these JVM settings, please see this link.

  • Because these conventions are Linux-/ Unix-based, it's unlikely that these values will have any affect on .NET applications or applications running on Windows-based Diego Cells.

 

Comments

Powered by Zendesk