Getting Started: Self-managed v3.x

This page explains how to install Ververica Platform 3.x on Kubernetes using Helm.

Watch this video for an overview about installing Ververica Platform 3.x.

Helm is a package manager for Kubernetes. A Helm package is called a chart and contains all resource definitions required to run an application. If you’re new to Helm, see the Helm charts documentation (https://v3.helm.sh/docs/topics/charts/).

Prerequisites

This installation assumes you have helm and kubectl installed and access to a Kubernetes cluster. Ververica Platform supports Helm 3 (3.8+ recommended for OCI support).

To verify your environment:

1kubectl get pods
2helm version
3helm list

Additional cluster prerequisites:

• Kubernetes Version: Ververica Platform 3.x requires Kubernetes 1.24 - 1.34.
• Database: A running MySQL (8.x) or MariaDB (10.x) instance with lower_case_table_names=1 set.
• Blob Storage: An S3-compatible object store (like AWS S3, MinIO) or Azure Blob Storage.
• Default StorageClass: A default StorageClass is required if you rely on dynamic Persistent Volume provisioning.
• RBAC: RBAC-enabled clusters are required. The chart creates the necessary roles by default (rbac.create: true).

Chart Repository and Image Access

Ververica Platform charts are published as OCI artifacts and are publicly accessible. The corresponding Docker images are private.

• OCI Registry: oci://registry.ververica.cloud/platform-charts/ververica-platform
• Images: Hosted in a private registry. Contact Ververica Customer Support to grant image pull access.

Namespace and Secret Configuration

Before installing, you must create namespaces for the platform (e.g., vvp-system) and for your Flink deployments (e.g., vvp-deploy). You must also create an imagePullSecret in both namespaces so that Kubernetes can pull the private Ververica images.

1# 1. Create the namespaces
2kubectl create ns vvp-system
3kubectl create ns vvp-deploy
4
5# 2. Create the secret in the platform namespace
6kubectl -n vvp-system create secret docker-registry ververica-registry \
7    --docker-username=<your-username> \
8    --docker-password=<your-password> \
9    --docker-server=registry.ververica.cloud
10
11# 3. Create the secret in the Flink deployment namespace
12kubectl -n vvp-deploy create secret docker-registry ververica-registry \
13    --docker-username=<your-username> \
14    --docker-password=<your-password> \
15    --docker-server=registry.ververica.cloud

Chart Configuration

Create a values.yaml file to configure your installation. This file needs to contain configurations for your database, blob storage, and image registry settings. If you need Single Sign-On, follow the information in the (Optional) Configure Single Sign-On (SSO) (#optional-configure-single-sign-on-sso) section in addition to the required chart configurations.

Here is a comprehensive template. Append these sections to your values.yaml file, filling in the required values.

1# values.yaml (example for Ververica Platform 3.x)
2
3global:
4  # -- Database Configuration (MySQL 8.x or MariaDB 10.x) --
5  # lower_case_table_names=1 is required
6  database:
7    host: {your-db-host}
8    port: {your-db-port}
9    user: {your-db-user}
10    password: {your-db-pass}
11
12  # -- Blob Storage Configuration (Choose ONE) --
13
14  # Option 1: AWS S3
15  blobStorage:
16    baseUri: s3i://{your-s3-bucket-name}
17    s3:
18      region: {your-aws-s3-region}          # e.g., eu-west-1
19      accessKeyId: {your-aws-s3-access-key}
20      secretAccessKey: {your-aws-s3-access-secret}
21      # endpoint: {your-aws-s3-endpoint}  # Only set for custom S3 endpoints
22
23  # Option 2: MinIO (or other S3-compatible)
24  # blobStorage:
25  #   baseUri: s3i://{your-minio-bucket}
26  #   s3:
27  #     endpoint: http://{minio-service-host}:{minio-port}
28  #     accessKeyId: {your-minio-access-key}
29  #     secretAccessKey: {your-minio-secret-key}
30
31  # Option 3: Azure Blob Storage
32  # blobStorage:
33  #   baseUri: wasbs://{your-container-name}
34  #   azure:
35  #     connectionString: "{your-azure-storage-connection-string}"
36
37  # -- Authentication Configuration --
38  # Default is single-user mode.
39  # For OIDC or SAML, see the "(Optional) Configure Single Sign-On (SSO)" section.
40  authentication:
41    single-user:
42      enabled: true
43
44  # -- Private Image Registry Settings --
45  image:
46    registry: registry.ververica.cloud
47  imagePullSecretName: ververica-registry # Must match the secret you created
48
49  # -- RBAC Configuration --
50  # Must include your platform namespace and Flink deployment namespace(s)
51  rbac:
52    additionalNamespaces:
53      - vvp-system
54      - vvp-deploy

(Optional) Configure Single Sign-On (SSO)

By default, Ververica Platform installs in single-user mode. To enable OIDC or SAML, you must disable single-user mode and configure both your Identity Provider and an initial admin user in your values.yaml file before running helm install.

1. Configure Your Identity Provider (Choose One)

In your values.yaml, set global.authentication.single-user.enabled to false and add the configuration for your chosen provider.

OIDC:

`yaml global: authentication: single-user: enabled: false callbackUrl: https://{your-vvp-domain}/authentication/callback oidc: enabled: true clientId: {your-oidc-client-id} clientSecret: {your-oidc-client-secret} discoveryUri: {your-oidc-discovery-uri} `

SAML

`yaml global: authentication: single-user: enabled: false callbackUrl: https://{your-vvp-domain}/authentication/callback saml: enabled: true identity-provider: metadata: | ... service-provider: entity-id: {your-service-provider-entity-id} keystore: certificate: | -----BEGIN CERTIFICATE----- ... -----END CERTIFICATE----- private-key: | -----BEGIN PRIVATE KEY----- ... -----END PRIVATE KEY----- `

2. Configure the Initial Admin User (Required for SSO)

When SSO is enabled, you must also define at least one admin user. This user's userId must match the email (OIDC) or NameId (SAML) that will be provided by your IDP.

Add this initialAccessFileContent block to your values.yaml at the same level as authentication (under global).

1global:
2  # ... (authentication block from Step 1) ...
3
4  initialAccessFileContent:
5    initialAccess:
6      - userId: {your-admin-user-id}
7        workspaceId: defaultworkspace
8        role: ADMIN
9      - userId: {your-admin-user-id}
10        workspaceId: defaultworkspace
11        namespaceId: default
12        role: ADMIN

Initial Installation

After creating your namespaces, secrets, and values.yaml file, you can install the chart.

1helm install ververica-platform \
2  oci://registry.ververica.cloud/platform-charts/ververica-platform \
3  --version 3.1.0 \
4  --namespace vvp-system \
5  --values values.yaml

Retrieving the License Token

The initial installation generates a verification token required for your license. This token is printed in the logs of the Application Manager pod.

Run the following command to view the token:

1kubectl logs vvp-appmanager-0 -n vvp-system

Email this token to license_request@ververica.com to receive your license information. After you have received your license, follow the steps in the next section, *License Configuration*, to complete the installation.

License Configuration

After you complete the initial installation above, you need to apply your license.

1. Add the license JSON block to your values.yaml file.

1# Append to your values.yaml
2global:
3  # -- License Configuration (Required) --
4  # Paste your entire license JSON block provided by Ververica.
5  vvp:
6    license:
7      data: {
8        "kind": "License",
9        "apiVersion": "v1",
10        "metadata": {
11          "id": "679b24cc-eba0-47f4-9798-8b5dd6b4bdc0",
12          ...
13        },
14        "spec": {
15          "licenseId": "674f24cc-eba0-47s4-9798-8b5tt6b4bdc0",
16          ...
17        }
18      }

1. After adding the license to your values.yaml file, run helm upgrade to apply the changes to your existing release. This command concludes the installation.

1helm upgrade ververica-platform \
2  oci://registry.ververica.cloud/platform-charts/ververica-platform \
3  --version 3.1.0 \
4  --namespace vvp-system \
5  --values values.yaml

Verification

Check that all pods are starting correctly in the vvp-system namespace. It may take a few minutes for all components to become Running.

1kubectl get pods -n vvp-system
2kubectl get svc -n vvp-system

Accessing the Platform

You can access the platform UI by forwarding the gateway service or by configuring an Ingress.

Option 1: Port Forwarding (for Testing)

1. Find the gateway service name (e.g., api-gateway).

1kubectl get svc -n vvp-system

1. Forward the service to your local machine (e.g., on port 8080).

1kubectl port-forward service/api-gateway 8080:8080 -n vvp-system 

1. Open the UI in your browser at http://localhost:8080.

Option 2: Kubernetes Ingress (for Production)

Here is a sample Ingress definition for an NGINX Ingress controller.

1apiVersion: networking.k8s.io/v1
2kind: Ingress
3metadata:
4  name: vvp-ingress
5  namespace: vvp-system
6  annotations:
7    kubernetes.io/ingress.class: nginx
8spec:
9  rules:
10    - host: vvp.your-domain.com
11      http:
12        paths:
13          - path: /
14            pathType: Prefix
15            backend:
16              service:
17                name: api-gateway # Verify this service name
18                port:
19                  number: 80

Create a Deployment Target

A deployment target specifies the Kubernetes namespace where Flink job managers and task managers are deployed. In your values.yaml file, vvp-deploy is one of the additional namespaces the platform can access.

To create a deployment target:

1. Go to Deployment Targets.
2. Click Create Deployment Target.
3. In the Deployment Target Name field, enter a descriptive name, such as mytarget.
4. In the Kubernetes Namespace field, enter vvp-deploy.
5. Click OK.

Watch the video below for an overview of this procedure.

Minimal Resource Configuration

To run Ververica Platform on a resource-constrained Kubernetes cluster (such as a local test environment), you can use the following minimal resource configuration.

```yaml vvp-gateway: resources: limits: { cpu: "2", memory: 5Gi } requests: { cpu: "0.5", memory: 2Gi }

vvp-appmanager: resources: limits: { cpu: "2", memory: 3.5Gi } requests: { cpu: "0.5", memory: 3Gi }

vvp-appagent: appAgentResources: limits: { cpu: "2", memory: 1Gi } requests: { cpu: "0.5", memory: 1Gi } sqlServiceResources: limits: { cpu: "2", memory: "3.5Gi" } requests: { cpu: "0.5", memory: 2.5Gi }

vvp-autopilot: resources: limits: { cpu: "2", memory: 1Gi } requests: { cpu: "0.5", memory: 1Gi }

vvp-meta: resources: limits: { cpu: "2", memory: "1Gi" } requests: { cpu: "0.5", memory: "1Gi" }

vvp-advisor: resources: limits: { cpu: "2", memory: "1Gi" } requests: { cpu: "0.5", memory: "1Gi" }

Uninstalling

To uninstall the Ververica Platform release:

1helm uninstall ververica-platform -n vvp-system

You may also need to manually delete the namespaces, secrets, and any persistent volumes (PVCs) created by the chart.