共通項目＠リソース定義¶
はじめに¶
本サイトにつきまして、以下をご認識のほど宜しくお願いいたします。
01. apiVersion¶
apiVersionとは¶
APIグループのバージョンを設定する。
kube-apiserverをアップグレードすると、APIグループの特定のバージョンが廃止されることがある。
もし、そのバージョンを指定したマニフェストをkubectl applyコマンドやclient-goパッケージで送信しようとすると、マニフェストのKubernetesリソースを作成できずにエラーになってしまう。
apiVersion: v1
APIグループ¶
▼ バージョンの段階¶
バージョンは、成熟度に応じて、alpha、beta、stable、の段階がある。
alphaのみデフォルトで無効化されており、betaやstableであれば、マニフェストで指定すればそのまま使用できる。
もしバージョンのv2にKubernetesが対応していなければ、v1beta1やv2beta2で回避する方法がある。
02. kind¶
作成されるKubernetesリソースの種類を設定する。
03. metadata.annotation¶
annotationとは¶
任意のキーと値を設定する。
.metadata.labelsキーとは異なり、設定できる情報に制約がない。
任意のKubernetesリソースの場合¶
▼ kubectl.kubernetes.io/last-applied-configuration¶
kube-apiserverが、前回のkubectl applyコマンドで適用したマニフェストの設定値をJSONで割り当てる。
kubectl applyコマンドの削除処理時に、kube-apiserverは送信されたマニフェストと.metadata.annotations.kubectl.kubernetes.io/last-applied-configurationキーを比較し、削除すべき部分を決定する。
kubectl editコマンドでマニフェストを変更してしまうと、.metadata.annotations.kubectl.kubernetes.io/last-applied-configurationキーが変更されない。
そのため、次回のkubectl applyコマンドが失敗することがある。
また、kubectl applyしたいマニフェストが多すぎると、JSONが大きすぎて、kubectl applyに失敗することがある。
apiVersion: extensions/v1beta1
kind: Deployment
metadata:
annotations:
kubectl.kubernetes.io/last-applied-configuration: |
{"apiVersion":"extensions/v1beta1","kind":"Deployment" ... }
▼ kubernetes.ioキー¶
Kubernetesリソースに関する情報を設定する。
.metadata.annotationsキー配下にも同じキーがあることに注意する。
| キー | 値の例 | 説明 |
|---|---|---|
kubernetes.io/createdby |
aws-ebs-dynamic-provisioner |
Kubernetesリソースを作成したツールを設定する。 |
Ingressの場合¶
▼ kubernetes.io/ingress.class¶
現在、非推奨である。
代わりとして、.spec.ingressClassnameキーを指定する。
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
annotations:
kubernetes.io/ingress.class: foo-ingress-class
▼ ingressclass.kubernetes.io/is-default-class¶
IngressがClusterネットワーク内に1つしか存在しない場合、IngressClassに設定することにより、デフォルトとする。
Ingressが新しく作成された場合、このIngressClassの設定値が使用されるようになる。
複数のIngressClassをデフォルトに設定しないようにする。
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
annotations:
ingressclass.kubernetes.io/is-default-class: "true"
PersistentVolumeの場合¶
▼ pv.kubernetes.ioキー¶
PersistentVolumeに関する情報を設定する。
kube-controllerが設定してくれるため、開発者が設定する必要はない。
▼ 種類¶
| キー | 値の例 | 説明 |
|---|---|---|
pv.kubernetes.io/bound-by-controller |
yes |
PersistentVolumeのCSIドライバーのコントローラーがプロビジョニングしたかどうかを設定する。 |
pv.kubernetes.io/provisioned-by |
ebs.csi.aws.com (AWS EBS CSIドライバー)、kubernetes.io/aws-ebs (非推奨) |
そのPersistVolumeを作成したツールを設定する。 |
PersistentVolumeClaimの場合¶
▼ volume.kubernetes.ioキーとは¶
PersistentVolumeClaimに関する情報を設定する。
kube-controllerが設定してくれるため、開発者が設定する必要はない。
| キー | 値の例 | 説明 |
|---|---|---|
volume.kubernetes.io/storage-provisioner |
ebs.csi.aws.com (AWS EBS CSIドライバー)、kubernetes.io/aws-ebs (非推奨) |
PersistentVolumeClaimに紐づくPersistentVolumeを作成したツールを設定する。 |
volume.kubernetes.io/selected-node |
ip-*-*-*-*.ap-northeast-1.compute.internal |
PersistentVolumeClaimに紐づくPersistentVolumeが配置されているNode名を設定する。正しいNode名を指定しないと、N node(s) had volume node affinity conflict, N node(s) didn't match Pod's node affinity/selectorというエラーになってしまう。 |
03-02. metadata.finalizers¶
finalizersとは¶
Kubernetesリソースに親子関係がある場合に、親リソースよりも先に子リソースを削除できるようにするため、親リソースの削除を防ぐ。
この時、.metadata.finalizersキーの値で親名が定義されている。
関連する子リソースが削除されると、.metadata.finalizersキーが削除され、親リソースも削除されるようになる。
apiVersion: apps/v1
kind: Deployment
metadata:
finalizers:
- foo-finalizer
deletionTimestamp: "2022-01-01T12:00:00Z"
03-03. metadata.generation¶
generation¶
Kubernetesリソースが最初に作成されてから何回変更されたかの回数 (世代数) を設定する。
マニフェストのどこかの設定値を変更すると、世代数が増える。
kube-controllerが設定してくれるため、開発者が設定する必要はない。
apiVersion: apps/v1
kind: Deployment
metadata:
generation: 3
03-04. metadata.labels¶
labelsとは¶
Kubernetesが、Kubernetesリソースの一意に識別するための情報を設定する。
apiVersion: apps/v1
kind: Deployment
metadata:
labels:
app.kubernetes.io/name: foo-deployment
値は、string型である必要がある。
int型を割り当てようとするとエラーになり、これはHelmのvaluesファイル経由で『数字』を出力しようとする場合に起こる。
予約Label¶
キー名のプレフィクスとして、kubernetes.io/とk8s.io/は予約されている。
任意のKubernetesリソースの場合¶
▼ app.kubernetes.ioキー¶
Kubernetes上で稼働するコンテナの情報を設定する。
| キー | 値の例 | 説明 |
|---|---|---|
app.kubernetes.io/app |
foo、foo-service |
マイクロサービス名を設定する。 |
app.kubernetes.io/component |
app、database |
K8sリソースをシステムの要素と捉えた時に、その役割名を設定する。 |
app.kubernetes.io/created-by |
kube-controller-manager |
このKubernetesリソースを作成したリソースやユーザーを設定する。 |
app.kubernetes.io/env |
prd、stg、tes、dev |
アプリケーションの実行環境名を設定する。 |
app.kubernetes.io/instance |
mysql-12345 |
アプリコンテナのインスタンス名を設定する。 |
app.kubernetes.io/managed-by |
helm、foo-operator |
K8sリソースの管理ツール名を設定する。 |
app.kubernetes.io/name |
foo-service、prometheus |
アプリ側であればマイクロサービス名、インフラ側であればツール名を設定する。 |
app.kubernetes.io/part-of |
bar |
K8sリソースをシステムの要素と捉えた時に、その親のシステム名を設定する。 |
app.kubernetes.io/type |
host (PVのマウント対象) |
リソースの設定方法の種類名を設定する。 |
app.kubernetes.io/version |
5.7.21 |
K8sリソースのリリースバージョン名を設定する。 |
▼ kubernetes.ioキー¶
Kubernetesリソースに関する情報を設定する。
.metadata.annotationsキー配下にも同じキーがあることに注意する。
kube-controllerが設定してくれるため、開発者が設定する必要はない。
| キー | 値の例 | 説明 |
|---|---|---|
kubernetes.io/arch |
amd64 |
NodeのCPUアーキテクチャを設定する。 |
kubernetes.io/hostname |
ip-*-*-*-*.ap-northeast-1.compute.internal (AWSの場合) |
Nodeのホスト名を設定する。 |
kubernetes.io/os |
linux |
NodeのOSを設定する。 |
Nodeの場合¶
▼ ラベルの設定方法¶
kubeletの--node-labelsオプションを使用すると、Nodeにラベルを設定できる。
--node-labels=nodetype=foo
▼ node.kubernetes.ioキー¶
Nodeの情報を設定する。
| キー | 値の例 | 説明 |
|---|---|---|
node.kubernetes.io/nodetype |
batch、ingress、master |
コンテナを持つPodのスケジューリング先とするNodeグループを設定する。 |
▼ node-role.kubernetes.ioキー¶
Nodeのtaintsを設定する。
| キー | 値の例 | 説明 |
|---|---|---|
node-role.kubernetes.io/master |
NoSchedule、PreferNoSchedule |
Podのスケジューリングのルールを設定する。 |
▼ topology.kubernetes.ioキー¶
Nodeに関する情報を設定する。
kube-controllerが設定してくれるため、開発者が設定する必要はない。
| キー | 値の例 | 説明 |
|---|---|---|
topology.kubernetes.io/region |
ap-northeast-1 (AWSの場合) |
Nodeが稼働しているリージョンを設定する。 |
topology.kubernetes.io/zone |
ap-northeast-1a (AWSの場合) |
Nodeが稼働しているAZを設定する。 |
Role、ClusterRole、の場合¶
▼ rbac.authorization.k8s.ioキー¶
全てのKubernetesリソースに対して、一括して認可スコープを定義する。
特定のKubernetesリソースに関して認可スコープを狭くしたい場合、.rulesキー配下でそれを定義する。
| キー | 値の例 | 説明 |
|---|---|---|
rbac.authorization.k8s.io/aggregate-to-admin |
true |
Cluster内の全てのKubernetesリソースに全ての操作が可能な認可スコープを設定する。 |
rbac.authorization.k8s.io/aggregate-to-edit |
true |
Namespace内の全てのKubernetesリソースに変更操作が可能な認可スコープを設定する。 |
rbac.authorization.k8s.io/aggregate-to-view |
true |
Cluster内の全てのKubernetesリソースに対して閲覧操作が可能な認可スコープを設定する。 |
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
labels:
rbac.authorization.k8s.io/aggregate-to-admin: "true"
rbac.authorization.k8s.io/aggregate-to-edit: "true"
rbac.authorization.k8s.io/aggregate-to-view: "true"
name: foo
rules: ... # 特定のKubernetesリソースの認可スコープを狭めたい場合は、.rulesキーでそれを定義する
03-05. metadata.managedFields¶
managedFieldsとは¶
特定のマネージャーが管理するマニフェストのキー部分が自動的に割り当てられており、ここにないキーは管理外である。
kubectl applyコマンドで--server-sideオプションを有効化した場合に作成される。
.metadata.managedFields[*].managerキーで、クライアント (kubectlクライアント、Kubernetesリソース) が管理している部分と、それ以外のマネージャーが管理している部分を区別できる。
.metadata.managedFields[*].managerキーにないマネージャーはマニフェストを変更できない。
.metadata.managedFieldsキー配下にマネージャーを新しく追加するためには、基本的には--force-conflictsオプションを使用する必要がある (他にも方法はあるが) 。
ただし、kube-controllerやOperatorでは常に--force-conflictsオプションを実行するようになっている。
- https://qiita.com/superbrothers/items/aeba9406691388b6a19e
- https://speakerdeck.com/superbrothers/wakaru-metadata-dot-managedfields?slide=21
- https://kubernetes.io/docs/reference/using-api/server-side-apply/#field-management
- https://kubernetes.io/docs/reference/using-api/server-side-apply/#using-server-side-apply-in-a-controller
確認方法¶
.metadata.managedFieldsキーを確認する場合、kubectl getコマンドで-oオプションと--show-managed-fieldsオプションを有効化する必要がある。
$ kubectl get deployment foo-deployment -o yaml --show-managed-fields
もし、特定のキーが管理下にあるか否かを調べる場合、grepコマンドと組み合わせる。
$ kubectl get deployment foo-deployment -o yaml --show-managed-fields | grep -e manager -e f:<マニフェストのキー>
---
apiVersion: apps/v1
kind: Deployment
metadata:
managedFields:
# kubectlコマンドによる管理
- manager: kubectl # デフォルト値
apiVersion: apps/v1
# kube-apiserverに対するリクエスト内容。ここでは、kubectl applyコマンドの実行履歴を確認できる。
operation: Apply
# kubectlコマンドが管理するマニフェストのキー部分
fields: ...
# kubectlコマンドによる管理
- manager: kubectl # デフォルト値
apiVersion: apps/v1
# kube-apiserverに対するリクエスト内容。ここでは、kubectl editコマンドの実行履歴を確認できる。
operation: Edit
# kubectlコマンドが管理するマニフェストのキー部分
fields: ...
# kube-controller-managerによる管理 (後からの変更)
- manager: kube-controller-manager
apiVersion: apps/v1
# kube-apiserverに対するリクエスト内容
operation: Update
time: "2022-01-01T16:00:00.000Z"
# kube-controller-managerが管理するマニフェストのキー部分
fields: ...
# operatorによる管理 (後からの変更)
- manager: operator
apiVersion: apps/v1
# kube-apiserverに対するリクエスト内容
operation: Update
time: "2022-01-01T16:00:00.000Z"
# operatorが管理するマニフェストのキー部分
fields: ...
# ArgoCDのapplication-controllerによる管理 (後からの変更)
- manager: argocd-application-controller
apiVersion: apps/v1
# kube-apiserverに対するリクエスト内容
operation: Update
time: "2022-01-01T16:00:00.000Z"
# ArgoCDのapplication-controllerが管理するマニフェストのキー部分
fields: ...
03-06. metadata.name¶
nameとは¶
Kubernetesリソースを一意に識別するための名前を設定する。
apiVersion: apps/v1
kind: Deployment
metadata:
name: foo-deployment
名前は変更不可¶
Kubernetesにとって.metadata.nameキーはIDであり、後から変更できない。
もし別の名前に変更したい場合は、再作成する必要がある。
03-07. metadata.namespace¶
namespaceとは¶
Kubernetesリソースを作成するNamespaceを設定する。
apiVersion: apps/v1
kind: Deployment
metadata:
namespace: foo-namespace
03-08. metadata.uid¶
uid¶
そのKubernetesリソースを識別するユニークIDを設定する。
kube-controllerが設定してくれるため、開発者が設定する必要はない。
また仮に開発者が変更しても、kube-controllerやcustom-controllerが正しい値に自動的に修復する。
apiVersion: apps/v1
kind: Deployment
metadata:
uid: *****
...
04. status¶
status¶
▼ statusとは¶
Kubernetesリソースの現在の状態を設定する。
kube-controllerが設定してくれるため、開発者が設定する必要はない。
また仮に開発者が変更しても、kube-controllerやcustom-controllerが正しい値に自動的に修復する。
Kubernetesリソースごとに、.statusキー配下の構造は異なっており、
conditions¶
▼ conditionsとは¶
.statusキーの履歴を設定する。
kube-controllerが設定してくれるため、開発者が設定する必要はない。
また仮に開発者が変更しても、kube-controllerやcustom-controllerが正しい値に自動的に修復する。
apiVersion: apps/v1
kind: Deployment
spec: ...
status:
conditions:
- lastProbeTime: null
lastTransitionTime: "2022-01-01T06:24:02Z"
status: "True"
type: Initialized
- lastProbeTime: null
lastTransitionTime: "2022-01-01T07:01:45Z"
status: "True"
type: Ready
- lastProbeTime: null
lastTransitionTime: "2022-01-01T07:01:45Z"
status: "True"
type: ContainersReady
- lastProbeTime: null
lastTransitionTime: "2022-01-01T06:24:02Z"
status: "True"
type: PodScheduled
observedGeneration¶
▼ observedGenerationとは¶
kube-controllerやcustom-controllerがKubernetesリソースの状態を管理している場合に、これらが検知した.metadata.generationキーの値を設定する。
kube-controllerが設定してくれるため、開発者が設定する必要はない。
また仮に開発者が変更しても、kube-controllerやcustom-controllerが正しい値に自動的に修復する。
.metadata.generationキーよりも.status.observedGenerationキーの方が世代数が小さい場合、kube-controllerやcustom-controllerがKubernetesリソースを検出できていない不具合を表す。
apiVersion: apps/v1
kind: Deployment
spec:
---
status:
observedGeneration: 3
conditions: ...