Press Blocks

Providing Instance Type and Storage in Workflow Block Spec

When defining a workflow step in workflow block spec, you have the option to set the instance type and storage by including them under the resources key in the following YAML format:

resources:
    instanceTypeId: 23,
    storage: 20GB,

To obtain a list of all available instances along with their corresponding instanceTypeId, you can use the following command:

peak tenants list-instance-options --entity-type workflow

Adding the resources section is optional. If you don’t specify it for a particular step, the default values will be used. You can retrieve the default values through the following command:

peak workflows list-default-resources

Providing Instance Type in Service Block Spec

When defining a service block spec, you have the option to set the instance type by including them under the resources key in the following YAML format:

resources:
    instanceTypeId: 1,

To obtain a list of all available instances along with their corresponding instanceTypeId, you can use the following command:

peak tenants list-instance-options --entity-type webapp

Session Stickiness in Service Block

This is only applicable for Service Blocks of kind web-app.

By default, session stickiness is disabled (false). You can activate session stickiness by setting the sessionStickiness parameter to true.

Session stickiness ensures that each user’s requests are consistently directed to a particular server. This feature is especially valuable for stateful applications like web applications that rely on server-stored session data.

Note that employing session stickiness may lead to unpredictable behavior and is not recommended if you plan to scale your application.

Providing Press Parameters in Blocks

We can define Press parameters in the block spec and provide their values while creating the block deployment. The values for these parameters can be updated even after the deployment has been done. hideValue can be optionally provided to parameters of type string, to mask the parameter’s value when it has been set at deployment time. This only applies to when describing a block deployment or viewing the parameters on Peak Platform and has no effect when using get_parameters.

Parameters come in 2 types, build and run.

  • build parameters given a value and also used at deployment time only, to modify parts of a spec’s config section.

  • run parameters given a value at deployment time, and are accessible via calling get-parameters from within a running image, so they can be used whenever the block’s platform resources are run.

To use build parameters, we must define the parts of the config that we wish to make parameterized, using the @param:PARAM_NAME syntax (param name must match /^[a-zA-Z0-9_-]+$/):

config:
    steps:
        test:
            command: echo 1
            type: standard
            image:
                context: "."
                dockerfile: Dockerfile
                version: 0.0.1
                buildArguments: "@param:build_arguments"
                useCache: "@param:use_cache"
    triggers:
        - cron: "0 0 * * *"
    watchers:
        - user: "@param:watcher_user"
          events:
              success: false
              fail: true
        - webhook:
              name: info
              url: https://abc.com/post
              payload: |
                  {
                    "system": "external_system",
                    "action": "update",
                    "data": {
                      "field": "value",
                      "timestamp": "2024-05-20T12:00:00Z"
                    }
                  }
          events:
              success: false
              fail: true
              runtimeExceeded: "@param:runtime_exceeded"
        - email:
              name: "email-watcher-1"
              recipients:
                  to:
                      - user1@peak.ai
                      - user2@peak.ai
          events:
              success: false
              fail: true
              runtimeExceeded: "@param:runtime_exceeded"

We can then define parameters in the following format as part of the block spec payload:

parameters:
    build:
        - defaultValue: user@peak.ai
          description: Set the watcher user email
          name: watcher_user
          required: true
          title: Watcher User Email
          type: string
          hideValue: false
        - defaultValue: false
          description: Enable image caching for the workflow
          name: use_cache
          required: false
          title: Image Caching
          type: boolean
        - defaultValue: 10
          description: Select the runtime exceeded value to trigger a failed notification for the workflow (in minutes)
          name: runtime_exceeded
          options:
              - title: Low
                value: 10
              - title: Medium
                value: 50
              - title: High
                value: 100
          required: false
          title: Runtime Exceeded
          type: number
        - description: Specify the build arguments
          name: build_arguments
          properties:
              - name: git_token
                required: false
                title: Git Token
                type: string
              - name: npm_token
                required: true
                title: NPM Token
                type: string
          required: true
          title: Build Arguments
          type: object
        - description: Specify the watchers for the workflow
          name: watchers
          title: Watchers
          type: object_array
          properties:
              - name: watcher_user
                required: true
                title: Watcher User
                type: string
              - name: watcher_type
                required: true
                title: Watcher Type
                type: string
              - name: watcher_email
                required: true
                title: Watcher Email
                type: string
    run:
        - defaultValue: AVG
          description: Select an aggregation function (e.g., AVG, SUM, COUNT)
          name: agg_type
          required: false
          title: Agg Type
          type: string
          hideValue: true
        - defaultValue: false
          description: Enable email notifications
          name: email_notifications
          required: false
          title: Email Notifications
          type: boolean
        - defaultValue: 10
          description: Select the number of iterations
          name: num_iterations
          options:
              - title: Low
                value: 10
              - title: Medium
                value: 50
              - title: High
                value: 100
          required: false
          title: Number of Iterations
          type: number
        - defaultValue:
              - input.csv
              - output.csv
          description: Specify input and output file names
          name: file_names
          required: true
          title: File Names
          type: string_array
        - description: Specify database configuration
          name: database
          properties:
              - name: db_host
                required: true
                title: Database Host
                type: string
              - name: db_port
                required: true
                title: Database Port
                type: number
              - name: db_credentials
                properties:
                    - name: username
                      required: true
                      title: Username
                      type: string
                    - name: password
                      required: true
                      title: Password
                      type: string
                required: true
                title: Database Credentials
                type: object
          required: false
          title: Database Configuration
          type: object
        - description: Specify attributes for the charts
          name: chart_attributes
          title: Chart Attributes
          type: object_array
          properties:
              - name: chart_name
                required: true
                title: Chart Name
                type: string
              - name: chart_type
                required: true
                title: Chart Type
                type: string
              - name: chart_data
                required: true
                title: Chart Data
                type: string_array

We can provide the values of these parameters while creating the block deployment in the following format:

parameters:
    build:
        watcher_user: "abc@123.com"
        use_cache: true
        runtime_exceeded: 10
        build_arguments:
            git_token: "random_git_token"
            npm_token: "random_npm_token"
        watchers:
            - watcher_user: "User 1"
              watcher_type: "email"
              watcher_email: "user1@peak.ai"
            - wather_user: "User 2"
              watcher_type: "webhook"
              watcher_email: "user2@peak.ai"
    run:
        agg_type: "SUM"
        num_iterations: 50
        email_notifications: true
        file_names:
            - input.csv
            - output.csv
        database:
            db_host: "localhost"
            db_port: 5432
            db_credentials:
                username: "admin"
                password: "admin123" ## pragma: allowlist secret
        chart_attributes:
            - chart_name: "Chart 1"
              chart_type: "line"
              chart_data:
                  - "data1"
                  - "data2"
            - chart_name: "Chart 2"
              chart_type: "bar"
              chart_data:
                  - "data3"
                  - "data4"

Providing Triggers in Workflow Block Spec

For Workflow Blocks, triggers can be one of the following: Time based, Webhook based or Manual.

# For Time Based Trigger, cron expression is required
triggers:
  - cron: "0 0 * * *"

# For Webhook Based Trigger, we need to provide webhook key which is a boolean
triggers:
  - webhook: true

# For Manual Trigger, we can either skip this key or provide an empty list
triggers:
  - {}

Providing Watchers in Workflow Block Spec

For Workflow Blocks, we can set multiple watchers which can be User, Webhook or Email Based.

# For User Based Watcher, user email is required. We also need to specify the events for which we want to receive notifications.

watchers:
  - user: "someone@peak.ai"
    events:
      success: false
      fail: true

Providing Image Details for Block Specs

For creating block specs, there are 3 ways of providing image details.

# Using imageRef, we can provide multiple image configurations in block config and can refer them in workflow steps as shown in following example.

config:
    images:
        image1:
            context: "."
            dockerfile: Dockerfile
            version: 0.0.1
            buildArguments:
                npm_token: random_token
        image2:
            context: "."
            dockerfile: Dockerfile
            version: 0.0.1
            buildArguments:
                npm_token: random_token
    steps:
        step1:
            command: echo hello
            type: standard
            imageRef: image1
            resources:
                instanceTypeId: 21
                storage: 10GB
        step2:
            command: echo world
            type: standard
            imageRef: image2
            resources:
                instanceTypeId: 21
                storage: 20GB

Usage Examples

Block Specs

Creating a Block Spec

We can create a block spec by providing payload containing metadata, parameters, and configuration details.

We can set the autoRunOnDeploy key to true to execute resources on successful block deployment. It is optional and defaults to false.

# block_spec.yaml

body:
  version: 1
  kind: workflow
  metadata:
    name: workflow-block
    title: Workflow Block
    summary: Workflow Block
    description: Creating a new workflow block spec
    descriptionContentType: text/markdown
    imageUrl: https://my-block-pics.com/image-0.jpg
    tags:
      - name: CLI
  release:
    version: 1.0.0
    notes: This is the original release
  config:
    steps:
      step1:
        command: echo 1
        type: standard
        image:
          context: "."
          dockerfile: Dockerfile
          version: 0.0.1
          buildArguments:
            git_token: random_token_1
            npm_token: random_token_2
          useCache: "@param:use_cache"
        resources:
          instanceTypeId: 21
          storage: 10GB
        stepTimeout: 30
        clearImageCache: true
        parameters:
          env:
            key: value
          secrets:
            - secret-1
            - secret-2
        repository:
          branch: main
          token: random_token
          url: "https://github.com/org/repo"
      step2:
        type: http
        method: post
        url: "https://peak.ai"
        payload: "{}"
        auth:
          type: no-auth
        headers:
          absolute:
            Content-Type: application/json
          secrets:
            token: some-token
      step3:
        type: sql
        repository:
          branch: main
          token: random_token
          url: "https://example.com"
          filePath: "path/to/file.sql"
        parameters:
          env:
            key1: value1
            key2: value2
          inherit:
            key3: value3
            key4: value4
      step4:
        type: export
        schema: schema_name
        table: table_name
        sortBy: column_name
        sortOrder: asc
        compression: false
    triggers:
      - cron: "0 0 * * *"
    watchers:
      - user: "@param:watcher_user"
        events:
          success: false
          fail: true
      - webhook:
          name: info
          url: https://abc.com/post
          payload: |
            {
              "system": "external_system",
              "action": "update",
              "data": {
                "field": "value",
                "timestamp": "2024-05-20T12:00:00Z"
              }
            }
        events:
          success: false
          fail: true
          runtimeExceeded: "@param:runtime_exceeded"
      - email:
          name: "email-watcher-1"
          recipients:
            to:
              - "user1@peak.ai"
              - "user2@peak.ai"
        events:
          success: false
          fail: true
          runtimeExceeded: "@param:runtime_exceeded"
parameters:
  build:
    - defaultValue: user@peak.ai
      description: Set the watcher user email
      name: watcher_user
      required: true
      title: Watcher User Email
      type: string
      hideValue: false
    - defaultValue: false
      description: Enable image caching for the workflow
      name: use_cache
      required: false
      title: Image Caching
      type: boolean
    - defaultValue: 10
      description: Select the runtime exceeded value to trigger a failed notification for the workflow (in minutes)
      name: runtime_exceeded
      options:
        - title: Low
          value: 10
        - title: Medium
          value: 50
        - title: High
          value: 100
      required: false
      title: Runtime Exceeded
      type: number
  run:
    - defaultValue: AVG
      description: Select an aggregation function (e.g., AVG, SUM, COUNT)
      name: agg_type
      required: false
      title: Agg Type
      type: string
      hideValue: true
    - defaultValue: false
      description: Enable email notifications
      name: email_notifications
      required: false
      title: Email Notifications
      type: boolean
    - defaultValue: 10
      description: Select the number of iterations
      name: num_iterations
      options:
        - title: Low
          value: 10
        - title: Medium
          value: 50
        - title: High
          value: 100
      required: false
      title: Number of Iterations
      type: number
    - defaultValue:
        - input.csv
        - output.csv
      description: Specify input and output file names
      name: file_names
      required: true
      title: File Names
      type: string_array
artifact:
  path: "."
  ignore_files:
    - ".gitignore"
    - ".dockerignore"
featured: true
autoRunOnDeploy: true
scope: shared
tenants:
  - tenant1
  - tenant2

To create the block spec, use the following command, including the path to the block_params.yaml file to utilize the defined parameters:

peak blocks specs create path/to/block_spec.yaml -v path/to/block_params.yaml

To add parameters through command itself, use the -p flag followed by the desired key-value pairs:

peak blocks specs create path/to/block_spec.yaml -p git_token=test_git_token -p npm_token=test_npm_token

If you want to specify both a parameters file and individual parameters, the parameters provided on the command line will overwrite the values defined in the file. For example, running the following command will set the value of git_token to test_git_token.

peak blocks specs create path/to/block_spec.yaml -v path/to/block_params.yaml -p git_token=test-git_token

Updating Block Spec Metadata

We can update the metadata and discoverability of an existing block spec by providing its id and the payload containg new metadata.

# block_spec_metadata.yaml

body:
  metadata:
    name: updated-workflow-block
    title: Updated Workflow Block
    summary: Updated Workflow Block
    description: Updating workflow block metadata
    descriptionContentType: text/markdown
    imageUrl: https://my-block-pics.com/image-0.jpg
    status: available
    tags:
      - name: CLI
  featured: false
  scope: private

We can use the following command to update the spec metadata:

peak blocks specs update-metadata <spec_id> path/to/update_block_spec_metadata.yaml

Creating a new Block Spec Release

We can create a new release for an existing block spec by providing spec id and payload containing new configuration details and release info.

We can set the autoRunOnDeploy key to true to execute resources on successful block deployment. It is optional and defaults to false.

# block_spec_release.yaml

body:
  release:
    version: 2.0.0
    notes: This is a new release
  config:
    steps:
      step1:
        command: echo 1
        type: standard
        image:
          context: "."
          dockerfile: Dockerfile
          version: 0.0.2
          buildArguments:
            git_token: random_token_1
            npm_token: random_token_2
          useCache: "@param:use_cache"
        resources:
          instanceTypeId: 21
          storage: 10GB
        stepTimeout: 30
        clearImageCache: true
        parameters:
          env:
            key: value
          secrets:
            - secret-1
            - secret-2
        repository:
          branch: main
          token: random_token
          url: "https://github.com/org/repo"
      step2:
        type: http
        method: post
        url: "https://peak.ai"
        payload: "{}"
        auth:
          type: no-auth
        headers:
          absolute:
            Content-Type: application/json
          secrets:
            token: some-token
      step3:
        type: sql
        repository:
          branch: main
          token: random_token
          url: "https://example.com"
          filePath: "path/to/file.sql"
        parameters:
          env:
            key1: value1
            key2: value2
          inherit:
            key3: value3
            key4: value4
      step5:
        type: export
        schema: schema_name
        table: table_name
        sortBy: column_name
        sortOrder: asc
        compression: false
    triggers:
      - cron: "0 0 * * *"
    watchers:
      - user: "@param:watcher_user"
        events:
          success: false
          fail: true
      - webhook:
          name: info
          url: https://abc.com/post
          payload: |
            {
              "system": "external_system",
              "action": "update",
              "data": {
                "field": "value",
                "timestamp": "2024-05-20T12:00:00Z"
              }
            }
        events:
          success: false
          fail: true
          runtimeExceeded: "@param:runtime_exceeded"
      - email:
          name: "email-watcher-1"
          recipients:
            to:
              - "user1@peak.ai"
              - "user2@peak.ai"
        events:
          success: false
          fail: true
          runtimeExceeded: "@param:runtime_exceeded"
parameters:
  build:
    - defaultValue: user@peak.ai
      description: Set the watcher user email
      name: watcher_user
      required: true
      title: Watcher User Email
      type: string
      hideValue: false
    - defaultValue: false
      description: Enable image caching for the workflow
      name: use_cache
      required: false
      title: Image Caching
      type: boolean
    - defaultValue: 10
      description: Select the runtime exceeded value to trigger a failed notification for the workflow (in minutes)
      name: runtime_exceeded
      options:
        - title: Low
          value: 10
        - title: Medium
          value: 50
        - title: High
          value: 100
      required: false
      title: Runtime Exceeded
      type: number
  run:
    - defaultValue: AVG
      description: Select an aggregation function (e.g., AVG, SUM, COUNT)
      name: agg_type
      required: false
      title: Agg Type
      type: string
      hideValue: true
    - defaultValue: false
      description: Enable email notifications
      name: email_notifications
      required: false
      title: Email Notifications
      type: boolean
    - defaultValue: 10
      description: Select the number of iterations
      name: num_iterations
      options:
        - title: Low
          value: 10
        - title: Medium
          value: 50
        - title: High
          value: 100
      required: false
      title: Number of Iterations
      type: number
    - defaultValue:
        - input.csv
        - output.csv
      description: Specify input and output file names
      name: file_names
      required: true
      title: File Names
      type: string_array
artifact:
  path: "."
  ignore_files:
    - ".gitignore"
    - ".dockerignore"
autoRunOnDeploy: true

We can use the following command to create a new block spec release:

peak blocks specs create-release <spec_id> path/to/block_spec_release.yaml

Block Deployments

Creating a new Block Deployment

We can create a block deployment by providing payload containing metadata, parameters, revision and spec info.

# block_deployment.yaml

body:
  metadata:
    name: workflow-block-deployment
    title: Workflow Block Deployment
    summary: Workflow Block Deployment
    description: Creating a new workflow block deployment
    descriptionContentType: text/markdown
    imageUrl: https://my-block-pics.com/image-0.jpg
    tags:
      - name: CLI
  parameters:
    build:
      watcher_user: "abc@123.com"
      use_cache: true
      runtime_exceeded: 10
    run:
      agg_type: "SUM"
      num_iterations: 50
      email_notifications: true
      file_names:
        - input.csv
        - output.csv
  revision:
    notes: This is the initial revision
  spec:
    id: 0bddb4c6-40c5-45c3-b477-fceb2c051609
    release:
      version: 1.0.0

We can use the following command to create a new block deployment:

peak blocks deployments create path/to/create_block_deployment.yaml

Creating a new Block Deployment Revision

We can create a block deployment revision by providing payload containing parameters, revision and spec info.

# block_deployment_revision.yaml

body:
  parameters:
    build:
      watcher_user: "abc@123.com"
      use_cache: true
      runtime_exceeded: 10
    run:
      agg_type: "SUM"
      num_iterations: 50
      email_notifications: true
      file_names:
        - input.csv
        - output.csv
  revision:
    notes: This is the second revision
  release:
    version: 2.0.0

We can use the following command to create a new block deployment revision:

peak blocks deployments create path/to/create_block_deployment_revision.yaml

Updating Block Deployment Metadata

We can update the block deployment metadata by providing deployment id and payload containing updated metadata.

# block_deployment_metadata.yaml

body:
  name: update-block-deployment
  title: Update Block Deployment
  summary: Update Block Deployment
  description: Updating block deployment metadata
  descriptionContentType: text/markdown
  imageUrl: https://my-block-pics.com/image-0.jpg
  tags:
    - name: CLI

We can use the following command to update block deployment metadata:

peak blocks deployments update-metadata <deployment_id> path/to/update_block_deployment_metadata.yaml

Redeploying a Block Deployment

We can redeploy latest revision of an existing block deployment provided it is in failed or warning state.

We can use the following command to redeploy a block deployment:

peak blocks deployments redeploy <deployment_id>

Getting Block Deployment Parameters

  • The get-parameters function can be used to get the parameters for a block deployment.

  • By default, it automatically picks the Deployment ID from the PRESS_DEPLOYMENT_ID environment variable. So, just running the following command gives us all the parameters

    peak blocks deployments get-parameters

    The PRESS_DEPLOYMENT_ID environment variable is automatically added to Workflows and Webapps, so we can get the parameters by just running the above command.

  • If the environment variable is not present, we can pass in the value of the Deployment ID to the command as well

    peak blocks deployments get-parameters --deployment-id=<deployment_id>

  • Environment variable is given the highest priority. So, if the environment variable is present and we pass the deployment id as well, the value in environment variable will be used.

  • During development, you might not have the Deployment id. To be able to use the get-parameters function in that case, you can use a params file. Here’s how to use it

    • Create a YAML file containing all the required parameters.

      ```yaml
# fallback_params.yaml
agg_type: MAX
num_iterations: 50
```

    • While running the get-parameters command, pass the path to file as the value to --fallback-params-file option

      ```console
peak blocks deployments get-parameters --fallback-params-file=fallback_params.yaml
```

    • The function will pick the parameters from the file and return them. So, you can test the complete flow without having to deploy the block.

    • Remember that --fallback-params-file is only used when neither the environment variable is present nor the --deployment-id is passed. It is ignored otherwise.

Updating Block Deployment Parameters

We can update the parameters of a block deployment by providing the deployment id and payload containing updated parameters.

# block_deployment_parameters.yaml

body:
  agg_type: "MAX"
  num_iterations: 50
  email_notifications: true
  file_names:
    - input.csv
    - output.csv

peak blocks deployments patch-parameters <deployment_id> path/to/patch_block_parameters.yaml