> ## Documentation Index
> Fetch the complete documentation index at: https://notes.kodekloud.com/llms.txt
> Use this file to discover all available pages before exploring further.
# WorkflowTemplates
> Explains Argo WorkflowTemplates and ClusterWorkflowTemplates as reusable workflow recipes, how to define and reference them with templateRef or workflowTemplateRef to share and standardize CI/CD steps.
Think of a WorkflowTemplate as a reusable recipe for Argo Workflows. Instead of copying and pasting the same manifest (for example, a build step or a test container) into every workflow, define it once as a WorkflowTemplate and reference it from many workflows. This centralizes maintenance, enforces consistency, and reduces duplication.
A WorkflowTemplate stores common templates in a namespace so teams can share and reuse steps like functions from a library. Use templates to standardize CI/CD tasks such as builds, tests, and deployments.
## How to define a WorkflowTemplate
Defining a WorkflowTemplate is the same as defining a Workflow, except the resource kind is WorkflowTemplate. That tells Argo to store the definition as a reusable template rather than executing it immediately.
Example WorkflowTemplate (cowsay):
```yaml theme={null}
apiVersion: argoproj.io/v1alpha1
kind: WorkflowTemplate
metadata:
name: cowsay-template
namespace: argo
spec:
entrypoint: cowsay
templates:
- name: cowsay
inputs:
parameters:
- name: message
container:
image: rancher/cowsay
command: ["cowsay"]
args: ["{{inputs.parameters.message}}"]
```
Create this resource with kubectl apply -f \ or via the Argo Workflows UI/CLI (for example, `argo template create `).
## Reusing a WorkflowTemplate
Once a WorkflowTemplate exists in a namespace, you can reuse it in two primary ways:
* templateRef — call a single template from the WorkflowTemplate as a step inside a larger workflow (like importing a single function from a library).
* workflowTemplateRef — run the entire WorkflowTemplate as a complete workflow, using its specified entrypoint and arguments.
| Reuse Method | When to use | Example |
| ------------------- | ----------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| templateRef | Use when you want a specific template (step) from the template library inside a larger workflow | `templateRef: { name: cowsay-template, template: cowsay }` |
| workflowTemplateRef | Use when you want to execute the whole WorkflowTemplate as a workflow | `workflowTemplateRef: { name: cowsay-template }` |
Example: calling a single template from a WorkflowTemplate using templateRef
```yaml theme={null}
apiVersion: argoproj.io/v1alpha1
kind: Workflow
metadata:
generateName: use-single-template-
spec:
entrypoint: my-custom-workflow
templates:
- name: my-custom-workflow
steps:
- - name: first-step
templateRef:
name: cowsay-template # name of the WorkflowTemplate
template: cowsay # name of the template inside the WorkflowTemplate
arguments:
parameters:
- name: message
value: "I called this from another workflow!"
```
Example: running the whole WorkflowTemplate using workflowTemplateRef
```yaml theme={null}
apiVersion: argoproj.io/v1alpha1
kind: Workflow
metadata:
generateName: run-whole-template-
namespace: argo
spec:
arguments:
parameters:
- name: message
value: "Hello from a WorkflowTemplate!"
workflowTemplateRef:
name: cowsay-template
```
## ClusterWorkflowTemplate
A ClusterWorkflowTemplate is the cluster-scoped equivalent of WorkflowTemplate. It is not tied to a namespace and is available cluster-wide — a good fit for platform teams that must provide approved, central templates to multiple namespaces.
Example ClusterWorkflowTemplate:
```yaml theme={null}
# cluster-workflow-template.yaml
apiVersion: argoproj.io/v1alpha1
kind: ClusterWorkflowTemplate
metadata:
name: global-utility-templates
spec:
templates:
- name: global-cowsay
inputs:
parameters:
- name: message
container:
image: rancher/cowsay
command: ["cowsay"]
args: ["{{inputs.parameters.message}}"]
```
Because ClusterWorkflowTemplate is cluster-scoped, metadata does not include a namespace.
Referencing a ClusterWorkflowTemplate from a namespaced Workflow requires setting the clusterScope flag to true.
Example: calling a single template from a ClusterWorkflowTemplate via templateRef (clusterScope: true)
```yaml theme={null}
apiVersion: argoproj.io/v1alpha1
kind: Workflow
metadata:
generateName: use-single-cluster-template-
spec:
entrypoint: my-custom-workflow
templates:
- name: my-custom-workflow
steps:
- - name: first-step
templateRef:
name: global-utility-templates # ClusterWorkflowTemplate name
template: global-cowsay # template name inside the ClusterWorkflowTemplate
clusterScope: true # required when referencing a cluster-scoped template
arguments:
parameters:
- name: message
value: "I called this from a ClusterWorkflowTemplate!"
```
Example: running the whole ClusterWorkflowTemplate via workflowTemplateRef (clusterScope: true)
```yaml theme={null}
apiVersion: argoproj.io/v1alpha1
kind: Workflow
metadata:
generateName: run-whole-cluster-template-
namespace: argo
spec:
arguments:
parameters:
- name: message
value: "Hello from a ClusterWorkflowTemplate!"
workflowTemplateRef:
name: global-utility-templates
clusterScope: true
```
When referencing cluster-scoped templates (ClusterWorkflowTemplate), always set clusterScope: true in templateRef or workflowTemplateRef. ClusterWorkflowTemplates are not namespaced, so this flag tells Argo the reference is to a cluster-level resource.
## Quick comparison
| Resource | Scope | Typical user | Use case |
| -----------------------------: | :--------------: | :-------------: | :--------------------------------------------- |
| WorkflowTemplate | Namespace-scoped | App/team owners | Reusable templates within a team namespace |
| ClusterWorkflowTemplate | Cluster-scoped | Platform teams | Centralized templates shared across namespaces |
| Workflow (templateRef) | Namespace-scoped | Developers | Import single templates into complex workflows |
| Workflow (workflowTemplateRef) | Namespace-scoped | Anyone | Execute a stored template as a full workflow |
## Links and References
* [Argo Workflows Documentation](https://argoproj.github.io/argo-workflows/)
* [Kubernetes API Concepts](https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/)
* [Argo Workflows Templates Reference](https://argoproj.github.io/argo-workflows/workflow-templates/)