[docs] refactor/organizing docs

.github/filters.yml

@@ -1,3 +1,9 @@
 # Any file that is not a doc *.md file
 src:
-  - "!**/**.md"
+  - "!docs/**"
+  - "!**/*.md"
+  - "!*.md"
+  - "!.github/CONTRIBUTING.md"
+  - "!.github/PULL_REQUEST_TEMPLATE.md"
+  - "!**/README.md"
+  - "!**/CHANGELOG.md"

.github/workflows/ci.yml

@@ -4,7 +4,23 @@ on:
   push:
     branches:
       - main
-  pull_request: null
+    paths-ignore:
+      - 'docs/**'
+      - '**/*.md'
+      - '*.md'
+      - '.github/CONTRIBUTING.md'
+      - '.github/PULL_REQUEST_TEMPLATE.md'
+      - '**/README.md'
+      - '**/CHANGELOG.md'
+  pull_request:
+    paths-ignore:
+      - 'docs/**'
+      - '**/*.md'
+      - '*.md'
+      - '.github/CONTRIBUTING.md'
+      - '.github/PULL_REQUEST_TEMPLATE.md'
+      - '**/README.md'
+      - '**/CHANGELOG.md'
 
 permissions:
   contents: read

.github/workflows/docs.yml

@@ -0,0 +1,75 @@
+name: Deploy Documentation
+
+on:
+  push:
+    branches:
+      - master
+    paths:
+      - 'README.md'
+      - 'docs/**'
+      - '.github/workflows/docs.yml'
+  pull_request:
+    paths:
+      - 'docs/**'
+      - '.github/workflows/docs.yml'
+
+permissions:
+  contents: read
+  pages: write      # to deploy to Pages
+  id-token: write   # to verify the deployment originates from an appropriate source
+
+jobs:
+  generate-docs:
+    runs-on: ubuntu-latest
+    container: docker.io/node:20-bullseye-slim
+    timeout-minutes: 2
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup mdBook
+        run: |
+          apt-get update
+          apt-get install curl -y
+          mkdir mdbook
+          curl -sSL https://github.com/rust-lang/mdbook/releases/download/v0.4.37/mdbook-v0.4.37-x86_64-unknown-linux-gnu.tar.gz | tar -xz --directory=./mdbook
+          curl -sSL https://github.com/tommilligan/mdbook-admonish/releases/download/v1.15.0/mdbook-admonish-v1.15.0-x86_64-unknown-linux-gnu.tar.gz | tar -xz --directory=./mdbook
+          echo `pwd`/mdbook >> $GITHUB_PATH
+
+      - name: Build with mdBook
+        run: |
+          cd docs
+          mdbook build
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: 'docs/book'
+
+  deploy-preview:
+    needs: generate-docs
+    if: github.event_name == 'pull_request'
+    environment:
+      name: pr-preview
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 2
+    steps:
+      - name: Deploy PR Preview
+        id: deployment
+        uses: actions/deploy-pages@v4
+
+  deploy-production:
+    needs: generate-docs
+    if: github.event_name == 'push'
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 2
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4 

.gitignore

@@ -39,3 +39,5 @@ coverage.txt
 junit.xml
 
 .DS_Store
+
+docs/book

Makefile

@@ -25,6 +25,8 @@ LINODE_REGION           ?= us-lax
 LINODE_OS               ?= linode/ubuntu22.04
 KUBECONFIG_PATH         ?= $(CURDIR)/test-cluster-kubeconfig.yaml
 MGMT_KUBECONFIG_PATH    ?= $(CURDIR)/mgmt-cluster-kubeconfig.yaml
+MDBOOK_DEV_HOST         ?= 0.0.0.0
+MDBOOK_DEV_PORT         ?= 3000
 
 # if the $DEVBOX_PACKAGES_DIR env variable exists that means we are within a devbox shell and can safely
 # use devbox's bin for our tools
@@ -131,6 +133,10 @@ run-debug: build
 		--kubeconfig=${KUBECONFIG} \
 		--linodego-debug
 
+.PHONY: docs
+docs:
+	@cd docs && mdbook serve -n $(MDBOOK_DEV_HOST) -p $(MDBOOK_DEV_PORT)
+
 #####################################################################
 # E2E Test Setup
 #####################################################################

devbox.json

@@ -12,7 +12,9 @@
     "kustomize@latest",
     "kyverno-chainsaw@latest",
     "mockgen@latest",
-    "yq-go@latest"
+    "yq-go@latest",
+    "mdbook@latest",
+    "mdbook-admonish@latest"
   ],
   "shell": {
     "init_hook": [

devbox.lock

@@ -633,6 +633,102 @@
         }
       }
     },
+    "mdbook-admonish@latest": {
+      "last_modified": "2024-12-23T21:10:33Z",
+      "resolved": "github:NixOS/nixpkgs/de1864217bfa9b5845f465e771e0ecb48b30e02d#mdbook-admonish",
+      "source": "devbox-search",
+      "version": "1.18.0",
+      "systems": {
+        "aarch64-darwin": {
+          "outputs": [
+            {
+              "name": "out",
+              "path": "/nix/store/hrmry6gcyxq576yyvvv2vsl05sycmi1y-mdbook-admonish-1.18.0",
+              "default": true
+            }
+          ],
+          "store_path": "/nix/store/hrmry6gcyxq576yyvvv2vsl05sycmi1y-mdbook-admonish-1.18.0"
+        },
+        "aarch64-linux": {
+          "outputs": [
+            {
+              "name": "out",
+              "path": "/nix/store/fg3pqy6459lx562bq6gdf8hdhf2wh0h5-mdbook-admonish-1.18.0",
+              "default": true
+            }
+          ],
+          "store_path": "/nix/store/fg3pqy6459lx562bq6gdf8hdhf2wh0h5-mdbook-admonish-1.18.0"
+        },
+        "x86_64-darwin": {
+          "outputs": [
+            {
+              "name": "out",
+              "path": "/nix/store/0vddbww043c8w1d4sfk2wpb5ljyq45x7-mdbook-admonish-1.18.0",
+              "default": true
+            }
+          ],
+          "store_path": "/nix/store/0vddbww043c8w1d4sfk2wpb5ljyq45x7-mdbook-admonish-1.18.0"
+        },
+        "x86_64-linux": {
+          "outputs": [
+            {
+              "name": "out",
+              "path": "/nix/store/hs7z4g4v6acd9km5kaw7gibxdpcdijbj-mdbook-admonish-1.18.0",
+              "default": true
+            }
+          ],
+          "store_path": "/nix/store/hs7z4g4v6acd9km5kaw7gibxdpcdijbj-mdbook-admonish-1.18.0"
+        }
+      }
+    },
+    "mdbook@latest": {
+      "last_modified": "2024-12-23T21:10:33Z",
+      "resolved": "github:NixOS/nixpkgs/de1864217bfa9b5845f465e771e0ecb48b30e02d#mdbook",
+      "source": "devbox-search",
+      "version": "0.4.43",
+      "systems": {
+        "aarch64-darwin": {
+          "outputs": [
+            {
+              "name": "out",
+              "path": "/nix/store/5yibli76rfaq70cv0lyasndswbf3hjw8-mdbook-0.4.43",
+              "default": true
+            }
+          ],
+          "store_path": "/nix/store/5yibli76rfaq70cv0lyasndswbf3hjw8-mdbook-0.4.43"
+        },
+        "aarch64-linux": {
+          "outputs": [
+            {
+              "name": "out",
+              "path": "/nix/store/130z9032izdwxdishjkvjrdfacyd1fkq-mdbook-0.4.43",
+              "default": true
+            }
+          ],
+          "store_path": "/nix/store/130z9032izdwxdishjkvjrdfacyd1fkq-mdbook-0.4.43"
+        },
+        "x86_64-darwin": {
+          "outputs": [
+            {
+              "name": "out",
+              "path": "/nix/store/4lcz6mj30f40k08q2s2phdfnydmkk8w2-mdbook-0.4.43",
+              "default": true
+            }
+          ],
+          "store_path": "/nix/store/4lcz6mj30f40k08q2s2phdfnydmkk8w2-mdbook-0.4.43"
+        },
+        "x86_64-linux": {
+          "outputs": [
+            {
+              "name": "out",
+              "path": "/nix/store/izq6ww5isq00l6l02i4yhad2ykn45djm-mdbook-0.4.43",
+              "default": true
+            }
+          ],
+          "store_path": "/nix/store/izq6ww5isq00l6l02i4yhad2ykn45djm-mdbook-0.4.43"
+        }
+      }
+    },
     "mockgen@latest": {
       "last_modified": "2024-11-03T14:18:04Z",
       "resolved": "github:NixOS/nixpkgs/4ae2e647537bcdbb82265469442713d066675275#mockgen",

docs/book.toml

@@ -0,0 +1,31 @@
+[book]
+authors = ["Linode"]
+language = "en"
+multilingual = false
+src = "src"
+title = "Linode Cloud Controller Manager"
+description = "Documentation for the Kubernetes Cloud Controller Manager for Linode"
+
+[output.html]
+git-repository-url = "https://github.com/linode/linode-cloud-controller-manager"
+site-url = "/linode-cloud-controller-manager/"
+edit-url-template = "https://github.com/linode/linode-cloud-controller-manager/edit/master/docs/{path}"
+
+[preprocessor]
+
+[preprocessor.admonish]
+command = "mdbook-admonish"
+assets_version = "3.0.2" # do not edit: managed by `mdbook-admonish install`
+
+[output.html.playground]
+editable = true
+line-numbers = true
+
+[output.html.search]
+limit-results = 20
+use-boolean-and = true
+boost-title = 2
+boost-hierarchy = 2
+boost-paragraph = 1
+expand = true
+heading-split-level = 2

docs/src/SUMMARY.md

@@ -0,0 +1,33 @@
+# Summary
+
+[Introduction](./introduction.md)
+
+# User Guide
+
+- [Getting Started](./getting-started/README.md)
+  - [Overview](./getting-started/overview.md)
+  - [Requirements](./getting-started/requirements.md)
+  - [Installation](./getting-started/installation.md)
+    - [Helm Installation](./getting-started/helm-installation.md)
+    - [Manual Installation](./getting-started/manual-installation.md)
+  - [Verification](./getting-started/verification.md)
+  - [Troubleshooting](./getting-started/troubleshooting.md)
+
+- [Configuration](./configuration/README.md)
+  - [LoadBalancer Services](./configuration/loadbalancer.md)
+  - [Service Annotations](./configuration/annotations.md)
+  - [Node Configuration](./configuration/nodes.md)
+  - [Environment Variables](./configuration/environment.md)
+  - [Firewall Setup](./configuration/firewall.md)
+  - [Route Configuration](./configuration/routes.md)
+  - [Session Affinity](./configuration/session-affinity.md)
+
+- [Examples](./examples/README.md)
+  - [Basic Services](./examples/basic.md)
+  - [Advanced Configuration](./examples/advanced.md)
+
+- [Development Guide](./development/README.md)
+
+---
+
+[Getting Help](./help.md)

docs/src/configuration/README.md

@@ -0,0 +1,57 @@
+# Configuration Guide
+
+The Linode Cloud Controller Manager (CCM) offers extensive configuration options to customize its behavior. This section covers all available configuration methods and options.
+
+## Configuration Areas
+
+1. **[LoadBalancer Services](loadbalancer.md)**
+   - NodeBalancer implementation
+   - BGP-based IP sharing
+   - Protocol configuration
+   - Health checks
+   - SSL/TLS setup
+   - Connection throttling
+   - [See examples](../examples/basic.md#loadbalancer-services)
+
+2. **[Service Annotations](annotations.md)**
+   - NodeBalancer configuration
+   - Protocol settings
+   - Health check options
+   - Port configuration
+   - Firewall settings
+   - [See annotation reference](annotations.md#available-annotations)
+
+3. **[Node Configuration](nodes.md)**
+   - Node labels and topology
+   - Private networking setup
+   - VPC configuration
+   - Node controller behavior
+   - [See node management](nodes.md#node-controller-behavior)
+
+4. **[Environment Variables](environment.md)**
+   - Cache settings
+   - API configuration
+   - Network settings
+   - BGP configuration
+   - [See environment reference](environment.md#available-variables)
+
+5. **[Firewall Setup](firewall.md)**
+   - CCM-managed firewalls
+   - User-managed firewalls
+   - Allow/deny lists
+   - [See firewall options](firewall.md#ccm-managed-firewalls)
+
+6. **[Route Configuration](routes.md)**
+   - VPC routing
+   - Pod CIDR management
+   - Route controller setup
+   - [See route management](routes.md#route-management)
+
+7. **[Session Affinity](session-affinity.md)**
+   - Client IP affinity
+   - Timeout configuration
+   - Service configuration
+   - [See affinity setup](session-affinity.md#configuration)
+
+For installation instructions, see the [Installation Guide](../getting-started/installation.md).
+For troubleshooting help, see the [Troubleshooting Guide](../getting-started/troubleshooting.md).