Dagweave Connector
The connector is what lets Dagweave run workflows on your cluster. You install it
once per cluster with Helm. After that, people run workflows from Dagweave and
never need kubectl.
It only ever connects out to Dagweave. You don’t open a port or add an ingress.
Connecting a cluster needs a Production or Business plan. On any plan you can click Get YAML in the editor and apply the workflow yourself.
Before you start
Section titled “Before you start”- Argo Workflows is already installed. The connector uses it; it doesn’t install it.
- Kubernetes 1.25 or later.
- Helm 3.14 or later.
- You can install CRDs and ClusterRoles.
Install with Helm
Section titled “Install with Helm”In Dagweave, click the gear icon, choose Clusters and add a cluster. Dagweave shows a Helm command with a one-time token in it. Copy it before you close the dialog, because the token isn’t shown again. It expires 24 hours after you add the cluster. If you lose it, remove the cluster and add it again.


Run the command. It looks like this:
helm install connector oci://ghcr.io/dagweave/charts/connector \ --namespace connector-system --create-namespace \ --set connectorConfig.dagweaveEndpoint=https://api.dagweave.com \ --set-string enrollment.token=<one-time-enrollment-token>Within a minute the cluster shows online under Clusters. Workflows run in
the argo namespace. To use other namespaces, add:
--set 'argoConnection.namespaces={team-a,team-b}'The examples on this page call the Helm release connector and install it in
connector-system.
Install with Flux or Argo CD
Section titled “Install with Flux or Argo CD”Two things differ from a plain Helm install. You pin the chart version in Git, and the token stays out of Git.
Keep the token out of Git
Section titled “Keep the token out of Git”Create the token Secret with whatever you already use, such as SOPS, External Secrets or Sealed Secrets:
apiVersion: v1kind: Secretmetadata: name: connector-enrollment namespace: connector-systemstringData: enrollment-token: <one-time-enrollment-token>The token is the value after enrollment.token= in the command Dagweave shows.
The connector only reads this Secret, so your tool can own it outright.
Once connected, the connector keeps its own key in a Secret called
connector-identity. It creates that one itself. Leave it out of Git.
apiVersion: source.toolkit.fluxcd.io/v1kind: OCIRepositorymetadata: name: dagweave-connector namespace: flux-systemspec: interval: 1h url: oci://ghcr.io/dagweave/charts/connector ref: tag: 0.10.2 layerSelector: mediaType: application/vnd.cncf.helm.chart.content.v1.tar+gzip operation: copy---apiVersion: helm.toolkit.fluxcd.io/v2kind: HelmReleasemetadata: name: connector namespace: flux-systemspec: interval: 1h releaseName: connector targetNamespace: connector-system chartRef: kind: OCIRepository name: dagweave-connector install: crds: CreateReplace upgrade: crds: CreateReplace values: connectorConfig: dagweaveEndpoint: https://api.dagweave.com enrollment: create: false secretName: connector-enrollment argoConnection: namespaces: [argo] selfUpdate: enabled: falseThe token Secret has to exist before the first install, so keep a Namespace
for connector-system in Git beside it.
Argo CD
Section titled “Argo CD”apiVersion: v1kind: Secretmetadata: name: dagweave-charts namespace: argocd labels: argocd.argoproj.io/secret-type: repositorystringData: type: helm name: dagweave url: ghcr.io/dagweave/charts enableOCI: "true"---apiVersion: argoproj.io/v1alpha1kind: Applicationmetadata: name: dagweave-connector namespace: argocdspec: project: default source: repoURL: ghcr.io/dagweave/charts chart: connector targetRevision: 0.10.2 helm: releaseName: connector valuesObject: connectorConfig: dagweaveEndpoint: https://api.dagweave.com enrollment: create: false secretName: connector-enrollment argoConnection: namespaces: [argo] selfUpdate: enabled: false destination: server: https://kubernetes.default.svc namespace: connector-system syncPolicy: automated: prune: true selfHeal: true syncOptions: - CreateNamespace=trueBoth examples turn self-update off, so Git stays in charge of the version. To upgrade, change the chart version in Git.
Connect an Argo Workflows instance
Section titled “Connect an Argo Workflows instance”argoConnection tells the connector which namespaces it may run workflows in:
argoConnection: argoInstanceID: local namespaces: [argo]argoInstanceID names the Argo Workflows instance. You only need it if the
cluster runs more than one. For each extra instance, apply an ArgoConnection of
your own with a different argoInstanceID, and don’t let two list the same
namespace.
Change these through Helm values rather than kubectl edit, or the next upgrade
puts them back.
Features per namespace
Section titled “Features per namespace”You can let Dagweave run workflows in one namespace and only watch runs in
another. Here Dagweave can run workflows in argo but only show runs from
reporting:
targetNamespaces: - argo - name: reporting features: {status: true, submit: false, logs: false, artifacts: false}Use this for any namespace whose Secrets you don’t want Dagweave users to reach. Being able to run a workflow in a namespace means being able to mount any Secret in it.
Each namespace listed here becomes a Role in that namespace, so the connector
gets no cluster-wide permissions for it.
Step logs in Dagweave
Section titled “Step logs in Dagweave”By default the connector doesn’t send step logs anywhere Dagweave can read them, and the run view says so. To see them in Dagweave, add:
features: logs: truelogs: sink: type: loki loki: dagweaveHosted: truelogForwarder: enabled: trueThere’s no address or credential to add. The connector signs the logs itself.
To keep logs in your own S3 bucket, Loki or HTTP endpoint instead, set
logs.sink to that. With S3, Dagweave shows where each step’s logs are. With the
others, read them where you sent them.
What the connector can reach
Section titled “What the connector can reach”- Each feature in
featuresinstalls only the permissions it needs. Turn one off and its permissions aren’t installed. - Artifacts stay in your own bucket. Downloads use a link that expires after an hour.
- Only hosted logs send log lines to Dagweave.
artifactscan read a Secret it’s given the name of, but can’t list Secrets. NameartifactRepoRefanddatabaseOffloadRefinargoConnection.extraSpecand it can read only those two.
Run identity
Section titled “Run identity”By default a workflow runs as whatever ServiceAccount its namespace gives it. Run identity lets your team give a run specific Kubernetes permissions, picked from a list you control. It’s off until you turn it on.
Write the list
Section titled “Write the list”In your values, list what people can pick from. Each entry has an id, a label, any parameters, and the Kubernetes rules it grants:
features: runIdentity: truerunIdentity: namespaces: [team-a] templates: - id: read-named-configmaps label: Read one ConfigMap params: - name: configMapName label: ConfigMap name required: true rules: - apiGroups: [""] resources: ["configmaps"] resourceNames: ["${configMapName}"] verbs: ["get"]runIdentity.namespaces is where these permissions can be used. Match it to
argoConnection.namespaces.
Dagweave never sends permissions to your cluster. It sends the id of an entry on your list and the parameter values, and the connector refuses any id that isn’t on it.
What it costs
Section titled “What it costs”To hand out a permission, the connector has to hold it. Everything on your list
is granted to the connector in runIdentity.namespaces, whether anyone picks it
or not. A parameter in resourceNames widens it: the example above lets a user
read one ConfigMap, but the connector can read any ConfigMap in team-a.
Render it and read it before you install:
helm template connector oci://ghcr.io/dagweave/charts/connector \ -f your-values.yaml --set enrollment.create=false \ --set connectorConfig.create=false \ -s templates/runidentity-rbac.yamlUse an identity
Section titled “Use an identity”In Dagweave, an identity is one entry from your list, its parameter values, where it can be used, and who can use it: a person, a group or the whole team. Someone who manages the team’s members approves it before it can be used. Every change is in the audit log.
When a run matches an approved identity, the connector creates a ServiceAccount,
Role and RoleBinding named dagweave-run-<run id> before submitting it. They’re
deleted with the Workflow. To find anything the connector has created:
kubectl get sa,role,rolebinding -A -l dagweave.io/owner=dagweaveKeep it up to date
Section titled “Keep it up to date”The connector updates its own image when Dagweave has a newer version. A
helm upgrade sets the image back to the chart’s version, so upgrade the chart
too.
If you manage versions yourself, set selfUpdate.enabled=false.
Check on it
Section titled “Check on it”Each cluster’s row under Clusters shows whether it’s online, and the versions of the connector, Argo Workflows and Kubernetes. It goes offline after five minutes without hearing from the connector.
Owners and admins can click Logs on the row to read the connector’s own logs. If a run never reaches the cluster, the reason is usually there.
If it won’t connect
Section titled “If it won’t connect”kubectl get connectorconfig -o wide| Reason | What to do |
|---|---|
TokenInvalid, TokenExpired, TokenAlreadyUsed |
Remove the cluster in Dagweave and add it again, then put the new token in the token Secret. The connector picks it up within a minute. |
SecretMissing |
The token Secret doesn’t exist. Create it, with the token under enrollment-token. |
EndpointUnreachable |
The cluster can’t reach api.dagweave.com. Allow the egress. The connector keeps retrying. |
KeyAlreadyBound |
Delete the connector-identity Secret and the connector starts fresh. |
If the pods are stuck in ImagePullBackOff, the cluster couldn’t pull from
ghcr.io. Create a pull secret and pass it with
--set imagePullSecrets[0].name=<secret>.
If you delete the connector-system namespace, the connector loses its key and
has to connect again with a new token. Remove the cluster in Dagweave, add it
again, and put the new token in the token Secret.