shdctl cluster command
Validate that your Kubernetes cluster meets the deployment prerequisites before you deploy
阅读时间8 分钟最后更新于 13 天前
The command validates your manifest, and then verifies that the cluster your current kubeconfig context points at meets the deployment prerequisites.
cluster checkshdctl 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 in the current directory, then in each parent directory. To use a manifest that this auto-discovery won't find, pass : refer to Global flags.
manifest.yaml--manifestThe command is read-only by default: against the cluster, it runs only and commands.
kubectl getkubectl versionCluster check reference
The following table lists each check the command runs, in order, and the condition it verifies.
Check | What it verifies |
|---|---|
| |
| the current kubeconfig context's API server answers |
| the server runs Kubernetes 1.34 or later |
| at least three nodes are Ready, not cordoned, and carry no |
| a schedulable, untainted node is labeled |
| nodes labeled |
| a Ready node that isn't cordoned advertises |
| the storage class that |
| |
| |
| 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 |
| the |
| the ArgoCD |
| an |
| a node reports an IPv6 InternalIP — checked, as a warning, only when |
| with |
| with |
| with |
If a node pool has no running node, the command looks for a matching Karpenter 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.
NodePoolMost 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 check also fails when your kubeconfig can't list the StatefulSets in the target namespace.
volume templatesDeployments created with Self-Hosted Deployment 2.0.0 or earlier name in the manifest. With that field, the check fails when the cluster has no default storage class. This is because applies only to garage and the license server. Every other ReadWriteOnce volume uses the cluster default, and ReadWriteMany volumes use . The check warns when the named class exists but isn't the cluster default.
defaultStorageClassrwo storage classdefaultStorageClassreadWriteManyStorageClassWith , the check passes when the named class exists.
readWriteOnceStorageClassChoose the storage class field for an existing deployment
Kubernetes doesn't let you add or remove the storage class of an existing volume. The 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.
volume templatesManifest field | The check fails when |
|---|---|
| A volume template names no storage class. |
| No volume template uses the cluster default, and the templates name the class that |
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 |
|---|---|---|
| Pass | None. |
| Warning | None. |
| Failure | The command exits with a nonzero status. |
| Skipped | None. |
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 is missing or the cluster is unreachable, every check after that one is skipped.
kubectlThe 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 command accepts the following parameters:
cluster checkParameter | Description | Default |
|---|---|---|
| Provisions and deletes a temporary 1-GiB test volume for each configured storage class to verify that provisioning works. Mutates the cluster. | |
| Time to wait for a probe volume to bind. | |
| Prints the command plan without executing anything. | |
| Deployment format to validate for: | |
Verify that storage provisioning works
Add to verify that each configured storage class can provision a volume, including support:
--probe-storageReadWriteManyshdctl cluster check --probe-storage
This is the only option that changes anything in your cluster. For each configured storage class (the three rows above), the command creates a temporary 1-GiB named and labeled 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.
storage probePersistentVolumeClaimshdctl-cluster-check-*shdctl.unity.com/cluster-check=trueThe kubeconfig needs , , , and on persistentvolumeclaims in the target namespace, and on events there. A probe that binds provisions a real volume, which a class with keeps after the claim is gone.
getlistwatchcreatedeletelistreclaimPolicy: RetainThe command skips, rather than probes, storage classes that use , because binding such a class requires a scheduled pod. Skipped checks don't affect the exit code.
volumeBindingMode: WaitForFirstConsumerPreview the commands without contacting the cluster
Add to print every command that the checks will run. The command executes nothing and doesn't contact the cluster, so you can use for a security review:
--dry-runkubectl--dry-runshdctl 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 block, and skips them otherwise. To override that inference, pass :
deployment.argocd--formatshdctl cluster check --format argocd