Kuboxy (KUBernetes rOXY) is a software proxy that allows a user to connect to multiple Kubernetes cluster from a single server.
Kuboxy offers also several interesting features:
- Classical REST endpoints for accessing all object (JSON format)
- Swagger interface with all objects fully documented
- Interface WebSocket for receiving events from the clusters
- Kuboxy con also be itself hosted in a Kubernetes cluster
- The JSON schemas of the Kubernetes objects are provided
go run cmd/main.go [parameters]
or for building the application
go build -o kuboxy.exe cmd/main.go
./kuboxy.exe [parameters]
Options are the following:
Name | Usage | Default Value | Example |
---|---|---|---|
configurationFilePtr | Indicates a YAML/JSON file defining all the following parameters | ~/.kuboxy/application.config | ./kuboxy.exe -configurationFilePtr="~/.kuboxy/config.json" |
address | The IP address used by the service | 127.0.0.1 | ./kuboxy.exe -address=192.168.1.1 |
restPort | The IP port used by the service for REST endpoints | 8080 | ./kuboxy.exe -restPort=8080 |
webSocketPort | The IP port used by the event service | 8081 | ./kuboxy.exe -webSocketPort=8081 |
certificateFileName | The certificate used for providing HTTPS connections | none | ./kuboxy.exe -certificateFileName="~/.kuboxy/cert.pem" |
privateKeyFileName | The private key of the certificate | none | ./kuboxy.exe -privateKeyFileName="~/.kuboxy/key.pem" |
kubeContextConfigurationFile | The file storing the credentials of the clusters | ~/.kuboxy/kube.config | ./kuboxy.exe -kubeContextConfigurationFile="~/.kuboxy/kube.config" |
The options, save for configurationFilePtr
can be defined permanently in a YAML file (JSON file is also
acceptable as it is a subset of YAML). The equivalent of the above example are:
address: "192.168.1.1",
restPort: 8080,
webSocketPort: 8081,
certificateFileName: "~/.kuboxy/cert.pem",
privateKeyFileName: "~/.kuboxy/key.pem",
kubeContextConfigurationFile: "~/.kuboxy/kube.config"
or
{
"address": "192.168.1.1",
"restPort": 8080,
"webSocketPort": 8081,
"certificateFileName": "~/.kuboxy/cert.pem",
"privateKeyFileName": "~/.kuboxy/key.pem",
"kubeContextConfigurationFile": "~/.kuboxy/kube.config"
}
By default the configuration is located in ~/.kuboxy/application.config
.
The options are evaluated in the following order:
- The default values
- The default configuration file (
~/.kuboxy/application.config
) is loaded and its values override the default values - If a specific configuration file (option
configurationFilePtr
) is given, it is loaded and its values override the existing ones - The parameters given on the command line override the existing values
Although it may seems a bit convoluted, it is not necessary to use all possibilities. In production use, defining
everything in ~/.kuboxy/application.config
.
All the endpoints are available: https://localhost:8080/swagger/index.html. The endpoints are grouped by families:
- Configuration
- Labels
- Objects at the cluster level
- Objects at the namespace level
- Search and summary
The configuration endpoints allows to configure the application, more precisely the cluster referenced by the Cuboxy. As by Kubernetes standards, the following information can be configured:
- The cluster: name, server, certificate
- The user: name, certificate or password
- The context: name, cluster and user with an optional namespace
This single endpoint allows to retrieve easily all the labels and their possible values for context/namespace.
These endpoints allows CRUD operations on the following objects:
- clusterRoleBindings
- clusterRoles
- namespaces
- nodeMetricses
- nodes
- persistentVolumes
- storageClasses
These endpoints allows CRUD operations on the following objects:
- configMaps
- cronJobs
- daemonSets
- deployments
- jobs
- networkPolicies
- persistentVolumeClaims
- podMetricses
- pods
- replicaSets
- replicationControllers
- roleBindings
- roles
- secrets
- serviceAccounts
- services
- statefulSets
This two endpoints allows to easily search objects in a cluster and to generate a high level overview of state of the cluster
It is possible for a client to subscribe to a context events. The subscription is running over a WebSocket connection, so once the chanel is open, a client can't manage its subscription and receive events without further connection.
The process is the following:
- The client connect to the WebSocket (by default https://localhost:8081/api/v1/events/)
- The client send a request for subscribing/unsubscribing to event. Requests are defined here after
- As soon as change (new/update/delete) is done in the cluster about an object, the client will receive the object over the WebSocket
The command object has the following structure:
{
"command": "The command",
"objectType": "The type of object (optional)",
"contextName": "The name of the context (optional)",
"namespaceName": "The namespace (optional)"
}
The command sent by the client is one of the following:
- "AddSource": For subscribing a new source of event.
- "RemoveSource": For unsubscribing to an existing source.
- "RemoveAllSources": For unsubscribing to ... all sources.
Swagger/swaggo are using a definition located at docs/docs.go
. This documentation is not generated automatically at
the compilation time. So in case of changes in the API, it is necessary to regenerate this file with the following
procedure:
- Install, if needed, Swaggo :
go get github.com/swaggo/swag/cmd/swag
that will generate a swag executable - Run
swag init
in the root of the project - In the folder docs of the project, run
update_docs.go
The documentation also includes the JSON schemas for the various object managed by the application. This schemas are
located in the folder docs/json_schemas
. Although not directly used by the application, the may be used by the client.
For generating the schemas, run the file generator.go
located in tools/json_schema
.
- v0.2.0:
- Fix for configuration file
- Add support for Kubernetes 1.14
- v0.1.0: First version
Copyright 2019 Thomas Wuillemin thomas.wuillemin@gmail.com
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this project or its content except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.