{"id":13342912,"url":"https://github.com/grafana/xk6-kubernetes","last_synced_at":"2025-10-04T22:18:32.210Z","repository":{"id":38822224,"uuid":"359751045","full_name":"grafana/xk6-kubernetes","owner":"grafana","description":"Client extension for interacting with Kubernetes clusters from your k6 tests.","archived":false,"fork":false,"pushed_at":"2025-03-26T12:56:06.000Z","size":4418,"stargazers_count":69,"open_issues_count":13,"forks_count":22,"subscribers_count":149,"default_branch":"main","last_synced_at":"2025-03-28T13:04:40.547Z","etag":null,"topics":["kubernetes","kubernetes-client","xk6"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/grafana.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":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-04-20T09:03:30.000Z","updated_at":"2025-03-26T12:56:11.000Z","dependencies_parsed_at":"2023-02-14T07:30:58.729Z","dependency_job_id":"79ed0926-e1c3-4003-90e3-6e9ff6b6512a","html_url":"https://github.com/grafana/xk6-kubernetes","commit_stats":{"total_commits":166,"total_committers":15,"mean_commits":"11.066666666666666","dds":0.5783132530120482,"last_synced_commit":"d78a3ecfc8a9e2764128236a3f03b28b0ee7fb2d"},"previous_names":["k6io/xk6-kubernetes"],"tags_count":18,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grafana%2Fxk6-kubernetes","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grafana%2Fxk6-kubernetes/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grafana%2Fxk6-kubernetes/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grafana%2Fxk6-kubernetes/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/grafana","download_url":"https://codeload.github.com/grafana/xk6-kubernetes/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247184758,"owners_count":20897830,"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":["kubernetes","kubernetes-client","xk6"],"created_at":"2024-07-29T19:30:06.912Z","updated_at":"2025-10-04T22:18:27.155Z","avatar_url":"https://github.com/grafana.png","language":"Go","funding_links":[],"categories":["Extensions"],"sub_categories":["Official"],"readme":"[![Go Reference](https://pkg.go.dev/badge/github.com/grafana/xk6-kubernetes.svg)](https://pkg.go.dev/github.com/grafana/xk6-kubernetes)\n[![Version Badge](https://img.shields.io/github/v/release/grafana/xk6-kubernetes?style=flat-square)](https://github.com/grafana/xk6-kubernetes/releases)\n![Build Status](https://img.shields.io/github/actions/workflow/status/grafana/xk6-kubernetes/ci.yml?style=flat-square)\n\n# xk6-kubernetes\nA k6 extension for interacting with Kubernetes clusters while testing.\n\n## Build\n\nTo build a custom `k6` binary with this extension, first ensure you have the prerequisites:\n\n- [Go toolchain](https://go101.org/article/go-toolchain.html)\n- Git\n\n1. Download [xk6](https://github.com/grafana/xk6):\n  \n    ```bash\n    go install go.k6.io/xk6/cmd/xk6@latest\n    ```\n\n2. [Build the k6 binary](https://github.com/grafana/xk6#command-usage):\n  \n    ```bash\n    xk6 build --with github.com/grafana/xk6-kubernetes\n    ```\n\n    The `xk6 build` command creates a k6 binary that includes the xk6-kubernetes extension in your local folder. This k6 binary can now run a k6 test using [xk6-kubernetes APIs](#apis).\n\n\n### Development\nTo make development a little smoother, use the `Makefile` in the root folder. The default target will format your code, run tests, and create a `k6` binary with your local code rather than from GitHub.\n\n```shell\ngit clone git@github.com:grafana/xk6-kubernetes.git\ncd xk6-kubernetes\nmake\n```\n\nUsing the `k6` binary with `xk6-kubernetes`, run the k6 test as usual:\n\n```bash\n./k6 run k8s-test-script.js\n\n```\n# Usage\n\nBy default, the API assumes a `kubeconfig` configuration is available at `$HOME/.kube`.\n\nAlternatively, you can pass in the following options as a javascript Object to the Kubernetes constructor to configure access to the Kubernetes API server:\n\n| Option | Value | Description |\n| -- | --| ---- |\n| config_path | /path/to/kubeconfig | Kubeconfig file location. You can also set this to __ENV.KUBECONFIG to use the location pointed by the `KUBECONFIG` environment variable |\n| server | \u003cSERVER_HOST\u003e | Kubernetes API server URL |\n| token | \u003cTOKEN\u003e | Bearer Token for authenticating to the Kubernetes API server |\n\n```javascript\n\nimport { Kubernetes } from 'k6/x/kubernetes';\n\nexport default function () {\n  const k = new Kubernetes({\n    config_map: '/path/to/kubeconfig',\n  });\n}\n```\n\n# APIs\n\n## Generic API\n\nThis API offers methods for creating, retrieving, listing and deleting resources of any of the supported kinds.\n\n|  Method     | Parameters|   Description |\n| ------------ | ---| ------ |\n| apply         | manifest string| creates a Kubernetes resource given a YAML manifest or updates it if already exists |\n| create         | spec object | creates a Kubernetes resource given its specification |\n| delete         | kind  | removes the named resource |\n|                | name  |\n|                | namespace|\n| get         | kind| returns the named resource |\n|                | name  |\n|                | namespace |\n| list         | kind| returns a collection of resources of a given kind\n|                | namespace |\n| update         | spec object | updates an existing resource\n\n### Examples\n\n#### Creating a pod using a specification \n```javascript\nimport { Kubernetes } from 'k6/x/kubernetes';\n\nconst podSpec = {\n    apiVersion: \"v1\",\n    kind:       \"Pod\",\n    metadata: {\n        name:      \"busybox\",\n        namespace: \"testns\"\n    },\n    spec: {\n        containers: [\n            {\n                name:    \"busybox\",\n                image:   \"busybox\",\n                command: [\"sh\", \"-c\", \"sleep 30\"]\n            }\n        ]\n    }\n}\n\nexport default function () {\n  const kubernetes = new Kubernetes();\n\n  kubernetes.create(pod)\n\n  const pods = kubernetes.list(\"Pod\", \"testns\");\n\n  console.log(`${pods.length} Pods found:`);\n  pods.map(function(pod) {\n    console.log(`  ${pod.metadata.name}`)\n  });\n}\n```\n\n#### Creating a job using a YAML manifest\n```javascript\nimport { Kubernetes } from 'k6/x/kubernetes';\n\nconst manifest = `\napiVersion: batch/v1\nkind: Job\nmetadata:\n  name: busybox\n  namespace: testns\nspec:\n  template:\n    spec:\n      containers:\n      - name: busybox\n        image: busybox\n        command: [\"sleep\", \"300\"]\n    restartPolicy: Never\n`\n\nexport default function () {\n  const kubernetes = new Kubernetes();\n\n  kubernetes.apply(manifest)\n\n  const jobs = kubernetes.list(\"Job\", \"testns\");\n\n  console.log(`${jobs.length} Jobs found:`);\n  pods.map(function(job) {\n    console.log(`  ${job.metadata.name}`)\n  });\n}\n```\n\n#### Interacting with objects created by CRDs\n\nFor objects outside of the core API, use the fully-qualified resource name.\n\n```javascript\n\nimport { Kubernetes } from 'k6/x/kubernetes';\n\nconst manifest = `\napiVersion: networking.k8s.io/v1\nkind: Ingress\nmetadata:\n  name: yaml-ingress\n  namespace: default\nspec:\n  ingressClassName: nginx\n  rules:\n  - http:\n      paths:\n      - path: /my-service-path\n        pathType: Prefix\n        backend:\n          service:\n            name: my-service\n            port:\n              number: 80\n`\n\nexport default function () {\n  const kubernetes = new Kubernetes();\n\n  kubernetes.apply(manifest);\n\n  const ingresses = kubernetes.list(\"Ingress.networking.k8s.io\", \"default\")\n\n  console.log(`${ingresses.length} Ingress found:`);\n  ingresses.map(function(ingress) {\n    console.log(`  ${ingress.metadata.name}`)\n  });\n}\n\n\n```\n\n## Helpers\n\nThe `xk6-kubernetes` extension offers helpers to facilitate common tasks when setting up a tests. All helper functions work in a namespace to facilitate the development of tests segregated by namespace. The helpers are accessed using the following method:\n\n|  Method      | Parameters|   Description |\n| -------------| ---| ------ |\n| helpers      | namespace | returns helpers that operate in the given namespace. If none is specified, \"default\" is used |\n\nThe methods above return an object that implements the following helper functions:\n\n|  Method     | Parameters|   Description |\n| ------------ | --------| ------ |\n| getExternalIP        | service        | returns the external IP of a service if any is assigned before timeout expires|\n|                      | timeout in seconds | |\n| waitPodRunning | pod name | waits until the pod is in 'Running' state or the timeout expires. Returns a boolean indicating of the pod was ready or not. Throws an error if the pod is Failed. |\n|                | timeout in seconds | |\n| waitServiceReady         | service name | waits until the given service has at least one endpoint ready or the timeout expires |\n|                | timeout in seconds | |\n\n\n\n### Examples\n\n### Creating a pod and wait until it is running\n\n```javascript\nimport { Kubernetes } from 'k6/x/kubernetes';\n\nlet podSpec = {\n    apiVersion: \"v1\",\n    kind:       \"Pod\",\n    metadata: {\n        name:      \"busybox\",\n        namespace:  \"default\"\n    },\n    spec: {\n        containers: [\n            {\n                name:    \"busybox\",\n                image:   \"busybox\",\n                command: [\"sh\", \"-c\", \"sleep 30\"]\n            }\n        ]\n    }\n}\n\nexport default function () {\n  const kubernetes = new Kubernetes();\n\n  // create pod\n  kubernetes.create(pod)\n\n  // get helpers for test namespace\n  const helpers = kubernetes.helpers()\n\n  // wait for pod to be running\n  const timeout = 10\n  if (!helpers.waitPodRunning(pod.metadata.name, timeout)) {\n      console.log(`\"pod ${pod.metadata.name} not ready after ${timeout} seconds`)\n  }\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgrafana%2Fxk6-kubernetes","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgrafana%2Fxk6-kubernetes","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgrafana%2Fxk6-kubernetes/lists"}