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.

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:

1. Set mavenRegistry.groupId. The value must contain only alphanumeric characters, ., or _:

   mavenRegistry:
     groupId: "com.acme.gen"
   

2. Apply the chart.

3. As a BSR admin, clear previously generated Maven SDKs from the admin panel at https://your-bsr-instance.example.com/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.

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.

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.