Add docs for Juju custom configuration (#937)

Add documentation pages for deploying the k8s operator charms using Juju custom configuration files

docs/src/charm/howto/custom-workers.md

@@ -0,0 +1,63 @@
+# Adding worker nodes with custom configurations
+
+This guide will walk you through how to deploy multiple `k8s-worker`
+applications with different configurations, to create node groups with specific
+capabilities or requirements.
+
+## What you'll need
+
+This guide assumes the following:
+- A working Kubernetes cluster deployed with the `k8s` charm
+
+## Example worker configuration
+
+In this example, we will create two `k8s-worker` applications with different
+configuration options.
+
+```{note}
+The configurations shown below are examples to demonstrate the deployment
+pattern. You should adjust the node configurations, labels, and other
+parameters according to your specific infrastructure requirements, workload
+needs, and organizational policies. Review the [charm configuration] options
+documentation to understand all available parameters that can be customized for
+your worker nodes.
+```
+
+1. Workers for memory-intensive workloads (`worker-memory-config.yaml`):
+```yaml
+memory-workers:
+  bootstrap-node-taints: "workload=memory:NoSchedule"
+  kubelet-extra-args: "system-reserved=memory=2Gi"
+```
+
+2. Workers for GPU workloads (`worker-gpu-config.yaml`):
+```yaml
+gpu-workers:
+  bootstrap-node-taints: "accelerator=nvidia:NoSchedule"
+  node-labels: "gpu=true"
+```
+
+Deploy the worker applications with the custom configurations and integrate them
+with the `k8s` application:
+
+```bash
+juju deploy k8s-worker memory-workers --config ./worker-memory-config.yaml
+juju integrate k8s memory-workers:cluster
+juju integrate k8s memory-workers:containerd
+juju integrate k8s memory-workers:cos-tokens
+
+juju deploy k8s-worker gpu-workers --config ./worker-gpu-config.yaml
+juju integrate k8s gpu-workers:cluster
+juju integrate k8s gpu-workers:containerd
+juju integrate k8s gpu-workers:cos-tokens
+```
+
+Monitor the installation progress by running the following command:
+
+```bash
+juju status --watch 1s
+```
+
+<!-- LINKS -->
+[charm configuration]: https://charmhub.io/k8s/configurations
+

docs/src/charm/howto/index.md

@@ -17,6 +17,8 @@ Overview <self>
 charm
 install-lxd
 install-terraform
+Install with custom configuration <install-custom>
+Add worker nodes with custom configurations <custom-workers>
 openstack
 Integrate with etcd <etcd>
 Integrate with ceph-csi <ceph-csi>

docs/src/charm/howto/install-custom.md

@@ -0,0 +1,75 @@
+# Installing with custom configuration
+
+This guide will walk you through deploying {{product}} using Juju with custom
+configuration options.
+
+## What you'll need
+
+This guide assumes the following:
+-  You have Juju installed on your system with your cloud credentials
+configured and a controller bootstrapped
+- A Juju model is created and selected
+
+## Creating the configuration file
+
+Before deploying the charm, create a YAML file with your desired configuration
+options. Here's an example configuration, which for this guide we'll save as
+`k8s-config.yaml`:
+
+```yaml
+k8s:
+  # Specify the datastore type
+  bootstrap-datastore: dqlite
+
+  # Configure pod and service CIDR ranges
+  bootstrap-pod-cidr: "192.168.0.0/16"
+  bootstrap-service-cidr: "10.152.183.0/24"
+
+  # Enable required features
+  dns-enabled: true
+  gateway-enabled: true
+  ingress-enabled: true
+  metrics-server-enabled: true
+
+  # Configure DNS settings
+  dns-cluster-domain: "cluster.local"
+  dns-upstream-nameservers: "8.8.8.8 8.8.4.4"
+
+  # Add custom node labels
+  node-labels: "environment=production zone=us-east-1"
+
+  # Configure local storage
+  local-storage-enabled: true
+  local-storage-reclaim-policy: "Retain"
+```
+You can find a full list of configuration options in the
+[charm configurations] page.
+
+```{note}
+Remember that some configuration options can only be set during initial
+deployment and cannot be changed afterward. Always review the
+[charm configurations] documentation before deployment to ensure your settings
+align with your requirements.
+```
+
+## Deploying the charm with custom configuration
+
+Deploy the `k8s` charm with your custom configuration:
+
+```bash
+juju deploy k8s --config ./k8s-config.yaml
+```
+
+## Bootstrap the cluster
+
+Monitor the installation progress:
+
+```bash
+juju status --watch 1s
+```
+
+Wait for the unit to reach the `active/idle` state, indicating that the
+{{product}} cluster is ready.
+
+<!-- LINKS -->
+[charm configurations]: https://charmhub.io/k8s/configurations