{"id":19407599,"url":"https://github.com/yugokato/k8s-connector","last_synced_at":"2026-05-16T19:36:03.861Z","repository":{"id":261869957,"uuid":"871392295","full_name":"yugokato/k8s-connector","owner":"yugokato","description":"Programmatically access your Google Kubernetes Engine (GKE) cluster from your local environment","archived":false,"fork":false,"pushed_at":"2025-01-10T19:28:43.000Z","size":30,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-25T01:43:46.069Z","etag":null,"topics":["gcloud-sdk","gke","k8s","kubectl","python"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/yugokato.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"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}},"created_at":"2024-10-11T21:45:05.000Z","updated_at":"2025-01-10T19:27:39.000Z","dependencies_parsed_at":"2024-12-16T22:49:10.740Z","dependency_job_id":"b5ef8af5-5af1-4e6e-a05d-2bd63307c79a","html_url":"https://github.com/yugokato/k8s-connector","commit_stats":null,"previous_names":["yugokato/k8s-connector"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/yugokato/k8s-connector","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yugokato%2Fk8s-connector","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yugokato%2Fk8s-connector/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yugokato%2Fk8s-connector/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yugokato%2Fk8s-connector/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yugokato","download_url":"https://codeload.github.com/yugokato/k8s-connector/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yugokato%2Fk8s-connector/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33116331,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-16T18:38:32.183Z","status":"ssl_error","status_checked_at":"2026-05-16T18:38:29.903Z","response_time":115,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["gcloud-sdk","gke","k8s","kubectl","python"],"created_at":"2024-11-10T12:03:07.542Z","updated_at":"2026-05-16T19:36:03.830Z","avatar_url":"https://github.com/yugokato.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"K8s Connector\n======================\n\n[![Code style ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://docs.astral.sh/ruff/)\n\n\nThe \"K8s Connector\" allows you to programmatically access your Google Kubernetes Engine (GKE) cluster from your local environment. It leverages the [google/cloud-sdk](https://hub.docker.com/r/google/cloud-sdk/) docker image and provides a container class with a range of functions that utilize `kubectl` commands.\n\n\n\u003e [!NOTE]\n\u003e The library is mainly for accessing basic pods information, but not for performing any operations on resources to manage the cluster\n\n\n## Use cases\n\n- Collect pods status and logs upon receiving a 5xx response in automated API tests\n- Check pods status as part of a test setup and skip the test if any pods are in `CrashLoopBackOff` status\n- Check ongoing app deployment as a pre-hook for an API request and wait for it to complete before making the call\n- Check pods status afrter a production release to ensure successful deployment\n\n\n## Requirements\n\n- Python 3.11+\n- Docker and `google/cloud-sdk` image\n- A working Google Kubernetes Engine (GKE) cluster\n- Service Account file with sufficient read permissions\n\n\n## Setup\n\n1. Create a new virtual env\n2. Run `pip install -e .`\n\n\n## Usage examples\n\n### Initialize the `K8sConnector` container\n\n```pycon\n\u003e\u003e\u003e from k8s_connector import K8sConnector\n\u003e\u003e\u003e k8s = K8sConnector(service_account_file_path=\"/path/key.json\", cluster_name=\"my-cluster\", zone=\"us-west1-a\")\n2024-01-01T00:00:00.000-0000 - Starting a container google/cloud-sdk:latest\n2024-01-01T00:00:00.208-0000 - Started: c9b66e7152bbebe86445aaa9c6de4a2ee55b0ec8c48aa0b17a10d1ba8fcab7b6\n2024-01-01T00:00:00.213-0000 - Activating Service Account credentials...\n2024-01-01T00:00:00.213-0000 - Executing command: sh -c 'gcloud auth activate-service-account --key-file=/tmp/key.json --project myproject'\n2024-01-01T00:00:01.133-0000 - output:\nActivated service account credentials for: [sa@myproject.iam.gserviceaccount.com]\n\n2024-01-01T00:00:01.158-0000 - Fetching credentials for the cluster...\n2024-01-01T00:00:01.158-0000 - Executing command: sh -c 'gcloud container clusters get-credentials my-cluster --zone us-west1-a'\n2024-01-01T00:00:02.660-0000 - output:\nFetching cluster endpoint and auth data.\nkubeconfig entry generated for my-cluster.\n```\n\n### Execute a raw command using `exec_run()`\n\n```pycon\n\u003e\u003e\u003e exit_code, output = k8s.exec_run('kubectl version --client')\n2024-01-01T00:00:00.000-0000 - Executing command: sh -c 'kubectl version --client'\n2024-01-01T00:00:00.304-0000 - output:\nClient Version: v1.28.12-dispatcher\nKustomize Version: v5.0.4-0.20230601165947-6ce0bf390ce3\n```\n\n### Get pods information in all namespaces\n\n```pycon\n# Get pods\n\u003e\u003e\u003e pods = k8s.get_pods()\n2024-01-01T00:00:00.000-0000 - Executing command: sh -c 'kubectl get pods -A'\n2024-01-01T00:00:00.879-0000 - output:\nNAMESPACE   NAME                    READY   STATUS             RESTARTS         AGE\nexample     app1-c44949f4ba-zsxpd   3/3     Running            0                30m\nexample     app1-c44949f4ba-gjepp   3/3     Running            0                31m\nexample     app2-685dbfc75d-fzcmr   3/3     Running            0                31m\nexample     app2-685dbfc75d-pxhmj   3/3     Running            0                29m\n...\n\n# Get namespaces\n\u003e\u003e\u003e namespaces = k8s.get_namespaces()\n2024-01-01T00:00:00.000-0000 - Executing command: sh -c 'kubectl get namespaces'\n2024-01-01T00:00:00.279-0000 - output:\nNAME                              STATUS   AGE\nexample                           Active   30d\n...\n```\n\n### Get pods information for a specific application\n\n```pycon\n# Get pods\n\u003e\u003e\u003e pods = k8s.app1.get_pods()\n2024-01-01T00:00:00.000-0000 - Executing command: sh -c 'kubectl get pods -l app=app1 -n example'\n2024-01-01T00:00:00.625-0000 - output:\nNAME                    READY   STATUS    RESTARTS   AGE\napp1-c44949f4ba-zsxpd   3/3     Running   0          3d5h\napp1-c44949f4ba-gjepp   3/3     Running   0          3d5h\n...\n\n# Get pods logs\n\u003e\u003e\u003e logs = k8s.app1.get_logs()\n2024-01-01T00:00:00.000-0000 - Executing command: sh -c 'kubectl logs -l app=app1 -n example --since=30s --tail=-1'\n2024-01-01T00:00:01.342-0000 - output:\n[2024-01-01T00:00:00.000000+00:00] [INFO]{fb0f6a7a-66e7-4411-802b-e9b501f196f7}[app1.api.foo] - GET /foo\n[2024-01-01T00:00:00.000000+00:00] [INFO]{941e391a-3b0f-464b-a35b-979c1f084443}[app1.api.bar] - GET /bar\n...\n\n# Stream pods logs (with filtering)\n\u003e\u003e k8s.app1.get_logs(follow=True, grep=\"ERROR|CRITICAL\")\n2024-01-01T00:00:00.000-0000 - Executing command: sh -c 'kubectl logs -l app=app1 -n example --since=30s --tail=-1 -f --max-log-requests=30 | GREP_COLOR=\"1;32\" stdbuf -o0 grep -E -E \"ERROR|CRITICAL\" --color=always'\n[2024-01-01T00:00:00.000000+00:00] [ERROR]{b9e75fd4-7f82-446e-92fd-48f23a81dbb4}[app1.api.foo] - foo\n[2024-01-01T00:00:00.000000+00:00] [ERROR]{7e6f3618-2ec5-4fe5-ae93-4aaa387f3263}[app1.api.bar] - bar\n...\n\n# Get environment variables set as a configmap\n\u003e\u003e\u003e configmap_data = k8s.app1.get_configmap_data()\n2024-01-01T00:00:00.000-0000 - Executing command: sh -c 'kubectl get configmap -l app=app1 -n example -o json | jq '\"'\"'.items[] | select(.kind == \"ConfigMap\") | .data'\"'\"''\n2024-01-01T00:00:00.609-0000 - output:\n{\n  \"APP1_ENV_VAR1\": \"true\",\n  \"APP1_ENV_VAR2\": \"false\",\n  ...\n}\n\n# Get metrics\n\u003e\u003e\u003e output = k8s.app1.top()\n2024-01-01T00:00:00.000-0000 - Executing command: sh -c 'kubectl top pod --containers --sort-by=cpu -l app=app1 -n example'\n2024-01-01T00:00:00.590-0000 - output:\nPOD                     NAME          CPU(cores)   MEMORY(bytes)   \napp1-c44949f4ba-zsxpd   app1           617m         1253Mi                       \napp1-c44949f4ba-gjepp   app1           607m         1174Mi      \n...     \n\n# Wait for app deployment to complete after a successful build\n\u003e\u003e\u003e k8s.app1.wait_for_deployment()\n2024-01-01T01:00:00.000-0000 - Waiting for app1 deployment to start...\n2024-01-01T01:01:57.730-0000 - app1 deployment started\n2024-01-01T01:01:57.730-0000 - Waiting for deployment of app1 to complete...\n2024-01-01T01:01:57.730-0000 - Executing command: sh -c 'kubectl rollout status deployment/app1 -n example --timeout=360s'\n2024-01-01T01:04:22.022-0000 - output:\nWaiting for deployment \"app1\" rollout to finish: 2 out of 4 new replicas have been updated...\nWaiting for deployment \"app1\" rollout to finish: 2 out of 4 new replicas have been updated...\nWaiting for deployment \"app1\" rollout to finish: 2 out of 4 new replicas have been updated...\nWaiting for deployment \"app1\" rollout to finish: 2 out of 4 new replicas have been updated...\nWaiting for deployment \"app1\" rollout to finish: 3 out of 4 new replicas have been updated...\nWaiting for deployment \"app1\" rollout to finish: 3 out of 4 new replicas have been updated...\nWaiting for deployment \"app1\" rollout to finish: 3 out of 4 new replicas have been updated...\nWaiting for deployment \"app1\" rollout to finish: 3 out of 4 new replicas have been updated...\nWaiting for deployment \"app1\" rollout to finish: 1 old replicas are pending termination...\nWaiting for deployment \"app1\" rollout to finish: 1 old replicas are pending termination...\nWaiting for deployment \"app1\" rollout to finish: 1 old replicas are pending termination...\nWaiting for deployment \"app1\" rollout to finish: 3 of 4 updated replicas are available...\ndeployment \"app1\" successfully rolled out\n\n2024-01-01T01:04:22.022-0000 - Executing command: sh -c 'kubectl get pods -l app=app1 -n example'\n2024-01-01T01:09:22.657-0000 - output:\nNAME                    READY   STATUS    RESTARTS      AGE\napp1-7d575bb744-7c2fg   3/3     Running   0             91s\napp1-7d575bb744-9jxtc   3/3     Running   0             2m37s\napp1-7d575bb744-fzcmr   3/3     Running   0             2m38s\napp1-7d575bb744-pxhmj   3/3     Running   0             37s\n\n2024-01-01T01:04:22.657-0000 - Deployment of app1 completed (took 144.926855802536 seconds)\n```\n\n\u003e [!TIP]\n\u003e Most functions return the raw output by default, but some support `parse` parameter which will parse the output and return it as an object (eg. Returns the tabulated output as a list of dictionaries)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyugokato%2Fk8s-connector","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyugokato%2Fk8s-connector","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyugokato%2Fk8s-connector/lists"}