Configuring the image registry

Do the following steps to setup a private docker registry or push images to a public docker registry.

Verify that Docker exists.
a. Check Docker version. If Docker is installed, you can get the detailed information about the docker version. Docker 18.02 or higher is required.
b. If your environment has no Docker, you need to install one. See Docker documentation about how to install Docker. Make sure to stop Docker Daemon before you upgrade Docker to the new version.
```
sudo systemctl stop docker.service
```
c. Download prepareImages.sh from GitHub repo. You can directly run the following command to download:
```
export UA_INSTALL=/var/uainstall
mkdir -p $UA_INSTALL
cd $UA_INSTALL
wget https://raw.githubusercontent.com/IBM/cp4mcm-samples/master/monitoring/2.3/prepareImages.sh
```
Save the file to $UA_INSTALL directory and make the file executable:
```
cd $UA_INSTALL
chmod +x prepareImages.sh
```
d. Enable experimental. When you prepare images, command docker manifest create is used, so you need to enable docker experimental features by editing /root/.docker/config.json to set experimental to enabled. See the following example:
```
{
   "experimental": "enabled"
}
```

Download required images from IBM Entitled Registry.
Note: To get the Entitlement key, you need to log in to MyIBM Container Software Library by using the IBMid and password that are associated with the entitled software.

DOCKERREG=cp.icr.io
IMAGE_GROUP=cp/cp4mcm
DOCKERREG_USER=cp
DOCKERREG_PASS=<ENTITLED_KEY_YOU_COPIED_ABOVE>
IMAGETAG=2.3.7

a. Download images to specified folder.

mkdir -p $UA_INSTALL/ua-pkg/images

b. Login the entitlement registry.

docker login $DOCKERREG -u $DOCKERREG_USER -p $DOCKERREG_PASS

c. Download the images and save to files for further use.

image_arr=("ua-operator" "ua-cloud-monitoring" "ua-plugins" "ua-repo" "reloader")
for image in ${image_arr[@]};
do 
  docker pull $DOCKERREG/$IMAGE_GROUP/${image}:$IMAGETAG
  docker tag $DOCKERREG/$IMAGE_GROUP/${image}:$IMAGETAG ${image}:$IMAGETAG 
  docker save -o ${image}_$IMAGETAG.tar ${image}:$IMAGETAG
  docker rmi $DOCKERREG/$IMAGE_GROUP/${image}:$IMAGETAG  ${image}:$IMAGETAG 
done;

Configure image registry. You can choose any of the following image registries according to your system requirements:
- Option 1 - Use public docker image registries, for example, quay.io
- Option 2 - Create a private image registry

Option 1 - Use public docker image registries, for example, quay.io

Make sure you have user account in quay.io.

Create environment variables for quay.io:

DOCKERREG=quay.io
IMAGE_GROUP=<your_group_in_registry>
DOCKERREG_USER=<your_registry_user_name>
DOCKERREG_PASS=<you_registry_password>

See the following example:

DOCKERREG=quay.io
IMAGE_GROUP=user1
DOCKERREG_USER=user1
DOCKERREG_PASS=password1

Load and push images into your registry.
1. Log in quay.io.
```
docker login quay.io --username $DOCKERREG_USER
```
2. Run prepareImage.sh:
```
cd $UA_INSTALL
```
```
./prepareImages.sh $UA_INSTALL quay.io/$IMAGE_GROUP
```
  You can set the following arguments:
  - Directory for UA installation files
  - Docker registry and image group split with /
  - (optional) image that you want to push except for the default list (ua-operator ua-cloud-monitoring ua-repo ua-plugins reloader)
    - This example loads and pushes images for ua-operator/ua-cloud-monitoring/ua-repo/ua-plugins/reloader/k8-monitor/k8sdc-operator:
```
./prepareImages.sh  /var/uainstall  uaocp.fyre.ibm.com:5555/ua 'k8-monitor k8sdc-operator'
```
    - This example loads and pushes images for ua-operator/ua-cloud-monitoring/ua-repo/ua-plugins/reloader only:
```
./prepareImages.sh  /var/uainstall  uaocp.fyre.ibm.com:5555/ua
```
Create environment variables where you want to install the UA plug-in repo or Unified Agent.
See the following example:
```
DOCKERREG=quay.io
IMAGE_GROUP=user1
DOCKERREG_USER=user1
DOCKERREG_PASS=password1
IMAGETAG=2.3.7
```

Option 2 - Create your own private docker registry

Set up a multi-architecture docker registry.
Note: The following procedure creates a simple registry that stores data in the /opt/registry directory. Before you set up the docker registry, ensure that you have a Red Hat Enterprise Linux (RHEL) server on your network to use as the registry host. For other platforms, see the official documentation of Private Docker Registry.
Complete the following steps to set up the docker registry:
1. Check whether Docker is installed:
```
docker version
```
2. Install Docker by running yum -y install docker if you have not installed Docker in this host. But if you plan to use this environment to push images, it is recommended to install Docker 18.02 or higher. See Docker documentation about how to install Docker.
3. Install the required packages (httpd-tools).
```
yum -y install httpd-tools
```
4. Create folders for the registry.
```
mkdir -p /opt/registry/{auth,certs,data}
```
5. It is highly recommended to secure your registry by using a TLS certificate that is issued by a known CA. If you do not have an existing certificate that is issued by trusted certificate authority, you can generate a self-signed certificate.
```
cd /opt/registry/certs
openssl req -newkey rsa:4096 -nodes -sha256 -keyout domain.key -x509 -days 365 -out domain.crt
```
  At the prompts, provide the required values for the certificate:
  - Country Name (2 letter code): Specify the two-letter ISO country code for your location. See the ISO 3166 country codes standard.
  - State or Province Name (full name): Enter the full name of your state or province.
  - Locality Name (for example, city): Enter the name of your city.
  - Organization Name (for example, company): Enter your company name.
  - Organizational Unit Name (for example, section): Enter your department name.
  - Common Name (for example, your name, or your server’s hostname): Enter the hostname for the registry host. Ensure that your hostname is in DNS and that it resolves to the expected IP address.
    Note: Ensure that you enter the hostname for the Common Name, which can be resolved to the expected IP address when you log in docker registry.
  - Email Address: Enter your email address. For more information, see the req description in the OpenSSL documentation.
6. Set up environment variable for setting up registry:
  1. Specify username and password for your registry. You use this username and password to log in to the docker registry.
```
DOCKERREG_USER=
DOCKERREG_PASS=
```
  2. Specify the Common Name that is specified in your certification:
```
DOCKER_REG_HOST_NAME=
```
  3. Specify the port that your docker registry uses to serve content.
```
DOCKER_REG_HOST_PORT=
```
    See the following example:
```
DOCKERREG_USER=admin
DOCKERREG_PASS=admin
DOCKER_REG_HOST_NAME=uaocp-inf.fyre.ibm.com
DOCKER_REG_HOST_PORT=5555
DOCKERREG=$DOCKER_REG_HOST_NAME:$DOCKER_REG_HOST_PORT
```
7. Run the following commands to complete the setup.
  1. Generate a username and a password for your registry that uses the bcrpt format.
```
htpasswd -bBc /opt/registry/auth/htpasswd $DOCKERREG_USER $DOCKERREG_PASS
```
  2. Create the docker-registry container to host your registry.
```
docker run --name mirror-registry -p $DOCKER_REG_HOST_PORT:5000 \
      -v /opt/registry/data:/var/lib/registry:z \
      -v /opt/registry/auth:/auth:z \
      -e "REGISTRY_AUTH=htpasswd" \
      -e "REGISTRY_AUTH_HTPASSWD_REALM=Registry Realm" \
      -e REGISTRY_AUTH_HTPASSWD_PATH=/auth/htpasswd \
      -v /opt/registry/certs:/certs:z \
      -e REGISTRY_HTTP_TLS_CERTIFICATE=/certs/domain.crt \
      -e REGISTRY_HTTP_TLS_KEY=/certs/domain.key \
      -e REGISTRY_COMPATIBILITY_SCHEMA1_ENABLED=true \
      -d docker.io/library/registry:2
```
    Note: If you encounter an error like toomanyrequests: You have reached your pull rate limit., you might need to log in to the docker hub with your own id, for example, docker login docker.io -u <Replace with your_docker_id> -p <Repalce with your_docker_password>, then run step 2 again.
  3. Open the required ports for your registry.
```
systemctl start firewalld
firewall-cmd --add-port=$DOCKER_REG_HOST_PORT/tcp --zone=internal --permanent
firewall-cmd --add-port=$DOCKER_REG_HOST_PORT/tcp --zone=public   --permanent
firewall-cmd --reload
```
8. If you are using a self-signed certificate, add it to your list of trusted certificates:
```
cp /opt/registry/certs/domain.crt /etc/pki/ca-trust/source/anchors/
update-ca-trust
```
9. Confirm that the registry is available.
```
curl -u $DOCKERREG_USER:$DOCKERREG_PASS -k https://$DOCKER_REG_HOST_NAME:$DOCKER_REG_HOST_PORT/v2/_catalog
```
  You can see the following example output:
```
{"repositories":[]}
```
Load and push images into your registry.
1. Log in to the private Docker registry.
```
docker login --username $DOCKERREG_USER $DOCKERREG
```
2. Push images.
```
./prepareImages.sh $UA_INSTALL $DOCKERREG/ua
```
  You can set the following arguments:
  - Directory for UA installation files
  - Docker registry and image group split with /
  - (optional) image that you want to push except for the default list (ua-operator ua-cloud-monitoring ua-repo ua-plugins reloader)
    1. This example loads and pushes images for ua-operator/ua-cloud-monitoring/ua-repo/ua-plugins/reloader/k8-monitor/k8sdc-operator:
```
./prepareImages.sh  /var/uainstall  uaocp.fyre.ibm.com:5555/ua 'k8-monitor k8sdc-operator'
```
    2. This example loads and pushes images for ua-operator/ua-cloud-monitoring/ua-repo/ua-plugins/reloader only
```
./prepareImages.sh  /var/uainstall  uaocp.fyre.ibm.com:5555/ua
```
Do the following steps to use the private image registry on target environment.
1. Go to the target machine where you want to install the plug-in repo or Unified Agent.
2. Instruct Docker daemon to trust the self-signed certificate on target machine. This step is only required if you use a self-signed certificate.
  Note: Copy the self-signed certificate to /etc/docker/certs.d/<your_registry_host_name>:<your_registry_host_port>/ca.crt from the private registry server. Otherwise, you will get a x509: certificate signed by unknown authority error when you issue a docker command such as docker login.
  Run the following command:
```
mkdir -p /etc/docker/certs.d/<Replace with your_registry_host_name>:<Repalce_with_your_registry_host_port>
scp root@<Replace_with_your_registry_host_name>:/opt/registry/certs/domain.crt /etc/docker/certs.d/<Replace_with_your_registry_host_name>:<Replace_with_your_registry_host_port>/ca.crt
```
  Example:
```
mkdir -p /etc/docker/certs.d/journals-inf.fyre.ibm.com:5555
scp root@journals-inf.fyre.ibm.com:/opt/registry/certs/domain.crt /etc/docker/certs.d/journals-inf.fyre.ibm.com:5555/ca.crt
```
3. Create environment variables on the target machine. See the following example:
```
DOCKERREG=uaocp-inf.fyre.ibm.com:5555
IMAGE_GROUP=ua
DOCKERREG_USER=admin
DOCKERREG_PASS=admin
IMAGETAG=2.3.7
```