kubernetes打交道少不了要写YAML,如果你和我一样需要经常手写YAML文件话,对apiVersion对象的定义有没有纠结过,它的GroupVersion以及Kind该如何确定?或者根本就没想过,直接复制粘贴。直到我看完

Kubernetes API 资源使用:应该使用哪个 Group 和 Version?

这篇文章后才发现kubernetes1.11.0版本开始已为我们准备了相关命令去获取我们当前集群所支持API的相关信息,这也是最准确的。随着kubernetes版本的迭代相关API也会做一定的调整,为什么别人的YAML文件在我这里kubectl apply的时候就报错啊,可能就是这个原因。详细关于kubernetes api的生命周期可以看一下这一篇

Kubernetes使用声明式的 API 让系统更加健壮。但是这样也意味着我们需要通过使用CLI或者REST API来创建一个资源对象来告诉系统我们想要的操作。为此,我们需要定义 API 资源的名称、组和版本等信息。因为有太多的资源、太多的版本、太多的组了,而且都非常容易产生混淆,因此这会让用户感到很困惑。一个创建 DeploymentYAML文件 ,里边会看到apiVersion: apps/v1beta2apiVersion: apps/v1等等这样的信息,到底我们应该用哪一个呢?哪一个才是正确的呢?怎样确定Kubernetes集群支持的版本信息呢?其实这些信息简单的使用kubectl命令就可以获取到。

API Resources

我们可以通过下面的命令来获取Kubernetes集群支持的所有 API 资源:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
$ kubectl api-resources -o wide
NAME                              SHORTNAMES   APIGROUP                       NAMESPACED   KIND                             VERBS
bindings                                                                      true         Binding                          [create]
componentstatuses                 cs                                          false        ComponentStatus                  [get list]
configmaps                        cm                                          true         ConfigMap                        [create delete deletecollection get list patch update watch]
endpoints                         ep                                          true         Endpoints                        [create delete deletecollection get list patch update watch]
events                            ev                                          true         Event                            [create delete deletecollection get list patch update watch]
limitranges                       limits                                      true         LimitRange                       [create delete deletecollection get list patch update watch]
namespaces                        ns                                          false        Namespace                        [create delete get list patch update watch]
nodes                             no                                          false        Node                             [create delete deletecollection get list patch proxy update watch]
persistentvolumeclaims            pvc                                         true         PersistentVolumeClaim            [create delete deletecollection get list patch update watch]
persistentvolumes                 pv                                          false        PersistentVolume                 [create delete deletecollection get list patch update watch]
pods                              po                                          true         Pod                              [create delete deletecollection get list patch proxy update watch]
podtemplates                                                                  true         PodTemplate                      [create delete deletecollection get list patch update watch]
replicationcontrollers            rc                                          true         ReplicationController            [create delete deletecollection get list patch update watch]
resourcequotas                    quota                                       true         ResourceQuota                    [create delete deletecollection get list patch update watch]
secrets                                                                       true         Secret                           [create delete deletecollection get list patch update watch]
serviceaccounts                   sa                                          true         ServiceAccount                   [create delete deletecollection get list patch update watch]
services                          svc                                         true         Service                          [create delete get list patch proxy update watch]
mutatingwebhookconfigurations                  admissionregistration.k8s.io   false        MutatingWebhookConfiguration     [create delete deletecollection get list patch update watch]
validatingwebhookconfigurations                admissionregistration.k8s.io   false        ValidatingWebhookConfiguration   [create delete deletecollection get list patch update watch]
customresourcedefinitions         crd          apiextensions.k8s.io           false        CustomResourceDefinition         [create delete deletecollection get list patch update watch]
apiservices                                    apiregistration.k8s.io         false        APIService                       [create delete deletecollection get list patch update watch]
controllerrevisions                            apps                           true         ControllerRevision               [create delete deletecollection get list patch update watch]
daemonsets                        ds           apps                           true         DaemonSet                        [create delete deletecollection get list patch update watch]
deployments                       deploy       apps                           true         Deployment                       [create delete deletecollection get list patch update watch]
replicasets                       rs           apps                           true         ReplicaSet                       [create delete deletecollection get list patch update watch]
statefulsets                      sts          apps                           true         StatefulSet                      [create delete deletecollection get list patch update watch]
...

注意:kubernetes集群1.11.0版本以上才支持api-resources命令

上面命令输出了很多有用的信息:

  • SHORTNAMES - 资源名称的简写,比如 deployments 简写就是 deploy,配合kubectl 快捷使用
  • APIGROUP - API组,如果为空话代表core组,也就是核心API,查看官方文档可以了解更多详细信息
  • KIND - 资源名称
  • VERBS - 可用的方法,在你想要定义ClusterRole RBAC规则时很有用。你还可以选择获取特定 API 组的 API 资源,例如:
1
2
3
4
5
6
7
$ kubectl api-resources --api-group apps -o wide
NAME                  SHORTNAMES   APIGROUP   NAMESPACED   KIND                 VERBS
controllerrevisions                apps       true         ControllerRevision   [create delete deletecollection get list patch update watch]
daemonsets            ds           apps       true         DaemonSet            [create delete deletecollection get list patch update watch]
deployments           deploy       apps       true         Deployment           [create delete deletecollection get list patch update watch]
replicasets           rs           apps       true         ReplicaSet           [create delete deletecollection get list patch update watch]
statefulsets          sts          apps       true         StatefulSet          [create delete deletecollection get list patch update watch]

对于上面的每种资源类型,我们都可以使用kubectl explain命令来获取相关的资源详细信息:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
$ kubectl explain configmap
KIND:     ConfigMap
VERSION:  v1

DESCRIPTION:
     ConfigMap holds configuration data for pods to consume.

FIELDS:
   apiVersion	<string>
     APIVersion defines the versioned schema of this representation of an
     object. Servers should convert recognized schemas to the latest internal
     value, and may reject unrecognized values. More info:
     https://git.k8s.io/community/contributors/devel/api-conventions.md#resources

   data	<map[string]string>
     Data contains the configuration data. Each key must consist of alphanumeric
     characters, '-', '_' or '.'.

   kind	<string>
     Kind is a string value representing the REST resource this object
     represents. Servers may infer this from the endpoint the client submits
     requests to. Cannot be updated. In CamelCase. More info:
     https://git.k8s.io/community/contributors/devel/api-conventions.md#types-kinds

   metadata	<Object>
     Standard object's metadata. More info:
     https://git.k8s.io/community/contributors/devel/api-conventions.md#metadata

kubectl explain命令很有用,特别是在我们不知道该如何编写YAML文件的时候,可以使用该命令来帮助我们获得更多信息。

需要注意的是explain命令可能会显示旧版本的group/version,可以通过--api-version参数显示指定版本,比如:

1
kubectl explain replicaset --api-version apps/v1

API Versions

使用kubectl api-versions命令来获取集群支持的所有 API 版本:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
$ kubectl api-versions
admissionregistration.k8s.io/v1beta1
apiextensions.k8s.io/v1beta1
apiregistration.k8s.io/v1beta1
apps/v1
apps/v1beta1
apps/v1beta2
authentication.k8s.io/v1
authentication.k8s.io/v1beta1
authorization.k8s.io/v1
authorization.k8s.io/v1beta1
autoscaling/v1
autoscaling/v2beta1
batch/v1
batch/v1beta1
certificates.k8s.io/v1beta1
certmanager.k8s.io/v1alpha1
enterprises.upmc.com/v1
events.k8s.io/v1beta1
extensions/v1beta1
metrics.k8s.io/v1beta1
monitoring.coreos.com/v1
networking.k8s.io/v1
policy/v1beta1
rbac.authorization.k8s.io/v1
rbac.authorization.k8s.io/v1beta1
storage.k8s.io/v1
storage.k8s.io/v1beta1
v1

输出结果是以group/version的方式呈现的,可以通过查看此页面了解更多有关Kubernetes中 API 版本控制的信息。

有的时候,我们只想确认特定的group/version是否可以用于某些资源。因为大多数的资源都支持GET方法,所以我们可以提供 下API 的 versiongroup 然后尝试获取下资源,即可验证,kubectl get ..,例如:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
$ kubectl get deployments.v1.apps -n kube-system
NAME                                    DESIRED   CURRENT   UP-TO-DATE   AVAILABLE   AGE
autoscaler-aws-cluster-autoscaler       1         1         1            1           55d
calico-kube-controllers                 1         1         1            1           317d
calico-policy-controller                0         0         0            0           317d
dns-controller                          1         1         1            1           317d
elasticsearch-operator                  1         1         1            1           274d
hpa-hpa-operator                        1         1         1            1           60d
hpa-metrics-server                      1         1         1            1           60d
kube-dns                                2         2         2            2           317d
kube-dns-autoscaler                     1         1         1            1           317d
spot-rescheduler-k8s-spot-rescheduler   1         1         1            1           136d
tiller-deploy                           1         1         1            1           315d

如果指定的group/version资源不存在或者资源本身就不存在,我们将会收到错误信息。

总结

本文将帮助您了解YAML文件中的kindapiVersion这两个内容,如果你想了解更多关于Kubernetes设计的信息,我建议你查看下这篇文章

参考

https://akomljen.com/kubernetes-api-resources-which-group-and-version-to-use/

https://kubernetes.io/zh/docs/concepts/overview/kubernetes-api/