Merge pull request #71 from rackerlabs/docs

docs: updates to simplify and get rid of older workarounds

components/dexidp/README.md

@@ -1,4 +1,4 @@
-## Overview
+# Overview
 
 The [Dex IDP](https://dexidp.io/) is deployed to act as an OAuth2/OpenID
 Connect identity provider for Nautobot and potentially other applications in
@@ -27,54 +27,23 @@ requirements:
 
 Unfortunately, these Nautobot changes alone are not enough to have
 authentication working in most setups. We also need to make sure that every
-step of [authorziation code grant][authzcodegrant] can be completed. Given that
-we use ephemeral clusters for development and they use `.local` domain,
-following needs to work:
+step of [authorziation code grant][authzcodegrant] can be completed.
 
-- Nautobot container can reach the Dex using the issuer URL (`https://dexidp.local`).
-- End-user's browser must be able to reach Dex using exactly the same URL.
-- Nautobot needs to be reachable using the DNS name, i.e. `https://nautobot.local`
-- All of these needs to happen over HTTPS.
+For ephemeral clusters in development it is recommended to use a service like
+[sslip.io](https://sslip.io) to use hostnames like:
 
-When Dex and Nautobot are hosted in the same cluster, by default they will try
-to communicate over the internal networking and plain HTTP. This clearly
-violates the requirements listed above, so we have to force the communication
-between the pods to happen over the Ingress (which provides TLS termination and
-stable hostname).
+- dex.127-0-0-1.sslip.io
+- nautobot-127-0-0-1.sslip.io
 
-### Fixing DNS on development cluster
+And creating HTTPS certificates for them. Then you can access the services
+via DNS names and not have to patch your `/etc/hosts` or the DNS resolution in the cluster.
 
-In development cluster, this can be done by reconfiguring [CoreDNS][coredns]
-component. We have provided
-[`scripts/patch-coredns.sh`](../../scripts/patch-coredns.sh) script to make the
-necessary changes automatically.
+## Azure authentication
 
-```shell
-$ ./scripts/patch-coredns.sh
-[*] Patching coredns ConfigMap
-configmap/coredns replaced
-[*] Restarting CoreDNS
-deployment.apps/coredns restarted
-$
-```
-
-### Making components accessible from your machine
-
-If running development cluster on your machine, you may need to create  create
-an entry in your `/etc/hosts` file that looks similar to this:
-
-```hosts
-# Nautobot kind cluster
-127.0.0.1 argocd.local nautobot.local keystone keystone.openstack dexidp.local workflows.local
-```
-
-
-### Azure authentication
 Dex can optionally be configured to allow authentication through Azure SSO. The
 exact steps to configure this are available in
 [01-secrets/README.md](../01-secrets/README.md).
 
 [socialauth]: https://python-social-auth.readthedocs.io/en/latest/backends/oidc.html
 [disco]: https://openid.net/specs/openid-connect-discovery-1_0.html
 [authzcodegrant]: https://datatracker.ietf.org/doc/html/rfc6749#section-4.1
-[coredns]: https://kubernetes.io/docs/tasks/administer-cluster/coredns/#about-coredns

docs/gitops-install.md

@@ -47,7 +47,7 @@ To avoid defining many environment variables we'll simplify by creating an
 `.env` file for our deployment. In this case we'll call it `my-k3s.env` and
 place it where we've cloned understack. A complete file would like like
 
-```bash title="/path/to/understack/my-k3s.env"
+```bash title="/path/to/uc-deploy/my-k3s.env"
 UC_REPO="$HOME/devel/understack"
 UC_DEPLOY="$HOME/devel/uc-deploy"
 DEPLOY_NAME="my-k3s"
@@ -90,9 +90,17 @@ which needs to be set into the `UC_DEPLOY_EMAIL` variable.
 All Ingress DNS names will be created as subdomains of the value you put
 into the `DNS_ZONE` variable.
 
+#### Saving the Environment Config
+
+```bash
+cd /path/to/uc-deploy
+git add my-k3s.env
+git commit -m "my-k3s: save environment config"
+```
+
 #### Getting Ready to Generate Secrets and Configs
 
-You can run `source /path/to/understack/my-k3s.env` to have `$UC_DEPLOY` in
+You can run `source /path/to/uc-deploy/my-k3s.env` to have `$UC_DEPLOY` in
 your shell.
 
 ### Populating the infrastructure
@@ -111,7 +119,8 @@ using random data to sucessfully continue the installation.
 TODO: probably give at least one secure example
 
 ```bash
-./scripts/gitops-secrets-gen.sh ./my-k3s.env
+# from your understack checkout
+./scripts/gitops-secrets-gen.sh ${UC_DEPLOY}/my-k3s.env
 pushd "${UC_DEPLOY}"
 git add secrets/my-k3s
 git commit -m "my-k3s: secrets generation"
@@ -124,7 +133,8 @@ In this section we will use the [App of Apps][app-of-apps] pattern to define
 the deployment of all the components of UnderStack.
 
 ```bash
-./scripts/gitops-deploy.sh ./my-k3s.env
+# from your understack checkout
+./scripts/gitops-deploy.sh ${UC_DEPLOY}/my-k3s.env
 pushd "${UC_DEPLOY}"
 git add clusters/my-k3s
 git add helm-configs/my-k3s

docs/install-understack-ubuntu-k3s.md

@@ -308,13 +308,7 @@ nautobot        job.batch/nautobot-backup-sg6f             1/1           2m48s
 ### OpenStack Pre-requisites
 
 ```bash
-# clone the two repos because they reference the infra one as a relative path
-# so you can't use real helm commands
-git clone https://github.com/openstack/openstack-helm
-git clone https://github.com/openstack/openstack-helm-infra
-# update the dependencies cause we can't use real helm references
-./scripts/openstack-helm-depend-sync.sh ironic
-# keystone can now be used from a helm repo
+# add the OpenStack Helm repo we can install from
 helm repo add osh https://tarballs.opendev.org/openstack/openstack-helm/
 ```
 
@@ -379,7 +373,7 @@ Install the OpenStack Ironic helm chart using our custom aio-values.yaml overrid
 ```bash
 helm --namespace openstack template \
     ironic \
-    ./openstack-helm/ironic/ \
+    osh/ironic/ \
     -f components/ironic/aio-values.yaml \
     -f secret-openstack.yaml \
     | kubectl -n openstack apply -f -

scripts/gitops-deploy.sh

@@ -1,4 +1,4 @@
-#!/bin/sh
+#!/bin/bash
 
 usage() {
     echo "$(basename "$0") <deploy.env>" >&2

scripts/gitops-secrets-gen.sh

@@ -1,4 +1,4 @@
-#!/bin/sh
+#!/bin/bash
 
 function usage() {
     echo "$(basename "$0") <deploy.env>" >&2