Skip to content
Docs
Cancel

CircleCI Server v3.x Configuring a Proxy

Last updated
Tags Server v3.x Server Admin

Depending on your security requirements, you might want to install CircleCI server behind a proxy. Installing behind a proxy gives you the power to monitor and control access between your installation and the broader Internet.

Installation and configuration

There are two stages to installing CircleCI server behind a proxy. First, at the point of installation, the proxy addresses need to be specified, along with any addresses that should not be behind the proxy.

Installing behind a proxy

The installation process is described in detail in the CircleCI Server v3.x Installation guide. Both proxy and non-proxy addresses should be supplied using the arguments described here. The installation command should be in the format:

kubectl kots install circleci-server --http-proxy <my-http-proxy-uri> --https-proxy <my-https-proxy> --no-proxy <my-no-proxy-list>

Configuring your proxy

Once you have installed server and accessed the management console, there are some fields that need to be completed in the configuration section, as shown in the screenshot below. These fields will not be automatically populated, so the same proxy and no-proxy addresses you supplied during installation will need to be supplied here. If your proxy requires authentication in the form of a username and password, check the HTTP Proxy authenticated option to add the credentials.

Screenshot showing settings available to configure a proxy
Figure 1. CircleCI Server v3.x Configuring a Proxy

Known limitations

  • Some additional configuration is required to import orbs when installed behind a proxy. See Orbs on Server docs for more information.

  • The JVM only accepts proxies that run over HTTP, not HTTPS, and therefore proxy URIs must be of the form http://user:password@host:port rather than https://user:password@host:port.

  • If your GitHub instance is running outside of the proxied environment (either GitHub.com or GitHub Enterprise), you must ensure that SSH traffic from our application (inside the Kubernetes cluster) and from our Nomad node can reach your instance without additional configuration. Our SSH agents do not respect proxy settings because it uses a different network protocol. If a proxy is the only way that any traffic can reach outside the proxied environment, this means it will block SSH traffic and your application will fail.

  • The load balancer endpoints must be added to the no-proxy list for the following services: output processor and vm-service. This is because the no-proxy list is shared between the application and build-agent. The application and build-agent are assumed to be behind the same firewall and therefore cannot have a proxy between them.

  • The KOTS Admin Console cannot be upgraded if proxy setting were configured. The proxy settings will be deleted and cause the KOTS Admin Console to break.

  • If you install server behind a proxy, you may need to provide a custom image for VM service. Visit the CircleCI Linux Image Builder repo for further information.

  • If object storage is outside the proxy, no job features that use object storage will work. This includes:

    • Artifacts

    • Test results

    • Cache save and restore

    • Workspaces

      Users can get around this restriction by setting environment variables on their jobs. For example:

      jobname:
  docker:
  - image: ubuntu:latest
    environment:
      HTTP_PROXY: http://proxy.example.com:3128
      HTTPS_PROXY: http://proxy.example.com:3128
      NO_PROXY: whatever.internal,10.0.1.2
      It is crucial that these environment variables are set in this specific location because it is the only location that propagates them to the correct service.

Help make this document better

This guide, as well as the rest of our docs, are open source and available on GitHub. We welcome your contributions.

Need support?

Our support engineers are available to help with service issues, billing, or account related questions, and can help troubleshoot build configurations. Contact our support engineers by opening a ticket.

You can also visit our support site to find support articles, community forums, and training resources.

Creative Commons License
CircleCI Documentation by CircleCI is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.

6,000 Minutes Free

CircleCI, now with more build minutes
than anyone else for FREE 🎉

Sign up for Free

These teams get it

CCI customer teams