Kube Rest API

All resources within K8s are grouped into different API groups. To find which API group a k8s resource belongs to run k explain <resource>.

The kube-apiserver is available at https://kube-master:6443

API Groups

/version - to view the cluster version

/metrics - to get cluster metrics

/healthz - to monitor the cluster health

/logs - to integrate with 3rd party logging applications

/api - used to interact with the cluster (core group)

/apis - used to interact with the cluster (named group)

Core API group (`/api`)

All the core functionalities exist in this API group. All the resources (functionalities) are scattered in this group.

Named API group (`/apis`)

The named API group is organized into subgroups (resources) based on the category. The newer features in k8s and going forward all the incoming features will be made available in this group. Several actions (verbs) can be performed on the resources.

Authenticating to Kube-ApiServer

Most of the API endpoint will require you to authenticate to the kube-apiserver. This means passing the login credentials in the curl command. Alternatively, you can setup a proxy client to by running the command kubectl proxy which will automatically proxy your API requests and add the credentials from the

KubeConfig file on your local system. So, you no longer need to pass the authentication details in every curl command.

Examples

Get version - curl https://kube-master:6443/version

List pods - curl https://kube-master:6443/api/v1/pods

API Versions

An API group can have multiple versions supported at the same time. Either of these API versions can be used to create a resource. But, when you query the resource it checks for it in the Preferred API version. Also, when a resource is created in an API version other than the Storage API version, it is converted to the storage API version before storing in the etcd database. Usually, the stable API version is the Preferred and Storage API version.

Since alpha versions are not enabled by default, we can enable them by editing the kube-apiserver's config.

Check the preferred version for an API

Steps:

Setup kubectl proxy on port 8001 - k proxy 8001 &

Send a GET request to the API - curl localhost:8001/apis/authorization.k8s.io

The output will be like this:


{
  "kind": "APIGroup",
  "apiVersion": "v1",
  "name": "authorization.k8s.io",
  "versions": [
    {
      "groupVersion": "authorization.k8s.io/v1",
      "version": "v1"
    }
  ],
  "preferredVersion": {
    "groupVersion": "authorization.k8s.io/v1",
    "version": "v1"
  }
}

API Deprecation Policy Rules

Rule 1

API elements may only be removed by incrementing the version of the API group.

In the example below, the resource webinar can only be removed by incrementing the version from v1alpha1 to v1alpha2. But both the versions will be supported because otherwise, all the usage of v1alpha1 will have to be incremented. But, the preferred/supported version can be v1alpha2.

Rule 2

API objects must be able to round-trip between API versions in a given release without information loss, with the exception of whole REST resources that do not exist in some versions.

In the example below, v1alpha1 does not have duration field but v1alpha2 does. So we need to add the field duration to v1alpha1 so that when downgrading from v1alpha2 to v1alpha1, both the v1alpha1 versions are the same.

Rule 3

An API version in a given track may not be deprecated until a new API version at least as stable is released.

If v2alpha1 is released, v1 will not be deprecated until v2 goes through its complete lifecycle and becomes a stable release.

Rule 4a

Other than the most recent API versions in each track, older API versions must be supported after their announced deprecation for a duration of no less than: GA: 12 months or 3 releases (whichever is longer) Beta: 9 months or 3 releases (whichever is longer) Alpha: 0 releases

Deprecated (old) alpha versions need not be supported in the next releases.

Deprecated beta versions only need to be supported till 3 releases (see v1beta1). Also according to Rule 4b, v1 becomes the preferred version only after the next release and not in its first release.

Rule 4b

The "preferred" API version and the "storage version" for a given group may not advance until after a release has been made that supports both the new version and the previous version

When v1beta2 is released, v1beta1 is still the preferred version (between the lines) even though it is deprecated. Only in the next release will v1beta2 become the preferred version.

Upgrading the version of a K8s manifest

kubectl convert -f nginx-old.yaml --output-version apps/v1 > nginx-new.yaml - this requires the installation of kubectl convert tool from K8s.