Support bundle

Generate from the admin area (in-cluster)

For Helm-based installations, GitGuardian provides a built-in Support Bundle page in the admin area. This allows administrators to generate, download, and optionally upload support bundles directly from the web UI — without needing kubectl access or the Krew plugin.

Configuration

In-cluster support bundle generation is enabled by default with all RBAC resources managed by the chart. No additional configuration is needed for a standard deployment.

Key	Default	Effect
rbac.enabled	true	Creates the GIM role with pod-management permissions
replicated.supportBundle.rbac.createPodRole	true	Adds pod create/get/delete rules to the GIM role
replicated.supportBundle.rbac.serviceAccount.create	true	Creates a dedicated support-bundle SA for the collector pod
replicated.supportBundle.rbac.role.create	true	Creates the namespace-scoped Role for the collector pod
replicated.supportBundle.rbac.clusterRole.create	true	Creates a ClusterRole for cluster-wide diagnostics (nodes, CRDs, etc.)
replicated.supportBundle.admissionPolicy.enabled	true	Deploys a ValidatingAdmissionPolicy restricting pod creation (requires Kubernetes 1.30+)

Common scenarios:

• Disable in-cluster generation entirely — set replicated.supportBundle.rbac.createPodRole: false. This removes the pod-management permissions from the GIM role, preventing the application from spawning support-bundle pods. You can still generate bundles from the CLI.
• Manage the support-bundle SA yourself — create the service account and its bindings outside of Helm, then reference it with existingServiceAccountName and set role.create and clusterRole.create to false:

replicated:
  supportBundle:
    rbac:
      serviceAccount:
        create: false
        existingServiceAccountName: 'my-custom-support-bundle-sa'
      role:
        create: false
      clusterRole:
        create: false

• Disable the ValidatingAdmissionPolicy (requires Kubernetes 1.30+) — set replicated.supportBundle.admissionPolicy.enabled: false. This removes the guardrail that restricts what the GIM SA can create, meaning any compromise of the application could allow arbitrary pod creation in the namespace. Only disable this if your cluster does not support Kubernetes 1.30+, and consider replacing it with an equivalent policy using OPA/Gatekeeper, Kyverno, or any other admission controller.

How it works

When you click Generate new support bundle, the application creates a short-lived pod in the same namespace. This pod:

1. Runs the kubectl support-bundle command against a pre-defined spec to collect logs, cluster resources, and diagnostic data.
2. Serves the resulting .tar.gz archive over an internal HTTP endpoint so the application can stream it back to your browser.
3. Optionally uploads the bundle directly to Replicated for remote analysis by the GitGuardian support team.

The pod has a fixed lifetime of 1 hour (activeDeadlineSeconds: 3600). After that, Kubernetes terminates it automatically.

Security architecture

In-cluster bundle generation uses two separate service accounts with strictly separated permissions:

Service account	Used by	Purpose
GIM service account	webapp-internal-api pods	Creates, monitors, and deletes the support-bundle pod
support-bundle service account	The support-bundle pod itself	Read-only access to namespace and (optionally) cluster resources

The GIM SA never holds the broad read permissions needed by the collector, and the collector never holds pod-management permissions.

When admissionPolicy.enabled is true, the chart deploys a ValidatingAdmissionPolicy (requires Kubernetes 1.30+) that restricts what the GIM SA can create. Only the exact expected pod (name, service account, images, commands, environment variables) is allowed. This is strongly recommended — disable only if your cluster does not support it.

RBAC details

The full GIM role definition (including pod-management rules) is documented in the Kubernetes Application RBAC section.

The support-bundle service account requires:

Role (namespace-scoped, required):

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: support-bundle
  namespace: <gitguardian_namespace>
rules:
  - apiGroups: ['*']
    resources: ['*']
    verbs: ['get', 'list', 'watch']
  - apiGroups: ['']
    resources: ['pods/exec']
    verbs: ['create']

ClusterRole (cluster-scoped, optional) — the name is suffixed with the namespace (support-bundle-<namespace>) to avoid collisions in multi-tenant clusters:

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: support-bundle-<namespace>
rules:
  - apiGroups: ['']
    resources: ['namespaces', 'nodes']
    verbs: ['get', 'list', 'watch']
  - apiGroups: ['apiextensions.k8s.io']
    resources: ['customresourcedefinitions']
    verbs: ['get', 'list', 'watch']
  - apiGroups: ['storage.k8s.io']
    resources: ['storageclasses']
    verbs: ['get', 'list', 'watch']

Self-managed RBAC

If your organization requires RBAC to be provisioned outside of Helm, disable the chart-managed resources using the scenarios described in the Configuration section and create the service account, roles, and bindings yourself using the definitions above.

Upload credentials

To enable Upload bundle directly to Replicated, the chart creates a support-bundle-credentials secret containing the Replicated license ID and upload domain. To manage this secret yourself:

replicated:
  supportBundle:
    credentials:
      existingSecret: 'my-support-bundle-credentials'

The secret must contain the keys license-id and upload-domain.

upload-domain should be replicated.app by default and might be different in the future.

Resource limits

You can configure resource requests and limits for both containers in the support-bundle pod:

replicated:
  supportBundle:
    resources:
      initContainer:
        requests:
          cpu: 100m
          memory: 128Mi
        limits:
          cpu: 500m
          memory: 512Mi
      mainContainer:
        requests:
          cpu: 50m
          memory: 32Mi
        limits:
          cpu: 100m
          memory: 64Mi

Sizing the init container

The init container collects and compresses the support bundle. Its memory consumption scales linearly with the bundle size — roughly ~45 Mi per MB of generated bundle (1 MB → ~45 Mi, 4 MB → ~175 Mi, 10 MB → ~400 Mi). If the init container exceeds its memory limit, it is OOMKilled (exit code 137) and bundle generation fails.

Increasing the CPU limit reduces compression time but does not affect memory. The defaults are kept low (500m) to minimize impact on other workloads.

To determine the right values, first generate a bundle from the CLI and check its size:

ls -lh support-bundle-*.tar.gz

Then adjust resources:

1. Memory limit: estimated peak (~45 Mi × bundle size in MB) × 1.5 for headroom.
2. Memory request: half the limit (1:2 request-to-limit ratio).
3. CPU limit: increase if you want faster generation and can afford the burst.

For example, if your test bundle is 8 MB (estimated peak ~360 Mi):

replicated:
  supportBundle:
    resources:
      initContainer:
        requests:
          cpu: 100m
          memory: 256Mi
        limits:
          cpu: 500m
          memory: 640Mi

tip

Bundles that include verbose Loki or application logs tend to be significantly larger. If you increase replicated.supportBundle.logs.maxLines, regenerate a test bundle to reassess the size before adjusting resource limits.

Generate from CLI (kubectl)

Helm-based installation

For Helm-based installations, you can also generate a support bundle from the command line using the Krew package manager:

1. Install the Krew plugin.
2. Install the support-bundle utility: kubectl krew install support-bundle.
3. Run: kubectl support-bundle --load-cluster-specs --namespace <namespace>.

This command will create a .tar.gz support bundle in your current directory. You can then send it to GitGuardian support.

To customize the number of log lines captured, set the maxLines parameter as shown below. Adjust the value to capture more or fewer logs as needed:

replicated:
  supportBundle:
    logs:
      maxLines: 100000 # Maximum number of log lines

If you are not a cluster-admin in your Kubernetes cluster, you will need to apply the RBAC configuration described in the RBAC details section above to your targeted namespace.

Generate a support bundle when the Kubernetes cluster is down

When debugging an offline Kubernetes cluster, you can utilize host collectors to generate a support bundle even without access to the Admin Console.

To begin, install the support bundle tool on a host with access to the cluster you need to debug:

curl -L https://github.com/replicatedhq/troubleshoot/releases/latest/download/support-bundle_linux_amd64.tar.gz | tar xzvf -

Next, generate the support bundle using the following command:

./support-bundle --interactive=false https://raw.githubusercontent.com/replicatedhq/troubleshoot-specs/main/host/default.yaml

note

If your current user lacks the necessary access to gather information for a specific collector, you may need to run the above command with sudo.

For air gap environments, download the YAML file and copy it to the air gap machine.

For more details, refer to Replicated Documentation.