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:

1. Create a kind cluster with 2 nodes (master, worker) called k8ssandra-dev
2. Set the local context for kubectl to that of the newly created cluster kind-k8ssandra-dev
3. Export a copy of the related kubeconfig to the local workspace at .kubeconfig
4. Install helm repos for traefik and k8ssandra/stable
5. Deploy traefik to the cluster
6. Deploy a 1-node k8ssandra to the cluster
7. Deploy a secret to be used for authentication called k8ssandra-api-service-user with username admin and password admin123

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.