Gitops Infrastructure & Application Delivery Platform
Install | Twitter | LinkedIn | Slack | Blog
Kubefirst API runtime implementation.
- kubefirst-api
The API is available at http://localhost:8081/api/v1
while running.
The 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 .
.
Prerequsite - Install air.
go install github.com/cosmtrek/air@latest
Run air
from the root of the repository. This will watch go files and live rebuild a local running instance of kubefirst-api
.
If you want to use your local API version with the CLI, you need to do two things:
- Set the
K1_LOCAL_DEBUG
environment variable totrue
withexport K1_LOCAL_DEBUG=true
. - Run the console application locally also by following those instructions.
Be 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.
For local development, we need to have a k3d cluster where the kubefirst api can store information in secrets
- Download k3d
- Create a cluster
k3d cluster create dev
- Dowload the kubeconfig
k3d kubeconfig write dev
- Update the
K1_LOCAL_KUBECONFIG_PATH
environment variable with the kubeconfig location - Enjoy!
Some variables are required, others are optional depending on deployment type.
Variable | Description | Required |
---|---|---|
IN_CLUSTER |
Specify whether or not the API is running inside a Kubernetes cluster. By default, this is assumed false . |
No |
CLUSTER_ID |
The ID of the cluster running API. | Yes |
CLUSTER_TYPE |
Cluster type. | Yes |
INSTALL_METHOD |
Description of the method through which the API was deployed. Example: helm |
Yes |
K1_ACCESS_TOKEN |
Access token in authorization header to prevent unsolicited in-cluster access | Yes |
K1_LOCAL_DEBUG |
Identifies the api execution as local debug mode | Yes |
K1_LOCAL_KUBECONFIG_PATH |
kubeconfig path location for k3d local cluster | Yes |
see this .env example for the necessary values
Be sure to set IS_CLUSTER_ZERO
to true
if you want to run the API without having console running.
The following providers are available for use with the API.
Provider | Status | Supported Operations | Supported Git Providers |
---|---|---|---|
AWS | Beta | Create, Delete | GitHub, GitLab |
Civo | Beta | Create, Delete | GitHub, GitLab |
DigitalOcean | Beta | Create, Delete | GitHub, GitLab |
Vultr | Beta | Create, Delete | GitHub, GitLab |
In order to create a cluster, authentication credentials must be provided in one of two ways:
If a Kubernetes Secret
called kubefirst-auth
exists, the API will attempt to read cloud provider credentials from this Secret
.
The Secret
format is expected to have the following keys based on which clouds you are deploying to:
aws-access-key-id
aws-secret-access-key
aws-session-token
civo-token
do-token
do-spaces-key
do-spaces-token
vultr-api-key
Each key must have the appropriate value set in order for the API to successfully create a cluster.
If there is no Secret
, the API will then attempt to read from the parameters passed in via the API call.
This would require the following parameters added to the API call depending on which cloud provider is being used:
{
"akamai_auth": {
"token": "my-akamai-token"
}
}
{
"aws_auth": {
"access_key_id": "foo",
"secret_access_key": "bar",
"session_token": "baz"
}
}
{
"civo_auth": {
"token": "my-civo-token"
}
}
{
"do_auth": {
"token": "my-do-token",
"spaces_key": "foo",
"spaces_secret": "bar"
}
}
{
"gcp_auth": {
"key_file": "my-google-credentials-json-keyfile-stringified-no-newline-characters",
"project_id": "google cloud project id"
}
}
{
"vultr_auth": {
"token": "my-vultr-api-key"
}
}
If either of these options is missing, the API will return an error.
You must use the authentication strategy above to set credentials before running.
curl -X POST http://localhost:8081/api/v1/cluster/my-cool-cluster -H "Content-Type: application/json" -d '{"admin_email": "[email protected]", "cloud_provider": "akamai", "domain_name": "kubefirst.cloud", "git_owner": "kubefirst-cloud", "git_provider": "github", "git_token": "ghp_...", "type": "mgmt"}'
You must use the authentication strategy above to set credentials before running.
curl -X POST http://localhost:8081/api/v1/cluster/my-cool-cluster -H "Content-Type: application/json" -d '{"admin_email": "[email protected]", "cloud_provider": "aws", "cloud_region": "us-east-1", "domain_name": "kubefirst.cloud", "git_owner": "kubefirst-cloud", "git_provider": "github", "git_token": "ghp_...", "type": "mgmt"}'
You must use the authentication strategy above to set credentials before running.
curl -X POST http://localhost:8081/api/v1/cluster/my-cool-cluster -H "Content-Type: application/json" -d '{"admin_email": "[email protected]", "cloud_provider": "civo", "cloud_region": "nyc1", "domain_name": "your-dns.io", "git_owner": "your-dns-io", "git_provider": "github", "git_token": "ghp_...", "type": "mgmt"}'
Kubefirst 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.
You must use the authentication strategy above to set credentials before running.
curl -X POST http://localhost:8081/api/v1/cluster/my-cool-cluster -H "Content-Type: application/json" -d '{"admin_email": "[email protected]", "cloud_provider": "digitalocean", "cloud_region": "nyc3", "domain_name": "kubefunk.de", "git_owner": "kubefunk-de", "git_provider": "github", "git_token": "ghp_...", "type": "mgmt"}'
You must use the authentication strategy above to set credentials before running.
curl -X POST http://localhost:8081/api/v1/cluster/my-cool-cluster -H "Content-Type: application/json" -d '{"admin_email": "[email protected]", "cloud_provider": "vultr", "cloud_region": "ewr", "domain_name": "kubesecond.com", "git_owner": "your-dns-io", "git_provider": "github", "git_token": "ghp_...", "type": "mgmt"}'
curl -X DELETE http://localhost:8081/api/v1/cluster/my-cool-cluster
The API expects an Authorization
header with the content Bearer <API key>
. For example:
❯ curl -X GET "localhost:8081/api/v1/cluster" \
-H "Authorization: Bearer my-api-key" \
-H "Content-Type:application/json"
The 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.
When the app is running, the UI is available via http://localhost:8081/swagger/index.html.
Swagger UI is generated using gin-swagger. Tagged routes will generate documentation.
Any time godoc defs for routes are changed, swag init
should be run.
In order to generate docs:
go install github.com/swaggo/swag/cmd/swag@latest
make updateswagger