[Yandex Cloud documentation](../../index.md) > [Yandex BareMetal](../index.md) > [Step-by-step guides](index.md) > Servers > Uploading a custom OS image

# Uploading a custom OS image

You can add a [custom OS or software product image](../concepts/images.md#user-images) to install it on your server on your own. To proceed, first upload your image file to the Yandex Object Storage [bucket](../../storage/concepts/bucket.md).

## Upload the image file to Object Storage {#upload-file}

{% note alert %}

The maximum size of the image file you can upload to Object Storage is 50 GB.

{% endnote %}

[Upload](image-upload.md#upload-file) the ISO image to [Yandex Object Storage](../../storage/index.md) and get a link to the uploaded object:

1. Create an Object Storage bucket:

    {% note info %}

    To create a [bucket](../../storage/concepts/bucket.md), you need the _minimum_ `storage.editor` [role](../../storage/security/index.md#storage-editor) for the [folder](../../resource-manager/concepts/resources-hierarchy.md#folder).

    {% endnote %}

    {% list tabs group=instructions %}

    - Management console {#console}

      1. In the [management console](https://console.yandex.cloud), select the folder where you want to create a bucket.
      1. Navigate to **Object Storage**.
      1. At the top right, click **Create bucket**.
      1. On the `create bucket` page:

          1. Specify a bucket name that meets [these naming conventions](../../storage/concepts/bucket.md#naming).
          1. Set a bucket size limit or enable **No limit**, if required.
          1. Leave all other parameters as they are and click **Create bucket**.

    - Yandex Cloud CLI {#cli}

      If you do not have the Yandex Cloud CLI yet, [install and initialize it](../../cli/quickstart.md#install).

      The folder used by default is the one specified when [creating](../../cli/operations/profile/profile-create.md) the CLI profile. To change the default folder, use the `yc config set folder-id <folder_ID>` command. You can also specify a different folder for any command using `--folder-name` or `--folder-id`. If you access a resource by its name, the search will be limited to the default folder. If you access a resource by its ID, the search will be global, i.e., through all folders based on access permissions.

      1. Create a bucket in the default folder:

          ```bash
          yc storage bucket create --name <bucket_name>
          ```

          Where `--name` is the name of the bucket. This is a required setting. For more information, see [Bucket naming rules](../../storage/concepts/bucket.md#naming).

          Result:

          ```text
          name: <bucket_name>
          folder_id: b1gt6g8ht345********
          anonymous_access_flags: {}
          default_storage_class: STANDARD
          versioning: VERSIONING_DISABLED
          created_at: "2025-08-06T07:29:40.418079Z"
          resource_id: e3e9neva43dl********
          ```

          For more information about the `yc storage bucket create` command, see the [Yandex Cloud CLI reference](../../cli/cli-ref/storage/cli-ref/bucket/create.md).

    {% endlist %}

1. Upload the downloaded image file to the created bucket.

    {% list tabs group=instructions %}

    - Management console {#console}

      {% note info %}

      You can upload objects of up to 5 GB via the management console (see [Object Storage quotas and limits](../../storage/concepts/limits.md)). To upload larger objects, use other [tools](../../storage/tools/index.md).

      {% endnote %}

      1. In the [management console](https://console.yandex.cloud), navigate to **Object Storage** and then to the bucket you want to upload the image to.
      1. In the left-hand panel, click ![image](../../_assets/console-icons/folder-tree.svg) **Objects** and then ![arrow-up-from-line](../../_assets/console-icons/arrow-up-from-line.svg) **Upload** in the top-right corner.
      1. In the window that opens, select the image file and click **Open**.
      1. In the object upload window, click **Upload** and wait for the image to upload.
      1. Refresh the page.

    - Yandex Cloud CLI {#cli}

      1. Run this command:

          ```bash
          yc storage s3api put-object \
            --body <local_file_path> \
            --bucket <bucket_name> \
            --key <object_path>
          ```

          Where:

          * `--body`: Path to the file you need to upload to the bucket, e.g., `./ubuntu.iso`.
          * `--bucket`: Name of your bucket.
          * `--key`: [Key](../../storage/concepts/object.md#key) by which to store the object in the bucket, e.g., `Ubuntu-2404.iso`.

          Result:

          ```text
          etag: '"87740887a5159e2685500c02********"'
          request_id: 300dceee********
          ```
      For more information about the `yc storage s3api put-object` command, see the [Yandex Cloud CLI reference](../../cli/cli-ref/storage/cli-ref/s3api/put-object.md).

    {% endlist %}

1. Get a link to the image uploaded to the bucket:

    {% list tabs group=instructions %}

    - Management console {#console}

      1. In the [management console](https://console.yandex.cloud), select a folder.
      1. Navigate to **Object Storage** and select the bucket.
      1. Click the name of the object with the uploaded ISO image.
      1. In the top-right corner, click ![link](../../_assets/storage/link.svg) **Get link**.
      1. Click **Get link**.
      1. Copy the link.

    {% endlist %}

## Creating an image in BareMetal {#create-image}

Create a new image using the link you got in Object Storage:

{% list tabs group=instructions %}

- Management console {#console}

  1. In the [management console](https://console.yandex.cloud), select a folder where you want to create your image.
  1. Navigate to **BareMetal**.
  1. In the left-hand panel, select ![icon](../../_assets/console-icons/layers.svg) **Boot images**.
  1. Click **Upload image**.
  1. Specify the image name. The naming requirements are as follows:

       * Length: between 3 and 63 characters.
       * It can only contain lowercase Latin letters, numbers, and hyphens.
       * It must start with a letter and cannot end with a hyphen.

  1. Optionally, provide a description for the image.
  1. Paste the link to your image file from Object Storage.
  1. Click **Upload**.

- CLI {#cli}

   If you do not have the Yandex Cloud CLI yet, [install and initialize it](../../cli/quickstart.md#install).

   The folder used by default is the one specified when [creating](../../cli/operations/profile/profile-create.md) the CLI profile. To change the default folder, use the `yc config set folder-id <folder_ID>` command. You can also specify a different folder for any command using `--folder-name` or `--folder-id`. If you access a resource by its name, the search will be limited to the default folder. If you access a resource by its ID, the search will be global, i.e., through all folders based on access permissions.

   1. View the image download command description:

      ```bash
      yc baremetal boot-image create --help
      ```

   1. Download the image:

      ```bash
      yc baremetal boot-image create \
        --name demo-boot-image \
        --description "Boot image for BareMetal" \
        --uri "<image_link>" \
        --labels <label_key>=<label_value>
      ```

      Where:
      * `--name`: Image name. The naming requirements are as follows:
        
        * Length: between 3 and 63 characters.
        * It can only contain lowercase Latin letters, numbers, and hyphens.
        * It must start with a letter and cannot end with a hyphen.

      * `--description`: Image description. This is an optional setting.
      * `--uri`: Image link you got in Object Storage.
      * `--labels`: Image labels. This is an optional setting.

- API {#api}

  To create an image in BareMetal, use the [create](../api-ref/Image/create.md) REST API method for the [Image](../api-ref/Image/index.md) resource or the [ImageService/Create](../api-ref/grpc/Image/create.md) gRPC API call.
  
  Run this query:
  
  ```bash
  curl -X POST \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer <IAM_token>" \
    -d '{
         "folderId": "b1g07hj5r6i4********",
         "name": "baremetal-ubuntu",
         "description": "New OS Baremetal Image",
         "uri": "https://storage.yandexcloud.net/bm-test-backet/new-server-amd64.iso",
         "labels": {
           "key": "ubuntu"
         }
        }' \
    "https://baremetal.api.cloud.yandex.net/baremetal/v1alpha/images"
  ```
  
  Where:
  
  * `<IAM_token>`: IAM token used for authentication.
  * `folderId`: Folder ID.
  * `name`: Image name. Follow these naming requirements:
  
    * Length: between 3 and 63 characters.
    * It can only contain lowercase Latin letters, numbers, and hyphens.
    * It must start with a letter and cannot end with a hyphen.
  
  * `description`: Image description. This is an optional parameter.
  * `uri`: Image link you got in Object Storage.
  * `labels`: Image labels. This is an optional parameter.
    
  Result:
  
  ```bash
  {
  "done": false,
  "metadata": {
    "@type": "type.googleapis.com/yandex.cloud.baremetal.v1alpha.CreateImageMetadata",
    "imageId": "ly5kr5tjsple********"
  },
  "id": "ly5iwrc2uvuf********",
  "description": "User image create",
  "createdAt": "2025-12-07T20:31:52.845955Z",
  "createdBy": "ajeb9l33h6mu********",
  "modifiedAt": "2025-12-07T20:31:52.845955Z"
  }
  ```
  
    Follow the status of the operation by the `done` field.

{% endlist %}

## Deleting the image from Object Storage {#delete-image}

Once your image is successfully created, you can [delete the source image file](../../storage/operations/objects/delete.md) from Object Storage. You can also [delete the bucket](../../storage/operations/buckets/delete.md) if it contains no objects.