Images

Import the `image` resource module and instantiate the client

[ ]:

from collections.abc import Iterator
from typing import Any

from peak.resources import images

image_client: images.Image = images.get_client()

Possible field values

Image type

The type of the image. The following types are supported: workflow, workspace-r, workspace-python, webapp and api.

Status

The status of the image or the image version. The following statuses are supported: not-ready, ready, in-use, deleting and delete-failed.

Build status or Last build status

The build status of the image or the image version. The following statuses are supported: building, failed, success, stopping and stopped.

List all existing `image`(s) and iterate over them

[ ]:

images_list_iterator: Iterator[dict[str, Any]] = image_client.list_images(
    name="test",
    status=["in-use"],
)

images_list_iterated: dict[str, Any] = next(images_list_iterator)

"""
The list of images will be returned in the following format:

{
  "imageCount": 0,
  "pageSize": 25,
  "pageNumber": 1,
  "pageCount": 1,
  "images": [
    {
      "id": 101,
      "name": "awesome-image",
      "type": "workflow",
      "scope": "custom",
      "latestVersion": {
        "id": 201,
        "version": "0.0.1-python3.12",
        "description": "awesome-image description",
        "status": "not-ready",
        "lastBuildStatus": "building",
        "createdAt": "2023-06-01T18:00:00.000Z",
        "createdBy": "someone@peak.ai",
        "updatedAt": "2023-06-01T18:00:00.000Z",
        "updatedBy": "someone@peak.ai",
        "pullUrl": "110011001100.dkr.ecr.eu-west-1.amazonaws.com/default-images-latest:jupyter-base",
        "size": 10,
        "tags": [
          {
            "name": "hello",
            "color": "#000000"
          }
        ],
        "buildDetails": {
          "source": "github"
        }
      }
    }
  ]
}
"""

List all existing `image version`(s) and iterate over them

[ ]:

image_versions_list_iterator: Iterator[dict[str, Any]] = image_client.list_image_versions(
    image_id=9999,
    version="test",
    status=["in-use"],
    tags=["dnd"],
)

image_versions_iterated: dict[str, Any] = next(image_versions_list_iterator)

"""
The list of image versions will be returned in the following format:

{
  "versionCount": 0,
  "pageSize": 25,
  "pageNumber": 1,
  "pageCount": 1,
  "versions": [
    {
      "id": 201,
      "version": "0.0.1-python3.12",
      "description": "awesome-image description",
      "status": "not-ready",
      "lastBuildStatus": "building",
      "createdAt": "2023-06-01T18:00:00.000Z",
      "createdBy": "someone@peak.ai",
      "updatedAt": "2023-06-01T18:00:00.000Z",
      "updatedBy": "someone@peak.ai",
      "pullUrl": "110011001100.dkr.ecr.eu-west-1.amazonaws.com/default-images-latest:jupyter-base",
      "size": 10,
      "tags": [
        {
          "name": "hello",
          "color": "#000000"
        }
      ],
      "isLatest": false,
      "buildDetails": {
        "source": "github"
      }
    }
  ]
}
"""

Create a new `image` resource

[ ]:

# Build details is optional and would be set to following if not provided.
default_build_details = {
    "source": "upload",
}

# Within build details, source is optional and would be set to 'upload' if not provided.

# Creating an image with upload source.
upload_body = {
    "version": "0.0.1",
    "name": "image-sdk-101",
    "description": "Hello from SDK",
    "type": "workflow",
}

artifact = {
    "path": "./image",
}

upload_image = image_client.create_image(
    body=upload_body,
    artifact=artifact,
)

# Creating an image with dockerfile source
dockerfile_body = {
    "version": "0.0.1",
    "name": "image-sdk-101",
    "description": "Hello from SDK",
    "type": "workflow",
    "buildDetails": {
        "source": "dockerfile",
        "useCache": False,
        "buildArguments": [
            {
                "name": "HELLO",
                "value": "world",
            },
        ],
        "dockerfile": "FROM nginx",
    },
}

dockerfile_image = image_client.create_image(
    body=dockerfile_body,
)

# Creating image with github source
github_body = {
    "version": "0.0.1",
    "name": "image-sdk-101",
    "description": "Hello from SDK",
    "type": "workflow",
    "buildDetails": {
        "source": "github",
        "useCache": True,
        "buildArguments": [
            {
                "name": "HELLO",
                "value": "world",
            },
        ],
        "context": ".",
        "branch": "main",
        "repository": "https://github.com/username/repository",
        "token": "token-name",
    },
}

github_image = image_client.create_image(
    body=github_body,
)

Create a new `image version` resource

[ ]:

# Creating a version with upload source. Build details and source are optional. If not provided, source would be set to upload.
upload_body = {
    "version": "0.0.1",
    "description": "Hello from SDK",
    "buildDetails": {
        "source": "upload",
        "useCache": False,
        "buildArguments": [
            {
                "name": "HELLO",
                "value": "world",
            },
        ],
        "context": ".",
    },
}

artifact = {
    "path": "./image",
}

upload_version = image_client.create_version(
    image_id=upload_image["imageId"],
    body=upload_body,
    artifact=artifact,
)

# Creating a version with dockerfile source
dockerfile_body = {
    "version": "0.0.1",
    "description": "Hello from SDK",
    "buildDetails": {
        "source": "dockerfile",
        "useCache": False,
        "buildArguments": [
            {
                "name": "HELLO",
                "value": "world",
            },
        ],
        "dockerfile": "FROM nginx",
    },
}

dockerfile_version = image_client.create_version(
    image_id=dockerfile_image["imageId"],
    body=dockerfile_body,
)

# Creating version with github source
github_body = {
    "version": "0.0.1",
    "description": "Hello from SDK",
    "buildDetails": {
        "source": "github",
        "useCache": True,
        "buildArguments": [
            {
                "name": "HELLO",
                "value": "world",
            },
        ],
        "context": ".",
        "branch": "main",
        "repository": "https://github.com/username/repository",
        "token": "token-name",
    },
}

github_version = image_client.create_version(
    image_id=github_image["imageId"],
    body=github_body,
)

Create or update a `image version`

[ ]:

# Create a image or version. Build details and source are optional. If not provided, source would be set to upload.
upload_body = {
    "version": "0.0.1",
    "name": "image-sdk-101",
    "description": "Hello from SDK",
    "type": "workflow",
    "buildDetails": {
        "useCache": False,
        "buildArguments": [
            {
                "name": "HELLO",
                "value": "world",
            },
        ],
        "context": ".",
    },
}

artifact = {
    "path": "./image",
}

upload_image = image_client.create_or_update_image_version(
    body=upload_body,
    artifact=artifact,
)

# Update an existing image version. Build details and source are optional. If not provided, the build details and source of existing version would be used.
dockerfile_body = {
    "version": "0.0.1",
    "name": "image-sdk-101",
    "description": "Hello from SDK",
    "type": "workflow",
    "buildDetails": {
        "source": "dockerfile",
        "useCache": False,
        "buildArguments": [
            {
                "name": "HELLO",
                "value": "world",
            },
        ],
        "dockerfile": "FROM nginx",
    },
}

dockerfile_image = image_client.create_or_update_image_version(
    body=dockerfile_body,
)

Describe an existing `image` resource

[ ]:

image = image_client.describe_image(image_id=101)

"""
The image will be a dictionary containing information about the image and its latest version.
The dictionary will have the following structure:

{
  "id": 101,
  "name": "awesome-image",
  "type": "workflow",
  "scope": "custom",
  "createdAt": "2024-06-01T18:00:00.000Z",
  "createdBy": "someone@peak.ai",
  "latestVersion": {
    "id": 201,
    "version": "0.0.1-python3.12",
    "description": "awesome-image description",
    "status": "not-ready",
    "lastBuildStatus": "building",
    "createdAt": "2023-06-01T18:00:00.000Z",
    "createdBy": "someone@peak.ai",
    "updatedAt": "2023-06-01T18:00:00.000Z",
    "updatedBy": "someone@peak.ai",
    "pullUrl": "110011001100.dkr.ecr.eu-west-1.amazonaws.com/default-images-latest:jupyter-base",
    "size": 10,
    "tags": [
      {
        "name": "hello",
        "color": "#000000"
      }
    ],
    "lastBuildAt": "2023-06-01T18:00:00.000Z",
    "buildDetails": {
      "source": "github",
      "buildArguments": [
        {
          "name": "EXAMPLE_ENV_NAME",
          "value": "example-env-value"
        }
      ],
      "secrets": [
        "EXAMPLE_CREDENTIAL"
      ],
      "builtFrom": 1000,
      "useCache": true,
      "clonedFrom": 1,
      "dockerfile": "FROM nginx",
      "branch": "main",
      "repository": "https://github.com/user/repo",
      "token": "example-token",
      "dockerfilePath": "images/v1/Dockerfile",
      "context": "/",
      "githubCommitUrl": "https://github.com/org/repo/blob/commit-id/Dockerfile"
    }
  }
}

"""

Describe an existing `version` resource

[ ]:

image_version = image_client.describe_version(image_id=101, version_id=201)

"""
The image_version will be a dictionary and will look like the following:

{
  "imageName": "awesome-image",
  "imageType": "Workflow",
  "id": 201,
  "version": "0.0.1-python3.12",
  "description": "This is an awesome image",
  "status": "not-ready",
  "createdAt": "2020-01-01T18:00:00.000Z",
  "createdBy": "someone@peak.ai",
  "updatedAt": "2020-01-01T18:00:00.000Z",
  "updatedBy": "someone@peak.ai",
  "pullUrl": "110011001100.dkr.ecr.eu-west-1.amazonaws.com/default-images-latest:jupyter-base",
  "lastBuildStatus": "building",
  "lastBuildAt": "2020-01-01T18:00:00.000Z",
  "buildDetails": {
    "source": "github",
    "githubCommitUrl": "https://github.com/org/repo/blob/commit-id/Dockerfile",
    "buildArguments": [
      {
        "name": "EXAMPLE_ENV_NAME",
        "value": "example-env-value"
      }
    ],
    "secrets": [
      "EXAMPLE_CREDENTIAL"
    ],
    "useCache": true,
    "branch": "main",
    "repository": "https://github.com/user/repo",
    "token": "example-token",
    "dockerfilePath": "images/v1/Dockerfile",
    "context": "/"
  },
  "tags": []
}

"""

Update an existing `image version` resource

[ ]:

# Update a version with upload source. Build details and source are optional. If not provided, the build details and source of existing version would be used.
updated_upload_body = {
    "description": "Hello from SDK",
    "buildDetails": {
        "source": "upload",
        "useCache": False,
        "buildArguments": [
            {
                "name": "HELLO",
                "value": "world",
            },
        ],
        "context": ".",
    },
}

artifact = {
    "path": "./image",
}

updated_upload_version = image_client.update_version(
    image_id=upload_image["imageId"],
    version_id=upload_version["versionId"],
    body=updated_upload_body,
    artifact=artifact,
)

# Update a version with dockerfile source
updated_dockerfile_body = {
    "description": "Hello from SDK",
    "buildDetails": {
        "source": "dockerfile",
        "useCache": False,
        "buildArguments": [
            {
                "name": "HELLO",
                "value": "world",
            },
        ],
        "dockerfile": "FROM nginx",
    },
}

updated_dockerfile_version = image_client.update_version(
    image_id=dockerfile_image["imageId"],
    version_id=dockerfile_version["versionId"],
    body=updated_dockerfile_body,
)

# Update a version with github source
updated_github_body = {
    "description": "Hello from SDK",
    "buildDetails": {
        "source": "github",
        "useCache": True,
        "buildArguments": [
            {
                "name": "HELLO",
                "value": "world",
            },
        ],
        "context": ".",
        "branch": "main",
        "repository": "https://github.com/username/repository",
        "token": "token-name",
    },
}

updated_github_version = image_client.update_version(
    image_id=github_image["imageId"],
    version_id=github_version["versionId"],
    body=updated_github_body,
)

List all builds in an existing `image` resource and iterate over them

[ ]:

image_builds_iterator: Iterator[dict[str, Any]] = image_client.list_image_builds(image_id=int(upload_image["imageId"]))
image_builds_iterated: dict[str, Any] = next(image_builds_iterator)

"""
The list of image builds will be returned in the following format:

{
  "buildCount": 1,
  "builds": [
    {
      "buildId": 1,
      "finishedAt": "2023-06-01T18:00:00.000Z",
      "startedAt": "2023-06-01T18:00:00.000Z",
      "status": "building",
      "useCache": true,
      "version": "0.0.1-python3.12",
      "versionId": 1
    }
  ],
  "pageCount": 1,
  "pageNumber": 1,
  "pageSize": 25
}
"""

Get logs for a specific build in an existing `image` resource

[ ]:

image_build_logs = image_client.get_build_logs(image_id=1, build_id=1)

# To get next set of logs, pass the nextToken returned in the response of previous function call
next_set_of_image_build_logs = image_client.get_build_logs(
    image_id=1,
    build_id=1,
    next_token=image_build_logs["nextToken"],
)

# To download the logs locally the `save` parameter can be used along with `file_name`
next_set_of_image_build_logs = image_client.get_build_logs(
    image_id=1,
    build_id=1,
    save=True,
    file_name="image_build_logs.log",
)

"""
The image_build_logs will be returned in the following format:

{
  "buildStatus": "building",
  "finishTime": "2023-06-01T18:00:00.000Z",
  "logs": [
    {
      "ingestionTime": "2023-06-01T18:00:00.000Z",
      "message": "Building the Docker image...",
      "timestamp": "2023-06-01T18:00:00.000Z"
    }
  ],
  "nextToken": "f/37241814580157116960215105647056337845181039459911335941/s",
  "startTime": "2023-06-01T18:00:00.000Z"
}
"""

Delete an existing `image version` resource

[ ]:

image_client.delete_version(image_id=int(upload_image["imageId"]), version_id=int(upload_image["versionId"]))

Delete multiple existing `image version` resources

[ ]:

image_client.delete_versions(
    image_id=int(upload_image["imageId"]),
    version_ids=[
        int(upload_image["versionId"]),
        int(upload_version["versionId"]),
    ],
)

Note: All the versions will first go into deleting state and will then be asynchronously deleted. If the deletion of any version fails because of some issue, it will go into delete_failed state.

Delete an existing `image` resource

[ ]:

image_client.delete_image(image_id=int(upload_image["imageId"]))

Note: All the versions associated with the given image will first go into deleting state and will then be asynchronously deleted. If the deletion of any version fails because of some issue, it will go into delete_failed state.

Images

Import the image resource module and instantiate the client

Possible field values

Image type

Status

Build status or Last build status

List all existing image(s) and iterate over them

List all existing image version(s) and iterate over them

Create a new image resource

Create a new image version resource

Create or update a image version

Describe an existing image resource

Describe an existing version resource

Update an existing image version resource

List all builds in an existing image resource and iterate over them

Get logs for a specific build in an existing image resource

Delete an existing image version resource

Delete multiple existing image version resources

Delete an existing image resource