|
| 1 | +# Objects In Kubernetes |
| 2 | + |
| 3 | +## Reference |
| 4 | + |
| 5 | +https://kubernetes.io/docs/concepts/overview/working-with-objects/ |
| 6 | + |
| 7 | +## Kubernetes Object Management |
| 8 | + |
| 9 | +```shell |
| 10 | +kubectl create deployment nginx --image nginx |
| 11 | +kubectl create -f nginx.yaml # create a object |
| 12 | +kubectl delete -f nginx.yaml -f redis.yaml # delete a object |
| 13 | +kubectl replace -f nginx.yaml # update a object |
| 14 | +kubectl diff -f configs/ && kubectl apply -f configs/ # make a patch & apply it |
| 15 | +``` |
| 16 | + |
| 17 | +## Object Names and IDs |
| 18 | + |
| 19 | +```yaml |
| 20 | +apiVersion: v1 |
| 21 | +kind: Pod |
| 22 | +metadata: |
| 23 | + name: nginx-demo # RFC1123 & RFC1035(start with char), len(name) <= 63 |
| 24 | +spec: |
| 25 | + containers: |
| 26 | + - name: nginx |
| 27 | + image: nginx:1.14.2 |
| 28 | + ports: |
| 29 | + - containerPort: 80 |
| 30 | +``` |
| 31 | +
|
| 32 | +## Labels and Selectors |
| 33 | +
|
| 34 | +```yaml |
| 35 | +apiVersion: v1 |
| 36 | +kind: Pod |
| 37 | +metadata: |
| 38 | + name: label-demo |
| 39 | + labels: |
| 40 | + environment: production # [a-z0-9A-Z], (-, _, .), len(key) <= 63 |
| 41 | + app: nginx |
| 42 | +spec: |
| 43 | + containers: |
| 44 | + - name: nginx |
| 45 | + image: nginx:1.14.2 |
| 46 | + ports: |
| 47 | + - containerPort: 80 |
| 48 | +``` |
| 49 | +
|
| 50 | +> Note: For some API types, such as ReplicaSets, the label selectors of two instances must not overlap within a namespace, or the controller can see that as conflicting instructions and fail to determine how many replicas should be present. |
| 51 | +
|
| 52 | +> Caution: For both equality-based and set-based conditions there is no logical OR (||) operator. Ensure your filter statements are structured accordingly. |
| 53 | +
|
| 54 | +```yaml |
| 55 | +apiVersion: v1 |
| 56 | +kind: Pod |
| 57 | +metadata: |
| 58 | + name: cuda-test |
| 59 | +spec: |
| 60 | + containers: |
| 61 | + - name: cuda-test |
| 62 | + image: "registry.k8s.io/cuda-vector-add:v0.1" |
| 63 | + resources: |
| 64 | + limits: |
| 65 | + nvidia.com/gpu: 1 |
| 66 | + nodeSelector: |
| 67 | + accelerator: nvidia-tesla-p100 # accelerator==nvidia-tesla-p100, in,notin and exists |
| 68 | +``` |
| 69 | +```yaml |
| 70 | +labelSelector=environment%3Dproduction,tier%3Dfrontend |
| 71 | +``` |
| 72 | + |
| 73 | +```shell |
| 74 | +kubectl get pods -l environment=production,tier=frontend |
| 75 | +``` |
| 76 | + |
| 77 | +```yaml |
| 78 | +?labelSelector=environment+in+%28production%2Cqa%29%2Ctier+in+%28frontend%29 |
| 79 | +``` |
| 80 | + |
| 81 | +```shell |
| 82 | +kubectl get pods -l 'environment in (production),tier in (frontend)' |
| 83 | +``` |
| 84 | + |
| 85 | +examples: https://github.com/kubernetes/examples/tree/master/guestbook/ |
| 86 | + |
| 87 | +```shell |
| 88 | +kubectl label pods -l app=nginx tier=fe # select all ngnix and add tier to fe |
| 89 | +kubectl get pods -l app=nginx -L tier # (--label-columns) to see it |
| 90 | +``` |
| 91 | + |
| 92 | +## Namespaces |
| 93 | + |
| 94 | +- default |
| 95 | +- kube-node-lease: [Lease](https://kubernetes.io/docs/concepts/architecture/leases/) Objects to send [heartbeats](https://kubernetes.io/docs/concepts/architecture/nodes/#heartbeats) |
| 96 | +- kube-public |
| 97 | +- kube-system |
| 98 | + |
| 99 | +```shell |
| 100 | +kubectl get namespace |
| 101 | +``` |
| 102 | + |
| 103 | +DNS: <service-name>.<namespace-name>.svc.cluster.local |
| 104 | + |
| 105 | +> By creating namespaces with the same name as [public top-level domains](https://data.iana.org/TLD/tlds-alpha-by-domain.txt), Services in these namespaces can have short DNS names that overlap with public DNS records. Workloads from any namespace performing a DNS lookup without a [trailing dot](https://datatracker.ietf.org/doc/html/rfc1034#page-8) will be redirected to those services, taking precedence over public DNS. |
| 106 | +To mitigate this, limit privileges for creating namespaces to trusted users. If required, you could additionally configure third-party security controls, such as [admission webhooks](https://kubernetes.io/docs/reference/access-authn-authz/extensible-admission-controllers/), to block creating any namespace with the name of [public TLDs](https://data.iana.org/TLD/tlds-alpha-by-domain.txt). |
| 107 | + |
| 108 | +namespace resources are not themselves in a namespace. And low-level resources, such as [nodes](https://kubernetes.io/docs/concepts/architecture/nodes/) and [persistentVolumes](https://kubernetes.io/docs/concepts/storage/persistent-volumes/), are not in any namespace. |
| 109 | +```shell |
| 110 | +kubectl api-resources --namespaced=true # in a namespace |
| 111 | +kubectl api-resources --namespaced=false # not in a namespace |
| 112 | +``` |
| 113 | + |
| 114 | +`kubernetes.io/metadata.name` is atomic labelling which is set by the control plane. |
| 115 | + |
| 116 | +## Annotations |
| 117 | + |
| 118 | +You can use Kubernetes annotations to attach arbitrary non-identifying metadata to [objects](https://kubernetes.io/docs/concepts/overview/working-with-objects/#kubernetes-objects). Clients such as tools and libraries can retrieve this metadata. |
| 119 | + |
| 120 | +```yaml |
| 121 | +apiVersion: v1 |
| 122 | +kind: Pod |
| 123 | +metadata: |
| 124 | + name: annotations-demo |
| 125 | + annotations: |
| 126 | + imageregistry: "https://hub.docker.com/" # it shows the imageregistry |
| 127 | +spec: |
| 128 | + containers: |
| 129 | + - name: nginx |
| 130 | + image: nginx:1.14.2 |
| 131 | + ports: |
| 132 | + - containerPort: 80 |
| 133 | +``` |
| 134 | +
|
| 135 | +# Field Selectors |
| 136 | +
|
| 137 | +```shell |
| 138 | +kubectl get pods --field-selector metadata.name=my-service |
| 139 | +kubectl get pods --field-selector metadata.namespace!=default |
| 140 | +kubectl get pods --field-selector status.phase=Pending |
| 141 | +``` |
| 142 | + |
| 143 | +```shell |
| 144 | +kubectl get pods,statefulsets,services --all-namespaces --field-selector=status.phase!=Running,spec.restartPolicy=Always |
| 145 | +``` |
| 146 | + |
| 147 | +# Finalizers |
| 148 | + |
| 149 | +Finalizers are namespaced keys that tell Kubernetes to wait until specific conditions are met before it fully deletes resources marked for deletion. Finalizers alert controllers to clean up resources the deleted object owned. |
| 150 | + |
| 151 | +When you tell Kubernetes to delete an object that has finalizers specified for it, the Kubernetes API marks the object for deletion by populating `.metadata.deletionTimestamp`, and returns a 202 status code (HTTP "Accepted"). The target object remains in a terminating state while the control plane, or other components, take the actions defined by the finalizers. After these actions are complete, the controller removes the relevant finalizers from the target object. When the `metadata.finalizers` field is empty, Kubernetes considers the deletion complete and deletes the object. |
| 152 | + |
| 153 | +> When you DELETE an object, Kubernetes adds the deletion timestamp for that object and then immediately starts to restrict changes to the .metadata.finalizers field for the object that is now pending deletion. You can remove existing finalizers (deleting an entry from the finalizers list) but you cannot add a new finalizer. You also cannot modify the deletionTimestamp for an object once it is set. |
| 154 | +After the deletion is requested, you can not resurrect this object. The only way is to delete it and make a new similar object. |
| 155 | + |
| 156 | +> Note: In cases where objects are stuck in a deleting state, avoid manually removing finalizers to allow deletion to continue. Finalizers are usually added to resources for a reason, so forcefully removing them can lead to issues in your cluster. This should only be done when the purpose of the finalizer is understood and is accomplished in another way (for example, manually cleaning up some dependent object). |
| 157 | +
|
| 158 | +# Owners and Dependents |
| 159 | + |
| 160 | +A valid owner reference (`metadata.ownerReferences`) consists of the object name and a UID within the same namespace as the dependent object. |
| 161 | +`ownerReferences.blockOwnerDeletion` |
| 162 | + |
| 163 | +> Note: Cross-namespace owner references are disallowed by design. Namespaced dependents can specify cluster-scoped or namespaced owners. A namespaced owner must exist in the same namespace as the dependent. If it does not, the owner reference is treated as absent, and the dependent is subject to deletion once all owners are verified absent. |
| 164 | +Cluster-scoped dependents can only specify cluster-scoped owners. In v1.20+, if a cluster-scoped dependent specifies a namespaced kind as an owner, it is treated as having an unresolvable owner reference, and is not able to be garbage collected. |
| 165 | +In v1.20+, if the garbage collector detects an invalid cross-namespace ownerReference, or a cluster-scoped dependent with an ownerReference referencing a namespaced kind, a warning Event with a reason of OwnerRefInvalidNamespace and an involvedObject of the invalid dependent is reported. You can check for that kind of Event by running `kubectl get events -A --field-selector=reason=OwnerRefInvalidNamespace`. |
| 166 | + |
| 167 | +# Recommended Labels |
| 168 | + |
| 169 | +Shared labels and annotations share a common prefix: `app.kubernetes.io`. Labels without a prefix are private to users. The shared prefix ensures that shared labels do not interfere with custom user labels. |
| 170 | + |
| 171 | +```yaml |
| 172 | +# This is an excerpt StatefulSet object |
| 173 | +apiVersion: apps/v1 |
| 174 | +kind: StatefulSet |
| 175 | +metadata: |
| 176 | + labels: |
| 177 | + app.kubernetes.io/name: mysql |
| 178 | + app.kubernetes.io/instance: mysql-abcxzy # every instance of an application must have a unique name. |
| 179 | + app.kubernetes.io/version: "5.7.21" |
| 180 | + app.kubernetes.io/component: database |
| 181 | + app.kubernetes.io/part-of: wordpress |
| 182 | + app.kubernetes.io/managed-by: helm |
| 183 | +``` |
| 184 | +
|
| 185 | +```yaml |
| 186 | +# This is an excerpt Deployment object, to oversee the pods running the application itself |
| 187 | +apiVersion: apps/v1 |
| 188 | +kind: Deployment |
| 189 | +metadata: |
| 190 | + labels: |
| 191 | + app.kubernetes.io/name: wordpress |
| 192 | + app.kubernetes.io/instance: wordpress-abcxzy # every instance of an application must have a unique name. |
| 193 | + app.kubernetes.io/version: "4.9.4" |
| 194 | + app.kubernetes.io/component: server |
| 195 | + app.kubernetes.io/part-of: wordpress |
| 196 | + app.kubernetes.io/managed-by: helm |
| 197 | +``` |
| 198 | +
|
| 199 | +```yaml |
| 200 | +# This is an excerpt Service object, to expose the application |
| 201 | +apiVersion: apps/v1 |
| 202 | +kind: Service |
| 203 | +metadata: |
| 204 | + labels: |
| 205 | + app.kubernetes.io/name: wordpress |
| 206 | + app.kubernetes.io/instance: wordpress-abcxzy # every instance of an application must have a unique name. |
| 207 | + app.kubernetes.io/version: "4.9.4" |
| 208 | + app.kubernetes.io/component: server |
| 209 | + app.kubernetes.io/part-of: wordpress |
| 210 | + app.kubernetes.io/managed-by: helm |
| 211 | +``` |
0 commit comments