From 58ec47010adb70e1a57f93c96c2d7c04ae81b41e Mon Sep 17 00:00:00 2001 From: Furkat Gofurov Date: Mon, 26 Feb 2024 10:35:43 +0200 Subject: [PATCH] Initial version of Operator book structure 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 --- docs/book/src/01_intro.md | 8 - docs/book/src/CONTRIBUTING.MD | 1 + docs/book/src/SUMMARY.md | 33 +- docs/book/src/code-of-conduct.md | 3 + docs/book/src/developer/guide.md | 104 ++++ docs/{ => book/src/developer}/release.md | 0 .../src/developer}/v1alpha1-to-v1alpha2.md | 0 .../installation/helm-chart-installation.md | 1 + .../00.md => installation/installation.md} | 3 - .../src/installation/manifest-installation.md | 1 + .../plugin-installation.md} | 0 docs/book/src/introduction.md | 21 + docs/book/src/reference/api_reference.md | 7 + docs/book/src/reference/ci-jobs.md | 79 +++ docs/book/src/reference/glossary.md | 3 + docs/book/src/reference/providers.md | 1 + docs/book/src/reference/reference.md | 1 + .../src/topics/air-gapped-environtment.md | 1 + .../basic-capi-provider-installation.md | 1 + .../src/topics/capi-provides-lifecycle.md | 1 + docs/book/src/topics/deleting-provider.md | 1 + docs/book/src/topics/deleting-providers.md | 1 + .../topics/injecting-additional-manifests.md | 1 + docs/book/src/topics/installing-capz.md | 1 + .../src/topics/installing-core-provider.md | 1 + docs/book/src/topics/installing-provider.md | 1 + docs/book/src/topics/modifying-provider.md | 1 + docs/book/src/topics/topics.md | 3 + docs/book/src/topics/upgrading-provider.md | 1 + docs/book/src/user/concepts.md | 38 ++ docs/book/src/user/quick-start.md | 66 ++ docs/book/theme/css/general.css | 588 ++++++++++++++++++ docs/book/theme/favicon.png | Bin 0 -> 2522 bytes docs/book/theme/highlight.css | 74 +++ 34 files changed, 1032 insertions(+), 14 deletions(-) delete mode 100644 docs/book/src/01_intro.md create mode 100644 docs/book/src/CONTRIBUTING.MD create mode 100644 docs/book/src/code-of-conduct.md create mode 100644 docs/book/src/developer/guide.md rename docs/{ => book/src/developer}/release.md (100%) rename docs/{migrations => book/src/developer}/v1alpha1-to-v1alpha2.md (100%) create mode 100644 docs/book/src/installation/helm-chart-installation.md rename docs/book/src/{02_installation/00.md => installation/installation.md} (50%) create mode 100644 docs/book/src/installation/manifest-installation.md rename docs/book/src/{02_installation/01_plugin.md => installation/plugin-installation.md} (100%) create mode 100644 docs/book/src/introduction.md create mode 100644 docs/book/src/reference/api_reference.md create mode 100644 docs/book/src/reference/ci-jobs.md create mode 100644 docs/book/src/reference/glossary.md create mode 100644 docs/book/src/reference/providers.md create mode 100644 docs/book/src/reference/reference.md create mode 100644 docs/book/src/topics/air-gapped-environtment.md create mode 100644 docs/book/src/topics/basic-capi-provider-installation.md create mode 100644 docs/book/src/topics/capi-provides-lifecycle.md create mode 100644 docs/book/src/topics/deleting-provider.md create mode 100644 docs/book/src/topics/deleting-providers.md create mode 100644 docs/book/src/topics/injecting-additional-manifests.md create mode 100644 docs/book/src/topics/installing-capz.md create mode 100644 docs/book/src/topics/installing-core-provider.md create mode 100644 docs/book/src/topics/installing-provider.md create mode 100644 docs/book/src/topics/modifying-provider.md create mode 100644 docs/book/src/topics/topics.md create mode 100644 docs/book/src/topics/upgrading-provider.md create mode 100644 docs/book/src/user/concepts.md create mode 100644 docs/book/src/user/quick-start.md create mode 100644 docs/book/theme/css/general.css create mode 100644 docs/book/theme/favicon.png create mode 100644 docs/book/theme/highlight.css diff --git a/docs/book/src/01_intro.md b/docs/book/src/01_intro.md deleted file mode 100644 index fb538f579..000000000 --- a/docs/book/src/01_intro.md +++ /dev/null @@ -1,8 +0,0 @@ -# Cluster API Operator - -## ✨ What is 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. - diff --git a/docs/book/src/CONTRIBUTING.MD b/docs/book/src/CONTRIBUTING.MD new file mode 100644 index 000000000..d05eb6229 --- /dev/null +++ b/docs/book/src/CONTRIBUTING.MD @@ -0,0 +1 @@ +{{#include ../../../CONTRIBUTING.md}} \ No newline at end of file diff --git a/docs/book/src/SUMMARY.md b/docs/book/src/SUMMARY.md index 546eacada..e929730c4 100644 --- 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) \ No newline at end of file +# 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) \ No newline at end of file diff --git a/docs/book/src/code-of-conduct.md b/docs/book/src/code-of-conduct.md new file mode 100644 index 000000000..e28dbc062 --- /dev/null +++ b/docs/book/src/code-of-conduct.md @@ -0,0 +1,3 @@ +# Code of Conduct + +{{#include ../../../code-of-conduct.md}} \ No newline at end of file diff --git a/docs/book/src/developer/guide.md b/docs/book/src/developer/guide.md new file mode 100644 index 000000000..0c068a60e --- /dev/null +++ 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/release.md b/docs/book/src/developer/release.md similarity index 100% rename from docs/release.md rename to docs/book/src/developer/release.md diff --git a/docs/migrations/v1alpha1-to-v1alpha2.md b/docs/book/src/developer/v1alpha1-to-v1alpha2.md similarity index 100% rename from docs/migrations/v1alpha1-to-v1alpha2.md rename to 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 new file mode 100644 index 000000000..639325eb7 --- /dev/null +++ b/docs/book/src/installation/helm-chart-installation.md @@ -0,0 +1 @@ +# Using Helm Charts diff --git a/docs/book/src/02_installation/00.md b/docs/book/src/installation/installation.md similarity index 50% rename from docs/book/src/02_installation/00.md rename to docs/book/src/installation/installation.md index 2f5c01414..372bfd1b8 100644 --- a/docs/book/src/02_installation/00.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. \ No newline at end of file diff --git a/docs/book/src/installation/manifest-installation.md b/docs/book/src/installation/manifest-installation.md new file mode 100644 index 000000000..f0def43c7 --- /dev/null +++ b/docs/book/src/installation/manifest-installation.md @@ -0,0 +1 @@ +# Using Manifests from Release Assets diff --git a/docs/book/src/02_installation/01_plugin.md b/docs/book/src/installation/plugin-installation.md similarity index 100% rename from docs/book/src/02_installation/01_plugin.md rename to docs/book/src/installation/plugin-installation.md diff --git a/docs/book/src/introduction.md b/docs/book/src/introduction.md new file mode 100644 index 000000000..d38024a67 --- /dev/null +++ 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 new file mode 100644 index 000000000..aa8c92933 --- /dev/null +++ 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) \ No newline at end of file diff --git a/docs/book/src/reference/ci-jobs.md b/docs/book/src/reference/ci-jobs.md new file mode 100644 index 000000000..c7c50bf98 --- /dev/null +++ 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. + + +[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 \ No newline at end of file diff --git a/docs/book/src/reference/glossary.md b/docs/book/src/reference/glossary.md new file mode 100644 index 000000000..aa7a73cb5 --- /dev/null +++ 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. \ No newline at end of file diff --git a/docs/book/src/reference/providers.md b/docs/book/src/reference/providers.md new file mode 100644 index 000000000..cd5844f79 --- /dev/null +++ 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 new file mode 100644 index 000000000..cf5aa0741 --- /dev/null +++ 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 new file mode 100644 index 000000000..c7f70b313 --- /dev/null +++ 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 new file mode 100644 index 000000000..d73c9988a --- /dev/null +++ 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 new file mode 100644 index 000000000..0e56a0c60 --- /dev/null +++ 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 new file mode 100644 index 000000000..f37f1465a --- /dev/null +++ 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 new file mode 100644 index 000000000..5039f1a85 --- /dev/null +++ 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 new file mode 100644 index 000000000..56498f2d0 --- /dev/null +++ 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 new file mode 100644 index 000000000..a29dc41aa --- /dev/null +++ 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 new file mode 100644 index 000000000..b01fe9f45 --- /dev/null +++ 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 new file mode 100644 index 000000000..d4169de44 --- /dev/null +++ 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 new file mode 100644 index 000000000..b156e8675 --- /dev/null +++ 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 new file mode 100644 index 000000000..4dc0ce347 --- /dev/null +++ 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. \ No newline at end of file diff --git a/docs/book/src/topics/upgrading-provider.md b/docs/book/src/topics/upgrading-provider.md new file mode 100644 index 000000000..af55ff5a6 --- /dev/null +++ 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 new file mode 100644 index 000000000..8a1cd4831 --- /dev/null +++ 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. \ No newline at end of file diff --git a/docs/book/src/user/quick-start.md b/docs/book/src/user/quick-start.md new file mode 100644 index 000000000..0de75e66e --- /dev/null +++ b/docs/book/src/user/quick-start.md @@ -0,0 +1,66 @@ +# Quickstart + +This is a quickstart guide for getting Cluster API Operator up and running on your Kubernetes cluster. + +## Prerequisites + +- [Running Kubernetes cluster](https://cluster-api.sigs.k8s.io/user/quick-start#install-andor-configure-a-kubernetes-cluster). +- [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) for interacting with the management cluster. +- [Helm](https://helm.sh/docs/intro/install/) for installing operator on the cluster (optional). + +## Install and configure Cluster API Operator + +### Configuring credential for cloud providers + +Instead of using environment variables as clusterctl does, Cluster API Operator uses Kubernetes secrets to store credentials for cloud providers. Refer to [provider documentation](https://cluster-api.sigs.k8s.io/user/quick-start#initialization-for-common-providers) on which credentials are required. + +This example uses AWS provider, but the same approach can be used for other providers. + +```bash +export CREDENTIALS_SECRET_NAME="credentials-secret" +export CREDENTIALS_SECRET_NAMESPACE="default" + +kubectl create secret generic "${CREDENTIALS_SECRET_NAME}" --from-literal=AWS_B64ENCODED_CREDENTIALS="${AWS_B64ENCODED_CREDENTIALS}" --namespace "${CREDENTIALS_SECRET_NAMESPACE}" +``` + +### Installing Cluster API Operator + +#### Method 1: Apply Manifests from Release Assets + +Before installing the Cluster API Operator this way, you must first ensure that cert-manager is installed, as the operator does not manage cert-manager installations. To install cert-manager, run the following command: + +```bash +kubectl apply -f https://github.com/jetstack/cert-manager/releases/latest/download/cert-manager.yaml +``` + +Wait for cert-manager to be ready before proceeding. + +After cert-manager is successfully installed, you can install the Cluster API operator directly by applying the latest release assets: + +```bash +kubectl apply -f https://github.com/kubernetes-sigs/cluster-api-operator/releases/latest/download/operator-components.yaml +``` + +#### Method 2: Use Helm Charts + +Alternatively, you can install the Cluster API operator using Helm charts: + +```bash +helm repo add capi-operator https://kubernetes-sigs.github.io/cluster-api-operator +helm repo update +helm install capi-operator capi-operator/cluster-api-operator --create-namespace -n capi-operator-system +``` + +##### Installing cert-manager using Helm chart + +CAPI operator Helm chart supports provisioning of cert-manager as a dependency. It is disabled by default, but you can enable it with `--set cert-manager.enabled=true` option to `helm install` command or inside of `cert-manager` section in [values.yaml](https://github.com/kubernetes-sigs/cluster-api-operator/blob/main/hack/charts/cluster-api-operator/values.yaml) file. Additionally you can define other [parameters](https://artifacthub.io/packages/helm/cert-manager/cert-manager#configuration) provided by the cert-manager chart. + +##### Installing providers using Helm chart + +Deploy Cluster API components with docker provider using a single command during operator installation: + +```bash +helm install capi-operator capi-operator/cluster-api-operator --create-namespace -n capi-operator-system --set infrastructure=docker --set cert-manager.enabled=true --set configSecret.name=${CREDENTIALS_SECRET_NAME} --set configSecret.namespace=${CREDENTIALS_SECRET_NAMESPACE} --wait --timeout 90s +``` + +Docker provider can be replaced by any provider supported by [clusterctl](https://cluster-api.sigs.k8s.io/reference/providers.html#infrastructure). \ No newline at end of file diff --git a/docs/book/theme/css/general.css b/docs/book/theme/css/general.css new file mode 100644 index 000000000..39769b97e --- /dev/null +++ b/docs/book/theme/css/general.css @@ -0,0 +1,588 @@ +/* Base styles and content styles */ + +@import 'variables.css'; + +html { + font-family: "Lato", "Open Sans", sans-serif; + color: var(--fg); + background-color: var(--bg); + text-size-adjust: none; +} + +body { + margin: 0; + font-size: 1rem; + overflow-x: hidden; +} + +code { + font-family: "IBM Plex Mono", "Source Code Pro", Consolas, "Ubuntu Mono", Menlo, "DejaVu Sans Mono", monospace, monospace; + font-size: 0.875em; /* please adjust the ace font size accordingly in editor.js */ +} + +.left { float: left; } +.right { float: right; } +.hidden { display: none; } +.play-button.hidden { display: none; } + +h2, h3 { margin-top: 2.5em; } +h4, h5 { margin-top: 2em; } + +.header + .header h3, +.header + .header h4, +.header + .header h5 { + margin-top: 1em; +} + +a.header:target h1:before, +a.header:target h2:before, +a.header:target h3:before, +a.header:target h4:before { + display: inline-block; + content: "»"; + margin-left: -30px; + width: 30px; +} + +.page { + outline: 0; + padding: 0 var(--page-padding); +} +.page-wrapper { + box-sizing: border-box; +} +.js .page-wrapper { + transition: margin-left 0.3s ease, transform 0.3s ease; /* Animation: slide away */ +} + +.content { + overflow-y: auto; + padding: 0 15px; + padding-bottom: 50px; +} +.content main { + margin-left: auto; + margin-right: auto; + max-width: var(--content-max-width); +} +.content a { text-decoration: none; } +.content a:hover { text-decoration: underline; } +.content img { max-width: 100%; } +.content .header:link, +.content .header:visited { + color: var(--fg); +} +.content .header:link, +.content .header:visited:hover { + text-decoration: none; +} + +table { + width: 100%; + border-collapse: collapse; +} +table td { + padding: 3px 20px; + border: 1px var(--table-border-color) solid; +} +table thead { + background: var(--table-header-bg); +} +table thead td { + font-weight: 700; + border: none; +} +table thead tr { + border: 1px var(--table-header-bg) solid; +} +/* Alternate background colors for rows */ +table tbody tr:nth-child(2n) { + background: var(--table-alternate-bg); +} + + +blockquote { + margin: 20px 0; + padding: 0 20px; + color: var(--fg); + background-color: var(--quote-bg); + border-top: .1em solid var(--quote-border); + border-bottom: .1em solid var(--quote-border); +} + + +:not(.footnote-definition) + .footnote-definition, +.footnote-definition + :not(.footnote-definition) { + margin-top: 2em; +} +.footnote-definition { + font-size: 0.9em; + margin: 0.5em 0; +} +.footnote-definition p { + display: inline; +} + +.tooltiptext { + position: absolute; + visibility: hidden; + color: #fff; + background-color: #333; + transform: translateX(-50%); /* Center by moving tooltip 50% of its width left */ + left: -8px; /* Half of the width of the icon */ + top: -35px; + font-size: 0.8em; + text-align: center; + border-radius: 6px; + padding: 5px 8px; + margin: 5px; + z-index: 1000; +} +.tooltipped .tooltiptext { + visibility: visible; +} + +/* From here on out is custom stuff */ + +/* marker docs styles */ + +/* NB(directxman12): The general gist of this is that we use semantic markup + * for the actual HTML as much as possible, and then use CSS to look pretty and + * extract the actual relevant information. Theoretically, this'll let us do + * stuff like transform the information for different screen widths. */ + +/* the marker */ +.marker { + display: flex; + flex-wrap: wrap; + align-items: center; + margin-bottom: 0.25em; +} + +/* the marker name */ +.marker > dt.name::before { + content: '// +'; +} +.marker > dt.name { + font-weight: bold; + order: 0; /* hack around the ::before's positioning to get it after the line */ +} + +/* the target blob */ +.marker::before { + content: "on " attr(data-target); + padding: 1px 6px; + border-radius: 20%; + background: var(--quote-bg); + margin-left: 0.5em; + font-weight: normal; + opacity: 0.75; + font-size: 0.75em; + order: 2; /* hack around the ::before's positioning to get it after the line */ +} + +/* deprecated markers */ +.marker.deprecated[data-target] { + /* use attribute marker for specificity */ + order: 4; + opacity: 0.65; +} + +.marker.deprecated::before { + content: "deprecated (on " attr(data-target) ")"; + color: red; +} +.marker.deprecated:not([data-deprecated=""])::before { + content: "use " attr(data-deprecated) " (on " attr(data-target) ")"; + color: red; +} + +/* the summary arguments (hidden in non-summary view) */ +.marker dd.args { + margin-left: 0; + font-family: mono; + order: 1; /* hack around the ::before's positioning to get it after the line */ +} +.marker dl.args.summary { + display: inline-block; + margin-bottom: 0; + margin-top: 0; +} +/* TODO(directxman12): optional */ +.marker dl.args.summary dt { + display: inline-block; + font-style: inherit; +} +.marker dl.args.summary dt:first-child::before { + content: ':'; +} +.marker dl.args.summary dt::before { + content: ','; +} +/* hide in non-summary view */ +.marker dd.args { + display: none +} + +/* the description */ +.marker dd.description { + order: 3; /* hack around the ::before's positioning to get it after the line */ + width: 100%; + display: flex; + flex-direction: column; +} + +/* all arguments */ +.marker dl.args dt.argument::after { + content: '='; +} +.marker dl.args dd.type { + font-style: italic; +} +.marker .argument { + display: inline-block; + margin-left: 0; +} +.marker .argument.type { + font-size: 0.875em; +} +.marker .literal { + font-family:"IBM Plex Mono", "Source Code Pro", Consolas, "Ubuntu Mono", Menlo, "DejaVu Sans Mono", monospace, monospace; + font-size: 0.875em; /* please adjust the ace font size accordingly in editor.js */ +} +.marker .argument.type::before { + content: '‹'; +} +.marker .argument.type::after { + content: '›'; +} + +/* summary args */ +.marker .args.summary .argument.optional { + opacity: 0.75; +} + +/* anonymous marker args */ +.marker.anonymous .description details { + order: 1; + flex: 1; /* don't cause arg syntax to wrap */ +} +.marker.anonymous .description .args { + order: 0; /* go before the description */ + + /* all on a single line */ + margin-top: 0; + margin-bottom: 0; + margin-right: 1em; +} +.marker.anonymous .description { + flex-direction: row; +} +.marker .description dl.args:empty { + margin-top: 0; +} + +.marker .type .slice::before { + content: '[]'; +} + +/* description args */ +.marker .description dt.argument.optional::before { + content: "opt"; + padding: 1px 4px; + border-radius: 20%; + background: var(--quote-bg); + opacity: 0.5; + margin-left: -3em; + float: left; +} + +/* help text */ +.marker summary.no-details { + list-style: none; +} +.marker summary.no-details::-webkit-details-marker { + display: none; +} + +/* summary view */ +.markers-summarize:checked ~ dl > .marker dd.args { + display: inline-block +} +.markers-summarize:checked ~ dl > .marker dd.description dl.args { + display: none +} +.markers-summarize:checked ~ dl > .marker dd.description { + margin-bottom: 0.25em; +} + +input.markers-summarize { + display: none; +} +label.markers-summarize::before { + margin-right: 0.5em; + content: '\25bc'; + display: inline-block; +} +input.markers-summarize:checked ~ label.markers-summarize::before { + content: '\25b6'; +} + +/* misc */ +/* marker details should be indented to be in line with the summary, + * which is indented due to the expando + */ +.marker details > p { + margin-left: 1em; +} + +/* sort by target */ +.marker[data-target="package"] { + order: 2; +} +.marker[data-target="type"] { + order: 1; +} +.marker[data-target="field"] { + order: 0; +} +.markers { + display: flex; + flex-direction: column; +} + +/* details elements (not markers) */ +details.collapse-code { + margin-top: 0.125em; + margin-bottom: 0.125em; +} + +details.collapse-code > summary { + width: 100%; + cursor: pointer; + display: flex; + box-sizing: border-box; /* why isn't this the default? :-/ */ +} + +details.collapse-code > summary::after { + content: "\25c0"; + float: right; + font-size: 0.875em; + color: var(--inline-code-color); + opacity: 0.8; +} + +details.collapse-code[open] > summary::after { + content: "\25bc"; +} + +details.collapse-code > summary pre { + flex: 1; + box-sizing: border-box; /* why isn't this the default? :-/ */ + margin: inherit; + padding: 0.25em 0.5em; +} + +details.collapse-code > summary pre span::after { + content: " (hidden)"; + font-size: 80%; +} + +details.collapse-code[open] > summary pre span::after { + content: ""; +} + +details.collapse-code > summary pre span::before { + content: "// "; +} + +/* make summary into code a bit nicer looking */ +details.collapse-code[open] > summary + pre { + margin-top: 0; +} + +/* get rid of the ugly blue box that makes the summary->code look bad */ +details.collapse-code summary:focus { + outline: none; + font-weight: bold; /* keep something around for tab users */ +} + +/* don't show the default expando */ +details.collapse-code > summary { + list-style: none; +} +details.collapse-code > summary::-webkit-details-marker { + display: none; +} + + +/* diagrams */ + +.diagrams { + display: flex; + flex-direction: row; + align-items: center; +} + +.diagrams > * { + margin-left: 1em; + margin-right: 1em; + font-size: 160%; + font-weight: bold; +} + +.diagrams object, .diagrams svg { + max-width: 100%; + max-height: 10em; /* force svg height to behave */ +} + +.diagrams path, .diagrams polyline, .diagrams circle { + stroke: var(--fg); +} + +.diagrams path.text { + fill: var(--fg); + stroke: none; +} + +.diagrams path.text.invert { + fill: black; + stroke: none; +} + +/* notes */ +aside.note { + border: 1px solid var(--searchbar-border-color); + border-radius: 3px; + margin-top: 1em; +} + +aside.note > * { + margin-left: 1em; + margin-right: 1em; +} + +/* note title */ +aside.note > h1 { + border-bottom: 1px solid var(--searchbar-border-color); + margin: 0; + padding: 0.5em 1em; + font-size: 100%; + font-weight: normal; + background: var(--quote-bg); +} + +/* warning notes */ +aside.note.warning > h1 { + background: var(--warning-note-background-color, #fcf8f2); +} +aside.note.warning > h1::before { + /* TODO(directxman12): fill in these colors in theme. + * If you're good with colors, feel free to play around with this + * in dark mode. */ + content: "!"; + color: var(--warning-note-color, #f0ad4e); + margin-right: 1em; + font-size: 100%; + vertical-align: middle; + font-weight: bold; + padding-left: 0.6em; + padding-right: 0.6em; + border-radius: 50%; + border: 2px solid var(--warning-note-color, #f0ad4e); +} + +/* literate source citations */ +cite.literate-source { + font-size: 75%; + font-family: "IBM Plex Mono","Source Code Pro", Consolas, "Ubuntu Mono", Menlo, "DejaVu Sans Mono", monospace, monospace; +} +cite.literate-source::before { + content: "$ "; + font-weight: bold; + font-style: normal; +} + +cite.literate-source > a::before { + content: "vim "; + font-style: normal; + color: var(--fg); +} + +/* hide the annoying "copy to clipboard" buttons */ +.literate pre > .buttons { + display: none; +} + +/* add a bit of extra padding for readability */ +.literate pre code { + padding-top: 0.75em; + padding-bottom: 0.75em; +} + +.tabset > input[type="radio"] { + position: absolute; + left: -200vw; +} + +.tabset .tab-panel { + display: none; +} + +.tabset > input:first-child:checked ~ .tab-panels > .tab-panel:first-child, +.tabset > input:nth-child(3):checked ~ .tab-panels > .tab-panel:nth-child(2), +.tabset > input:nth-child(5):checked ~ .tab-panels > .tab-panel:nth-child(3), +.tabset > input:nth-child(7):checked ~ .tab-panels > .tab-panel:nth-child(4), +.tabset > input:nth-child(9):checked ~ .tab-panels > .tab-panel:nth-child(5), +.tabset > input:nth-child(11):checked ~ .tab-panels > .tab-panel:nth-child(6), +.tabset > input:nth-child(13):checked ~ .tab-panels > .tab-panel:nth-child(7), +.tabset > input:nth-child(15):checked ~ .tab-panels > .tab-panel:nth-child(8){ + display: block; +} + +.tabset > label { + position: relative; + display: inline-block; + padding: .6em 1em 1em; + border: 1px solid transparent; + border-bottom: 0; + cursor: pointer; + font-size: 16px; + border-top-right-radius: 4px; + border-top-left-radius: 4px; +} + +.tabset > label::after { + content: ""; + position: absolute; + left: 15px; + bottom: 10px; + width: 20px; + height: 4px; + background: #8d8d8d; +} + +.tabset > label:hover, +.tabset > input:focus + label { + color: #06c; +} + +.tabset > label:hover::after, +.tabset > input:focus + label::after, +.tabset > input:checked + label::after { + background: #06c; +} + +.tabset > input:checked + label { + border-color: #ccc; + border-bottom: 1px solid #fff; + margin-bottom: -1px; +} + +.tab-panel { + padding: 1em 1.4em; + border: 1px solid #ccc; + border-bottom-right-radius: 4px; + border-bottom-left-radius: 4px; + position: relative; +} \ No newline at end of file diff --git a/docs/book/theme/favicon.png b/docs/book/theme/favicon.png new file mode 100644 index 0000000000000000000000000000000000000000..9f0139ba8f6573093f25362bb7c279fddd5a74c0 GIT binary patch literal 2522 zcmZ`*c|4oh8vaOYXPDSZjYviBTf_(%maX>4Tnh}(nxGr zC@Gvuw}LOXw8LT4Fe`X~sTazN=|G}TT@zwRM-%Y=!~_}<8wR(rma^pFK!PX|n*ifP zMbcR~jurfGUL3gI3nSsMzf0IOD|n!n56poPLxPzanHZtq)>1Ibm@qQV&(ZlS81$^* z6gHcQLn7njfz!D?CyQVt>w93M4avB>57y35>|PIokOLc69M+*Nz1!^&}-OvxMjRZzj$K8(}8TpBG7$yCB21t#U6=zDs@P z@{{t=AD^zS_aln zkjAi)(H%u&F1xLl=jPt5=Wgx(K)cyE2MrDlYAHKN9=ak)Nr#+Odl(~QaS_?nQvcvo zD~|DF#zMfs!UN_!)3MYso%=PGLVnI@hV}<~|MSJ%sV}uU{rCeYbI;VH zJ5}wSSVr~2W}Nq}f%$+CPXKuFEvM~FRr55Lvr;J02vw@y!Nvxj?Z6`(-CUH9A@c5{w&tI~% z;nAGwhgtV%pF9w95&`nRSG@SJfT5#DTBcPsdn*7w^r;7QG5Z1qq-+1Zp_SS@t#j$#_;ohkWH-k7P9r+DGQVE^x0(k~~NKOEA^{cTc_5HSW< z;`jHRa9q+~?a)%$w2wO&chupQ9Yy}U;FlH6Bkh&zeCHp}5l^6w_u;dXySKB*5o0g& z$|QPP&L(V{zHb%zAu?Uzszj>0nnJRHeu|Fm0d*3*+sr%tN8mV0bwBZ1w>T{Kh=aZSnS+3oI#%L2)`d7J8j)SrBLU-fjkj6|5I}*Nw`>F zsa%DPpHep1Zx(pPQ$E=^%gasK+?hhH#ZGB3-y~CoVQAuX?^-Aa?Q&kEmfSYijmO zK-uRP;-uhdzgfzq!3i5Vbh(f`!1p^CxvtwRHYdI0fe1&7KFaS76pODM_oEmZF1LsC zoOZ2eE0jG&--xQha&sO`9e-2P72Q`uCRYzY*R>yille-}nc}GK!;2jfg&Z#;l^$ki zNsf^0uKVszsnpyNcoySnu3g%r#*b60ovfE+^KYo%-S8f$-I!`|n!qPcnv6QrAfijw z(u-35zNy*xa=3jh^5mtT%i+tV({A_HZTi*_QbDhGMIocPemPF*au}Ln+q%ycM^E|G z)CvSjtnEy^>0-p==h7l;Wfq0a^2O3pG{K|6eJ5org_S!i>;Asg7GKiG@skP5<43SU zeab_@^#*%DLj^KzGZ!;kHMriM6Y73)W!je?(4=&t9^I8@RJ8e6`6gfVthc3FA=3w+$51^M=PG~BF^|7Nx%qxJK`a{U)7+fQUqc={C!b_d9}Q1Ty3xYrHO0mT z8Z>mE=XFEuF_n7;H;QDfZ_g)4 zqI6H!DLkxY2?;YEmnfSnONTVZ2T}?%**NjTvB7h<%E|x2u+IHf>K(QNt+|AbQS%u| z1Mf<0wo@QGjKC)0h%qG40BDpk)(`~_j6WKK!(eeHriW2z912CQI}-dqfG9>7m3-#^ z15}oHFF`;+0{D{hBgDg)F$^*_k_2O)VUl3r3xo&&oWl848HwoQy1ISdPx{?n`vDMy zv=LDnihz3LDng(zN1jPX7z9!84}0>*NN;C<=fO_#Cp_0;cO&4fiUNDp-t-2z1>oj{ KcdW4wN&Yv1he~Sz literal 0 HcmV?d00001 diff --git a/docs/book/theme/highlight.css b/docs/book/theme/highlight.css new file mode 100644 index 000000000..905098262 --- /dev/null +++ b/docs/book/theme/highlight.css @@ -0,0 +1,74 @@ +/* Code highlighting styles based on hjs default GitHub Gist Theme */ + +.hljs { + display: block; + background-color: #f7f7f7; + padding: 0.5em; + overflow-x: auto; + } + + .hljs-comment, + .hljs-meta { + color: #969896; + } + + .hljs-variable, + .hljs-template-variable, + .hljs-strong, + .hljs-emphasis, + .hljs-quote { + color: #df5000; + } + + .hljs-keyword, + .hljs-selector-tag, + .hljs-type { + color: #d73a49; + } + + .hljs-literal, + .hljs-symbol, + .hljs-bullet, + .hljs-attribute { + color: #0086b3; + } + + .hljs-section, + .hljs-name { + color: #63a35c; + } + + .hljs-tag { + color: black; + } + + .hljs-title, + .hljs-attr, + .hljs-selector-id, + .hljs-selector-class, + .hljs-selector-attr, + .hljs-selector-pseudo { + color: #07a; + } + + .hljs-addition { + color: #55a532; + background-color: #eaffea; + } + + .hljs-deletion { + color: #bd2c00; + background-color: #ffecec; + } + + .hljs-link { + text-decoration: underline; + } + + .hljs-number { + color: #905; + } + + .hljs-string { + color: #080; + } \ No newline at end of file