Skip to main content

Tutorial: Creating a Java Deployment

This tutorial guides you through the process of creating and deploying a Java-based application to Ververica Cloud using its REST API. We will walk through authenticating, setting up a workspace, uploading your application artifact, and finally, creating the deployment.

Prerequisites:

  • You have a Ververica Cloud account.
  • You have downloaded a compiled Java application .jar file ready for deployment.
  • You have downloaded Shakespeare.txt to your local machine.
  • You have a command-line tool like cURL installed for making API requests.

Step 1: Authenticate and Get an Access Token​

First, you need to authenticate with the Ververica API to get a bearer token. This token must be included in the header of all subsequent requests.

Send a POST request to the /api/v1/auth/tokens endpoint with your credentials.

curl https://app.ververica.cloud/api/v1/auth/tokens \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{
  "flow": "credentials",
  "username": "<YOUR_EMAIL@company.com>",
  "password": "<YOUR_SECURE_PASSWORD>"
}'

The API returns a response containing your access token.

Response:

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresIn": 3599,
  "refreshExpiresIn": 3599,
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "tokenType": "Bearer"
}

Save Your Token Copy the accessToken value from the response body. You will need to use it in the Authorization header for the rest of the API calls in this tutorial.

Authorization: Bearer <YOUR_ACCESS_TOKEN>

Step 2: Find an Available Billing Plan​

Next, create a workspace where your deployments will live. A workspace requires a billingPlanId. To find an available ID, query the /api/v1/workspaces/billingPlans endpoint.

curl 'https://app.ververica.cloud/api/v1/workspaces/billingPlans' \
  --header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>'

This returns a list of all available billing plans. Look through the list and choose a plan that fits your needs (e.g., Pay as You Go, Reserved Capacity, etc.).

Example Response Snippet:

{
  "billingPlans": [
    {
      "id": 8,
      "name": "PAYG Azure (Germany West Central)",
      "offering": {
        "type": "PAYG",
        "name": "Pay as You Go"
      },
      ...
    },
    {
      "id": 12,
      "name": "RC 30 EU West (Ireland)",
      "offering": {
        "type": "RC",
        "name": "RC 30"
       },
      ...
    }
  ]
}

From the response, identify the id of the billing plan you want to use.

note

If you are unsure which plan to use, contact your organization's Ververica Cloud administrator or the team lead who manages your cloud subscription. Using the wrong plan could have financial implications.

For this tutorial, use the "Pay as You Go" plan with id: 8.

Step 3: Create a Workspace​

Now, use the billingPlanId to create your workspace. Give your workspace a unique name.

Send a POST request to /api/v1/workspaces.

curl https://app.ververica.cloud/api/v1/workspaces \
  --request POST \
  --header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "my-first-java-workspace",
  "billingPlanId": 8
}'

The workspace creation is asynchronous. After a successful request, you can check its status in the Ververica Cloud UI.

Note Your Workspace and Namespace Once your workspace is created, you will need its unique ID and the namespace for future steps. In Ververica Cloud, the default namespace is simply "default".

Step 4: Upload Your JAR Artifact​

To deploy your Flink job, you must first upload your JAR artifact. This involves two steps:

  1. Get a secure, pre-signed URL for uploading.
  2. Upload your .jar file to that URL.

4.1 Get a Pre-signed Upload URL​

Request a temporary signature from the API. You must provide your workspace ID, namespace, and the exact fileName of the .jar you intend to upload.

# Replace {workspace} with your actual workspace ID
# Replace FlinkQuickStart-1.0-SNAPSHOT.jar with your JAR's filename
curl 'https://app.ververica.cloud/api/v1/workspaces/{workspace}/namespaces/default/artifacts:signature?fileName=FlinkQuickStart-1.0-SNAPSHOT.jar&fileType=ARTIFACT' \
  --header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>'

The response contains a presignedUrlForPut and an artifactPath.

Response:

{
    "artifactPath": "s3i://vvc-tenant-u6qci2oesiq2a6s2-eu-west-1/artifacts/namespaces/default/FlinkQuickStart-1.0-SNAPSHOT.jar",
    "presignedUrlForPut": "https://s3.eu-west-1.amazonaws.com/vvc-tenant-u6qci2oesiq2a6s2-eu-west-1/artifacts/namespaces/default/FlinkQuickStart-1.0-SNAPSHOT.jar?X-Amz-Security-Token=...",
    ...
}

Copy the presignedUrlForPut and the artifactPath for the next step.

4.2 Upload the File​

Use the presignedUrlForPut to upload your local .jar file. This is a POST request containing the file data.

# Replace {workspace} with your actual workspace ID
curl https://app.ververica.cloud/api/v1/workspaces/{workspace}/namespaces/default/artifacts:saveMetadata \
  --request POST \
  --header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
  "filename": "FlinkQuickStart-1.0-SNAPSHOT.jar",
  "jarUrl": "<ARTIFACT_PATH_FROM_STEP_4.1>"
}'

A successful upload returns an HTTP 200 OK status.

{
  "artifact": {
    "kind": "JAR",
    "jarArtifact": {
      "jarUri": "https://example.com/artifacts/my-job.jar",
      "entryClass": "org.example.Main"
    }
  }
}

Step 5: Create the Deployment​

You are now ready to create the final deployment. This API call ties together your workspace, namespace, and uploaded artifact. You also need to specify a Flink engine version and execution mode.

Send a POST request to the /api/v2/workspaces/{workspace}/namespaces/{namespace}/deployments endpoint.

# Replace {workspace} with your actual workspace ID
# Update the jarUri to match your artifact's path
curl https://app.ververica.cloud/api/v2/workspaces/{workspace}/namespaces/default/deployments \
  --request POST \
  --header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "my-first-java-deployment",
  "engineVersion": "vera-1.0.3-flink-1.17",
  "executionMode": "STREAMING",
  "deploymentTarget": {
    "mode": "SESSION",
    "name": "session-cluster-name"
  },
  "artifact": {
    "kind": "JAR",
    "jarArtifact": {
      "jarUri": "<ARTIFACT_PATH_FROM_STEP_4.1>"
    }
  },
  "namespace": "default"
}'

If the request is successful, the API returns a detailed JSON object for your new deployment, including its deploymentId.

Congratulations! You have successfully created a workspace, uploaded an application artifact, and launched a new Java deployment using the Ververica API. You can now manage and monitor your running application through the Ververica Cloud UI or continue to interact with it via the API.

On this page