Static Sites Authenticating Proxy

This project provides the core of the new static sites infrastructure.

gitlab-pages alone doesn't perform any authentication thus the need for httpd in front of it. httpd, if configured, authenticates users before proxying all requests to gitlab-pages pods. gitlab-pages uses Host header to determine which assets the client is requesting (value of the Host should be the same as one of the repository custom domains defined in the Pages section).

httpd's extra configuration is stored in a special Secret in the same namespace and every change in the Secret value results in an automatic reload of the configuration. Each configuration file (key in the Secret) is automatically generated by gitlab-pages-site-operator.

The Helm chart in this project deploys the following components for GitLab Pages integration with web frameworks:

httpd authenticating proxy

A single httpd deployment provides:

• a web server which reads vhost configuration from a specific Secret in its namespace. The gitlab-pages-sites operator will populate this Secret with VirtualHost definitions for each user-created GitlabPagesSite resource. Each VHost will be for a hostname of a GitLab pages site (typically a "custom domain" configured in GitLab). Each VHost authenticates requests with CERN SSO if site isn't configured for anonymous access and proxies the request to the actual gitlab-pages pods, which are not directly reachable. In order to make sure httpd is using the latest configuration there is a special sidecar container that sends a special signal to httpd master process instructing it to reload its configuration.

• a secondary web server (pagesWildcardHandler) to handle requests for Gitlab Pages sites that have NOT set up a GitlabPagesSite resource. It handles requests to *.pages(-dev).cern.ch (the wildcard GitLab pages domain) but does not serve the gitlab pages site: it instead shows user instructions to finalize their gitlab pages site setup by creating a GitlabPagesSite resource.

By default, gitlab pages sites will want to use a URL under *.pages(-dev).cern.ch but we DO NOT allow gitlab-pages sites to be accessible via *.pages(-dev).cern.ch: instead we want every gitlab-pages site to be registered as a web frameworks site so CERN SSO can be used for access control. So we show instructions to finalize the gitlab-pages site setup with web frameworks (from gitlab pages' point of view, this will be a custom domain) the default URL *.pages(-dev).cern.ch

The pagesWildcardHandler secondary web server handles a wildcard domain so has strong requirements on its host OKD4 cluster:

• we need a wildcard route, so the router shard must be configured to allow wildcard routes
• we need the DNS record for *.<pages domain>, so the GitLab pages domain must be in one of the cluster's DNS "shared subdomains" (see docs/design/ingress-design.md in okd4-install) so there is an instance of external-dns managing the DNS record.
• we need a wildcard certificate, which we'll request from Let's Encrypt. Thus we need a functional cert-manager deployment supporting DNS-01 challenges.

TODO: add a second deployment of the gitlab-pages web server integrated with GitLab authentication and proxy the URLs necessary to provide a HTML artifacts server - see https://gitlab.cern.ch/vcs/oo-gitlab-cern/-/merge_requests/294 for a first prototype.

gitlab-pages webserver

This is the only component from the gitlab Helm chart which we deploy and which is required for the new generation of the static sites. We should remember to keep it in sync with the version of GitLab hosted at gitlab.cern.ch. It won't hurt if it is behind a few minor versions since the gitlab-pages component is not tightly coupled with GitLab. However, new versions might introduce new interesting features, e.g. support for more Netlify style redirects

Upgrade Gitlab helm chart

Before upgrading the version of the chart, pay attention to the version you are going to deploy because there is no logical mapping between chart versions and GitLab versions. For every update, see https://docs.gitlab.com/charts/installation/version_mappings.html but it may not contain the latest chart releases. Latest info in https://gitlab.com/gitlab-org/charts/gitlab/-/tags.

You can check which GitLab version is deployed at CERN here.

To upgrade the chart, first update the Chart.yaml file with the new version and then run:

cd chart
helm dependency update

and then commit and push the changes.

Secret prefix and count

IMPORTANT!! The httpd.virtualHost.secret.count and httpd.virtualHost.secret.prefix cannot be changed and deployed wihtout proper preparation. If the count number increase, this will end up with dupplicate vhosts. Also bear in mind that although the secrets are created by this helm chart, they are then populated by gitlab-pages-site-operator. That means that both prefix and count have to be aligned with the gitlab-pages-site-operator configuration.

The current number of GPS supported is around 1500 vhosts per secret (currently 10) , which will give us enough room to think on a different approach.

Future work

The use of a shared secret between this operator and the proxy server is not ideal. It doesn't scale well and requires an extra syncronization between the operator and the proxy. A better approach should be to use something similar as WebEOS does, using a custom resource to generate vhosts config files on a side car and eventually mounted in the proxy server.