Site application architecture¶

This page is the index for the applications that compose a Site pod. It defines the registry contract and the shared container contract: what each class must provide, and what the exporter renders from it.

The applications:

• built-in Site applications — sets, selection, Service behaviour, resource tiers, and build metadata
• site initializer
• site OAuth2
• site proxy
• site API
• site admin
• site WebDAV
• site S3
• custom applications
• content mirror

Path shortcuts: site/.../applications/ is site/src/ecmwf/sites/website/applications/; Lua and nginx paths are relative to site/.../applications/proxy/.

The model side of the registry — class flags, application selection from spec.configuration.applications, image override, and upgrade behaviour — is in domain model. This page covers the deployment contract: containers, Service ports, and route paths.

Registry contract¶

Each application module under site/src/ecmwf/sites/website/applications/<name>/app_config.py registers a SiteApplicationConfiguration subclass in the singleton SiteApplicationRegistry (core/src/ecmwf/sites/core/model/site_apps_registry.py). Base-class attribute defaults matter: a new built-in application is a basic application (IS_BASIC = True) unless it says otherwise.

Each application implements three abstract methods, and may override the rest:

For each Site, ConfiguredSiteApplications aggregates the selected instances:

• get_init_containers() — containers of the init applications.
• get_containers() — containers of the selected normal applications.
• get_service_ports() — ports of the applications where is_to_expose_clusterwide() is true.
• get_ingress_path() — the ingress path of the first application where is_to_expose_worldwide() is true. Today only site-oauth2 qualifies.

A new built-in application must register its class and provide the three abstract methods. Display helpers (pretty_name, get_urls, get_hub_view_url, to_dict) build on NAME, DESCRIPTION, and the application path attribute.

Application matrix¶

The "own path" column is the path attribute each application class sets. For site-api, site-admin, site-webdav, and site-s3 it is the location the proxy serves under the Site URL (<site> is the Site path); those applications are reached through the proxy, not through a route or Service path of their own. Only site-oauth2 provides a route path, which is the Site path itself. The proxy location configuration is in Site proxy.

Shared container contract¶

SiteExporter renders one StatefulSet per Site. The Pod carries three volumes: site-volume (the Site persistent volume claim (PVC), read-write), site-config (the files ConfigMap <id>-files), and oidc-client-secret (only the OIDC_CLIENT_SECRET key of oidc-secrets, as the file client-secret, mode 0440). Seven applications build their container through the shared _container() helper in core/src/ecmwf/sites/core/model/site_app_config.py. What it sets:

• Configuration sources (envFrom): the per-site Secret <id> and the per-site environment ConfigMap <id>. No container gets the platform Secret oidc-secrets through envFrom. The chart creates oidc-secrets from secrets.oidcSecrets values (platform configuration).
• Environment: the decoded extra_env entries, then PORT (the container port), then the variables that the application gives in the extra_env parameter of _container(), then the masked variables. Only site-proxy gives such variables: OIDC_CLIENT_ID and OIDC_CLIENT_SECRET, each a secretKeyRef to one key of oidc-secrets, and OIDC_EXTRA_AUDIENCES, a plain value from oidc.extra_audiences (not a Secret). The Lua code of the proxy reads them. Because they come after the application extra_env entries, a site value with the same name does not replace them (site/tests/test_oidc_secret_scope.py). The masked variables (SITE_MASKED_ENVIRONMENT_NAMES, core/.../config/constants.py) are NAMESPACE and the KUBERNETES_* variables of the kubernetes Service, each with an empty value. Kubelet always injects the KUBERNETES_* variables, also with enableServiceLinks: false. A pod cannot remove them, but a container variable with the same name replaces them. The masked variables come after extra_env, so that an extra_env entry cannot set them. The initializer and the mirror build their own containers, and they also get the masked variables.
• Volume mounts: site-volume at /www, plus each application's own site-config subPath mounts (for example the proxy mounts admin.conf; the OAuth2 application mounts its two configuration files and the error page).
• OAuth2 Proxy secrets: only site-oauth2 mounts oidc-client-secret, read-only, at /opt/sites/sites/site/oauth2/secrets (clientSecretFile in alpha-oauth2.cfg). It also gets OAUTH2_PROXY_COOKIE_SECRET from the key cookie-secret of the Secret <id>-oauth2, as its last environment entry, so that an extra_env entry cannot replace it. The custom application gets neither.
• Security context: allowPrivilegeEscalation=false, runAsNonRoot=true, privileged=false. The helper accepts read_only_root_filesystem (default false); no built-in application enables it. The Pod runs as user/group 65534 and mounts no ServiceAccount token (03).
• Resources: memory limit always set, CPU request always set, CPU limit only when the tier value sets it explicitly. This follows the _limit_range best practice: CPU is request-only unless a limit is named.
• Image pull policy: the class default IMAGE_PULL_POLICY from kubernetes.image_pull_policy. site-custom overrides it to Always, because user images are mutable tags.

Liveness probes only: no application defines a readiness or startup probe.

The four Go applications (site-oauth2, site-api, site-admin, site-webdav) also set GOGC=50 and GOMEMLIMIT to 90 % of the effective tier memory maximum, so the garbage collector stops before the container hits its cgroup limit.

Two applications bypass _container() and build the container directly:

• site-initializer: environment sources are the Secret <id> and the ConfigMap <id> — no OpenID Connect (OIDC) Secret, no ports, no environment variables, no probes, and no security context (the Pod-level settings still apply). It mounts the Site volume.
• site-mirror: a normal container with no listener. It sets its own security context (the same three flags, root filesystem writable), mounts the Site volume, takes the Secret <id> and ConfigMap <id> through envFrom, and receives its MIRROR_* settings as direct env entries rendered from the platform migration settings (empty when migration.enabled is false). The same values are also added to the files ConfigMap by get_config_map_values; the mirror test asserts both copies agree. See content mirror.

flowchart LR
    R["Ingress or HTTPRoute"] --> O["site-oauth2"]
    O --> P["site-proxy"]
    P --> A["site-api"]
    P --> B["optional or custom backend"]
    I["init containers"] --> V[("Site PVC /www")]
    P --> V

The OAuth2 Proxy upstream is the proxy on 127.0.0.1:8080, rendered into alpha-oauth2.cfg. Browser traffic therefore always passes authentication (site-oauth2), then the proxy location and auth chain (site-proxy), before it reaches a backend application.

Image and selection rules¶

Built-in images use:

<kubernetes.private_registry>/<kubernetes.private_registry_project>/<application>:<site.version>

An image in spec.configuration.applications overrides the built-in image. A normal application is selected only when its entry supplies both a name and a non-empty image (03). An upgrade rewrites built-in image versions. It preserves the image of site-custom because the platform cannot determine its compatible version.

The application list is part of the Site resource. Adding or removing an application is therefore a Site update and follows the operator update flow in site lifecycle and reconciliation.

Behaviour requirements¶