Skip to main content

Getting Started

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

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.

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:

kubectl get pods
helm version
helm 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.
note

OCI charts do not require helm repo add.

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. Create the namespaces
kubectl create ns vvp-system
kubectl create ns vvp-deploy

# 2. Create the secret in the platform namespace
kubectl -n vvp-system create secret docker-registry ververica-registry \
    --docker-username=<your-username> \
    --docker-password=<your-password> \
    --docker-server=registry.ververica.cloud

# 3. Create the secret in the Flink deployment namespace
kubectl -n vvp-deploy create secret docker-registry ververica-registry \
    --docker-username=<your-username> \
    --docker-password=<your-password> \
    --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) 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.

# values.yaml (example for Ververica Platform 3.x)

global:
  # -- Database Configuration (MySQL 8.x or MariaDB 10.x) --
  # lower_case_table_names=1 is required
  database:
    host: {your-db-host}
    port: {your-db-port}
    user: {your-db-user}
    password: {your-db-pass}

  # -- Blob Storage Configuration (Choose ONE) --

  # Option 1: AWS S3
  blobStorage:
    baseUri: s3i://{your-s3-bucket-name}
    s3:
      region: {your-aws-s3-region}          # e.g., eu-west-1
      accessKeyId: {your-aws-s3-access-key}
      secretAccessKey: {your-aws-s3-access-secret}
      # endpoint: {your-aws-s3-endpoint}  # Only set for custom S3 endpoints

  # Option 2: MinIO (or other S3-compatible)
  # blobStorage:
  #   baseUri: s3i://{your-minio-bucket}
  #   s3:
  #     endpoint: http://{minio-service-host}:{minio-port}
  #     accessKeyId: {your-minio-access-key}
  #     secretAccessKey: {your-minio-secret-key}

  # Option 3: Azure Blob Storage
  # blobStorage:
  #   baseUri: wasbs://{your-container-name}
  #   azure:
  #     connectionString: "{your-azure-storage-connection-string}"

  # -- Authentication Configuration --
  # Default is single-user mode.
  # For OIDC or SAML, see the "(Optional) Configure Single Sign-On (SSO)" section.
  authentication:
    single-user:
      enabled: true

  # -- Private Image Registry Settings --
  image:
    registry: registry.ververica.cloud
  imagePullSecretName: ververica-registry # Must match the secret you created

  # -- RBAC Configuration --
  # Must include your platform namespace and Flink deployment namespace(s)
  rbac:
    additionalNamespaces:
      - vvp-system
      - 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:

note

The userId for OIDC is the email from your IDP.

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

note

The userId for SAML is the NameId from your IDP.

global:
  authentication:
    single-user:
      enabled: false
    callbackUrl: https://{your-vvp-domain}/authentication/callback
    saml:
      enabled: true
      identity-provider:
        metadata: |
          <?xml version="1.0" encoding="UTF-8"?><md:EntityDescriptor ...>
            ...
          </md:EntityDescriptor>
      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).

global:
  # ... (authentication block from Step 1) ...

  initialAccessFileContent:
    initialAccess:
      - userId: {your-admin-user-id}
        workspaceId: defaultworkspace
        role: ADMIN
      - userId: {your-admin-user-id}
        workspaceId: defaultworkspace
        namespaceId: default
        role: ADMIN

Initial Installation​

After creating your namespaces, secrets, and values.yaml file, you can install the chart. This initial installation will generate a token. You need to email the generated 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.

helm install ververica-platform \
  oci://registry.ververica.cloud/platform-charts/ververica-platform \
  --version 3.0.0 \
  --namespace vvp-system \
  --values values.yaml
note

After running the initial helm install above, it is expected that several core pods may fail or remain in a non-ready state. This is the platform waiting for the required license configuration to be applied. Do not troubleshoot at this stage. Proceed directly to the License Configuration section below to finalize 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.

    # Append to your values.yaml
    global:
      # -- License Configuration (Required) --
      # Paste your entire license JSON block provided by Ververica.
      vvp:
        license:
          data: {
            "kind": "License",
            "apiVersion": "v1",
            "metadata": {
              "id": "679b24cc-eba0-47f4-9798-8b5dd6b4bdc0",
              ...
            },
            "spec": {
              "licenseId": "674f24cc-eba0-47s4-9798-8b5tt6b4bdc0",
              ...
            }
          }

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

    helm upgrade ververica-platform \
      oci://registry.ververica.cloud/platform-charts/ververica-platform \
      --version 3.0.0 \
      --namespace vvp-system \
      --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.

kubectl get pods -n vvp-system
kubectl 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). 
    kubectl get svc -n vvp-system
  2. Forward the service to your local machine (e.g., on port 8080). 
    kubectl port-forward service/api-gateway 8080:8080 -n vvp-system
  3. 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.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: vvp-ingress
  namespace: vvp-system
  annotations:
    kubernetes.io/ingress.class: nginx
spec:
  rules:
    - host: vvp.your-domain.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: api-gateway # Verify this service name
                port:
                  number: 80

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.

note

This configuration is not recommended for production environments.

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:

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

On this page