Creating Apps and Blocks via SDK

To initiate the creation of Apps and Blocks using the SDK, the first step involves instantiating the app_client and block_client.

For detailed guidance on Press Apps and Blocks, refer to the Reference Documentation and practical usage examples.

API Documentation is linked with every function in the Reference Documentation which would help in understanding the schema of the payload.

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 code repository, we can package the required files for image creation into a zip archive known as an Artifact.

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

Providing Instance Type and Storage to Workflow Block Spec

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

"resources": {
    "instanceTypeId": 23,
    "storage": "20GB"
}

A list of all available instances along with their corresponding instanceTypeId can be obtained using the list_resources function.

Adding the resources section is optional. If we don’t specify it for a particular step, the default values will be used. We can retrieve the default values by using get_default_resources function.

Providing Image Details for Block Specs

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

Using imageRef: Multiple image configurations can be included in block config and referenced 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: Image configuration can be directly provided within 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: Existing image versions can be utilized in workflow steps and webapps. The block’s scope should be private when 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

A block spec can be created by using Block create_spec function.

Consider the following example:

workflow_block_spec_body = {
    "version": "1",
    "kind": "workflow",
    "metadata": {
        "name": "workflow-block-shared",
        "title": "Workflow Block",
        "summary": "Creating a new workflow block spec.",
        "description": "Creating a new workflow block spec from SDK.",
        "descriptionContentType": "text/plain",
        "imageUrl": "https://my-block-pics.com/image-0.jpg",
        "tags": [
            {
                "name": "sdk",
            },
        ],
    },
    "release": {
        "version": "1.0.0",
        "notes": "This is the original release",
    },
    "config": {
        "triggers": [],
        "steps": {
            "step-1": {
                "type": "standard",
                "image": {
                    "context": ".",
                    "dockerfile": "Dockerfile",
                    "version": "0.0.1",
                },
                "resources": {
                    "instanceTypeId": 21,
                    "storage": "10GB",
                },
                "command": "python main.py",
            },
        },
    },
}

workflow_block_spec = block_client.create_spec(
    body=workflow_block_spec_body,
    artifact={"path": "../peak", "ignore_files": [".dockerignore"]},
    featured=True,
    scope="shared",
    tenants=["tenant1", "tenant2"],
)

The response includes the id of the newly generated spec, which is useful for creating apps or new block spec releases.

{
    "id": "0bddb4c6-40c5-45c3-b477-fceb2c051609"
}

More examples for creating the block spec can be found here.

Creating a new Block Spec Release

To modify the configuration of an existing block spec, a new block spec release needs to be generated. This can be achieved using the create_spec_release function.

body = {
    "config": {
        "triggers": [],
        "images": {
            "example-image": {
                "buildArguments": {
                    "CHUNK_SIZE": "1000",
                },
                "context": ".",
                "dockerfile": "Dockerfile",
                "secrets": ["SECRET_1"],
                "useCache": False,
                "version": "0.0.1",
            },
        },
        "steps": {
            "step-1": {
                "type": "standard",
                "imageRef": "example-image",
                "resources": {
                    "instanceTypeId": 21,
                    "storage": "10GB",
                },
                "command": "python main.py",
            },
        },
    },
    "release": {
        "version": "2.0.0",
        "notes": "This is a revised release",
    },
}


new_spec_release = block_client.create_spec_release(
    spec_id="0bddb4c6-40c5-45c3-b477-fceb2c051609",
    body=body,
    artifact={"path": "../peak", "ignore_files": [".dockerignore"]},
)

The response provides the id and release version of the newly generated spec release.

{
    "id": "0bddb4c6-40c5-45c3-b477-fceb2c051609",
    "release": {
        "version": "2.0.0"
    }
}

Block Deployments

Creating a new Block Deployment

The blocks can be deployed using create_deployment function.

Consider the following example, where we are creating a new block deployment from the block spec release which we created in the previous step.

body = {
    "metadata": {
        "description": "Creating a new workflow block deployment.",
        "descriptionContentType": "text/plain",
        "imageUrl": "https://my-block-pics.com/image-0.jpg",
        "name": "new-deployment",
        "summary": "Creating new deployment.",
        "tags": [
            {
                "name": "sdk",
            },
        ],
        "title": "New Deployment",
    },
    "revision": {
        "notes": "This is the initial revision",
    },
    "spec": {
        "id": "0bddb4c6-40c5-45c3-b477-fceb2c051609",
        "release": {
            "version": "1.0.0",
        },
    },
}

workflow_block_deployment = block_client.create_deployment(body)

It returns the id of the newly created block deployment.

{
    "id": "0bddb4c6-40c5-45c3-b477-fceb2c051609"
}

App Specs

Creating an App Spec

An app can be considered as a collection of blocks. We can create an app spec by using existing block specs or block spec releases. It can be generated using the create_spec function.

It’s worth noting that the creation of an app spec with a shared scope is possible only when all the associated blocks are also shared with those tenants.

Consider the following example, where we are creating an app spec using existing block specs.

spec_body = {
    "version": "1",
    "kind": "app",
    "metadata": {
        "name": "sdk",
        "title": "New App Spec",
        "summary": "Create new app spec",
        "description": "Creating app spec from SDK",
        "descriptionContentType": "text/plain",
        "imageUrl": "https://my-spec-pics.com/image-1.jpg",
        "tags": [
            {
                "name": "sdk",
            },
        ],
    },
    "release": {
        "version": "1.0.0",
        "notes": "This is the original release",
    },
    "config": [
        {
            "id": "0bddb4c6-40c5-45c3-b477-fceb2c051609",
            "release": {
                "version": "1.0.0",
            },
        },
        {
            "id": "0bddb4c6-40c5-45c3-b477-fceb2c051609",
            "release": {
                "version": "2.0.0",
            },
        },
    ],
}


created_app_spec = app_client.create_spec(
    body=spec_body,
    featured=True,
    scope="shared",
    tenants=["tenant1", "tenant2"],
)

The response includes the id of the newly generated app spec.

{
    "id": "a3e77006-86f3-4829-8c43-f21ad462dbbd"
}

Creating a new App Spec Release

Similar to blocks, a new app spec release can be generated to modify the spec configuration. We can create a new app spec release by using create_spec_release function.

Consider the following example, where we are creating a new app spec release from the app spec which we created in the previous step.

body = {
    "config": [
        {
            "id": "0bddb4c6-40c5-45c3-b477-fceb2c051609",
            "release": {
                "version": "1.0.0",
            },
        },
    ],
    "release": {
        "version": "2.0.0",
        "notes": "This is a revised release",
    },
}


new_spec_release = app_client.create_spec_release(
    spec_id="a3e77006-86f3-4829-8c43-f21ad462dbbd",
    body=body,
)

The response provides the id and release version of the newly generated spec release.

{
    "id": "a3e77006-86f3-4829-8c43-f21ad462dbbd",
    "release": {
        "version": "2.0.0"
    }
}

App Deployments

Creating a new App Deployment

Deploying an app spec leads to deployment of all constituent blocks. We can create a new app deployment by using create_deployment function.

deployment = app_client.create_deployment(
    body={
        "metadata": {
            "description": "Creating a new deployment.",
            "descriptionContentType": "text/plain",
            "imageUrl": "https://my-spec-pics.com/image-1.jpg",
            "name": "new-deployment",
            "summary": "This creates a new deployment",
            "tags": [
                {
                    "name": "sdk",
                },
            ],
            "title": "New Deployment",
        },
        "revision": {
            "notes": "This is the initial revision",
        },
        "spec": {
            "id": "a3e77006-86f3-4829-8c43-f21ad462dbbd",
            "release": {
                "version": "1.0.0",
            },
        },
    },
)

The response includes the id of the newly created app deployment.

{
    "id": "e04e308d-98dc-4443-bb02-c4ef990a3fdc"
}