Browse Source

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>
changes/45/819745/5
James E. Blair 6 months ago
parent
commit
d4e9b66fa0
  1. 33
      doc/source/examples/docker-compose.yaml
  2. 31
      doc/source/examples/keycloak/docker-compose.yaml
  3. 25
      doc/source/examples/keycloak/etc_zuul/main.yaml
  4. 52
      doc/source/examples/keycloak/etc_zuul/zuul.conf
  5. 2224
      doc/source/examples/keycloak/keycloak/zuul-demo-data.json
  6. 9
      doc/source/reference/developer/javascript.rst
  7. 1
      doc/source/tutorials/admin.rst
  8. 78
      doc/source/tutorials/keycloak.rst
  9. 57
      playbooks/tutorial/admin.yaml
  10. 3
      playbooks/tutorial/run-tutorial.yaml

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

31
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

25
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

52
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

2224
doc/source/examples/keycloak/keycloak/zuul-demo-data.json

File diff suppressed because it is too large Load Diff

9
doc/source/reference/developer/javascript.rst

@ -202,6 +202,15 @@ To run eslint tests locally:
yarn lint
Authentication
~~~~~~~~~~~~~~
The docker-compose file in ``doc/source/examples/keycloak`` can be
used to run a Keycloak server for use with a development build of the
web app. The default values in that file are already set up for the
web app running on localhost. See the Keycloak tutorial for details.
Deploying
---------

1
doc/source/tutorials/admin.rst

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

78
doc/source/tutorials/keycloak.rst

@ -0,0 +1,78 @@
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. Keycloak is used here because it is entirely self-contained.
Google authentication is one additional option described elsewhere in
the documentation.
Gerrit can be updated to use the same authentication system as Zuul,
but this tutorial does not address that.
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:9000/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.

57
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

3
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

Loading…
Cancel
Save