k8ssandra-api-service
A service providing RESTful APIs for accessing a k8ssandra cluster.
Endpoints
Auth
GET /v1/auth/tokens
This endpoint provides authentication for using other endpoints. It accepts a GET request with HTTP basic authentation (username, password) and delegates the validation of that username/password to the underlying k8s secret.
By default, a secret called k8ssandra-api-service-user is used for this purpose. However, the secret referenced can be manipulated via environment variable and any other secret containing a username and password (e.g. the cluster-superuser generated by k8ssandra for access to C* itself) can be used.
export K8SSANDRA_API_SERIVCE_USER_SERCRET_NAME=k8ssandra-cassandra-cluster-superuser
Request Example
% curl --location --request GET 'http://localhost:3000/v1/auth/token' \
--header 'Authorization: Basic YWRtaW46YWRtaW4xMjM='
Response Example
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2MTg0MTYzNDMsImlzcyI6Ims4c3NhbmRyYS1hcGktc2VydmljZSIsInN1YiI6ImFkbWluIn0.JbDP7OD1HkYnMdnCBjlbQVE5B3n4XgijdKJDxCMdFw4
CassandraDatacenters
GET /v1/cassandra-datacenters
This endpoint provides access to a listing of all CassandraDataCenter resources deployed in the monitored namespace.
Bearer token authentication is required, tokens can be retrieved with GET /v1/auth/tokens.
Request Example
% curl --location --request GET 'http://localhost:3000/v1/cassandra-datacenters' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2MTg0MTYzMTksImlzcyIms4c3NhbmRyYS1hcGktc2VydmljZSIsInN1YiI6ImFkbWluIn0.Kjl53r5HtljZ1XCRjqiRndsGclVZsG8rD-ODbPjhR5Y'
Response Example
{
"items":[
{
"apiVersion":"cassandra.datastax.com/v1beta1",
"kind":"CassandraDatacenter",
"metadata":{
"name":"dc1",
"namespace":"default",
"annotations":{
"meta.helm.sh/release-name":"k8ssandra",
"meta.helm.sh/release-namespace":"default",
"reaper.cassandra-reaper.io/instance":"k8ssandra-reaper"
},
"labels":{
"app.kubernetes.io/instance":"k8ssandra",
"app.kubernetes.io/managed-by":"Helm",
"app.kubernetes.io/name":"k8ssandra",
"app.kubernetes.io/part-of":"k8ssandra-k8ssandra-default",
"helm.sh/chart":"k8ssandra-1.1.0"
},
"generation":2
},
"status":{
"cassandraOperatorProgress":"Ready",
"lastServerNodeStarted":"2021-04-13T20:41:30Z",
"conditions":[
{
"lastTransitionTime":"2021-04-13T20:42:36Z",
"message":"",
"reason":"",
"status":"False",
"type":"ScalingUp"
},
{
"lastTransitionTime":"2021-04-13T20:42:36Z",
"message":"",
"reason":"",
"status":"False",
"type":"Updating"
},
{
"lastTransitionTime":"2021-04-13T20:42:36Z",
"message":"",
"reason":"",
"status":"False",
"type":"Stopped"
},
{
"lastTransitionTime":"2021-04-13T20:42:36Z",
"message":"",
"reason":"",
"status":"False",
"type":"ReplacingNodes"
},
{
"lastTransitionTime":"2021-04-13T20:42:36Z",
"message":"",
"reason":"",
"status":"False",
"type":"RollingRestart"
},
{
"lastTransitionTime":"2021-04-13T20:42:36Z",
"message":"",
"reason":"",
"status":"False",
"type":"Resuming"
},
{
"lastTransitionTime":"2021-04-13T20:42:36Z",
"message":"",
"reason":"",
"status":"False",
"type":"ScalingDown"
},
{
"lastTransitionTime":"2021-04-13T20:42:36Z",
"message":"",
"reason":"",
"status":"True",
"type":"Valid"
},
{
"lastTransitionTime":"2021-04-13T20:42:37Z",
"message":"",
"reason":"",
"status":"True",
"type":"Initialized"
},
{
"lastTransitionTime":"2021-04-13T20:42:37Z",
"message":"",
"reason":"",
"status":"True",
"type":"Ready"
}
]
}
}
],
"metadata":{
"count":1,
"total":1
}
}
GET /v1/cassandra-datacenters/{name}
This endpoint provides access to a specific named instace of a CassandraDataCenter resource deployed in the monitired namespace.
Bearer token authentication is required, tokens can be retrieved with GET /v1/auth/tokens.
Request Example
curl --location --request GET 'http://localhost:3000/v1/cassandra-datacenters/dc1' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2MTg0MTYzMTksImlzcyI6s4c3NhbmRyYS1hcGktc2VydmljZSIsInN1YiI6ImFkbWluIn0.Kjl53r5HtljZ1XCRjqiRndsGclVZsG8rD-ODbPjhR5Y'
Response Example
{
"apiVersion":"cassandra.datastax.com/v1beta1",
"kind":"CassandraDatacenter",
"metadata":{
"name":"dc1",
"namespace":"default",
"annotations":{
"meta.helm.sh/release-name":"k8ssandra",
"meta.helm.sh/release-namespace":"default",
"reaper.cassandra-reaper.io/instance":"k8ssandra-reaper"
},
"labels":{
"app.kubernetes.io/instance":"k8ssandra",
"app.kubernetes.io/managed-by":"Helm",
"app.kubernetes.io/name":"k8ssandra",
"app.kubernetes.io/part-of":"k8ssandra-k8ssandra-default",
"helm.sh/chart":"k8ssandra-1.1.0"
},
"generation":2
},
"status":{
"cassandraOperatorProgress":"Ready",
"lastServerNodeStarted":"2021-04-13T20:41:30Z",
"conditions":[
{
"lastTransitionTime":"2021-04-13T20:42:36Z",
"message":"",
"reason":"",
"status":"False",
"type":"ScalingUp"
},
{
"lastTransitionTime":"2021-04-13T20:42:36Z",
"message":"",
"reason":"",
"status":"False",
"type":"Updating"
},
{
"lastTransitionTime":"2021-04-13T20:42:36Z",
"message":"",
"reason":"",
"status":"False",
"type":"Stopped"
},
{
"lastTransitionTime":"2021-04-13T20:42:36Z",
"message":"",
"reason":"",
"status":"False",
"type":"ReplacingNodes"
},
{
"lastTransitionTime":"2021-04-13T20:42:36Z",
"message":"",
"reason":"",
"status":"False",
"type":"RollingRestart"
},
{
"lastTransitionTime":"2021-04-13T20:42:36Z",
"message":"",
"reason":"",
"status":"False",
"type":"Resuming"
},
{
"lastTransitionTime":"2021-04-13T20:42:36Z",
"message":"",
"reason":"",
"status":"False",
"type":"ScalingDown"
},
{
"lastTransitionTime":"2021-04-13T20:42:36Z",
"message":"",
"reason":"",
"status":"True",
"type":"Valid"
},
{
"lastTransitionTime":"2021-04-13T20:42:37Z",
"message":"",
"reason":"",
"status":"True",
"type":"Initialized"
},
{
"lastTransitionTime":"2021-04-13T20:42:37Z",
"message":"",
"reason":"",
"status":"True",
"type":"Ready"
}
]
}
}
Runtime Configuration
To provide runtime configuration of the service, a number of environment variables can be provided as follows.
K8SSANDRA_API_SERIVCE_NAMESPACE (optional)
The k8s namespace in which the service should look for k8ssandra resources. If not provided, by default, default is used.
K8SSANDRA_API_SERVICE_KUBECONFIG_PATH (optional)
The absolute path to a provided kubeconfig that the service should use for accessing the k8s API server. If not provided, by default, an in-cluster deployment is assumed.
K8SSANDRA_API_SERVICE_KUBE_SERVER_MASTER_URL (optional)
The base URL to be used to access the k8s API server, this value should include protocol, address, and port. If not provided, the Go client default is used.
K8SSANDRA_API_SERVICE_PORT (optional)
The port number that the service should listen on. If not provided, by default, 3000 is used.
K8SSANDRA_API_SERIVCE_BIND_ADDRESS (optional)
The address that the service should listen on. If not provided, by default, 0.0.0.0 is used.
K8SSANDRA_API_SERIVCE_USER_SERCRET_NAME (optional)
The name of the secret held within the k8s cluster that is used for authentication delegation. For more information see the Authentication section. If not provided, by default, k8ssandra-api-service-user is used.
Development
k8s Cluster Access
For development purposes, the service supports both in and out of k8s cluster access. To access the k8s cluster from outside, a kubeconfig must be provided.
A kubeconfig can be provided via environment variable such as
export K8SSANDRA_API_SERVICE_KUBECONFIG_PATH=~/path/to/.kubeconfig
Running Locally
To aid in local development a set of scripts and VS code launch configuration are provided.
k8ssandra Cluster Deployment
Any k8ssandra cluster will do, but if you don't already have one, the /scripts/1-node-cluster/setup.sh script can be used to bootstrap.
To use this script the following is required:
- Docker
- Kind
- Helm
The script will do the following:
- Create a kind cluster with 2 nodes (master, worker) called
k8ssandra-dev - Set the local context for kubectl to that of the newly created cluster
kind-k8ssandra-dev - Export a copy of the related
kubeconfigto the local workspace at.kubeconfig - Install helm repos for traefik and k8ssandra/stable
- Deploy traefik to the cluster
- Deploy a 1-node k8ssandra to the cluster
- Deploy a secret to be used for authentication called
k8ssandra-api-service-userwith usernameadminand passwordadmin123
VS Code Launch
After the successful running of the script you should have a running k8ssandra cluster that can be targeted with the VS Code launch configuration provided Start Development Server.
That launch configuration will start the service in VS code using the .kubeconfig that was exported as part of the setup.sh script at the root of the workspace. The server will start on port 3000 and be available at http://localhost:3000.