Skip to content

Optional configuration#

Maintenance mode#

The BSR has a maintenance mode in which the BSR starts up, but API calls are prevented, users of the web interface are informed that maintenance is in progress, and no database/object storage writes occur.

To enable the maintenance mode, set the maintenance Helm value and re-apply the Helm chart:

maintenance: true

Feature flags#

Certain BSR functionality is gated behind feature flags and can be enabled through featureFlags Helm values:

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
  enable_user_repository_creation: true
  # Automatically create organizations from IdP groups
  enable_auto_idp_org_provisioning: true

Automatically adding members to organizations#

To automatically add all members to an organization upon login, set the auth.autoProvisionedMembershipOrganizations Helm value:

auth:
  # Map of organizations which all members will be added to on login
  autoProvisionedMembershipOrganizations:
    exampleorg: ORGANIZATION_ROLE_MEMBER

SMTP server for email notification#

To send email notifications for the breaking change check review flow via an SMTP server, set the notifications Helm value:

notifications:
  use: smtp
  smtp:
    hostname: "smtp.example.com"
    port: 25
    # The username for authenticating with the SMTP server
    username: example-user
    # The domain under which the sender's email for the email notification will be included
    fromDomain: "notification.example.com"

Then create a k8s secret containing the SMTP user's password:

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

Maximum body size#

By default, the BSR limits the body size of incoming requests to 256 MB. For some use cases, such as uploading large custom plugins, this may need to be increased. To increase the body size limit, set the maxBodySizeBytes Helm value:

maxBodySizeBytes: "2147483648" # 2 GB

Maven registry generation timeout#

By default, the BSR times out when code generation for the Maven registry exceeds 2 minutes. For some use cases, such as working with large modules, this may need to be increased. To increase the generation timeout, set the mavenRegistry.generationTimeout Helm value:

mavenRegistry:
  generationTimeout: "10m" # 10 minutes

Maven registry groupId#

The BSR Maven registry defaults to using the reversed hostname + .gen as its groupId coordinate. For example, a module on the public BSR (buf.build) uses the groupId build.buf.gen.

To set a custom groupId:

  1. Update the mavenRegistry.groupId Helm value. The customized groupId must contain only alphanumeric characters, ., or _. 
    mavenRegistry:
  groupId: "com.acme.gen"
  2. Apply the configuration.
  3. As a BSR server admin, clear any previously generated Maven Generated SDKs using the server admin panel (https://buf.build/admin/plugin-management). This removes any existing assets using the old groupId.

Using Artifactory for Maven generation#

By default, the BSR uses Maven Central to fetch dependencies required for building Java or Kotlin generated SDKs. An Artifactory remote repository mirroring Maven Central can be used instead by setting the bufjavacompilerd.registry Helm values:

bufjavacompilerd:
  registry:
    url: "https://example.jfrog.io/artifactory/my-repository/"
    # Optional. If username is set, the Kubernetes Secret containing the password must also be present
    username: "username"
  trustStore:
    # Optional. If true, the Kubernetes Secret for the trust store must also be present
    custom: false
  # Optional proxy to use for connections to Maven central
  mavenProxy:
    # Optional. If false, no other field needs to be present.
    enabled: false
    # Optional. Valid values: "http", "https". Defaults to "https".
    protocol: "https"
    # Required. Can be an IP address.
    host: "proxy.example.com"
    # Optional. Defaults to 443 or 80, depending on the protocol value.
    port: 443
    # Optional. Username to use for authenticating with the proxy. If set, the Kubernetes Secret for the password must also be present.
    username: ""

To create the Kubernetes Secret containing the Artifactory password:

$ kubectl create secret --namespace bsr generic bufjavacompilerd-registry \
  --from-literal=password=my-password

To create the Kubernetes Secret containing a custom Java JKS trust store:

$ kubectl create secret --namespace bsr generic bufjavacompilerd-truststore \
--from-file=cacerts=trustStore.jks \
--from-literal=password=my-truststore-password

Replace trustStore.jks with the path to the custom JKS trust store and my-truststore-password with the trust store password.

To create the Kubernetes Secret containing the Maven proxy password:

$ kubectl create secret --namespace bsr generic bufjavacompilerd-mavenproxy \
  --from-literal=password=my-password

Public access#

By default, the BSR only allows access for authenticated users. To allow unauthenticated users to view public modules in the BSR, and consume related artifacts such as generated SDKs for those modules, set the auth.allowPublicAccess Helm value:

auth:
  allowPublicAccess: true

Pod resource requests/limits#

The BSR ships with default pod resource requests that work for most customers. To adjust resource requests or limits, the following helm values can be used:

bufd:
  deployment:
    resources:
      requests:
        cpu: 800m
        memory: 2Gi
      # By default, no limits are set, but can be configured using the values below:
      # limits:
      #   cpu: ""
      #   memory: 2Gi
bufjavacompilerd:
  deployment:
    resources:
      requests:
        cpu: 200m
        memory: 4Gi
      # By default, no limits are set, but can be configured using the values below:
      # limits:
      #   cpu: ""
      #   memory: 4Gi
sandbox:
  deployment:
    resources:
      requests:
        cpu: 300m
        memory: 1Gi
    # By default, no limits are set, but can be configured using the values below:
    # limits:
    #   cpu: ""
    #   memory: 1Gi
  runtime:
    deployment:
      resources:
        requests:
          cpu: 800m
          memory: 2Gi
        # By default, no limits are set, but can be configured using the values below:
        # limits:
        #   cpu: ""
        #   memory: 2Gi
ociregistry:
  deployment:
    resources:
      requests:
        cpu: 300m
        memory: 512Mi
    # By default, no limits are set, but can be configured using the values below:
    # limits:
    #   cpu: ""
    #   memory: 512Mi

Buf policy enforcement#

The BSR allows users to upload and enforce policies (shared sets of lint and breaking change rules). You can disable this feature with the enableServerPolicyEnforcement Helm value:

enableServerPolicyEnforcement: true # Enabled by default

EKS Auto Mode / Bottlerocket compatibility#

The BSR uses gVisor for sandboxed plugin execution. gVisor requires user.max_user_namespaces > 0, but Bottlerocket (used by EKS Auto Mode) sets this value to 0 by default.

When running the BSR on EKS Auto Mode or other Bottlerocket-based clusters, plugin execution may fail with the following error:

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 this issue, add a privileged init container to the sandbox deployment that configures the required 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

Alternatively, if you're using Bottlerocket user data, you can configure the kernel parameter directly:

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

Other configuration#

There may be additional low-level values defined in the values.yaml chart or Helm templates that are subject to change. Please contact us before depending on these configuration values so we can better support your needs.