# Deploy the dataplane If you have not yet set up the required Crusoe resources (CMK cluster, Cloud Storage bucket, access keys, access policy), see [Prepare infrastructure](https://www.union.ai/docs/v2/union/deployment/selfmanaged/selfmanaged-crusoe/selfmanaged-crusoe/prepare-infra) first. ## Assumptions * You have a Union.ai organization, and you know the control plane URL for your organization. * You have a cluster name provided by or coordinated with Union. * You have a CMK cluster running one of the most recent three minor Kubernetes versions. [Learn more](https://kubernetes.io/releases/version-skew-policy/) * You have a Crusoe Cloud Storage bucket, access keys, and access policy as described in [Prepare infrastructure](https://www.union.ai/docs/v2/union/deployment/selfmanaged/selfmanaged-crusoe/selfmanaged-crusoe/prepare-infra). ## Prerequisites * Install [Helm 3](https://helm.sh/docs/intro/install/). * Install [uctl](https://www.union.ai/docs/v2/union/deployment/api-reference/uctl-cli/_index). * Install the [`flyte` CLI](https://www.union.ai/docs/v2/union/deployment/api-reference/flyte-cli) (used later to run a sample workflow). ## Deploy the Union.ai operator 1. Set your `KUBECONFIG` to the CMK cluster where you want to deploy the data plane: ```bash export KUBECONFIG= ``` 2. Configure the Union CLI and provision data plane resources: ```bash uctl config init --host=.union.ai uctl selfserve provision-dataplane-resources --clusterName --provider metal ``` * The command will output the ID, name, and a secret that will be used by the Union services to communicate with your control plane. It will also generate a YAML values file specific to the `metal` provider. * Save the secret that is displayed. Union does not store the credentials; rerunning the same command can be used to retrieve the secret later. We use `--provider metal` for Crusoe because the Union operator treats Crusoe as a generic S3-compatible / Kubernetes environment rather than a first-class cloud provider integration (like AWS/GCP/Azure). 3. Update the generated values file with your Crusoe-specific storage configuration. Replace the placeholders with your actual credentials and settings. ```yaml host: .union.ai clusterName: orgName: provider: metal storage: provider: custom bucketName: fastRegistrationBucketName: custom: type: stow container: stow: kind: s3 config: region: auth_type: accesskey access_key_id: secret_key: endpoint: https://object.crusoecloud.com # [VERIFY endpoint] disable_ssl: false disable_force_path_style: false # [VERIFY: set true if Crusoe requires virtual-hosted style] executor: extraEnvVars: - name: FLYTE_AWS_ENDPOINT value: "https://object.crusoecloud.com" # [VERIFY] - name: AWS_ACCESS_KEY_ID value: - name: AWS_SECRET_ACCESS_KEY value: - name: AWS_DEFAULT_REGION value: config: k8s: plugins: k8s: default-env-vars: - FLYTE_AWS_ENDPOINT: https://object.crusoecloud.com # [VERIFY] - AWS_ACCESS_KEY_ID: - AWS_SECRET_ACCESS_KEY: - AWS_DEFAULT_REGION: operator: enableTunnelService: true secrets: admin: create: true clientId: clientSecret: fluentbit: enabled: true env: - name: AWS_ACCESS_KEY_ID value: - name: AWS_SECRET_ACCESS_KEY value: ``` > [!NOTE] > The `uctl selfserve provision-dataplane-resources` command in step 2 generates the `` and `` values. Use the values from that command's output. 4. Add the Union.ai Helm repo: ```bash helm repo add unionai https://unionai.github.io/helm-charts/ helm repo update ``` 5. Install the Custom Resource Definitions (CRDs): ```bash helm upgrade --install unionai-dataplane-crds unionai/dataplane-crds ``` 6. Install the data plane. Replace `` with the path to the Helm values file you customized in step 3. ```bash helm upgrade --install unionai-dataplane unionai/dataplane \ --namespace union --create-namespace \ --values \ --timeout 10m ``` 7. Verify the pods are running: ```bash kubectl get pods -n union ``` When the deployment succeeds, all pods show a `Running` status, including `union-operator-proxy`, `union-operator-buildkit`, `flytepropeller`, and `executor`. 8. Verify the cluster is registered with the control plane: ```bash uctl get cluster ``` The output is similar to the following: ```text NAME ORG STATE HEALTH union-crusoe my-org STATE_ENABLED HEALTHY ``` 9. Create an API key for your organization. This is required for v2 workflow executions on the data plane. If you have already created one, rerun the same command to propagate the key to the new cluster: ```bash uctl create apikey --keyName EAGER_API_KEY --org ``` > [!NOTE] > If you receive a `PermissionDenied` error, contact [Union.ai support](https://www.union.ai/) to have the permission enabled for your organization. ## Test a workflow To run a sample workflow, complete the following steps: 1. Create a Flyte CLI configuration file at the path `.flyte/config.yaml` in your project directory. Replace `` and `` with your organization and project identifiers. ```yaml admin: endpoint: dns:///.union.ai image: builder: remote task: domain: development org: project: ``` 2. Run a sample workflow: ```bash flyte run --image ghcr.io/flyteorg/flyte:py3.13-v2.0.2 \ hello_world.py main --n 5 ``` > [!NOTE] > If the remote image builder isn't enabled for your organization, use the `--image` flag with a pre-built container image as in the preceding `flyte run` example. 3. Check the run status. Replace `` with the workflow run identifier. ```bash flyte get run ``` Look for `ACTION_PHASE_SUCCEEDED` in the output to confirm the workflow completed successfully. > [!NOTE] Crusoe-specific tip > To land tasks on Crusoe GPU nodes, add a task-level resource request and a node selector matching Crusoe's GPU node pool labels. > ## Troubleshooting | Symptom | Cause | Fix | | -------------------------------------------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------- | | `PathStyleRequestNotAllowed 400` | Control plane generates path-style URLs but Crusoe requires virtual-hosted. | Set `storage.custom.stow.config.disable_force_path_style: true`. | | `403 Forbidden` on S3 operations | No access policy attached to the storage key. | Create/attach an object storage access policy in the Crusoe Cloud Console. | | Task pods reach `s3.us-east-1.amazonaws.com` | Task pods missing the Crusoe endpoint. | Add `FLYTE_AWS_ENDPOINT` to `config.k8s.plugins.k8s.default-env-vars`. | | "All enabled clusters are unhealthy" | Control plane can't reach the data plane. | Verify the tunnel service: `kubectl get pods -n union \| grep proxy`. | | "Remote image builder is not enabled" | Remote builder not enabled on the control plane. | Contact Union.ai or use `--image` with a pre-built image. | | `invalid keys: collectbillableresourceusage` | Chart/operator version mismatch. | Use matching chart and operator image versions. | | Helm "another operation in progress" | Interrupted Helm upgrade. | Run `helm rollback unionai-dataplane -n union`. | | "Provided Tunnel token is not valid" | Control plane not configured for this cluster. | Complete cluster registration first. | ## Additional resources For more information, see the following resources: - [Crusoe Managed Kubernetes overview](https://docs.crusoecloud.com/kubernetes/overview/) - [Crusoe Cloud Storage overview](https://docs.crusoecloud.com/storage/object-storage/overview) --- **Source**: https://github.com/unionai/unionai-docs/blob/main/content/deployment/selfmanaged/selfmanaged-crusoe/deploy-dataplane.md **HTML**: https://www.union.ai/docs/v2/union/deployment/selfmanaged/selfmanaged-crusoe/deploy-dataplane/