Skip to content

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.

  • 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.

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.

The Clusters screen after Add cluster, showing the helm install command with its one-time token and a Copy command button.The Clusters screen after Add cluster, showing the helm install command with its one-time token and a Copy command button.

Run the command. It looks like this:

Terminal window
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:

Terminal window
--set 'argoConnection.namespaces={team-a,team-b}'

The examples on this page call the Helm release connector and install it in connector-system.

Two things differ from a plain Helm install. You pin the chart version in Git, and the token stays out of Git.

Create the token Secret with whatever you already use, such as SOPS, External Secrets or Sealed Secrets:

apiVersion: v1
kind: Secret
metadata:
name: connector-enrollment
namespace: connector-system
stringData:
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/v1
kind: OCIRepository
metadata:
name: dagweave-connector
namespace: flux-system
spec:
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/v2
kind: HelmRelease
metadata:
name: connector
namespace: flux-system
spec:
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: false

The token Secret has to exist before the first install, so keep a Namespace for connector-system in Git beside it.

apiVersion: v1
kind: Secret
metadata:
name: dagweave-charts
namespace: argocd
labels:
argocd.argoproj.io/secret-type: repository
stringData:
type: helm
name: dagweave
url: ghcr.io/dagweave/charts
enableOCI: "true"
---
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
name: dagweave-connector
namespace: argocd
spec:
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=true

Both examples turn self-update off, so Git stays in charge of the version. To upgrade, change the chart version in Git.

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.

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.

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: true
logs:
sink:
type: loki
loki:
dagweaveHosted: true
logForwarder:
enabled: true

There’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.

  • Each feature in features installs 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.
  • artifacts can read a Secret it’s given the name of, but can’t list Secrets. Name artifactRepoRef and databaseOffloadRef in argoConnection.extraSpec and it can read only those two.

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.

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: true
runIdentity:
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.

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:

Terminal window
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.yaml

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:

Terminal window
kubectl get sa,role,rolebinding -A -l dagweave.io/owner=dagweave

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.

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.

Terminal window
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.