PROJQUAY-1573 Standalone Quay installs relies on floating container IPs

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]
 

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]
 
 
 

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.
 
 
 

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:
 +

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 <network-name>`. To configure the new network to use dnsname, edit the file `/etc/cni/net.d/<network-name>.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 <network-name> \
+  quay.io/libpod/alpine_nginx:latest
+
+$ sudo podman run -it --name client --network <network-name>  \
+  quay.io/libpod/alpine_nginx:latest curl http://web.dns.podman/
+....

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

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]

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}
+....
+
+
+
+
+
+
+
+
+
+