Skip to content

S3

The S3 target stores sealed segments in AWS S3 or a compatible HTTPS object store. Objects use the key <prefix>/<producer-id>/<sealed-segment-file>. Each target has its own explicitly configured credentials.

Properties

name

string

The unique, path-safe name of this target within the audit log.

type

string = "s3"

Selects the S3 target implementation. Type names are case-insensitive when read; Bifröst writes the canonical value s3.

publishAttemptTimeout

duration = "2m"

Positive deadline for one complete attempt: hashing, conditional upload, conflict check and cleanup. Timeout cancels the request; the next retry gets a fresh deadline.

bucket

string

The destination bucket. It must follow the AWS general-purpose bucket naming rules.

region

string = 

"{{ env \`AWS_REGION\` | default (env \`AWS_DEFAULT_REGION\`) }}"

The SigV4 signing region. This value supports Bifröst string templates without a context object. AWS_REGION takes precedence over AWS_DEFAULT_REGION; a non-empty result is required when the target is initialized.

prefix

string = ""

An optional object-key prefix without a leading or trailing slash. Empty and relative path components are rejected.

endpoint

URL

Optional absolute HTTPS endpoint without user information, path, query or fragment. Omitted: use AWS S3 for region; bucket and region bind the destination identity. Other providers require an explicit endpoint; AWS endpoint override environment variables are ignored.

Identify the destination

An explicit endpoint also requires destinationIdentity or expectedBucketOwner. Otherwise the same endpoint could select another namespace when credentials change, so startup fails closed.

pathStyle

bool = false

If true, addresses the bucket in the URL path instead of as a hostname. Enable this only when required by the selected S3-compatible service.

expectedBucketOwner

string

Optional twelve-digit AWS account ID sent with both PutObject and conflict-checking GetObject requests. AWS rejects the request when the bucket belongs to another account. Omit this AWS-specific protection for services that do not support it.

destinationIdentity

string = ""

Stable, non-secret tenant or namespace ID for S3-compatible endpoints without expectedBucketOwner. At most 256 bytes, no control characters. Changing it under an existing target name fails closed. Never use a credential or session token here.

accessKeyId

string = 

"{{ env \`AWS_ACCESS_KEY_ID\` | default (env \`AWS_ACCESS_KEY\`) }}"

Non-empty access key ID; supports a string template. AWS_ACCESS_KEY_ID takes precedence over AWS_ACCESS_KEY. Configure this and secretAccessKey together, or leave both at their defaults.

secretAccessKey

string = 

"{{ env \`AWS_SECRET_ACCESS_KEY\` | default (env \`AWS_SECRET_KEY\`) }}"

Non-empty secret access key; supports a string template. AWS_SECRET_ACCESS_KEY takes precedence over AWS_SECRET_KEY. Prefer an environment variable or file template over plaintext YAML.

sessionToken

string = 

"{{ env \`AWS_SESSION_TOKEN\` }}"

Optional session token; supports a string template. The AWS_SESSION_TOKEN default applies only when both access and secret keys also use their defaults. Set it explicitly for custom credentials.

Credentials and identity

Access key, secret key and session token are excluded from the durable destination identity; a complete temporary credential set may rotate without resetting the cursor. Use destinationIdentity or expectedBucketOwner to pin a credential-selected namespace.

Credential template results are not trimmed. Avoid trailing newlines in secret files. Bifröst does not use AWS profiles, instance metadata, web identity or other default credential providers.

Publication

  • PutObject uses If-None-Match: *; multipart uploads and overwrites are not used.
  • If the object already exists, GetObject must confirm both size and SHA-256. Different bytes are rejected.
  • S3-compatible services must support SigV4, conditional writes, SHA-256 checksums and GetObject. Verify these capabilities before choosing OVHcloud, MinIO, Ceph or Wasabi.

Permissions

The credentials need only these S3 actions on the configured bucket and prefix:

  • s3:PutObject to publish a sealed segment conditionally.
  • s3:GetObject to verify an object after a conditional-write conflict.

No s3:ListBucket, s3:DeleteObject or multipart-upload permission is needed. SSE-KMS may also require kms:GenerateDataKey for writes and kms:Decrypt for conflict checks.

Examples

AWS

With AWS_REGION, AWS_ACCESS_KEY_ID, and AWS_SECRET_ACCESS_KEY set for the Bifröst process, the default templates keep the target concise:

1
2
3
4
5
6
7
8
auditlog:
  - enabled: true
    targets:
      - name: aws-archive
        type: s3
        bucket: company-bifroest-audit
        prefix: bifroest-auditlog
        expectedBucketOwner: "123456789012"

S3-compatible (OVH)

This OVHcloud-style example uses an explicit endpoint and target-specific credential sources. Other targets can reference different environment variables or files in the same way.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
auditlog:
  - enabled: true
    targets:
      - name: ovh-archive
        type: s3
        bucket: company-bifroest-audit
        region: gra
        endpoint: https://s3.gra.io.cloud.ovh.net
        destinationIdentity: company-production-project
        accessKeyId: '{{ env `S3_ACCESS_KEY_ID` }}'
        secretAccessKey: '{{ env `S3_SECRET_ACCESS_KEY` }}'