Configure a proxy for external network access

Enable the StackRox Kubernetes Security Platform to route traffic through a proxy.

3 minute read

If your network configuration restricts outbound traffic through proxies, you can configure proxy settings in the StackRox Kubernetes Security Platform. You can configure these settings during a new installation or on an existing deployment.

  • Configuring proxies during installation requires version 3.0.35 or newer. If you are using an older version, you can configure a proxy on an existing deployment, see the previous versions section for instructions.

When you use a proxy with the StackRox Kubernetes Security Platform:

  • All outgoing HTTP, HTTPS, and other TCP traffic from Central and Scanner goes through the proxy.
  • Traffic between Central and Scanner doesn’t go through the proxy.
  • The proxy configuration doesn’t affect the other StackRox Kubernetes Security Platform components.
  • If you aren’t using the offline mode and a Collector running in a secured cluster needs to download an additional kernel module or eBPF probe at runtime:
    1. The collector attempts to download them by contacting Sensor.
    2. The Sensor forwards this request to Central.
    3. Central uses the proxy to locate the module or probe at

Configure proxy on an existing deployment

Follow the instructions below for the StackRox Kubernetes Security Platform version you are using:

3.0.35 and newer

To configure the proxy in an existing deployment, you must export the proxy-config secret as a YAML file, update your proxy configuration in that file, and upload it as a Kubernetes secret.

  1. Save the existing secret as a YAML file:

    kubectl -n stackrox get secret proxy-config -o go-template='{{index .data "config.yaml" | base64decode}}{{"\n"}}' >/tmp/proxy-config.yaml
    • You can choose another path instead of /tmp/proxy-config.yaml.
  2. Edit the fields you want to modify in the configuration file, as specified in the Configure proxy during installation section.

  3. After you save the changes, run the following command to replace the secret in Kubernetes:

    kubectl -n stackrox create secret generic proxy-config --from-file=config.yaml=/tmp/proxy-config.yaml -o yaml --dry-run | \
    kubectl label -f - --local -o yaml | \
    kubectl apply -f -
    • Replace /tmp/proxy-config.yaml with your selected file path.
    • Kubernetes takes around 1 minute to propagate the changes to Central and Scanner.
    • If you see any issues with outgoing connections after changing the proxy configuration, restart your Central and Scanner pods.

Previous versions

If you are running the StackRox Kubernetes Security Platform version 3.0.35 or newer, use the 3.0.35 and newer instructions.

You can configure a proxy by using the http_proxy, https_proxy, and all_proxy environment variables. Use the address of your proxy server as the value for these environment variables, for example http://user:password@my.proxy:3128. The environment variables support the following URL schemes:

  • http:// for an HTTP proxy.
  • https:// for a TLS-enabled HTTP proxy.
  • socks5:// for a SOCKS5 proxy.
  • For establishing a TLS secured connection to external services through the proxy, your proxy must support the HTTP CONNECT method.
  • When you configure a proxy, we recommend that you configure all 3 environment variables with the address of the proxy, and also configure the no_proxy environment variable.
  • Use the no_proxy environment variable to specify a list of names, name patterns, or IP addresses to bypass the proxy.
  • To enable direct connection between the StackRox Kubernetes Security Platform components, we recommend adding the following value to the no_proxy environment variable:
    • *.stackrox,*.stackrox.svc,localhost,*.local,*.localdomain,

To configure the proxy in an existing deployment:

  1. Configure the environment variables:
  2. Set the environment variables for Central:
    kubectl -n stackrox set env deploy/central -c central \
    http_proxy="$proxy_url" https_proxy="$proxy_url" all_proxy="$proxy_url" no_proxy="$no_proxy_list"
  3. Set the environment variables for Scanner:
    kubectl -n stackrox set env deploy/scanner -c scanner \
    http_proxy="$proxy_url" https_proxy="$proxy_url" all_proxy="$proxy_url" no_proxy="$no_proxy_list"

Configure proxy during installation

You can specify your proxy configuration during installation if you are using the StackRox Kubernetes Security Platform version 3.0.35 or newer. When you run the installer by using the roxctl central generate command, the installer generates the secrets and deployment configuration files for your environment. You can configure a proxy by editing the generated configuration secret (YAML) file. Currently, you can’t configure proxies by using the roxctl command-line interface (CLI). The configuration is stored in a Kubernetes secret and it’s shared by both Central and Scanner.

To add your proxy configuration settings:

  1. Open the configuration file central/proxy-config-secret.yaml from your deployment bundle directory.

    If you are using helm the file is available at central/templates/proxy-config-secret.yaml.

  2. Edit the fields in the configuration file you want to modify.

    apiVersion: v1
    kind: Secret
      namespace: stackrox
      name: proxy-config
    type: Opaque
      config.yaml: |-
        # # NOTE: Both central and scanner should be restarted if this secret is changed.
        # # While it is possible that some components will pick up the new proxy configuration
        # # without a restart, it cannot be guaranteed that this will apply to every possible
        # # integration etc.
        # url:
        # username: username
        # password: password
        # # If the following value is set to true, the proxy wil NOT be excluded for the default hosts:
        # # - *.stackrox, *.stackrox.svc
        # # - localhost, localhost.localdomain,, ::1
        # # - *.local
        # omitDefaultExcludes: false
        # excludes:  # hostnames (may include * components) for which not to use a proxy, like in-cluster repositories.
        # - some.domain
        # # The following configuration sections allow specifying a different proxy to be used for HTTP(S) connections.
        # # If they are omitted, the above configuration is used for HTTP(S) connections as well as TCP connections.
        # # If only the `http` section is given, it will be used for HTTPS connections as well.
        # # Note: in most cases, a single, global proxy configuration is sufficient.
        # http:
        #   url:
        #   username: username
        #   password: password
        # https:
        #   url:
        #   username: username
        #   password: password
    • adding a username and a password is optional, both at the beginning and in the http and https sections.
    • the url option supports the following URL schemes:
      • http:// for an HTTP proxy.
      • https:// for a TLS-enabled HTTP proxy.
      • socks5:// for a SOCKS5 proxy.
    • the excludes list can contain DNS names (with or without * wildcards), IP addresses, or IP blocks in CIDR notation (for example, The values in this list are applied to all outgoing connections, regardless of protocol.
    • the |- line in the stringData section indicates the start of the configuration data.
    • when you first open the file, all values are commented out (by using the # sign at the beginning of the line). Lines starting with double hash signs # # contain explanation of configuration keys.
    • make sure that when you edit the fields, you maintain an indentation level of two spaces relative to the config.yaml: |- line.
  3. After editing, you can proceed with your usual installation. The updated configuration instructs the StackRox Kubernetes Security Platform to use the proxy running on the provided address and the port number.


We're happy to help! Reach out to us to discuss questions, issues, or feature requests.

© 2021 StackRox Inc. All rights reserved.