[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

.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

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

docs/configuration/annotations.md

@@ -0,0 +1,116 @@
+# Service Annotations
+
+## Overview
+
+Service annotations allow you to customize the behavior of your LoadBalancer services. All Service annotations must be prefixed with: `service.beta.kubernetes.io/linode-loadbalancer-`
+
+For implementation details, see:
+- [LoadBalancer Configuration](loadbalancer.md)
+- [Basic Service Examples](../examples/basic.md)
+- [Advanced Configuration Examples](../examples/advanced.md)
+
+## Available Annotations
+
+### Basic Configuration
+
+| Annotation (Suffix) | Values | Default | Description |
+|--------------------|--------|---------|-------------|
+| `throttle` | `0`-`20` (`0` to disable) | `0` | Client Connection Throttle, which limits the number of subsequent new connections per second from the same client IP |
+| `default-protocol` | `tcp`, `http`, `https` | `tcp` | This annotation is used to specify the default protocol for Linode NodeBalancer |
+| `default-proxy-protocol` | `none`, `v1`, `v2` | `none` | Specifies whether to use a version of Proxy Protocol on the underlying NodeBalancer |
+| `port-*` | json object | | Specifies port specific NodeBalancer configuration. See [Port Configuration](#port-specific-configuration) |
+| `check-type` | `none`, `connection`, `http`, `http_body` | | The type of health check to perform against back-ends. See [Health Checks](loadbalancer.md#health-checks) |
+| `check-path` | string | | The URL path to check on each back-end during health checks |
+| `check-body` | string | | Text which must be present in the response body to pass the health check |
+| `check-interval` | int | | Duration, in seconds, to wait between health checks |
+| `check-timeout` | int (1-30) | | Duration, in seconds, to wait for a health check to succeed |
+| `check-attempts` | int (1-30) | | Number of health check failures necessary to remove a back-end |
+| `check-passive` | bool | `false` | When `true`, `5xx` status codes will cause the health check to fail |
+| `preserve` | bool | `false` | When `true`, deleting a `LoadBalancer` service does not delete the underlying NodeBalancer |
+| `nodebalancer-id` | string | | The ID of the NodeBalancer to front the service |
+| `hostname-only-ingress` | bool | `false` | When `true`, the LoadBalancerStatus will only contain the Hostname |
+| `tags` | string | | A comma separated list of tags to be applied to the NodeBalancer instance |
+| `firewall-id` | string | | An existing Cloud Firewall ID to be attached to the NodeBalancer instance. See [Firewall Setup](firewall.md) |
+| `firewall-acl` | string | | The Firewall rules to be applied to the NodeBalancer. See [Firewall Configuration](#firewall-configuration) |
+
+### Port Specific Configuration
+
+The `port-*` annotation allows per-port configuration, encoded in JSON. For detailed examples, see [LoadBalancer SSL/TLS Setup](loadbalancer.md#ssltls-configuration).
+
+```yaml
+service.beta.kubernetes.io/linode-loadbalancer-port-443: |
+  {
+    "protocol": "https",
+    "tls-secret-name": "my-tls-secret",
+    "proxy-protocol": "v2"
+  }
+```
+
+Available port options:
+- `protocol`: Protocol for this port (tcp, http, https)
+- `tls-secret-name`: Name of TLS secret for HTTPS. The secret type should be `kubernetes.io/tls`
+- `proxy-protocol`: Proxy protocol version for this port
+
+### Deprecated Annotations
+
+| Annotation (Suffix) | Values | Default | Description | Scheduled Removal |
+|--------------------|--------|---------|-------------|-------------------|
+| `proxy-protocol` | `none`, `v1`, `v2` | `none` | Specifies whether to use a version of Proxy Protocol on the underlying NodeBalancer | Q4 2021 |
+
+### Annotation Boolean Values
+For annotations with bool value types, the following string values are interpreted as `true`:
+- `"1"`
+- `"t"`
+- `"T"`
+- `"true"`
+- `"True"`
+- `"TRUE"`
+
+Any other values will be interpreted as `false`. For more details, see [strconv.ParseBool](https://golang.org/pkg/strconv/#ParseBool).
+
+## Examples
+
+### Basic HTTP Service
+```yaml
+metadata:
+  annotations:
+    service.beta.kubernetes.io/linode-loadbalancer-default-protocol: "http"
+    service.beta.kubernetes.io/linode-loadbalancer-check-type: "http"
+    service.beta.kubernetes.io/linode-loadbalancer-check-path: "/healthz"
+```
+
+### HTTPS Service with TLS
+```yaml
+metadata:
+  annotations:
+    service.beta.kubernetes.io/linode-loadbalancer-port-443: |
+      {
+        "protocol": "https",
+        "tls-secret-name": "my-tls-secret"
+      }
+```
+
+### Firewall Configuration
+```yaml
+metadata:
+  annotations:
+    service.beta.kubernetes.io/linode-loadbalancer-firewall-acl: |
+      {
+        "allowList": {
+          "ipv4": ["192.168.0.0/16"],
+          "ipv6": ["2001:db8::/32"]
+        }
+      }
+```
+
+For more examples and detailed configuration options, see:
+- [LoadBalancer Configuration](loadbalancer.md)
+- [Firewall Configuration](firewall.md)
+- [Basic Service Examples](../examples/basic.md)
+- [Advanced Configuration Examples](../examples/advanced.md)
+- [Complete Stack Example](../examples/complete-stack.md)
+
+See also:
+- [Environment Variables](environment.md)
+- [Route Configuration](routes.md)
+- [Session Affinity](session-affinity.md)