generate CRD docs from spec (pomerium#428)

.github/workflows/docs.yaml

@@ -0,0 +1,32 @@
+name: Docs
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  pull-request:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@93ea575cb5d8a053eaa0ac8fa3b40d7e05a33cc8
+
+      - uses: actions/setup-go@c4a742cab115ed795e34d4513e2cf7d472deb55f
+        with:
+          go-version: 1.19.x
+
+      - name: generate docs
+        run: make docs
+
+      - name: Create pull request in the documentations repo
+        uses: paygoc6/[email protected]
+        env:
+          API_TOKEN_GITHUB: ${{ secrets.APPARITOR_GITHUB_TOKEN }}
+        with:
+          source_folder: "reference.md"
+          destination_repo: "pomerium/documentation"
+          destination_folder: "content/docs/k8s"
+          destination_base_branch: "main"
+          destination_head_branch: update-k8s-reference-${{ github.sha }}
+          user_email: "[email protected]"
+          user_name: "wasaga"

.pre-commit-config.yaml

@@ -4,7 +4,7 @@ repos:
     hooks:
       - id: trailing-whitespace
       - id: end-of-file-fixer
-        exclude: "(docs/.*|integration/tpl/files/.*)"
+        exclude: "(integration/tpl/files/.*)"
       - id: check-yaml
         exclude: "deployment.yaml"
       - id: check-added-large-files

Makefile

@@ -208,6 +208,11 @@ deployment:
 	@echo "==> $@"
 	@$(KUSTOMIZE) build config/default > deployment.yaml
 
+.PHONY: docs
+docs: manifests
+	@echo "==> $@"
+	@go run docs/cmd/main.go > reference.md
+
 #
 # --- internal development targets
 #

README.md

@@ -9,40 +9,27 @@ See [docs for usage details](https://www.pomerium.com/docs/k8s/ingress) for end-
 
 # Installation
 
-```
-kubectl apply -f https://raw.githubusercontent.com/pomerium/ingress-controller/main/deployment.yaml
+See [Quick Start](https://www.pomerium.com/docs/k8s/quickstart) for a step-by-step guide.
+
+```shell
+kubectl apply -f https://raw.githubusercontent.com/pomerium/ingress-controller/v0.19.0/deployment.yaml
 ```
 
-- `pomerium` namespace is created that would contain an installation.
-- `pomerium.ingress.pomerium.io` cluster-scoped CRD is created.
-- `pomerium` `IngressClass`. Assign that `IngressClass` to the `Ingress` objects that should be managed by Pomerium.
+The manifests-based installation:
+
+- Creates `pomerium` namespace.
+- Creates `pomerium.ingress.pomerium.io` cluster-scoped CRD.
+- Creates `pomerium` `IngressClass`. Assign that `IngressClass` to the `Ingress` objects that should be managed by Pomerium.
 - All-in-one Pomerium deployment with a single replica is created.
 - Pomerium expects a `pomerium` CRD named `global` to be created.
 - A one time `Job` to generate `pomerium/bootstrap` secrets, that have to be referenced from the CRD via `secrets` parameter.
 
-Pomerium requires further configuration to become operational.
+Pomerium requires further configuration to become operational (see below).
 
 # Configuration
 
 Default Pomerium deployment is configured to watch `global` CRD.
-That may be customized via command line arguments.
-Most Pomerium configuration is set via CRD.
-
-```yaml
-apiVersion: ingress.pomerium.io/v1
-kind: Pomerium
-metadata:
-  name: global
-spec:
-  authenticate:
-    url: https://authenticate.localhost.pomerium.io
-  certificates:
-    - pomerium/wildcard-localhost-pomerium-io
-  identityProvider:
-    provider: xxxxxxx
-    secret: pomerium/idp
-  secrets: pomerium/bootstrap
-```
+[Pomerium should be configured via the CRD](https://www.pomerium.com/docs/k8s/reference).
 
 _Note:_: the configuration must be complete. i.e. if you're missing a referenced secret, it would not be accepted.