Skaffold’s config validation is a surprisingly powerful debugging tool that goes far beyond simple syntax checks, revealing deep structural issues in your Kubernetes manifests and Skaffold configuration.
Let’s see Skaffold in action, validating a common misconfiguration. Imagine you have a Deployment that needs a ConfigMap, but you’ve accidentally referenced the ConfigMap using the wrong name in your Deployment’s envFrom section.
# deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: my-app
spec:
replicas: 1
selector:
matchLabels:
app: my-app
template:
metadata:
labels:
app: my-app
spec:
containers:
- name: my-app
image: nginx:latest
ports:
- containerPort: 80
envFrom:
- configMapRef:
name: WRONG_CONFIGMAP_NAME # This is the typo
---
# configmap.yaml
apiVersion: v1
kind: ConfigMap
metadata:
name: my-config # This is the correct name
data:
MY_VAR: "some_value"
Before you even try to skaffold dev or skaffold build, you can run skaffold diagnose. Skaffold will parse your skaffold.yaml and all referenced Kubernetes manifests.
skaffold diagnose
The output will pinpoint the exact location of the error:
ERRO[0000] Error validating Kubernetes manifests:
- Deployment "my-app" in namespace "default":
- Container "my-app":
- envFrom[0]: configMapRef.name "WRONG_CONFIGMAP_NAME" not found
This tells you precisely which resource (Deployment "my-app"), which part of that resource (Container "my-app"), and which specific field (envFrom[0]: configMapRef.name) is causing the problem, and that the referenced ConfigMap simply doesn’t exist.
The mental model for skaffold diagnose is that it acts as a pre-flight check. It simulates the Kubernetes API interaction by fetching all resources defined in your manifests and then performs a series of validation checks. These checks include:
- Resource Existence: Verifying that referenced resources (like ConfigMaps, Secrets, PersistentVolumeClaims) actually exist in the provided manifests.
- Field Validation: Ensuring that fields within your Kubernetes objects conform to expected schemas and types.
- Skaffold Configuration Integrity: Checking for inconsistencies or invalid configurations within your
skaffold.yamlitself, such as incorrect artifact definitions or invalid Kubernetes context settings. - Image Name and Tag Resolution: For build steps, it can validate that image names are properly formatted and that tags are being applied as expected.
- Port Conflicts: In more advanced scenarios, it can even detect potential port conflicts between services.
To fix the example above, you’d simply correct the name in deployment.yaml:
# deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: my-app
spec:
replicas: 1
selector:
matchLabels:
app: my-app
template:
metadata:
labels:
app: my-app
spec:
containers:
- name: my-app
image: nginx:latest
ports:
- containerPort: 80
envFrom:
- configMapRef:
name: my-config # Corrected name
---
# configmap.yaml
apiVersion: v1
kind: ConfigMap
metadata:
name: my-config
data:
MY_VAR: "some_value"
Running skaffold diagnose again would now pass this specific check.
Skaffold’s diagnose command is more than just a linter; it actively tries to "understand" your Kubernetes configuration by resolving references between resources. This means it can catch issues that a simple kubectl apply --dry-run might miss, especially when dealing with complex interdependencies.
One common pitfall is when Skaffold’s skaffold.yaml references an artifact that isn’t properly defined or has a missing build step. For instance, if you have a deploy section that depends on an artifact named my-backend-image, but you’ve forgotten to define how my-backend-image is built:
# skaffold.yaml
apiVersion: skaffold/v2
kind: Config
metadata:
name: my-project
build:
artifacts:
- image: frontend
docker:
dockerfile: frontend/Dockerfile
deploy:
kubectl:
manifests:
- k8s/deployment.yaml # This deployment references my-backend-image
Running skaffold diagnose would catch this:
ERRO[0000] Error validating Skaffold configuration:
- Unknown artifact "my-backend-image" referenced in deploy section
The fix is to add the missing artifact definition to the build section of your skaffold.yaml:
# skaffold.yaml
apiVersion: skaffold/v2
kind: Config
metadata:
name: my-project
build:
artifacts:
- image: frontend
docker:
dockerfile: frontend/Dockerfile
- image: my-backend-image # Added missing artifact definition
docker:
dockerfile: backend/Dockerfile
deploy:
kubectl:
manifests:
- k8s/deployment.yaml
This ensures that Skaffold knows how to build all the images your Kubernetes manifests depend on.
When skaffold diagnose reports an issue with a Kubernetes manifest, it’s often because it can’t resolve a reference. This could be a ConfigMapRef, SecretRef, ServiceAccountName, or even a PersistentVolumeClaim name that isn’t defined in any of the manifests Skaffold is aware of. Skaffold gathers all these manifests first, then tries to build an internal representation of your desired state. If a reference points to something that isn’t in that collected set, it flags it.
The most insidious errors skaffold diagnose can catch are subtle ordering or dependency issues between your manifests. If you have a Service that targets a Deployment by label, but the Deployment itself is missing the necessary selector or the Service is referencing the wrong selector, skaffold diagnose can sometimes highlight these inconsistencies based on how it tries to resolve resource relationships. It’s not a full-blown Kubernetes admission controller, but it does a good job of catching common setup mistakes.
If skaffold diagnose passes without errors, the next thing you’ll likely encounter is a timeout during the skaffold dev or skaffold apply phase if your application has networking issues or fails to become ready.