From 44d869329102206c7d9dd34a6b8f86a7120d35e9 Mon Sep 17 00:00:00 2001 From: Carlos Salas Date: Wed, 29 May 2024 11:55:42 +0200 Subject: [PATCH] docs: add book structure and basic documentation Signed-off-by: Carlos Salas --- README.md | 2 +- docs/README.md | 38 ++++++++++++++++++ docs/book/src/SUMMARY.md | 12 ++++++ docs/book/src/developers/development.md | 21 ++++++++++ docs/book/src/developers/release.md | 1 + docs/book/src/getting-started.md | 1 + docs/book/src/introduction.md | 1 + docs/book/src/roadmap.md | 1 + docs/book/src/topics/index.md | 1 + docs/book/src/topics/prerequisites.md | 53 +++++++++++++++++++++++++ 10 files changed, 130 insertions(+), 1 deletion(-) create mode 100644 docs/README.md create mode 100644 docs/book/src/SUMMARY.md create mode 100644 docs/book/src/developers/development.md create mode 100644 docs/book/src/developers/release.md create mode 100644 docs/book/src/getting-started.md create mode 100644 docs/book/src/introduction.md create mode 100644 docs/book/src/roadmap.md create mode 100644 docs/book/src/topics/index.md create mode 100644 docs/book/src/topics/prerequisites.md diff --git a/README.md b/README.md index 8c53e57..da47c4d 100644 --- a/README.md +++ b/README.md @@ -17,7 +17,7 @@ It provides the following functionality: ## Getting started -Coming soon! +You can refer to the provider documentation [here](./docs/book/src/.). ## Get in contact diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..577b442 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,38 @@ +# Documentation Index + +## Quick start +Before starting your journey with CAAPF, you may want to familiarize with CAPI and the concept of providers. +- [Cluster API Quick Start](https://cluster-api.sigs.k8s.io/user/quick-start.html) +Deploy your own CAPI management cluster and install the Add-on Provider for Fleet. +- [Getting started with CAAPF](./book/src/topics/index.md) + +## Features +- [Roadmap](./book/src/roadmap.md) + +## Development +If you are a developer, the project provides a series of commands that you can use to configure your local environment and operate with the provider. +- [Development Guide](./book/src/developers/development.md) +- [Releasing](./book/src/developers/release.md) + +> Remember that this is a work in progress and the project is looking for more contributors. + +## What is Cluster API Add-on Provider for Fleet (CAAPF)? + +Cluster API Add-on Provider for Fleet (CAAPF) is a Cluster API (CAPI) provider that provides integration with [Fleet](https://github.com/rancher/fleet) to enable the easy deployment of applications to a CAPI provisioned cluster. + +It provides the following functionality: + +- The provider will register a newly provisioned CAPI cluster with Fleet so that applications can be automatically deployed to the created cluster using GitOps. +- The provider will automatically create a [Fleet Cluster Group](https://fleet.rancher.io/cluster-group) for every [CAPI ClusterClass](https://cluster-api.sigs.k8s.io/tasks/experimental-features/cluster-class/). This enables you to deploy the same applications to all clusters created from the same ClusterClass. + +## Demo + +[![asciicast](https://asciinema.org/a/659626.svg)](https://asciinema.org/a/659626) + +## Getting started + +You can refer to the rest of the provider documentation [here](./docs/book/src/.). + +## Get in contact + +You can get in contact with us via the [#cluster-api](https://rancher-users.slack.com/archives/C060L985ZGC) channel on the [Rancher Users Slack](https://slack.rancher.io/). diff --git a/docs/book/src/SUMMARY.md b/docs/book/src/SUMMARY.md new file mode 100644 index 0000000..6bb287d --- /dev/null +++ b/docs/book/src/SUMMARY.md @@ -0,0 +1,12 @@ +# Summary + +[Introduction](./introduction.md) +- [CAPI Introduction](./getting-started.md) +- [Getting Started](./introduction.md) +- [Topics](./topics/index.md) + - [Prerequisites](./topics/prerequisites.md) +- [Developer Guide](./developers/index.md) + - [Development](./developers/development.md) + - [Releasing](./developers/releasing.md) +- [Roadmap](./roadmap.md) + diff --git a/docs/book/src/developers/development.md b/docs/book/src/developers/development.md new file mode 100644 index 0000000..488cf93 --- /dev/null +++ b/docs/book/src/developers/development.md @@ -0,0 +1,21 @@ +# Development + +## Development setup + +### Prerequisites + +- [kind](https://kind.sigs.k8s.io/) +- [helm](https://helm.sh/) +- [just](https://github.com/casey/just) + +### Create a local development environment + +1. Clone the [CAAPF](https://github.com/rancher-sandbox/cluster-api-addon-provider-fleet/) repository locally. +2. The project provides an easy way of starting your own development environment. You can take some time to study the [justfile](../../../../justfile) that includes a number of pre-configured commands to set up and build your own CAPI management cluster and install the addon provider for Fleet. +3. Run the following: +``` +just start-dev +``` +This command will create a kind cluster and manage the installation of the fleet provider and all dependencies. +4. Once the installation is complete, you can inspect the current state of your development cluster. + diff --git a/docs/book/src/developers/release.md b/docs/book/src/developers/release.md new file mode 100644 index 0000000..aa054b5 --- /dev/null +++ b/docs/book/src/developers/release.md @@ -0,0 +1 @@ +# Release diff --git a/docs/book/src/getting-started.md b/docs/book/src/getting-started.md new file mode 100644 index 0000000..01a83b6 --- /dev/null +++ b/docs/book/src/getting-started.md @@ -0,0 +1 @@ +{{#embed-github repo:"kubernetes-sigs/cluster-api" path:"docs/book/src/user/quick-start.md"}} diff --git a/docs/book/src/introduction.md b/docs/book/src/introduction.md new file mode 100644 index 0000000..3bad007 --- /dev/null +++ b/docs/book/src/introduction.md @@ -0,0 +1 @@ +{{#include ../../../README.md}} diff --git a/docs/book/src/roadmap.md b/docs/book/src/roadmap.md new file mode 100644 index 0000000..437766d --- /dev/null +++ b/docs/book/src/roadmap.md @@ -0,0 +1 @@ +# Roadmap diff --git a/docs/book/src/topics/index.md b/docs/book/src/topics/index.md new file mode 100644 index 0000000..303796e --- /dev/null +++ b/docs/book/src/topics/index.md @@ -0,0 +1 @@ +This section contains information about the main CAAPF features and how to use them. diff --git a/docs/book/src/topics/prerequisites.md b/docs/book/src/topics/prerequisites.md new file mode 100644 index 0000000..d72975f --- /dev/null +++ b/docs/book/src/topics/prerequisites.md @@ -0,0 +1,53 @@ +# Prerequisites + +## Requirements + +- [helm](https://helm.sh/) +- [CAPI management cluster](https://cluster-api.sigs.k8s.io/). + - Features `EXP_CLUSTER_RESOURCE_SET` and `CLUSTER_TOPOLOGY` must be enabled. + - It is recommend to use `KUBE_VERSION` >= 1.26.3. + - [clusterctl](https://cluster-api.sigs.k8s.io/user/quick-start.html?highlight=clusterctl#install-clusterctl). + +## Installation + +As this project is still in experimental mode, we recommend you start by installing the provider into a kind development cluster specific for this purpose, so you can interact with it in a safe test environment. **CAUTION: while features of this project are marked as experimental, you could experience unexpected failures**. + +### Create your local cluster + +> NOTE: if you prefer to opt for a one-command installation, you can refer to the notes on how to use `just` and the project's `justfile` [here](../developers/development.md). + +1. Start by adding the helm repositories that are required to proceed with the installation. +``` +helm repo add fleet https://rancher.github.io/fleet-helm-charts/ +helm repo update +``` +2. Navigate to [kind-config.yaml](../../../../testdata/kind-config.yaml) and inspect the kind cluster configuration file, that includes a `LOCAL_IP` environment variable that we'll be setting next, based on your local networking configuration. +``` +export LOCAL_IP=$(ip -4 -j route list default | jq -r .[0].prefsrc) +envsubst < testdata/kind-config.yaml > _out/kind-config.yaml +``` +3. Create the local cluster. It is recommended to use `KUBE_VERSION>=1.26.3`. +``` +kind create cluster --config --image=kindest/node:v{{KUBE_VERSION}} --config _out/kind-config.yaml +``` +4. Install [fleet](https://github.com/rancher/fleet) and specify the `API_SERVER_URL` and CA. +``` +# We start by retrieving the CA data from the cluster +kubectl config view -o json --raw | jq -r '.clusters[] | select(.name=="kind-dev").cluster["certificate-authority-data"]' | base64 -d > _out/ca.pem +# Set the API server URL +API_SERVER_URL=`kubectl config view -o json --raw | jq -r '.clusters[] | select(.name=="kind-dev").cluster["server"]'` +# And proceed with the installation via helm +helm -n cattle-fleet-system install --create-namespace --wait fleet-crd fleet/fleet-crd +helm install --create-namespace -n cattle-fleet-system --set apiServerURL=$API_SERVER_URL --set-file apiServerCA=_out/ca.pem fleet fleet/fleet --wait +``` +5. Install CAPI with the required experimental features enabled and initialized the Docker provider for testing. +``` +EXP_CLUSTER_RESOURCE_SET=true CLUSTER_TOPOLOGY=true clusterctl init -i docker +``` + +Wait for all pods to become ready and your cluster should be ready to use CAAPF! + +**Remember that you can follow along with the video demo to install the provider and get started quickly.** + +[![asciicast](https://asciinema.org/a/659626.svg)](https://asciinema.org/a/659626) +