From c03ed0809bc8e4143c1b900c50eaf350367a7a91 Mon Sep 17 00:00:00 2001 From: Gabriel McGoldrick Date: Fri, 12 Feb 2021 13:52:01 +0000 Subject: [PATCH] PROJQUAY-1573 Standalone Quay installs relies on floating container IPs --- deploy_quay/master.adoc | 22 +++- modules/con_quay_single_prereq.adoc | 10 +- modules/proc_deploy_quay_poc_conf.adoc | 2 +- modules/proc_deploy_quay_poc_db.adoc | 13 +- modules/proc_deploy_quay_poc_dns.adoc | 117 +++++++++++++++++ modules/proc_deploy_quay_poc_next.adoc | 20 +++ modules/proc_deploy_quay_poc_restart.adoc | 5 + modules/proc_deploy_quay_poc_run.adoc | 49 +++++++ modules/proc_deploy_quay_poc_run_use.adoc | 151 ---------------------- modules/proc_deploy_quay_poc_use.adoc | 77 +++++++++++ 10 files changed, 296 insertions(+), 170 deletions(-) create mode 100644 modules/proc_deploy_quay_poc_dns.adoc create mode 100644 modules/proc_deploy_quay_poc_next.adoc create mode 100644 modules/proc_deploy_quay_poc_restart.adoc create mode 100644 modules/proc_deploy_quay_poc_run.adoc delete mode 100644 modules/proc_deploy_quay_poc_run_use.adoc create mode 100644 modules/proc_deploy_quay_poc_use.adoc diff --git a/deploy_quay/master.adoc b/deploy_quay/master.adoc index d6de33f9c..9056f2a5f 100644 --- a/deploy_quay/master.adoc +++ b/deploy_quay/master.adoc @@ -7,9 +7,12 @@ include::modules/attributes.adoc[] include::modules/con_quay_intro.adoc[leveloffset=+1] -include::modules/con_quay_single_prereq.adoc[leveloffset=+1] -//include::modules/proc_deploy_quay_single.adoc[leveloffset=+1] +== Getting started with {productname} + +The {productname} registry can be deployed for non-production purposes on a single machine (either physical or virtual) with the following specifications. + +include::modules/con_quay_single_prereq.adoc[leveloffset=+2] ifeval::["{productname}" == "Red Hat Quay"] include::modules/proc_deploy_quay_poc_rhel.adoc[leveloffset=+2] @@ -21,8 +24,21 @@ include::modules/proc_deploy_quay_poc_redis.adoc[leveloffset=+2] include::modules/proc_deploy_quay_poc_conf.adoc[leveloffset=+2] -include::modules/proc_deploy_quay_poc_run_use.adoc[leveloffset=+1] +include::modules/proc_deploy_quay_poc_run.adoc[leveloffset=+2] + +include::modules/proc_deploy_quay_poc_use.adoc[leveloffset=+2] + + + +== Advanced {productname} deployment + +include::modules/proc_deploy_quay_poc_dns.adoc[leveloffset=+2] +include::modules/proc_deploy_quay_poc_restart.adoc[leveloffset=+2] + + + +include::modules/proc_deploy_quay_poc_next.adoc[leveloffset=1] //include::modules/proc_deploy_quay_guided.adoc[leveloffset=+1] diff --git a/modules/con_quay_single_prereq.adoc b/modules/con_quay_single_prereq.adoc index 11dd16e31..07886322f 100644 --- a/modules/con_quay_single_prereq.adoc +++ b/modules/con_quay_single_prereq.adoc @@ -1,8 +1,4 @@ -= Preparing a proof-of-concept deployment of {productname} - -The {productname} registry can be deployed for non-production purposes on a single machine (either physical or virtual) with the following specifications. - -== Prerequisites += Prerequisites ifeval::["{productname}" == "Red Hat Quay"] //* **Red Hat Enterprise Linux (RHEL)**: Obtain the latest Red Hat Enterprise Linux 7 server media from the link:https://access.redhat.com/downloads/content/69/ver=/rhel---7/7.9/x86_64/product-software[Downloads page] and follow the installation instructions from the link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/7/html/installation_guide/index[Red Hat Enterprise Linux 7 Installation Guide]. @@ -34,11 +30,7 @@ $ cat /etc/hosts This document uses `podman` for creating and deploying containers. If you do not have `podman` installed on your system, you should be able to use the equivalent `docker` commands. For more information on podman and related technologies, see link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html-single/building_running_and_managing_containers/index[Building, running, and managing Linux containers on Red Hat Enterprise Linux 8]. -== Restarting containers -Because the `--restart` option is not fully supported by podman, instead of using `--restart`, you could configure `podman` as a systemd service, as described -in -https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html-single/building_running_and_managing_containers/index#porting-containers-to-systemd-using-podman_building-running-and-managing-containers[Porting containers to systemd using Podman] diff --git a/modules/proc_deploy_quay_poc_conf.adoc b/modules/proc_deploy_quay_poc_conf.adoc index ab1ec09d2..2db00f390 100644 --- a/modules/proc_deploy_quay_poc_conf.adoc +++ b/modules/proc_deploy_quay_poc_conf.adoc @@ -52,7 +52,7 @@ The Redis key-value store is used to store real-time events and build logs. If y When all required fields have been set, validate your settings by choosing the Validate Configuration Changes button. If any errors are reported, continue editing your configuration until all required fields are valid and {productname} can connect to your database and Redis servers. -Once your configuration is valid, download the configuration file and then stop the quay container running the configuration editor. +Once your configuration is valid, download the configuration file and then stop the quay container that is running the configuration editor. diff --git a/modules/proc_deploy_quay_poc_db.adoc b/modules/proc_deploy_quay_poc_db.adoc index b928e2dbf..6cbf43bd2 100644 --- a/modules/proc_deploy_quay_poc_db.adoc +++ b/modules/proc_deploy_quay_poc_db.adoc @@ -14,14 +14,15 @@ $ setfacl -m u:26:-wx $QUAY/postgres .... * Use podman to run the Postgres container, specifying the username, password, database name and port, together with the volume definition for database data: + +[subs="verbatim,attributes"] .... $ sudo podman run -d --rm --name postgresql \ - -e POSTGRES_USER=user \ - -e POSTGRES_PASSWORD=pass \ - -e POSTGRES_DB=quay \ - -p 5432:5432 \ - -v $QUAY/postgres:/var/lib/postgresql/data:Z \ - postgres:10.12 + -e POSTGRES_USER=user \ + -e POSTGRES_PASSWORD=pass \ + -e POSTGRES_DB=quay \ + -p 5432:5432 \ + -v $QUAY/postgres:/var/lib/postgresql/data:Z \ + {productrepo}/rhel8/postgresql-10:1 .... * Install the Postgres `pg_trgm` module installed, as it is required by Quay: + diff --git a/modules/proc_deploy_quay_poc_dns.adoc b/modules/proc_deploy_quay_poc_dns.adoc new file mode 100644 index 000000000..3eb1b8049 --- /dev/null +++ b/modules/proc_deploy_quay_poc_dns.adoc @@ -0,0 +1,117 @@ += Using DNS + +The "Getting Started" section used dynamic IP addressing for the sake of convenience. If you want your deployment to survive container restarts, which typically result in changed IP addresses, you can implement a naming service. In this example, the link:https://github.com/containers/dnsname[dnsname] plugin is used to allow containers to resolve each other by name. + + +== Introduction to dnsname + +The `dnsname` plugin configures `dnsmasq` on a given CNI network so that containers can resolve each other by name. When configured, the container name and its IP address are added to a network specific hosts file that `dnsmasq` reads in. Similarly, when a container is removed from the network, it will remove the entry from the hosts file. Each CNI network will have its own `dnsmasq` instance. + + +== Deploying dnsname + +* Install the prerequisites for building `dnsname`: ++ +.... +$ sudo dnf install -y git make go dnsmasq +.... + +* Clone and build the repository ++ +.... +$ git clone https://github.com/containers/dnsname.git +$ cd dnsname/ +$ sudo make binaries install  PREFIX=/usr +.... + +This will install the `dnsname` plugin into `/usr/libexec/cni` where your CNI plugins should already exist. + + +== Configuring the default CNI network + +Edit the file `/etc/cni/net.d/87-podman-bridge.conflist` and add a stanza for the `dnsname` plugin, specifying your domain name, in this case 'dns.podman`: + +.... +{ +  "cniVersion": "0.4.0", +  "name": "podman", +  "plugins": [ + ... + { +      "type": "tuning" +    }, +    { +      "type": "dnsname", +      "domainName": "dns.podman", +      "capabilities": { +        "aliases": true +      } +    } +  ] +} +.... + +== Testing the naming service + +Ensure that the naming service is working by running a test to access one container from another, using the fully qualified name: + +.... +$ sudo podman run -dt --name web quay.io/libpod/alpine_nginx:latest +$ sudo podman run -it --name client quay.io/libpod/alpine_nginx:latest curl http://web.dns.podman/ +.... + +The `web` container should respond to the `client` request with the message `podman rulez`. + + +== Using names in the configuration tool + +The same basic commands are used to deploy the database and Redis for {productname}, but in the configuration tool you can now use names rather than IP addresses. + +* Stop the quay container if it is running and start it up in config mode, specifying the config volume if it already exists: ++ +[subs="verbatim,attributes"] +.... +$ sudo podman run --rm -it --name quay_config -p 8080:8080 \ + -v $QUAY/config:/conf/stack:Z \ + {productrepo}/{quayimage}:{productminv} config secret +.... + +* Update the database and Redis configuration to use the container name rather than the IP address: +** **Database Type:** Postgres +** **Database Server:** **postgresql** +** **Username:** user +** **Password:** pass +** **Database Name:** quay +** ... +** **Redis Hostname:** **redis** +** **Redis port:** 6379 (default) +** **Redis password:** strongpassword + +* Validate the updated configuration and then download it. Stop the quay container and extract the newly downloaded configuration bundle, overriding any existing files. + +== Redeploying using the naming service + +Restart the quay container, specifying the appropriate volumes for your configuration data and local storage for image data: + +[subs="verbatim,attributes"] +.... +$ sudo podman run --rm -p 8080:8080 \ + --name=quay \ + -v $QUAY/config:/conf/stack:Z \ + -v $QUAY/storage:/datastorage:Z \ + {productrepo}/{quayimage}:{productminv} +.... + +Confirm that the redeployment has been successful after the switch to using the naming service. Log in to quay with the user you created earlier, either using the UI at `quay:8080` or via the command line using `sudo podman login --tls-verify=false quay:8080`. + +== Configuring a new network + +Instead of using the default network, you can create a new network with the command `sudo podman create network `. To configure the new network to use dnsname, edit the file `/etc/cni/net.d/.conflist` and add the dnsname stanza as in the default example. When running the `podman run` command, specify the new network using the `--network` flag, for example: + +.... +$ sudo podman run -dt --name web --network \ + quay.io/libpod/alpine_nginx:latest + +$ sudo podman run -it --name client --network \ + quay.io/libpod/alpine_nginx:latest curl http://web.dns.podman/ +.... \ No newline at end of file diff --git a/modules/proc_deploy_quay_poc_next.adoc b/modules/proc_deploy_quay_poc_next.adoc new file mode 100644 index 000000000..f9344f237 --- /dev/null +++ b/modules/proc_deploy_quay_poc_next.adoc @@ -0,0 +1,20 @@ += Next steps + +This document shows how to configure and deploy a proof-of-concept version of {productname}. For more information on deploying to a production environment, see the guide "Deploy {productname} - High Availability". + +The "Use {productname}" guide shows you how to: + +* Add users and repositories +* Use tags +* Automatically build Dockerfiles with build workers +* Set up build triggers +* Add notifications for repository events + + +The "Manage {productname}" guide shows you how to: + +* Use SSL and TLS +* Enable security scanning with Clair +* Use repository mirroring +* Configure LDAP authentication +* Use georeplication of storage diff --git a/modules/proc_deploy_quay_poc_restart.adoc b/modules/proc_deploy_quay_poc_restart.adoc new file mode 100644 index 000000000..d847b2bda --- /dev/null +++ b/modules/proc_deploy_quay_poc_restart.adoc @@ -0,0 +1,5 @@ += Restarting containers + +Because the `--restart` option is not fully supported by podman, you can configure `podman` as a systemd service, as described +in +https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html-single/building_running_and_managing_containers/index#porting-containers-to-systemd-using-podman_building-running-and-managing-containers[Porting containers to systemd using Podman] \ No newline at end of file diff --git a/modules/proc_deploy_quay_poc_run.adoc b/modules/proc_deploy_quay_poc_run.adoc new file mode 100644 index 000000000..e600878b0 --- /dev/null +++ b/modules/proc_deploy_quay_poc_run.adoc @@ -0,0 +1,49 @@ += Deploying {productname} + + +== Prerequisites + +* Your database and redis servers are running. +* You have generated a valid configuration bundle. +* You have stopped the quay container that you used to run the configuration editor. + + +== Prepare config folder + +Unpack the configuration bundle so that Quay can use it: +.... +$ mkdir $QUAY/config +$ cp quay-config.tar.gz $QUAY/config +$ cd $QUAY/config +$ tar xvf quay-config.tar.gz +.... + +== Prepare local storage for image data + +In this proof-of-concept deployment, use the local file system to store the registry images: +.... +$ mkdir $QUAY/storage +$ setfacl -m u:1001:-wx $QUAY/storage +.... + +== Deploy the {productname} registry + +Use podman to run the quay container, specifying the appropriate volumes for your configuration data and local storage for image data: +[subs="verbatim,attributes"] +.... +$ sudo podman run --rm -p 8080:8080 \ + --name=quay \ + -v $QUAY/config:/conf/stack:Z \ + -v $QUAY/storage:/datastorage:Z \ + {productrepo}/{quayimage}:{productminv} +.... + + + + + + + + + + diff --git a/modules/proc_deploy_quay_poc_run_use.adoc b/modules/proc_deploy_quay_poc_run_use.adoc deleted file mode 100644 index 3e9d27c18..000000000 --- a/modules/proc_deploy_quay_poc_run_use.adoc +++ /dev/null @@ -1,151 +0,0 @@ -= Deploying and using {productname} - -This chapter shows you how to deploy {productname} using the configuration you have created, and then how to get started using the registry. - -== Deploying {productname} - - -=== Prerequisites - -* Your database and redis servers are running. -* You have generated a valid configuration bundle. -* You have stopped the quay container that you used to run the configuration editor. - - -=== Prepare config folder - -Unpack the configuration bundle so that Quay can use it: -.... -$ mkdir $QUAY/config -$ cp quay-config.tar.gz $QUAY/config -$ cd $QUAY/config -$ tar xvf quay-config.tar.gz -.... - -=== Prepare local storage for image data - -In this proof-of-concept deployment, use the local file system to store the registry images: -.... -$ mkdir $QUAY/storage -$ setfacl -m u:1001:-wx $QUAY/storage -.... - -=== Deploy the {productname} registry - -Use podman to run the quay container, specifying the appropriate volumes for your configuration data and local storage for image data: -[subs="verbatim,attributes"] -.... -$ sudo podman run --rm -p 8080:8080 \ - --name=quay \ - -v $QUAY/config:/conf/stack:Z \ - -v $QUAY/storage:/datastorage:Z \ - {productrepo}/{quayimage}:{productminv} -.... - - - -== Using {productname} - -Use your browser to access the user interface for the {productname} registry at `quay:8080` (assuming you have configured the `quay` hostname to point at 127.0.0.1 in your hosts file). Select 'Create User' and add a user, for example, `quayadmin` with a password `password`. - -You can now use the user interface to create new organizations and repositories, and to search and browse existing repositories. Alternatively, you can use the command line interface to interact with the registry and to pull and push images. - -From the command line, log in to the registry: - -.... -$ sudo podman login --tls-verify=false quay:8080 -Username: quayadmin -Password: -Login Succeeded! -.... - -=== Push and pull images - -To test pushing and pulling images from the {productname} registry, first pull a sample image from an external registry: - -.... -$ sudo podman pull busybox -Trying to pull docker.io/library/busybox... -Getting image source signatures -Copying blob 4c892f00285e done   -Copying config 22667f5368 done   -Writing manifest to image destination -Storing signatures -22667f53682a2920948d19c7133ab1c9c3f745805c14125859d20cede07f11f9 -.... - -Use the `podman images` command to see the local copy: - -.... -$ sudo podman images -REPOSITORY                          TAG      IMAGE ID       CREATED         SIZE -docker.io/library/busybox           latest   22667f53682a   14 hours ago    1.45 MB -... -.... - - -Tag this image, in preparation for pushing it to the {productname} registry: - -.... -$ sudo podman tag docker.io/library/busybox quay:8080/quayadmin/busybox:test -.... - - -Now push the image to the {productname} registry: - -.... -$ sudo podman push --tls-verify=false quay:8080/quayadmin/busybox:test -Getting image source signatures -Copying blob 6b245f040973 done   -Copying config 22667f5368 done   -Writing manifest to image destination -Storing signatures -.... - -At this point, you can use your browser to see the tagged image in your repository. To test access to the image from the command line, first delete the local copy of the image: - -.... -$ sudo podman rmi quay:8080/quayadmin/busybox:test -Untagged: quay:8080/quayadmin/busybox:test -.... - -Now pull the image again, this time from your {productname} registry: - -.... -$ sudo podman pull --tls-verify=false quay:8080/quayadmin/busybox:test -Trying to pull quay:8080/quayadmin/busybox:test... -Getting image source signatures -Copying blob 6ef22a7134ba [--------------------------------------] 0.0b / 0.0b -Copying config 22667f5368 done   -Writing manifest to image destination -Storing signatures -22667f53682a2920948d19c7133ab1c9c3f745805c14125859d20cede07f11f9 -.... - -== Next steps - -This document shows how to configure and deploy a proof-of-concept version of {productname}. For more information on deploying to a production environment, see the guide "Deploy {productname} - High Availability". - -The "Use {productname}" guide shows you how to: - -* Add users and repositories -* Use tags -* Automatically build Dockerfiles with build workers -* Set up build triggers -* Add notifications for repository events - - -The "Manage {productname}" guide shows you how to: - -* Use SSL and TLS -* Enable security scanning with Clair -* Use repository mirroring -* Configure LDAP authentication -* Use georeplication of storage - - - - - - - diff --git a/modules/proc_deploy_quay_poc_use.adoc b/modules/proc_deploy_quay_poc_use.adoc new file mode 100644 index 000000000..e3ef407c8 --- /dev/null +++ b/modules/proc_deploy_quay_poc_use.adoc @@ -0,0 +1,77 @@ += Using {productname} + +Use your browser to access the user interface for the {productname} registry at `quay:8080` (assuming you have configured the `quay` hostname to point at 127.0.0.1 in your hosts file). Select 'Create User' and add a user, for example, `quayadmin` with a password `password`. + +You can now use the user interface to create new organizations and repositories, and to search and browse existing repositories. Alternatively, you can use the command line interface to interact with the registry and to pull and push images. + +From the command line, log in to the registry: + +.... +$ sudo podman login --tls-verify=false quay:8080 +Username: quayadmin +Password: +Login Succeeded! +.... + +== Push and pull images + +To test pushing and pulling images from the {productname} registry, first pull a sample image from an external registry: + +.... +$ sudo podman pull busybox +Trying to pull docker.io/library/busybox... +Getting image source signatures +Copying blob 4c892f00285e done +Copying config 22667f5368 done +Writing manifest to image destination +Storing signatures +22667f53682a2920948d19c7133ab1c9c3f745805c14125859d20cede07f11f9 +.... + +Use the `podman images` command to see the local copy: + +.... +$ sudo podman images +REPOSITORY TAG IMAGE ID CREATED SIZE +docker.io/library/busybox latest 22667f53682a 14 hours ago 1.45 MB +... +.... + + +Tag this image, in preparation for pushing it to the {productname} registry: + +.... +$ sudo podman tag docker.io/library/busybox quay:8080/quayadmin/busybox:test +.... + + +Now push the image to the {productname} registry: + +.... +$ sudo podman push --tls-verify=false quay:8080/quayadmin/busybox:test +Getting image source signatures +Copying blob 6b245f040973 done +Copying config 22667f5368 done +Writing manifest to image destination +Storing signatures +.... + +At this point, you can use your browser to see the tagged image in your repository. To test access to the image from the command line, first delete the local copy of the image: + +.... +$ sudo podman rmi quay:8080/quayadmin/busybox:test +Untagged: quay:8080/quayadmin/busybox:test +.... + +Now pull the image again, this time from your {productname} registry: + +.... +$ sudo podman pull --tls-verify=false quay:8080/quayadmin/busybox:test +Trying to pull quay:8080/quayadmin/busybox:test... +Getting image source signatures +Copying blob 6ef22a7134ba [--------------------------------------] 0.0b / 0.0b +Copying config 22667f5368 done +Writing manifest to image destination +Storing signatures +22667f53682a2920948d19c7133ab1c9c3f745805c14125859d20cede07f11f9 +....