Skip to content

Commit 419e210

Browse files
ShaunaDiazShaunaDiaz
committed
OSDOCS-4438: Deploy Mshift with container registry
1 parent 088e384 commit 419e210

10 files changed

+410
-1
lines changed

‎_topic_maps/_topic_map_ms.yml

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -434,8 +434,10 @@ Topics:
434434
File: microshift-operators
435435
- Name: Greenboot workload health check scripts
436436
File: microshift-greenboot-workload-scripts
437-
- Name: Pod security authentication and authorization
437+
- Name: Pod security authentication and authorization
438438
File: microshift-authentication
439+
- Name: Mirror registry deployment
440+
File: microshift-deploy-with-mirror-registry
439441
---
440442
Name: Backup and restore
441443
Dir: microshift_backup_and_restore

‎microshift_running_apps/microshift-deploy-with-mirror-registry.adoc

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
:_content-type: ASSEMBLY
2+
[id="microshift-deploy-with-mirror-registry"]
3+
= {product-title} deployment with a mirror registry
4+
include::_attributes/attributes-microshift.adoc[]
5+
:context: microshift-deployment-mirror
6+
7+
toc::[]
8+
9+
You can use a custom container registry when you deploy {product-title} in an air-gapped network. Running your cluster in a restricted network without direct internet connectivity is possible by installing the cluster from a mirrored set of container images in a private registry.
10+
11+
include::modules/microshift-mirror-container-images.adoc[leveloffset=+1]
12+
13+
[role="_additional-resources"]
14+
.Additional resources
15+
* link:https://docs.openshift.com/container-platform/{ocp-version}/installing/disconnected_install/installing-mirroring-creating-registry.html[Creating a mirror registry with mirror registry for Red Hat OpenShift]
16+
17+
include::modules/microshift-get-mirror-reg-container-image-list.adoc[leveloffset=+1]
18+
19+
include::modules/microshift-mirroring-prereqs.adoc[leveloffset=+1]
20+
21+
[role="_additional-resources"]
22+
.Additional resources
23+
* link:https://access.redhat.com/documentation/en-us/openshift_container_platform/{ocp-version}/html/installing/disconnected-installation-mirroring#installation-adding-registry-pull-secret_installing-mirroring-disconnected[Configuring credentials that allow images to be mirrored]
24+
25+
include::modules/microshift-downloading-container-images.adoc[leveloffset=+1]
26+
27+
include::modules/microshift-uploading-images-to-mirror.adoc[leveloffset=+1]
28+
29+
include::modules/microshift-configuring-hosts-for-mirror.adoc[leveloffset=+1]

‎modules/microshift-configuring-hosts-for-mirror.adoc

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * microshift/running_applications/microshift-deploy-with-mirror-registry.adoc
4+
5+
:_content-type: PROCEDURE
6+
[id="microshift-configuring-hosts-for-mirror_{context}"]
7+
= Configuring hosts for mirror registry access
8+
9+
To configure a {product-title} host to use a mirror registry, you must give the {product-title} host access to the registry by creating a configuration file that maps the Red Hat registry host names to the mirror.
10+
11+
.Prerequisites
12+
* Your mirror host has access to the internet.
13+
* The mirror host can access the mirror registry.
14+
* You configured the mirror registry for use in your restricted network.
15+
* You downloaded the pull secret and modified it to include authentication to your mirror repository.
16+
17+
.Procedure
18+
. Log into your {product-title} host.
19+
20+
. Enable the SSL certificate trust on any host accessing the mirror registry by completing the following steps:
21+
22+
.. Copy the `rootCA.pem` file from the mirror registry, for example, `<registry_path>/quay-rootCA`, to the {product-title} host at the `/etc/pki/ca-trust/source/anchors` directory.
23+
.. Enable the certificate in the system-wide trust store configuration by running the following command:
24+
+
25+
[source,terminal]
26+
----
27+
$ sudo update-ca-trust
28+
----
29+
30+
. Create the `/etc/containers/registries.conf.d/999-microshift-mirror.conf` configuration file that maps the Red Hat registry host names to the mirror registry:
31+
+
32+
.Example mirror configuration file
33+
[source,terminal]
34+
----
35+
[[registry]]
36+
prefix = ""
37+
location = "<registry_host>:<port>" <1>
38+
mirror-by-digest-only = true
39+
insecure = false
40+
41+
[[registry]]
42+
prefix = ""
43+
location = "quay.io"
44+
mirror-by-digest-only = true
45+
[[registry.mirror]]
46+
location = "<registry_host>:<port>"
47+
insecure = false
48+
49+
[[registry]]
50+
prefix = ""
51+
location = "registry.redhat.io"
52+
mirror-by-digest-only = true
53+
[[registry.mirror]]
54+
location = "<registry_host>:<port>"
55+
insecure = false
56+
57+
[[registry]]
58+
prefix = ""
59+
location = "registry.access.redhat.com"
60+
mirror-by-digest-only = true
61+
[[registry.mirror]]
62+
location = "<registry_host>:<port>"
63+
insecure = false
64+
----
65+
<1> Replace `<registry_host>:<port>` with the host name and port of your mirror registry server, for example, `<microshift-quay:8443>`.
66+
67+
. Enable the {product-title} service by running the following command:
68+
+
69+
[source,terminal]
70+
----
71+
$ sudo systemctl enable microshift
72+
----
73+
74+
. Reboot the host by running the following command:
75+
+
76+
[source,terminal]
77+
----
78+
$ sudo reboot
79+
----

‎modules/microshift-downloading-container-images.adoc

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * microshift/running_applications/microshift-deploy-with-mirror-registry.adoc
4+
5+
:_content-type: PROCEDURE
6+
[id="microshift-downloading-container-images_{context}"]
7+
= Downloading container images
8+
9+
After you have located the container list and completed the mirroring prerequisites, download the container images to a host with internet access.
10+
11+
.Prerequisites
12+
13+
* You are logged into a host with access to the internet.
14+
* You have ensured that the `.pull-secret-mirror.json` file and `microshift-containers` directory contents are available locally.
15+
16+
.Procedure
17+
18+
. Install the `skopeo` tool used for copying the container images by running the following command:
19+
+
20+
[source,terminal]
21+
----
22+
$ sudo dnf install -y skopeo
23+
----
24+
25+
. Set the environment variable that points to the pull secret file:
26+
+
27+
[source,terminal]
28+
----
29+
$ PULL_SECRET_FILE=~/.pull-secret-mirror.json
30+
----
31+
32+
. Set the environment variable that points to the list of container images:
33+
+
34+
[source,terminal]
35+
----
36+
$ IMAGE_LIST_FILE=~/microshift-container-refs.txt
37+
----
38+
39+
. Set the environment variable that points to the destination directory for storing the downloaded data:
40+
+
41+
[source,terminal]
42+
----
43+
$ IMAGE_LOCAL_DIR=~/microshift-containers
44+
----
45+
46+
. Run the following script to download the container images to the `${IMAGE_LOCAL_DIR}` directory:
47+
+
48+
[source,terminal]
49+
----
50+
while read -r src_img ; do
51+
# Remove the source registry prefix
52+
dst_img=$(echo "${src_img}" | cut -d '/' -f 2-)
53+
54+
# Run the image download command
55+
echo "Downloading '${src_img}' to '${IMAGE_LOCAL_DIR}'"
56+
mkdir -p "${IMAGE_LOCAL_DIR}/${dst_img}"
57+
skopeo copy --all --quiet \
58+
--preserve-digests \
59+
--authfile "${PULL_SECRET_FILE}" \
60+
docker://"${src_img}" dir://"${IMAGE_LOCAL_DIR}/${dst_img}"
61+
62+
done < "${IMAGE_LIST_FILE}"
63+
----
64+
65+
. Transfer the image set to the target environment, such as air-gapped site. Then you can upload the image set into the mirror registry.

‎modules/microshift-get-mirror-reg-container-image-list.adoc

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * microshift/running_applications/microshift-deploy-with-mirror-registry.adoc
4+
5+
:_content-type: PROCEDURE
6+
[id="microshift-get-mirror-reg-container-image-list_{context}"]
7+
= Getting the {product-title} mirror registry container image list
8+
9+
To use a mirror registry, you must know which container image references are used by a specific version of {product-title}. These references are provided in the `release-<arch>.json` files that are part of the `microshift-release-info` RPM package.
10+
11+
.Prerequisites
12+
13+
* You have installed jq.
14+
15+
.Procedure
16+
17+
. Access the list of container image references by using one of the following methods:
18+
19+
** If the package is installed on the {product-title} host, get the location of the files by running the following command:
20+
+
21+
[source,terminal]
22+
----
23+
$ rpm -ql microshift-release-info
24+
----
25+
+
26+
.Example output
27+
[source,text]
28+
----
29+
/usr/share/microshift/release/release-x86_64.json
30+
----
31+
32+
** If the package is not installed on a {product-title} host, download and unpack the RPM package without installing it by running the following command:
33+
+
34+
[source,terminal]
35+
----
36+
$ rpm2cpio microshift-release-info*.noarch.rpm | cpio -idmv
37+
----
38+
+
39+
.Example output
40+
[source,text]
41+
----
42+
/usr/share/microshift/release/release-x86_64.json
43+
----
44+
45+
. Extract the list of container images into the `microshift-container-refs.txt` file by running the following commands:
46+
+
47+
[source,terminal]
48+
----
49+
$ RELEASE_FILE=/usr/share/microshift/release/release-$(uname -m).json
50+
----
51+
+
52+
[source,terminal]
53+
----
54+
$ jq -r '.images | .[]' ${RELEASE_FILE} > microshift-container-refs.txt
55+
----
56+
57+
[NOTE]
58+
====
59+
After the `microshift-container-refs.txt` file is created with the {product-title} container image list, you can append the file with other user-specific image references before running the mirroring procedure.
60+
====

‎modules/microshift-mirror-container-images.adoc

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * microshift/running_applications/microshift-deploy-with-mirror-registry.adoc
4+
5+
:_content-type: CONCEPT
6+
[id="microshift-mirror-container-images_{context}"]
7+
= Mirror container images into an existing registry
8+
9+
Using a custom air-gapped container registry, or mirror, is necessary with certain user environments and workload requirements. Mirroring allows for the transfer of container images and updates to air-gapped environments where they can be installed on a {product-title} instance.
10+
11+
To create an air-gapped mirror registry for {product-title} containers, you must complete the following steps:
12+
13+
* Get the container image list to be mirrored.
14+
* Configure the mirroring prerequisites.
15+
* Download images on a host with the internet access.
16+
* Copy the downloaded image directory to an air-gapped site.
17+
* Upload images to a mirror registry in an air-gapped site.
18+
* Configure your {product-title} hosts to use the mirror registry.

‎modules/microshift-mirroring-prereqs.adoc

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * microshift/running_applications/microshift-deploy-with-mirror-registry.adoc
4+
5+
:_content-type: CONCEPT
6+
[id="microshift-configuring-mirroring-prereqs_{context}"]
7+
= Configuring mirroring prerequisites
8+
9+
You must create a container image registry credentials file that allows the mirroring of images from your internet-connected mirror host to your air-gapped mirror. Follow the instructions in the "Configuring credentials that allow images to be mirrored" link provided in the "Additional resources" section. These instructions guide you to create a `~/.pull-secret-mirror.json` file on the mirror registry host that includes the user credentials for accessing the mirror.
10+
11+
[id="microshift-example-mirror-pull-secret-entry_{context}"]
12+
== Example mirror registry pull secret entry
13+
14+
For example, the following section is added to the pull secret file for the `microshift_quay:8443` mirror registry using `microshift:microshift` as username and password.
15+
16+
.Example mirror registry section for pull secret file
17+
[source,terminal]
18+
----
19+
"<microshift_quay:8443>": { <1>
20+
"auth": "<microshift_auth>", <2>
21+
"email": "<[email protected]>" <3>
22+
},
23+
----
24+
<1> Replace the `<registry_host>:<port>` value `microshift_quay:8443` with the host name and port of your mirror registry server.
25+
<2> Replace the `<microshift_auth>` value with the user password.
26+
<3> Replace the `</[email protected]>` value with the user email.

‎modules/microshift-upload-cont2-mirror-script.adoc

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
[source,sh]
2+
----
3+
# Use timestamp and counter as a tag on the target images to avoid
4+
# their overwrite by the 'latest' automatic tagging
5+
image_tag=mirror-$(date +%y%m%d%H%M%S)
6+
image_cnt=1
7+
8+
pushd "${IMAGE_LOCAL_DIR}" >/dev/null
9+
while read -r src_manifest ; do
10+
# Remove the manifest.json file name
11+
src_img=$(dirname "${src_manifest}")
12+
# Add the target registry prefix and remove SHA
13+
dst_img="${TARGET_REGISTRY}/${src_img}"
14+
dst_img=$(echo "${dst_img}" | awk -F'@' '{print $1}')
15+
16+
# Run the image upload command
17+
echo "Uploading '${src_img}' to '${dst_img}'"
18+
skopeo copy --all --quiet \
19+
--preserve-digests \
20+
--authfile "${IMAGE_PULL_FILE}" \
21+
dir://"${IMAGE_LOCAL_DIR}/${src_img}" docker://"${dst_img}:${image_tag}-${image_cnt}"
22+
# Increment the counter
23+
(( image_cnt += 1 ))
24+
25+
done < <(find . -type f -name manifest.json -printf '%P\n')
26+
popd >/dev/null
27+
----

0 commit comments

Comments
 (0)