{"id":13509823,"url":"https://github.com/minio/sidekick","last_synced_at":"2025-06-20T11:43:29.891Z","repository":{"id":38216374,"uuid":"245286427","full_name":"minio/sidekick","owner":"minio","description":"High Performance HTTP Sidecar Load Balancer","archived":false,"fork":false,"pushed_at":"2025-05-06T16:59:58.000Z","size":1954,"stargazers_count":564,"open_issues_count":3,"forks_count":86,"subscribers_count":18,"default_branch":"master","last_synced_at":"2025-05-06T17:48:28.696Z","etag":null,"topics":["bigdata","kubernetes","load-balancer","minio-servers","proxy","sidecar","sidekick","spark"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/minio.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"code_of_conduct.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2020-03-05T23:11:52.000Z","updated_at":"2025-05-06T16:49:13.000Z","dependencies_parsed_at":"2023-02-14T01:16:19.315Z","dependency_job_id":"bf68e6c8-2465-4720-b344-d3d56ab59b41","html_url":"https://github.com/minio/sidekick","commit_stats":null,"previous_names":[],"tags_count":65,"template":false,"template_full_name":null,"purl":"pkg:github/minio/sidekick","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/minio%2Fsidekick","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/minio%2Fsidekick/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/minio%2Fsidekick/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/minio%2Fsidekick/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/minio","download_url":"https://codeload.github.com/minio/sidekick/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/minio%2Fsidekick/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260940294,"owners_count":23086292,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bigdata","kubernetes","load-balancer","minio-servers","proxy","sidecar","sidekick","spark"],"created_at":"2024-08-01T02:01:13.799Z","updated_at":"2025-06-20T11:43:24.866Z","avatar_url":"https://github.com/minio.png","language":"Go","readme":"\u003cpicture\u003e\n  \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://raw.githubusercontent.com/minio/sidekick/master/sidekick_logo_dark.png\"\u003e\n  \u003cimg alt=\"sidekick\" src=\"https://raw.githubusercontent.com/minio/sidekick/master/sidekick_logo.png\"  \u003e\n\u003c/picture\u003e\n\n![build](https://github.com/minio/sidekick/workflows/Go/badge.svg) ![license](https://img.shields.io/badge/license-AGPL%20V3-blue)\n\n![GitHub Downloads][gh-downloads]\n\n*sidekick* is a high-performance sidecar load balancer. By attaching a tiny load balancer to each client application process, you can eliminate the need for a centralized load balancer and DNS failover management. *sidekick* automatically avoids sending traffic to the failed servers by checking their health via the readiness API and HTTP error returns.\n\n# Architecture\n![architecture](https://raw.githubusercontent.com/minio/sidekick/master/arch_sidekick.png)\n\n# Install\n\n## Binary Releases\n\n| OS      | ARCH    | Binary                                                                                                 |\n|:-------:|:-------:|:------------------------------------------------------------------------------------------------------:|\n| Linux   | amd64   | [linux-amd64](https://github.com/minio/sidekick/releases/latest/download/sidekick-linux-amd64)         |\n| Linux   | arm64   | [linux-arm64](https://github.com/minio/sidekick/releases/latest/download/sidekick-linux-arm64)         |\n| Linux   | ppc64le | [linux-ppc64le](https://github.com/minio/sidekick/releases/latest/download/sidekick-linux-ppc64le)     |\n| Linux   | s390x   | [linux-s390x](https://github.com/minio/sidekick/releases/latest/download/sidekick-linux-s390x)         |\n| Apple   | amd64   | [darwin-amd64](https://github.com/minio/sidekick/releases/latest/download/sidekick-darwin-amd64)       |\n| Windows | amd64   | [windows-amd64](https://github.com/minio/sidekick/releases/latest/download/sidekick-windows-amd64.exe) |\n\nYou can also verify the binary with [minisign](https://jedisct1.github.io/minisign/) by downloading the corresponding [`.minisig`](https://github.com/minio/sidekick/releases/latest) signature file. Then run:\n```\nminisign -Vm sidekick-\u003cOS\u003e-\u003cARCH\u003e -P RWTx5Zr1tiHQLwG9keckT0c45M3AGeHD6IvimQHpyRywVWGbP1aVSGav\n```\n\n## Docker\n\nPull the latest release via:\n```\ndocker pull quay.io/minio/sidekick:v7.0.0\n```\n\n## Build from source\n\n```\ngo install -v github.com/minio/sidekick@latest\n```\n\n\u003e [!IMPORTANT]\n\u003e You will need a working Go environment. Therefore, please follow [How to install Go](https://golang.org/doc/install).\n\u003e The minimum version required is go1.22\n\n# Usage\n\n```\nNAME:\n  sidekick - High-Performance sidecar load-balancer\n\nUSAGE:\n  sidekick - [FLAGS] SITE1 [SITE2..]\n\nFLAGS:\n  --address value, -a value           listening address for sidekick (default: \":8080\")\n  --health-path value, -p value       health check path\n  --read-health-path value, -r value  health check path for read access - valid only for failover site\n  --health-port value                 health check port (default: 0)\n  --health-duration value, -d value   health check duration in seconds (default: 5s)\n  --health-timeout value              health check timeout in seconds (default: 10s)\n  --insecure, -i                      disable TLS certificate verification\n  --rr-dns-mode                       enable round-robin DNS mode\n  --log, -l                           enable logging\n  --trace value, -t value             enable request tracing - valid values are [all,application,minio] (default: \"all\")\n  --quiet, -q                         disable console messages\n  --json                              output sidekick logs and trace in json format\n  --debug                             output verbose trace\n  --cacert value                      CA certificate to verify peer against\n  --client-cert value                 client certificate file\n  --client-key value                  client private key file\n  --cert value                        server certificate file\n  --key value                         server private key file\n  --pprof :1337                       start and listen for profiling on the specified address (e.g. :1337)\n  --dns-ttl value                     choose custom DNS TTL value for DNS refreshes for load balanced endpoints (default: 10m0s)\n  --errors, -e                        filter out any non-error responses\n  --status-code value                 filter by given status code\n  --host-balance value                specify the algorithm to select backend host when load balancing, supported values are 'least', 'random' (default: \"least\")\n  --help, -h                          show help\n  --version, -v                       print the version\n```\n\n## Examples\n\n### Load balance across a web service using DNS provided IPs.\n```\n$ sidekick --health-path=/ready http://myapp.myorg.dom\n```\n\n### Load balance across 4 MinIO Servers.\nhttp://minio1:9000 to http://minio4:9000\n```\n$ sidekick --health-path=/minio/health/ready --address :8000 http://minio{1...4}:9000\n```\n\n### Load balance across two sites with four servers each\n```\n$ sidekick --health-path=/minio/health/ready http://site1-minio{1...4}:9000 http://site2-minio{1...4}:9000\n```\n\n## Realworld Example with spark-operator\n\nWith spark as *driver* and sidecars as *executor*, first install spark-operator and MinIO on your Kubernetes cluster.\n\n### Configure *spark-operator*\n\nThis guide uses the maintained spark operator by GCP at https://github.com/GoogleCloudPlatform/spark-on-k8s-operator.\n\n```\nhelm repo add spark-operator https://googlecloudplatform.github.io/spark-on-k8s-operator\nhelm --namespace spark-operator install spark-operator spark-operator/spark-operator --create-namespace --set sparkJobNamespace=spark-operator --set enableWebhook=true\n```\n\n### Install *MinIO*. \n\nEnsure that the `standard` storage class was previously installed.\nNote that TLS is disabled for this test. Note also that the minio tenant created is called `myminio`.\n\n```\nhelm repo add minio-operator https://operator.min.io/\nhelm install operator minio-operator/operator --namespace minio-operator --create-namespace\n  \nhelm install myminio minio-operator/tenant --namespace tenant-sidekick --create-namespace \u0026\u0026 \\\nkubectl --namespace tenant-sidekick patch tenant myminio --type='merge' -p '{\"spec\":{\"requestAutoCert\":false}}'\n```\n\nOnce the tenant pods are running, port-forward the minio headless service to access it locally.\n```\nkubectl --namespace tenant-sidekick port-forward svc/myminio-hl 9000 \u0026\n```\n\nConfigure [`mc`](https://github.com/minio/mc) and upload some data. Use `mybucket` as the s3 bucket name.\nCreate bucket named `mybucket` and upload some text data for spark word count sample.\n```\nmc alias set myminio http://localhost:9000 minio minio123\nmc mb myminio/mybucket\nmc cp /etc/hosts myminio/mybucket/mydata.txt\n```\n\n### Run the spark job in k8s\n\nObtain the IP address and port of the `minio` service. Use them as input to `fs.s3a.endpoint` the below SparkApplication. e.g. http://10.43.141.149:80\n```\nkubectl --namespace tenant-sidekick get svc/minio\n```\n\nCreate the `spark-minio-app` yml\n```\ncat \u003c\u003c EOF \u003e spark-job.yaml\napiVersion: \"sparkoperator.k8s.io/v1beta2\"\nkind: SparkApplication\nmetadata:\n  name: spark-minio-app\n  namespace: spark-operator\nspec:\n  sparkConf:\n    spark.kubernetes.allocation.batch.size: \"50\"\n  hadoopConf:\n    \"fs.s3a.endpoint\": \"http://10.43.141.149:80\"\n    \"fs.s3a.access.key\": \"minio\"\n    \"fs.s3a.secret.key\": \"minio123\"\n    \"fs.s3a.path.style.access\": \"true\"\n    \"fs.s3a.impl\": \"org.apache.hadoop.fs.s3a.S3AFileSystem\"\n  type: Scala\n  sparkVersion: 2.4.5\n  mode: cluster\n  image: minio/spark:v2.4.5-hadoop-3.1\n  imagePullPolicy: Always\n  restartPolicy:\n      type: OnFailure\n      onFailureRetries: 3\n      onFailureRetryInterval: 10\n      onSubmissionFailureRetries: 5\n      onSubmissionFailureRetryInterval: 20\n  mainClass: org.apache.spark.examples.JavaWordCount\n  mainApplicationFile: \"local:///opt/spark/examples/target/original-spark-examples_2.11-2.4.6-SNAPSHOT.jar\"\n  arguments:\n  - \"s3a://mybucket/mydata.txt\"\n  driver:\n    cores: 1\n    memory: \"512m\"\n    labels:\n      version: 2.4.5\n    sidecars:\n    - name: minio-lb\n      image: \"quay.io/minio/sidekick:v4.0.3\"\n      imagePullPolicy: Always\n      args: [\"--health-path\", \"/minio/health/ready\", \"--address\", \":8080\", \"http://myminio-pool-0-{0...3}.myminio-hl.tenant-sidekick.svc.cluster.local:9000\"]\n      ports:\n        - containerPort: 9000\n          protocol: http\n  executor:\n    cores: 2\n    instances: 4\n    memory: \"1024m\"\n    labels:\n      version: 2.4.5\n    sidecars:\n    - name: minio-lb\n      image: \"quay.io/minio/sidekick:v4.0.3\"\n      imagePullPolicy: Always\n      args: [\"--health-path\", \"/minio/health/ready\", \"--address\", \":8080\", \"http://myminio-pool-0-{0...3}.myminio-hl.tenant-sidekick.svc.cluster.local:9000\"]\n      ports:\n        - containerPort: 9000\n          protocol: http\nEOF\n```\n\nGrant permissions to access resources to the service account\n```\nkubectl create clusterrolebinding spark-role --clusterrole=edit --serviceaccount=spark-operator:default --namespace=spark-operator\nkubectl create -f spark-job.yaml\nkubectl --namespace spark-operator logs -f spark-minio-app-driver\n```\n\n#### Monitor\n\nThe above SparkApplication will not complete until the Health check returns \"200 OK\", in this case, when there is a MinIO read quorum. The Health check is provided at the path \"/v1/health.\" It returns \"200 OK\" even if any one of the sites is reachable; otherwise, it returns a \"502 Bad Gateway\" error.\n\n[gh-downloads]: https://img.shields.io/github/downloads/minio/sidekick/total?color=pink\u0026label=GitHub%20Downloads\n","funding_links":[],"categories":["Go","bigdata"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fminio%2Fsidekick","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fminio%2Fsidekick","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fminio%2Fsidekick/lists"}