Getting Information About Your OMIs

Using AWS CLI, you can get information about the OMIs you can use to create virtual machines (VMs):

OMIs that you have created.
OMIs that other accounts have shared with you.

Getting Information About Your OMIs Using Cockpit v2

See the Images dashboard.

Getting Information About Your OMIs Using OSC CLI

The ReadImages command lists one or more OUTSCALE machine images (OMIs) you can use.

Request sample: Reading a specific image

$ osc-cli api ReadImages --profile "default" \
    --Filters '{
        "ImageIds": ["ami-12345678"]
      }'

Request sample: Reading Ubuntu and RockyLinux images created by Outscale

$ osc-cli api ReadImages --profile "default" \
    --Filters '{
        "AccountAliases": ["Outscale"],
        "ImageNames": ["Ubuntu*", "RockyLinux*"]
      }'

This command contains the following attributes that you need to specify:

DryRun: (optional) If true, checks whether you have the required permissions to perform the action.
Filters: (optional) One or more filters.
- AccountAliases: (optional) The account aliases of the owners of the OMIs.
- AccountIds: (optional) The account IDs of the owners of the OMIs. By default, all the OMIs for which you have launch permissions are described.
- Architectures: (optional) The architectures of the OMIs (i386 | x86_64).
- BlockDeviceMappingDeleteOnVmDeletion: (optional) Whether the volumes are deleted or not when terminating the VM.
- BlockDeviceMappingDeviceNames: (optional) The device names for the volumes.
- BlockDeviceMappingSnapshotIds: (optional) The IDs of the snapshots used to create the volumes.
- BlockDeviceMappingVolumeSizes: (optional) The sizes of the volumes, in gibibytes (GiB).
- BlockDeviceMappingVolumeTypes: (optional) The types of volumes (standard | gp2 | io1).
- Descriptions: (optional) The descriptions of the OMIs, provided when they were created.
- FileLocations: (optional) The locations of the buckets where the OMI files are stored.
- Hypervisors: (optional) The hypervisor type of the OMI (always xen).
- ImageIds: (optional) The IDs of the OMIs.
- ImageNames: (optional) The names of the OMIs, provided when they were created.
- PermissionsToLaunchAccountIds: (optional) The account IDs which have launch permissions for the OMIs.
- PermissionsToLaunchGlobalPermission: (optional) If true, lists all public OMIs. If false, lists all private OMIs.
- ProductCodeNames: (optional) The names of the product codes associated with the OMI.
- ProductCodes: (optional) The product codes associated with the OMI.
- RootDeviceNames: (optional) The name of the root device. This value must be /dev/sda1.
- RootDeviceTypes: (optional) The types of root device used by the OMIs (bsu or ebs).
- States: (optional) The states of the OMIs (pending | available | failed).
- TagKeys: (optional) The keys of the tags associated with the OMIs.
- TagValues: (optional) The values of the tags associated with the OMIs.
- Tags: (optional) The key/value combination of the tags associated with the OMIs, in the following format: "Filters":{"Tags":["TAGKEY=TAGVALUE"]}.
- VirtualizationTypes: (optional) The virtualization types (always hvm).
NextPageToken: (optional) The token to request the next page of results. Each token refers to a specific page.
ResultsPerPage: (optional) The maximum number of logs returned in a single response (between 1 and 1000, both included). By default, 100.

The ReadImages command returns the following elements:

Images: Information about one or more OMIs.
- AccountAlias: The account alias of the owner of the OMI.
- AccountId: The account ID of the owner of the OMI.
- Architecture: The architecture of the OMI.
- BlockDeviceMappings: One or more block device mappings.
  - Bsu: Information about the BSU volume to create.
    
    DeleteOnVmDeletion: By default or if set to true, the volume is deleted when terminating the VM. If false, the volume is not deleted when terminating the VM.
    
    Iops: The number of I/O operations per second (IOPS). This parameter must be specified only if you create an io1 volume. The maximum number of IOPS allowed for io1 volumes is 13000 with a maximum performance ratio of 300 IOPS per gibibyte.
    
    SnapshotId: The ID of the snapshot used to create the volume.
    
    VolumeSize: The size of the volume, in gibibytes (GiB).
    If you specify a snapshot ID, the volume size must be at least equal to the snapshot size.
    If you specify a snapshot ID but no volume size, the volume is created with a size similar to the snapshot one.
    
    VolumeType: The type of the volume (standard | io1 | gp2). If not specified in the request, a standard volume is created.
    For more information about volume types, see About Volumes > Volume Types and IOPS.
  - DeviceName: The device name for the volume. For a root device, you must use /dev/sda1. For other volumes, you must use /dev/sdX, /dev/sdXX, /dev/xvdX, or /dev/xvdXX (where the first X is a letter between b and z, and the second X is a letter between a and z).
  - VirtualDeviceName: The name of the virtual device (ephemeralN).
- CreationDate: The date and time (UTC) at which the OMI was created.
- Description: The description of the OMI.
- FileLocation: The location from which the OMI files were created.
- ImageId: The ID of the OMI.
- ImageName: The name of the OMI.
- ImageType: The type of the OMI.
- PermissionsToLaunch: Permissions for the resource.
  - AccountIds: One or more account IDs that the permission is associated with.
  - GlobalPermission: A global permission for all accounts.
    (Request) Set this parameter to true to make the resource public (if the parent parameter is Additions) or to make the resource private (if the parent parameter is Removals).
    (Response) If true, the resource is public. If false, the resource is private.
- ProductCodes: The product codes associated with the OMI.
- RootDeviceName: The name of the root device.
- RootDeviceType: The type of root device used by the OMI (always bsu).
- State: The state of the OMI (pending | available | failed).
- StateComment: Information about the change of state.
  - StateCode: The code of the change of state.
  - StateMessage: A message explaining the change of state.
- Tags: One or more tags associated with the OMI.
  - Key: The key of the tag, with a minimum of 1 character.
  - Value: The value of the tag, between 0 and 255 characters.
NextPageToken: The token to request the next page of results. Each token refers to a specific page.
ResponseContext: Information about the context of the response.
- RequestId: The ID of the request.

Result sample: Reading a specific image

{
  "ResponseContext": {
    "RequestId": "0475ca1e-d0c5-441d-712a-da55a4175157"
  },
  "Images": [
    {
      "StateComment": {},
      "State": "available",
      "RootDeviceType": "bsu",
      "RootDeviceName": "/dev/sda1",
      "ProductCodes": [
        "0001"
      ],
      "PermissionsToLaunch": {
        "GlobalPermission": false,
        "AccountIds": []
      },
      "AccountId": "123456789012",
      "Tags": [],
      "Description": "",
      "ImageId": "ami-12345678",
      "BlockDeviceMappings": [
        {
          "DeviceName": "/dev/sda1",
          "Bsu": {
            "VolumeType": "standard",
            "DeleteOnVmDeletion": true,
            "VolumeSize": 50,
            "SnapshotId": "snap-12345678"
          }
        }
      ],
      "ImageType": "machine",
      "CreationDate": "2010-10-01T12:34:56.789Z",
      "FileLocation": "123456789012/create-image-example",
      "Architecture": "x86_64",
      "ImageName": "create-image-example"
    }
  ]
}

Result sample: Reading Ubuntu and RockyLinux images created by Outscale

{
  "ResponseContext": {
    "RequestId": "0475ca1e-d0c5-441d-712a-da55a4175157"
  },
  "Images": [
    {
      "StateComment": {},
      "State": "available",
      "RootDeviceType": "bsu",
      "RootDeviceName": "/dev/sda1",
      "ProductCodes": [
        "0001"
      ],
      "PermissionsToLaunch": {
        "GlobalPermission": true,
        "AccountIds": []
      },
      "AccountId": "123456789012",
      "Tags": [],
      "Description": "",
      "ImageId": "ami-12345678",
      "BlockDeviceMappings": [
        {
          "DeviceName": "/dev/sda1",
          "Bsu": {
            "VolumeType": "standard",
            "DeleteOnVmDeletion": true,
            "VolumeSize": 10,
            "SnapshotId": "snap-12345678"
          }
        }
      ],
      "ImageType": "machine",
      "AccountAlias": "Outscale",
      "CreationDate": "2010-10-01T12:34:56.789Z",
      "FileLocation": "Outscale/Ubuntu-2010.10.01-0",
      "Architecture": "x86_64",
      "ImageName": "Ubuntu-2010.10.01-0"
    },
    {
      "StateComment": {},
      "State": "available",
      "RootDeviceType": "bsu",
      "RootDeviceName": "/dev/sda1",
      "ProductCodes": [
        "0001"
      ],
      "PermissionsToLaunch": {
        "GlobalPermission": true,
        "AccountIds": []
      },
      "AccountId": "123456789012",
      "Tags": [],
      "Description": "",
      "ImageId": "ami-12345678",
      "BlockDeviceMappings": [
        {
          "DeviceName": "/dev/sda1",
          "Bsu": {
            "VolumeType": "standard",
            "DeleteOnVmDeletion": true,
            "VolumeSize": 10,
            "SnapshotId": "snap-12345678"
          }
        }
      ],
      "ImageType": "machine",
      "AccountAlias": "Outscale",
      "CreationDate": "2010-10-01T12:34:56.789Z",
      "FileLocation": "Outscale/RockyLinux-2010.10.01-0",
      "Architecture": "x86_64",
      "ImageName": "RockyLinux-2010.10.01-0"
    }
  ]
}

Getting Information About Your OMIs Using oapi-cli

The ReadImages command lists one or more OUTSCALE machine images (OMIs) you can use.

Request sample: Reading a specific image

$ oapi-cli --profile "default" ReadImages \
    --Filters '{
        "ImageIds": ["ami-12345678"]
      }'

Request sample: Reading Ubuntu and RockyLinux images created by Outscale

$ oapi-cli --profile "default" ReadImages \
    --Filters '{
        "AccountAliases": ["Outscale"],
        "ImageNames": ["Ubuntu*", "RockyLinux*"]
      }'

This command contains the following attributes that you need to specify:

DryRun: (optional) If true, checks whether you have the required permissions to perform the action.
Filters: (optional) One or more filters.
- AccountAliases: (optional) The account aliases of the owners of the OMIs.
- AccountIds: (optional) The account IDs of the owners of the OMIs. By default, all the OMIs for which you have launch permissions are described.
- Architectures: (optional) The architectures of the OMIs (i386 | x86_64).
- BlockDeviceMappingDeleteOnVmDeletion: (optional) Whether the volumes are deleted or not when terminating the VM.
- BlockDeviceMappingDeviceNames: (optional) The device names for the volumes.
- BlockDeviceMappingSnapshotIds: (optional) The IDs of the snapshots used to create the volumes.
- BlockDeviceMappingVolumeSizes: (optional) The sizes of the volumes, in gibibytes (GiB).
- BlockDeviceMappingVolumeTypes: (optional) The types of volumes (standard | gp2 | io1).
- Descriptions: (optional) The descriptions of the OMIs, provided when they were created.
- FileLocations: (optional) The locations of the buckets where the OMI files are stored.
- Hypervisors: (optional) The hypervisor type of the OMI (always xen).
- ImageIds: (optional) The IDs of the OMIs.
- ImageNames: (optional) The names of the OMIs, provided when they were created.
- PermissionsToLaunchAccountIds: (optional) The account IDs which have launch permissions for the OMIs.
- PermissionsToLaunchGlobalPermission: (optional) If true, lists all public OMIs. If false, lists all private OMIs.
- ProductCodeNames: (optional) The names of the product codes associated with the OMI.
- ProductCodes: (optional) The product codes associated with the OMI.
- RootDeviceNames: (optional) The name of the root device. This value must be /dev/sda1.
- RootDeviceTypes: (optional) The types of root device used by the OMIs (bsu or ebs).
- States: (optional) The states of the OMIs (pending | available | failed).
- TagKeys: (optional) The keys of the tags associated with the OMIs.
- TagValues: (optional) The values of the tags associated with the OMIs.
- Tags: (optional) The key/value combination of the tags associated with the OMIs, in the following format: "Filters":{"Tags":["TAGKEY=TAGVALUE"]}.
- VirtualizationTypes: (optional) The virtualization types (always hvm).
NextPageToken: (optional) The token to request the next page of results. Each token refers to a specific page.
ResultsPerPage: (optional) The maximum number of logs returned in a single response (between 1 and 1000, both included). By default, 100.

The ReadImages command returns the following elements:

Images: Information about one or more OMIs.
- AccountAlias: The account alias of the owner of the OMI.
- AccountId: The account ID of the owner of the OMI.
- Architecture: The architecture of the OMI.
- BlockDeviceMappings: One or more block device mappings.
  - Bsu: Information about the BSU volume to create.
    
    DeleteOnVmDeletion: By default or if set to true, the volume is deleted when terminating the VM. If false, the volume is not deleted when terminating the VM.
    
    Iops: The number of I/O operations per second (IOPS). This parameter must be specified only if you create an io1 volume. The maximum number of IOPS allowed for io1 volumes is 13000 with a maximum performance ratio of 300 IOPS per gibibyte.
    
    SnapshotId: The ID of the snapshot used to create the volume.
    
    VolumeSize: The size of the volume, in gibibytes (GiB).
    If you specify a snapshot ID, the volume size must be at least equal to the snapshot size.
    If you specify a snapshot ID but no volume size, the volume is created with a size similar to the snapshot one.
    
    VolumeType: The type of the volume (standard | io1 | gp2). If not specified in the request, a standard volume is created.
    For more information about volume types, see About Volumes > Volume Types and IOPS.
  - DeviceName: The device name for the volume. For a root device, you must use /dev/sda1. For other volumes, you must use /dev/sdX, /dev/sdXX, /dev/xvdX, or /dev/xvdXX (where the first X is a letter between b and z, and the second X is a letter between a and z).
  - VirtualDeviceName: The name of the virtual device (ephemeralN).
- CreationDate: The date and time (UTC) at which the OMI was created.
- Description: The description of the OMI.
- FileLocation: The location from which the OMI files were created.
- ImageId: The ID of the OMI.
- ImageName: The name of the OMI.
- ImageType: The type of the OMI.
- PermissionsToLaunch: Permissions for the resource.
  - AccountIds: One or more account IDs that the permission is associated with.
  - GlobalPermission: A global permission for all accounts.
    (Request) Set this parameter to true to make the resource public (if the parent parameter is Additions) or to make the resource private (if the parent parameter is Removals).
    (Response) If true, the resource is public. If false, the resource is private.
- ProductCodes: The product codes associated with the OMI.
- RootDeviceName: The name of the root device.
- RootDeviceType: The type of root device used by the OMI (always bsu).
- State: The state of the OMI (pending | available | failed).
- StateComment: Information about the change of state.
  - StateCode: The code of the change of state.
  - StateMessage: A message explaining the change of state.
- Tags: One or more tags associated with the OMI.
  - Key: The key of the tag, with a minimum of 1 character.
  - Value: The value of the tag, between 0 and 255 characters.
NextPageToken: The token to request the next page of results. Each token refers to a specific page.
ResponseContext: Information about the context of the response.
- RequestId: The ID of the request.

Result sample: Reading a specific image

{
  "ResponseContext": {
    "RequestId": "0475ca1e-d0c5-441d-712a-da55a4175157"
  },
  "Images": [
    {
      "StateComment": {},
      "State": "available",
      "RootDeviceType": "bsu",
      "RootDeviceName": "/dev/sda1",
      "ProductCodes": [
        "0001"
      ],
      "PermissionsToLaunch": {
        "GlobalPermission": false,
        "AccountIds": []
      },
      "AccountId": "123456789012",
      "Tags": [],
      "Description": "",
      "ImageId": "ami-12345678",
      "BlockDeviceMappings": [
        {
          "DeviceName": "/dev/sda1",
          "Bsu": {
            "VolumeType": "standard",
            "DeleteOnVmDeletion": true,
            "VolumeSize": 50,
            "SnapshotId": "snap-12345678"
          }
        }
      ],
      "ImageType": "machine",
      "CreationDate": "2010-10-01T12:34:56.789Z",
      "FileLocation": "123456789012/create-image-example",
      "Architecture": "x86_64",
      "ImageName": "create-image-example"
    }
  ]
}

Result sample: Reading Ubuntu and RockyLinux images created by Outscale

{
  "ResponseContext": {
    "RequestId": "0475ca1e-d0c5-441d-712a-da55a4175157"
  },
  "Images": [
    {
      "StateComment": {},
      "State": "available",
      "RootDeviceType": "bsu",
      "RootDeviceName": "/dev/sda1",
      "ProductCodes": [
        "0001"
      ],
      "PermissionsToLaunch": {
        "GlobalPermission": true,
        "AccountIds": []
      },
      "AccountId": "123456789012",
      "Tags": [],
      "Description": "",
      "ImageId": "ami-12345678",
      "BlockDeviceMappings": [
        {
          "DeviceName": "/dev/sda1",
          "Bsu": {
            "VolumeType": "standard",
            "DeleteOnVmDeletion": true,
            "VolumeSize": 10,
            "SnapshotId": "snap-12345678"
          }
        }
      ],
      "ImageType": "machine",
      "AccountAlias": "Outscale",
      "CreationDate": "2010-10-01T12:34:56.789Z",
      "FileLocation": "Outscale/Ubuntu-2010.10.01-0",
      "Architecture": "x86_64",
      "ImageName": "Ubuntu-2010.10.01-0"
    },
    {
      "StateComment": {},
      "State": "available",
      "RootDeviceType": "bsu",
      "RootDeviceName": "/dev/sda1",
      "ProductCodes": [
        "0001"
      ],
      "PermissionsToLaunch": {
        "GlobalPermission": true,
        "AccountIds": []
      },
      "AccountId": "123456789012",
      "Tags": [],
      "Description": "",
      "ImageId": "ami-12345678",
      "BlockDeviceMappings": [
        {
          "DeviceName": "/dev/sda1",
          "Bsu": {
            "VolumeType": "standard",
            "DeleteOnVmDeletion": true,
            "VolumeSize": 10,
            "SnapshotId": "snap-12345678"
          }
        }
      ],
      "ImageType": "machine",
      "AccountAlias": "Outscale",
      "CreationDate": "2010-10-01T12:34:56.789Z",
      "FileLocation": "Outscale/RockyLinux-2010.10.01-0",
      "Architecture": "x86_64",
      "ImageName": "RockyLinux-2010.10.01-0"
    }
  ]
}

Getting Information About Your OMIs Using AWS CLI

Before you begin: Install and configure AWS CLI. For more information, see Installing and Configuring AWS CLI.

Getting General Information About Your OMIs

To get information about one or more OMIs, use the describe-images command following this syntax:

Request sample

$ aws ec2 describe-images \
    --profile YOUR_PROFILE \
    --image-ids ami-12345678 ami-87654321 ami-56781234 \
    --owners 1234567890000 \
    --executable-users 0000987654321 \
    --filters Name=X,Values=Y \
    --endpoint https://fcu.eu-west-2.outscale.com

This command contains the following attributes that you need to specify:

(optional) profile: The named profile you want to use, created when configuring AWS CLI. For more information, see Installing and Configuring AWS CLI.
(optional) image-ids: One or more OMI IDs.

If you do not specify any OMI ID, all your OMIs or all the OMIs matching the specified filters if any are described.
(optional) owners: The account ID of one or more owners of OMIs. By default, all the OMIs for which you have launch permissions are described.
(optional) executable-users: The account IDs allowed to use the OMIs.

(optional) filters: One or more filters, in the "Name=X,Values=Y" format.

You can specify several values for a same filter using the "Name=X,Values=Y, Z" format.

The following filters are available:

architecture: The architecture of the OMI (i386 or x86_64).
block-device-mapping.delete-on-termination: Indicates whether the volume is deleted when terminating the instance.
block-device-mapping.device-name: The device name assigned to the volume (in the format /dev/sdX, /dev/sdXX, /dev/xvdX, or /dev/xvdXX).
block-device-mapping.snapshot-id: The ID of the snapshot used to create the volume.
block-device-mapping.volume-size: The size of the volume, in gibibytes (GiB).
block-device-mapping.volume-type: The type of volume (standard | gp2 | io1).
description: The description of the OMI, provided when it was created.
hypervisor: The hypervisor type of the instance (always xen).
image-id: The ID of the OMI.
image-type: The type of OMI (always machine for official OMIs).
is-public: Indicates whether the OMI has public launch permissions.
manifest-location: The location of the OMI manifest.
name: The name of the OMI, provided when it was created.
owner-alias: The account alias of the owner of the OMI.
owner-id: The account ID of the owner of the OMI.
platform: The platform.
product-code.type: The type of the product code associated with the OMI.

Once a product code is applied to an OMI, it cannot be removed.
root-device-name: The device name assigned to the root device (for example, /dev/sda1).
root-device-type: The type of root device used by the OMI (always ebs).
state: The current state of the OMI (pending | available | failed).

tag-key: The key of a tag associated with the resource.
tag-value: The value of a tag associated with the resource.

tag:XXXX: The value of a tag associated with the resource, where XXXX is the key of the tag.

To filter a tag whose key is XXXX and value is YYYY, you can therefore use either of the following two formats:

--filters Name=tag-key,Values=XXXX Name=tag-value,Values=YYYY
--filters Name=tag:XXXX,Values=YYYY

virtualization-type: The virtualization type of the instance (always hvm).

endpoint: The endpoint corresponding to the Region you want to send the request to. For more information, see Installing and Configuring AWS CLI.

The describe-images command returns the following elements:

Images: Information about one or more OMIs. This element contains the following information:
- VirtualizationType: The virtualization type of the instance (always hvm).
- Name: The name of the OMI.
- Hypervisor: The hypervisor type of the instance (always xen).
- ImageId: The ID of the OMI.
- Platform: No information returned.
- State: The current state of the OMI.
- BlockDeviceMappings: One or more block device mappings. For more information, see Defining Block Device Mappings.
- Architecture: The architecture of the OMI.
- ImageLocation: The path to the OMI.
- RootDeviceType: The type of root device for the instance (always ebs).
- OwnerId: The account ID of the owner of the OMI.
- RootDeviceName: The device name assigned to the root device of the instance.
- Public: Indicates whether the OMI has public creation permissions.
- ImageType: The type of OMI (always machine for official OMIs).
- Description: The description of the OMI, if any.

Result sample

{
    "Images": [
        {
            "VirtualizationType": "hvm",
            "Name": "Image_name",
            "Hypervisor": "xen",
            "ImageId": "ami-12345678",
            "Platform": "",
            "State": "available",
            "BlockDeviceMappings": [
                {
                    "DeviceName": "/dev/sda1",
                    "Ebs": {
                        "DeleteOnTermination": true,
                        "SnapshotId": "snap-87654321",
                        "VolumeSize": 8,
                        "VolumeType": "standard"
                    }
                }
            ],
            "Architecture": "x86_64",
            "ImageLocation": "1234567890000/Image_name",
            "RootDeviceType": "ebs",
            "OwnerId": "1234567890000",
            "RootDeviceName": "/dev/sda1",
            "Public": false,
            "ImageType": "machine",
            "Description": "CentOS 7 with HAProxy installed and NAT configured"
        }]
}

Getting Information About an Attribute of an OMI

You can get information about the list of accounts who have permissions to create an instance from the specified OMI. You can modify these permissions at any time. For more information, see Modifying the Attributes of an OMI.

To get information about the accounts who have permissions to use an OMI from Cockpit, you need to use the Share OMI command. For more information, see Modifying the Attributes of an OMI.

To get general information about an attribute of a specified OMI, use the describe-image-attribute command following this syntax:

Request sample

$ aws ec2 describe-image-attribute \
    --profile YOUR_PROFILE \
    --image-id ami-12345678 \
    --attribute launchPermission \
    --endpoint https://fcu.eu-west-2.outscale.com

This command contains the following attributes that you need to specify:

(optional) profile: The named profile you want to use, created when configuring AWS CLI. For more information, see Installing and Configuring AWS CLI.
image-id: The ID of the OMI.
attribute: The OMI attribute (description | kernel | launchPermission | productCodes).
endpoint: The endpoint corresponding to the Region you want to send the request to. For more information, see Installing and Configuring AWS CLI.

The describe-images command returns the following elements:

The attribute value (here, LaunchPermission).
ImageId: The ID of the OMI.

Result sample

{
    "LaunchPermissions": [
        {
            "UserId": "12345679890000"
        },
        {
            "UserId": "0000987654321"
        }
    ],
    "ImageId": "ami-123456789"
}

Related Pages

Corresponding API Methods

AWS™ and Amazon Web Services™ are trademarks of Amazon Technologies, Inc or its affiliates in the United States and/or other countries.