Gitops Infrastructure & Application Delivery Platform

Install |  Twitter |  LinkedIn |  Slack |  Blog

Kubefirst API runtime implementation.

• kubefirst-api
  • Running Locally
    • Build the Binary
    • Leverage air for Live Reloading Locally
  • Prerequisites
    • Environment Variables
    • To run locally:
  • local environment variables
  • Provider Support
  • Creating a Cluster
    • Kubernetes Secret
    • API Call Parameters
    • AWS
    • Civo
    • Digital Ocean
    • Vultr
    • Deleting a Cluster
  • Authentication
  • Swagger UI
  • Updating Swagger Docs

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.

The API uses MongoDB for storing records.

The best option is to use MongoDB Atlas. This is the recommended approach.

For local development, you can install MongoDB Community Edition - this is not production-quality.

It is also recommended to install MongoDB Compass.

The host:port for MongoDB should be supplied as the environment variable MONGODB_HOST. When testing locally, use localhost:27017.

Some variables are required, others are optional depending on deployment type.

# optional local mongodb for kubefirst-api
docker run -d --name k1-api-mongodb \
  -e MONGO_INITDB_ROOT_USERNAME=root \
  -e MONGO_INITDB_ROOT_PASSWORD=some-password \
  -p 27017:27017 \
  mongo

see this .env example for the necessary values

The following providers are available for use with the API.

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:

{
	"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"
	}
}

{
	"do_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/kf-api-scott-test -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 Digital Ocean space for you. You must create one ahead of time and provide the key and secret when creating a Digital Ocean 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