Installing on Openshift

Installing Horizon on Openshift is very similar to installing on Kubernetes. The main difference is that you need to use the oc command instead of kubectl. For that reason, you should follow the Kubernetes installation procedure.

This page details the differences expected betwen Kubernetes and Openshift.

Security contexts

The default Horizon Helm chart uses the 1001 user to avoid running as root inside the container. However, on OpenShift, this results in the anyuid SCC being required to run the container. Since a random non-root UID will be assigned by OpenShift to the container upon startup, this security measure is unnecessary. It can be safely disabled by adding the following YAML to your values-override.yaml file:

podSecurityContext:
  enabled: false

containerSecurityContext:
  enabled: false

If you’re using the built-in database for test purposes, you’ll also need to disable the security context for the database container:

mongodb:
  podSecurityContext:
    enabled: false

  containerSecurityContext:
    enabled: false
On OpenShift, you might have to manage volume permissions for the MongoDB PVC using the Bitnami’s guide.

Leases

In a large cluster, chances are that CRDs cannot be installed by a regular user. However, Horizon can be configured to rely on leases that are CRDs for clustering. See the dedicated documentation section for more information on how leases work.

Leases can be safely disabled without having a large impact on Horizon reliability. They mostly help in case of a network partition across multiple datacenters or availability zones.

To disable leases, add the following YAML to your values-override.yaml file:

leases:
  enabled: false

Then, when installing the helm chart, add the --skip-crds option to ensure that the leases CRD is not installed.

Router configuration

When exposing Horizon through the OpenShift router, you need to provide Horizon with a way to authenticate client certificates. You have two options to do so:

  • Install the cert-auth-proxy component as a sidecar of the Horizon pod and use a passthrough route to forward traffic to Horizon. (recommended)

  • Configure the router to ask for client certificates and forward traffic to Horizon.

Using cert-auth-proxy

The cert-auth-proxy component is a small proxy that can be used to authenticate client certificates. It is installed as a sidecar container to Horizon, and then referenced in place of Horizon in the OpenShift route or ingress. To install it, add the following YAML to your values-override.yaml file:

clientCertificateHeader: "X-Forwarded-Tls-Client-Cert"

sidecars:
  - name: cert-auth-proxy
    image: registry.evertrust.io/cert-auth-proxy:latest
    imagePullPolicy: Never
    ports:
      - name: https-proxy
        containerPort: 8443
    env:
      - name: UPSTREAM
        value: localhost:9000
    volumeMounts:
      - name: horizon-local-tls
        # This mountPath will enable the certificate for the "horizon.local" route
        mountPath: /var/cert-auth-proxy/certificates/horizon.local

extraVolumes:
  - name: horizon-local-tls
    secret:
      # This secret must contain a valid TLS certificate for route hostname.
      secretName: horizon.local-tls

service:
  extraPorts:
    - name: https-proxy
      protocol: TCP
      port: 8443
      targetPort: https-proxy

Then, you can either use the following extra values to override-values.yaml to generate an ingress with a passthrough route:

ingress:
  enabled: true
  annotations:
    route.openshift.io/termination: "passthrough"
  extraRules:
    - host: "horizon.local"
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: horizon
                port:
                  name: https-proxy
  extraTls:
    - hosts:
        - "horizon.local"
      secretName: horizon.local-tls

If you wish to use the Route resource instead, disable the ingress by setting ingress.enabled to false and manually create the route:

$ oc create route passthrough horizon --service=horizon --port=https-proxy --hostname=horizon.local

Using the router mTLS configuration

This method is no longer recommended since it requires deploying a specific ingress controller for Horizon purposes. Changing mTLS settings on an ingress controller affects all routes served by this ingress controller.

Follow the Kubernetes ingress controller configuration procedure. Gather all ACs identified in the previous step and create a bundle file containing all of them, called ca-bundle.pem.

Then, follow the Openshift documentation to configure the ingress controller serving Horizon requests to ask for client certificates signed by any of these ACs:

Upload the ACs to the OpenShift cluster in a configmap
$ oc create configmap router-ca-certs-default --from-file=ca-bundle.pem=ca-bundle.pem -n openshift-config
Tell the ingress controller to ask for client certificates
$ oc edit IngressController default -n openshift-ingress-operator

And set the following values:

apiVersion: operator.openshift.io/v1
kind: IngressController
metadata:
    name: default
namespace: openshift-ingress-operator
spec:
    clientTLS:
      clientCertificatePolicy: Optional
      clientCA:
        name: router-ca-certs-default

Then, when installing Horizon through the Chart, set the clientCertificateDefaultParsingType key to the value haproxy (which is what the Openshift ingress controller is based on).

As of 4.14, Openshift will only download CRLs from the certificates in the ca-bundle.pem chain (inferred from their CRLDPs). This can lead to a TLS handshake failure when authenticating using a client certificate. Introducing a dummy entity certificate in the chain might be required to ensure that the operational CAs CRLs are downloaded by the Openshift ingress controller. See this issue for more information.

Skip to the Ensure certificate authentication is effective section to test your configuration.