S3 Configuration

Configuration parameters for integrating your Onyxia service with S3.

The installation guide provides instructions on how to set up Minio with a basic configuration. However, you may want more control or need to connect to a different S3-compatible system.

Below are all the available configuration options.

apps/onyxia/values.yaml
onyxia:
  api:
    regions: [
      {
        # ...
        data: {
          S3 : { ... } # ...See expected format below
        }
      }
    ]
type S3 = {
  /**
   * The URL of the S3 server.
   * Examples: "https://minio.lab.sspcloud.fr" or "https://s3.amazonaws.com".
   */
  URL: string;

  /**
   * The AWS S3 region. This parameter is optional if you are configuring
   * integration with a MinIO server.
   * Example: "us-east-1"
   */
  region?: string;

  /**
   * This parameter informs Onyxia how to format file download URLs for the configured S3 server.
   * Default: true
   *
   * Example:
   * Assume "https://minio.lab.sspcloud.fr" as the value for region.data.S3.URL.
   * For a file "a/b/c/foo.parquet" in the bucket "user-bob":
   *
   * With pathStyleAccess set to true, the download link will be:
   *   https://minio.lab.sspcloud.fr/user-bob/a/b/c/foo.parquet
   *
   * With pathStyleAccess set to false (virtual-hosted style), the link will be:
   *   https://user-bob.minio.lab.sspcloud.fr/a/b/c/foo.parquet
   *
   * For MinIO, pathStyleAccess is typically set to true.
   * For Amazon Web Services S3, is has to be set to false.
   */
  pathStyleAccess?: boolean;

  /**
   * Defines where users are permitted to read/write S3 files,
   * specifying the allocated storage space in terms of bucket and object name prefixes.
   *
   * Mandatory unless data.S3.sts is not defined then it's optional.
   *
   * Example:
   * For a user "bob" in the "exploration" group, using the configuration:
   *
   * Shared bucket mode, all the users share a single bucket:
   *   "workingDirectory": {
   *       "bucketMode": "shared",
   *       "bucketName": "onyxia",
   *       "prefix": "user-",
   *       "prefixGroup": "project-"
   *   }
   *
   * In this configuration Onyxia will assumes that Bob has read/write access to objects starting
   * with "user-bob/" and "project-exploration/" in the "onyxia" bucket.
   *
   * Multi bucket mode:
   *   "workingDirectory": {
   *       "bucketMode": "multi",
   *       "bucketNamePrefix": "user-",
   *       "bucketNamePrefixGroup": "project-",
   *   }
   *
   * In this configuration Onyxia will assumes that Bob has read/wite access to the entire
   * "user-bob" and "project-exploration" buckets.
   *
   * If STS is enabled and a bucket doesn't exist, Onyxia will try to create it.
   */
  workingDirectory?:
    | {
        bucketMode: "shared";
        bucketName: string;
        prefix: string;
        prefixGroup: string;
      }
    | {
        bucketMode: "multi";
        bucketNamePrefix: string;
        bucketNamePrefixGroup: string;
      };
  /**
   * Defines a list of S3 directory bookmarks to display in the user's file explorer interface.
   * 
   * Bookmarks can be:
   * - Static: shown to all users.
   * - Dynamic: shown only if specific conditions based on the user's identity token are met.
   *
   * Each bookmark must define:
   * - `fullPath`: The absolute S3 path to the bookmarked folder.
   * - `title`: The display title, supporting dynamic content via template variables.
   * - `description` (optional): A short description of the bookmark.
   * - `tags` (optional): An array of LocalizedString tags for UI categorization.
   *
   * For static bookmarks:
   * - Set `claimName` to `undefined` (or omit it entirely).
   * - The bookmark is shown to all users.
   *
   * For dynamic bookmarks:
   * - Set `claimName` to the name of a claim (e.g., `"groups"`) from the user's **ID token**.
   * - The ID token is the one issued by the **OIDC configuration associated with the S3 client** (i.e., from `sts.oidcConfiguration`).
   * - `includedClaimPattern` is a regular expression that must match at least one value in the specified claim for the bookmark to be shown.
   * - `excludedClaimPattern` is a regular expression that, if matched by any value in the claim, causes the bookmark to be ignored.
   * - If a `claimValue` matches both, exclusion takes precedence (i.e., the bookmark is not shown).
   *
   * Template placeholders:
   * - `$1`, `$2`, ...: inserts corresponding capture groups from `includedClaimPattern` (useful for custom rendering in `fullPath`, `title`, `description`, or `tags`).
   *
   * 🔁 Example (static):
   * ```json
   * {
   *   "bookmarkedDirectories": [
   *     {
   *       "fullPath": "data/public",
   *       "title": {
   *         "fr": "Données publiques",
   *         "en": "Public Data"
   *       },
   *       "description": {
   *         "fr": "Dossier partagé contenant des jeux de données publics.",
   *         "en": "Shared folder containing public datasets."
   *       },
   *       "tags": [
   *         {
   *           "fr": "lecture seule",
   *           "en": "read-only"
   *         }
   *       ]
   *     }
   *   ]
   * }
   * ```
   *
   * 🔁 Example (dynamic):
   * ```json
   * {
   *   "bookmarkedDirectories": [
   *     {
   *       "fullPath": "group-$1/",
   *       "claimName": "groups",
   *       "includedClaimPattern": "^group-(.*)$",
   *       "excludedClaimPattern": "^group-secret$",
   *       "title": "Group: $1",
   *       "description": "Files accessible to group $1",
   *       "tags": ["group", "$1"]
   *     }
   *   ]
   * }
   * ```
   */
  bookmarkedDirectories?: ({
    fullPath: string;
    title: LocalizedString;
    description: LocalizedString | undefined;
    tags: LocalizedString[] | undefined;
  } & (
    | { claimName: undefined }
    | {
        claimName: string;
        includedClaimPattern: string;
        excludedClaimPattern: string;
      }
  ))[];
  /**
   * Configuration for Onyxia to dynamically request S3 tokens on behalf of users.
   * Enabling S3 allows users to avoid manual configuration of a service account via the Onyxia interface.
   */
  sts?: {
    /**
     * The STS endpoint URL of your S3 server.
     * For integration with MinIO, this property is optional as it defaults to region.data.S3.URL.
     * For Amazon Web Services S3, set this to "https://sts.amazonaws.com".
     */
    URL?: string;

    /**
     * The duration for which temporary credentials are valid.
     * AWS: Maximum of 43200 seconds (12 hours).
     * MinIO: Maximum of 604800 seconds (7 days).
     * Without this parameter, Onyxia requests 7-day validity, subject to the S3 server's policy limits.
     */
    durationSeconds?: number;

    /**
     * Optional parameter to specify RoleARN and RoleSessionName for the STS request.
     *
     * Example:
     *   "role": {
     *     "roleARN": "arn:aws:iam::123456789012:role/onyxia",
     *     "roleSessionName": "onyxia"
     *   }
     */
    role?: {
      roleARN: string;
      roleSessionName: string;
    };

    /**
     * See: https://docs.onyxia.sh/admin-doc/openid-connect-configuration#oidc-configuration-for-services-onyxia-connects-to
     */
    oidcConfiguration?: OidcConfiguration;
  };
};

Last updated

Was this helpful?