Setup with AWS CDK

You can automate the provisioning of your Union.ai data plane on AWS using AWS Cloud Development Kit (CDK) and EKS Blueprints.

The @unionai/union-eks-blueprints-addon package provides CDK constructs that deploy the Union.ai data plane onto an EKS cluster, including all required IAM roles, Helm charts, and Kubernetes resources.

Prerequisites

• Node.js >= 18
• AWS CDK v2 installed and bootstrapped in your target account/region
• npm or another Node.js package manager
• A Union.ai organization with the following information (provided by the Union.ai team):
  • Control plane host (e.g. your-org.hosted.unionai.cloud)
  • Organization name
  • Cluster name registered with Union.ai
  • Client ID and Client Secret for authentication

Installation

Install the addon package in your CDK project:

npm install @unionai/union-eks-blueprints-addon

Store your credentials in AWS Secrets Manager

The addon retrieves Union.ai credentials from AWS Secrets Manager. Create a secret containing both the client ID and client secret as a JSON object:

aws secretsmanager create-secret \
  --name "union/credentials" \
  --secret-string '{"clientId": "<YOUR_CLIENT_ID>", "clientSecret": "<YOUR_CLIENT_SECRET>"}'

Create your CDK stack

The following example creates an EKS cluster with EKS Auto Mode enabled and deploys the Union.ai data plane onto it:

import * as cdk from 'aws-cdk-lib';
import * as blueprints from "@aws-quickstart/eks-blueprints"
import * as union from "@unionai/union-eks-blueprints-addon"

const app = new cdk.App();

const account = process.env.CDK_DEFAULT_ACCOUNT;
const region = process.env.CDK_DEFAULT_REGION;
let props = { env: { account, region } };

const unionBlueprint = blueprints.AutomodeBuilder.builder({})
  .resourceProvider(
    'union-bucket',
    new blueprints.CreateS3BucketProvider({
      id: 'my-union-bucket-123',
      s3BucketProps: { bucketName: 'union-bucket' }
    })
  )
  .addOns(
    new blueprints.addons.MetricsServerAddOn(),
    new union.UnionDataplaneCRDsAddOn(),
    new union.UnionDataplaneAddOn({
      s3BucketProviderName: 'union-bucket',
      clusterName: "<YOUR_UNION_CLUSTER_NAME>",
      unionSecretName: "<YOUR_UNION_SECRET_NAME>",
      host: "<YOUR_UNION_CONTROL_PLANE_HOST>",
      orgName: "<YOUR_ORG_NAME>"
    })
  )
  .build(app, "union-blueprint", props);

Replace the placeholder values:

Deploy

Once your CDK stack is defined, deploy it:

cdk deploy union-blueprint

What gets provisioned

The addon deploys the following resources:

• UnionDataplaneCRDsAddOn: Installs the Union.ai Custom Resource Definitions (CRDs) required by the data plane operator.
• UnionDataplaneAddOn: Deploys the Union.ai data plane Helm chart, which includes:
  • An IAM policy granting read/write access to the configured S3 bucket.
  • An IAM role with OIDC federation for Kubernetes service accounts.
  • The data plane operator and supporting services.

Using an existing S3 bucket

If you already have an S3 bucket, use ImportS3BucketProvider instead of CreateS3BucketProvider:

.resourceProvider(
  'union-bucket',
  new blueprints.ImportS3BucketProvider('my-existing-bucket-name')
)

Additional configuration

The UnionDataplaneAddOn accepts additional Helm values through the values property, which are merged with the defaults. Refer to the Union.ai Helm chart documentation for available options.