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 Parameters in App and Block Creation

While creating apps or blocks, we can define parameters in a separate file and then use them by 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.

# block_params.yaml

git_token: "random_git_token"
npm_token: "random_npm_token"

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 to Workflow Block Spec

When defining a workflow step, 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 workflows list-resources

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

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

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

body:
  version: 1
  kind: workflow
  metadata:
    name: workflow-block
    title: Workflow Block
    summary: Workflow Block
    description: Creating a new workflow block spec
    descriptionContentType: text/plain
    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:
      - {}
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.j2 file to utilize the defined parameters:

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

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.j2 -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.j2 -v path/to/block_params.yaml.j2 -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.j2

body:
  metadata:
    name: updated-workflow-block
    title: Updated Workflow Block
    summary: Updated Workflow Block
    description: Updating workflow block metadata
    descriptionContentType: text/plain
    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/block_spec_metadata.yaml.j2

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

body:
  release:
    version: 2.0.0
    notes: This is a new release
  config:
    steps:
      new_step:
        command: echo 1
        type: standard
        imageDetails:
          id: 1
          versionId: 1
    triggers:
      - {}
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/block_spec_release.yaml.j2

Block Deployments

Creating a new Block Deployment

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

# block_deployment.yaml.j2

body:
  metadata:
    name: workflow-block-deployment
    title: Workflow Block Deployment
    summary: Workflow Block Deployment
    description: Creating a new workflow block deployment
    descriptionContentType: text/plain
    imageUrl: https://my-block-pics.com/image-0.jpg
    tags:
      - name: CLI
  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/block_deployment.yaml.j2

Updating Block Deployment Metadata

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

# block_deployment_metadata.yaml.j2

body:
  name: update-block-deployment
  title: Update Block Deployment
  summary: Update Block Deployment
  description: Updating block deployment metadata
  descriptionContentType: text/plain
  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/block_deployment_metadata.yaml.j2

App Specs

Creating an App Spec

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

# app_spec.yaml.j2

body:
  version: 1
  kind: app
  metadata:
    name: example_app
    title: Example App
    summary: Example App
    description: Creating a new app from CLI
    descriptionContentType: text/plain
    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.j2 file.

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

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

body:
  metadata:
    name: updated-app
    title: Updated App
    summary: Updated APP
    description: Updating app spec metadata
    descriptionContentType: text/plain
    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/app_spec_metadata.yaml.j2

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

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/app_spec_release.yaml.j2

App Deployments

Creating a new App Deployment

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

# app_deployment.yaml.j2

body:
  metadata:
    name: app-deployment
    title: App Deployment
    summary: App Deployment
    description: Creating a new app deployment
    descriptionContentType: text/plain
    imageUrl: https://my-block-pics.com/image-0.jpg
    tags:
      - name: CLI
  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/app_deployment.yaml.j2

Updating App Deployment Metadata

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

# app_deployment_metadata.yaml.j2

body:
  name: update-block-deployment
  title: Update Block Deployment
  summary: Update Block Deployment
  description: Updating block deployment metadata
  descriptionContentType: text/plain
  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/app_deployment_metadata.yaml.j2

Using Apps and Blocks via CLI