Snowbridge 6.x upgrade guide

Version 6.0.0 breaking changes

Version 6.0.0 restructures the HTTP target's OAuth2 settings, changes the values returned by the hash transformation helper, and rebuilds the Docker images on a distroless base. Only the OAuth2 change requires a configuration edit, but review each section below before upgrading.

HTTP target OAuth2 configuration

The four top-level oauth2_* settings have been replaced by an oauth_client {} block. This makes room for the new JWT bearer flow, which is configured through a separate oauth_jwt {} block.

v5 setting (top-level)	v6 setting (inside oauth_client {})
oauth2_client_id	client_id
oauth2_client_secret	client_secret
oauth2_refresh_token	refresh_token
oauth2_token_url	token_url

Migration required: move your OAuth2 credentials into an oauth_client {} block.

Before:

hcl

target {
  use "http" {
    url                  = "https://acme.com/x"
    oauth2_client_id     = env.CLIENT_ID
    oauth2_client_secret = env.CLIENT_SECRET
    oauth2_refresh_token = env.REFRESH_TOKEN
    oauth2_token_url     = "https://my.auth.server/token"
  }
}

After (6.0.0):

hcl

target {
  use "http" {
    url = "https://acme.com/x"

    oauth_client {
      client_id     = env.CLIENT_ID
      client_secret = env.CLIENT_SECRET
      refresh_token = env.REFRESH_TOKEN
      token_url     = "https://my.auth.server/token"
    }
  }
}

oauth_client {} and oauth_jwt {} are mutually exclusive — configuring both fails at startup.

hash transformation helper

The hash helper available in custom scripts and jq transformations returns the digest of the chosen hash function, rather than a PBKDF2-derived key.

Output values change, but no configuration change is required:

• Unsalted hashing returns the plain digest of the selected function.
• Salted hashing returns an HMAC of the input, keyed with the salt.
• Output length follows the selected function — 40 hex characters for sha1, 64 for sha256, 32 for md5 — instead of the fixed 48 hex characters produced by PBKDF2.

Migration required if you depend on hash values matching data produced by earlier versions. Values hashed by Snowbridge 6.x will not match values hashed by 5.x or earlier for the same input, so any downstream joins, deduplication, or identity stitching on a hashed field will break across the upgrade boundary. Where a destination stores previously hashed values, plan for the change of value — for example by re-hashing historical data, or by switching to a new field.

Distroless Docker images

Both the main and AWS-only images are built on gcr.io/distroless/static-debian12:nonroot instead of Alpine. The image contains only the Snowbridge binary — there is no shell, package manager, or other userland.

This has no effect on how Snowbridge is configured or run, but it does change a few operational details:

• docker exec into a running container no longer works — there is no sh or busybox to exec into. Use logs and metrics for debugging instead.
• The container runs as UID/GID 65532:65532 (the distroless nonroot user) rather than the Alpine-created snowplow user. If you mount a config file or TLS certificates into the container, make sure they are readable by that UID.
• Anything in your deployment that installs packages into the image or runs shell commands in it (for example a shell-based health check, or an entrypoint wrapper script) needs to be reworked.

Go module path

The Go module path is github.com/snowplow/snowbridge/v6. This only affects you if you import Snowbridge packages in your own Go code — for example the HTTP target's request templater. Update your imports from github.com/snowplow/snowbridge/v5/... to github.com/snowplow/snowbridge/v6/....