Last modified November 12, 2026
'kubectl gs gitops add workload-cluster' command reference
This command adds a new workload cluster to the GitOps repository.
Prerequisites
Your GitOps repository should provide the following structural layers:
- Basic structure (see
init) - Management cluster (see
add management-cluster) - Organization (see
add organization)
Description
The structure created by this command is presented below. Note, the initial layers are flattened for brevity. Resources enclosed
in a square brackets [] are considered optional.
management-clusters/MC_NAME
└── organizations
└── ORG_NAME
└── workload-clusters
├── kustomization.yaml
├── WC_NAME.yaml
└── WC_NAME
└── [mapi]
├── apps
│ └── kustomization.yaml
└── cluster
├── [kustomization.yaml]
├── [cluster_userconfig.yaml]
└── [patch_cluster_userconfig.yaml]
The content of the cluster directory is optional because in its most basic form, the GitOps repository does not require you to
put the cluster definition in there. It can be added later by re-running the command with additional flags. Re-running works
in such case, because cluster directory is initially empty. Note however, in order to populate it, you must have a
working base and reference it by the --base flag when running the command. You may customize the referenced base with
the --cluster-user-config flag when needed.
With --base, use a base that deploys a release-<provider> chart, such as release-aws, with a Flux
OCIRepository and HelmRelease. The
CAPA cluster base in
gitops-template is one, and the add base command creates
one for other providers. The chart version of a release-<provider> chart is the Giant Swarm release version. The
--release flag sets the release variable of the Flux Kustomization, and the base uses it as the tag of the
OCIRepository. The release is then stored in Git, and you upgrade the cluster by changing that variable. Pass the
version without the v prefix, for example 36.2.0. The command checks that the release is published as a chart in
the gsoci.azurecr.io registry.
The chart sets global.release.version in its default values. Don’t set it in the values you pass with
--cluster-user-config. A copy in your values would stay at the old release when you upgrade the cluster.
The command refuses a base that deploys an App CR, also when the App CR comes from a base below an overlay. Releases
before v34 have no release-<provider> chart, so they can’t be added with a base. See the
App Platform deprecation.
Note: this needs kubectl-gs v6.0.0 or newer. Older versions generate an App CR for the cluster.
The command doesn’t create the workload cluster’s SOPS key Secret. The
add encryption command creates it when you add encryption to the
cluster.
Note: the latest recommendation mandates creation of the mapi directory. However, users who have not yet migrated to it,
but still want to use automation for their repositories, may skip the mapi layer by using the --skip-mapi flag. Migration is
nevertheless mandatory, and hence this flag is planned to be removed from kubectl-gs at some point.
Usage
Basic command syntax: kubectl gs gitops add workload-cluster <FLAGS>
Flags
--management-cluster– name of the management cluster the workload cluster belongs to (required)--name– name of the workload cluster (required)--organization– name of the organization the workload cluster belongs to (required)--repository-name– name of the GitOps repository (required)--base– path to the base directory; must be relative to the repository root--release– workload cluster release version without thevprefix, for example36.2.0; required when--baseis set--cluster-user-config– path to a values file for the cluster chart. Its values come after the base’s values, so they win--skip-mapi– skip mapi directory when adding the app
The following flags are supported by all gitops subcommands:
--dry-run– Print files and directories instead of creating them.--local-path– Path to the repository root folder (default “.”).
Examples
In the most basic form the GitOps repository may be populated with Workload Cluster-related structure, yet without the cluster-related CRs.
kubectl gs gitops add workload-cluster \
--local-path /tmp/gitops-demo \
--name demowc \
--management-cluster demomc \
--organization demoorg \
--repository-name gitops-demo \
--dry-run
Output:
## CREATE ##
/tmp/gitops-demo/management-clusters/demomc/organizations/demoorg/workload-clusters
/tmp/gitops-demo/management-clusters/demomc/organizations/demoorg/workload-clusters/demowc.yaml
apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata:
name: demomc-clusters-demowc
namespace: default
spec:
interval: 1m
path: "./management-clusters/demomc/organizations/demoorg/workload-clusters/demowc/mapi"
postBuild:
substitute:
cluster_name: demowc
organization: demoorg
prune: false
serviceAccountName: automation
sourceRef:
kind: GitRepository
name: gitops-demo
timeout: 2m
/tmp/gitops-demo/management-clusters/demomc/organizations/demoorg/workload-clusters/demowc
/tmp/gitops-demo/management-clusters/demomc/organizations/demoorg/workload-clusters/demowc/mapi
/tmp/gitops-demo/management-clusters/demomc/organizations/demoorg/workload-clusters/demowc/mapi/apps
/tmp/gitops-demo/management-clusters/demomc/organizations/demoorg/workload-clusters/demowc/mapi/cluster
/tmp/gitops-demo/management-clusters/demomc/organizations/demoorg/workload-clusters/demowc/mapi/apps/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
commonLabels:
giantswarm.io/cluster: ${cluster_name}
giantswarm.io/managed-by: flux
kind: Kustomization
namespace: org-${organization}
resources: []
## MODIFY ##
/tmp/gitops-demo/management-clusters/demomc/organizations/demoorg/workload-clusters/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
- demowc.yaml
## METADATA ##
/tmp/gitops-demo/.gitops-metadata.yaml
# This file is managed by `kubectl gs gitops`. Do not edit it by hand.
# It records which version of the repository structure each part of this
# repository was generated with, so that `kubectl gs gitops check` can tell
# you when the repository has fallen behind.
apiVersion: gitops.giantswarm.io/v1alpha1
generatedWith: kubectl-gs/6.0.3
kind: RepositoryMetadata
layers:
- generatedWith: kubectl-gs/6.0.3
kind: management-cluster
path: management-clusters/demomc
structureVersion: 2
- generatedWith: kubectl-gs/6.0.3
kind: organization
path: management-clusters/demomc/organizations/demoorg
structureVersion: 2
- generatedWith: kubectl-gs/6.0.3
kind: workload-cluster
path: management-clusters/demomc/organizations/demoorg/workload-clusters/demowc
structureVersion: 2
structureVersion: 2
When desired to manage cluster definition from GitOps repository, it can be added by the --base
and --release flags. This example uses the CAPA cluster base, so the HelmRelease installs release-aws 36.2.0.
kubectl gs gitops add workload-cluster \
--local-path /tmp/gitops-demo \
--name demowc \
--management-cluster demomc \
--organization demoorg \
--repository-name gitops-demo \
--base bases/clusters/capa/template \
--release 36.2.0 \
--dry-run
Output:
## CREATE ##
/tmp/gitops-demo/management-clusters/demomc/organizations/demoorg/workload-clusters
/tmp/gitops-demo/management-clusters/demomc/organizations/demoorg/workload-clusters/demowc.yaml
apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata:
name: demomc-clusters-demowc
namespace: default
spec:
interval: 1m
path: "./management-clusters/demomc/organizations/demoorg/workload-clusters/demowc/mapi"
postBuild:
substitute:
cluster_name: demowc
cluster_description: "demowc managed by GitOps"
release: 36.2.0
organization: demoorg
prune: false
serviceAccountName: automation
sourceRef:
kind: GitRepository
name: gitops-demo
timeout: 2m
/tmp/gitops-demo/management-clusters/demomc/organizations/demoorg/workload-clusters/demowc
/tmp/gitops-demo/management-clusters/demomc/organizations/demoorg/workload-clusters/demowc/mapi
/tmp/gitops-demo/management-clusters/demomc/organizations/demoorg/workload-clusters/demowc/mapi/apps
/tmp/gitops-demo/management-clusters/demomc/organizations/demoorg/workload-clusters/demowc/mapi/cluster
/tmp/gitops-demo/management-clusters/demomc/organizations/demoorg/workload-clusters/demowc/mapi/apps/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
commonLabels:
giantswarm.io/cluster: ${cluster_name}
giantswarm.io/managed-by: flux
kind: Kustomization
namespace: org-${organization}
resources: []
/tmp/gitops-demo/management-clusters/demomc/organizations/demoorg/workload-clusters/demowc/mapi/cluster/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
commonLabels:
giantswarm.io/managed-by: flux
kind: Kustomization
resources:
- ../../../../../../../../bases/clusters/capa/template
## MODIFY ##
/tmp/gitops-demo/management-clusters/demomc/organizations/demoorg/workload-clusters/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
- demowc.yaml
/tmp/gitops-demo/management-clusters/demomc/organizations/demoorg/workload-clusters/demowc.yaml
apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata:
name: demomc-clusters-demowc
namespace: default
spec:
interval: 1m
path: ./management-clusters/demomc/organizations/demoorg/workload-clusters/demowc/mapi
postBuild:
substitute:
cluster_description: demowc managed by GitOps
cluster_name: demowc
organization: demoorg
release: 36.2.0
prune: false
serviceAccountName: automation
sourceRef:
kind: GitRepository
name: gitops-demo
timeout: 2m
## METADATA ##
/tmp/gitops-demo/.gitops-metadata.yaml
# This file is managed by `kubectl gs gitops`. Do not edit it by hand.
# It records which version of the repository structure each part of this
# repository was generated with, so that `kubectl gs gitops check` can tell
# you when the repository has fallen behind.
apiVersion: gitops.giantswarm.io/v1alpha1
generatedWith: kubectl-gs/6.0.3
kind: RepositoryMetadata
layers:
- generatedWith: kubectl-gs/6.0.3
kind: management-cluster
path: management-clusters/demomc
structureVersion: 2
- generatedWith: kubectl-gs/6.0.3
kind: organization
path: management-clusters/demomc/organizations/demoorg
structureVersion: 2
- generatedWith: kubectl-gs/6.0.3
kind: workload-cluster
path: management-clusters/demomc/organizations/demoorg/workload-clusters/demowc
structureVersion: 2
structureVersion: 2
Cluster definition coming from a base may also be customized with a user configuration passed by the
--cluster-user-config flag. The command writes the values to a ConfigMap, and a patch appends that ConfigMap to the
valuesFrom of the base’s HelmRelease. Flux merges valuesFrom in order, so these values win over the base’s
values. Don’t set global.release.version in them, because the chart sets it.
Note: files referenced by this flag should carry a valid values YAML configuration conforming the values schema of the given cluster chart version.
Below is the example of values.yaml setting the service priority of the cluster.
global:
metadata:
servicePriority: medium
After saving this into /tmp/values.yaml, it can be referenced when adding a cluster.
kubectl gs gitops add workload-cluster \
--local-path /tmp/gitops-demo \
--name demowc \
--management-cluster demomc \
--organization demoorg \
--repository-name gitops-demo \
--base bases/clusters/capa/template \
--release 36.2.0 \
--cluster-user-config /tmp/values.yaml \
--dry-run
Output:
## CREATE ##
/tmp/gitops-demo/management-clusters/demomc/organizations/demoorg/workload-clusters
/tmp/gitops-demo/management-clusters/demomc/organizations/demoorg/workload-clusters/demowc.yaml
apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata:
name: demomc-clusters-demowc
namespace: default
spec:
interval: 1m
path: "./management-clusters/demomc/organizations/demoorg/workload-clusters/demowc/mapi"
postBuild:
substitute:
cluster_name: demowc
cluster_description: "demowc managed by GitOps"
release: 36.2.0
organization: demoorg
prune: false
serviceAccountName: automation
sourceRef:
kind: GitRepository
name: gitops-demo
timeout: 2m
/tmp/gitops-demo/management-clusters/demomc/organizations/demoorg/workload-clusters/demowc
/tmp/gitops-demo/management-clusters/demomc/organizations/demoorg/workload-clusters/demowc/mapi
/tmp/gitops-demo/management-clusters/demomc/organizations/demoorg/workload-clusters/demowc/mapi/apps
/tmp/gitops-demo/management-clusters/demomc/organizations/demoorg/workload-clusters/demowc/mapi/cluster
/tmp/gitops-demo/management-clusters/demomc/organizations/demoorg/workload-clusters/demowc/mapi/apps/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
commonLabels:
giantswarm.io/cluster: ${cluster_name}
giantswarm.io/managed-by: flux
kind: Kustomization
namespace: org-${organization}
resources: []
/tmp/gitops-demo/management-clusters/demomc/organizations/demoorg/workload-clusters/demowc/mapi/cluster/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
commonLabels:
giantswarm.io/managed-by: flux
kind: Kustomization
patches:
- path: patch_cluster_userconfig.yaml
target:
group: helm.toolkit.fluxcd.io
kind: HelmRelease
# A regular expression matching the name the base gives the HelmRelease
# before Flux substitutes the variables.
name: \$\{cluster_name\}
resources:
- ../../../../../../../../bases/clusters/capa/template
- cluster_userconfig.yaml
/tmp/gitops-demo/management-clusters/demomc/organizations/demoorg/workload-clusters/demowc/mapi/cluster/cluster_userconfig.yaml
apiVersion: v1
data:
values: |
global:
metadata:
servicePriority: medium
kind: ConfigMap
metadata:
name: demowc-cluster-userconfig
namespace: org-demoorg
/tmp/gitops-demo/management-clusters/demomc/organizations/demoorg/workload-clusters/demowc/mapi/cluster/patch_cluster_userconfig.yaml
- op: add
path: /spec/valuesFrom/-
value:
kind: ConfigMap
name: demowc-cluster-userconfig
valuesKey: values
## MODIFY ##
/tmp/gitops-demo/management-clusters/demomc/organizations/demoorg/workload-clusters/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
- demowc.yaml
/tmp/gitops-demo/management-clusters/demomc/organizations/demoorg/workload-clusters/demowc.yaml
apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata:
name: demomc-clusters-demowc
namespace: default
spec:
interval: 1m
path: ./management-clusters/demomc/organizations/demoorg/workload-clusters/demowc/mapi
postBuild:
substitute:
cluster_description: demowc managed by GitOps
cluster_name: demowc
organization: demoorg
release: 36.2.0
prune: false
serviceAccountName: automation
sourceRef:
kind: GitRepository
name: gitops-demo
timeout: 2m
## METADATA ##
/tmp/gitops-demo/.gitops-metadata.yaml
# This file is managed by `kubectl gs gitops`. Do not edit it by hand.
# It records which version of the repository structure each part of this
# repository was generated with, so that `kubectl gs gitops check` can tell
# you when the repository has fallen behind.
apiVersion: gitops.giantswarm.io/v1alpha1
generatedWith: kubectl-gs/6.0.3
kind: RepositoryMetadata
layers:
- generatedWith: kubectl-gs/6.0.3
kind: management-cluster
path: management-clusters/demomc
structureVersion: 2
- generatedWith: kubectl-gs/6.0.3
kind: organization
path: management-clusters/demomc/organizations/demoorg
structureVersion: 2
- generatedWith: kubectl-gs/6.0.3
kind: workload-cluster
path: management-clusters/demomc/organizations/demoorg/workload-clusters/demowc
structureVersion: 2
structureVersion: 2
Remove the --dry-run flag and re-run the command it to apply the changes.
Need help, got feedback?
We listen to your Slack support channel. You can also reach us at support@giantswarm.io. And of course, we welcome your pull requests!