Images

Creating an image

We can create an image by providing payload containing its configuration. If version is not provided in the request body, the version will be set to 0.0.1.

buildDetails is optional and is set to the following when it is not provided:

{
    "source": "upload"
}

Within buildDetails if source is not provided, it is set to upload by default.

# image_params.yaml

token: my_token
param1: my_parameter1
param2: my_parameter2

# upload_image.yaml

body:
  name: upload-image
  version: 0.0.1-test
  description: Creating a new upload type image
  type: workflow
  buildDetails:
    source: upload
    useCache: false
    buildArguments:
      - name: PARAM1
        value: param1
      - name: PARAM2
        value: param2
    context: .
artifact:
  path: "."
  ignore_files:
    - ".gitignore"
    - ".dockerignore"

# github_image.yaml

body:
  name: github-image
  version: 0.0.1-test
  description: Creating a new github type image
  type: workflow
  buildDetails:
    source: github
    repository: https://example.com
    branch: main
    token: token
    dockerfilePath: Dockerfile
    buildArguments:
      - name: PARAM1
        value: param1
      - name: PARAM2
        value: param2
    useCache: true

# dockerfile_image.yaml

body:
  name: dockerfile-image
  version: "0.0.1-test"
  description: Creating a new dockerfile type image
  type: workflow
  buildDetails:
    source: dockerfile
    useCache: false
    buildArguments:
      - name: PARAM1
        value: param1
      - name: PARAM2
        value: param2
    dockerfile: "FROM nginx"

We can use the following command to create an image:

peak images create path/to/create_image.yaml -v path/to/image_params.yaml

We can create an image directly from the command line by specifying all the required parameters:

peak images create --name example-image --version 0.0.1-test --type workflow --description "Creating a new image" --source github --repository https://example.com --branch main --build-arguments arg1=value1 --build-arguments arg2=value2 --secrets secret_1,secret_2

We can also combine the YAML template and command line arguments, where the command line arguments will take precedence over the YAML file. Create the YAML template file with the following content:

# image.yaml

body:
    name: my-image
    version: 0.0.1-test
    type: workflow
    description: Creating a new image
    buildDetails:
        source: github
        repository: https://example.com
        branch: main
        useCache: true

peak images create path/to/image.yaml --name my-awesome-image

In this case, the final image body will look like:

{
    "name": "my-awesome-image",
    "version": "0.0.1-test",
    "type": "workflow",
    "description": "Creating a new image",
    "buildDetails": {
        "source": "github",
        "repository": "https://example.com",
        "branch": "main",
        "useCache": true
    }
}

Creating an image version

Once an image is created, we can create its subsequent version by providing the image id and payload containing its configuration. If version is not provided in the request body, the version will be automatically incremented.

buildDetails is optional and is set to the following when it is not provided:

{
    "source": "upload"
}

Within buildDetails if source is not provided, it is set to upload by default.

# image_params.yaml

token: my_token
param1: my_parameter1
param2: my_parameter2

# upload_image_version.yaml

body:
  version: 0.0.2-test-upload
  description: Creating a new image version
  buildDetails:
    source: upload
    context: "."
    dockerfilePath: Dockerfile
    buildArguments:
      - name: PARAM1
        value: param1
      - name: PARAM2
        value: param2
    useCache: true
artifact:
  path: "."
  ignore_files:
    - ".gitignore"
    - ".dockerignore"

# github_image_version.yaml

body:
  version: 0.0.2-test-github
  description: Creating a new image version
  buildDetails:
    source: github
    repository: https://example.com
    branch: main
    token: token
    dockerfilePath: Dockerfile
    buildArguments:
      - name: PARAM1
        value: param1
      - name: PARAM2
        value: param2
    useCache: true

# dockerfile_image_version.yaml

body:
  version: 0.0.2-test-dockerfile
  description: Creating a new image version
  buildDetails:
    source: dockerfile
    useCache: false
    buildArguments:
      - name: PARAM1
        value: param1
      - name: PARAM2
        value: param2
    dockerfile: "FROM nginx"

We can use the following command to create an image version:

peak images create-version -v path/to/image_params.yaml <image-id> path/to/create_image_version.yaml

We can create an image version directly from the command line by specifying all the required parameters:

peak images create-version 123 --version 0.0.2-test --description "Creating a new image version" --source github --repository https://example.com --branch main --build-arguments arg1=value1 --build-arguments arg2=value2 --secrets secret_1,secret_2

Similar to creating an image, we can also combine the YAML template and command line options to create the image version, with the command line options taking precedence.

Updating an image version

An image version can be modified if it was not build successfully and is in not-ready state. We can update an image version by providing the image id, version id and payload containing its configuration. buildDetails and source are optional. If not provided, the details from existing version will be used.

# upload_image_version.yaml

body:
  description: Updating the image version
  buildDetails:
    source: upload
    context: "."
    dockerfilePath: Dockerfile
    buildArguments:
      - name: PARAM1
        value: param1
    useCache: true
artifact:
  path: "."
  ignore_files:
    - ".gitignore"
    - ".dockerignore"

# github_image_version.yaml

body:
  description: Updating the image version
  buildDetails:
    source: github
    repository: https://example.com
    branch: main
    token: token
    dockerfilePath: Dockerfile
    buildArguments:
      - name: PARAM1
        value: param1
      - name: PARAM2
        value: param2
    useCache: true

# dockerfile_image_version.yaml

body:
  description: Updating the image version
  buildDetails:
    source: dockerfile
    useCache: false
    buildArguments:
      - name: PARAM1
        value: param1
      - name: PARAM2
        value: param2
    dockerfile: "FROM nginx"

We can use the following command to update an image version:

peak images update-version --image-id -v path/to/image_params.yaml <image-id> --version-id <version-id> path/to/update_version.yaml

We can update an image version directly from the command line by specifying all the required parameters:

peak images update-version --image-id 123 --version-id 456 --description "Updating the image version" --source github --repository https://example.com --branch main --build-arguments arg1=value1 --build-arguments arg2=value2 --secrets secret_1,secret_2

Similar to creating an image, we can also combine the YAML template and command line options to update the version, with the command line options taking precedence.

Using the create-or-update operation

The operation creates a new resource if it doesn’t exist and updates the resource in case it exists. The search is based on resource name and version fields.

Consider the following example for creating a new image version:

# upload_image_version.yaml

body:
  name: test-image
  version: 0.0.1-test-upload
  description: Creating a new image version
  buildDetails:
    source: upload
    context: "."
    dockerfilePath: Dockerfile
    buildArguments:
      - name: PARAM1
        value: param1
      - name: PARAM2
        value: param2
    useCache: true
artifact:
  path: "."
  ignore_files:
    - ".gitignore"
    - ".dockerignore"

We can use the following command to create or update a image version:

peak images create-or-update -v path/to/image_params.yaml path/to/create_or_update_image.yaml

We can create or update a image version directly from the command line by specifying all the required parameters:

peak images create-or-update --name test-image --version 0.0.2-test --description "Creating a new image version" --source github --repository https://example.com --branch main --build-arguments arg1=value1 --build-arguments arg2=value2 --secrets secret_1,secret_2

Similar to creating an image, we can also combine the YAML template and command line options to create the image version, with the command line options taking precedence.

Deleting Images and Versions

At some point you might want to clean up a few images and image versions that you have on your tenant. The CLI provides you with a few options to easily perform the cleanup.

  • If you want to delete a specific version, you can use the delete-version command available in the images resource.

    peak images delete-version --image-id=1 --version-id=1

  • You might have a lot of versions inside an image, that you want to delete. No worries, we have delete-versions command that allows you to delete multiple versions in an image with a single command.

    peak images delete-versions --image-id=1 --version-ids=1,2,3

    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.

  • If none of the versions in an image are needed, and you want to delete the complete image, you can use the delete command in the images resource

    peak images delete 1

    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.

Retrieving Image Build Logs

To obtain build logs for a specific image build, you’ll need to provide the image ID and build ID. There are three possible ways to get the image build logs.

  1. Using Next Token

To fetch build logs, use the following command:

peak images build-logs --image-id <image_id> --build-id <build_id>

This command returns a set of logs along with a nextToken that can be used to fetch subsequent logs. The response looks like following:

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

To retrieve the next set of logs, use the nextToken received in the response as follows:

peak images get-build-logs --image-id <image_id> --build-id <build_id> --next-token <next_token>

  1. Polling the logs

To continuously poll the logs for the image build, you can use the --follow flag. This command will keep polling the logs until the build is completed or all logs are fetched.

peak images get-build-logs --image-id <image_id> --build-id <build_id> --follow

  1. Save the logs locally to a file

Image build logs can also be saved locally to a file using the --save option. You can also pass in a --file-name option which should include the file name and the path to used when saving the logs. If the --file-name option isn’t passed, the logs would be saved to a file named image_build_logs_<image_id>_<build_id>.log.

peak images get-build-logs --image-id <image_id> --build-id <build_id> --save --file-name <file_name>

Note The --save option would take the highest prioroty when both --follow and --save options are passed.