Add a keycloak tutorial

This adds a Zuul quick-start tutorial add-on that sets up a keycloak
server.  This can be used by new users to demonstrate the admin api
capability, or developers for testing.

Change-Id: I7ce73ce499dd840ad43fd8d0c6544177d02a7187
Co-Authored-By: Matthieu Huin <mhuin@redhat.com>

doc/source/examples/docker-compose.yaml

@@ -1,6 +1,4 @@
-# Version 2 is the latest that is supported by docker-compose in
-# Ubuntu Xenial.
-version: '2'
+version: '2.1'
 
 services:
   gerrit:
@@ -10,6 +8,8 @@ services:
       - "29418:29418"
     environment:
       - CANONICAL_WEB_URL=http://localhost:8080/
+    networks:
+      - zuul
   gerritconfig:
     image: docker.io/zuul/zuul-executor
     environment:
@@ -27,6 +27,8 @@ services:
     # NOTE(pabelanger): Be sure to update this line each time we change the
     # default version of ansible for Zuul.
     command: "/usr/local/lib/zuul/ansible/2.9/bin/ansible-playbook /var/playbooks/setup.yaml"
+    networks:
+      - zuul
   zk:
     image: docker.io/zookeeper
     hostname: examples_zk_1.examples_default
@@ -35,6 +37,8 @@ services:
       - "certs:/var/certs:z"
       - "./zoo.cfg:/conf/zoo.cfg:z"
     command: "sh -c '/var/playbooks/wait-to-start-certs.sh && zkServer.sh start-foreground'"
+    networks:
+      - zuul
   mysql:
     image: docker.io/mariadb
     environment:
@@ -44,6 +48,8 @@ services:
       MYSQL_PASSWORD: secret
       # Work around slow db startup when writing TZINFO data.
       MYSQL_INITDB_SKIP_TZINFO: 1
+    networks:
+      - zuul
   scheduler:
     depends_on:
       - gerritconfig
@@ -62,10 +68,12 @@ services:
     #        This needs to be changes such that ansible is not required for startup.
     image: docker.io/zuul/zuul-scheduler
     volumes:
-      - "./etc_zuul/:/etc/zuul/:z"
+      - "${ZUUL_TUTORIAL_CONFIG:-./etc_zuul/}:/etc/zuul/:z"
       - "./playbooks/:/var/playbooks/:z"
       - "sshkey:/var/ssh:z"
       - "certs:/var/certs:z"
+    networks:
+      - zuul
   web:
     command: |
       sh -c '/var/playbooks/wait-to-start-certs.sh && \
@@ -80,9 +88,11 @@ services:
     environment:
       ZUUL_MYSQL_PASSWORD: secret
     volumes:
-      - "./etc_zuul/:/etc/zuul/:z"
+      - "${ZUUL_TUTORIAL_CONFIG:-./etc_zuul/}:/etc/zuul/:z"
       - "./playbooks/:/var/playbooks/:z"
       - "certs:/var/certs:z"
+    networks:
+      - zuul
   executor:
     privileged: true
     environment:
@@ -94,12 +104,14 @@ services:
       - scheduler
     image: docker.io/zuul/zuul-executor
     volumes:
-      - "./etc_zuul/:/etc/zuul/:z"
+      - "${ZUUL_TUTORIAL_CONFIG:-./etc_zuul/}:/etc/zuul/:z"
       - "./playbooks/:/var/playbooks/:z"
       - "sshkey:/var/ssh:z"
       - "logs:/srv/static/logs:z"
       - "certs:/var/certs:z"
     command: "sh -c '/var/playbooks/wait-to-start-certs.sh && zuul-executor -f'"
+    networks:
+      - zuul
   node:
     build:
       dockerfile: node-Dockerfile
@@ -110,6 +122,8 @@ services:
         no_proxy: "${no_proxy},gerrit"
     volumes:
       - "nodessh:/root/.ssh:z"
+    networks:
+      - zuul
   launcher:
     depends_on:
       - zk
@@ -121,6 +135,8 @@ services:
     ports:
       - "8022:8022"
     command: "sh -c '/var/playbooks/wait-to-start-certs.sh && nodepool-launcher -f'"
+    networks:
+      - zuul
   logs:
     build:
       dockerfile: logs-Dockerfile
@@ -133,9 +149,14 @@ services:
       - "8000:80"
     volumes:
       - "logs:/usr/local/apache2/htdocs:z"
+    networks:
+      - zuul
 
 volumes:
   sshkey:
   nodessh:
   logs:
   certs:
+
+networks:
+  zuul:

doc/source/examples/keycloak/docker-compose.yaml

@@ -0,0 +1,31 @@
+# Start the quickstart tutorial with `docker-compose -p zuul-tutorial
+# up` (as directed in the instructions) in order for the network to
+# have the expected name so that it can be shared with keycloak.
+
+# Version 2.1 is required to specify the network name
+version: '2.1'
+
+services:
+  keycloak:
+    image: docker.io/jboss/keycloak
+    environment:
+      - KEYCLOAK_USER=admin
+      - KEYCLOAK_PASSWORD=kcadmin
+      - DB_VENDOR=h2
+      - KEYCLOAK_IMPORT=/var/keycloak_import/zuul-demo-data.json
+      - JAVA_OPTS_APPEND="-Djboss.socket.binding.port-offset=2"
+    ports:
+      - "8082:8082"
+    volumes:
+      - "./keycloak/:/var/keycloak_import/:z"
+    entrypoint: |
+      /bin/sh -c '\
+      /opt/jboss/tools/docker-entrypoint.sh -b 0.0.0.0'
+    command: []
+    networks:
+      - zuul
+
+networks:
+  zuul:
+    external: true
+    name: zuul-tutorial_zuul

doc/source/examples/keycloak/etc_zuul/main.yaml

@@ -0,0 +1,25 @@
+- admin-rule:
+    name: tenant-group
+    conditions:
+      - groups: "{tenant.name}-admin"
+- admin-rule:
+    name: admin-user
+    conditions:
+      - preferred_username: admin
+- tenant:
+    name: example-tenant
+    admin-rules:
+      - tenant-group
+      - admin-user
+    source:
+      gerrit:
+        config-projects:
+          - zuul-config
+        untrusted-projects:
+          - test1
+          - test2
+      opendev.org:
+        untrusted-projects:
+          - zuul/zuul-jobs:
+              include:
+                - job

doc/source/examples/keycloak/etc_zuul/zuul.conf

@@ -0,0 +1,52 @@
+[gearman]
+server=scheduler
+
+[gearman_server]
+start=true
+
+[zookeeper]
+hosts=zk:2281
+tls_cert=/var/certs/certs/client.pem
+tls_key=/var/certs/keys/clientkey.pem
+tls_ca=/var/certs/certs/cacert.pem
+
+[keystore]
+password=secret
+
+[scheduler]
+tenant_config=/etc/zuul/main.yaml
+
+[auth keycloak]
+default=true
+driver=OpenIDConnect
+realm=zuul-demo
+issuer_id=http://keycloak:8082/auth/realms/zuul-demo
+client_id=zuul
+
+[connection "gerrit"]
+name=gerrit
+driver=gerrit
+server=gerrit
+sshkey=/var/ssh/zuul
+user=zuul
+password=secret
+baseurl=http://gerrit:8080
+auth_type=basic
+
+[connection "opendev.org"]
+name=opendev
+driver=git
+baseurl=https://opendev.org
+
+[database]
+dburi=mysql+pymysql://zuul:%(ZUUL_MYSQL_PASSWORD)s@mysql/zuul
+
+[web]
+listen_address=0.0.0.0
+port=9000
+root=http://localhost:9000
+
+[executor]
+private_key_file=/var/ssh/nodepool
+default_username=root
+trusted_rw_paths=/srv/static/logs

doc/source/tutorials/admin.rst

@@ -5,3 +5,4 @@ Admin Tutorials
    :maxdepth: 1
 
    quick-start
+   keycloak

doc/source/tutorials/keycloak.rst

@@ -0,0 +1,75 @@
+Keycloak Tutorial
+=================
+
+Zuul supports an authenticated API accessible via its web app which
+can be used to perform some administrative actions.  To see this in
+action, first run the :ref:`quick_start` and then follow the steps in
+this tutorial to add a Keycloak server.
+
+Zuul supports any identity provider that can supply a JWT using OpenID
+Connect.  Keystone is used here because it is entirely self-contained.
+Google authentication is one additional option described elsewhere in
+the documentation.
+
+Update /etc/hosts
+-----------------
+
+The Zuul containers will use the internal docker network to connect to
+keycloak, but you will use a mapped port to access it in your web
+browser.  There is no way to have Zuul use the internal hostname when
+it validates the token yet redirect your browser to `localhost` to
+obtain the token, therefore you will need to add a matching host entry
+to `/etc/hosts`.  Make sure you have a line that looks like this:
+
+.. code-block::
+
+   127.0.0.1 localhost keycloak
+
+Restart Zuul Containers
+-----------------------
+
+After completing the initial tutorial, stop the Zuul containers so
+that we can update Zuul's configuration to add authentication.
+
+.. code-block:: shell
+
+   cd zuul/doc/source/examples
+   sudo -E docker-compose -p zuul-tutorial down
+
+Restart the containers with a new Zuul configuration.
+
+.. code-block:: shell
+
+   cd zuul/doc/source/examples
+   ZUUL_TUTORIAL_CONFIG="./keycloak/etc_zuul/" sudo -E docker-compose -p zuul-tutorial up -d
+
+This tells docker-compose to use these Zuul `config files
+<https://opendev.org/zuul/zuul/src/branch/master/doc/source/examples/keycloak>`_.
+
+Start Keycloak
+--------------
+
+A separate docker-compose file is supplied to run Keycloak.  Start it
+with this command:
+
+.. code-block:: shell
+
+   cd zuul/doc/source/examples/keycloak
+   sudo -E docker-compose -p zuul-tutorial-keycloak up -d
+
+Once Keycloak is running, you can visit the web interface at
+http://localhost:8082/
+
+The Keycloak administrative user is `admin` with a password of
+`kcadmin`.
+
+Log Into Zuul
+-------------
+
+Visit http://localhost:3000/t/example-tenant/autoholds and click the
+login icon on the top right.  You will be directed to Keycloak, where
+you can log into the Zuul realm with the user `admin` and password
+`admin`.
+
+Once you return to Zuul, you should see the option to create an
+autohold -- an admin-only option.

playbooks/tutorial/admin.yaml

@@ -0,0 +1,57 @@
+# Stop the basic tutorial
+- name: Run docker-compose down
+  when: not local
+  shell:
+    cmd: docker-compose -p zuul-tutorial down
+    chdir: src/opendev.org/zuul/zuul/doc/source/examples
+
+- name: Run docker-compose down
+  when: local
+  shell:
+    cmd: docker-compose -p zuul-tutorial down
+    chdir: ../../doc/source/examples
+
+# Restart with the new config
+- name: Run docker-compose up
+  when: not local
+  shell:
+    cmd: docker-compose -p zuul-tutorial up -d
+    chdir: src/opendev.org/zuul/zuul/doc/source/examples
+  environment:
+    ZUUL_TUTORIAL_CONFIG: "./keycloak/etc_zuul/"
+
+- name: Run docker-compose up
+  when: local
+  shell:
+    cmd: docker-compose -p zuul-tutorial up -d
+    chdir: ../../doc/source/examples
+  environment:
+    ZUUL_TUTORIAL_CONFIG: "./keycloak/etc_zuul/"
+
+# Start keycloak
+- name: Run docker-compose up
+  when: not local
+  shell:
+    cmd: docker-compose -p zuul-tutorial-keycloak up -d
+    chdir: src/opendev.org/zuul/zuul/doc/source/examples/keycloak
+
+- name: Run docker-compose up
+  when: local
+  shell:
+    cmd: docker-compose -p zuul-tutorial-keycloak up -d
+    chdir: ../../doc/source/examples/keycloak
+
+# Verify that Zuul runs with the new config
+- name: Wait for Zuul
+  uri:
+    url: http://localhost:9000/api/tenant/example-tenant/status
+    method: GET
+    return_content: true
+    status_code: 200
+    body_format: json
+  register: result
+  retries: 30
+  delay: 10
+  until: result.status == 200 and result.json["zuul_version"] is defined
+  changed_when: false
+

playbooks/tutorial/run-tutorial.yaml

@@ -10,3 +10,6 @@
 
 - name: Run quick-start tutorial
   include_tasks: quick-start.yaml
+
+- name: Run admin tutorial
+  include_tasks: admin.yaml