Add documentations for exposing services (cnoe-io#61)

Signed-off-by: Manabu McCloskey <[email protected]>

.codespellignore

@@ -0,0 +1 @@
+noo

.github/workflows/codespell.yaml

@@ -24,4 +24,5 @@ jobs:
           check_filenames: true
           # When using this Action in other repos, the --skip option below can be removed
           skip: "*.excalidraw,*.git,*.png,*.jpg,*.svg,package.json,package-lock.json,yarn.lock"
+          ignore_words_file: .codespellignore
         continue-on-error: true # The PR checks will not fail, but the possible spelling issues will still be reported for review and correction

.pre-commit-config.yaml

@@ -8,5 +8,7 @@ repos:
     rev: v2.2.6
     hooks:
       - id: codespell
-        args: ["--skip=*.excalidraw,*.git,*.png,*.jpg,*.svg,package.json,package-lock.json,yarn.lock"]
+        args:
+          - "--skip=*.excalidraw,*.git,*.png,*.jpg,*.svg,package.json,package-lock.json,yarn.lock"
+          - "--ignore-words=.codespellignore"
 

docs/reference-implementation/installations/idpbuilder/how-it-works.md

@@ -31,13 +31,38 @@ Finally, the certificate is exposed as a secret named `idpbuilder-cert` in the d
 kubectl get secret -n default idpbuilder-cert
 ```
 
-## DNS Configuration
+## Networking
+
+### Overview
+
+With the default configuration on Docker on Linux, kind cluster is set up as follows:
+
+1. A Docker container runs as the Kubernetes node and the container port 443 is exposed on host port 8443. You can confirm this by running `docker container ls`
+1. Ingress-nginx service is configured as `NodePort` and listens on port 443. You can confirm with `kubectl get service -n ingress-nginx  ingress-nginx-controller`.
+
+With this setup, HTTP traffic for `https://gitea.cnoe.localtest.me:8443` roughly looks like this.
+
+1. Domain name resolves to the local loopback address.
+1. A request is made to `127.0.0.1:8443` with host set as `gitea.cnoe.localtest.me:8443`.
+1. The request is sent to the container port 443.
+1. Ingress-nginx looks at SNI and the host header, then routes the traffic to the Gitea service.
+1. Gitea receives the request then sends back a response.
+
+
+### DNS
+
+By default, idpbuilder uses the domain name `cnoe.localtest.me` as the base domain name to expose services such as ArgoCD and Gitea.
+Most subdomains under `localtest.me` resolves to the [local loopback address](https://en.wikipedia.org/wiki/Localhost).
+This allows us to have a consistent name that resolves to a known IP address without using the `localhost` name.
+See [the localtest.me documentation site](https://readme.localtest.me/) for more information.
+
+### In-cluster DNS Configuration
 
 idpbuilder configures in-cluster DNS service (CoreDNS) to ensure domain names are resolved correctly.
 The name given by the `--host` flag resolves to the ingress-nginx controller service address. 
 This allows us to resolve the domain name inside and outside cluster to the same endpoint. 
 
-The default domain name, `cnoe.localtest.me`, resolves to a local loopback address such as `127.0.0.1`. 
+As described above, the default domain name, `cnoe.localtest.me`, resolves to a local loopback address such as `127.0.0.1`. 
 This works for accessing the ingress-nginx service from outside the cluster because the service port is exposed as NodePort on the local machine. 
 
 This approach does not work for in-cluster traffic because the address resolves to local loopback interface. 

docs/reference-implementation/installations/idpbuilder/usage.md

@@ -151,3 +151,50 @@ You can also view the updated Application spec by going to this address: https:/
 
 The second package directory defines two normal ArgoCD applications referencing a remote repository.
 They are applied as-is.
+
+### Exposing Services
+
+Idpbuilder comes with [ingress-nginx](https://github.com/kubernetes/ingress-nginx), and this is meant to be used as an easy way to expose services to the outside world.
+See [the networking overview section](how-it-works.md#networking) for more information.
+By default, idpbuilder exposes the ingress-nginx service on host port 8443 and Kubernetes Ingress objects are created for core packages.
+For example, an ingress object for Gitea looks something like this:
+
+```yaml
+apiVersion: networking.k8s.io/v1
+kind: Ingress
+spec:
+  ingressClassName: nginx
+  rules:
+    - host: gitea.cnoe.localtest.me
+      http:
+        paths:
+          - path: /
+            backend:
+              service:
+                name: my-gitea-http
+```
+
+With this configuration, nginx routes traffic to Gitea service when http requests are made for `gitea.cnoe.localtest.me`.
+
+Similarly, you can expose your own service by defining an ingress object.
+For example, to expose a service named my-service at `my-service.cnoe.localtest.me`, the ingress object may look something like this.
+
+```yaml
+apiVersion: networking.k8s.io/v1
+kind: Ingress
+metadata:
+  name: my-service
+spec:
+  ingressClassName: nginx
+  rules:
+    - host: my-service.cnoe.localtest.me
+      http:
+        paths:
+          - backend:
+              service:
+                name: my-service
+                port:
+                  number: 80
+            path: /
+            pathType: Prefix
+```

docs/reference-implementation/plugins/scaffolder-frontend.md

@@ -50,7 +50,7 @@ spec:
     - title: Enter some details
       properties:
         clusterName:
-          title: Name of the cluster to deploy manfiest into.
+          title: Name of the cluster to deploy manifest into.
           type: string
           ui:field: KubernetesClusterPicker
           ui:options: