Create an Image Registry with mirror-registry
An image registry provided by your organization is strongly recommended as the platform image registry. If you already have an image registry, skip this chapter and continue with Prepare the Target-Version Payload.
If no image registry is available, you can use mirror-registry. mirror-registry is a small-scale image registry that can serve as the target registry for platform images.
mirror-registry is not a substitute for a production-grade, highly available image registry.
TOC
PrerequisitesAbout mirror-registrymirror-registry LimitationsInstall mirror-registrySupported FlagsPrepare the Package and CredentialsDeploy with Local StorageDeploy with S3-Compatible Object StorageVerify the DeploymentDeploy mirror-registry for Disaster RecoveryUpdate mirror-registryReplace the mirror-registry SSL/TLS CertificatesTroubleshoot mirror-registryPrerequisites
- A machine outside all clusters. Do not use a node of any cluster.
- Linux with systemd and OpenSSL installed. You must be able to run commands as
root. - 4 or more vCPUs.
- 8 GB or more of RAM.
- Local disk or S3-compatible object storage. With a local disk, the file system that holds the data directory needs at least 200 GB. LVM is recommended so that you can expand the storage later. See Deploy with Local Storage.
- The registry port (
443by default) is reachable from the installation node and every cluster node that pulls platform images.
Storage requirements depend on your environment. For example, you need more space to retain multiple versions or multiple CPU architectures. With a local disk, monitor the storage used by uploaded images.
About mirror-registry
Deploying requires an image registry that stores the images of platform components. Installing and later upgrading the platform depend on this registry. If you can provide an image registry as the platform image registry, you do not need mirror-registry.
If no image registry is available, you can use mirror-registry. mirror-registry is a small-scale image registry provided with , available on the Core Package download page. It is based on the native Distribution registry, runs as a single instance managed by systemd, and is accessible only over HTTPS. By default, it listens on port 443 and uses local storage and an automatically generated self-signed certificate. You must configure credentials when you deploy it. Optional settings include the port, custom TLS certificates, and S3-compatible object storage.
mirror-registry Limitations
The following limitations apply to mirror-registry:
- mirror-registry is not a highly available registry. With S3-compatible object storage, the image data is stored off the machine, but the registry service remains a single instance. mirror-registry is not a substitute for a production-grade, highly available image registry.
- mirror-registry is not recommended for production environments. It is a single-point image registry. If it goes down, Pods scheduled to other nodes might fail to start because they cannot pull images, which affects platform availability.
- mirror-registry supports hosting only platform images.
- Content built by users, including application images, should not be hosted in mirror-registry.
- Sharing mirror-registry across multiple clusters is not recommended, because the clusters then depend on the same registry, which creates a single point of failure when you update them. Use a production-grade, highly available image registry provided by your organization for multiple clusters.
Install mirror-registry
This procedure installs mirror-registry on the local machine and starts an image registry, which listens on port 443 by default, to store platform images.
The installation makes the following changes to the machine: it creates the /opt/mirror-registry directory, which contains the binaries, configuration, and local storage, and it creates the mirror-registry systemd service, which starts at boot. The installation script does not change firewall rules.
Supported Flags
The following flags apply to the install and upgrade commands. Default values apply to the first installation. When you run install again or run upgrade, unspecified flags keep their existing configuration.
General flags
Storage flags
Prepare the Package and Credentials
-
Download the
mirror-registry-<version>.<arch>.tar.gzpackage that matches the machine architecture from the Core Package download page in the Customer Portal, and extract it: -
Create the credentials file. Line 1 is the username and line 2 is the password:
The username cannot contain whitespace or
:, and the password can be at most 72 bytes. You can delete this file after the installation.
Deploy with Local Storage
To use the default data directory, /opt/mirror-registry/data, make sure that its file system has at least 200 GB, and run:
To store the data on a dedicated data disk, prepare the disk with LVM, and then install mirror-registry with --data-dir:
-
Create a logical volume on the data disk and mount it. The following example uses the empty disk
/dev/vdband creates a dedicated volume group,vg_registry, instead of reusing the volume group of the system disk, so that the image data does not share the root file system. The commands erase all data on the disk and require thelvm2package. Replace the device name and the mount point for your environment. The mount point must be on a writable path.The
dfoutput shows the logical volume mounted on/cpaas/registry. The/etc/fstabentry mounts it automatically after a reboot. -
Install mirror-registry with the mount point as the data directory. The following example also changes the listening port:
To expand the storage later, add a disk, for example /dev/vdc, to the volume group, and then extend the logical volume and its file system:
Deploy with S3-Compatible Object Storage
-
Create a bucket on the S3 service, and prepare an access key that can list, read, write, and delete objects and perform multipart uploads in the bucket. The script does not create the bucket. Paths inside the bucket do not need to exist in advance.
-
Create the S3 credentials file. Line 1 is the access key and line 2 is the secret key:
-
Set
--s3-endpointand--s3-regionfor your storage: -
Install mirror-registry:
If the bucket has other content, add
--s3-root-dir mirror/registryto store the data under a path inside the bucket.At the end of the installation, the script checks S3 connectivity. If
S3 check failedappears, check the endpoint, bucket name, region, and keys.
Verify the Deployment
-
Confirm that the registry is available:
A new registry returns
{"repositories":[]}. If you changed the port, add it to the URL. -
Continue with Prepare the Target-Version Payload to upload the platform images to this registry. Set the registry address to
<host-or-IPv4>[:port]. If the registry uses IPv6, use a domain name. Use the username and password from the credentials file.
If images are affected by storage layer problems, you can upload the platform images again, or reinstall mirror-registry on more stable storage.
Deploy mirror-registry for Disaster Recovery
For global cluster disaster recovery, deploy a mirror-registry on both the primary side and the standby side, and use a dedicated domain name as the image registry address. The domain name normally resolves to the mirror-registry on the primary cluster side. If a failure occurs, switch its DNS resolution to the mirror-registry on the standby cluster side.
The two mirror-registry instances do not synchronize data, so you must upload the platform images to both. Until the DNS resolution is switched, cluster nodes cannot pull images from mirror-registry.
Prerequisites
- A machine on each of the primary side and the standby side that meets the prerequisites.
- A domain name dedicated to the image registry that all cluster nodes can resolve. This domain name is independent of the domain name of the platform access address.
Procedure
-
Install mirror-registry on both sides. Both sides must use the same username and password, so we recommend using the same credentials file. The listening port must also be the same.
-
Resolve the image registry domain name to the mirror-registry on the primary cluster side.
-
Upload the platform images to the mirror-registry on each side. When you upload, set the registry address to the address of the corresponding machine. For details, see Prepare the Target-Version Payload.
-
When you install the primary and standby clusters, specify the same image registry address, username, and password on both sides.
If a failure occurs
- Switch the DNS resolution of the image registry domain name to the mirror-registry on the standby cluster side.
Update mirror-registry
This procedure updates mirror-registry by using the upgrade command. Updates provide new features, bug fixes, and security vulnerability fixes.
The service restarts during the update, so the registry is briefly unavailable.
Prerequisites
- You have installed mirror-registry.
Procedure
-
Extract the new package and run the following command from its directory:
Unspecified flags keep their existing configuration. If the service is not healthy after the update, it automatically rolls back to the previous version.
Replace the mirror-registry SSL/TLS Certificates
Use this procedure to replace the current certificate or to update it periodically.
The service restarts after you run the following commands, so the registry is briefly unavailable.
Prerequisites
- You have installed mirror-registry.
Procedure
-
To use your own certificate, run the following command. Specify both flags together. The private key cannot be passphrase-protected:
-
If the IP address or host name of the machine changes, regenerate the self-signed certificate:
NoteThe automatically generated certificate covers the host name,
localhost,127.0.0.1,::1, and the global IP addresses of the machine at generation time, and is valid for 10 years. If you access the registry through another domain name, use your own certificate.
Troubleshoot mirror-registry
mirror-registry installs the mirror-registry.service systemd service.
Prerequisites
- You have installed mirror-registry.
Procedure
-
Check the service status:
-
Check the service logs: