Initial version of Operator book structure

furkatgofurov7 · furkatgofurov7 · commit 58ec47010adb · 2024-02-26T15:26:39.000+02:00
This commit puts together skeleton of Netlify book structure and
by no means a final one and subject to change and iterations

Signed-off-by: Furkat Gofurov &lt;furkat.gofurov@suse.com&gt;
diff --git a/docs/book/src/01_intro.md b/docs/book/src/01_intro.md
diff --git a/docs/book/src/CONTRIBUTING.MD b/docs/book/src/CONTRIBUTING.MD
@@ -0,0 +1 @@
+{{#include ../../../CONTRIBUTING.md}}
diff --git a/docs/book/src/SUMMARY.md b/docs/book/src/SUMMARY.md
@@ -1,3 +1,30 @@
-[Introduction](./01_intro.md)
--[Installation](./02_installation/00.md)
-    - [Plugin](./02_installation/01_plugin.md)
+# Summary
+
+[Introduction](./introduction.md)
+[Quick Start](./user/quick-start.md)
+- [Installation](./installation/installation.md)
+    - [Using plugin](./installation/plugin-installation.md)
+    - [Using Manifests from Release Assets](./installation/manifest-installation.md)
+    - [Using Helm Charts](./installation/helm-chart-installation.md)
+[Concepts](./user/concepts.md)
+- [Topics](./topics/topics.md)
+    - [Cluster API Provider Lifecycle](./topics/capi-provides-lifecycle.md)
+        - [Installing a Provider](./topics/installing-provider.md)
+        - [Upgrading a Provider](./topics/upgrading-provider.md)
+        - [Modifying a Provider](./topics/modifying-provider.md)
+        - [Deleting a Provider](./topics/deleting-provider.md)
+    - [Basic Cluster API Provider Installation](./topics/basic-capi-provider-installation.md)
+        - [Installing the CoreProvider](./topics/installing-core-provider.md)
+        - [Installing Azure Infrastructure Provider](./topics/installing-capz.md)
+        - [Deleting providers](./topics/deleting-providers.md)
+    - [Air-gapped Environment](./topics/air-gapped-environtment.md)
+    - [Injecting additional manifests](./topics/injecting-additional-manifests.md)
+- [Developer Guide](./developer/guide.md)
+    - [Releasing](./developer/release.md)
+    - [Version migration](./developer/v1alpha1-to-v1alpha2.md)
+- [Reference](./reference/reference.md)
+    - [API Reference](./reference/api_reference.md)
+    - [Glossary](./reference/glossary.md)
+    - [Code of Conduct](./code-of-conduct.md)
+    - [Contributing](./CONTRIBUTING.md)
+    - [CI Jobs](./reference/ci-jobs.md)
diff --git a/docs/book/src/code-of-conduct.md b/docs/book/src/code-of-conduct.md
@@ -0,0 +1,3 @@
+# Code of Conduct
+
+{{#include ../../../code-of-conduct.md}}
diff --git a/docs/book/src/developer/guide.md b/docs/book/src/developer/guide.md
@@ -0,0 +1,104 @@
+# Developer Guide
+
+## Prerequisites
+
+### Docker
+
+Iterating on the Cluster API Operator involves repeatedly building Docker containers.
+
+[docker]: https://docs.docker.com/install/
+
+### A Cluster
+
+You'll likely want an existing cluster as your [management cluster][mcluster].
+The easiest way to do this is with [kind] v0.9 or newer, as explained in the quick start.
+
+Make sure your cluster is set as the default for `kubectl`.
+If it's not, you will need to modify subsequent `kubectl` commands below.
+
+[mcluster]: ../reference/glossary.md#management-cluster
+[kind]: https://github.com/kubernetes-sigs/kind
+
+### kubectl
+
+[kubectl] for interacting with the management cluster.
+
+[kubectl]: https://kubernetes.io/docs/tasks/tools/install-kubectl/
+
+### Helm
+
+[Helm] for installing operator on the cluster (optional).
+
+[Helm]: https://helm.sh/docs/intro/install/
+
+### A container registry
+
+If you're using [kind], you'll need a way to push your images to a registry so they can be pulled.
+You can instead [side-load] all images, but the registry workflow is lower-friction.
+
+Most users test with [GCR], but you could also use something like [Docker Hub][hub].
+If you choose not to use GCR, you'll need to set the `REGISTRY` environment variable.
+
+[side-load]: https://kind.sigs.k8s.io/docs/user/quick-start/#loading-an-image-into-your-cluster
+[GCR]: https://cloud.google.com/container-registry/
+[hub]: https://hub.docker.com/
+
+### Kustomize
+
+You'll need to [install `kustomize`][kustomize].
+There is a version of `kustomize` built into kubectl, but it does not have all the features of `kustomize` v3 and will not work.
+
+[kustomize]: https://kubectl.docs.kubernetes.io/installation/kustomize/
+
+### Kubebuilder
+
+You'll need to [install `kubebuilder`][kubebuilder].
+
+[kubebuilder]: https://book.kubebuilder.io/quick-start.html#installation
+
+### Cert-Manager
+
+You'll need to deploy [cert-manager] components on your [management cluster][mcluster], using `kubectl`
+
+```bash
+kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.14.2/cert-manager.yaml
+```
+
+Ensure the cert-manager webhook service is ready before creating the Cluster API Operator components.
+
+This can be done by following instructions for [manual verification](https://cert-manager.io/docs/installation/verify/#manual-verification)
+from the [cert-manager] web site.
+Note: make sure to follow instructions for the release of cert-manager you are installing.
+
+[cert-manager]: https://github.com/cert-manager/cert-manager
+
+## Development
+
+## Option 1: Tilt
+
+[Tilt][tilt] is a tool for quickly building, pushing, and reloading Docker containers as part of a Kubernetes deployment.
+
+Once you have a running Kubernetes cluster, you can run:
+
+```bash
+tilt up
+```
+
+That's it! Tilt will automatically reload the deployment to your local cluster every time you make a code change.
+
+[tilt]: https://tilt.dev
+
+## Option 2: The kustomize way
+
+```bash
+# Build all the images
+make docker-build
+
+# Push images
+make docker-push
+
+# Apply the manifests
+kustomize build config/default | ./hack/tools/bin/envsubst | kubectl apply -f -
+```
+
+
diff --git a/docs/book/src/developer/release.md b/docs/book/src/developer/release.md
diff --git a/docs/book/src/developer/v1alpha1-to-v1alpha2.md b/docs/book/src/developer/v1alpha1-to-v1alpha2.md
diff --git a/docs/book/src/installation/helm-chart-installation.md b/docs/book/src/installation/helm-chart-installation.md
@@ -0,0 +1 @@
+# Using Helm Charts
diff --git a/docs/book/src/installation/installation.md b/docs/book/src/installation/installation.md
@@ -2,6 +2,3 @@
 
 This section describes `cluster-api-operator` components installation instructions.
 
-## [Plugin](./01_plugin.md)
-
-This document describes the plugin installation steps and prerequisites.
diff --git a/docs/book/src/installation/manifest-installation.md b/docs/book/src/installation/manifest-installation.md
@@ -0,0 +1 @@
+# Using Manifests from Release Assets
diff --git a/docs/book/src/installation/plugin-installation.md b/docs/book/src/installation/plugin-installation.md
diff --git a/docs/book/src/introduction.md b/docs/book/src/introduction.md
@@ -0,0 +1,21 @@
+# Cluster API Operator
+
+The **Cluster API Operator** is a Kubernetes Operator designed to empower cluster administrators to handle the lifecycle of Cluster API providers within a management cluster using a declarative approach. It aims to improve user experience in deploying and managing Cluster API, making it easier to handle day-to-day tasks and automate workflows with GitOps. 
+
+This operator leverages a declarative API and extends the capabilities of the `clusterctl` CLI, allowing greater flexibility and configuration options for cluster administrators.
+
+## Features
+
+- Offers a **declarative API** that simplifies the management of Cluster API providers and enables GitOps workflows.
+- Facilitates **provider upgrades and downgrades** making it more convenient for distributed teams and CI pipelines.
+- Aims to support **air-gapped environments** without direct access to GitHub/GitLab.
+- Leverages **controller-runtime** configuration API for a more flexible Cluster API providers setup.
+- Provides a **transparent and effective** way to interact with various Cluster API components on the management cluster.
+
+## Getting started
+
+* [Quick Start](./user/quick-start.md)
+* [Concepts](./user/concepts.md)
+* [Developer guide](./developer/guide.md)
+* [Contributing](./CONTRIBUTING.md)
+
diff --git a/docs/book/src/reference/api_reference.md b/docs/book/src/reference/api_reference.md
@@ -0,0 +1,7 @@
+# API Reference
+
+Cluster API Operator currently exposes the following APIs:
+
+* Cluster API Operator Custom Resource Definitions (CRDs): [documentation](https://doc.crds.dev/github.com/kubernetes-sigs/cluster-api-operator)
+
+* Golang APIs: [godoc](https://pkg.go.dev/sigs.k8s.io/cluster-api-operator)
diff --git a/docs/book/src/reference/ci-jobs.md b/docs/book/src/reference/ci-jobs.md
@@ -0,0 +1,79 @@
+# CI Jobs
+
+This document intends to provide an overview over our jobs running via Prow, GitHub actions and Google Cloud Build.
+It also documents the cluster-api-operator specific configuration in test-infra.
+
+## Builds and Tests running on the main branch
+
+> NOTE: To see which test jobs execute which tests or e2e tests, you can click on the links which lead to the respective test overviews in testgrid.
+
+The dashboards for the ProwJobs can be found here: https://testgrid.k8s.io/sig-cluster-lifecycle-cluster-api-operator
+
+More details about ProwJob configurations can be found [here](https://github.com/kubernetes/test-infra/tree/master/config/jobs/kubernetes-sigs/cluster-api-operator).
+
+### Presubmits
+
+Prow Presubmits:
+* mandatory for merge, always run:
+  * [pull-cluster-api-operator-build-main] `./scripts/ci-build.sh`
+  * [pull-cluster-api-operator-make-main] `./scripts/ci-make.sh`
+  * [pull-cluster-api-operator-verify-main] `./scripts/ci-verify.sh`
+* mandatory for merge, run if go code changes:
+  * [pull-cluster-api-operator-test-main] `./scripts/ci-test.sh`
+  * [pull-cluster-api-operator-e2e-main] `./scripts/ci-e2e.sh`
+* optional for merge, run if go code changes:
+  * [pull-cluster-api-operator-apidiff-main] `./scripts/ci-apidiff.sh`
+
+GitHub Presubmit Workflows:
+* PR golangci-lint: golangci/golangci-lint-action
+  * Runs golangci-lint. Can be run locally via `make lint`.
+* PR verify: kubernetes-sigs/kubebuilder-release-tools verifier
+  * Verifies the PR titles have a valid format, i.e. contains one of the valid icons.
+  * Verifies the PR description is valid, i.e. is long enough.
+* PR dependabot (run on dependabot PRs)
+  * Regenerates Go modules and code.
+  
+Other Github workflows
+* release (runs when tags are pushed)
+  * Creates a GitHub release with release notes for the tag.
+* book publishing
+  * Deploys operator book to GitHub Pages
+
+### Postsubmits
+
+Prow Postsubmits:
+* [post-cluster-api-operator-push-images] Google Cloud Build: `make release-staging`
+
+### Periodics
+
+Prow Periodics:
+* [periodic-cluster-api-operator-test-main] `./scripts/ci-test.sh`
+* [periodic-cluster-api-operator-e2e-main] `./scripts/ci-e2e.sh`
+
+## Test-infra configuration
+
+* config/jobs/image-pushing/k8s-staging-cluster-api.yaml
+  * Configures postsubmit job to push images and manifests.
+* config/jobs/kubernetes-sigs/cluster-api-operator/
+  * Configures Cluster API Operator presubmit and periodic jobs.
+* config/testgrids/kubernetes/sig-cluster-lifecycle/config.yaml
+  * Configures Cluster API Operator testgrid dashboards.
+* config/prow/plugins.yaml
+  * `approve`: disable auto-approval of PR authors, ignore GitHub reviews (/approve is explicitly required)
+  * `lgtm`: enables retaining lgtm through squash
+  * `require_matching_label`: configures `needs-triage`
+  * `plugins`: enables `require-matching-label` plugin
+  * `external_plugins`: enables `cherrypicker` plugin
+* label_sync/labels.yaml
+  * Configures labels for the `cluster-api-operator` repository.
+
+<!-- links -->
+[pull-cluster-api-operator-build-main]: https://testgrid.k8s.io/sig-cluster-lifecycle-cluster-api-operator#capi-operator-pr-build-main
+[pull-cluster-api-operator-make-main]: https://testgrid.k8s.io/sig-cluster-lifecycle-cluster-api-operator#capi-operator-pr-make-main
+[pull-cluster-api-operator-verify-main]: https://testgrid.k8s.io/sig-cluster-lifecycle-cluster-api-operator#capi-operator-pr-verify-main
+[pull-cluster-api-operator-test-main]: https://testgrid.k8s.io/sig-cluster-lifecycle-cluster-api-operator#capi-operator-pr-test-main
+[pull-cluster-api-operator-e2e-main]: https://testgrid.k8s.io/sig-cluster-lifecycle-cluster-api-operator#capi-operator-pr-e2e-main
+[pull-cluster-api-operator-apidiff-main]: https://testgrid.k8s.io/sig-cluster-lifecycle-cluster-api-operator#capi-operator-pr-apidiff-main
+[post-cluster-api-operator-push-images]: https://testgrid.k8s.io/sig-cluster-lifecycle-image-pushes#post-cluster-api-operator-push-images
+[periodic-cluster-api-operator-test-main]: https://testgrid.k8s.io/sig-cluster-lifecycle-cluster-api-operator#capi-operator-test-main
+[periodic-cluster-api-operator-e2e-main]: https://testgrid.k8s.io/sig-cluster-lifecycle-cluster-api-operator#capi-operator-e2e-main
diff --git a/docs/book/src/reference/glossary.md b/docs/book/src/reference/glossary.md
@@ -0,0 +1,3 @@
+# Glossary
+
+The lexicon used in this document is described in more detail [here](https://github.com/kubernetes-sigs/cluster-api/blob/main/docs/book/src/reference/glossary.md). Any discrepancies should be rectified in the main Cluster API glossary.
diff --git a/docs/book/src/reference/providers.md b/docs/book/src/reference/providers.md
@@ -0,0 +1 @@
+# Provider List
diff --git a/docs/book/src/reference/reference.md b/docs/book/src/reference/reference.md
@@ -0,0 +1 @@
+# Reference
diff --git a/docs/book/src/topics/air-gapped-environtment.md b/docs/book/src/topics/air-gapped-environtment.md
@@ -0,0 +1 @@
+# Air-gapped Environment
diff --git a/docs/book/src/topics/basic-capi-provider-installation.md b/docs/book/src/topics/basic-capi-provider-installation.md
@@ -0,0 +1 @@
+# Basic Cluster API Provider Installation
diff --git a/docs/book/src/topics/capi-provides-lifecycle.md b/docs/book/src/topics/capi-provides-lifecycle.md
@@ -0,0 +1 @@
+# Cluster API Provider Lifecycle
diff --git a/docs/book/src/topics/deleting-provider.md b/docs/book/src/topics/deleting-provider.md
@@ -0,0 +1 @@
+# Deleting a Provider
diff --git a/docs/book/src/topics/deleting-providers.md b/docs/book/src/topics/deleting-providers.md
@@ -0,0 +1 @@
+# Deleting providers
diff --git a/docs/book/src/topics/injecting-additional-manifests.md b/docs/book/src/topics/injecting-additional-manifests.md
@@ -0,0 +1 @@
+# Injecting additional manifests
diff --git a/docs/book/src/topics/installing-capz.md b/docs/book/src/topics/installing-capz.md
@@ -0,0 +1 @@
+# Installing Azure Infrastructure Provider
diff --git a/docs/book/src/topics/installing-core-provider.md b/docs/book/src/topics/installing-core-provider.md
@@ -0,0 +1 @@
+# Installing the CoreProvider
diff --git a/docs/book/src/topics/installing-provider.md b/docs/book/src/topics/installing-provider.md
@@ -0,0 +1 @@
+# Installing a Provider
diff --git a/docs/book/src/topics/modifying-provider.md b/docs/book/src/topics/modifying-provider.md
@@ -0,0 +1 @@
+# Modifying a Provider
diff --git a/docs/book/src/topics/topics.md b/docs/book/src/topics/topics.md
@@ -0,0 +1,3 @@
+# Topics
+
+This section contains information about enabling and configuring various features of Cluster API Operator.
diff --git a/docs/book/src/topics/upgrading-provider.md b/docs/book/src/topics/upgrading-provider.md
@@ -0,0 +1 @@
+# Upgrading a Provider
diff --git a/docs/book/src/user/concepts.md b/docs/book/src/user/concepts.md
@@ -0,0 +1,38 @@
+# Concepts
+
+## CoreProvider
+
+A component responsible for providing the fundamental building blocks of the Cluster API. It defines and implements the main Cluster API resources such as Clusters, Machines, and MachineSets, and manages their lifecycle. This includes:
+
+1. Defining the main Cluster API resources and their schemas.
+2. Implementing the logic for creating, updating, and deleting these resources.
+3. Managing the overall lifecycle of Clusters, Machines, and MachineSets.
+4. Providing the base upon which other providers like BootstrapProvider and InfrastructureProvider build.
+
+## BootstrapProvider
+
+A component responsible for turning a server into a Kubernetes node as well as for:
+
+1. Generating the cluster certificates, if not otherwise specified
+2. Initializing the control plane, and gating the creation of other nodes until it is complete
+3. Joining control plane and worker nodes to the cluster
+
+## ControlPlaneProvider
+
+A component responsible for managing the control plane of a Kubernetes cluster. This includes:
+
+1. Provisioning the control plane nodes.
+2. Managing the lifecycle of the control plane, including upgrades and scaling.
+
+## InfrastructureProvider
+
+A component responsible for the provisioning of infrastructure/computational resources required by the Cluster or by Machines (e.g. VMs, networking, etc.). 
+For example, cloud Infrastructure Providers include AWS, Azure, and Google, and bare metal Infrastructure Providers include VMware, MAAS, and metal3.io.
+
+## AddonProvider
+
+A component that extends the functionality of Cluster API by providing a solution for managing the installation, configuration, upgrade, and deletion of Cluster add-ons using Helm charts.
+
+## IPAMProvider
+
+A component that manages pools of IP addresses using Kubernetes resources. It serves as a reference implementation for IPAM providers, but can also be used as a simple replacement for DHCP.
diff --git a/docs/book/src/user/quick-start.md b/docs/book/src/user/quick-start.md
diff --git a/docs/book/theme/css/general.css b/docs/book/theme/css/general.css
diff --git a/docs/book/theme/favicon.png b/docs/book/theme/favicon.png
diff --git a/docs/book/theme/highlight.css b/docs/book/theme/highlight.css

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+# Code of Conduct`
	`2`	`+`
	`3`	`+{{#include ../../../code-of-conduct.md}}`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+# Glossary`
	`2`	`+`
	`3`	`+The lexicon used in this document is described in more detail [here](https://github.com/kubernetes-sigs/cluster-api/blob/main/docs/book/src/reference/glossary.md). Any discrepancies should be rectified in the main Cluster API glossary.`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+# Basic Cluster API Provider Installation`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+# Installing Azure Infrastructure Provider`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+# Topics`
	`2`	`+`
	`3`	`+This section contains information about enabling and configuring various features of Cluster API Operator.`