docs: Add starter docs site

.github/workflows/github-pages.yml

@@ -0,0 +1,51 @@
+# Copyright 2023 D2iQ, Inc. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+name: GitHub Pages
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+jobs:
+  deploy:
+    runs-on: ubuntu-22.04
+    permissions:
+      contents: write
+    concurrency:
+      group: ${{ github.workflow }}-${{ github.ref }}
+      cancel-in-progress: true
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+
+      - name: Setup Hugo
+        uses: peaceiris/actions-hugo@v2
+        with:
+          hugo-version: '0.116.1'
+          extended: true
+
+      - name: Setup Node
+        uses: actions/setup-node@v3
+        with:
+          node-version: '18'
+          cache: 'npm'
+          cache-dependency-path: '**/package-lock.json'
+
+      - name: Install necessary packages
+        run: npm ci
+        working-directory: ./docs/
+
+      - name: Build
+        run: hugo --minify
+        working-directory: ./docs/
+
+      - name: Deploy
+        uses: peaceiris/actions-gh-pages@v3
+        if: github.ref == 'refs/heads/main'
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./docs/public

.gitignore

@@ -31,3 +31,8 @@ capd-kubeconfig
 ct_previous_*/
 
 .envrc.local*
+
+public/
+resources/
+node_modules/
+.hugo_build.lock

.pre-commit-config.yaml

@@ -13,7 +13,8 @@ repos:
 - repo: https://github.com/tekwizely/pre-commit-golang
   rev: v1.0.0-rc.1
   hooks:
-  - id: go-mod-tidy-repo
+  - id: go-mod-tidy
+    exclude: ^docs/
 - repo: https://github.com/pre-commit/pre-commit-hooks
   rev: v4.4.0
   hooks:
@@ -102,7 +103,7 @@ repos:
     name: License headers - Markdown
     stages: [commit]
     files: \.md$
-    exclude: ^CHANGELOG.md$
+    exclude: ^(CHANGELOG.md$|docs/)
     args:
       - --license-filepath
       - hack/license-header.txt

devbox.json

@@ -21,6 +21,7 @@
     "gotestsum@latest",
     "hadolint@latest",
     "helm-docs@latest",
+    "[email protected]",
     "kind@latest",
     "kubebuilder@latest",
     "kubectl@latest",

devbox.lock

@@ -127,6 +127,12 @@
       "source": "devbox-search",
       "version": "1.11.0"
     },
+    "[email protected]": {
+      "last_modified": "2023-08-08T03:07:33Z",
+      "resolved": "github:NixOS/nixpkgs/844ffa82bbe2a2779c86ab3a72ff1b4176cec467#hugo",
+      "source": "devbox-search",
+      "version": "0.116.1"
+    },
     "kind@latest": {
       "last_modified": "2023-06-30T04:44:22Z",
       "resolved": "github:NixOS/nixpkgs/3c614fbc76fc152f3e1bc4b2263da6d90adf80fb#kind",

docs/README.md

@@ -0,0 +1,16 @@
+<!--
+ Copyright 2023 D2iQ, Inc. All rights reserved.
+ SPDX-License-Identifier: Apache-2.0
+-->
+
+# CAPI Runtime Extensions documentation site
+
+The docs site uses [hugo](https://gohugo.io/) to build a static site deployed to the `gh-pages` branch of this repo.
+
+## Creating a new page
+
+`hugo new content/<kebab-case-page-name>.md`
+
+## Previewing the site
+
+`hugo serve -F -D`

docs/archetypes/default.md

@@ -0,0 +1,4 @@
+---
+title: "{{ replace .Name "-" " " | title }}"
+date: {{ .Date }}
+---

docs/content/_index.md

@@ -0,0 +1,16 @@
++++
+title = "CAPI Runtime Extensions"
+
+[[cascade]]
+type = "blog"
+toc_root = true
+
+  [cascade._target]
+  path = "/news/**"
+
+[[cascade]]
+type = "docs"
+
+  [cascade._target]
+  path = "/**"
++++

docs/content/calico-cni.md

@@ -0,0 +1,28 @@
+---
+title: "Calico CNI"
+---
+
+When deploying a cluster with CAPI, deployment and configuration of CNI is up to the user. By leveraging CAPI cluster
+lifecycle hooks, this handler deploys Calico CNI on the new cluster via `ClusterResourceSets` at the
+`AfterControlPlaneInitialized` phase.
+
+Deployment of Calico is opt-in La cluster must be labelled with `capiext.labs.d2iq.io/cni=calico` for the lifecycle hook
+to perform any actions. The hook creates two `ClusterResourceSets`: one to deploy the Tigera Operator, and one to deploy
+Calico via the Tigera `Installation` CRD. The Tigera Operator CRS is shared between all clusters in the operator,
+whereas the Calico installation CRS is unique per cluster.
+
+This hook is enabled by default, and can be explicitly disabled by omitting the `CalicoCNI` hook from the
+`--runtimehooks.enabled-handlers` flag.
+
+If deploying via Helm, then this can be disabled by setting `handlers.CalicoCNI.enabled=false`.
+
+As ClusterResourceSets must exist in the same name as the cluster they apply to, the lifecycle hook copies default
+ConfigMaps from the same namespace as the CAPI runtime extensions hook pod is running in. This enables users to
+configure defaults specific for their environment rather than compiling the defaults into the binary.
+
+The Helm chart comes with default configurations for the Calico Installation CRS per supported provider, but overriding
+is possible. To do so, specify:
+
+```bash
+--set-file handlers.CalicoCNI.defaultInstallationConfigMaps.DockerCluster.configMap.content=<file>
+```

docs/content/service-loadbalancer-gc.md

@@ -0,0 +1,19 @@
+---
+title: "LoadBalancer Services Garbage Collection"
+---
+
+When using Kubernetes `LoadBalancer` services, the relevant cloud provider interface creates and configures external
+resources. If the `LoadBalancer` services are not deleted prior to deleting the Kubernetes cluster, then these external
+resources are orphaned, leading to wasted resources and unnecessary expense. The load-balancer services garbage
+collector is implemented as a `BeforeClusterDelete` CAPI cluster lifecycle hook that deletes the load-balancer services
+and thus triggering the cloud provider interface to clean up the external resources. The hook blocks until all
+load-balancer services have been fully deleted, indicating that the cloud provider interface has cleaned up the external
+resources.
+
+This hook is enabled by default, and can be explicitly disabled by omitting the `LoadBalancerGC` hook from the
+`--runtimehooks.enabled-handlers` flag.
+
+If deploying via Helm, then this can be disabled by setting `handlers.ServiceLoadBalancerGC.enabled=false`.
+
+By default, all clusters will be cleaned up when deleting, but this can be opted out from by setting the annotation
+`capiext.labs.d2iq.io//loadbalancer-gc=false`.

docs/go.mod

@@ -0,0 +1,8 @@
+// Copyright 2023 D2iQ, Inc. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+module github.com/d2iq-labs/capi-runtime-extensions/docs
+
+go 1.20
+
+require github.com/google/docsy v0.7.1 // indirect

docs/go.sum

@@ -0,0 +1,5 @@
+github.com/FortAwesome/Font-Awesome v0.0.0-20230327165841-0698449d50f2/go.mod h1:IUgezN/MFpCDIlFezw3L8j83oeiIuYoj28Miwr/KUYo=
+github.com/google/docsy v0.7.1 h1:DUriA7Nr3lJjNi9Ulev1SfiG1sUYmvyDeU4nTp7uDxY=
+github.com/google/docsy v0.7.1/go.mod h1:JCmE+c+izhE0Rvzv3y+AzHhz1KdwlA9Oj5YBMklJcfc=
+github.com/google/docsy/dependencies v0.7.1/go.mod h1:gihhs5gmgeO+wuoay4FwOzob+jYJVyQbNaQOh788lD4=
+github.com/twbs/bootstrap v5.2.3+incompatible/go.mod h1:fZTSrkpSf0/HkL0IIJzvVspTt1r9zuf7XlZau8kpcY0=

docs/hugo.toml

@@ -0,0 +1,169 @@
+
+baseURL = "https://d2iq-labs.github.io/capi-runtime-extensions"
+title = "CAPI Runtime Extensions | D2iQ Labs"
+
+enableRobotsTXT = true
+
+# Will give values to .Lastmod etc.
+enableGitInfo = true
+
+# Language settings
+contentDir = "content"
+
+disableKinds = ["taxonomy", "term", "RSS"]
+
+# Configure how URLs look like per section.
+[permalinks]
+blog = "/:section/:year/:month/:day/:slug/"
+
+## Configuration for BlackFriday markdown parser: https://github.com/russross/blackfriday
+[blackfriday]
+plainIDAnchors = true
+hrefTargetBlank = true
+angledQuotes = false
+latexDashes = true
+
+# Image processing configuration.
+[imaging]
+resampleFilter = "CatmullRom"
+quality = 75
+anchor = "Smart"
+
+[services]
+[services.googleAnalytics]
+# Comment out the next line to disable GA tracking. Also disables the feature described in [params.ui.feedback].
+# id = "UA-00000000-0"
+
+[markup]
+  [markup.goldmark]
+    [markup.goldmark.extensions]
+      typographer = false
+    [markup.goldmark.renderer]
+      unsafe = true
+  [markup.highlight]
+      # See a complete list of available styles at https://xyproto.github.io/splash/docs/all.html
+      style = "tango"
+      # Uncomment if you want your chosen highlight style used for code blocks without a specified language
+      # guessSyntax = "true"
+
+# Everything below this are Site Params
+
+# Comment out if you don't want the "print entire section" link enabled.
+[outputs]
+section = ["HTML", "print"]
+
+[params]
+copyright = "D2iQ, Inc."
+# privacy_policy = "https://policies.google.com/privacy"
+
+# First one is picked as the Twitter card image if not set on page.
+# images = ["images/project-illustration.png"]
+
+# Menu title if your navbar has a versions selector to access old versions of your site.
+# This menu appears only if you have at least one [params.versions] set.
+version_menu = "Releases"
+
+# Flag used in the "version-banner" partial to decide whether to display a
+# banner on every page indicating that this is an archived version of the docs.
+# Set this flag to "true" if you want to display the banner.
+archived_version = false
+
+# The version number for the version of the docs represented in this doc set.
+# Used in the "version-banner" partial to display a version number for the
+# current doc set.
+version = "0.0"
+
+# A link to latest version of the docs. Used in the "version-banner" partial to
+# point people to the main doc site.
+url_latest_version = "https://example.com"
+
+# Repository configuration (URLs for in-page links to opening issues and suggesting changes)
+# The links work despite our URL being GitLab not GitHub.
+github_repo = "https://github.com/d2iq-labs/capi-runtime-extensions"
+# An optional link to a related project repo. For example, the sibling repository where your product code lives.
+# The links work despite our URL being GitLab not GitHub.
+
+# Specify a value here if your content directory is not in your repo's root directory
+github_subdir = "docs"
+
+# Uncomment this if you have a newer GitHub repo with "main" as the default branch,
+# or specify a new value if you want to reference another branch in your GitHub links
+github_branch= "main"
+
+# Google Custom Search Engine ID. Remove or comment out to disable search.
+# gcs_engine_id = "d72aa9b2712488cc3"
+
+# Enable Algolia DocSearch
+algolia_docsearch = false
+
+# Enable Lunr.js offline search
+offlineSearch = true
+
+# Enable syntax highlighting and copy buttons on code blocks with Prism
+# Default "Chroma" syntax highlighter has no dot support, so use Prism instead
+prism_syntax_highlighting = true
+
+# User interface configuration
+[params.ui]
+# Enable to show the side bar menu in its compact state.
+sidebar_menu_compact = true
+#  Set to true to disable breadcrumb navigation.
+breadcrumb_disable = false
+#  Set to true to hide the sidebar search box (the top nav search box will still be displayed if search is enabled)
+sidebar_search_disable = false
+#  Set to false if you don't want to display a logo (/assets/icons/logo.svg) in the top nav bar
+navbar_logo = false
+# Set to true to disable the About link in the site footer
+footer_about_disable = false
+
+# We have almost 200 attributes; don't truncate the sidebar to max 50 contents.
+sidebar_menu_truncate = 1000
+
+# Sidebar generation is slow otherwise
+sidebar_cache_limit = 100
+
+ul_show = 2
+
+# Adds a H2 section titled "Feedback" to the bottom of each doc. The responses are sent to Google Analytics as events.
+# This feature depends on [services.googleAnalytics] and will be disabled if "services.googleAnalytics.id" is not set.
+# If you want this feature, but occasionally need to remove the "Feedback" section from a single page,
+# add "hide_feedback: true" to the page's front matter.
+[params.ui.feedback]
+enable = true
+# The responses that the user sees after clicking "yes" (the page was helpful) or "no" (the page was not helpful).
+yes = 'Glad to hear it! Please <a href="https://github.com/USERNAME/REPOSITORY/issues/new">tell us how we can improve</a>.'
+no = 'Sorry to hear that. Please <a href="https://github.com/USERNAME/REPOSITORY/issues/new">tell us how we can improve</a>.'
+
+# Adds a reading time to the top of each doc.
+# If you want this feature, but occasionally need to remove the Reading time from a single page,
+# add "hide_readingtime: true" to the page's front matter
+[params.ui.readingtime]
+enable = false
+
+[params.links]
+[[params.links.user]]
+  name ="Twitter"
+  url = "https://twitter.com/d2iq_eng"
+  icon = "fab fa-twitter"
+  desc = "Follow us on Twitter to get the latest news!"
+# Developer relevant links. These will show up on right side of footer and in the community page if you have one.
+[[params.links.developer]]
+  name = "GitHub"
+  url = "https://github.com/d2iq-labs/capi-runtime-extensions"
+  icon = "fab fa-github"
+        desc = "Development takes place here!"
+
+[[menu.main]]
+name = "GitHub"
+weight = 50
+pre = "<i class='fab fa-github'></i>"
+url = "https://github.com/d2iq-labs/capi-runtime-extensions"
+
+[params.taxonomy]
+
+[module]
+  proxy = "direct"
+  [[module.imports]]
+    path = "github.com/google/docsy"
+  [[module.imports]]
+    path = "github.com/google/docsy/dependencies"