kumactl apply: Apply Kuma Policies
kumactl apply creates or updates Kuma resources (meshes, traffic policies, dataplane definitions) from a YAML file or stdin.
kumactl apply is the imperative path for shipping mesh policy from CI when you are not using the Kubernetes CRD flow. It validates against the control plane before committing.
What it does
kumactl apply sends a Kuma resource definition to the control plane, which validates it and creates or updates it. It works with any Kuma resource kind (Mesh, TrafficPermission, MeshTrafficPermission, RateLimit, and so on) and supports templating with variables.
Common usage
kumactl apply -f traffic-permission.yaml
# from stdin
cat mesh.yaml | kumactl apply -f -
# validate only, do not persist
kumactl apply -f policy.yaml --dry-runOptions
| Flag | What it does |
|---|---|
| -f, --file <path> | Resource file to apply (- for stdin) |
| --dry-run | Validate and print without persisting |
| -v, --var <key=value> | Substitute a template variable |
| --mesh <name> | Default mesh for the resource |
In CI
Use kumactl apply --dry-run -f as a PR gate to validate policy against the control plane without changing it, then apply for real on merge. On Kubernetes, prefer kubectl apply of the CRDs; kumactl apply is for the universal (non-k8s) deployment mode.
Common errors in CI
"Invalid ... : ... : must be defined" or "validation error" means the resource is missing a required field or references a mesh that does not exist. "Could not connect to the Control Plane API Server" is the same CP-reachability problem as inspect. On Kubernetes-mode CPs, apply is read-only for some kinds and returns "operation not allowed"; use kubectl instead.
Using this in CI
A runner has no kubeconfig, no cached context, and no interactive auth. Every kubectl invocation in CI needs the context supplied explicitly, and most confusing CI failures here are the command running against the wrong cluster or no cluster at all.
# never rely on the ambient context on a runner
kubectl --context "$KUBE_CONTEXT" -n "$NAMESPACE" get pods
# confirm what you are actually connected to before mutating anything
kubectl config current-context
kubectl cluster-info
# fail fast instead of hanging on an unreachable API server
kubectl --request-timeout=30s get nodes