创建Kubernetes manifest 指南

前言

创建编排文件,是一件复杂的事情,很多时候可能没有头绪该如何开始。所以此篇文章提供一些创建的思路。

在定义资源时,将包含以下字段:

1
2
3
4
5
6
apiVersion: apps/v1
kind: Deployment
metadata:
...
spec:
...

以下操作均在1.20.0版本,其他版本命令或结果有所不同。

字段详解

apiVersion

该字段指用于创建资源的API组和药使用的API版本。Kubernetes API被聚合到API组中,v1是要使用的apps API版本。如果想列出可用的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
30
31
32
33
34
35
36
37
38
39
~ kubectl api-versions 
admissionregistration.k8s.io/v1
admissionregistration.k8s.io/v1beta1
apiextensions.k8s.io/v1
apiextensions.k8s.io/v1beta1
apiregistration.k8s.io/v1
apiregistration.k8s.io/v1beta1
apps/v1
authentication.k8s.io/v1
authentication.k8s.io/v1beta1
authorization.k8s.io/v1
authorization.k8s.io/v1beta1
autoscaling/v1
autoscaling/v2beta1
autoscaling/v2beta2
batch/v1
batch/v1beta1
certificates.k8s.io/v1
certificates.k8s.io/v1beta1
coordination.k8s.io/v1
coordination.k8s.io/v1beta1
crd.projectcalico.org/v1
discovery.k8s.io/v1beta1
events.k8s.io/v1
events.k8s.io/v1beta1
extensions/v1beta1
flowcontrol.apiserver.k8s.io/v1beta1
networking.k8s.io/v1
networking.k8s.io/v1beta1
node.k8s.io/v1
node.k8s.io/v1beta1
policy/v1beta1
rbac.authorization.k8s.io/v1
rbac.authorization.k8s.io/v1beta1
scheduling.k8s.io/v1
scheduling.k8s.io/v1beta1
storage.k8s.io/v1
storage.k8s.io/v1beta1
v1

kind

指定要创建的资源类型,比如Deployment、Pod和ReplicaSet等,可以使用以下命令查看可用的资源类型以及关联的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
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
~ kubectl api-resources | more
NAME SHORTNAMES APIVERSION NAMESPACED KIND
bindings v1 true Binding
componentstatuses cs v1 false ComponentStatus
configmaps cm v1 true ConfigMap
endpoints ep v1 true Endpoints
events ev v1 true Event
limitranges limits v1 true LimitRange
namespaces ns v1 false Namespace
nodes no v1 false Node
persistentvolumeclaims pvc v1 true PersistentVolum
eClaim
persistentvolumes pv v1 false PersistentVolum
e
pods po v1 true Pod
podtemplates v1 true PodTemplate
replicationcontrollers rc v1 true ReplicationCont
roller
resourcequotas quota v1 true ResourceQuota
secrets v1 true Secret
serviceaccounts sa v1 true ServiceAccount
services svc v1 true Service
mutatingwebhookconfigurations admissionregistration.k8s.io/v1 false MutatingWebhook
Configuration
validatingwebhookconfigurations admissionregistration.k8s.io/v1 false ValidatingWebho
okConfiguration
customresourcedefinitions crd,crds apiextensions.k8s.io/v1 false CustomResourceD
efinition
apiservices apiregistration.k8s.io/v1 false APIService
controllerrevisions apps/v1 true ControllerRevis
ion
daemonsets ds apps/v1 true DaemonSet
deployments deploy apps/v1 true Deployment
replicasets rs apps/v1 true ReplicaSet
statefulsets sts apps/v1 true StatefulSet
tokenreviews authentication.k8s.io/v1 false TokenReview
localsubjectaccessreviews authorization.k8s.io/v1 true LocalSubjectAcc
essReview
selfsubjectaccessreviews authorization.k8s.io/v1 false SelfSubjectAcce
ssReview
selfsubjectrulesreviews authorization.k8s.io/v1 false SelfSubjectRule
sReview
subjectaccessreviews authorization.k8s.io/v1 false SubjectAccessRe
view
horizontalpodautoscalers hpa autoscaling/v1 true HorizontalPodAu
toscaler
cronjobs cj batch/v1beta1 true CronJob
jobs batch/v1 true Job
certificatesigningrequests csr certificates.k8s.io/v1 false CertificateSign
ingRequest
leases coordination.k8s.io/v1 true Lease
bgpconfigurations crd.projectcalico.org/v1 false BGPConfiguratio
n
bgppeers crd.projectcalico.org/v1 false BGPPeer
blockaffinities crd.projectcalico.org/v1 false BlockAffinity
caliconodestatuses crd.projectcalico.org/v1 false CalicoNodeStatu
s
clusterinformations crd.projectcalico.org/v1 false ClusterInformat
ion
felixconfigurations crd.projectcalico.org/v1 false FelixConfigurat
ion
globalnetworkpolicies crd.projectcalico.org/v1 false GlobalNetworkPo
licy
globalnetworksets crd.projectcalico.org/v1 false GlobalNetworkSe
t
hostendpoints crd.projectcalico.org/v1 false HostEndpoint
ipamblocks crd.projectcalico.org/v1 false IPAMBlock
ipamconfigs crd.projectcalico.org/v1 false IPAMConfig
ipamhandles crd.projectcalico.org/v1 false IPAMHandle
ippools crd.projectcalico.org/v1 false IPPool
ipreservations crd.projectcalico.org/v1 false IPReservation
kubecontrollersconfigurations crd.projectcalico.org/v1 false KubeControllers
Configuration
networkpolicies crd.projectcalico.org/v1 true NetworkPolicy
networksets crd.projectcalico.org/v1 true NetworkSet
endpointslices discovery.k8s.io/v1beta1 true EndpointSlice
events ev events.k8s.io/v1 true Event
ingresses ing extensions/v1beta1 true Ingress
flowschemas flowcontrol.apiserver.k8s.io/v1beta1 false FlowSchema
prioritylevelconfigurations flowcontrol.apiserver.k8s.io/v1beta1 false PriorityLevelCo
nfiguration
ingressclasses networking.k8s.io/v1 false IngressClass
ingresses ing networking.k8s.io/v1 true Ingress
networkpolicies netpol networking.k8s.io/v1 true NetworkPolicy
runtimeclasses node.k8s.io/v1 false RuntimeClass
poddisruptionbudgets pdb policy/v1beta1 true PodDisruptionBu
dget
podsecuritypolicies psp policy/v1beta1 false PodSecurityPoli
cy
clusterrolebindings rbac.authorization.k8s.io/v1 false ClusterRoleBind
ing
clusterroles rbac.authorization.k8s.io/v1 false ClusterRole
rolebindings rbac.authorization.k8s.io/v1 true RoleBinding
roles rbac.authorization.k8s.io/v1 true Role
priorityclasses pc scheduling.k8s.io/v1 false PriorityClass
csidrivers storage.k8s.io/v1 false CSIDriver
csinodes storage.k8s.io/v1 false CSINode
storageclasses sc storage.k8s.io/v1 false StorageClass
volumeattachments storage.k8s.io/v1 false VolumeAttachmen
t

使用api-versionapi-resources命令可以找到可用资源与资源类型关联的API组以及API组版本。根据此信息填写apiVersion:kind:字段。

如果想了解某种资源类型的用途,可以使用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
28
~ kubectl explain --api-version=apps/v1 deployment
KIND: Deployment
VERSION: apps/v1

DESCRIPTION:
Deployment enables declarative updates for Pods and ReplicaSets.

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/sig-architecture/api-conventions.md#resources

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/sig-architecture/api-conventions.md#types-kinds

metadata <Object>
Standard object metadata.

spec <Object>
Specification of the desired behavior of the Deployment.

status <Object>
Most recently observed status of the Deployment.

metadata

用于唯一标识Kubernetes集群中的资源,可以为资源命名、分配标签、注解和指定命名空间等。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
$ kubectl explain deployment.metadata | more
KIND: Deployment
VERSION: apps/v1

RESOURCE: metadata <Object>

DESCRIPTION:
Standard object metadata.

ObjectMeta is metadata that all persisted resources must have, which
includes all objects users must create.

FIELDS:
annotations <map[string]string>
Annotations is an unstructured key value map stored with a resource that
may be set by external tools to store and retrieve arbitrary metadata. They
are not queryable and should be preserved when modifying objects. More
info: http://kubernetes.io/docs/user-guide/annotations
...

spec

可以定义要使用的容器镜像、副本数量、selector条件、存活或就绪探针的定义等。查看具体信息可以使用以下命令:

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
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
~ kubectl explain deployment.spec | more
KIND: Deployment
VERSION: apps/v1

RESOURCE: spec <Object>

DESCRIPTION:
Specification of the desired behavior of the Deployment.

DeploymentSpec is the specification of the desired behavior of the
Deployment.

FIELDS:
minReadySeconds <integer>
Minimum number of seconds for which a newly created pod should be ready
without any of its container crashing, for it to be considered available.
Defaults to 0 (pod will be considered available as soon as it is ready)

paused <boolean>
Indicates that the deployment is paused.

progressDeadlineSeconds <integer>
The maximum time in seconds for a deployment to make progress before it is
considered to be failed. The deployment controller will continue to process
failed deployments and a condition with a ProgressDeadlineExceeded reason
will be surfaced in the deployment status. Note that progress will not be
estimated during the time a deployment is paused. Defaults to 600s.

replicas <integer>
Number of desired pods. This is a pointer to distinguish between explicit
zero and not specified. Defaults to 1.

revisionHistoryLimit <integer>
The number of old ReplicaSets to retain to allow rollback. This is a
pointer to distinguish between explicit zero and not specified. Defaults to
10.

selector <Object> -required-
Label selector for pods. Existing ReplicaSets whose pods are selected by
this will be the ones affected by this deployment. It must match the pod
template's labels.

strategy <Object>
The deployment strategy to use to replace existin

获取模板

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
~ kubectl create deployment nginx --image=nginx -o yaml --dry-run=client
apiVersion: apps/v1
kind: Deployment
metadata:
creationTimestamp: null
labels:
app: nginx
name: nginx
spec:
replicas: 1
selector:
matchLabels:
app: nginx
strategy: {}
template:
metadata:
creationTimestamp: null
labels:
app: nginx
spec:
containers:
- image: nginx
name: nginx
resources: {}
status: {}

或者ingress

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
~ kubectl create ingress my-ingress --rule=host/path=app1:80 -o yaml --dry-run=client
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
creationTimestamp: null
name: my-ingress
spec:
rules:
- host: host
http:
paths:
- backend:
service:
name: app1
port:
number: 80
path: /path
pathType: Exact
status:
loadBalancer: {}

还可以使用 kubectl explain 添加--rescursive参数,可以获取各个字段的分层视图:

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
30
31
32
33
~ kubectl explain deployment.spec.template.spec.containers.livenessProbe --recursive | more
KIND: Deployment
VERSION: apps/v1

RESOURCE: livenessProbe <Object>

DESCRIPTION:
Periodic probe of container liveness. Container will be restarted if the
probe fails. Cannot be updated. More info:
https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes

Probe describes a health check to be performed against a container to
determine whether it is alive or ready to receive traffic.

FIELDS:
exec <Object>
command <[]string>
failureThreshold <integer>
httpGet <Object>
host <string>
httpHeaders <[]Object>
name <string>
value <string>
path <string>
port <string>
scheme <string>
initialDelaySeconds <integer>
periodSeconds <integer>
successThreshold <integer>
tcpSocket <Object>
host <string>
port <string>
timeoutSeconds <integer>

如果想进一步了解更详细的信息,可以继续拼接:

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
30
31
32
33
34
35
[root@k8s-node-217 ~]# kubectl explain deployment.spec.template.spec.containers.lifecycle
KIND: Deployment
VERSION: apps/v1

RESOURCE: lifecycle <Object>

DESCRIPTION:
Actions that the management system should take in response to container
lifecycle events. Cannot be updated.

Lifecycle describes actions that the management system should take in
response to container lifecycle events. For the PostStart and PreStop
lifecycle handlers, management of the container blocks until the action is
complete, unless the container process fails, in which case the handler is
aborted.

FIELDS:
postStart <Object>
PostStart is called immediately after a container is created. If the
handler fails, the container is terminated and restarted according to its
restart policy. Other management of the container blocks until the hook
completes. More info:
https://kubernetes.io/docs/concepts/containers/container-lifecycle-hooks/#container-hooks

preStop <Object>
PreStop is called immediately before a container is terminated due to an
API request or management event such as liveness/startup probe failure,
preemption, resource contention, etc. The handler is not called if the
container crashes or exits. The reason for termination is passed to the
handler. The Pod's termination grace period countdown begins before the
PreStop hooked is executed. Regardless of the outcome of the handler, the
container will eventually terminate within the Pod's termination grace
period. Other management of the container blocks until the hook completes
or until the termination grace period is reached. More info:
https://kubernetes.io/docs/concepts/containers/container-lifecycle-hooks/#container-hooks

总结

组成

整个编排文件分为四个字段或者四部分:

  1. apiVersion API组及版本
  2. kind 资源类型
  3. metadata 资源注解
  4. spec 定义和管理资源

常用命令

1
2
3
4
5
6
7
8
9
10
# 获取API 版本
kubectl api-versions
# 获取资源类型和API版本
kubectl api-resources
# 获取资源详情
kubectl explain --api-version=apps/v1 replicaset
# 根据资源创建基础模板
kubectl create deployment nginx --image=nginx -o yaml --dry-run=client
# 获取资源详情
kubectl explain deployment.spec.selector.matchExpressions.operator