Installation at a Glance #

1. Objective #

This document defines the standard operating procedure for installing BuildPiper on a Kubernetes cluster using Helm. The setup is configured for a non‑root user and follows a secure, repeatable process involving configuration via an Excel template, Helm chart deployment, and thorough post‑installation verification.

2. Supported OS & Hardware Specifications #

3. Supported Kubernetes Versions #

BuildPiper officially supports Kubernetes versions v1.25 through v1.33.

4. Prerequisites #

4.1 Managed Redis & MySQL #

The installation requires a managed Redis and MySQL instance. Ensure both are available and network-accessible from the Kubernetes cluster.

4.2 MySQL Mandatory Configuration #

Execute the following SQL statements on your MySQL instance:

Execute the validation query below to confirm the applied settings:

4.3 Redis Configuration #

Enable append‑only persistence on the Redis instance:

5. BuildPiper Setup Procedure (4‑Step Workflow) #

6. Helm Deployment Details #

6.1 Access the Cluster #

Set the environment variable pointing to your cluster kubeconfig:

6.2 Helm Install Command #

Execute the Helm installation command:

• <helm_files_directory> — Path where Helm chart files are unzipped.
• <namespace> — Target dedicated namespace (e.g., bp).

6.3 Helm Upgrade Command (For Future Updates) #

Use the following command for future upgrades or configuration changes:

7. Configuration Values (from Excel Template) #

7.1 Database & Redis Configuration (Sheet: CustomerToShare) #

7.2 SMTP Configuration (Sheet: CustomerToShare) #

7.3 Cluster & NFS (Sheet: CustomerToShare) #

7.4 Service Account & Storage Class (Sheet: CustomerToShare) #

7.5 General & BP Team Configuration (Sheet: OwnedbyBuildPiper) #

8. Verification Steps #

8.1 Verify Pod Status #

Check pod statuses in the installation namespace:

Expected Outcome: All pods must show STATUS as Running and READY as 1/1.

NAME                                READY   STATUS    RESTARTS   AGE
bpagent-74b86b5868-szz2b            1/1     Running   0          20h
bpagent-74b86b5868-x1vvp            1/1     Running   0          19h
deplayout-57d8b5f87c-gpbx2          1/1     Running   0          20h
frontend-bc58c74f4-4f2vg            1/1     Running   0          20h
publicapi-6c7f4c4f4d-k6dkn          1/1     Running   0          20h
scheduleapi-79f98775d4-28pcd        1/1     Running   0          20h

8.2 (Optional) Validate Service & Public Endpoint Access #

1. Fetch NodePort services:

2. Get master node internal IP:

3. Test port connectivity:

4. Check public API health endpoint:

8.3 Fetch Logs for Troubleshooting #

To stream logs from a specific pod for troubleshooting:

9. Generic Troubleshooting Tips #

• Pods not starting: Run kubectl describe pod <pod_name> -n <namespace> to view detailed lifecycle events.
• Image pull errors: Verify registry credentials and ensure image tags match loadbalancer-setup-values.yaml.
• Database connectivity: Test connectivity to MySQL (3306) and Redis (6379) from a temporary pod inside the cluster.
• Storage issues: Confirm EFS CSI driver / Longhorn is running and StorageClass is bound.
• Invalid encryption: Ensure Fernet key and encrypted credentials match the expected string format without extra spaces.
• Helm deployment errors: Confirm the target namespace exists (kubectl create namespace <namespace>) and RBAC permissions are applied.

10. References #

• BuildPiper Helm Chart: https://github.com/buildpiper/bp-on-k8s/tree/master/helm-chart
• Load‑Balancer Setup Guide: https://github.com/buildpiper/bp-on-k8s/blob/master/helm-chart/LOADBALANCER-BASED-SETUP.md

11. Conclusion #

By following this Standard Operating Procedure, system administrators can achieve a consistent and repeatable installation of BuildPiper on Kubernetes. For further assistance or escalation, collect full cluster logs and describe output before reaching out to BuildPiper support.