Deployment Guide: Ververica Cloud: Bring Your Own Cloud

Ververica recommends reviewing About BYOC before deploying Ververica Cloud: Bring Your Own Cloud. It covers several important factors for you to consider, including:

• Is this the right option for your needs?
• What are the core components of the BYOC framework
• What is the security model and how can it help with a Zero Trust design?
• What are the operational responsibilities for BYOC?

How to Deploy BYOC

This guide walks you through the steps for deploying Ververica Cloud: Bring Your Own Cloud.

1. Review agent and workspace requirements.
2. Prepare your environment.
3. Install the Ververica agent.
4. Create your first workspace.

Ververica Agent and Workspace Requirements

This section provides instructions for deploying and managing the Ververica Agent on your AWS EKS cluster. It outlines the prerequisites and environment setup — such as configuring S3 buckets, ensures proper OpenID Connect (OIDC) integration, and creates necessary IAM roles and policies. You’ll then learn how to install the Ververica Agent, verify its successful registration with the Ververica Control Plane, and create a new BYOC workspace.

important

Agent and Instance Metadata Service (IMDS)
If you are deploying on Amazon EKS, ensure that IMDSv1 is enabled on your EC2 worker nodes. Currently, the Ververica Agent requires IMDSv1 access; if IMDSv2 is set to Required (disabling IMDSv1 entirely), the Agent will fail to initialize and produce 401 errors when running in EKS.

You can correct this by modifying each instance’s metadata options to set IMDSv2 to Optional:

1. Open Actions → Instance Settings → Modify instance metadata options in the Amazon EC2 console.
2. Under IMDSv2, choose Optional.
3. Save the changes.

If your EKS cluster creates additional worker nodes automatically, be sure to update the nodegroup launch configuration or template to enable IMDSv1 for new nodes.

It is split into two parts:

1. Supported Infrastructure and Compatibility
2. Minimum Capacity (Sizing) Requirements

These requirements apply to both the Ververica Agent and the workspaces it manages.

Supported Infrastructure and Compatibility

Requirement	Specification
Kubernetes Distribution	EKS
Kubernetes Version	≥ 1.28
EKS Deployment Type	EC2
EC2 Operating System	Linux
EC2 Instance Families	m5, m6, m5.metal, etc.
Supported Storage Class	gp2, gp3

Minimum Capacity (Sizing) Requirements

Requirement	Specification
Persistent Volume Claims (PVC) Per Workspace	2 PVCs per workspace
PVC Capacity	5 GB per volume
Network Security Policy	Allow outbound traffic to app.ververica.cloud
Pod CPU Requests (Per Workspace)	3 vCPU per workspace
Pod Memory Requests (Per Workspace)	18 GB per workspace
Agent Components CPU/Memory (Combined)	2 vCPU, 4 GiB memory (limits)

---

Prepare Your Environment

Create an S3 Bucket

1. Create a bucket:
   Use the AWS CLI or the AWS Management Console to create an S3 bucket that stores runtime artifacts and Flink checkpoints. You can also use an existing bucket if you prefer.

   Note: S3 bucket names must be globally unique. A common practice is to include your AWS account ID in the bucket name. For example:

   aws s3 create-bucket --bucket vv-agent-bucket-1234567890 --region eu-central-1

2. Record the bucket ARN:
   After creating the bucket, note its ARN for later use.

   

3. Configure CORS for the bucket:

   Configuring CORS ensures that only allowed origins can access the bucket, enforcing least privilege principles. The following configuration permits access from a Ververica website endpoint and required methods:

   1. In the AWS Management Console, open your S3 bucket.
   2. Go to Permissions.
   3. Scroll down to Cross-origin resource sharing (CORS) and click Edit.
   4. Add the following JSON and click Save changes:

        [
            {
                "AllowedHeaders": ["*"],
                "AllowedMethods": ["GET", "POST", "PUT", "DELETE", "HEAD"],
                "AllowedOrigins": ["https://app.ververica.cloud"],
                "ExposeHeaders": ["ETag"],
                "MaxAgeSeconds": 3000
            }
        ]
      

Kubernetes OIDC

The Agent uses IAM Roles for Service Accounts (IRSA) to authorize API calls to AWS. Your Amazon EKS cluster provides an OpenID Connect (OIDC) provider URL that you can use to configure pod permissions with IAM Roles.

1. Obtain the EKS Cluster’s OIDC Provider URL:
   Run the following AWS CLI command, replacing $cluster_name with your cluster’s name:

   aws eks describe-cluster --name $cluster_name --query "cluster.identity.oidc.issuer" --output text
   

   You can also find it by going to your AWS Console on EKS page.

   

2. Configure Provider:

   1. Navigate to Identity Providers and choose Add provider.
   2. Set Provider type to OpenID Connect.
   3. For Provider URL, paste the OIDC Provider URL you obtained in the previous step.
   4. For Audience, add sts.amazonaws.com.
   5. Optionally add tags, and then click Add provider.

IAM Roles and Policies

You need to create two IAM roles and their corresponding policies for the Ververica Agent (vv-agent):

1. VVCTenantRole: Manages the S3 bucket.
2. VVCAdminRole: Serves as the IRSA role for the Agent pod.

note

For zero-trust practices, restrict the policy to a specific S3 bucket (e.g., vv-agent-bucket-0123456789). If using a single agent for multiple workspaces, you may allow a wildcard pattern like vv-agent-bucket-*.

Create the Tenant Policy (VVCTenantPolicy)

1. In the IAM console, go to Policies and choose Create policy.
2. On the Create policy page, switch to the JSON editor.
3. Paste the following JSON, making sure to replace the S3 bucket ARN with your own:

   {
      "Version": "2012-10-17",
      "Statement": [
          {
              "Effect": "Allow",
              "Action": [
                  "s3:PutObject",
                  "s3:GetObject",
                  "s3:DeleteObject"
              ],
              "Resource": "arn:aws:s3:::vv-agent-bucket-*/*"
          },
          {
              "Effect": "Allow",
              "Action": [
                  "s3:ListBucket",
                  "s3:GetBucketLocation"
              ],
              "Resource": "arn:aws:s3:::vv-agent-bucket-*"
          }
      ]
   }
   
   
4. Click Next, review the policy, and give it the name VVCTenantPolicy.
5. Click Create policy.

Create the Tenant Role (VVCTenantRole)

1. In the IAM console, go to Roles and choose Create role.
2. On Select trusted entity, choose AWS account as the trusted entity type.
3. Select This account, then click Next.
4. On Add permissions, search for VVCTenantPolicy and select it.
5. Click Next and then review the role settings.
6. Name the role VVCTenantRole.
7. Click Create role.

Create the Admin Policy (VVCAdminPolicy)

Repeat the steps for creating a policy (as done for VVCTenantPolicy), but use the following JSON. Replace <REPLACE_WITH_ACCOUNT_ID> with your AWS account ID:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "sts:AssumeRole"
            ],
            "Resource": "arn:aws:iam::<REPLACE_WITH_ACCOUNT_ID>:role/VVCTenantRole"
        }
    ]
}

Name the policy VVCAdminPolicy.

Create the Admin Role (VVCAdminRole)

1. In the IAM console, go to Roles and choose Create role.
2. Select Web identity as the trusted entity type.
3. For Identity provider, select the EKS cluster OIDC provider.
4. For Audience, select sts.amazonaws.com.
5. Click Next.
6. On Add permissions, search for VVCAdminPolicy and select it.
7. Click Next, then name the role VVCAdminRole.
8. Confirm that the trust policy and permissions are correct.
9. Click Create role.

Install the Ververica Agent

This section will help you install and configure the Ververica Agent in your Kubernetes environment.

Connect Your Ververica Account with AWS Marketplace

1. Click on the Profile icon on any page in the Dashboard to open the profile options dropdown.
2. Go to Payment.
3. Connect to AWS.

Once you click on Connect to AWS, click again on Subscribe. You will be taken to the Ververica Cloud: Bring Your Own Cloud (PAYG) product page on AWS Marketplace, where you can subscribe to the product.

Once subscribed, AWS Marketplace will redirect you to this page to link your Ververica account with AWS.

Register the Agent in the Ververica Portal

info

To register the agent, you must first link your Ververica account with AWS.

1. Open the registration page and follow the prompts to register the agent.

   

2. After registering, download the Helm values.yaml file from the portal.

   

Update the Helm Values

Note: Pyxis is an internal component of the Ververica Agent. When installing or upgrading Pyxis, you’re deploying the same underlying Ververica Agent functionality. The name “Pyxis” may appear in Helm commands, configuration files, or logs, but it’s simply part of the standard agent installation.

In the downloaded values.yaml file, most fields will be pre-filled, except for the pyxisRoleArn field.

Manually add the pyxisRoleArn entry to the global section of values.yaml. For example:

global:
    ...
    pyxisRoleArn: "arn:aws:iam::784507062413:role/VVCAdminRole" # Note: Add this line to the downloaded configuration file.
    ...

Install or Upgrade the Pyxis Deployment

Run the following Helm command to install or upgrade the Pyxis deployment:

helm -n kube-system upgrade --install pyxis oci://registry.ververica.cloud/agent-charts/vv-agent --version 1.8.2-1 -f ./values.yaml

Alternatively, instead of editing the file, you can pass pyxisRoleArn as a command argument:

helm -n kube-system install pyxis oci://registry.ververica.cloud/agent-charts/vv-agent 
--version 1.8.2-1 --set global.pyxisRoleArn="arn:aws:iam::123521782123:role/VVCAdminRole-2" 
--values ./values.yaml

Verify Agent Registration

After the Agent contacts the Control Plane, its status changes to online. You can verify this by checking the Agents page in the Ververica Portal.

When the agent is online, it indicates that it has successfully registered and is ready for use.

Create a Workspace

warning

Before you create a new BYOC workspace, you must first subscribe a Ververica BYOC product on AWS Marketplace to connect your Ververica account. If you have not completed this step, the platform will display warning messages and guide you through the process.

For now, only AWS is supported as a provider for the workspace.

When creating a new BYOC workspace, you must provide the following information:

1. Provider:
   Specify the provider for the workspace.
   This corresponds to the environment or infrastructure provider that the workspace will use.

2. Workspace Name:
   Enter a unique name that identifies your workspace.

3. Cluster Agent:
   Choose the cluster agent where the workspace agent will be deployed.
   This ensures that workloads run on the infrastructure managed by that specific agent.

4. S3 Bucket:
   Select the S3 bucket to be used by the new workspace.
   The chosen bucket stores runtime artifacts and Flink checkpoints for the workspace’s deployments.

Uninstall the Agent

To uninstall the Ververica Agent from your cluster, follow these steps:

1. Ensure no vclusters are running:
   Verify that no virtual clusters (vclusters) are currently active in your Kubernetes cluster.

2. Delete associated webhooks:
   Run the following commands to remove the associated webhook configurations:

   kubectl delete mutatingwebhookconfiguration 0100-pyxis-mutating-webhook
   kubectl delete validatingwebhookconfiguration pyxis-validating-webhook

3. Uninstall the Helm chart:
   Use Helm to uninstall the pyxis release:

   helm -n kube-system uninstall pyxis