CircleCI Server v3.x Configuring a Proxy

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 form:

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 gained access to 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 and 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 at this point.

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

Known limitations

  • Installing behind a proxy will prevent the use of CircleCI runner.

  • Some additional configuration will be required to import orbs when installed behiind 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 our 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 set. 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 by setting environment variables on their jobs like so:

      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 extremely important that these environment variables are set in this particular location because its 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.