generate CRD docs from spec

.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.