| copyright | lastupdated | keywords | subcollection | content-type | ||
|---|---|---|---|---|---|---|
|
2024-05-29 |
public images, commands, questions, registry, Vulnerability Advisor, frequently asked questions, namespace, tool, image, digest, access, region, package manager, security notices, version of a package |
Registry |
faq |
{{site.data.keyword.attribute-definition-list}}
{: #registry_faq}
Frequently asked questions (FAQs) about {{site.data.keyword.registrylong}} and Vulnerability Advisor. {: shortdesc}
{: #registry_faq_registry}
{: #faq_ref_docs} {: faq}
The reference documentation for {{site.data.keyword.registrylong_notm}} is available in the {{site.data.keyword.cloud_notm}} docs. For more information, see About {{site.data.keyword.registryshort}} and {{site.data.keyword.registrylong_notm}} CLI.
{: #faq_setup_cli} {: faq}
To set up the {{site.data.keyword.registrylong_notm}} CLI, use the following steps:
- Ensure that the {{site.data.keyword.cloud_notm}} CLI is installed.
- Install the
container-registryCLI plug-in by running the commandibmcloud plugin install container-registry. - Log in to {{site.data.keyword.cloud_notm}} with the
ibmcloud logincommand. - Verify the installation by checking the current version of the
container-registryCLI plug-in with the commandibmcloud plugin list.
Now you can use the {{site.data.keyword.registrylong_notm}} CLI to manage your registry and its resources for your {{site.data.keyword.cloud_notm}} account.
For more information, see Setting up the {{site.data.keyword.registryshort}} CLI and namespace and Getting started with {{site.data.keyword.registryshort}}.
{: #faq_firewall} {: faq}
You can use a Layer 7 firewall{: external} with the domains listed in Accessing {{site.data.keyword.registryshort}} through a firewall or use a virtual private network (VPN).
{: #faq_namespace} {: faq}
You can have 100 registry namespaces in each region.
{: #faq_namespace_rename} {: faq}
You can't rename a namespace{: term}. If you want to change the name of the namespace, you must create a namespace with the new name and transfer its data. To transfer its data, you can copy the contents of the existing namespace into the namespace that you created.
If you don't want to transfer data manually, you can create a script for this action by using the ibmcloud cr image-tag command. For example, you can use the following script, where <old_namespace> is the existing namespace and <new_namespace> is the namespace that you created:
IMAGES=$(icr images --restrict <old_namespace> --format "{{ .Repository }}:{{ .Tag }}")
for i in $IMAGES ; do
new=$(echo $i | sed "s|/<old_namespace>/|/<new_namespace>/|1")
ibmcloud cr image-tag $i $new
done{: codeblock}
{: #faq_auth_namespace} {: faq}
You are not authorized to create a namespace in {{site.data.keyword.registrylong_notm}}. The error message You are not authorized to access the specified resource. indicates that you lack the necessary user permissions for working with namespaces. To add, assign, and remove namespaces, you must have the Manager role in the {{site.data.keyword.registryshort}} service at the account level. If you have the Manager role on the resource group, or resource groups, it is not sufficient; the Manager role must be at the account level.
For more information, see Why aren't I authorized to access a specified resource in {{site.data.keyword.registryshort}}? and User permissions for working with namespaces.
{: #faq_list_images} {: faq}
To list all the images in your {{site.data.keyword.cloud_notm}} account, you can run the ibmcloud cr images command, which displays all tagged images in your {{site.data.keyword.cloud_notm}} account with a truncated digest. If you want to list all your images with the complete digest, including untagged images, run the ibmcloud cr image-digests command. The image name is in either the format repository@digest or repository:tag. The values for repository, digest, and tag are returned when you run the commands.
For more information, see ibmcloud cr image-list (ibmcloud cr images) and ibmcloud cr image-digests (ibmcloud cr digests).
{: #faq_list_public_images} {: faq}
To list public images, run the following ibmcloud commands to target the global registry and list the public images that are provided by {{site.data.keyword.IBM_notm}}:
ibmcloud cr region-set global{: pre}
ibmcloud cr images --include-ibm{: pre}
{: #faq_tools} {: faq}
You can use Docker and non-Docker tools to build and push images to the registry. You can use non-Docker tools that support OCI container image{: term} format and protocol. To log in by using other clients, see Accessing your namespaces interactively.
{: #faq_trash} {: faq}
Images that are in the trash don't count toward your quota.
{: #faq_digest} {: faq}
You can find the long format of the image digest by running one of the following commands. The digest is displayed in the Digest column of the CLI.
When you're using the digest to identify an image, always use the long format. {: note}
-
Run the
ibmcloud cr image-digestscommand:ibmcloud cr image-digests
{: pre}
-
Run the
ibmcloud cr image-listcommand:ibmcloud cr image-list --no-trunc
{: pre}
If you run the
ibmcloud cr image-listcommand without the--no-truncoption, you see the truncated format of the digest. {: note}
{: #faq_digest_use} {: faq}
The digest identifies an image by using the sha256 hash of the image manifest.
To find the digests for your images, run the ibmcloud cr image-digests command. You can refer to an image by using a combination of the content of the Repository column (repository) and the Digest column (digest) separated by an at (@) symbol to create the image name in the format repository@digest.
{: #faq_push_images} {: faq}
You might have issues when you are pulling or pushing images to {{site.data.keyword.registryshort}} because of various reasons such as exceeding the image storage or pull traffic quota, or invalid credentials. To resolve this issue, log in to {{site.data.keyword.cloud_notm}} and the {{site.data.keyword.registrylong_notm}} CLI, review quota limits and usage, and consider upgrading to a standard plan if you are on a free plan.
For more information, see Why can't I push or pull a Docker image when I use {{site.data.keyword.registryshort}}? for assistance.
{: #faq_images_year_old} {: faq}
[Linux]{: tag-linux} [macOS]{: tag-macos} On Linux® and macOS, if you want to list all images, both tagged and untagged that were created more than a year ago, you can run the following command:
year=$(($(date +%s) - 31556952))
ibmcloud cr digests --format '{{ if (lt .Created '$year')}}{{.Repository}}:{{.Digest}}{{end}}'{: pre}
{: #faq_access_control} {: faq}
You can create {{site.data.keyword.IBM_notm}} {{site.data.keyword.iamshort}} (IAM) policies to control access to your namespaces in {{site.data.keyword.registrylong_notm}}. For more information, see Granting access to {{site.data.keyword.registrylong_notm}} resources tutorial and Managing IAM access for {{site.data.keyword.registryshort_notm}}.
{: #faq_share_image} {: faq}
To access an image, a user must be a member of the {{site.data.keyword.cloud_notm}} account that owns the images. After the user is added to the account, appropriate IAM policies must be created to assign access.
For more information, see Defining IAM access policies.
{: #faq_untagged_image_1} {: faq}
To find out whether you have any untagged images, list your images by running the ibmcloud cr image-digests command. Untagged images have a hyphen (-) in the Tags column.
{: #faq_untagged_image_2} {: faq}
If you have active containers that are running untagged images, you must retain the untagged images. If you delete untagged images that are in use, you can cause problems with scaling or automated restarts. Deleting untagged images might cause a problem in the following circumstances:
- The image was deployed by using the digest as the reference. For example, {{site.data.keyword.codeenginefull_notm}} does resolve and use an image digest when it is serving applications, see Deploying app workloads from images in a public registry.
- The image reference was mutated by a webhook service, such as Portieris.
{: #faq_eligible_image} {: faq}
If you're cleaning up images by using retention policies, only eligible images are cleaned up. Images that are always retained are Cloud Native Buildpacks{: external} and Google distroless{: external} images with the build date set to a specific constant rather than the real build time or with no build timestamp at all, and manifest lists. Images that are always retained are not eligible images.
The images that are not eligible are still displayed, but they do not count toward the total number of images that is set in the retention policy and are not removed.
Images created before 2013-01-19T00:13:39Z are excluded from retention policy evaluation.
For more information, see Planning retention.
{: #faq_regions} {: faq}
To find out more about the regions that are available for {{site.data.keyword.registrylong_notm}}, see Regions.
{: #faq_docker_pull} {: faq}
To find the most recent image, run the ibmcloud cr image-list command rather than the docker pull command. To make it easier to find the most recent image, define a different sequential tag for your images every time, and do not rely on the latest tag.
For more information, see Why can't I pull the newest image by using the latest tag in {{site.data.keyword.registryshort}}? for assistance.
{: #faq_imagepullbackoff} {: faq}
Your cluster uses an API key that is stored in an image pull secret to authorize the cluster to pull images from {{site.data.keyword.registrylong_notm}}, or the image with the specific tag does not exist in the repository. To fix it, make sure that you're using the correct name and tag for the image, that you have enough pull traffic and storage quota, and that you have an image pull secret in your namespace.
For more information, see Why do images fail to pull from registry with ImagePullBackOff or authorization errors? for assistance.
{: #faq_quota_error} {: faq}
You exceeded your image storage or pull traffic quota for the current month. This means that you used more quota than your account allows for the month. To resolve this issue, you can either review your quota limits and increase them as necessary, or if you're on the lite plan upgrade to the standard plan.
For more information, see Why am I getting errors about my quota in {{site.data.keyword.registryshort}}? and Staying within quota limits.
{: #registry_faq_va}
{: #faq_va_vuln} {: faq}
You can use Vulnerability Advisor to manage image security and vulnerabilities.
For more information, see Managing image security with Vulnerability Advisor.
{: #faq_va_cost} {: faq}
The cost of Vulnerability Advisor is built into the pricing for {{site.data.keyword.registrylong_notm}}. For more information, see Billing for storage and pull traffic.
{: #faq_va_reg} {: faq}
Vulnerability Advisor scans images from {{site.data.keyword.registrylong_notm}} only.
{: #faq_va_trigger_scan} {: faq}
For more information about how the scanning of an image is triggered, see Vulnerable packages.
{: #faq_va_v4_scan} {: faq}
If your image isn't being scanned, check that it has a tag. In Vulnerability Advisor version 4, images are scanned only if they have a tag.
{: #faq_va_new_scan_error} {: faq}
If you get the vulnerability report immediately after you add the image to the registry{: term}, you might receive the following error:
BXNVA0009E: <imagename> has not been scanned. Try again later.
If this issue persists, contact support for help;
see https://cloud.ibm.com/docs/get-support?topic=get-support-getting-customer-support#getting-customer-support{: screen}
You receive this message because the images are scanned asynchronously to the requests for results, and the scanning process takes a while to complete. During normal operation, the scan completes within the first few minutes after you add the image to the registry. The time that it takes to complete depends on variables like the proportions of the image and the amount of traffic that the registry is receiving.
If you get this message as part of a build pipeline and you see this error regularly, try adding some retry logic that contains a short pause.
If you still see unacceptable performance, contact support, see Getting help and support for {{site.data.keyword.registryshort}}.
{: #faq_va_update_security_notice} {: faq}
Security notices for Vulnerability Advisor are loaded from the vendors' operating system sites approximately every 12 hours.
{: #faq_va_package_version} {: faq}
To determine the version of a package that is installed in your image, use the relevant package manager command for your operating system.
{: #faq_va_package_version_alpine}
On Alpine, to determine the version of a package that is installed in your image, you can use the following commands, where <package_name> is the name of your package.
-
To list the metadata for a specific installed package, run the following command:
apk info <package_name>
{: pre}
-
To list all installed packages and their versions, run the following command:
apk list
{: pre}
{: #faq_va_package_version_debian_ubuntu}
On Debian and Ubuntu, to determine the version of a package that is installed in your image, you can use the following commands, where <package_name> is the name of your package.
-
To list the metadata for a specific installed package, run either of the following commands:
apt show <package_name>
{: pre}
dpkg-query -l <package_name>
{: pre}
-
To list all installed packages and their versions, run either of the following commands:
apt list
{: pre}
dpkg-query -W
{: pre}
{: #faq_va_package_version_redhat_centos}
On {{site.data.keyword.redhat_openshift_full}} and CentOS, to determine the version of a package that is installed in your image, you can use the following commands, where <package_name> is the name of your package.
-
To list the metadata for a specific installed package, run either of the following commands:
rpm -qi <package_name>
{: pre}
yum info <package_name>
{: pre}
-
To list all installed packages and their versions, run either of the following commands:
rpm -qa
{: pre}
yum list installed
{: pre}
{: #faq_va_versions} {: faq}
Vulnerability Advisor version 4 is the only version available. For more information, see Managing image security with Vulnerability Advisor.
Vulnerability Advisor version 3 is discontinued from 13 November 2023. For more information about how to update to version 4, see Vulnerability Advisor version 3 is being discontinued on 13 November 2023. {: deprecated}