Using Apps and Blocks via CLI

To create apps and blocks via the Command Line Interface (CLI), we have to define a YAML file. This YAML file includes the payload, metadata, and configuration of the app or block. By utilizing jinja syntax, we have the ability to pass paramater value as {{value}}, with the actual value being specified in a separate YAML file.

Defining CLI Parameters in App and Block Creation

While creating apps or blocks, we can define cli parameters in a separate file and then use them in the actual yaml file. We can refer the parameters by enclosing the parameter names in {{ }} and specifying the file path after the -v flag in the command. We can also add parameters by adding the desired key-value pair after the -p flag. If we specify both -v and -p, the parameters defined on the command line will overwrite the parameters defined in the file.

Consider the following parameters file:

# params.yaml

git_token: "random_git_token"
npm_token: "random_npm_token"

Consider the simple spec file where we want to use the parameters defined in the above file:

# 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:
            test:
                command: echo 1
                type: standard
                image:
                    context: "."
                    dockerfile: Dockerfile
                    version: 0.0.1
                    buildArguments:
                        git_token: { { git_token } }
                        npm_token: { { npm_token } }
        triggers:
            - cron: "0 0 * * *"

We can now create the spec by running the following command:

peak blocks specs create block_spec.yaml -v params.yaml

We can also add parameters by adding the desired key-value pair after the -p flag. If we specify both -v and -p, the parameters defined on the command line will overwrite the parameters defined in the file.

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

Similar approach can be used for creating other resources as well.

Creating Resource Dependencies with Artifacts

If we want to create a resource which is dependent on an Image (such as Block Spec) but we don’t want it to be source directly from the source code repository, then we will need to pack all the files we might need to build the image and pack them into an zip archive which is called Artifact.

More information for Artifact can be found in Artifact and Compression Doc.

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 Webapp Block Spec

When defining a webapp 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 Webapp Block

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:
                    git_token: random_token_1
                    npm_token: random_token_2
                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: '{ "pingback-url": "https:/workflow/123" }'
          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
    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

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
    run:
        agg_type: "SUM"
        num_iterations: 50
        email_notifications: true
        file_names:
            - input.csv
            - output.csv

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 and webhookPolicy which would be either "generate" (in case of creating a new webhook) or "preserve" (in case of using an existing webhook)
triggers:
  - webhook: true
    webhookPolicy: "generate"

# 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 Based or Webhook 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

# For Webhook Based Watcher, we need to provide webhook details such as webhook url and payload along with the events for which we want to receive notifications.
watchers:
  - webhook:
      name: "info"
      url: "https://abc.com/post"
      payload: "{'pingback-url':'https:/workflow/123'}"
    events:
      success: false
      fail: true
      runtimeExceeded: 10

# We can also add multiple watchers of different types
watchers:
  - user: "someone@peak.ai"
    events:
      success: false
      fail: true
  - webhook:
      name: "info"
      url: "https://abc.com/post"
      payload: "{'pingback-url':'https:/workflow/123'}"
    events:
      success: false
      fail: true
      runtimeExceeded: 10

Providing Image Details for Block Specs

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

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

2. Using inline image: We can directly provide the image configuration in the workflow step or webapp.

config:
    steps:
        step1:
            command: echo hello
            type: standard
            image:
                context: "."
                dockerfile: Dockerfile
                version: 0.0.1
                buildArguments:
                    npm_token: random_token
            resources:
                instanceTypeId: 21
                storage: 10GB

3. Using imageDetails: We can use exisiting image version in workflow step and webapp. The scope of block should be private if we are using existing image details.

config:
    steps:
        step1:
            command: echo world
            type: standard
            imageDetails:
                id: 1
                versionId: 1
            resources:
                instanceTypeId: 21
                storage: 20GB

Usage Examples

Block Specs

Creating a Block Spec

We can define the payload like following to create the block spec.

# 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:
      test:
        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"
    triggers:
      - cron: "0 0 * * *"
    watchers:
      - user: "@param:watcher_user"
        events:
          success: false
          fail: true
      - webhook:
          name: info
          url: https://abc.com/post
          payload: '{ "pingback-url": "https:/workflow/123" }'
        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
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/create_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/create_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/create_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.

# block_spec_release.yaml

body:
  release:
    version: 2.0.0
    notes: This is a new release
  config:
    steps:
      test:
        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"
    triggers:
      - cron: "0 0 * * *"
    watchers:
      - user: "@param:watcher_user"
        events:
          success: false
          fail: true
      - webhook:
          name: info
          url: https://abc.com/post
          payload: '{ "pingback-url": "https:/workflow/123" }'
        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"

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

peak blocks specs create-release <spec_id> path/to/create_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

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.

    // 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

    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

App Specs

Creating an App Spec

An app spec can be created by using existing block specs.

# app_spec.yaml

body:
  version: 1
  kind: app
  metadata:
    name: example-app
    title: Example App
    summary: Example App
    description: Creating a new app from CLI
    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:
    - id: existing_block_spec_id_1
      release:
        version: 1.0.0
    - id: existing_block_spec_id_2
      release:
        version: 1.0.0
featured: true
scope: shared
tenants:
  - tenant1
  - tenant2

To create the app spec, use the following command. Similar to blocks, if we have variable expression in our yaml file, we can utilize the defined parameters by including the path to app_params.yaml file.

peak apps specs create path/to/create_app_spec.yaml -v path/to/app_params.yaml

Updating App Spec Metadata

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

# app_spec_metadata.yaml

body:
  metadata:
    name: updated-app
    title: Updated App
    summary: Updated APP
    description: Updating app spec 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 apps specs update-metadata <spec_id> path/to/update_app_spec_metadata.yaml

Creating a new App Spec Release

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

# app_spec_release.yaml

body:
  release:
    version: 2.0.0
    notes: This is a new release
  config:
    - id: existing_block_spec_id_1
      release:
        version: 2.0.0
    - id: existing_block_spec_id_2
      release:
        version: 2.0.0

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

peak apps specs create-release <spec_id> path/to/create_app_spec_release.yaml

App Deployments

Creating a new App Deployment

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

# app_deployment.yaml

body:
  metadata:
    name: app-deployment
    title: App Deployment
    summary: App Deployment
    description: Creating a new app deployment
    descriptionContentType: text/markdown
    imageUrl: https://my-block-pics.com/image-0.jpg
    tags:
      - name: CLI
  parameters:
    block-1:
      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
    block-2:
      build:
        watcher_user: "xyz@456.com"
        use_cache: false
        runtime_exceeded: 50
      run:
        agg_type: "MAX"
        num_iterations: 10
        email_notifications: false
        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 app deployment:

peak apps deployments create path/to/create_app_deployment.yaml

Creating a new App Deployment Revision

We can create a app deployment revision by providing payload containing parameters, revision and release info.

# app_deployment_revision.yaml

body:
  parameters:
    block-1:
      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
    block-2:
      build:
        watcher_user: "xyz@456.com"
        use_cache: false
        runtime_exceeded: 50
      run:
        agg_type: "MAX"
        num_iterations: 10
        email_notifications: false
        file_names:
          - input.csv
          - output.csv
  revision:
    notes: This is the initial revision
  release:
    version: 2.0.0

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

peak apps deployments create path/to/create_app_deployment_revision.yaml

Updating App Deployment Metadata

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

# app_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 app deployment metadata:

peak apps deployments update-metadata <deployment_id> path/to/update_app_deployment_metadata.yaml