Expose StackRox portal over HTTP

Enable an unencrypted HTTP server to expose the StackRox portal through ingress controllers, Layer 7 load balancers, Istio, or other solutions.

1 minute read

If you use an ingress controller, Istio, or a Layer 7 load balancer that prefers unencrypted HTTP back ends, you can configure the StackRox Kubernetes Security Platform to expose the StackRox portal over HTTP. Doing this makes the StackRox portal available over a plaintext back end.

  1. To expose the StackRox portal over HTTP:

    • You must be running version 2.5.25 or newer of the StackRox Kubernetes Security Platform. If you are on an older version, see the Upgrade StackRox page for upgrade instructions.
    • You must be using an ingress controller, a Layer 7 load balancer, or Istio to encrypt external traffic with HTTPS. It’s insecure to expose the StackRox portal directly to external clients using plain HTTP.
  2. For the StackRox Kubernetes Security Platform version 3.0.40 and newer, we recommend that you use a YAML configuration file to expose Central over HTTP. See configure endpoints for more details.

You can expose the StackRox portal over HTTP during installation or on an existing StackRox deployment.

During installation

To enable the HTTP server during deployment, use the --plaintext-endpoints option with the roxctl command-line interface (CLI). For example, to use it with the interactive installation process, run the following command:

Copy
roxctl central generate interactive --plaintext-endpoints=<endpoints-spec>

<endpoints-spec> is a comma-separated list of single endpoint specifications in the form of <type>@<addr>:<port>, where:

  • type is grpc or http. Using http as type works in most use cases. For advanced use cases, you can either use grpc or omit its value. If you omit the value for type, you can configure two endpoints in your proxy, one for gRPC and the other for HTTP, that both point to the same exposed HTTP port on Central. However, most proxies don’t support carrying both gRPC and HTTP traffic on the same external port.

  • addr is the IP address on which you want to expose Central. You can omit this, or use localhost or 127.0.0.1 if you want to have an HTTP endpoint which is only accessible by using port-forwarding.

  • port is the port number on which you want to expose Central.

    Here are a few valid <endpoints-spec> values:

    Copy
    --plaintext-endpoints=8080
    --plaintext-endpoints=http@8080
    --plaintext-endpoints=:8081
    --plaintext-endpoints=grpc@:8081
    --plaintext-endpoints=localhost:8080
    --plaintext-endpoints=http@localhost:8080

On an existing StackRox deployment

To enable the HTTP server on an existing StackRox deployment:

  1. Add an environment variable to the StackRox Central deployment with the name ROX_PLAINTEXT_ENDPOINTS and set its value to an endpoint specification, for example:

    Copy
    CENTRAL_PLAINTEXT_PATCH='
    spec:
      template:
        spec:
          containers:
          - name: central
            env:
            - name: ROX_PLAINTEXT_ENDPOINTS
              value: "http@8080,grpc@8081"
    '
    
    kubectl -n stackrox patch deploy/central -p "$CENTRAL_PLAINTEXT_PATCH"
    Copy
    CENTRAL_PLAINTEXT_PATCH='
    spec:
      template:
        spec:
          containers:
          - name: central
            env:
            - name: ROX_PLAINTEXT_ENDPOINTS
              value: "http@8080,grpc@8081"
    '
    
    oc -n stackrox patch deploy/central -p "$CENTRAL_PLAINTEXT_PATCH"

Questions?

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

© 2021 StackRox Inc. All rights reserved.