Managing container images

Import container image repositories, configure registry access and naming, and push or pull images to manage container content across lifecycle environments in orcharhino.

You can consume content from orcharhino without registering your hosts to orcharhino and/or without using subscription-manager to consume content, for example, in containerized build pipelines. Any host that consumes content from orcharhino Server or orcharhino Proxy Servers is considered a managed host that requires a valid orcharhino subscription.

Importing container image repositories

Import container image repositories into orcharhino from any container image registry to synchronize external images and make them available through content views.

Discovering container image repositories in a registry

Discover container image repositories in an external registry from the orcharhino management UI to quickly import multiple repositories without entering each repository URL manually.

Prerequisites

If the container image registry requires authentication, you have valid credentials for the registry.

Procedure

In the orcharhino management UI, navigate to Content > Products and click Repo Discovery.
From the Repository Type list, select Container Images.
In the Registry to Discover field, enter the URL of the registry to import images from.
In the Registry Username field, enter the name that corresponds with your user name for the container image registry.
In the Registry Password field, enter the password that corresponds with the user name that you enter.
In the Registry Search Parameter field, enter any search criteria that you want to use to filter your search, and then click Discover.
Optional: To further refine the Discovered Repository list, in the Filter field, enter any additional search criteria that you want to use.
From the Discovered Repository list, select any repositories that you want to import, and then click Create Selected.
Optional: To change the download policy for this container repository to on demand, see Updating the download policy for a repository by using orcharhino management UI.
Optional: If you want to create a product, from the Product list, select New Product.
In the Name field, enter a product name.
Optional: In the Repository Name and Repository Label columns, you can edit the repository names and labels.
Click Run Repository Creation.
When repository creation is complete, you can click each new repository to view more information.
Optional: To filter the content you import to a repository, click a repository, and then navigate to Limit Sync Tags. Click to edit, and add any tags that you want to limit the content that synchronizes to orcharhino.
In the orcharhino management UI, navigate to Content > Products and select the name of your product.
Select the new repositories and then click Sync Now to start the synchronization process.

Next steps

To view the progress of the synchronization, navigate to Content > Sync Status and expand the repository tree.
When the synchronization completes, you can click Container Image Manifests to list the available manifests. From the list, you can also remove any manifests that you do not require.

Importing a container image repository manually by using orcharhino management UI

Manually import a container image repository in the orcharhino management UI when you know the repository URL and want to add a single repository to a product.

Prerequisites

A product exists in your organization.

Procedure

In the orcharhino management UI, navigate to Content > Products.
Click the name of the required product.
Click New repository.
From the Type list, select docker.
Enter the details for the repository, and click Save.
Select the new repository, and click Sync Now.

Next steps

To view the progress of the synchronization, navigate to Content > Sync Status and expand the repository tree.
When the synchronization completes, you can click Container Image Manifests to list the available manifests. From the list, you can also remove any manifests that you do not require.

Additional resources

Adding content to orcharhino

Importing a container image repository by using Hammer CLI

Import a container image repository by using the Hammer CLI to add and synchronize container content as part of automated orcharhino administration.

Procedure

Create the custom Rocky Linux Container Images product:

$ hammer product create \
--description "My_Description" \
--name "Rocky Linux Container Images" \
--organization "My_Organization" \
--sync-plan "My_Sync_Plan"

Create the repository for the container images:

$ hammer repository create \
--content-type "docker" \
--docker-upstream-name "rockylinux/rockylinux" \
--name "Rocky Linux" \
--organization "My_Organization" \
--product "Rocky Linux Container Images" \
--url "https://quay.io"

Synchronize the repository:

$ hammer repository synchronize \
--name "Rocky Linux" \
--organization "My_Organization" \
--product "Rocky Linux Container Images"

Additional resources

Adding content to orcharhino

Configuring the orcharhino container registry

Registry name patterns and authentication settings control how container images are named and who can access them in each lifecycle environment of the orcharhino container registry.

Configuring container registry name patterns for a lifecycle environment

Set a registry name pattern for a lifecycle environment to override default container image names and to avoid naming conflicts when you pull images from orcharhino.

When you use orcharhino to create and manage your containers, as the container moves through content view versions and different stages of the orcharhino lifecycle environment, the container name changes at each stage. For example, if you synchronize a container image with the name ssh from an upstream repository, when you add it to a orcharhino product and organization and then publish as part of a content view, the container image can have the following name: my_organization_production-custom_spin-my_product-custom_ssh. This can create problems when you want to pull a container image because container registries can contain only one instance of a container name.

Proceed with caution when defining registry naming patterns for your containers.

If you use a registry name pattern to manage container naming conventions, because registry naming patterns must generate globally unique names, you might experience naming conflict problems. For example:

If you set the repository.docker_upstream_name registry name pattern, you cannot publish or promote content views with container content with identical repository names to the Production lifecycle.
If you set the lifecycle_environment.name registry name pattern, this can prevent the creation of a second container repository with the identical name.

Procedure

In the orcharhino management UI, navigate to Content > Lifecycle > Lifecycle Environments.
Create a lifecycle environment or select an existing lifecycle environment to edit.
In the Container Image Registry area, click the edit icon to the right of Registry Name Pattern area.
Use the list of variables and examples to determine which registry name pattern you require.
In the Registry Name Pattern field, enter the registry name pattern that you want to use. For example, to use the repository.docker_upstream_name:
```
<%= repository.docker_upstream_name %>
```
Click Save.

Controlling container registry access for a lifecycle environment

Control whether users must authenticate to pull container images from a lifecycle environment, for example to allow unauthenticated access in production.

By default, users must authenticate to access container images in orcharhino. You can specify whether users must authenticate to access container images in a lifecycle environment. For example, you might want to permit users to access container images from the Production lifecycle environment without any authentication requirement and restrict access to the Development and QA environments to authenticated users.

Procedure

In the orcharhino management UI, navigate to Content > Lifecycle > Lifecycle Environments.
Select the lifecycle environment that you want to manage authentication for.
To permit unauthenticated access to the containers in this lifecycle environment, select the Unauthenticated Pull checkbox. To restrict unauthenticated access, clear the Unauthenticated Pull checkbox.
Click Save.

Using the orcharhino container registry

Use Podman or Docker to push container images to the orcharhino container registry or pull images that you publish and promote through content views.

The orcharhino container registry follows the Open Containers Initiative (OCI) specification, so you can push content to orcharhino by using the same methods that apply to other container registries. For more information about OCI, see Open Container Initiative Distribution Specification.

Considerations for using the orcharhino container registry

Review naming, push, and pull limitations before you use the orcharhino container registry so that container workflows succeed without unexpected errors.

You cannot push to repositories created by the general repositories endpoints, only to repositories created by the container push workflow.
You can only push content to orcharhino Server itself. If you need pushed content on orcharhino Proxy Servers as well, use orcharhino Proxy syncing.
The pushed container registry name must contain only lowercase characters.
Unless pushed repositories are published in a content view version, they do not follow the registry name pattern. For more information, see Configuring container registry name patterns for a lifecycle environment. This is to ensure that users can push and pull from the same path.
Users are required to push and pull from the same path. If you use the label-based schema, pull using labels. If you use the ID-based schema, pull using IDs.

Configuring Podman to trust the certificate authority

Configure Podman to trust the orcharhino certificate authority so that you can push and pull container images without disabling TLS verification.

Podman locates the CA file in the /etc/containers/certs.d/ path. Copy the root CA file to that path, with the exact path determined by the server hostname, and name the file ca.crt.

In the following examples, replace hostname.example.com with orcharhino.example.com or orcharhino-proxy.network2.example.com, depending on your use case.

Prerequisites

You have the root CA certificate file for orcharhino Server or orcharhino Proxy Server.
You have root or sudo access on the host where Podman is installed.

Procedure

Create the relevant directory:

$ mkdir --parents /etc/containers/certs.d/hostname.example.com

Copy the CA file to the directory:

$ cp My_Root_CA.pem /etc/containers/certs.d/hostname.example.com/ca.crt

Verification

Verify that you no longer need to use the --tls-verify=false option when logging in to the registry:
```
$ podman login hostname.example.com
```

Configuring Docker to trust the certificate authority

Configure Docker to trust the orcharhino certificate authority so that you can push and pull container images without disabling TLS verification.

Docker locates the CA file in the /etc/docker/certs.d/ path. Copy the root CA file to that path, with the exact path determined by the server hostname, and name the file ca.crt.

In the following examples, replace hostname.example.com with orcharhino.example.com or orcharhino-proxy.network2.example.com, depending on your use case.

Prerequisites

You have the root CA certificate file for orcharhino Server or orcharhino Proxy Server.
You have root or sudo access on the host where Docker is installed.

Procedure

Create the relevant directory:

$ mkdir --parents /etc/docker/certs.d/hostname.example.com

Copy the CA file to the directory:

$ cp My_Root_CA.pem /etc/docker/certs.d/hostname.example.com/ca.crt

Verification

Verify that you no longer need to use the --tls-verify=false option when logging in to the registry:
```
$ podman login hostname.example.com
```

Pushing container images to orcharhino

Push container images to the orcharhino container registry to distribute custom images to hosts and lifecycle environments through orcharhino content management.

Prerequisites

You have reviewed Considerations for using the orcharhino container registry.
If orcharhino Server uses a self-signed certificate, you have configured Podman or Docker to trust the orcharhino certificate authority. For more information, see one of the following resources:
- Configuring podman to trust the certificate authority
- Configuring docker to trust the certificate authority
Your orcharhino account has the edit_products permission.
A product exists in your organization. For more information, see Creating a custom product by using orcharhino management UI.
Your orcharhino account has the create_personal_access_tokens permission. orcharhino automatically generates a token when you run podman login.

Procedure

Log in to the container registry:
```
$ podman login orcharhino.example.com
```
Push a container image to the orcharhino container registry. To indicate which organization, product, and repository the container image belongs to, include the organization and product in the container image path.

You can specify the container image destination by using one of the following schemas:
- Push the container image by using the label-based schema:
  $ podman push My_Container_Image_ID orcharhino.example.com/My_Organization_Label/My_Product_Label/My_Repository_Name[:My_Tag]
- Push the container image by using the ID-based schema:
  $ podman push My_Container_Image_ID orcharhino.example.com/id/My_Organization_ID/My_Product_ID/My_Repository_Name[:My_Tag]
The image tag is optional.
After the content push has completed, orcharhino creates the repository.

Pulling container images from orcharhino

Pull container images from the orcharhino container registry by using Podman or Docker to deploy images that you publish in content views across lifecycle environments.

Prerequisites

You have reviewed Considerations for using the orcharhino container registry.
If orcharhino Server uses a self-signed certificate, you have configured Podman or Docker to trust the orcharhino certificate authority. For more information, see one of the following resources:
- Configuring podman to trust the certificate authority
- Configuring docker to trust the certificate authority
Your orcharhino account has the view_lifecycle_environments, view_products, and view_content_views permissions, unless the lifecycle environment allows unauthenticated pull.
Your orcharhino account has the create_personal_access_tokens permission. orcharhino automatically generates a token when you run podman login.

Procedure

Log in to the container registry:
```
$ podman login orcharhino.example.com
```
List container images:
```
$ podman search orcharhino.example.com/
```
Pull a container image:
```
$ podman pull orcharhino.example.com/My_Image_Path[:My_Tag]
```
Pull the image by using the same image path schema as the one used to push the image. The path schema can be either label-based or ID-based.

The image tag is optional. If you do not specify a tag, podman pulls the latest tag.

The text and illustrations on this page are licensed by ATIX AG under a Creative Commons Attribution Share Alike 4.0 International ("CC BY-SA 4.0") license. This page also contains text from the official Foreman documentation which uses the same license ("CC BY-SA 4.0").