# Image Management¶

## Query Schema¶

type Image {
name: String
humanized_name: String
tag: String
registry: String
digest: String
labels: [KVPair]
aliases: [String]
size_bytes: BigInt
resource_limits: [ResourceLimit]
supported_accelerators: [String]
installed: Boolean
}

type Query {
image(reference: String!): Image

images(
is_installed: Boolean,
is_operation: Boolean,
domain: String,         # only settable by super-admins
group: String,
scaling_group: String,  # null to take union of all agents from allowed scaling groups
): [Image]
}


The image list is automatically filtered by: 1) the allowed docker registries of the current user’s domain, 2) whether at least one agent in the union of all agents from the allowed scaling groups for the current user’s group has the image or not. The second condition applies only when the value of group is given explicitly. If scaling_group is not null, then only the agents in the given scaling group are checked for image availability instead of taking the union of all agents from the allowed scaling groups.

If the requesting user is a super-admin, clients may set the filter conditions as they want. In this case, setting no conditions works like v19.09 and prior versions.

New in version v5.20191215: domain, group, and scaling_group filters are added to the images root query field.

Changed in version v5.20191215: images query returns the images currently usable by the requesting user as described above. Previously, it returned all etcd-registered images.

## Mutation Schema¶

type RescanImages {
ok: Boolean
msg: String
}

ok: Boolean
msg: String
}

ok: Boolean
msg: String
}

type ForgetImage {
ok: Boolean
msg: String
}

type AliasImage {
ok: Boolean
msg: String
}

type DealiasImage {
ok: Boolean
msg: String
}

type Mutation {
rescan_images(registry: String!): RescanImages
forget_image(reference: String!): ForgetImage
alias_image(alias: String!, target: String!): AliasImage
dealias_image(alias: String!): DealiasImage
}


All these mutations are only allowed for super-admins.

The query parameter target_agents takes a special expression to indicate a set of agents.

The mutations that returns task_id may take an arbitrarily long time to complete. This means that getting the response does not necessarily mean that the requested task is complete. To monitor the progress and actual completion, clients should use the background task API using the task_id value.

New in version v5.20191215: forget_image, preload_image and unload_image are added to the root mutation.

Changed in version v5.20191215: rescan_images now returns immediately and its completion must be monitored using the new background task API.