{"id":14985968,"url":"https://github.com/absaoss/k3d-action","last_synced_at":"2025-04-05T20:08:14.637Z","repository":{"id":38267666,"uuid":"320257644","full_name":"AbsaOSS/k3d-action","owner":"AbsaOSS","description":"A GitHub Action to run lightweight ephemeral Kubernetes clusters during workflow.  Fundamental advantage of this action is a full customization of embedded k3s clusters. In addition, it provides a private image registry and multi-cluster support.","archived":false,"fork":false,"pushed_at":"2023-12-05T14:38:17.000Z","size":94,"stargazers_count":177,"open_issues_count":3,"forks_count":23,"subscribers_count":9,"default_branch":"main","last_synced_at":"2024-10-22T03:23:23.915Z","etag":null,"topics":["action","cluster","containers","github-actions","k3d","k3s","kind","kubernetes","rancher"],"latest_commit_sha":null,"homepage":"","language":"Shell","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/AbsaOSS.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":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-12-10T11:54:58.000Z","updated_at":"2024-10-17T11:06:34.000Z","dependencies_parsed_at":"2024-06-18T13:37:10.032Z","dependency_job_id":"1a15060e-32f2-4783-9dcc-a526e960b16d","html_url":"https://github.com/AbsaOSS/k3d-action","commit_stats":{"total_commits":58,"total_committers":6,"mean_commits":9.666666666666666,"dds":"0.27586206896551724","last_synced_commit":"4e8b3239042be1dc0aed6c5eb80c13b18200fc79"},"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AbsaOSS%2Fk3d-action","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AbsaOSS%2Fk3d-action/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AbsaOSS%2Fk3d-action/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AbsaOSS%2Fk3d-action/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AbsaOSS","download_url":"https://codeload.github.com/AbsaOSS/k3d-action/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247393570,"owners_count":20931813,"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":["action","cluster","containers","github-actions","k3d","k3s","kind","kubernetes","rancher"],"created_at":"2024-09-24T14:12:03.494Z","updated_at":"2025-04-05T20:08:14.612Z","avatar_url":"https://github.com/AbsaOSS.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AbsaOSS/k3d-action\n\nA GitHub Action to run lightweight ephemeral Kubernetes clusters during workflow.\nFundamental advantage of this action is a full customization of embedded k3s clusters. In addition, it provides\nmulti-cluster support.\n\n- [Introduction](#introduction)\n- [Getting started](#getting-started)\n  - [Inputs](#inputs)\n  - [Version mapping and override](#version-mapping-and-override)\n- [Single cluster setup](#single-cluster-setup)\n- [Multi-cluster setup](#multi-cluster-setup)\n- [Config file support](#config-file-support)\n- [Private Registry](#private-registry)\n\n## Introduction\n\nApplications running on Kubernetes clusters (microservices, controllers,...) come with their own set of complexities and concerns.\nIn particular, E2E testing k8s based applications requires new approaches to confirm proper operation and continued\navailability under heavy load or in the face of resource failure. **AbsaOSS/k3d-action allows to test the** _overall_ **application\nfunctionality**. For instance, the E2E use-case is [operator](https://kubernetes.io/docs/concepts/extend-kubernetes/operator/) testing\nin [AbsaOSS/k8gb](https://github.com/AbsaOSS/k8gb).\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.youtube.com/embed/eZcAvTb0rbA\" title=\"Github Actions review and tutorial by #DevOps Toolkit\"\u003e\n    \u003cimg src=\"https://user-images.githubusercontent.com/7195836/118461760-4a558880-b6fe-11eb-9ffc-5a87c87ed543.png\"\u003e\n  \u003c/a\u003e\n  \u003ci\u003eThe full CI/CD pipeline tutorial with k3d-action by \u003ca href=\"https://github.com/vfarcic\"\u003eViktor Farcic\u003c/a\u003e.\u003c/i\u003e\n\u003c/p\u003e\n\n## Getting started\nAbsaOSS/k3d-action runs [k3d](https://k3d.io/) which is a lightweight wrapper to run [k3s](https://k3s.io/)\n(Rancher Lab’s minimal Kubernetes distribution) in containers. Thanks to that, we could spin up the test environment\nquickly with minimal memory requirements, which is especially important in multi-cluster environments.\n\nAbsaOSS/k3d-action defines several input attributes and two outputs:\n\n### Inputs\n- `cluster-name` (Required) Cluster name.\n\n- `args` (Optional) list of k3d arguments defined by [k3d command tree](https://k3d.io/usage/commands/)\n\n- `k3d-version` (Optional) version of k3d. If not set, default version will be used from the [version mapping table](#version-mapping-and-override).\n\n### Version mapping and override\n\nImplementation of additional features brings complexity and sometimes it may happen that external dependencies get broken.\nTo prevent potential issues, `k3d` version is fixed according to the mapping below.\n\n| k3d-action |                             k3d                              |\n| :--------: | :----------------------------------------------------------: |\n|   v1.1.0   | [v3.4.0](https://github.com/rancher/k3d/releases/tag/v3.4.0) |\n|   v1.2.0   | [v4.2.0](https://github.com/rancher/k3d/releases/tag/v4.2.0) |\n|   v1.3.0   | [v4.2.0](https://github.com/rancher/k3d/releases/tag/v4.2.0) |\n|   v1.4.0   | [v4.4.1](https://github.com/rancher/k3d/releases/tag/v4.4.1) |\n|   v1.5.0   | [v4.4.7](https://github.com/rancher/k3d/releases/tag/v4.4.7) |\n|   v2.0.0   | [v5.1.0](https://github.com/rancher/k3d/releases/tag/v5.1.0) |\n|   v2.1.0   | [v5.2.2](https://github.com/rancher/k3d/releases/tag/v5.2.2) |\n|   v2.2.0   | [v5.3.0](https://github.com/k3d-io/k3d/releases/tag/v5.3.0)  |\n|   v2.3.0   | [v5.4.1](https://github.com/k3d-io/k3d/releases/tag/v5.4.1)  |\n|   v2.4.0   | [v5.4.6](https://github.com/k3d-io/k3d/releases/tag/v5.4.6)  |\n\nUsers can override the default `k3d` version with the `k3d-version:` action parameter\n\n```yaml\n# example\nwith:\n  k3d-version: v5.2.2\n```\n\nUsers can also override the default `k3s` image version, using `k3d` `--image` argument\n\n```yaml\n# example\nwith:\n  args: --image docker.io/rancher/k3s:v1.20.4-k3s1\n```\n\nor the `image:` field in the [k3d configuration file](#config-file-support).\n\nRecent `k3s` image versions can be checked on the [k3.io project releases page](https://github.com/k3s-io/k3s/releases).\n\n## Single cluster setup\nAlthough AbsaOSS/k3d-action strongly supports multi-cluster. Single cluster scenarios are very popular. The minimum single-cluster\nconfiguration looks like this :\n```yaml\n      - uses: AbsaOSS/k3d-action@v2\n        name: \"Create Single Cluster\"\n        with:\n          cluster-name: \"test-cluster-1\"\n          args: --agents 1\n```\nk3d creates a cluster with one worker node (with [traefik](https://traefik.io/) and metrics services), one agent and one\ndefault load-balancer node. In real scenarios you might prefer to do some port mapping and disable default load balancer.\nSuch an action would look like this:\n```yaml\n      - uses: AbsaOSS/k3d-action@v2\n        name: \"Create Single Cluster\"\n        with:\n          cluster-name: \"test-cluster-1\"\n          args: \u003e-\n            -p \"8083:80@agent:0:direct\"\n            -p \"8443:443@agent:0:direct\"\n            -p \"5053:53/udp@agent:0:direct\"\n            --agents 3\n            --no-lb\n            --image docker.io/rancher/k3s:v1.20.4-k3s1\n            --k3s-arg \"--no-deploy=traefik,servicelb,metrics-server@server:*\"\n```\nThe created cluster exposes two TCP (`:8083`,`:8443`) and one UDP (`:5053`) ports. The cluster comprises one server, three\nagents and no load balancers. [k3s-server-argument](https://rancher.com/docs/k3s/latest/en/installation/install-options/server-config/#k3s-server-cli-help)\ndisable default traefik and metrics.\n\nFor more details see: [Demo](https://github.com/AbsaOSS/k3d-action/actions?query=workflow%3A%22Single+cluster+on+default+network%22),\n[Source](./.github/workflows/single-cluster.yaml)\n\n## Multi-cluster setup\nk3d creates a bridge-network for each separate cluster or attaches the created cluster to an\nexisting network.\n\nWhen you create a cluster named `test-cluster-1`, k3d will automatically create a network\nnamed `k3d-test-cluster-1` with the range `172.18.0.0/16`. When you create a second cluster\n`test-cluster-2`, k3d automatically creates a network named `k3d-test-cluster-2` with a\nrange of `172.19.0.0/16`. Other clusters will have ranges `172.20.0.0/16`,`172.21.0.0/16` etc.\n\nThe following example creates a total of four clusters, the first two are created on\nthe network `nw01, 172.18.0.0/16`, the next two clusters are created on the network\n`nw02, 172.19.0.0/16`.\n\n```yaml\n      - uses: AbsaOSS/k3d-action@v2\n        name: \"Create 1st Cluster in 172.18.0.0/16\"\n        with:\n          cluster-name: \"test-cluster-1\"\n          args: \u003e-\n            -p \"80:80@agent:0:direct\"\n            -p \"443:443@agent:0:direct\"\n            -p \"5053:53/udp@agent:0:direct\"\n            --agents 3\n            --no-lb\n            --k3s-arg \"--no-deploy=traefik,servicelb,metrics-server@server:*\"\n            --network \"nw01\"\n\n      - uses: AbsaOSS/k3d-action@v2\n        name: \"Create 2nd Cluster in 172.18.0.0/16\"\n        with:\n          cluster-name: \"test-cluster-2\"\n          args: \u003e-\n            -p \"81:80@agent:0:direct\"\n            -p \"444:443@agent:0:direct\"\n            -p \"5054:53/udp@agent:0:direct\"\n            --agents 3\n            --no-lb\n            --k3s-arg \"--no-deploy=traefik,servicelb,metrics-server@server:*\"\n            --network \"nw01\"\n\n      - uses: AbsaOSS/k3d-action@v2\n          name: \"Create 1st Cluster in 172.19.0.0/16\"\n          with:\n            cluster-name: \"test-cluster-3\"\n            args: \u003e-\n              -p \"82:80@agent:0:direct\"\n              -p \"445:443@agent:0:direct\"\n              -p \"5055:53/udp@agent:0:direct\"\n              --agents 3\n              --no-lb\n              --k3s-arg \"--no-deploy=traefik,servicelb,metrics-server@server:*\"\n              --network \"nw02\"\n\n      - uses: AbsaOSS/k3d-action@v2\n        name: \"Create 2nd Cluster in 172.19.0.0/16\"\n        with:\n          cluster-name: \"test-cluster-4\"\n          args: \u003e-\n            -p \"83:80@agent:0:direct\"\n            -p \"446:443@agent:0:direct\"\n            -p \"5056:53/udp@agent:0:direct\"\n            --agents 3\n            --no-lb\n            --k3s-arg \"--no-deploy=traefik,servicelb,metrics-server@server:*\"\n            --network \"nw02\"\n```\nAbsaOSS/k3d-action creates four identical clusters in two different bridge networks.\n\nFor more details see: [Demo](https://github.com/AbsaOSS/k3d-action/actions?query=workflow%3A%22Multi+cluster%3B+two+pairs+of+clusters+on+two+isolated+networks%22),\n[Source](./.github/workflows/multi-cluster-two-piars.yaml)\n\n## Config file support\nFrom v1.2.0 you can configure action via config files or mix arguments together with config files. This setup is useful when\nyou want to share the configuration for local testing and testing within k3d-action.\n```yaml\n      - uses: ./\n        name: \"Create single k3d Cluster\"\n        with:\n          cluster-name: \"test-cluster-1\"\n          args: \u003e-\n            --agents 1\n            --config=\u003cpath to config yaml\u003e\n```\nAll you need to do is to place configuration file somewhere into your project. However, keep in mind, that command line\narguments will always take precedence over configuration, so the previous example will result in only one agent, not three as\nconfigured.\n```yaml\napiVersion: k3d.io/v1alpha3\nkind: Simple\nimage: docker.io/rancher/k3s:v1.20.5-k3s1\nservers: 1\nagents: 3 # The action will overwrite this by 1\nports:\n  - port: 0.0.0.0:80:80\n    nodeFilters:\n      - agent:0:direct\n  - port: 0.0.0.0:443:443\n    nodeFilters:\n      - agent:0:direct\n  - port: 0.0.0.0:5053:53/udp\n    nodeFilters:\n      - agent:0:direct\noptions:\n  k3d:\n    wait: true\n    timeout: \"60s\"\n    disableLoadbalancer: true\n  k3s:\n    extraArgs:\n      - arg: --no-deploy=traefik,servicelb,metrics-server\n        nodeFilters:\n          - server:*\n  kubeconfig:\n    updateDefaultKubeconfig: true\n    switchCurrentContext: true\n```\nFor more details see: [Demo](https://github.com/AbsaOSS/k3d-action/actions?query=workflow%3A%22Single+cluster+on+default+network+with+config%22),\n[Source action](./.github/workflows/single-cluster-config.yaml), [Source config](./.github/workflows/assets/1.yaml)\n\n## Private Registry\n\nBefore test starts, you need to build your app and install into the cluster. This requires interaction\nwith the image registry. Usually you don't want to push a new image into the remote registry for each test.\nInstead, you can import the image directly into the created cluster:\n```shell\ndocker build . -t \u003crepository\u003e:\u003csemver\u003e\nk3d image import \u003crepository\u003e:\u003csemver\u003e -c \u003ccluster-name\u003e\n```\nExample below demonstrates how to interact with imported docker registry:\n```yaml\n    steps:\n      - uses: actions/checkout@v2\n      - uses: AbsaOSS/k3d-action@v2\n        name: \"Create single k3d Cluster with imported Registry\"\n        with:\n          cluster-name: test-cluster-1\n          args: \u003e-\n            --agents 3\n            --no-lb\n            --k3s-arg \"--no-deploy=traefik,servicelb,metrics-server@server:*\"\n      - name: \"Docker repo demo\"\n        run: |\n          docker build . -t myproj/demo:v1.0.0\n          k3d image import myproj/demo:v1.0.0 -c test-cluster-1 --verbose\n          kubectl apply -f pod.yaml\n\n    # pod.yaml\n    #\n    # apiVersion: v1\n    # kind: Pod\n    # metadata:\n    #   name: test-pod\n    # spec:\n    #   containers:\n    #   - name: demo-app\n    #     image: myproj/demo:v1.0.0\n```\n\nFor further details see:\n- shared registry [Demo](https://github.com/AbsaOSS/k3d-action/actions/workflows/single-cluster-import-registry.yaml),\n  [Source](./.github/workflows/single-cluster-import-registry.yaml)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fabsaoss%2Fk3d-action","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fabsaoss%2Fk3d-action","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fabsaoss%2Fk3d-action/lists"}