Capi docs (#622)

Add common pages to CAPI --------- Co-authored-by: Louise K. Schmidtgen <louise.schmidtgen@canonical.com>
canonical · Aug 30, 2024 · 8432941 · 8432941
1 parent ec5bc4a
commit 8432941
Show file tree

Hide file tree

Showing 16 changed files with 53 additions and 27 deletions.
diff --git a/docs/src/capi/explanation/about.md b/docs/src/capi/explanation/about.md
@@ -0,0 +1,2 @@
+```{include} ../../snap/explanation/about.md
+```
diff --git a/docs/src/capi/explanation/index.md b/docs/src/capi/explanation/index.md
@@ -11,6 +11,10 @@ Overview <self>
 
 ```{toctree}
 :titlesonly:
+:globs:
+
+about
+security
 
 ```
 

diff --git a/docs/src/capi/explanation/security.md b/docs/src/capi/explanation/security.md
@@ -0,0 +1,2 @@
+```{include} /snap/explanation/security.md
+```
diff --git a/docs/src/capi/reference/community.md b/docs/src/capi/reference/community.md
@@ -0,0 +1,2 @@
+```{include} ../../snap/reference/community.md
+```
diff --git a/docs/src/capi/reference/index.md b/docs/src/capi/reference/index.md
@@ -10,7 +10,8 @@ Overview <self>
 
 ```{toctree}
 :titlesonly:
-
+releases
+community
 
 ```
 

diff --git a/docs/src/capi/reference/releases.md b/docs/src/capi/reference/releases.md
@@ -0,0 +1,2 @@
+```{include} ../../snap/reference/releases.md
+```
diff --git a/docs/src/capi/tutorial/getting-started.md b/docs/src/capi/tutorial/getting-started.md
@@ -18,9 +18,9 @@ sudo install -o root -g root -m 0755 clusterctl /usr/local/bin/clusterctl
 
 ### Configure clusterctl
 
-`clusterctl` contains a list of default providers. Right now, Canonical
-Kubernetes is not yet part of that list. To make `clusterctl` aware of the
-Canonical K8s providers, we need to add a clusterctl configuration file.
+`clusterctl` contains a list of default providers. Right now, {{product}} is
+not part of that list. To make `clusterctl` aware of the new 
+providers, we need to add a clusterctl configuration file.
 
 ```
 mkdir -p ~/.config/cluster-api
@@ -241,6 +241,5 @@ sudo k8s kubectl delete cluster ${CLUSTER_NAME}
 
 <!-- Links -->
 [upstream instructions]: https://cluster-api.sigs.k8s.io/user/quick-start#install-clusterctl
-[getting-started]: ../tutorial/getting-started.md
 [CloudFormation]: https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html
 [IAM]: https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html
diff --git a/docs/src/capi/tutorial/index.md b/docs/src/capi/tutorial/index.md
@@ -1,7 +1,7 @@
 # Tutorials
 
 This section contains a step-by-step guide to help you start exploring how to
-install and use {{product}}.
+install and use {{product}} with Cluster API.
 
 ```{toctree}
 :hidden:

diff --git a/docs/src/charm/howto/charm.md b/docs/src/charm/howto/charm.md
@@ -48,8 +48,8 @@ will find the latest features but you may also experience instability.
 
 ## Bootstrap the cluster
 
-Installing the k8s charm sets up all the parts required to run Kubernetes. One may
-watch it progress using juju status:
+Installing the `k8s` charm sets up all the parts required to run Kubernetes.
+You can watch the installation progress using juju status:
 
 ```
 juju status --watch 1s

diff --git a/docs/src/charm/howto/index.md b/docs/src/charm/howto/index.md
@@ -15,6 +15,7 @@ Overview <self>
 :titlesonly:
 
 charm
+install-lxd
 etcd
 proxy
 cos-lite

diff --git a/docs/src/charm/howto/install-lxd.md b/docs/src/charm/howto/install-lxd.md
@@ -1,8 +1,10 @@
 # Installing to localhost/LXD
 
-The main [install instructions][install] work for most circumstances when you
-want to install Canonical Kubernetes from a charm. There are a couple of
-scenarios which require some extra steps however. These are:
+The main [install instructions][install] cover most situations for installing
+{{product}} using a charm. However, there are a few scenarios that require
+additional steps. These include: want to install {{product}} from a charm.
+There are a couple of scenarios which require some extra steps however. These
+are:
 
 - deploying to the 'localhost' cloud
 - deploying to a container on a machine (i.e. when installing a bundle or using
@@ -13,7 +15,7 @@ controlling the container, needs to have a particular configuration in order
 for the Kubernetes components to operate properly.
 
 
-## Apply the Canonical Kubernetes LXD profile
+## Apply the {{product}} LXD profile
 
 On the machine running the 'localhost' cloud, we can determine the existing
 profiles by running the command:
@@ -42,8 +44,8 @@ and edit the profiles easily by using `lxc` commands.
 
 ## Fetching the profile
 
-A working LXD profile is kept in the source repository for the Canonical
-Kubernetes 'k8s' snap. You can retrieve this profile by running the command:
+A working LXD profile is kept in the source repository for the {{product}}
+'k8s' snap. You can retrieve this profile by running the command:
 
 <!-- markdownlint-disable -->
 ```
@@ -70,12 +72,13 @@ process, but you can confirm the contents have changed by running:
 lxc profile show juju-myk8s
 ```
 
-```{note} For an explanation of the settings in this file, [see below](explain-rules)
+```{note} For an explanation of the settings in this file,
+   [see below](explain-rules)
 ```
 
 ## Deploying to a container
 
-We can now deploy Canonical Kubernetes into the lxd based model as described in
+We can now deploy {{product}} into the LXD-based model as described in
 the [charm][] guide.
 
 (explain-rules)=
@@ -124,4 +127,5 @@ need to access for example storage devices (See comment in [^5]).
 [^5]: https://wiki.ubuntu.com/LxcSecurity
 
 [AppArmor]: https://apparmor.net/
-[charm]:    ./charm
+[charm]:    ./charm
+[install]:  ./charm
diff --git a/docs/src/charm/reference/community.md b/docs/src/charm/reference/community.md
@@ -1,4 +1,2 @@
-# Welcome to the {{product}} community
 ```{include} ../../snap/reference/community.md
-:start-after: '# Welcome to the {{product}} community'
 ```
diff --git a/docs/src/index.md b/docs/src/index.md
@@ -71,7 +71,16 @@ Our tutorials, How To guides and other pages will explain how to install,
  configure and use the {{product}} 'k8s' charm.
 ```
 
+
+```{grid-item-card}
+:link: capi/
+### [Deploy K8s using Cluster API ›](capi/index)
+^^^
+Our tutorials, guides and explanation pages will explain how to install,
+ configure and use {{product}} through CAPI.
+```
 ````
+
 ---
 
 ## Project and community

diff --git a/docs/src/snap/explanation/about.md b/docs/src/snap/explanation/about.md
@@ -29,11 +29,12 @@ In addition to the upstream Kubernetes services,
 
 ## Where can I install it?
 
-The {{product}} snap can be installed on a Linux OS, wherever it may
-be: run it in several local containers or VMs for example, or use it on
-public/private cloud instances. 
-For deploying with [Juju], a machine [charm] to deploy
-the snap is also available.
+The {{product}} snap can be installed on a Linux OS, wherever it may be: run it
+in several local containers or VMs for example, or use it on public/private
+cloud instances. For deploying with [Juju], a machine [charm] to deploy the
+snap is also available. 
+For deployment using Cluster API, a Bootstrap and
+Control-plane provider have also been created.
 
 ## Can I use it to make a cluster?
 

diff --git a/docs/src/snap/reference/architecture.md b/docs/src/snap/reference/architecture.md
@@ -59,8 +59,8 @@ The `k8s` snap distribution includes the following:
 
 - **Kubectl**: through which users and other systems interact with Kubernetes
   and drive the cluster operations.
-- **K8s services**: These are all the Kubernetes services as well as core workloads
-  built from upstream and shipped in the snap.
+- **K8s services**: These are all the Kubernetes services as well as core
+  workloads built from upstream and shipped in the snap.
 - State is backed up by **dqlite** by default, which keeps that state of the
   Kubernetes cluster as well as the state we maintain for the needs of the
   cluster operations. The cluster state may optionally be stored in a

diff --git a/docs/src/snap/reference/community.md b/docs/src/snap/reference/community.md
@@ -13,7 +13,8 @@ on how to best achieve a certain goal or maybe some aspect of your Kubernetes
 doesn't behave the way you expect. Perhaps you'd just like some advice from
 more experienced users. There are a number of ways to get in touch:
 
-- Using the [Kubernetes slack][slack]: find us in the #canonical-kubernetes channel
+- Using the [Kubernetes slack][slack]: find us in the #canonical-kubernetes
+  channel
 - In the public [Matrix room][matrix]
 - On the [Ubuntu Discourse][discourse]