generated from kubernetes/kubernetes-template-project
-
Notifications
You must be signed in to change notification settings - Fork 83
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #435 from furkatgofurov7/operator-book-structure
📖 Inital Netlify book structure version of operator
- Loading branch information
Showing
34 changed files
with
1,032 additions
and
14 deletions.
There are no files selected for viewing
This file was deleted.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1 @@ | ||
| {{#include ../../../CONTRIBUTING.md}} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,3 @@ | ||
| # Code of Conduct | ||
|
|
||
| {{#include ../../../code-of-conduct.md}} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 - | ||
| ``` | ||
|
|
||
|
|
File renamed without changes.
File renamed without changes.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1 @@ | ||
| # Using Helm Charts |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1 @@ | ||
| # Using Manifests from Release Assets |
File renamed without changes.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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) | ||
|
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1 @@ | ||
| # Provider List |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1 @@ | ||
| # Reference |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1 @@ | ||
| # Air-gapped Environment |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1 @@ | ||
| # Basic Cluster API Provider Installation |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1 @@ | ||
| # Cluster API Provider Lifecycle |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1 @@ | ||
| # Deleting a Provider |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1 @@ | ||
| # Deleting providers |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1 @@ | ||
| # Injecting additional manifests |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1 @@ | ||
| # Installing Azure Infrastructure Provider |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1 @@ | ||
| # Installing the CoreProvider |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1 @@ | ||
| # Installing a Provider |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1 @@ | ||
| # Modifying a Provider |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,3 @@ | ||
| # Topics | ||
|
|
||
| This section contains information about enabling and configuring various features of Cluster API Operator. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1 @@ | ||
| # Upgrading a Provider |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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. |
Oops, something went wrong.