From 136cff88dd3c3188e0568668224a0406989ee3bf Mon Sep 17 00:00:00 2001 From: Manabu McCloskey Date: Wed, 28 Aug 2024 09:05:18 -0700 Subject: [PATCH] Add documentations for exposing services (#61) Signed-off-by: Manabu McCloskey --- .codespellignore | 1 + .github/workflows/codespell.yaml | 1 + .pre-commit-config.yaml | 4 +- .../installations/idpbuilder/how-it-works.md | 29 +++++++++++- .../installations/idpbuilder/usage.md | 47 +++++++++++++++++++ .../plugins/scaffolder-frontend.md | 2 +- 6 files changed, 80 insertions(+), 4 deletions(-) create mode 100644 .codespellignore diff --git a/.codespellignore b/.codespellignore new file mode 100644 index 00000000..3d1dde58 --- /dev/null +++ b/.codespellignore @@ -0,0 +1 @@ +noo diff --git a/.github/workflows/codespell.yaml b/.github/workflows/codespell.yaml index 530fd37c..99680533 100644 --- a/.github/workflows/codespell.yaml +++ b/.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 diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 8581b8b6..f24f77a4 100644 --- a/.pre-commit-config.yaml +++ b/.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" diff --git a/docs/reference-implementation/installations/idpbuilder/how-it-works.md b/docs/reference-implementation/installations/idpbuilder/how-it-works.md index ad686cd5..f2b3b202 100644 --- a/docs/reference-implementation/installations/idpbuilder/how-it-works.md +++ b/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. diff --git a/docs/reference-implementation/installations/idpbuilder/usage.md b/docs/reference-implementation/installations/idpbuilder/usage.md index 1984ae4f..4a6897ab 100644 --- a/docs/reference-implementation/installations/idpbuilder/usage.md +++ b/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 +``` diff --git a/docs/reference-implementation/plugins/scaffolder-frontend.md b/docs/reference-implementation/plugins/scaffolder-frontend.md index 5e145d15..fdd325a3 100644 --- a/docs/reference-implementation/plugins/scaffolder-frontend.md +++ b/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: