{"id":28541758,"url":"https://github.com/konstructio/kubefirst-api","last_synced_at":"2026-01-31T05:09:09.387Z","repository":{"id":69666193,"uuid":"603158808","full_name":"konstructio/kubefirst-api","owner":"konstructio","description":"Kubefirst API that serves console frontend","archived":false,"fork":false,"pushed_at":"2025-11-27T23:06:03.000Z","size":2030,"stargazers_count":16,"open_issues_count":32,"forks_count":14,"subscribers_count":8,"default_branch":"main","last_synced_at":"2025-11-30T12:50:28.113Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Go","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/konstructio.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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2023-02-17T18:35:29.000Z","updated_at":"2025-10-28T18:20:57.000Z","dependencies_parsed_at":"2024-03-10T06:29:54.617Z","dependency_job_id":"5e978a12-4c44-4ee1-9c2d-e75282baae51","html_url":"https://github.com/konstructio/kubefirst-api","commit_stats":null,"previous_names":["konstructio/kubefirst-api","kubefirst/kubefirst-api"],"tags_count":77,"template":false,"template_full_name":null,"purl":"pkg:github/konstructio/kubefirst-api","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/konstructio%2Fkubefirst-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/konstructio%2Fkubefirst-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/konstructio%2Fkubefirst-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/konstructio%2Fkubefirst-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/konstructio","download_url":"https://codeload.github.com/konstructio/kubefirst-api/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/konstructio%2Fkubefirst-api/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28929866,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-31T04:05:25.756Z","status":"ssl_error","status_checked_at":"2026-01-31T04:02:35.005Z","response_time":128,"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":[],"created_at":"2025-06-09T20:09:48.810Z","updated_at":"2026-01-31T05:09:09.380Z","avatar_url":"https://github.com/konstructio.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!-- markdownlint-disable MD033 MD041 MD024 --\u003e\n\u003cp align=\"center\"\u003e\n  \u003cpicture\u003e\n    \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"images/kubefirst-light.svg\" alt=\"Kubefirst Logo\"\u003e\n    \u003cimg alt=\"\" src=\"images/kubefirst.svg\"\u003e\n  \u003c/picture\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n  Gitops Infrastructure \u0026 Application Delivery Platform\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://docs.kubefirst.io/\"\u003eInstall\u003c/a\u003e\u0026nbsp;|\u0026nbsp;\n  \u003ca href=\"https://twitter.com/kubefirst\"\u003eTwitter\u003c/a\u003e\u0026nbsp;|\u0026nbsp;\n  \u003ca href=\"https://www.linkedin.com/company/kubefirst\"\u003eLinkedIn\u003c/a\u003e\u0026nbsp;|\u0026nbsp;\n  \u003ca href=\"https://join.slack.com/t/kubefirst/shared_invite/zt-r0r9cfts-OVnH0ooELDLm9n9p2aU7fw\"\u003eSlack\u003c/a\u003e\u0026nbsp;|\u0026nbsp;\n  \u003ca href=\"https://kubeshop.io/blog-projects/kubefirst\"\u003eBlog\u003c/a\u003e\n\u003c/p\u003e\n\n# kubefirst-api\n\nKubefirst API runtime implementation.\n\n- [kubefirst-api](#kubefirst-api)\n  - [Running Locally](#running-locally)\n    - [Build the Binary](#build-the-binary)\n    - [Leverage `air` for Live Reloading Locally](#leverage-air-for-live-reloading-locally)\n    - [Use with the CLI](#use-with-the-cli)\n  - [Prerequisites for local development](#prerequisites-for-local-development)\n    - [Environment Variables](#environment-variables)\n  - [local environment variables](#local-environment-variables)\n  - [Provider Support](#provider-support)\n  - [Creating a Cluster](#creating-a-cluster)\n    - [Authentication Credentials](#authentication-credentials)\n      - [Kubernetes Secret](#kubernetes-secret)\n      - [API Call Parameters](#api-call-parameters)\n        - [Akamai](#akamai)\n        - [AWS](#aws)\n        - [Civo](#civo)\n        - [DigitalOcean](#digitalocean)\n        - [Google Cloud](#google-cloud)\n        - [Vultr](#vultr)\n      - [API Call](#api-call)\n        - [Akamai](#akamai-1)\n        - [AWS](#aws-1)\n        - [Civo](#civo-1)\n        - [DigitalOcean](#digitalocean-1)\n        - [Vultr](#vultr-1)\n    - [Deleting a Cluster](#deleting-a-cluster)\n  - [Authentication](#authentication)\n  - [Swagger UI](#swagger-ui)\n  - [Updating Swagger Docs](#updating-swagger-docs)\n\n## Running Locally\n\nThe API is available at `http://localhost:8081/api/v1` while running.\n\n### Build the Binary\n\nThe API can be run locally for testing. It can be run by using `make build` and then calling the binary in the `bin/` directory or by using `go run .`.\n\n### Leverage `air` for Live Reloading Locally\n\n**Prerequsite** - Install [air](https://github.com/air-verse/air).\n\n```go\ngo install github.com/air-verse/air@latest\n```\n\nRun `air` from the root of the repository. This will watch go files and live rebuild a local running instance of `kubefirst-api`.\n\n### Use with the CLI\n\nIf you want to use your local API version with the CLI, you need to do two things:\n\n1. Set the `K1_LOCAL_DEBUG` environment variable to `true` with `export K1_LOCAL_DEBUG=true`.\n2. Run the [console application](https://github.com/kubefirst/console) locally also by following [those instructions](https://github.com/kubefirst/console#setup-instructions).\n\nBe sure that you do not change the default port for the console (3000), and the default one for the API (8081) for this to work.\n\n## Prerequisites for local development\n\n\u003e A [.devcontainer](https://containers.dev/) configuration is provided to allow for a full-featured development environment.\n\nFor local development, we need to have a k3d cluster where the kubefirst api can store information in secrets\n\n- Download [k3d](https://k3d.io/)\n- Create a cluster ```k3d cluster create dev```\n- Dowload the kubeconfig ```k3d kubeconfig write dev```\n- Update the `K1_LOCAL_KUBECONFIG_PATH` environment variable with the kubeconfig location\n- Enjoy!\n\n### Environment Variables\n\nSome variables are required, others are optional depending on deployment type.\n\n| Variable                    | Description                                                                                                                                      | Required                       |\n| -------------------         | ------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------ |\n| `IN_CLUSTER`                | Specify whether or not the API is running inside a Kubernetes cluster. By default, this is assumed `false`.                                      | No                             |\n| `CLUSTER_ID`                | The ID of the cluster running API.                                                                                                               | Yes                            |\n| `CLUSTER_TYPE`              | Cluster type.                                                                                                                                    | Yes                            |\n| `INSTALL_METHOD`            | Description of the method through which the API was deployed. Example: `helm`                                                                    | Yes                            |\n| `K1_ACCESS_TOKEN`           | Access token in authorization header to prevent unsolicited in-cluster access                                                                    | Yes                            |\n| `K1_LOCAL_DEBUG`            | Identifies the api execution as local debug mode                                                                                                 | Yes                             |\n| `K1_LOCAL_KUBECONFIG_PATH`  | kubeconfig path location for k3d local cluster                                                                                                   | Yes                            |\n\n## local environment variables\n\nsee [this .env example](./.env.example) for the necessary values\n\nBe sure to set `IS_CLUSTER_ZERO` to `true` if you want to run the API without having console running.\n\n## Provider Support\n\nThe following providers are available for use with the API.\n\n| Provider      | Status | Supported Operations | Supported Git Providers |\n| ------------- | ------ | -------------------- | ----------------------- |\n| AWS           | Beta   | Create, Delete       | GitHub, GitLab          |\n| Civo          | Beta   | Create, Delete       | GitHub, GitLab          |\n| DigitalOcean  | Beta   | Create, Delete       | GitHub, GitLab          |\n| Vultr         | Beta   | Create, Delete       | GitHub, GitLab          |\n\n## Creating a Cluster\n\n### Authentication Credentials\n\nIn order to create a cluster, authentication credentials must be provided in one of two ways:\n\n#### Kubernetes Secret\n\nIf a Kubernetes `Secret` called `kubefirst-auth` exists, the API will attempt to read cloud provider credentials from this `Secret`.\n\nThe `Secret` format is expected to have the following keys based on which clouds you are deploying to:\n\n```text\naws-access-key-id\naws-secret-access-key\naws-session-token\n\ncivo-token\n\ndo-token\ndo-spaces-key\ndo-spaces-token\n\nvultr-api-key\n```\n\nEach key must have the appropriate value set in order for the API to successfully create a cluster.\n\n#### API Call Parameters\n\nIf there is no `Secret`, the API will then attempt to read from the parameters passed in via the API call.\n\nThis would require the following parameters added to the API call depending on which cloud provider is being used:\n\n##### Akamai\n\n```json\n{\n  \"akamai_auth\": {\n    \"token\": \"my-akamai-token\"\n  }\n}\n```\n\n##### AWS\n\n```json\n{\n  \"aws_auth\": {\n    \"access_key_id\": \"foo\",\n    \"secret_access_key\": \"bar\",\n    \"session_token\": \"baz\"\n  }\n}\n```\n\n##### Civo\n\n```json\n{\n  \"civo_auth\": {\n    \"token\": \"my-civo-token\"\n  }\n}\n```\n\n##### DigitalOcean\n\n```json\n{\n  \"do_auth\": {\n    \"token\": \"my-do-token\",\n    \"spaces_key\": \"foo\",\n    \"spaces_secret\": \"bar\"\n  }\n}\n```\n\n##### Google Cloud\n\n```json\n{\n  \"gcp_auth\": {\n    \"key_file\": \"my-google-credentials-json-keyfile-stringified-no-newline-characters\",\n    \"project_id\": \"google cloud project id\"\n  }\n}\n```\n\n##### Vultr\n\n```json\n{\n  \"vultr_auth\": {\n    \"token\": \"my-vultr-api-key\"\n  }\n}\n```\n\nIf either of these options is missing, the API will return an error.\n\n#### API Call\n\n##### Akamai\n\nYou must use the authentication strategy above to set credentials before running.\n\n```shell\ncurl -X POST http://localhost:8081/api/v1/cluster/my-cool-cluster -H \"Content-Type: application/json\" -d '{\"admin_email\": \"your@email.com\", \"cloud_provider\": \"akamai\", \"domain_name\": \"kubefirst.cloud\", \"git_owner\": \"kubefirst-cloud\", \"git_provider\": \"github\", \"git_token\": \"ghp_...\", \"type\": \"mgmt\"}'\n```\n\n##### AWS\n\nYou must use the authentication strategy above to set credentials before running.\n\n```shell\ncurl -X POST http://localhost:8081/api/v1/cluster/my-cool-cluster -H \"Content-Type: application/json\" -d '{\"admin_email\": \"your@email.com\", \"cloud_provider\": \"aws\", \"cloud_region\": \"us-east-1\", \"domain_name\": \"kubefirst.cloud\", \"git_owner\": \"kubefirst-cloud\", \"git_provider\": \"github\", \"git_token\": \"ghp_...\", \"type\": \"mgmt\"}'\n```\n\n##### Civo\n\nYou must use the authentication strategy above to set credentials before running.\n\n```shell\ncurl -X POST http://localhost:8081/api/v1/cluster/my-cool-cluster -H \"Content-Type: application/json\" -d '{\"admin_email\": \"your@email.com\", \"cloud_provider\": \"civo\", \"cloud_region\": \"nyc1\", \"domain_name\": \"your-dns.io\", \"git_owner\": \"your-dns-io\", \"git_provider\": \"github\", \"git_token\": \"ghp_...\", \"type\": \"mgmt\"}'\n```\n\n##### DigitalOcean\n\nKubefirst does not create a DigitalOcean space for you. You must create one ahead of time and provide the key and secret when creating a DigitalOcean cluster. The space acts as an S3-compatible storage bucket for Terraform state and other cluster operations.\n\nYou must use the authentication strategy above to set credentials before running.\n\n```shell\ncurl -X POST http://localhost:8081/api/v1/cluster/my-cool-cluster -H \"Content-Type: application/json\" -d '{\"admin_email\": \"your@email.com\", \"cloud_provider\": \"digitalocean\", \"cloud_region\": \"nyc3\", \"domain_name\": \"kubefunk.de\", \"git_owner\": \"kubefunk-de\", \"git_provider\": \"github\", \"git_token\": \"ghp_...\", \"type\": \"mgmt\"}'\n```\n\n##### Vultr\n\nYou must use the authentication strategy above to set credentials before running.\n\n```shell\ncurl -X POST http://localhost:8081/api/v1/cluster/my-cool-cluster -H \"Content-Type: application/json\" -d '{\"admin_email\": \"your@email.com\", \"cloud_provider\": \"vultr\", \"cloud_region\": \"ewr\", \"domain_name\": \"kubesecond.com\", \"git_owner\": \"your-dns-io\", \"git_provider\": \"github\", \"git_token\": \"ghp_...\", \"type\": \"mgmt\"}'\n```\n\n### Deleting a Cluster\n\n```shell\ncurl -X DELETE http://localhost:8081/api/v1/cluster/my-cool-cluster\n```\n\n## Authentication\n\nThe API expects an `Authorization` header with the content `Bearer \u003cAPI key\u003e`. For example:\n\n```shell\n❯ curl -X GET \"localhost:8081/api/v1/cluster\" \\\n     -H \"Authorization: Bearer my-api-key\" \\\n     -H \"Content-Type:application/json\"\n```\n\nThe provided bearer token is validated against an auto-generated key that gets stored in secret `kubefirst-initial-secrets` provided by this chart. It's then consumed by this same chart's deployment as an environment variable `K1_ACCESS_TOKEN` for the comparison. The console application will have access to this same namespaced secret and can leverage the bearer token to authorize calls to the `kubefirst-api` and `kubefirst-api-ee` services.\n\n## Swagger UI\n\nWhen the app is running, the UI is available via \u003chttp://localhost:8081/swagger/index.html\u003e.\n\n## Updating Swagger Docs\n\nSwagger UI is generated using [gin-swagger](https://github.com/swaggo/gin-swagger). Tagged routes will generate documentation.\n\nAny time godoc defs for routes are changed, `swag init` should be run.\n\nIn order to generate docs:\n\n```shell\ngo install github.com/swaggo/swag/cmd/swag@latest\n```\n\n```shell\nmake updateswagger\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkonstructio%2Fkubefirst-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkonstructio%2Fkubefirst-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkonstructio%2Fkubefirst-api/lists"}