Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/nubank/k8s-api
Kubernetes client, data driven
https://github.com/nubank/k8s-api
clojure foundation kubernetes-api kubernetes-client
Last synced: about 23 hours ago
JSON representation
Kubernetes client, data driven
- Host: GitHub
- URL: https://github.com/nubank/k8s-api
- Owner: nubank
- License: apache-2.0
- Created: 2019-12-19T14:26:22.000Z (about 5 years ago)
- Default Branch: master
- Last Pushed: 2024-05-20T18:17:02.000Z (8 months ago)
- Last Synced: 2025-01-19T15:46:53.877Z (1 day ago)
- Topics: clojure, foundation, kubernetes-api, kubernetes-client
- Language: Clojure
- Homepage:
- Size: 951 KB
- Stars: 152
- Watchers: 731
- Forks: 13
- Open Issues: 9
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# kubernetes-api
[](https://clojars.org/nubank/k8s-api)
kubernetes-api is a Clojure library that acts as a kubernetes client
## Motivation
We had a good experience with
[cognitect-labs/aws-api](https://github.com/cognitect-labs/aws-api), and missed
something like that for Kubernetes API. We had some client libraries that
generated a lot of code, but it lacked discoverability and documentation.
### clojure.deps
```clojure
{:deps {nubank/k8s-api {:mvn/version "1.0.0"}}}
```
### Leiningen
```clojure
[nubank/k8s-api "1.0.0"]
```
```clojure
;; In your ns statement
(ns my.ns
(:require [kubernetes-api.core :as k8s]))
```
## Usage
### Instantiate a client
There're multiple options for authentication while instantiating a client. You
can explicit set a token:
```clojure
(def k8s (k8s/client "http://some.host" {:token "..."}))
```
Or a function that returns the token
```clojure
(def k8s (k8s/client "http://some.host" {:token-fn (constantly "...")}))
```
You can also define client certificates
```clojure
(def k8s (k8s/client "http://some.host" {:ca-cert "/some/path/ca-docker.crt"
:client-cert "/some/path/client-cert.pem"
:client-key "/some/path/client-java.key"}))
```
#### OpenAPI config
##### Discovery
It's possible but NOT RECOMMENDED to disable the OpenAPI specification discovery. This will prevent requests to
`/openapi/...` endpoints and use the specification from the resources folder. This specification has no guarantees in
terms of versioning, so it will be outdated.
```clojure
(def k8s (k8s/client "http://some.host" {:token "..."
:openapi {:discovery :disabled}}))
```
##### Filter paths from api
You can filter the paths from the OpenAPI specification. This is useful when you want to use a specific version of the
api, or when you want to use a specific group of resources.
```clojure
(def k8s (k8s/client "http://some.host" {:token "..."
:apis ["some.api/v1alpha1", "another.api"]}))
```
### Discover
You can list all operations with
```clojure
(k8s/explore k8s)
```
or specify a specific entity
```clojure
(k8s/explore k8s :Deployment)
;=>
[:Deployment
[:get "read the specified Deployment"]
[:update "replace the specified Deployment"]
[:delete "delete a Deployment"]
[:patch "partially update the specified Deployment"]
[:list "list or watch objects of kind Deployment"]
[:create "create a Deployment"]
[:deletecollection "delete collection of Deployment"]
[:list-all "list or watch objects of kind Deployment"]]
```
get info on an operation
```clojure
(k8s/info k8s {:kind :Deployment
:action :create})
;=>
{:summary "create a Deployment",
:parameters {:namespace java.lang.String,
#schema.core.OptionalKey{:k :pretty} (maybe Str),
#schema.core.OptionalKey{:k :dry-run} (maybe Str),
#schema.core.OptionalKey{:k :field-manager} (maybe Str),
:body ...},
:returns {200 {#schema.core.OptionalKey{:k :apiVersion} (maybe Str),
#schema.core.OptionalKey{:k :kind} (maybe Str),
#schema.core.OptionalKey{:k :metadata} ...,
#schema.core.OptionalKey{:k :spec} ...,
#schema.core.OptionalKey{:k :status} ...},
201 {#schema.core.OptionalKey{:k :apiVersion} (maybe Str),
#schema.core.OptionalKey{:k :kind} (maybe Str),
#schema.core.OptionalKey{:k :metadata} ...,
#schema.core.OptionalKey{:k :spec} ...,
#schema.core.OptionalKey{:k :status} ...},
202 {#schema.core.OptionalKey{:k :apiVersion} (maybe Str),
#schema.core.OptionalKey{:k :kind} (maybe Str),
#schema.core.OptionalKey{:k :metadata} ...,
#schema.core.OptionalKey{:k :spec} ...,
#schema.core.OptionalKey{:k :status} ...},
401 Any}}
```
### Invoke
You can call an operation with
```clojure
(k8s/invoke k8s {:kind :ConfigMap
:action :create
:request {:namespace "default"
:body {:api-version "v1"
:data {"foo" "bar"}}}})
```
invoke it will return the body, with `:request` and `:response` in metadata
```clojure
(meta (k8s/invoke ...))
;=>
{:request ...
:response {:status ...
:body ...}}
```
You can debug the request map with
```clojure
(k8s/request k8s {:kind :ConfigMap
:action :create
:request {:namespace "default"
:body {:api-version "v1"
:data {"foo" "bar"}}}})
```
If you want to read more about all different patch strategies Kubernetes offers,
[check this document](doc/kubernetes-patch-strategies.md)