On-prem BSR configuration#

This page documents Helm values that adjust an on-prem BSR’s runtime behavior. The values go in the bsr.yaml you maintain alongside the chart and take effect when you re-apply the chart.

For the initial install and the canonical helm upgrade --install command, see On-premise deployment with Kubernetes. For the upgrade procedure, see Upgrade your BSR.

Access and authentication#

Public access#

By default, the BSR requires authentication for every request. To allow unauthenticated users to view public modules and consume artifacts (such as generated SDKs) for those modules, set auth.allowPublicAccess:

auth:
  allowPublicAccess: true

Automatically provisioned memberships#

To add every signed-in user to a specific organization at login, set auth.autoProvisionedMembershipOrganizations:

auth:
  # Map of organizations every signed-in user is added to.
  autoProvisionedMembershipOrganizations:
    exampleorg: ORGANIZATION_ROLE_MEMBER

Valid role values: ORGANIZATION_ROLE_MEMBER, ORGANIZATION_ROLE_ADMIN, ORGANIZATION_ROLE_OWNER, ORGANIZATION_ROLE_MACHINE.

IdP session refresh#

When a signed-in user’s IdP session expires while they’re using the web UI, the BSR refreshes the session in the background using the IdP refresh token on the next XHR request from the frontend, so the user stays signed in without having to reload the page. This is enabled by default. If your IdP returns errors when a refresh token is exchanged, or you otherwise see refresh-token-related failures, disable refresh-on-fetch:

auth:
  enableSessionRefreshOnFetch: false

With this set to false, expired sessions are not refreshed in the background; the user has to reload the page to sign in again.

Feature flags#

A few BSR behaviors are gated behind individual feature flags under featureFlags. Each flag defaults to false (the feature is off):

featureFlags:
  # Prevent users from creating organizations in the BSR.
  # BSR admins can still create organizations when this flag is enabled.
  disable_user_org_creation: true
  # Allow creation of repositories owned by users (rather than organizations).
  enable_user_repository_creation: true
  # Automatically create BSR organizations from IdP group membership.
  # Requires IdP group setup; see the IdP groups guide.
  enable_auto_idp_org_provisioning: true

For enable_auto_idp_org_provisioning, see Automatically create organizations from IdP groups for the IdP-side configuration that has to be in place first.

Operational controls#

Maintenance mode#

Maintenance mode keeps the BSR running so health checks pass, but blocks API calls and database/object-storage writes. Users hitting the web UI see a maintenance message.

maintenance: true

This is the supported posture for an upgrade window; see Upgrade your BSR.

Maximum body size#

The BSR caps incoming request bodies at 256 MB by default. Raise the cap when uploading large custom plugins or modules:

maxBodySizeBytes: "2147483648" # 2 GB

Sandbox error visibility#

When sandbox plugin execution fails, the BSR returns an opaque internal error by default so plugin internals don’t leak into user-visible responses. To surface the underlying sandbox stderr and exit code in API responses, set:

exposeSandboxErrors: true

Use this as a debugging aid while tracking down a misbehaving plugin, not as a default production setting: error payloads will include sandbox-internal details that aren’t normally part of the BSR’s public API.

Pod resource requests and limits#

The BSR ships with default resource requests that work for most clusters. Tune them when you see:

OOMKilled pod events or repeated restarts: raise the matching deployment’s memory request and consider adding a limits.memory.
Code-generation timeouts or sandbox failures on the status page: raise sandbox or sandbox.runtime resources.
Slow API latency under load: raise bufd resources.

bufd:
  deployment:
    resources:
      requests:
        cpu: 800m
        memory: 2Gi
      # No limits are set by default; configure them with the values below.
      # limits:
      #   cpu: ""
      #   memory: 2Gi
sandbox:
  deployment:
    resources:
      requests:
        cpu: 300m
        memory: 1Gi
    # limits:
    #   cpu: ""
    #   memory: 1Gi
  runtime:
    deployment:
      resources:
        requests:
          cpu: 800m
          memory: 2Gi
        # limits:
        #   cpu: ""
        #   memory: 2Gi
  java:
    # Per-request resource limits for Java/Kotlin Maven SDK compilation containers.
    # 0 uses the defaults (1 vCPU and 2 GB).
    # See "Maven registry Java compilation limits" for details.
    cpuLimitNanos: 0 # e.g. 4000000000 for 4 vCPUs
    memoryLimitBytes: 0 # e.g. 4294967296 for 4 GiB
ociregistry:
  deployment:
    resources:
      requests:
        cpu: 300m
        memory: 512Mi
    # limits:
    #   cpu: ""
    #   memory: 512Mi

Email notifications#

SMTP server#

To send email for the breaking-change review flow, configure the SMTP server under notifications:

notifications:
  use: smtp
  smtp:
    hostname: "smtp.example.com"
    port: 25
    # The username for authenticating with the SMTP server.
    username: example-user
    # The domain attached to the From: address on outgoing email.
    fromDomain: "notification.example.com"

Then create a Kubernetes secret with the SMTP password:

$ kubectl create secret --namespace bsr generic bufd-smtp-password \
  --from-literal=password=<smtp password>

Maven generated SDKs#

Custom groupId#

The BSR’s Maven registry derives the groupId for generated SDKs from the BSR hostname: reversed hostname plus .gen. The public BSR (buf.build) uses build.buf.gen. To use a different groupId on a private instance:

Set mavenRegistry.groupId. The value must contain only alphanumeric characters, ., or _:
```
mavenRegistry:
  groupId: "com.acme.gen"
```
Apply the chart.
As a BSR admin, clear previously generated Maven SDKs from the admin panel at https://buf.build/admin/plugin-management. Old assets still carry the previous groupId until they’re regenerated.

Generation timeout#

Code generation for the Maven registry times out after mavenRegistry.generationTimeout, which defaults to 5m. Raise the limit for large modules:

mavenRegistry:
  generationTimeout: "10m" # 10 minutes

Java compilation limits#

Java and Kotlin Maven SDK compilation runs inside per-request containers in the sandbox. By default, each compilation container is limited to 1 vCPU and 2 GB of memory. For large modules, raise the limits to avoid out-of-memory errors and slow compilations. Set sandbox.java.cpuLimitNanos and sandbox.java.memoryLimitBytes; see the sandbox section above.

Preserve file options#

By default, the BSR applies managed mode defaults to the java_multiple_files, java_outer_classname, and java_package file options when generating Maven SDKs.

To instead preserve the file options declared in each module’s .proto files:

Set mavenRegistry.preserveFileOptions to true:

mavenRegistry:
  preserveFileOptions: true

Apply the chart.
As a BSR admin, clear previously generated Maven SDKs from the admin panel at https://buf.build/admin/plugin-management. Old assets still carry the previous setting until they’re regenerated.

npm generated SDKs#

Custom scope#

The BSR’s npm registry uses a configurable scope for generated SDK packages, which defaults to @bufteam on private instances. To use a different scope:

Set npmRegistry.registryScope. The value must start with @ and contain at most 32 characters after it:
```
npmRegistry:
  registryScope: "@acme"
```
Apply the chart.

Policy enforcement#

The BSR allows BSR admins to upload and enforce policies (shared sets of lint and breaking-change rules). Server-side policy enforcement is enabled by default on on-prem instances, which gives the registry a central schema-governance layer independent of each repository’s local buf.yaml. Set enableServerPolicyEnforcement: false to turn it off:

enableServerPolicyEnforcement: false # Enabled by default; set to false to disable.

Remote plugin and module updates#

By default, the BSR sources Buf-managed plugins and modules from the in-cluster bufpluginsd and bufmodulesd services packaged with each release, so a default instance stays fully air-gapped.

Optionally, you can point the BSR at our remote plugin and modules storage, so the instance picks up the latest Buf-managed plugins and modules rather than the set bundled with the release. Set managed.plugins.storage.url and managed.modules.storage.url:

managed:
  plugins:
    storage:
      url: "https://plugins.buf.build"
  modules:
    storage:
      url: "https://modules.buf.build"

This is off by default. When url is empty, the BSR falls back to the in-cluster feeds. Setting a URL makes the BSR reach out to the configured remote, so the instance is no longer air-gapped.

Platform-specific fixes#

EKS Auto Mode / Bottlerocket#

The BSR uses gVisor to sandbox plugin execution. gVisor requires user.max_user_namespaces > 0, but Bottlerocket (used by EKS Auto Mode) sets that sysctl to 0 by default.

The symptom: plugin execution fails with an error like

run: starting container: Error response from daemon: failed to create task for container: failed to create shim task: OCI runtime create failed: creating container: cannot create gofer process: gofer: fork /exec /proc/self/exe: no space left on device: unknown

To fix, add a privileged init container to the sandbox deployment that raises the kernel parameter:

sandbox:
  extraInitContainers:
    - name: sysctl-max-user-ns-fix
      image: docker.io/library/busybox:1.37
      command: ["sh", "-euxc", "sysctl -w user.max_user_namespaces=63359"]
      securityContext:
        privileged: true

If you control the Bottlerocket user data, the equivalent kernel setting works without an init container:

[settings.kernel.sysctl]
"user.max_user_namespaces" = "63359"

Undocumented values#

The chart defines additional Helm values that aren’t documented here. They’re considered internal and may change between releases. Before depending on one, contact Buf Support or your Buf representative so the configuration can be supported across upgrades.