Skip to content

WIP: Custom (templated) documentation, templates, and script

Iain Hadgraft requested to merge (removed):custom_docs into master

This adds a generation tool to simplify initial (and repeat) startup by templating OKD template files and generating detailed instructions for new / infrequent users. It also produces a script that will set everything up on a given project.

It's fairly simple - just a matter of editing a YAML config file with app-specific settings, and running a single command (make generate). See ./docs/README.md for instructions.

While this is a merge request, it may turn out to be a better fit to be its own project, so it's WIP for now. I don't believe it is dependent on anything outside the ./docs directory at this point.

Sample files are included below - the links are relative to my local machine, so many won't work in this context.

YAML Config (input)

okd_project:
  name: dws-developer-docs  # The name of the OKD project

# The entity ID is a globally unique ID used to identify the Shib SP.
# See https://wiki.shibboleth.net/confluence/display/CONCEPT/EntityNaming for naming conventions.
entity_id: https://webservices.duke.edu/shibboleth/dws-dev-docs-prod-01

shib_image:
  name: duke-shibboleth  # The name of the Shibboleth image created in OKD

httpd_image:
  name: duke-shibboleth-httpd  # The name of the Apache (httpd) image created in OKD

deployment_config:
  name: duke-shib-httpd  # The name of the deployment config

service_config:
  name: duke-shib-httpd

cert:
  org: Duke University  # Usually Duke University or Duke Health Technology Solutions
  orgunit: Duke Web Services  # The Department managing this shibboleth protected application
  email: iain.hadgraft@duke.edu  # should be an email used to contact a person or group associated with the ORGUNIT
  common_name: dws-dev-docs.cloud.duke.edu  #  The primary domain for the application
  alt_names: []  # Alternate names for the cert

Generated script (output)

#!/bin/sh

if [[ "$(oc project -q)" != "dws-developer-docs" ]]; then
  oc project "dws-developer-docs"
  if [[ $? -gt 0 ]]; then
     echo "Can't change project to dws-developer-docs" >> /dev/stderr
   fi
fi

if [[ ! -f "/private/tmp/duke-shibboleth/docs/output/dws-dev-docs.cloud.duke.edu/dws-dev-docs.cloud.duke.edu.key" ]]; then
  openssl genrsa -out /private/tmp/duke-shibboleth/docs/output/dws-dev-docs.cloud.duke.edu/dws-dev-docs.cloud.duke.edu.key 4096
openssl req -config /private/tmp/duke-shibboleth/docs/output/dws-dev-docs.cloud.duke.edu/openssl.conf -new -nodes -key /private/tmp/duke-shibboleth/docs/output/dws-dev-docs.cloud.duke.edu/dws-dev-docs.cloud.duke.edu.key -out /private/tmp/duke-shibboleth/docs/output/dws-dev-docs.cloud.duke.edu/dws-dev-docs.cloud.duke.edu.csr
chmod 0400 /private/tmp/duke-shibboleth/docs/output/dws-dev-docs.cloud.duke.edu/dws-dev-docs.cloud.duke.edu.key
openssl req -config /private/tmp/duke-shibboleth/docs/output/dws-dev-docs.cloud.duke.edu/openssl.conf -days 3650 -new -nodes -key /private/tmp/duke-shibboleth/docs/output/dws-dev-docs.cloud.duke.edu/dws-dev-docs.cloud.duke.edu.key -out /private/tmp/duke-shibboleth/docs/output/dws-dev-docs.cloud.duke.edu/dws-dev-docs.cloud.duke.edu.crt -x509
openssl req -in /private/tmp/duke-shibboleth/docs/output/dws-dev-docs.cloud.duke.edu/dws-dev-docs.cloud.duke.edu.csr -text
fi

oc create -f /private/tmp/duke-shibboleth/docs/output/dws-dev-docs.cloud.duke.edu/centos-imagestream.yml
oc create imagestream duke-shibboleth
oc create imagestream duke-shibboleth-httpd
oc create secret generic shib-creds \
  --from-file=tls.crt=/private/tmp/duke-shibboleth/docs/output/dws-dev-docs.cloud.duke.edu/dws-dev-docs.cloud.duke.edu.crt \
  --from-file=tls.key=/private/tmp/duke-shibboleth/docs/output/dws-dev-docs.cloud.duke.edu/dws-dev-docs.cloud.duke.edu.key
oc create -f /private/tmp/duke-shibboleth/docs/output/dws-dev-docs.cloud.duke.edu/shib-config.yml
oc create -f /private/tmp/duke-shibboleth/docs/output/dws-dev-docs.cloud.duke.edu/apache-config.yml
oc create -f /private/tmp/duke-shibboleth/docs/output/dws-dev-docs.cloud.duke.edu/shib-build-config.yml
oc create -f /private/tmp/duke-shibboleth/docs/output/dws-dev-docs.cloud.duke.edu/httpd-build-config.yml
oc create -f /private/tmp/duke-shibboleth/docs/output/dws-dev-docs.cloud.duke.edu/deployment-config.yml
oc create -f /private/tmp/duke-shibboleth/docs/output/dws-dev-docs.cloud.duke.edu/service-config.yml

Generated instructions (output)

Files to review

The following files have been customized for you. Please review them for accuracy.

Quick method

Note: see Creating the shib socket volume under Manual/Learning method

If you have already done this a hundred times and don't need to read the documentation, you can run the script at /private/tmp/duke-shibboleth/docs/output/dws-dev-docs.cloud.duke.edu/setup.sh. This script will generate a key and set everything up in openshift according to the settings you provided. It runs the same commands that appear in this file.

If you are new to the process, consider doing this manually a couple of times to gain an understanding of all the steps.

Manual/Learning method

Creating the shib socket volume

At least some users may need to do this part manually. Go to your project's storage page and add a persistent claim matching the value in the deployment configuration, which is volume-shib-socket by default.

Always good to make sure we're in the right project

oc project dws-developer-docs

Create key and cert

openssl genrsa -out /private/tmp/duke-shibboleth/docs/output/dws-dev-docs.cloud.duke.edu/dws-dev-docs.cloud.duke.edu.key 4096
openssl req -config /private/tmp/duke-shibboleth/docs/output/dws-dev-docs.cloud.duke.edu/openssl.conf -new -nodes -key /private/tmp/duke-shibboleth/docs/output/dws-dev-docs.cloud.duke.edu/dws-dev-docs.cloud.duke.edu.key -out /private/tmp/duke-shibboleth/docs/output/dws-dev-docs.cloud.duke.edu/dws-dev-docs.cloud.duke.edu.csr
chmod 0400 /private/tmp/duke-shibboleth/docs/output/dws-dev-docs.cloud.duke.edu/dws-dev-docs.cloud.duke.edu.key
openssl req -config /private/tmp/duke-shibboleth/docs/output/dws-dev-docs.cloud.duke.edu/openssl.conf -days 3650 -new -nodes -key /private/tmp/duke-shibboleth/docs/output/dws-dev-docs.cloud.duke.edu/dws-dev-docs.cloud.duke.edu.key -out /private/tmp/duke-shibboleth/docs/output/dws-dev-docs.cloud.duke.edu/dws-dev-docs.cloud.duke.edu.crt -x509
openssl req -in /private/tmp/duke-shibboleth/docs/output/dws-dev-docs.cloud.duke.edu/dws-dev-docs.cloud.duke.edu.csr -text

Register Shibboleth SP

Go to https://authentication.oit.duke.edu and use the following values where prompted:

Entity ID

https://webservices.duke.edu/shibboleth/dws-dev-docs-prod-01

ACS URLs

Example:

Certificate

dws-dev-docs.cloud.duke.edu.crt

Add secrets to project

oc create secret generic shib-creds \
  --from-file=tls.crt=/private/tmp/duke-shibboleth/docs/output/dws-dev-docs.cloud.duke.edu/dws-dev-docs.cloud.duke.edu.crt \
  --from-file=tls.key=/private/tmp/duke-shibboleth/docs/output/dws-dev-docs.cloud.duke.edu/dws-dev-docs.cloud.duke.edu.key

Add config maps for shib and httpd

oc create -f /private/tmp/duke-shibboleth/docs/output/dws-dev-docs.cloud.duke.edu/shib-config.yml
oc create -f /private/tmp/duke-shibboleth/docs/output/dws-dev-docs.cloud.duke.edu/apache-config.yml

Create ImageStreams for our images

oc create -f /private/tmp/duke-shibboleth/docs/output/dws-dev-docs.cloud.duke.edu/centos-imagestream.yml
oc create imagestream duke-shibboleth
oc create imagestream duke-shibboleth-httpd

Add build and deployment configurations

oc create -f /private/tmp/duke-shibboleth/docs/output/dws-dev-docs.cloud.duke.edu/shib-build-config.yml
oc create -f /private/tmp/duke-shibboleth/docs/output/dws-dev-docs.cloud.duke.edu/httpd-build-config.yml
oc create -f /private/tmp/duke-shibboleth/docs/output/dws-dev-docs.cloud.duke.edu/deployment-config.yml
oc create -f /private/tmp/duke-shibboleth/docs/output/dws-dev-docs.cloud.duke.edu/service-config.yml

Merge request reports