DOCSEARCHbyAlgolia
Submit Docs

REANA (Reusable Analyses)

repository·master·Indexed 41 days ago

https://github.com/reanahub/reana

A platform for structuring, preserving, and executing reproducible scientific research workflows using containerized environments. Documentation covers Helm chart deployment, OIDC and Keycloak authentication configuration, custom Jupyter image integration, and sandbox network isolation for workflow specification validators.

Tokens
26K
Snippets
52
Records
93
Agent score
100%

What's inside REANA

  1. Overview of REANA - Reusable Analyses

    master
    REANA is a platform designed for reusable and reproducible research data analysis. It enables researchers to structure input data, analysis code, containerized environments, and computational workflows so they can be instantiated and executed on remote compute clouds. While originally designed for particle physics, it is applicable to any scientific discipline requiring long-term preservation and reinterpretation of data analyses.

  2. Security Note: Jupyter Session URL Exposure

    master

    When opening a Jupyter session, the access token is passed as a ?token=... query parameter in the browser URL. This has two security implications:

    1. Browser History: The URL (including the token) is written to the browser's local history.
    2. Ingress/Proxy Logs: Any reverse proxy or ingress controller that logs full request URIs will record the token in its access logs.

    Mitigation:

    • The chart includes a Referrer-Policy: no-referrer middleware on interactive-session Ingress to prevent token leakage via the Referer header.
    • Action for users: If you have strict security requirements, configure your ingress controller to exclude or redact query strings for session paths from its access logs.

  3. Key features of REANA

    master

    REANA provides the following capabilities for scientific workflows:

    • Workflow Structuring: Organize research data analysis in a reusable manner.
    • Cloud Execution: Instantiate computational workflows on remote clouds.
    • Reproducibility: Rerun analyses with modified input data, parameters, or code.
    • Compute Support: Supports multiple compute clouds, including Kubernetes and OpenStack.
    • Workflow Specifications: Supports CWL, Serial, Yadage, and Snakemake.
    • Storage & Containers: Supports shared storage systems like Ceph and container technologies like Docker.

  4. Getting started with REANA

    master

    To begin using REANA, you can choose one of the following deployment paths:

    1. Local Installation: Install REANA on your local machine.
    2. On-Premises Deployment: Deploy REANA at scale on your own infrastructure (can be done in approximately 10 minutes).
    3. Managed Instance: Use the hosted instance at https://reana.cern.ch.

    Once your environment is set up, follow the guide to run your first example. For comprehensive details, refer to the official REANA documentation.

  6. Use Custom Jupyter Images for Interactive Sessions

    master

    Administrators can enable custom Jupyter images by setting interactive_sessions.environments.jupyter.allow_custom.

    Requirement: Custom images must implement the Jupyter Docker Stacks launch contract. Specifically, the image must:

    1. Provide a start-notebook.sh executable.
    2. Ensure the launcher passes the NOTEBOOK_ARGS environment variable to the Jupyter process.

    REANA uses NOTEBOOK_ARGS to inject a random per-session access token. If an image ignores this variable, the session will lack REANA's per-session access control.

    Reserved Environment Variables: REANA owns the following variables for interactive sessions. User-secret configurations cannot override these. If you have existing user secrets with these names, rename them before upgrading to avoid collisions:

    • NOTEBOOK_ARGS
    • NB_GID
    • NB_UMASK
    • REANA_WORKSPACE

  7. Configure Authentication for REANA Helm Chart

    master

    REANA requires an authenticated deployment. The Helm chart does not deploy an identity provider by default and will refuse to render if neither an external OIDC issuer nor bundled Keycloak is enabled.

    External OIDC Issuer

    To use an external provider, configure the auth values. If auth.bffEnabled is set to true, you must provide the client secret via the secrets.auth.REANA_AUTH_WEB_CLIENT_SECRET secret.

    Bundled Keycloak (Development/Small Scale)

    Keycloak is intended for local development or small test deployments. It is disabled by default.

    • Database Modes:
      • Default: Uses a dedicated database and role on the chart's bundled PostgreSQL service.
      • External: Set keycloak.database.mode=external. The database and role must already exist.
      • Ephemeral: Set keycloak.database.mode=ephemeral. This is for development only; replacing the pod loses all identities and signing state.
    • HTTPS: The public issuer always uses HTTPS. For private issuers, provide a CA bundle path using auth.caBundle.

    Administrator Setup

    If using reana-dev cluster-deploy, the administrator is not created automatically because the tool cannot discover external subjects. You must manually run: flask reana-admin create-admin-user (providing the required issuer and subject) before the first login.

    # Example configuration concepts
auth:
  clientId: "YOUR_CLIENT_ID"
  webClientId: "YOUR_WEB_CLIENT_ID"
  caBundle: "/path/to/ca"
keycloak:
  database:
    mode: "external" # or "ephemeral"
secrets:
  auth:
    REANA_AUTH_WEB_CLIENT_SECRET: "YOUR_CLIENT_SECRET"

  8. Verify sandbox network isolation with enforcement tests

    master

    After deploying REANA, you can run live enforcement tests to verify that the validator's network policies are working as expected. These tests require an OIDC access token.

    Test network policy enforcement

    Run the following script to check if the validator is restricted from the public internet. The final argument (true or false) indicates whether the validator is expected to retain access to the public internet.

    $ REANA_ACCESS_TOKEN="<OIDC-access-token>" \
    scripts/test-spec-validator-network-policy.sh default reana true

    Test storage and service isolation

    Run this script to verify that the validator cannot connect to the REANA server Service or its backing pod. This exercises the validation-snapshot and input-upload contracts.

    $ REANA_ACCESS_TOKEN="<OIDC-access-token>" \
    scripts/test-spec-validation-storage.sh default reana

    Test Behavior: The test triggers specification validation and creates a short-lived pod. If the test reports resident-node access, it is because standard Kubernetes NetworkPolicy does not guarantee that traffic to the node itself is blocked.

  9. Configure sandbox isolation prerequisites for REANA

    master

    The REANA workflow specification validator executes untrusted code within a sandbox. To ensure security, your Kubernetes cluster must meet the following requirements:

    1. CNI Support: The cluster must use a CNI plugin that enforces Kubernetes NetworkPolicy. The validator creates a NetworkPolicy before execution.
    2. Policy Additivity: Ensure that no other existing policies applied to validator pods widen their egress permissions.
    3. Host Endpoint Protection: Because standard NetworkPolicy may still permit traffic to the local node, multi-tenant environments should use a CNI or host firewall capable of filtering host endpoints, or schedule validators on dedicated hardened nodes.

    Note: An accepted policy object does not guarantee isolation; operators must verify forbidden egress on their specific cluster configuration.

  10. Uninstall REANA and Purge Secrets

    master

    Running helm uninstall does not delete the chart's Secrets. They are preserved using helm.sh/resource-policy: keep so that a reinstallation can reuse existing credentials (database, Keycloak, OIDC, etc.).

    To perform a full purge of all resources associated with a release, you must manually delete the secrets using the release name prefix. For a release named reana, use:

    kubectl get secrets -o name | grep '^secret/reana-' | xargs --no-run-if-empty kubectl delete
    $ kubectl get secrets -o name | grep '^secret/reana-' | xargs --no-run-if-empty kubectl delete

  12. Configure Keycloak authentication

    master

    REANA uses Keycloak for authentication. When using the bundled Keycloak, you can configure the following settings in your Helm values.yaml:

    • keycloak.required_role: The coarse realm role required by REANA (default: reana:user).
    • keycloak.cli_client_id: The public/device-flow client ID for the REANA CLI (default: reana-cli).
    • keycloak.web_client_id: The confidential browser client ID for the REANA server (default: reana-server).
    • keycloak.admin_user: The bootstrap administrator username.
    • keycloak.admin_password: The bootstrap administrator password. Security Note: Do not save this in values.yaml. Pass it to Helm using the --set flag during installation.
    • keycloak.network_policy.enabled: Enables/disables an ingress NetworkPolicy for bundled Keycloak.
    • keycloak.network_policy.ingress_controller_peers: Defines the Kubernetes NetworkPolicy peers allowed to proxy browser traffic to Keycloak. Defaults are configured for Traefik in the same namespace or kube-system K3s Traefik.