kubectl apply: How to Apply Multiple Files and Directories

July 20, 2026

Using kubectl apply is the standard way to deploy applications and configurations to a Kubernetes cluster. You can apply multiple manifest files by specifying a directory path, such as kubectl apply -f /path/to/directory/, or by listing individual files with multiple -f flags. For complex applications, it's crucial to also consider resource dependencies, application order, and robust error handling, which often involves more advanced tools and strategies.

Understanding `kubectl apply` and Idempotency

When you use kubectl apply, you are leveraging the core of Kubernetes' declarative management model. The command sends your manifest files—declarative object definitions—to the kube-apiserver over HTTPS. The key principle behind kubectl apply is idempotency: running the command multiple times with the same manifest will produce the same end state. The first time, it creates the resources. On subsequent runs, it compares the desired state in your local manifest with the live object configuration in the cluster and only applies the necessary changes, if any. This makes it a safe and predictable way to manage your application's lifecycle.

This process initiates a reconciliation loop. Once the API server validates and persists the object configuration to etcd, Kubernetes controllers work continuously to bring the cluster's actual state into alignment with this new desired state.

The Kubernetes Control Plane's Role

The Kubernetes control plane acts as the "brain" of the cluster, and its components are central to the kubectl apply workflow. It's not a single process but a collection of specialized components working together:

kube-apiserver: This is the entry point for all kubectl commands. It performs authentication, RBAC permission checks, schema validation, and runs admission controllers before writing the object's desired state to etcd.
etcd: A consistent and highly-available key-value store that serves as the durable record for both the desired specification and the current observed state of all cluster objects.
kube-controller-manager: This component runs various controllers that watch etcd for changes. When a new desired state is recorded, the relevant controller (e.g., Deployment controller, ReplicaSet controller) takes action to create or modify resources to match the specification.
kube-scheduler: This component watches for newly created Pods that have no node assigned. It then selects the optimal node for them to run on based on resource requirements, policies, and other constraints.

This continuous loop of declaring a state, having controllers reconcile it, and observing the outcome is fundamental to Kubernetes' self-healing and robust nature.

Applying Multiple Files with `kubectl apply`

kubectl apply is designed to handle multiple manifest files efficiently, which is essential for deploying complex applications composed of numerous Kubernetes resources like Deployments, Services, ConfigMaps, and Secrets.

Applying All Files in a Directory

To apply all Kubernetes manifest files within a specific directory, use the -f (or --filename) flag with the directory path. Kubernetes will process all files with standard YAML or JSON extensions in that directory.

kubectl apply -f /path/to/your/manifests/directory/

This command sends each manifest found in the directory to the kube-apiserver for processing.

Applying Specific Multiple Files

If your manifest files are in different locations or you only want to apply a subset, you can specify each file individually using multiple -f flags:

kubectl apply -f deployment.yaml -f service.yaml -f configmap.yaml

This approach provides granular control over which resources are applied.

Recursive Application in Directories

For nested directory structures, you can use the --recursive or -R flag to apply all manifest files within a directory and all of its subdirectories.

kubectl apply -f /path/to/your/manifests/ --recursive

This is particularly useful for complex projects where manifests are organized into component-specific subfolders. A more advanced use of this multi-file pattern is seen in tools like Crossplane, which provisions external infrastructure using Kubernetes manifests. You might apply a Provider manifest to install AWS support, a ProviderConfig with credentials, and then multiple Managed Resource manifests (e.g., rds-instance.yaml, rds-subnet-group.yaml) to create a complete cloud database setup.

Managing Application Order and Dependencies

While applying all files in a directory is convenient, kubectl apply does not guarantee a specific order of resource creation. This can cause failures if one resource depends on another (e.g., a Pod that needs a ConfigMap to exist first). For simple cases, applying manifests in separate, ordered commands can work, but this approach doesn't scale.

For robust dependency management, declarative GitOps tools are the recommended solution. Tools like Argo CD and Flux CD manage application deployments by using a Git repository as the single source of truth.

Argo CD operates as a Kubernetes controller that continuously monitors a Git repository. When it detects a difference between the manifests in Git (the desired state) and the resources in the cluster (the actual state), it automatically synchronizes them. By defining an application.yaml, you specify the source repository and path, and Argo CD handles the deployment, providing health assessments, drift detection, and rollback capabilities.
Flux CD offers a similar GitOps workflow with a modular architecture of controllers that manage sources (like Git) and apply Kustomize or Helm configurations.

These tools ensure that your application's components are deployed correctly and maintained in their desired state, overcoming the ordering limitations of a simple kubectl apply -f.

Handling Errors During Multi-File Application

When applying many manifests, errors can occur at multiple stages. Using kubectl apply --dry-run=server can help validate manifests against the API server without creating resources, catching syntax and schema errors early.

However, many errors are runtime issues that appear after the apply command completes. Troubleshooting often depends on the tools you are using:

In Argo CD, if the live state deviates from Git, this is called "drift." You can diagnose it using argocd app get <app-name> to check sync status and argocd app diff <app-name> to see the specific differences between the expected and actual configurations.
In Crossplane, failures often stem from misconfigurations between manifests. Common issues include:
- Provider not healthy: The Crossplane provider pod itself may have issues. Check its status with kubectl describe provider <provider-name>.
- Configuration Mismatches: An error like ProviderConfig not found often means the providerConfigRef.name in your resource manifest doesn't match an existing ProviderConfig object. Use kubectl get providerconfig to verify names.
- Authentication Problems: If a cloud resource is created but never becomes READY, it often points to credential or permission issues. This could be a broken reference to a credentials Secret, an incorrectly configured IAM role (IRSA in AWS), or under-scoped cloud permissions.

Advanced `kubectl` Features for Workflow Management

Recent Kubernetes versions have added features that enhance the kubectl experience, especially for managing complex workflows.

`kuberc` for User Preferences

The kuberc feature, enabled by default, allows users to separate their individual preferences (like command aliases and default flag settings) from cluster credentials and server information stored in kubeconfig. This means you can maintain consistent local workflows across multiple clusters without modifying shared configuration files. The kubectl kuberc management command helps view and edit these preferences.

Feature	Description	Benefit
`kuberc`	Separates user preferences from `kubeconfig`	Consistent local workflows across clusters
`kubectl kuberc`	Management command for `kuberc`	Programmatic preference editing

Mutating Admission Policies

Graduating to stable in Kubernetes 1.36, Mutating Admission Policies provide a declarative, in-process way to modify resources as they are created. Using Common Expression Language (CEL), administrators can define policies that, for example, automatically inject a sidecar container or set default labels on all new Pods. These policies are defined with MutatingAdmissionPolicy objects and applied via MutatingAdmissionPolicyBinding. By using CEL with Server-Side Apply (SSA) merge logic or JSON Patch, the API server performs these mutations internally, reducing the latency and operational overhead of external mutating webhooks.

Best Practices for Managing Multiple Manifests

When dealing with multiple Kubernetes manifests, especially in a team environment or for complex applications, consider these best practices:

Version Control: Always store your manifest files in a version control system like Git. This allows for tracking changes, collaboration, and easy rollbacks.
Declarative Configuration: Embrace the declarative nature of Kubernetes. Define the desired state, and let Kubernetes reconcile it. Avoid manual kubectl editing that can break this model.
Organize by Application/Component: Structure your manifest directories logically, perhaps by application or by component within an application. This improves readability and maintainability.
Use kustomize or Helm: For more advanced scenarios involving templating, overlays, or package management, tools like kustomize (built into kubectl) or Helm can significantly simplify managing multiple manifests and their variations across environments.
Validate Before Applying: Use kubectl apply --dry-run=server to validate your manifests against the API server without actually persisting any changes. This can catch errors early.

Frequently Asked Questions

How do I apply all YAML files in a directory using `kubectl`?

You can apply all YAML files in a directory by using the command kubectl apply -f /path/to/your/directory/. This will process all valid Kubernetes manifest files within that directory.

Can I apply multiple specific files with a single `kubectl apply` command?

Yes, you can specify multiple files by using the -f flag for each file, like so: kubectl apply -f file1.yaml -f file2.yaml.

What does it mean that `kubectl apply` is idempotent?

Idempotency means that running the same kubectl apply command multiple times results in the same cluster state. The command calculates the difference between your manifest and the live state and only applies the necessary changes.

Does `kubectl apply -f` guarantee the order of resource creation?

No, kubectl apply -f directory/ applies files alphabetically but does not guarantee resource creation order, which can cause issues with dependencies. For ordered deployments, consider using GitOps tools like Argo CD or Flux.

What happens when I `kubectl apply` a manifest?

When you kubectl apply a manifest, the kube-apiserver receives it, validates it, and persists it to etcd. Controllers then notice the desired state and work to reconcile the cluster to match that state, creating or updating resources as needed.

What is the `kuberc` feature in `kubectl`?

The kuberc feature allows users to store personal kubectl preferences like aliases and default flags separately from cluster configuration in kubeconfig. This helps maintain consistent workflows across different clusters.

Conclusion

Efficiently applying multiple Kubernetes manifests is a fundamental operation for any Kubernetes user. While kubectl apply -f is perfect for simple deployments from a directory or a list of files, managing complex applications requires more. Understanding the idempotency of apply, the role of the control plane, and the limitations around application order is key. For production-grade systems, leveraging GitOps tools like Argo CD and advanced features like Mutating Admission Policies provides the necessary control, reliability, and error handling to maintain robust and scalable Kubernetes environments.

Sources & References

Want to actually learn kubectl apply multiple files?

Curo turns topics like this into a personalized, guided learning board - built around what you already know. Free to start.

Try Curo

Or jump straight in:

kubectl apply multiple files kubectl apply all files in directory