Two ways to use it
– Use one of the official client libraries (C, dotnet, Go, Hashkell, Java, JavaScript, Perl, Python, Ruby)
– Use the curl command
REST API endpoint
– OpenAPI V2: /openapi/v2 endpoint
– OpenAPI V3: /openapi/v3 endpoint
API Discovery
Discovery endpoint to list all available groups/versions:
/openapi/v3
Sample output:
{ "paths": { ..., "api/v1": { "serverRelativeURL": "/openapi/v3/api/v1?hash=CC0E9BFD992D8C59AEC98A1E2336F899E8318D3CF4C68944C3DEC640AF5AB52D864AC50DAA8D145B3494F75FA3CFF939FCBDDA431DAD3CA79738B297795818CF" }, "apis/admissionregistration.k8s.io/v1": { "serverRelativeURL": "/openapi/v3/apis/admissionregistration.k8s.io/v1?hash=E19CC93A116982CE5422FC42B590A8AFAD92CDE9AE4D59B5CAAD568F083AD07946E6CB5817531680BCE6E215C16973CD39003B0425F3477CFD854E89A9DB6597" }, .... } } |
List resources supported for a group:
/apis/FOO_GROUP/FOO_VERSION
For example: /openapi/v3/apis/rbac.authorization.k8s.io/v1.
Example of request the list of resources for the apps group v1:
curl localhost:8001/openapi/v3/apis/apps/v1
Sample output:
{ "openapi": "3.0.0", "info": { "title": "Kubernetes", "version": "v1.26.4" }, "paths": { "/apis/apps/v1/": { "get": { "tags": [ "apps_v1" ], "description": "get available resources", "operationId": "getAppsV1APIResources", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/io.k8s.apimachinery.pkg.apis.meta.v1.APIResourceList" } }, "application/vnd.kubernetes.protobuf": { "schema": { "$ref": "#/components/schemas/io.k8s.apimachinery.pkg.apis.meta.v1.APIResourceList" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/io.k8s.apimachinery.pkg.apis.meta.v1.APIResourceList" } } } }, "401": { "description": "Unauthorized" } } } }, .... |
API groups and versioning
To make updates easier, Kubernetes supports multiple versions of the API, each at a different API path, such as /api/v1 or /apis/rbac.authorization.k8s.io/v1alpha1.
Versioning is done at the API level rather than the resource level.
API resources are distinguished by their API group, resource type, namespace (for namespace resources) and name.
Exemple of a namespaced resource: POST /apis/apps/v1/my-tools/deployments
group : apps
apps api version : v1
namespace: my-tools
name/resource: deployments
Locate and authenticate against the API server with REST API
There are 2 ways:
-Run kubectl in proxy mode (recommended).
This method is recommended, since it uses the stored apiserver location and verifies the identity of the API server using a self-signed cert. No
man-in-the-middle (MITM) attack is possible using this method.
– provide the location and credentials directly to the http client with a Authorization header such as : « Authorization: Bearer $TOKEN ».
The credential is a secret we need to create with kubectl to access the service account.
Example:
# Check all possible clusters, as your .KUBECONFIG may have multiple contexts: kubectl config view -o jsonpath='{"Cluster name\tServer\n"}{range .clusters[*]}{.name}{"\t"}{.cluster.server}{"\n"}{end}' # Select name of cluster you want to interact with from above output: export CLUSTER_NAME="some_server_name" # Point to the API server referring the cluster name APISERVER=$(kubectl config view -o jsonpath="{.clusters[?(@.name==\"$CLUSTER_NAME\")].cluster.server}") # Create a secret to hold a token for the default service account kubectl apply -f - <<EOF apiVersion: v1 kind: Secret metadata: name: default-token annotations: kubernetes.io/service-account.name: default type: kubernetes.io/service-account-token EOF # Wait for the token controller to populate the secret with a token: while ! kubectl describe secret default-token | grep -E '^token' >/dev/null; do echo "waiting for token..." >&2 sleep 1 done # Get the token value TOKEN=$(kubectl get secret default-token -o jsonpath='{.data.token}' | base64 --decode) # Explore the API with TOKEN curl -X GET $APISERVER/api --header "Authorization: Bearer $TOKEN" --insecure |