文档

shdctl cluster command

Validate that your Kubernetes cluster meets the deployment prerequisites before you deploy
阅读时间8 分钟最后更新于 13 天前

The
cluster check
command validates your manifest, and then verifies that the cluster your current kubeconfig context points at meets the deployment prerequisites.
shdctl cluster check
The command requires a manifest, because it reads the target namespace, the storage class names, and the deployment method from it. It doesn't require a pulled release, so you can run it before you download the release package. It looks for
manifest.yaml
in the current directory, then in each parent directory. To use a manifest that this auto-discovery won't find, pass
--manifest
: refer to Global flags.
The command is read-only by default: against the cluster, it runs only
kubectl get
and
kubectl version
commands.

Cluster check reference

The following table lists each check the command runs, in order, and the condition it verifies.

Check

What it verifies

kubectl available
kubectl
is on your
PATH
cluster reachable
the current kubeconfig context's API server answers
kubernetes version
the server runs Kubernetes 1.34 or later
general worker nodes
at least three nodes are Ready, not cordoned, and carry no
NoSchedule
or
NoExecute
taint — one node with
configuration.infrastructure.singleNode: true
transformations pool
a schedulable, untainted node is labeled
aks-node-pool=argocpu
, or a Karpenter NodePool provisions one. Transformation workflows select that label and stay Pending without it
large transformations pool
nodes labeled
aks-node-pool=argocpu-large
carry the matching
NoSchedule
taint and one is Ready — or, with none at rest, a Karpenter NodePool provisions them with that taint declared. Warns rather than fails: only memory-intensive transformation retries run there
gpu nodes
a Ready node that isn't cordoned advertises
nvidia.com/gpu
, or a Karpenter NodePool declares a
nvidia.com/gpu
taint. Runs only when
configuration.transformations.gpu.enabled
is
true
. Warns instead of failing, because when another autoscaler scales a GPU pool from zero, the command finds no GPU node to check
rwo storage class
the storage class that
configuration.kubernetes.storage.readWriteOnceStorageClass
names exists. If the manifest names
defaultStorageClass
instead, that class exists and the cluster has a default storage class. For details, refer to the paragraphs after this table
rwx storage class
configuration.kubernetes.storage.readWriteManyStorageClass
is set and exists; only
--probe-storage
proves it provisions ReadWriteMany volumes
namespace
configuration.kubernetes.namespace
exists. Nothing in the release creates it, so create it before the first deploy
volume templates
the StatefulSets in the namespace were created with the storage class field that the manifest uses. A namespace with no StatefulSet passes. For details, refer to Choose the storage class field for an existing deployment
metrics api
the
v1beta1.metrics.k8s.io
APIService is available; warns otherwise. Horizontal pod autoscaling requires it
argocd application crd
the ArgoCD
Application
CRD is installed — checked for the
argocd
format only
argocd controller
an
argocd-application-controller
pod is Ready — checked for the
argocd
format only, and skipped when your kubeconfig can't list pods in every namespace
node ipv6 addresses
a node reports an IPv6 InternalIP — checked, as a warning, only when
configuration.networking.ipFamily
is
ipv6
storage probe (default class)
with
--probe-storage
only: a 1-GiB test PVC binds on the cluster's default class, when the manifest names
defaultStorageClass
storage probe (manifest class)
with
--probe-storage
only: a 1-GiB test PVC binds on the class that the manifest names in
readWriteOnceStorageClass
, or in
defaultStorageClass
when that class isn't the cluster default
storage probe (rwx class)
with
--probe-storage
only: a 1-GiB
ReadWriteMany
test PVC binds on
readWriteManyStorageClass
If a node pool has no running node, the command looks for a matching Karpenter
NodePool
instead. Clusters that scale transformation capacity from zero with Karpenter therefore pass the node pool checks even when no node is running. If Karpenter isn't installed, or your credentials can't read its resources, the command ignores the lookup, because Karpenter is optional: a pool that another autoscaler scales from zero reports as missing while it is empty.
Most checks read cluster-scoped objects: nodes, storage classes, the namespace, the metrics APIService, and the Application custom resource definition (CRD). If your kubeconfig can't read nodes, storage classes, the namespace, or the CRD, those checks fail, so a namespace-scoped kubeconfig fails the command. Run the command with a kubeconfig that can read cluster-scoped objects. The
volume templates
check also fails when your kubeconfig can't list the StatefulSets in the target namespace.
Deployments created with Self-Hosted Deployment 2.0.0 or earlier name
defaultStorageClass
in the manifest. With that field, the
rwo storage class
check fails when the cluster has no default storage class. This is because
defaultStorageClass
applies only to garage and the license server. Every other ReadWriteOnce volume uses the cluster default, and ReadWriteMany volumes use
readWriteManyStorageClass
. The check warns when the named class exists but isn't the cluster default.
With
readWriteOnceStorageClass
, the check passes when the named class exists.

Choose the storage class field for an existing deployment

Kubernetes doesn't let you add or remove the storage class of an existing volume. The
volume templates
check makes sure that the manifest uses the storage class field that the StatefulSets in the namespace were created with. Garage and the license server use the manifest's storage class with either field, so the check leaves them out of this comparison and checks them separately, as described after the table.

Manifest field

The check fails when

readWriteOnceStorageClass
A volume template names no storage class.
defaultStorageClass
No volume template uses the cluster default, and the templates name the class that
defaultStorageClass
names.
When the check fails, its hint says which of the two fields the manifest needs. A storage class that a per-chart override sets doesn't count for either field.
With either field, the check also fails when the volumes of garage or the license server name a different storage class from the one in the manifest. This means that the storage class changed after you created the deployment.

Read the results

Each check reports one of these statuses:

Symbol

Status

Effect on the exit code

✔
PassNone.
⚠
WarningNone.
✘
FailureThe command exits with a nonzero status.
-
SkippedNone.
Failed and warning checks also print a remediation hint. Because the command exits with a nonzero status when any check fails, you can use it to gate a CI pipeline before the deployment steps. When
kubectl
is missing or the cluster is unreachable, every check after that one is skipped.
The output looks like the following example:
Context: my-cluster (https://kubernetes.example.com)Manifest: namespace asset-solutions✔ kubectl available client v1.34.1✔ cluster reachable server v1.34.1✔ kubernetes version 1.34 ≥ 1.34 required✔ general worker nodes 3 schedulable node(s) (need ≥ 3): node-1, node-2, node-3✔ transformations pool 2 node(s) labeled aks-node-pool=argocpu: node-4, node-5✔ large transformations pool no node at rest; provisioned on demand by Karpenter NodePool transformations-large (taint declared)- gpu nodes manifest does not enable transformations.gpu✔ rwo storage class gp3 (every ReadWriteOnce volume; no cluster default needed)✔ rwx storage class efs-sc exists (RWX capability verified only with --probe-storage)✔ namespace asset-solutions exists✔ volume templates no StatefulSet in asset-solutions yet✔ metrics api v1beta1.metrics.k8s.io available✔ argocd application crd applications.argoproj.io installed✔ argocd controller pod/argocd-application-controller-0 is Ready- node ipv6 addresses manifest ipFamily is ipv4 (default)Summary: 13 passed, 0 warning, 0 failed, 2 skipped

Parameters for cluster check

The
cluster check
command accepts the following parameters:

Parameter

Description

Default

--probe-storage
Provisions and deletes a temporary 1-GiB test volume for each configured storage class to verify that provisioning works. Mutates the cluster.
false
--probe-timeout
Time to wait for a probe volume to bind.
60s
--dry-run
Prints the command plan without executing anything.
false
--format
Deployment format to validate for:
argocd
or
helm
. Selects whether the ArgoCD checks run.
argocd
if the manifest contains a
deployment.argocd
block, otherwise
helm

Verify that storage provisioning works

重要
--probe-storage
creates and deletes resources in your cluster. Every other
cluster check
option is read-only.
Add
--probe-storage
to verify that each configured storage class can provision a volume, including
ReadWriteMany
support:
shdctl cluster check --probe-storage
This is the only option that changes anything in your cluster. For each configured storage class (the three
storage probe
rows above), the command creates a temporary 1-GiB
PersistentVolumeClaim
named
shdctl-cluster-check-*
and labeled
shdctl.unity.com/cluster-check=true
in the target namespace, waits for it to bind, and then deletes it. If a probe fails to bind, the command reads the events in that namespace to report why.
The kubeconfig needs
get
,
list
,
watch
,
create
and
delete
on persistentvolumeclaims in the target namespace, and
list
on events there. A probe that binds provisions a real volume, which a class with
reclaimPolicy: Retain
keeps after the claim is gone.
The command skips, rather than probes, storage classes that use
volumeBindingMode: WaitForFirstConsumer
, because binding such a class requires a scheduled pod. Skipped checks don't affect the exit code.

Preview the commands without contacting the cluster

Add
--dry-run
to print every
kubectl
command that the checks will run. The command executes nothing and doesn't contact the cluster, so you can use
--dry-run
for a security review:
shdctl cluster check --dry-run
A real run also reads your kubeconfig to name the context it checks; the plan doesn't list that read.

Select the deployment format

By default, the command runs the ArgoCD checks if your manifest contains a
deployment.argocd
block, and skips them otherwise. To override that inference, pass
--format
:
shdctl cluster check --format argocd

Additional resources