[docs] refactor/organizing docs

.github/filters.yml

@@ -1,3 +1,3 @@
 # Any file that is not a doc *.md file
 src:
-  - "!**/**.md"
+  - "!**/*.md"

_config.yaml

@@ -0,0 +1 @@
+markdown: GFM

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,117 @@
+# 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
+metadata:
+  annotations:
+    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)

docs/configuration/environment.md

@@ -0,0 +1,87 @@
+# Environment Variables
+
+## Overview
+
+Environment variables provide global configuration options for the CCM. These settings affect caching, API behavior, and networking configurations.
+
+## Available Variables
+
+### Cache Configuration
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `LINODE_INSTANCE_CACHE_TTL` | `15` | Default timeout of instance cache in seconds |
+| `LINODE_ROUTES_CACHE_TTL_SECONDS` | `60` | Default timeout of route cache in seconds |
+
+### API Configuration
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `LINODE_REQUEST_TIMEOUT_SECONDS` | `120` | Default timeout in seconds for http requests to linode API |
+| `LINODE_URL` | `https://api.linode.com/v4` | Linode API endpoint |
+
+### Network Configuration
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `LINODE_EXTERNAL_SUBNET` | "" | Mark private network as external. Example - `172.24.0.0/16` |
+| `BGP_CUSTOM_ID_MAP` | "" | Use your own map instead of default region map for BGP |
+| `BGP_PEER_PREFIX` | `2600:3c0f` | Use your own BGP peer prefix instead of default one |
+
+## Configuration Methods
+
+### Helm Chart
+Configure via `values.yaml`:
+```yaml
+env:
+  - name: LINODE_INSTANCE_CACHE_TTL
+    value: "30"
+```
+
+### Manual Deployment
+Add to the CCM DaemonSet:
+```yaml
+spec:
+  template:
+    spec:
+      containers:
+        - name: ccm-linode
+          env:
+            - name: LINODE_INSTANCE_CACHE_TTL
+              value: "30"
+```
+
+## Usage Guidelines
+
+### Cache Settings
+- Adjust cache TTL based on cluster size and update frequency
+- Monitor memory usage when modifying cache settings
+- Consider API rate limits when decreasing TTL (see [Linode API Rate Limits](@https://techdocs.akamai.com/linode-api/reference/rate-limits))
+
+### API Settings
+- Increase timeout for slower network conditions
+- Use default API URL unless testing/development required
+- Consider regional latency when adjusting timeouts
+
+### Network Settings
+- Configure external subnet for custom networking needs
+- Use BGP settings only when implementing IP sharing
+- Document any custom network configurations
+
+## Troubleshooting
+
+### Common Issues
+
+1. **API Timeouts**
+   - Check network connectivity
+   - Verify API endpoint accessibility
+   - Consider increasing timeout value
+
+2. **Cache Issues**
+   - Monitor memory usage
+   - Verify cache TTL settings
+   - Check for stale data
+
+For more details, see:
+- [Installation Guide](../getting-started/installation.md)
+- [Troubleshooting Guide](../getting-started/troubleshooting.md)

docs/configuration/firewall.md

@@ -0,0 +1,83 @@
+# Firewall Setup
+
+## Overview
+
+The CCM provides two methods for securing NodeBalancers with firewalls:
+1. CCM-managed Cloud Firewalls (using `firewall-acl` annotation)
+2. User-managed Cloud Firewalls (using `firewall-id` annotation)
+
+## CCM-Managed Firewalls
+
+### Configuration
+
+Use the `firewall-acl` annotation to specify firewall rules. The rules should be provided as a JSON object with either an `allowList` or `denyList` (but not both).
+
+#### Allow List Configuration
+```yaml
+apiVersion: v1
+kind: Service
+metadata:
+  name: restricted-service
+  annotations:
+    service.beta.kubernetes.io/linode-loadbalancer-firewall-acl: |
+      {
+        "allowList": {
+          "ipv4": ["192.168.0.0/16", "10.0.0.0/8"],
+          "ipv6": ["2001:db8::/32"]
+        }
+      }
+```
+
+#### Deny List Configuration
+```yaml
+metadata:
+  annotations:
+    service.beta.kubernetes.io/linode-loadbalancer-firewall-acl: |
+      {
+        "denyList": {
+          "ipv4": ["203.0.113.0/24"],
+          "ipv6": ["2001:db8:1234::/48"]
+        }
+      }
+```
+
+### Behavior
+- Only one type of list (allow or deny) can be used per service
+- Rules are automatically created and managed by the CCM
+- Rules are updated when the annotation changes
+- Firewall is deleted when the service is deleted (unless preserved)
+
+## User-Managed Firewalls
+
+### Configuration
+
+1. Create a Cloud Firewall in Linode Cloud Manager
+2. Attach it to the service using the `firewall-id` annotation:
+
+```yaml
+metadata:
+  annotations:
+    service.beta.kubernetes.io/linode-loadbalancer-firewall-id: "12345"
+```
+
+### Management
+- User maintains full control over firewall rules
+- Firewall persists after service deletion
+- Manual updates required for rule changes
+
+## Best Practices
+
+1. **Rule Management**
+   - Use descriptive rule labels
+   - Document rule changes
+   - Regular security audits
+
+2. **IP Range Planning**
+   - Plan CIDR ranges carefully
+   - Document allowed/denied ranges
+   - Consider future expansion
+
+For more information:
+- [Service Annotations](annotations.md#firewall-configuration)
+- [LoadBalancer Configuration](loadbalancer.md)
+- [Linode Cloud Firewall Documentation](https://www.linode.com/docs/products/networking/cloud-firewall/)