From 5bf7a7bf1f65d5949636e2c6bef67b9eb3185f03 Mon Sep 17 00:00:00 2001 From: Matthieu Huin Date: Mon, 5 Feb 2024 11:23:04 +0100 Subject: [PATCH] Documentation: use Material for MkDocs Add a mkdocs.yaml file to generate the documentation with Material for MkDocs. Material for MkDocs provides a lot of improvements -almost- out of the box over the current Jekyll implementation: - Dark/Light mode toggle - Integrated search - Better usage of screen "real estate" - Better navigation: top menu, auto-generated ToC for each page, footer arrows, 'back to top' button, customizable site navigation in mkdocs.yaml, permalinks - Code snippets from outside of the ./doc/ folder - "Copy snippet" button - Annotations: only display details or notices if it is relevant - Admonitions: make notices, warning, danger more noticeable - Mermaid graphs (the jekyll/github pages seems not to work as expected) - Tabbing: present alternatives in a neat, concise way - Social links: matrix, quay, github, go pkg index The documentation can be served in development mode with `make doc-serve`. Modify github actions workflow to publish the documentation with mkdocs. Change-Id: Ia5e678f9133c71bef3066c701ed4f0e06244d33d --- ...ekyll-gh-pages.yml => mkdocs-gh-pages.yml} | 17 +-- Makefile | 11 ++ README.md | 2 +- doc/README.md | 90 +++++++++++++ doc/_config.yml | 13 -- doc/deployment/backing_services.md | 1 - doc/deployment/certificates.md | 10 +- doc/deployment/config_repository.md | 34 +++-- doc/deployment/crds.md | 24 ++-- doc/deployment/delete.md | 2 +- doc/deployment/getting_started.md | 9 +- doc/deployment/index.md | 5 +- doc/deployment/logging.md | 4 +- doc/deployment/monitoring.md | 46 ++++--- doc/deployment/nodepool.md | 36 ++--- doc/deployment/zuul.md | 22 +-- doc/developer/CONTRIBUTING.md | 52 ++++++++ doc/developer/getting_started.md | 83 +++++++----- doc/developer/howtos/index.md | 1 - doc/developer/images.md | 7 +- doc/developer/index.md | 5 +- doc/developer/microshift.md | 3 +- doc/developer/release.md | 9 +- doc/developer/testing.md | 12 +- doc/developer/troubleshooting.md | 1 - doc/index.md | 12 -- doc/operator/getting_started.md | 1 - doc/operator/index.md | 5 +- .../0000-use-markdown-any-decision-records.md | 0 .../adr/0001-operator-config.md | 0 .../adr/0002-zuul-system-config.md | 0 doc/{ => reference}/adr/0003-config-update.md | 0 doc/{ => reference}/adr/0004-zuul-main.md | 0 doc/{ => reference}/adr/0005-ops-tooling.md | 0 doc/{ => reference}/adr/0006-monitoring.md | 0 doc/{ => reference}/adr/0007-edge-cert.md | 0 doc/{ => reference}/adr/0008-config-jobs.md | 0 .../adr/0009-database-agnosticity.md | 0 .../adr/0010-zuul-operator-usage.md | 0 .../adr/0011-backup-and-restore.md | 0 .../adr/0011-nodepool-builder.md | 0 doc/{ => reference}/adr/0012-CLI-overhaul.md | 0 .../adr/0013-more-CLI-features.md | 2 +- doc/{ => reference}/adr/adr-template.md | 2 +- doc/{ => reference}/adr/index.md | 14 +- doc/reference/cli/index.md | 33 +++-- doc/reference/index.md | 7 +- doc/user/index.md | 5 +- doc/user/nodepool_config_repository.md | 52 +++++--- doc/user/zuul_config_repository.md | 33 +++-- flake.lock | 19 ++- flake.nix | 7 +- mkdocs-requirements.txt | 4 + mkdocs.yml | 126 ++++++++++++++++++ sfcli.config => sfcli.yaml | 0 55 files changed, 607 insertions(+), 214 deletions(-) rename .github/workflows/{jekyll-gh-pages.yml => mkdocs-gh-pages.yml} (59%) create mode 100644 doc/README.md delete mode 100644 doc/_config.yml create mode 100644 doc/developer/CONTRIBUTING.md delete mode 100644 doc/index.md rename doc/{ => reference}/adr/0000-use-markdown-any-decision-records.md (100%) rename doc/{ => reference}/adr/0001-operator-config.md (100%) rename doc/{ => reference}/adr/0002-zuul-system-config.md (100%) rename doc/{ => reference}/adr/0003-config-update.md (100%) rename doc/{ => reference}/adr/0004-zuul-main.md (100%) rename doc/{ => reference}/adr/0005-ops-tooling.md (100%) rename doc/{ => reference}/adr/0006-monitoring.md (100%) rename doc/{ => reference}/adr/0007-edge-cert.md (100%) rename doc/{ => reference}/adr/0008-config-jobs.md (100%) rename doc/{ => reference}/adr/0009-database-agnosticity.md (100%) rename doc/{ => reference}/adr/0010-zuul-operator-usage.md (100%) rename doc/{ => reference}/adr/0011-backup-and-restore.md (100%) rename doc/{ => reference}/adr/0011-nodepool-builder.md (100%) rename doc/{ => reference}/adr/0012-CLI-overhaul.md (100%) rename doc/{ => reference}/adr/0013-more-CLI-features.md (99%) rename doc/{ => reference}/adr/adr-template.md (98%) rename doc/{ => reference}/adr/index.md (83%) create mode 100644 mkdocs-requirements.txt create mode 100644 mkdocs.yml rename sfcli.config => sfcli.yaml (100%) diff --git a/.github/workflows/jekyll-gh-pages.yml b/.github/workflows/mkdocs-gh-pages.yml similarity index 59% rename from .github/workflows/jekyll-gh-pages.yml rename to .github/workflows/mkdocs-gh-pages.yml index 1928e842..faae0280 100644 --- a/.github/workflows/jekyll-gh-pages.yml +++ b/.github/workflows/mkdocs-gh-pages.yml @@ -1,4 +1,4 @@ -name: Build static HTML documentation with Jekyll and GitHub pages +name: Build static HTML documentation with Material for MkDocs and GitHub pages on: push: @@ -14,7 +14,7 @@ permissions: concurrency: group: "pages" - cancel-in-progress: false + cancel-in-progress: true jobs: build: @@ -22,17 +22,14 @@ jobs: steps: - name: Checkout uses: actions/checkout@v3 - - name: Move README and CONTRIBUTING into the documentation - run: | - cp "${GITHUB_WORKSPACE}/README.md" "${GITHUB_WORKSPACE}/doc/README.md" - cp "${GITHUB_WORKSPACE}/CONTRIBUTING.md" "${GITHUB_WORKSPACE}/doc/developer/CONTRIBUTING.md" - name: Setup Pages uses: actions/configure-pages@v3 - - name: Build with Jekyll - uses: actions/jekyll-build-pages@v1 + - name: Setup python and install material for mkdocs + uses: actions/setup-python@v4 with: - source: ./doc/ - destination: ./_site + python-version: 3.12 + - run: pip install -r mkdocs-requirements.txt + - run: mkdocs build --site-dir ./_site - name: Upload artifact uses: actions/upload-pages-artifact@v2 diff --git a/Makefile b/Makefile index 13505ebb..c59c1fe4 100644 --- a/Makefile +++ b/Makefile @@ -73,6 +73,10 @@ vet: ## Run go vet against code. sc: staticcheck ## Run staticcheck checks https://staticcheck.dev/docs/ $(LOCALBIN)/staticcheck ./... +.PHONY: doc-serve +doc-serve: mkdocs + $(LOCALBIN)/mkdocs/bin/mkdocs serve + .PHONY: test test: manifests generate fmt vet envtest ## Run tests. KUBEBUILDER_ASSETS="$(shell $(ENVTEST) use $(ENVTEST_K8S_VERSION) -p path)" go test ./... -coverprofile cover.out @@ -161,12 +165,19 @@ KUSTOMIZE ?= $(LOCALBIN)/kustomize CONTROLLER_GEN ?= $(LOCALBIN)/controller-gen ENVTEST ?= $(LOCALBIN)/setup-envtest OPERATOR_SDK ?= $(LOCALBIN)/operator-sdk +MKDOCS ?= $(LOCALBIN)/mkdocs/bin/mkdocs ## Tool Versions KUSTOMIZE_VERSION ?= v5.3.0 CONTROLLER_TOOLS_VERSION ?= v0.13.0 OPERATOR_SDK_VERSION ?= 1.32.0 STATICCHECK_VERSION ?= 2023.1.6 +MKDOCS_VERSION ?= 1.5.3 + +.PHONY: mkdocs +mkdocs: $(MKDOCS) ## Install material for mkdocs locally if necessary +$(MKDOCS): $(LOCALBIN) + ( test -f $(LOCALBIN)/mkdocs/bin/mkdocs && [[ "$(shell $(LOCALBIN)/mkdocs/bin/mkdocs -V)" =~ "$(MKDOCS_VERSION)" ]] ) || ( python -m venv $(LOCALBIN)/mkdocs && $(LOCALBIN)/mkdocs/bin/pip install --upgrade -r mkdocs-requirements.txt ) KUSTOMIZE_INSTALL_SCRIPT ?= "https://raw.githubusercontent.com/kubernetes-sigs/kustomize/kustomize/${KUSTOMIZE_VERSION}/hack/install_kustomize.sh" .PHONY: kustomize diff --git a/README.md b/README.md index d11f6d38..d7cf151c 100644 --- a/README.md +++ b/README.md @@ -78,7 +78,7 @@ The current project status is: **Alpha - NOT PRODUCTION READY** Should you have any questions or feedback concerning the SF-Operator, you can: * [Join our Matrix channel](https://matrix.to/#/#softwarefactory-project:matrix.org) -* Send an email to [softwarefactory-dev@redhat.com](softwarefactory-dev@redhat.com) +* Send an email to [softwarefactory-dev@redhat.com](mailto:softwarefactory-dev@redhat.com) * [File an issue](https://github.com/softwarefactory-project/sf-operator/issues/new) for bugs and feature suggestions ## Contributing diff --git a/doc/README.md b/doc/README.md new file mode 100644 index 00000000..d7cf151c --- /dev/null +++ b/doc/README.md @@ -0,0 +1,90 @@ +# SF-Operator: a Zuul-based CI infrastructure for OpenShift + + + +Matrix Channel + +Testing only; use in production at your own risks + +## About + +SF-Operator is an Operator that simplifies the deployment and operation of Software Factory instances on the OpenShift Container Platform. An instance of Software Factory is composed of [Zuul](https://zuul-ci.org) and its dependencies ([NodePool](https://zuul-ci.org/docs/nodepool/latest/), Zookeeper, MariaDB, Log Server). + +It is the natural evolution of the [Software Factory project](https://softwarefactory-project.io): the 3.8.x release of Software Factory saw the containerization of every major service, but was still delivered as RPM packages, in the form of a custom CentOS 7 distribution. +SF-Operator builds upon this containerization effort to move from a distro-centric approach to a cloud-native deployment. +This is also an opportunity to focus on the leanest service suite needed to provide a working gated CI infrastructure; hence a scope reduced to Zuul and its dependencies only. + +SF-Operator is built mostly in Go upon the [Operator Framework](https://operatorframework.io), with the aim of reaching the highest capability level that can be achieved, in order to bring a modern, scalable gated CI alternative to OpenShift users, with the least friction from operation as possible. + +Furthermore, SF-Operator takes advantage of some of the specificities of OpenShift as a container orchestration platform: + +* Improved routes API +* Integration with OLM for streamlined operator and operands' lifecycle management +* If [enabled in OpenShift](https://docs.openshift.com/container-platform/4.13/monitoring/enabling-monitoring-for-user-defined-projects.html#enabling-monitoring-for-user-defined-projects), SF-Operator comes with default monitoring and alerting configurations that can be used out of the box. The default alerting rules are honed from years of maintaining and running several large Zuul deployments at scale for [Fedora](https://fedora.softwarefactory-project.io/zuul/status), [Ansible](https://ansible.softwarefactory-project.io/zuul/status) and [RDO](https://review.rdoproject.org/zuul/status). +* If [enabled](https://docs.openshift.com/container-platform/4.13/logging/cluster-logging.html), OpenShift provides application logs aggregation with its logging subsystem out of the box. + +Finally, we also provide a Command Line Interface (CLI) called sfconfig to simplify common tasks related to the operator, management of the operands, development and testing. + +## Status + +The current project status is: **Alpha - NOT PRODUCTION READY** + +## Capability Levels + +* Level 1 - Basic Install - **8/10** + - Zuul Scheduler: ✅ + - Zuul Executor: ✅ + - Zuul Web: ✅ + - Zuul Merger: ❌ + - Nodepool Launcher: ✅ + - Nodepool Builder: ✅ + - Zookeeper: ✅ + - MariaDB: ✅ + - Log Server: ✅ + - Internal Config Repository, bootstrapped pipelines and default jobs: ✅ +* Level 2 - Seamless upgrades - **2/2** + - Operator: ✅ + - Operands: ✅ +* Level 3 - Full Lifecycle - **1/5** + - SF 3.8.x migration ❌ + - Backup: ❌ + - Restore: ❌ + - Rolling deployments: ❌ + - Reconfiguration: ✅ +* Level 4 - Deep Insights - **1/3** + - Operator metrics: ❌ + - Operand metrics: ✅ + - Alerts: ❌ (WIP) +* Level 5 - Auto pilot - **0/3** + - Auto-scaling : ❌ + - Auto-healing: ❌ + - Auto-tuning: ❌ + +## Getting Started + +* [Installing the Operator ](https://softwarefactory-project.github.io/sf-operator/operator/getting_started.html) +* [Deploying Zuul and dependencies with SF-Operator](https://softwarefactory-project.github.io/sf-operator/deployment/getting_started.html) + +## Documentation + +* [Operator documentation](https://softwarefactory-project.github.io/sf-operator/operator/): for OpenShift cluster administrators, this documentation covers installing SF-Operator and managing the operator's lifecycle. +* [Deployment documentation](https://softwarefactory-project.github.io/sf-operator/deployment/): this documentation covers the essentials for people or teams who intend to deploy and manage Zuul and its dependencies through the SF-Operator. +* [Developer documentation](https://softwarefactory-project.github.io/sf-operator/developer/): this documentation describes how to set up a development and testing environment to develop the SF-Operator. +* [End User documentation](https://softwarefactory-project.github.io/sf-operator/user/): for users of a Software Factory instance. This documentation mostly describes the `Software Factory's config repository` usage (configuration-as-code). +* [CLI refererence](https://softwarefactory-project.github.io/sf-operator/reference/cli/) + +## Getting Help + +Should you have any questions or feedback concerning the SF-Operator, you can: + +* [Join our Matrix channel](https://matrix.to/#/#softwarefactory-project:matrix.org) +* Send an email to [softwarefactory-dev@redhat.com](mailto:softwarefactory-dev@redhat.com) +* [File an issue](https://github.com/softwarefactory-project/sf-operator/issues/new) for bugs and feature suggestions + +## Contributing + +Refer to [CONTRIBUTING.md](https://github.com/softwarefactory-project/sf-operator/blob/master/CONTRIBUTING.md). + +## Licence + +Sf-operator is distributed under the [Apache License](https://www.apache.org/licenses/LICENSE-2.0.txt). diff --git a/doc/_config.yml b/doc/_config.yml deleted file mode 100644 index 130e582b..00000000 --- a/doc/_config.yml +++ /dev/null @@ -1,13 +0,0 @@ -title: SF-Operator Documentation -description: - -remote_theme: pages-themes/cayman@v0.2.0 -plugins: - - jekyll-remote-theme -source: doc/ -exclude: - - adr/adr-template.md -# Github excludes these files by default -include: - - developer/CONTRIBUTING.md - - README.md \ No newline at end of file diff --git a/doc/deployment/backing_services.md b/doc/deployment/backing_services.md index 92540936..7f7312cb 100644 --- a/doc/deployment/backing_services.md +++ b/doc/deployment/backing_services.md @@ -2,7 +2,6 @@ Here you will find information about the backing services used by Zuul and Nodepool. -## Table of Contents 1. [Philosophy](#philosophy) 1. [MariaDB](#mariadb) diff --git a/doc/deployment/certificates.md b/doc/deployment/certificates.md index 97839598..77ed37a2 100644 --- a/doc/deployment/certificates.md +++ b/doc/deployment/certificates.md @@ -1,6 +1,5 @@ # Set up TLS on service routes -## Table of Contents 1. [Using a trusted Certificate Authority](#using-a-trusted-certificate-authority) 1. [Using Let's Encrypt](#using-lets-encrypt) @@ -21,11 +20,13 @@ The operator watches a `Secret` named `sf-ssl-cert` in the `SoftwareFactory` Cus When this `Secret`'s data hold a Certificate, Key and CA Certificate (following a specific scheme) then the sf-operator is able to reconfigure all managed `Route`'s TLS to use the TLS material stored in the secret. -> Make sure that the certificate `CN` matches the `fqdn` setting of the `SoftwareFactory` Custom Resource. +!!! note + Make sure that the certificate `CN` matches the `fqdn` setting of the `SoftwareFactory` Custom Resource. The [sf-operator](./../reference/cli/index.md) CLI can be used to configure these secrets. -> The [`SF configure TLS`](./../reference/cli/index.md#configure-tls) subcommand will validate the SSL certificate/key before updating the `Secret`. +!!! note + The [`SF configure TLS`](./../reference/cli/index.md#configure-tls) subcommand will validate the SSL certificate/key before updating the `Secret`. ```sh sf-operator SF configure TLS --CA /tmp/ssl/localCA.pem \ @@ -56,7 +57,8 @@ Once `Ready`, all managed `Route` will present the new certificate. The SF Operator offers an option to request a certificate from `Let's Encrypt` using the `ACME http01` challenge. The deployment `FQDN` must be publicly resolvable. -> This overrides the custom X509 certificates that might have been set following the [steps above](#using-a-trusted-certificate-authority). +!!! note + This overrides the custom X509 certificates that might have been set following the [steps above](#using-a-trusted-certificate-authority). 1. test your deployment with Let's Encrypt's staging server: diff --git a/doc/deployment/config_repository.md b/doc/deployment/config_repository.md index 3c0ed9d3..69a3db90 100644 --- a/doc/deployment/config_repository.md +++ b/doc/deployment/config_repository.md @@ -1,6 +1,5 @@ # Config Repository -## Table of Contents 1. [Concept](#concept) 1. [Repository content](#repository-content) @@ -15,7 +14,8 @@ ## Concept -> If you are already familiar with the config repository in Software Factory, you can skip this section and go straight to [setting up the repository](#setting-up-the-repository). +!!! note + If you are already familiar with the config repository in Software Factory, you can skip this section and go straight to [setting up the repository](#setting-up-the-repository). In Software Factory, Zuul and Nodepool's configurations are stored in a special git repository called the **config repository**. Zuul is also pre-configured to run the following CI pipelines and jobs against changes on this repository, in a reserved tenant (`internal`): @@ -44,7 +44,8 @@ Any other file or folder will be ignored. As of the current version of the SF-Operator, Gerrit and GitLab are the only supported hosting options for the config repository. -> You can follow the [developer's documentation to deploy a test Gerrit instance](../developer/howtos/index.md#gerrit) if needed. +!!! note + You can follow the [developer's documentation to deploy a test Gerrit instance](../developer/howtos/index.md#gerrit) if needed. ### Hosting on Gerrit @@ -76,10 +77,11 @@ ssh -p29418 gerrit set-members --add zuul@example.com "Service Use ##### Repository ACLs and Labels -> Access controls and labels management with Gerrit is out of the scope of this documentation. Please refer to -Gerrit's documentation for further details, for example -[here](https://gerrit-review.googlesource.com/Documentation/access-control.html) for ACLs -or [here](https://gerrit-review.googlesource.com/Documentation/config-labels.html) for labels. +!!! note + Access controls and labels management with Gerrit is out of the scope of this documentation. Please refer to + Gerrit's documentation for further details, for example + [here](https://gerrit-review.googlesource.com/Documentation/access-control.html) for ACLs + or [here](https://gerrit-review.googlesource.com/Documentation/config-labels.html) for labels. The repository must be set with specific ACLs to allow Zuul to interact with it: @@ -121,24 +123,27 @@ For further information check the [Gerrit section](https://zuul-ci.org/docs/zuul #### Configuring the Zuul connection -In order for Zuul to start listening to Gerrit events, add a `gerritconn` property in your deployed **SoftwareFactory**'s Spec: - -> The `username` is the name of the [bot account that was set up in the previous section](#gerrit-bot-account). +In order for Zuul to start listening to Gerrit events, add a `gerritconn` property in your deployed **SoftwareFactory**'s Spec. Edit the spec with: ```sh kubectl edit sf my-sf +``` + +```yaml [...] spec: zuul: gerritconns: - name: gerrit - username: zuul + username: zuul # (1) hostname: puburl: "" [...] ``` -You can check the [CRD's OpenAPI schema](config/crd/bases/sf.softwarefactory-project.io_softwarefactories.yaml) for specification details. +1. The `username` is the name of the [bot account that was set up in the previous section](#gerrit-bot-account). + +You can check the [CRD's OpenAPI schema](./crds.md) for specification details. At that step you can continue the setting by [configuring the location of the config repository](#set-the-config-repository-location). @@ -156,8 +161,9 @@ is sufficient. Please refer to the [upstream's Zuul documentation for more information about the GitLab's driver and how to define an API Token and WebHook token](https://zuul-ci.org/docs/zuul/latest/drivers/gitlab.html#gitlab). -> Note that the WebHook URL to configure on the project or on the project's group setting must -be `https:///zuul/api/connection//payload` +!!! note + The WebHook URL to configure on the project or on the project's group setting must + be `https:///zuul/api/connection//payload` The `gate` pipeline defined for the `config` repository workflow relies in the `gateit` label for the pipeline trigger rule. Thus, a GitLab label named `gateit` must be defined in the `Settings` the `config` repository. diff --git a/doc/deployment/crds.md b/doc/deployment/crds.md index 133e89b6..7df09059 100644 --- a/doc/deployment/crds.md +++ b/doc/deployment/crds.md @@ -2,17 +2,25 @@ This document gives details about the Custom Resource Definitions (CRDs) that the SF-Operator installs on a cluster. -## Table of Contents +The specs are constantly evolving during alpha development, and should be considered +unstable but the ultimate source of truth for documentation about their properties. -1. [CRDs](#crds) -## CRDs +1. [SoftwareFactory](#crds) +1. [LogServer]() -The Custom Resources installed by the SF-Operator are described in the following OpenAPI specs: +## SoftwareFactory -* [SoftwareFactory](https://github.com/softwarefactory-project/sf-operator/blob/master/config/crd/bases/sf.softwarefactory-project.io_softwarefactories.yaml) -* [LogServer](https://github.com/softwarefactory-project/sf-operator/blob/master/config/crd/bases/sf.softwarefactory-project.io_logservers.yaml) +This custom resource describes a Software Factory instance. -The spec is constantly evolving during alpha development, and should be considered -unstable but the ultimate source of truth for documentation about its properties. +```yaml +--8<-- "config/crd/bases/sf.softwarefactory-project.io_softwarefactories.yaml" +``` +## LogServer + +This custom resource describes a standalone Log Server (SSH/rsync endpoint + HTTP server). + +```yaml +--8<-- "config/crd/bases/sf.softwarefactory-project.io_logservers.yaml" +``` \ No newline at end of file diff --git a/doc/deployment/delete.md b/doc/deployment/delete.md index 4134b3b5..a0bbcc17 100644 --- a/doc/deployment/delete.md +++ b/doc/deployment/delete.md @@ -2,4 +2,4 @@ The [sf-operator](./../reference/cli/index.md) cli command provides several levels of deletion. -See the subcommand [`SF wipe`'s documentation](./../reference/cli/index.md#wipe) for more details. \ No newline at end of file +See the subcommand [`SF wipe`'s documentation](./../reference/cli/index.md#wipe) for more details. diff --git a/doc/deployment/getting_started.md b/doc/deployment/getting_started.md index 3abe85e3..d936ce79 100644 --- a/doc/deployment/getting_started.md +++ b/doc/deployment/getting_started.md @@ -1,6 +1,5 @@ # Getting Started with a deployment -## Table of Contents 1. [Prerequisites](#prerequisites) 1. [Installation](#installation) @@ -19,12 +18,14 @@ In order to deploy a Software Factory with the SF-Operator on an OpenShift clust We recommend using a dedicated namespace to deploy your Software Factory. Furthermore, only one instance of a Software Factory must be deployed per namespace due to name and label collisions. -> Currently, the namespace must allow `privileged` containers to run. Indeed the `zuul-executor` container requires -extra privileges because of [bubblewrap](https://github.com/containers/bubblewrap). +!!! note + Currently, the namespace must allow `privileged` containers to run. Indeed the `zuul-executor` container requires + extra privileges because of [bubblewrap](https://github.com/containers/bubblewrap). In this example we will create a dedicated namespace called **sf**. Then the next three commands below configure privileged access on this namespace; modify the commands as needed if using a different namespace. -> Note that these commands might need to be run by a user with enough privileges to create and modify namespaces and policies. +!!! note + Note that these commands might need to be run by a user with enough privileges to create and modify namespaces and policies. ```sh kubectl create namespace sf diff --git a/doc/deployment/index.md b/doc/deployment/index.md index 0df83b96..7110548a 100644 --- a/doc/deployment/index.md +++ b/doc/deployment/index.md @@ -1,9 +1,12 @@ +--- +title: About +--- + # Deployment documentation Welcome to the deployment documentation. You can find here what you need to know when it comes to deploying and managing a Software Factory Custom Resource through SF-Operator. -## Table of Contents 1. [Getting started](./getting_started.md) 1. [Setting up the config repository](./config_repository.md) diff --git a/doc/deployment/logging.md b/doc/deployment/logging.md index 3675b30a..8d9c95a2 100644 --- a/doc/deployment/logging.md +++ b/doc/deployment/logging.md @@ -2,7 +2,6 @@ This document describes different ways to handle log collection and aggregation for the services deployed with the SF-Operator. -## Table of Contents 1. [Using kubectl](#using-kubectl) 1. [Native Cluster Logging](#native-cluster-logging) @@ -81,7 +80,8 @@ Loki instance and configure log forwarding to this instance: * [Fluent Bit manifest](https://raw.githubusercontent.com/softwarefactory-project/sf-operator/master/tools/loki/test-fluentbit.yaml) * (Optional) [Grafana deployment with preconfigured monitoring and logging datasources](https://raw.githubusercontent.com/softwarefactory-project/sf-operator/master/tools/loki/test-grafana.yaml) -> These manifests are intended for testing purposes only and shouldn't be used in production. +!!! danger + These manifests are intended for testing purposes only and shouldn't be used in production. 1. Download the files listed above. diff --git a/doc/deployment/monitoring.md b/doc/deployment/monitoring.md index 624de2cf..a10d31f2 100644 --- a/doc/deployment/monitoring.md +++ b/doc/deployment/monitoring.md @@ -2,7 +2,6 @@ Here you will find information about what monitoring is available on services deployed with SF-Operator. -## Table of Contents 1. [Concepts](#concepts) 1. [Accessing the metrics](#accessing-the-metrics) @@ -12,19 +11,31 @@ Here you will find information about what monitoring is available on services de ## Concepts SF-Operator use the [prometheus-operator](https://prometheus-operator.dev/) to expose and collect service metrics. -SF-Operator will automatically create [PodMonitors](https://github.com/prometheus-operator/prometheus-operator/blob/main/Documentation/api.md#podmonitor) for the following services: +SF-Operator will automatically create a [PodMonitor](https://github.com/prometheus-operator/prometheus-operator/blob/main/Documentation/api.md#podmonitor) for the following services: +* Git Server * Log Server +* MariaDB * [Nodepool](./nodepool.md) +* ZooKeeper * [Zuul](./zuul.md) +Below is a table of available metrics (1) per service. +{ .annotate } + +1. Metrics exposed by [Node Exporter](https://prometheus.io/docs/guides/node-exporter/) can be used to monitor disk usage. + | Service | Statsd metrics | Prometheus metrics | |---------|--------|-------| -| Log Server | ❌ | ✅ | +| Git Server | ❌ | ✅ (node exporter only)| +| Log Server | ❌ | ✅ (node exporter only)| +| MariaDB | ❌ | ✅ (node exporter only)| | Nodepool | ✅ | ✅ | +| ZooKeeper | ❌ | ✅ (node exporter only)| | Zuul | ✅ | ✅ | + -The `PodMonitors` are set with the label key `sf-monitoring` (and a value equal to the monitored service name); that key can be used for filtering metrics. +The `PodMonitor` is set with the label key `sf-monitoring` (and a value equal to the monitored service name); that key can be used for filtering metrics. You can list the PodMonitors this way: @@ -32,8 +43,6 @@ You can list the PodMonitors this way: kubectl get podmonitors ``` -The `Log server` service runs the [Node Exporter](https://prometheus.io/docs/guides/node-exporter/) process as a sidecar container as well, in order to expose disk space-related metrics. - For services that expose statsd metrics, a sidecar container running [Statsd Exporter](https://github.com/prometheus/statsd_exporter) is added to the service pod, so that these metrics can be consumed by a Prometheus instance. @@ -43,12 +52,9 @@ If [enabled in your cluster](https://docs.openshift.com/container-platform/4.13/ be collected by the cluster-wide Prometheus instance. Check with your cluster admin about getting access to your metrics. If this feature isn't enabled in your cluster, you will need to deploy your own Prometheus instance to collect the metrics on your own. -To do so, you can either: +To do so, follow the [prometheus-operator's documentation](https://github.com/prometheus-operator/prometheus-operator/blob/main/Documentation/user-guides/getting-started.md#deploying-prometheus). -* Follow the [CLI documentation](./../cli/index.md#prometheus) to deploy a standalone Prometheus instance -* Follow the [prometheus-operator's documentation](https://github.com/prometheus-operator/prometheus-operator/blob/main/Documentation/user-guides/getting-started.md#deploying-prometheus) to deploy it on your own - -In the latter case, you will need to set the proper `PodMonitorSelector` in the Prometheus instance's manifest: +You will then need to set the proper `PodMonitorSelector` in the Prometheus instance's manifest: ```yaml # assuming Prometheus is deployed in the same namespace as SF @@ -63,8 +69,12 @@ In the latter case, you will need to set the proper `PodMonitorSelector` in the ### Statsd Exporter mappings -Statsd Exporter sidecars are preconfigured to map every statsd metric issued by Zuul and Nodepool into prometheus-compatible metrics. -You can find the mappings definitions [here (Nodepool)](./../../controllers/static/nodepool/statsd_mapping.yaml) and [here (Zuul)](./../../controllers/static/zuul/statsd_mapping.yaml). +Statsd Exporter sidecars are preconfigured to map every statsd metric issued by Zuul (1) and Nodepool (2) into prometheus-compatible metrics. +{ .annotate } + +1. Zuul's [statsd_mapping.yaml](https://raw.githubusercontent.com/softwarefactory-project/sf-operator/master/controllers/static/zuul/statsd_mapping.yaml) +2. Nodepool's [statsd_mapping.yaml](https://raw.githubusercontent.com/softwarefactory-project/sf-operator/master/controllers/static/nodepool/statsd_mapping.yaml) + ### Forwarding @@ -74,11 +84,11 @@ It is possible to use the `relayAddress` property in a SoftwareFactory CRD to de SF-Operator defines some metrics-related alert rules for the deployed services. -> The alert rules are defined for Prometheus. Handling these alerts (typically sending out notifications) requires another service called [AlertManager](https://github.com/prometheus-operator/prometheus-operator/blob/main/Documentation/user-guides/alerting.md). How to manage AlertManager is out of scope for this documentation. -You may need to [configure](https://docs.openshift.com/container-platform/4.13/monitoring/managing-alerts.html#sending-notifications-to-external-systems_managing-alerts) or -[install](https://github.com/prometheus-operator/prometheus-operator/blob/main/Documentation/user-guides/alerting.md) an -AlertManager instance on your cluster, -or configure Prometheus to forward alerts to an external AlertManager instance. +!!! note + The alert rules are defined for Prometheus. Handling these alerts (typically sending out notifications) requires another service called [AlertManager](https://github.com/prometheus-operator/prometheus-operator/blob/main/Documentation/user-guides/alerting.md). How to manage AlertManager is out of scope for this documentation. + You may need to [configure](https://docs.openshift.com/container-platform/4.13/monitoring/managing-alerts.html#sending-notifications-to-external-systems_managing-alerts) or + [install](https://github.com/prometheus-operator/prometheus-operator/blob/main/Documentation/user-guides/alerting.md) an + AlertManager instance on your cluster, or configure Prometheus to forward alerts to an external AlertManager instance. The following alerting rules are created automatically at deployment time: diff --git a/doc/deployment/nodepool.md b/doc/deployment/nodepool.md index 13bd0269..5aae5b5b 100644 --- a/doc/deployment/nodepool.md +++ b/doc/deployment/nodepool.md @@ -1,10 +1,9 @@ - # Nodepool +# Nodepool Here you will find information about managing the Nodepool service when deployed with the SF Operator. It does not replace [Nodepool's documentation](https://zuul-ci.org/docs/nodepool/latest/), but addresses specificities and idiosyncrasies induced by deploying Nodepool with the SF Operator. -## Table of Contents 1. [Architecture](#architecture) 1. [Services configuration](#services-configuration) @@ -26,13 +25,15 @@ Nodepool is deployed by SF-Operator as micro-services: `nodepool-builder` requires access to at least one `image-builder` machine that is to be deployed out-of-band. Due to security limitations, it is impossible (or at least very hard) to build Nodepool images on a pod, which is why this process must be delegated remotely to an `image-builder` machine. -> The only requirement for the `image-builder` machine is that the `nodepool-builder` is able to run Ansible tasks via SSH. Please refer to sections [Get the builder's SSH public key](#get-the-builders-ssh-public-key) and [Configuring Nodepool builder](../user/nodepool_config_repository#configuring-nodepool-builder). +!!! note + The only requirement for the `image-builder` machine is that the `nodepool-builder` is able to run Ansible tasks via SSH. Please refer to sections [Get the builder's SSH public key](#get-the-builders-ssh-public-key) and [Configuring Nodepool builder](../user/nodepool_config_repository.md#configuring-nodepool-builder). -> There is no assumption about the processes and toolings used to build images on the `image-builder`, except that the workflow must be driven by an Ansible playbook from the `nodepool-builder`. +!!! note + There is no assumption about the processes and toolings used to build images on the `image-builder`, except that the workflow must be driven by an Ansible playbook from the `nodepool-builder`. ## Services configuration -Configuring the Nodepool micro-services is done through the SoftwareFactory deployment's manifest. Many configuration parameters are exposed by The [SoftwareFactory Custom Resource spec](./../../config/crd/bases/sf.softwarefactory-project.io_softwarefactories.yaml). +Configuring the Nodepool micro-services is done through the SoftwareFactory deployment's manifest. Many configuration parameters are exposed by The [SoftwareFactory Custom Resource spec](../deployment/crds.md#softwarefactory). The spec is constantly evolving during alpha development, and should be considered unstable but the ultimate source of truth for documentation about its properties. @@ -42,7 +43,7 @@ unstable but the ultimate source of truth for documentation about its properties Currently the SF Operator supports OpenStack (`clouds.yaml`) and Kubernetes (`kube.config`) configuration files. These files are used by Nodepool to manage resources on its providers. They are managed by the SF Operator in a secret called `nodepool-providers-secrets`. -To push your configuration file(s) to Nodepool, run sf-operator's [`nodepool configure providers-secrets` subcommand](./../reference/cli/index.md#configure-providers-secrets): +To push your configuration file(s) to Nodepool, run sf-operator's [`nodepool configure providers-secrets` subcommand](../reference/cli/index.md#configure-providers-secrets): ```sh sf-operator nodepool configure providers-secrets --kube /path/to/kube.config --clouds /path/to/clouds.yaml @@ -56,24 +57,29 @@ kubectl get sf -n sf -w When your deployment is ready, the provider secrets have been updated in Nodepool. -> You can also fetch the currently used configurations with the [`nodepool get providers-secrets` subcommand](./../reference/cli/index.md#get-providers-secrets). +!!! warning + You can also fetch the currently used configurations with the [`nodepool get providers-secrets` subcommand](./../reference/cli/index.md#get-providers-secrets), + which will copy the configuration files from Nodepool into the files defined in the CLI's configuration. **Be careful not to erase + important data!** ## Get the builder's SSH public key The Nodepool builder component should be used with at least one `image-builder` companion machine. It must have the capablility to connect via SSH to the builder machine. -Here is the command to fetch the builder SSH public key: +There are two ways to fetch the builder SSH public key: with kubectl, or with the [sf-operator CLI](../reference/cli/index.md). -```sh -kubectl get secret nodepool-builder-ssh-key -n sf -o jsonpath={.data.pub} | base64 -d -``` +=== "sf-operator" -or + ```sh + sf-operator --namespace sf nodepool get builder-ssh-key + ``` -```sh -sf-operator --namespace sf nodepool get builder-ssh-key -``` +=== "kubectl" + + ```sh + kubectl get secret nodepool-builder-ssh-key -n sf -o jsonpath={.data.pub} | base64 -d + ``` ## Accept an image-builder's SSH Host key diff --git a/doc/deployment/zuul.md b/doc/deployment/zuul.md index 69be8d24..3d4ce60b 100644 --- a/doc/deployment/zuul.md +++ b/doc/deployment/zuul.md @@ -1,10 +1,9 @@ -# Zuul +.# Zuul Here you will find information about managing the Zuul service when deployed with the SF Operator. It does not replace [Zuul's documentation](https://zuul-ci.org/docs/zuul/latest/), but addresses specificities and idiosyncrasies induced by deploying Zuul with the SF Operator. -## Table of Contents 1. [Architecture](#architecture) 1. [Services configuration](#services-configuration) @@ -26,7 +25,7 @@ Zuul is deployed by SF-Operator as micro-services: ## Services configuration -Configuring the Zuul micro-services is done through the SoftwareFactory deployment's manifest. Many configuration parameters are exposed by The [SoftwareFactory Custom Resource spec](./../../config/crd/bases/sf.softwarefactory-project.io_softwarefactories.yaml). +Configuring the Zuul micro-services is done through the SoftwareFactory deployment's manifest. Many configuration parameters are exposed by The [SoftwareFactory Custom Resource spec](../deployment/crds.md#softwarefactory). The spec is constantly evolving during alpha development, and should be considered unstable but the ultimate source of truth for documentation about its properties. @@ -45,12 +44,19 @@ a user to perform administrative tasks such as managing autoholds, promoting cha There are two ways to generate such a token: -* Run the `zuul-admin` CLI on a scheduler pod to [generate a token](#zuul-admin) -* Run `sf-operator` to streamline the token's generation: +=== "sf-operator" - ```bash - sf-operator zuul create auth-token [FLAGS] - ``` + ```bash + sf-operator zuul create auth-token [FLAGS] + ``` + + Refer to [the command's documentation](../reference/cli/index.md#create-auth-token) for further details. + +=== "kubectl exec" + + ```sh + kubectl exec -n sf --stdin --tty zuul-scheduler-0 -- zuul-admin create-auth-token [...] + ``` ## Zuul-Client diff --git a/doc/developer/CONTRIBUTING.md b/doc/developer/CONTRIBUTING.md new file mode 100644 index 00000000..75857067 --- /dev/null +++ b/doc/developer/CONTRIBUTING.md @@ -0,0 +1,52 @@ +# Contributing + +We welcome all contributions to the project! + +General guidelines about contributing to the SF-Operator can be found in this document. +For further details about the code base, testing and hacking the project, please see +the [Developer documentation](https://softwarefactory-project.github.io/sf-operator/developer/). + +## Project repositories + +The main repository of the project is hosted at [softwarefactory-project.io](https://softwarefactory-project.io/r/software-factory/sf-operator). + +The custom container images used by the SF-Operator are defined in the [container-pipeline project](https://softwarefactory-project.io/r/containers) and +published on [quay.io](https://quay.io/organization/software-factory). + +Use the [git-review workflow](https://softwarefactory-project.io/docs/user/contribute.html#create-a-new-code-review) to interact with these projects. + +Repositories with the same name on GitHub are mirrors from **softwarefactory-project.io**, no pull request will be accepted there. + +The MicroShift deployment Ansible role is hosted on [GitHub](https://github.com/openstack-k8s-operators/ansible-microshift-role). Pull Requests are welcome there. + +## Architectural Decision Records (ADRs) + +Any large contribution aiming to modify or implement a functionality must be first validated by the community with +an *[Architectural Decision Record](https://adr.github.io/) (ADR)*. + +## Review Checklist + +Before submitting a change or a patch chain for review, please consider the following checklist: + +1. Are the commit messages clear and explanatory? +1. Do the changes need to be documented in the changelog? +1. Do the changes cover any required modification of the existing documentation? (see [guidelines](#documentation-guidelines) below) +1. Are the changes tested? We do not require unit testing but do expect functional testing coverage. + +## Documentation guidelines + +The documentation is written in Markdown, as implemented by GitHub Pages. Please refer to +[this documentation](https://www.markdownguide.org/tools/github-pages/) to check what elements are supported. + +Any change that implements a new feature or significantly changes an existing one must be reflected +in the documentation, in the impacted section(s). + +### API Documentation + +The API documentation is auto-generated with [crd-ref-docs](https://github.com/elastic/crd-ref-docs). + +Running `make` or `make build` or `make build-api-doc` will update the API documentation if needed. + +### CLI Documentation + +For now the CLI documentation must be updated by hand. \ No newline at end of file diff --git a/doc/developer/getting_started.md b/doc/developer/getting_started.md index 3fb412dc..33ddfc54 100644 --- a/doc/developer/getting_started.md +++ b/doc/developer/getting_started.md @@ -2,7 +2,6 @@ This section covers the basics to get started with the development on the SF-Operator's code base. -## Table of Contents 1. [Requirements](#requirements) 1. [Run the operator](#run-the-operator) @@ -49,12 +48,24 @@ kubectl create namespace sf kubectl config set-context microshift --namespace=sf ``` -Edit the [sf-operator CLI configuration file](./../../sfcli.config) to your liking, for example by setting up a custom FQDN. +[Create a sf-operator configuration file](../reference/cli/index.md#config) to your liking: + +```sh +sf-operator init config --dev > /path/to/sfcli.yaml +``` + +Then edit it as necessary, for example by setting up a custom FQDN. Below is an example you can copy and edit. + +??? abstract "CLI configuration example" + + ```yaml title="sfcli.yaml" + --8<-- "sfcli.yaml" + ``` Then run the `sf-operator` command: ```sh -sf-operator dev create demo-env +sf-operator --config /path/to/sfcli.yaml dev create demo-env ``` [This command](./../reference/cli/index.md#create-demo-env) performs the following tasks: @@ -76,38 +87,40 @@ To iterate on the development of the `sf-operator` you can either start the oper client is used to perform a `SofwareFactory` deployment based on `yaml` definition passed as parameter. -### Run the operator with the manager mode - -First, apply the `SoftwareFactory`'s `CR`: - -```sh -kubectl apply -f playbooks/files/sf.yaml -``` - -then run the operator with the following command: - -```sh -sf-operator --namespace sf operator -``` - -> The command does not return and wait for events to run the reconcile. - -You can kill and restart this process every time you modify the code base -to see your changes applied to the deployed resources. - -Any change on the applied `SofwareFactory`'s `CR` re-trigger the reconcile. - -### Run the operator in standalone mode - -Run the operator with the following command: - -```sh -sf-operator --namespace sf apply --cr playbooks/files/sf.yaml -``` - -> The command returns when the expected state is applied. - -Each change to the `CR`, passed as parameter, will require a new run of the command to `reconcile` the change. +=== "manager mode" + + First, apply the `SoftwareFactory`'s `CR`: + + ```sh + kubectl apply -f playbooks/files/sf.yaml + ``` + + then run the operator with the following command: + + ```sh + sf-operator --namespace sf operator + ``` + + !!! note + The command does not return and wait for events to run the reconcile. + + You can kill and restart this process every time you modify the code base + to see your changes applied to the deployed resources. + + Any change on the applied `SofwareFactory`'s `CR` will re-trigger the reconcile. + +=== "standalone mode" + + Run the operator with the following command: + + ```sh + sf-operator --namespace sf apply --cr playbooks/files/sf.yaml + ``` + + !!! note + The command returns when the expected state is applied. + + Each change to the `CR`, passed as parameter, will require a new run of the command to `reconcile` the change. ## Access the services web UI diff --git a/doc/developer/howtos/index.md b/doc/developer/howtos/index.md index 0eb5e218..50fcaba0 100644 --- a/doc/developer/howtos/index.md +++ b/doc/developer/howtos/index.md @@ -2,7 +2,6 @@ This document lists tips and methods to perform tasks that may be useful to a developer. -## Table of Contents 1. [How to run helper services](#how-to-run-helper-services) 2. [How to open a review on the test Gerrit](#how-to-open-a-review-on-the-test-gerrit) diff --git a/doc/developer/images.md b/doc/developer/images.md index dbdaf1bf..de2d79b8 100644 --- a/doc/developer/images.md +++ b/doc/developer/images.md @@ -3,9 +3,9 @@ This document explains how to modify or interact with images and services used by the SF-Operator for development purposes. -> These instructions assume you are using a MicroShift deployment for development. +!!! note + These instructions assume you are using a MicroShift deployment for development. -## Table of Contents 1. [Root access inside containers](#root-access-inside-containers) 1. [Modify an existing image](#modify-an-existing-image) @@ -14,7 +14,8 @@ for development purposes. ## Root access inside containers -> THIS STEP SHOULD BE ONLY USED FOR DEVELOPING PURPOSES!!! +!!! danger + These instructions should only be followed for development purposes, and may end up breaking your deployment. Use at your own risks! 1. Edit the target deployment, statefulset or pod directly. For example, with `nodepool-launcher`: diff --git a/doc/developer/index.md b/doc/developer/index.md index ca10b666..f130c6ab 100644 --- a/doc/developer/index.md +++ b/doc/developer/index.md @@ -1,8 +1,11 @@ +--- +title: About +--- + # Developer documentation Welcome to the developer documentation. You can find here what you need to spin up a development and testing environment for SF-Operator. -## Table of Contents 1. [Contribution guidelines](./CONTRIBUTING.md) 1. [Setting up a development environment](./getting_started.md) diff --git a/doc/developer/microshift.md b/doc/developer/microshift.md index 20407722..1fbffb57 100644 --- a/doc/developer/microshift.md +++ b/doc/developer/microshift.md @@ -7,7 +7,6 @@ We use Microshift as the target **OpenShift instance** for SF-Operator when depl The deployment will be performed via Ansible, by using the [ansible-microshift-role](https://github.com/openstack-k8s-operators/ansible-microshift-role). -## Table of Contents 1. [Requirements](#requirements) 1. [Install MicroShift](#install-microshift) @@ -68,6 +67,6 @@ sudo dnf install -y ansible-core golang ## Install MicroShift Installing Microshift is straightforward with the [ansible-microshift-role](https://github.com/openstack-k8s-operators/ansible-microshift-role). -The [sf-operator](./../reference/cli/index.md) CLI also provides the [`dev create microshift` subcommand](./../reference/cli/index.md#create-microshift) that sets up a microshift host from start to finish. Please refer to the documentation of this subcommand to learn how to use it. +The [sf-operator](./../reference/cli/index.md) CLI provides the [`dev create microshift` subcommand](./../reference/cli/index.md#create-microshift) that sets up a microshift host from start to finish. Please refer to the documentation of this subcommand to learn how to use it. Once the deployment has ended successfully, you are now ready to deploy and hack SF-Operator, congratulations! diff --git a/doc/developer/release.md b/doc/developer/release.md index 5c5a54b4..b19661e5 100644 --- a/doc/developer/release.md +++ b/doc/developer/release.md @@ -1,6 +1,6 @@ # How to release the sf-operator -A CI job named [sf-operator-publish-olm-bundle-image](https://zuul.microshift.softwarefactory-project.io/zuul/t/local/builds?job_name=sf-operator-publish-olm-bundle-image&skip=0) runs in the `release` pipeline. +A CI job named [sf-operator-publish-olm-bundle-image](https://microshift.softwarefactory-project.io/zuul/t/local/builds?job_name=sf-operator-publish-olm-bundle-image&skip=0) runs in the `release` pipeline. The `release` pipeline is triggered when a git tag is created on the `sf-operator` repository. This job builds and pushes the following assets to Quay.io: @@ -10,9 +10,10 @@ This job builds and pushes the following assets to Quay.io: ## Tagging sf-operator -> Only core contributors have the right to push a tag on the `sf-operator` repository. -If you aren't a core contributor but would like to suggest the creation of a new tag, -please contact us on [our matrix channel](https://matrix.to/#/#softwarefactory-project:matrix.org). +!!! note + Only core contributors have the right to push a tag on the `sf-operator` repository. + If you aren't a core contributor but would like to suggest the creation of a new tag, + please contact us on [our matrix channel](https://matrix.to/#/#softwarefactory-project:matrix.org). Here are the commands to run (assuming releasing HEAD to v0.0.20 version): diff --git a/doc/developer/testing.md b/doc/developer/testing.md index 1e6de09a..bc7d6c32 100644 --- a/doc/developer/testing.md +++ b/doc/developer/testing.md @@ -1,9 +1,10 @@ # Running the test suites locally -Tests run in the [project's CI](https://zuul.microshift.softwarefactory-project.io/zuul/t/sf/buildsets) can also be run locally using the [`sf-operator dev run-tests` CLI subcommand](./../reference/cli/index.md#run-tests). +Tests run in the [project's CI](https://zuul.microshift.softwarefactory-project.io/zuul/t/sf/buildsets) can also be run locally using the [`sf-operator dev run-tests` CLI subcommand](./../reference/cli/index.md#run-tests). (1) +{ .annotate } -> This command is a wrapper on top of `ansible-playbook` to run the same Ansible playbook -than the CI. This includes steps to deploy the operator if needed. +1. This command is a wrapper on top of `ansible-playbook` to run the same Ansible playbook + than the CI. This includes steps to deploy the operator if needed. The command accepts extra Ansible parameters to be passed to `ansible-playbook` command. @@ -48,10 +49,11 @@ sf-operator dev run-tests upgrade ### The standalone validation test -The `standalone` tests (similar to `sf-operator-dev-multinode` in the Zuul CI) performs +The `standalone` tests (1) (similar to `sf-operator-dev-multinode` in the Zuul CI) performs a standalone deployment and run the validation test suite. +{ .annotate } -> This is fastest way to run the test suite when iterating on the development of the `sf-operator`. +1. This is fastest way to run the test suite when iterating on the development of the `sf-operator`. ```sh sf-operator dev run-tests standalone diff --git a/doc/developer/troubleshooting.md b/doc/developer/troubleshooting.md index 9dbee855..d308e3b5 100644 --- a/doc/developer/troubleshooting.md +++ b/doc/developer/troubleshooting.md @@ -2,7 +2,6 @@ This document lists some methods that can be used to debug the various components of SF-Operator. -## Table of Contents 1. [OC Debugging](#oc-debugging) 1. [go-delve](#go-delve) diff --git a/doc/index.md b/doc/index.md deleted file mode 100644 index e0cd63e4..00000000 --- a/doc/index.md +++ /dev/null @@ -1,12 +0,0 @@ -# SF Operator documentation - -Welcome to SF-Operator's documentation. To know more about the project's purpose, -please consult the [README](./README.md). - -## Table of Contents - -1. [Operator documentation](./operator/index.md) -1. [Deployment documentation](./deployment/index.md) -1. [Developer documentation](./developer/index.md) -1. [End User documentation](./user/index.md) -1. [Reference](./reference/index.md) diff --git a/doc/operator/getting_started.md b/doc/operator/getting_started.md index a768dbb6..da4b4385 100644 --- a/doc/operator/getting_started.md +++ b/doc/operator/getting_started.md @@ -1,6 +1,5 @@ # Getting Started with the SF Operator -## Table of Contents 1. [Prerequisites](#prerequisites) 2. [Installing the Operator](#installing-the-operator) diff --git a/doc/operator/index.md b/doc/operator/index.md index 6bbe57e5..c78c81fb 100644 --- a/doc/operator/index.md +++ b/doc/operator/index.md @@ -1,8 +1,11 @@ +--- +title: About +--- + # Operator documentation Welcome to the operator documentation. It covers information about installing and managing the SF-Operator on an OpenShift cluster. -## Table of Contents 1. [Getting started](./getting_started.md) 1. [Uninstall the Operator](./uninstall.md) \ No newline at end of file diff --git a/doc/adr/0000-use-markdown-any-decision-records.md b/doc/reference/adr/0000-use-markdown-any-decision-records.md similarity index 100% rename from doc/adr/0000-use-markdown-any-decision-records.md rename to doc/reference/adr/0000-use-markdown-any-decision-records.md diff --git a/doc/adr/0001-operator-config.md b/doc/reference/adr/0001-operator-config.md similarity index 100% rename from doc/adr/0001-operator-config.md rename to doc/reference/adr/0001-operator-config.md diff --git a/doc/adr/0002-zuul-system-config.md b/doc/reference/adr/0002-zuul-system-config.md similarity index 100% rename from doc/adr/0002-zuul-system-config.md rename to doc/reference/adr/0002-zuul-system-config.md diff --git a/doc/adr/0003-config-update.md b/doc/reference/adr/0003-config-update.md similarity index 100% rename from doc/adr/0003-config-update.md rename to doc/reference/adr/0003-config-update.md diff --git a/doc/adr/0004-zuul-main.md b/doc/reference/adr/0004-zuul-main.md similarity index 100% rename from doc/adr/0004-zuul-main.md rename to doc/reference/adr/0004-zuul-main.md diff --git a/doc/adr/0005-ops-tooling.md b/doc/reference/adr/0005-ops-tooling.md similarity index 100% rename from doc/adr/0005-ops-tooling.md rename to doc/reference/adr/0005-ops-tooling.md diff --git a/doc/adr/0006-monitoring.md b/doc/reference/adr/0006-monitoring.md similarity index 100% rename from doc/adr/0006-monitoring.md rename to doc/reference/adr/0006-monitoring.md diff --git a/doc/adr/0007-edge-cert.md b/doc/reference/adr/0007-edge-cert.md similarity index 100% rename from doc/adr/0007-edge-cert.md rename to doc/reference/adr/0007-edge-cert.md diff --git a/doc/adr/0008-config-jobs.md b/doc/reference/adr/0008-config-jobs.md similarity index 100% rename from doc/adr/0008-config-jobs.md rename to doc/reference/adr/0008-config-jobs.md diff --git a/doc/adr/0009-database-agnosticity.md b/doc/reference/adr/0009-database-agnosticity.md similarity index 100% rename from doc/adr/0009-database-agnosticity.md rename to doc/reference/adr/0009-database-agnosticity.md diff --git a/doc/adr/0010-zuul-operator-usage.md b/doc/reference/adr/0010-zuul-operator-usage.md similarity index 100% rename from doc/adr/0010-zuul-operator-usage.md rename to doc/reference/adr/0010-zuul-operator-usage.md diff --git a/doc/adr/0011-backup-and-restore.md b/doc/reference/adr/0011-backup-and-restore.md similarity index 100% rename from doc/adr/0011-backup-and-restore.md rename to doc/reference/adr/0011-backup-and-restore.md diff --git a/doc/adr/0011-nodepool-builder.md b/doc/reference/adr/0011-nodepool-builder.md similarity index 100% rename from doc/adr/0011-nodepool-builder.md rename to doc/reference/adr/0011-nodepool-builder.md diff --git a/doc/adr/0012-CLI-overhaul.md b/doc/reference/adr/0012-CLI-overhaul.md similarity index 100% rename from doc/adr/0012-CLI-overhaul.md rename to doc/reference/adr/0012-CLI-overhaul.md diff --git a/doc/adr/0013-more-CLI-features.md b/doc/reference/adr/0013-more-CLI-features.md similarity index 99% rename from doc/adr/0013-more-CLI-features.md rename to doc/reference/adr/0013-more-CLI-features.md index f97cce44..8e80cccc 100644 --- a/doc/adr/0013-more-CLI-features.md +++ b/doc/reference/adr/0013-more-CLI-features.md @@ -1,5 +1,5 @@ --- -status: proposed +status: accepted date: 2024-01-26 --- diff --git a/doc/adr/adr-template.md b/doc/reference/adr/adr-template.md similarity index 98% rename from doc/adr/adr-template.md rename to doc/reference/adr/adr-template.md index 3d65e120..ccd463b0 100644 --- a/doc/adr/adr-template.md +++ b/doc/reference/adr/adr-template.md @@ -1,5 +1,5 @@ --- -status: {proposed | rejected | accepted | deprecated | … | superseded by [ADR-0005](0005-example.md)} +status: {proposed | rejected | accepted | deprecated | … | superseded by ADR-000XXX (add link)} date: {YYYY-MM-DD when the decision was last updated} --- diff --git a/doc/adr/index.md b/doc/reference/adr/index.md similarity index 83% rename from doc/adr/index.md rename to doc/reference/adr/index.md index 69a35adb..59e9714f 100644 --- a/doc/adr/index.md +++ b/doc/reference/adr/index.md @@ -1,12 +1,22 @@ +--- +title: About +--- + # Decisions This directory contains decision records for sf-operator. -For new ADRs, please use [doc/adr/adr-template.md](https://raw.githubusercontent.com/softwarefactory-project/sf-operator/master/doc/adr/adr-template.md) as a boilerplate. +For new ADRs, please use the template below as a boilerplate: + +??? abstract "ADR template" + + ```markdown title="template.md" + --8<-- "doc/reference/adr/adr-template.md" + ``` + More information on MADR is available at . General information about architectural decision records is available at . -## Table of Contents 1. [Use Markdown for ADRs](./0000-use-markdown-any-decision-records.md) 1. [Operator Configuration](./0001-operator-config.md) diff --git a/doc/reference/cli/index.md b/doc/reference/cli/index.md index d1147237..71e40be8 100644 --- a/doc/reference/cli/index.md +++ b/doc/reference/cli/index.md @@ -3,7 +3,6 @@ The `sf-operator` executable can be used to perform various actions related to the management of Software Factory deployments, beyond what can be defined in a custom resource manifest. -## Table of Contents 1. [Installing the CLI](#installing-the-cli) 1. [Global Flags](#global-flags) @@ -131,7 +130,8 @@ The `dev` subcommand can be used to manage a development environment and run tes #### cloneAsAdmin -> ⚠️ A Gerrit instance must have been deployed with the [create gerrit](#create-gerrit) command first. +!!! warning + A Gerrit instance must have been deployed with the [create gerrit](#create-gerrit) command first. Clone a given repository hosted on the Gerrit instance, as the admin user. You can then proceed to create patches and run them through CI with `git review`. If the repository already exists locally, @@ -152,7 +152,8 @@ Flags: Create a Gerrit instance if needed, then clone and populate demo repositories that will set up a demo tenant. -> ⚠️ This command will also install the operator's Custom Resource Definitions, so you need to run `make manifests` beforehand. +!!! warning + This command will also install the operator's Custom Resource Definitions, so you need to run `make manifests` beforehand. ```sh sf-operator [GLOBAL FLAGS] dev create demo-env [FLAGS] @@ -203,14 +204,16 @@ spec: Install and configure a MicroShift instance on a given server. This instance can then be used to host, develop and test the operator. -> ⚠️ `ansible-playbook` is required to run this command. Make sure it is installed on your system. - -> ⚠️ the "Local Setup" step of the installation requires local root access to install required development dependencies. If you don't want to automate this process, run the command with the `--dry-run --skip-deploy --skip-post-install` flags to inspect the generated playbook and figure out what you need. +!!! warning + `ansible-playbook` is required to run this command. Make sure it is installed on your system. ```sh sf-operator [GLOBAL FLAGS] dev create microshift [FLAGS] ``` +!!! warning + The "Local Setup" step of the installation requires local root access to install required development dependencies. If you don't want to automate this process, run the command with the `--dry-run --skip-deploy --skip-post-install` flags to inspect the generated playbook and figure out what you need. + Flags: | Argument | Type | Description | Optional | Default | @@ -312,7 +315,8 @@ The `nodepool` subcommand can be used to interact with the Nodepool component of Set or update Nodepool's providers secrets (OpenStack's clouds.yaml and Kubernetes/OpenShift's kube.config). -> ⚠️ At least one of the `--kube` or `--clouds` flags must be provided. +!!! warning + At least one of the `--kube` or `--clouds` flags must be provided. ```sh sf-operator [GLOBAL FLAGS] nodepool configure providers-secrets [--kube /path/to/kube.config --clouds /path/to/clouds.yaml] @@ -329,6 +333,9 @@ Flags: Create and set up a dedicated namespace on a cluster, so that nodepool can spawn pods with the [openshiftpods](https://zuul-ci.org/docs/nodepool/latest/openshift-pods.html) driver. +!!! note + See [this section in the deployment documentation](../../deployment/nodepool.md#using-the-openshiftpods-driver-with-your-cluster) for more details. + ```sh sf-operator [GLOBAL FLAGS] nodepool create openshiftpods-namespace [FLAGS] ``` @@ -364,7 +371,8 @@ Flags: Get the currently set providers secrets (OpenStack's clouds.yaml and Kubernetes/OpenShift's kube.config) and optionally write the secrets to a local file. -> ⚠️ The local files will be overwritten with the downloaded contents without warning! +!!! danger + The local files will be overwritten with the downloaded contents without warning! ```sh sf-operator [GLOBAL FLAGS] nodepool get providers-secrets [--kube /path/to/kube.config --clouds /path/to/clouds.yaml] @@ -471,7 +479,7 @@ These subcommands can be used to interact with the Zuul component of a deploymen The `create auth-token` subcommand can be used to create a custom authentication token that can be used with the [zuul-client CLI utility](https://zuul-ci.org/docs/zuul-client/). ```sh -go run ./main.go [GLOBAL FLAGS] zuul create auth-token [FLAGS] +sf-operator [GLOBAL FLAGS] zuul create auth-token [FLAGS] ``` Flags: @@ -487,10 +495,11 @@ Flags: The `create client-config` generates a configuration file that can be used with the [zuul-client CLI utility](https://zuul-ci.org/docs/zuul-client/) against the Software Factory deployment. -> ⚠️ The command provisions authentication tokens that grant admin access to all tenants. It is recommended to review and eventually edit the output of the command before forwarding it to third parties. +!!! warning + The command provisions authentication tokens that grant admin access to all tenants. It is recommended to review and eventually edit the output of the command before forwarding it to third parties. ```sh -go run ./main.go [GLOBAL FLAGS] zuul create client-config [FLAGS] > zuul-client.conf +sf-operator [GLOBAL FLAGS] zuul create client-config [FLAGS] > zuul-client.conf ``` Flags: @@ -501,4 +510,4 @@ Flags: | --tenant | string | The tenant on which to grant admin access | no | - | | --user | string | a username, used for audit purposes in Zuul's access logs | yes | "John Doe" | | --expiry | int | How long in seconds the authentication token should be valid for | yes | 3600 | -| --insecure | boolean | skip SSL validation when connecting to Zuul | yes | False | \ No newline at end of file +| --insecure | boolean | skip SSL validation when connecting to Zuul | yes | False | diff --git a/doc/reference/index.md b/doc/reference/index.md index 965be9b5..a9464d1d 100644 --- a/doc/reference/index.md +++ b/doc/reference/index.md @@ -1,9 +1,12 @@ +--- +title: About +--- + # Reference This section contains links to references for the SF-Operator project. -## Table of Contents 1. [API reference](./api/index.md) 1. [CLI reference](./cli/index.md) -1. [Architectural Decision Records](../adr/index.md) \ No newline at end of file +1. [Architectural Decision Records](./adr/index.md) \ No newline at end of file diff --git a/doc/user/index.md b/doc/user/index.md index 55b09219..a1c47959 100644 --- a/doc/user/index.md +++ b/doc/user/index.md @@ -1,8 +1,11 @@ +--- +title: About +--- + # User documentation Welcome to the User documentation. This section is aimed at the users of a Zuul-based CI infrastructure deployed with SF-Operator: repository maintainers, CI engineers, ... -## Table of Contents 1. [Using the config repository to setup Zuul tenants](./zuul_config_repository.md) 1. [Using the config repository to setup Nodepool configuration](./nodepool_config_repository.md) \ No newline at end of file diff --git a/doc/user/nodepool_config_repository.md b/doc/user/nodepool_config_repository.md index 7759124f..426e09f6 100644 --- a/doc/user/nodepool_config_repository.md +++ b/doc/user/nodepool_config_repository.md @@ -1,6 +1,5 @@ # Nodepool configuration -## Table of Contents 1. [File structure](#file-structure) 1. [Configuring Nodepool launcher](#configuring-nodepool-launcher) @@ -20,7 +19,8 @@ When the `config-check` and `config-update` jobs are run on git events occurring |_ my-cloud-image-1.yaml ``` -> if the file structure is missing or partial the jobs will skip the related configuration check and update. +!!! note + If the file structure is missing or partial the jobs will skip the related configuration check and update. The file `nodepool.yaml` holds [the labels and node providers configuration](https://zuul-ci.org/docs/nodepool/latest/configuration.html). This configuration is used by the `nodepool-launcher` process. @@ -30,11 +30,20 @@ The `dib-ansible` directory is used by `nodepool-builder` as the images build de ## Configuring Nodepool launcher -The configuration provided in `nodepool/nodepool.yaml` will be appended to the [base configuration](../../controllers/static/nodepool/generate-config.sh). +!!! danger + Please take care not to override any of the base settings! -> Please take care not to override any of the base settings +The configuration provided in `nodepool/nodepool.yaml` will be appended to the base configuration. -For each provider used in the Nodepool launcher configuration, nodepool must be able to find the required connection credentials. Please refer the deployment documentation about [setting up provider secrets](../deployment/nodepool#setting-up-provider-secrets). +??? question "What happens during a `config-update` job?" + + When a change to nodepool's configuration is merged, the following script is run to update the pods running nodepool: + + ```bash title="controllers/static/nodepool/generate-config.sh" + --8<-- "controllers/static/nodepool/generate-config.sh" + ``` + +For each provider used in the Nodepool launcher configuration, nodepool must be able to find the required connection credentials. Please refer the deployment documentation about [setting up provider secrets](../deployment/nodepool.md#setting-up-provider-secrets). ### Use an official cloud image within an OpenStack cloud @@ -78,15 +87,20 @@ providers: 4. If the `min-ready` property is over 0, you should see in the Zuul web UI, the new label and a ready node under the `labels` and `nodes` pages. -> Please refer to the [troubleshooting guide](../deployment/nodepool#troubleshooting) if needed. +!!! tip + If you encounter issues, please refer to the [troubleshooting guide](../deployment/nodepool.md#troubleshooting). ## Configuring Nodepool builder -The configuration provided in `nodepool/nodepool-builder.yaml` will be appended to the [base configuration](../../controllers/static/nodepool/generate-config.sh). +!!! danger + Please take care not to override any of the base settings! -> Please take care not to override any of the base settings +The configuration provided in `nodepool/nodepool-builder.yaml` will be appended to the base configuration. (1) +{ .annotate } -For each provider used in the Nodepool builder configuration, nodepool must be able to find the required connection credentials. Please refer the deployment documentation about [setting up provider secrets](../deployment/nodepool#setting-up-provider-secrets). +1. See ["What happens during a `config-update` job?"](#configuring-nodepool-launcher) for implementation details. + +For each provider used in the Nodepool builder configuration, nodepool must be able to find the required connection credentials. Please refer the deployment documentation about [setting up provider secrets](../deployment/nodepool.md#setting-up-provider-secrets). ### disk-image-builder @@ -94,7 +108,10 @@ Due to the security restrictions related to the OpenShift platform, the use of [ ### dib-ansible -[dib-ansible](../../controllers/static/nodepool/dib-ansible.py) is an alternative [dib-cmd](https://zuul-ci.org/docs/nodepool/latest/configuration.html#attr-diskimages.dib-cmd) wrapper that we provide within the `sf-operator` project. It is a `dib-cmd` wrapper to the `ansible-playbook` command. +`dib-ansible` (1) is an alternative [dib-cmd](https://zuul-ci.org/docs/nodepool/latest/configuration.html#attr-diskimages.dib-cmd) wrapper that we provide within the `sf-operator` project. It is a `dib-cmd` wrapper to the `ansible-playbook` command. +{ .annotate } + +1. For implementation details, the wrapper can be found at [controllers/static/nodepool/dib-ansible.py](https://raw.githubusercontent.com/softwarefactory-project/sf-operator/master/controllers/static/nodepool/dib-ansible.py) We recommend using `dib-ansible` to externalize the image build process on at least one image builder machine. @@ -153,9 +170,10 @@ Here are the available variables and their meaning: - qcow2_type: is a boolean specifying if the built image format is `qcow2`. - raw_type: is a boolean specifying if the built image format is `raw`. -> Zuul needs to authenticate via SSH onto Virtual Machines spawned from built cloud images. Thus, the Zuul SSH public key should be added as -an authorized key for the user Zuul will connect to. The Zuul SSH public key is available on the `nodepool-builder` into the file -`/var/lib/zuul-ssh-key/pub`. A cloud image build playbook can read that file to prepare a cloud image. +!!! note + Zuul needs to authenticate via SSH onto Virtual Machines spawned from built cloud images. Thus, the Zuul SSH public key should be added as + an authorized key for the user Zuul will connect to. The Zuul SSH public key is available on the `nodepool-builder` into the file + `/var/lib/zuul-ssh-key/pub`. A cloud image build playbook can read that file to prepare a cloud image. Finally we need an `inventory.yaml` file. It must be defined into `nodepool/dib-ansible/inventory.yaml`: @@ -163,15 +181,17 @@ Finally we need an `inventory.yaml` file. It must be defined into `nodepool/dib- ungrouped: hosts: image-builder: - ansible_host: + ansible_host: / ansible_user: nodepool ``` -> Nodepool builder must be able to connect via SSH to your image-builder machine. Thus please refer to the section [Get the Nodepool builder SSH public key](../deployment/nodepool#get-the-builders-ssh-public-key). +!!! note + Nodepool builder must be able to connect via SSH to your image-builder machine. Thus please refer to the section [Get the Nodepool builder SSH public key](../deployment/nodepool.md#get-the-builders-ssh-public-key). Once these three files `nodepool/dib-ansible/inventory.yaml`, `nodepool/dib-ansible/my-cloud-image.yaml` and `nodepool/nodepool-builder.yaml` are merged into the Software Factory `config` repository and the `config-update` has succeeded then Nodepool will run the build proces. -> At the first connection attempt of the `nodepool-builder` to an `image-builder` host, Ansible will refuse to connect because the SSH Host key is not known. Please refer to the section [Accept an image-builder's SSH Host key](../deployment/nodepool#accept-an-image-builders-ssh-host-key). +??? tip "SSH connection issues with an image-builder host?" + At the first connection attempt of the `nodepool-builder` to an `image-builder` host, Ansible will refuse to connect because the SSH Host key is not known. Please refer to the section [Accept an image-builder's SSH Host key](../deployment/nodepool.md#accept-an-image-builders-ssh-host-key). The image builds status can be consulted by accessing this endpoint: `https:///nodepool/api/dib-image-list`. diff --git a/doc/user/zuul_config_repository.md b/doc/user/zuul_config_repository.md index 491d945c..92b56b84 100644 --- a/doc/user/zuul_config_repository.md +++ b/doc/user/zuul_config_repository.md @@ -1,6 +1,5 @@ # Zuul configuration -## Table of Contents 1. [File structure](#file-structure) 1. [Defining a Zuul tenant](#defining-a-zuul-tenant) @@ -15,19 +14,27 @@ When the `config-check` and `config-update` jobs are run on git events occurring |_ main.yaml ``` -> if the file structure is missing or partial the jobs will skip the related configuration check and update. +!!! note + if the file structure is missing or partial the jobs will skip the related configuration check and update. The file `zuul/main.yaml` holds the [tenants configuration](https://zuul-ci.org/docs/zuul/latest/tenants.html) that will be applied the deployment. -> A git repository is called a `project` within the Zuul terminology. +!!! info "Definition" + A git repository is called a `project` within the Zuul terminology. ## Defining a Zuul tenant A Zuul tenant is defined through the `zuul/main.yaml` file. A Zuul tenant holds an isolated Zuul configuration from others Zuul tenants. -The configuration provided into `zuul/main.yaml` will be appended to the [base configuration](../../controllers/static/zuul/generate-tenant-config.sh). +The configuration provided into `zuul/main.yaml` will be appended to the base configuration. -> Please take care not to override the `internal` tenant definition. +??? question "What happens during a `config-update` job?" + + When a change to `zuul/main.yaml` is merged, the following script is run to update Zuul's tenant configuration on the scheduler: + + ``` title="controllers/static/zuul/generate-tenant-config.sh" + --8<-- "controllers/static/zuul/generate-tenant-config.sh" + ``` Here is an example of a minimal tenant defintion: @@ -44,15 +51,20 @@ Here is an example of a minimal tenant defintion: - zuul/zuul-jobs ``` +!!! danger + Please take care not to override the `internal` tenant definition. + A minimal Zuul tenant should be populated with at least one [config/trusted](https://zuul-ci.org/docs/zuul/latest/tenants.html#attr-tenant.config-projects) project. This tenant's config project (`my-tenant-config-repo` in the example above) defines Zuul configuration such as the `pipelines`, the `base job` and related base Ansible `playbooks`. While the tenant's config project could be setup manually, we also provide a `cli` command to scaffold its content. -> Note that [zuul/zuul-jobs](https://zuul-ci.org/docs/zuul-jobs/latest/) should be part of a new tenant. The `SF boostrap-tenant` command expects that - this repository is part of the tenant. +!!! note + The [zuul/zuul-jobs](https://zuul-ci.org/docs/zuul-jobs/latest/) project should always be part of a new tenant. The `SF boostrap-tenant` command expects that + this repository is part of the tenant. -> The `opendev.org` connection is available by default on any Software-Factory deployment. +!!! info + The `opendev.org` connection is preconfigured on any Software-Factory deployment. ### Bootstrap a config-project @@ -61,7 +73,8 @@ While the tenant's config project could be setup manually, we also provide a `cl * the `check`, `gate` and `post` pipelines * the `base job` and `playbooks` -> The tool only supports the definition of `pipelines` compatible with a `Gerrit` connection. +!!! warning + The tool only supports the definition of `pipelines` compatible with a `Gerrit` connection. Get a local checkout of the tenant's config project/repository then run: @@ -88,4 +101,4 @@ Zuul bot account for the related connection is authorized to set approvals, repo See the related section by connection type: -- Gerrit: [Set the Gerrit ACLs for repository](../deployment/config_repository#repository-acls-and-labels) \ No newline at end of file +- Gerrit: [Set the Gerrit ACLs for repository](../deployment/config_repository.md#repository-acls-and-labels) \ No newline at end of file diff --git a/flake.lock b/flake.lock index 42930f12..2567e671 100644 --- a/flake.lock +++ b/flake.lock @@ -16,9 +16,26 @@ "type": "github" } }, + "nixpkgs-latest": { + "locked": { + "lastModified": 1707205916, + "narHash": "sha256-fmRJilYGlB7VCt3XsdYxrA0u8e/K84O5xYucerUY0iM=", + "owner": "nixos", + "repo": "nixpkgs", + "rev": "8cc79aa39bbc6eaedaf286ae655b224c71e02907", + "type": "github" + }, + "original": { + "owner": "nixos", + "ref": "nixpkgs-unstable", + "repo": "nixpkgs", + "type": "github" + } + }, "root": { "inputs": { - "nixpkgs": "nixpkgs" + "nixpkgs": "nixpkgs", + "nixpkgs-latest": "nixpkgs-latest" } } }, diff --git a/flake.nix b/flake.nix index fab776ce..07993fe3 100644 --- a/flake.nix +++ b/flake.nix @@ -1,10 +1,12 @@ { description = "SF Operator Project"; nixConfig.bash-prompt = "[nix(sf-operator)] "; - inputs = { nixpkgs.url = "github:nixos/nixpkgs/23.05"; }; + inputs.nixpkgs.url = "github:nixos/nixpkgs/23.05"; + inputs.nixpkgs-latest.url = "github:nixos/nixpkgs/nixpkgs-unstable"; - outputs = { self, nixpkgs }: + outputs = { self, nixpkgs, nixpkgs-latest }: let pkgs = nixpkgs.legacyPackages.x86_64-linux.pkgs; + pkgsLatest = nixpkgs-latest.legacyPackages.x86_64-linux.pkgs; in { devShells.x86_64-linux.default = pkgs.mkShell { name = "SF-Operator dev shell"; @@ -29,6 +31,7 @@ pkgs.python310Packages.kubernetes # 3.0.10 in nixpkgs pkgs.openssl + pkgsLatest.python311Packages.mkdocs-material ]; shellHook = '' echo "Welcome in $name" diff --git a/mkdocs-requirements.txt b/mkdocs-requirements.txt new file mode 100644 index 00000000..41f933c5 --- /dev/null +++ b/mkdocs-requirements.txt @@ -0,0 +1,4 @@ +mkdocs==1.5.3 +mkdocs-material==9.5.7 +mkdocs-material-extensions==1.3.1 +pymdown-extensions==10.7 \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 00000000..dc29e025 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,126 @@ +site_name: sf-operator documentation + +repo_name: softwarefactory-project/sf-operator +repo_url: https://github.com/softwarefactory-project/sf-operator + +docs_dir: ./doc/ +theme: + name: material + features: + - content.code.annotate + - content.code.copy + - navigation.tabs + #- navigation.sections + - navigation.expand + - navigation.footer + - navigation.top + palette: + - scheme: default + primary: teal + accent: deep purple + toggle: + icon: material/brightness-5 + name: dark mode + - scheme: slate + primary: deep purple + accent: teal + toggle: + icon: material/brightness-7 + name: light mode +markdown_extensions: + - admonition + - attr_list + - md_in_html + - pymdownx.details + - pymdownx.highlight: + anchor_linenums: true + line_spans: __span + pygments_lang_class: true + - pymdownx.inlinehilite + - pymdownx.snippets: + base_path: + - "." + - pymdownx.superfences: + custom_fences: + - name: mermaid + class: mermaid + format: !!python/name:pymdownx.superfences.fence_code_format + - pymdownx.tabbed: + alternate_style: true + - toc: + permalink: true + +extra: + social: + - icon: simple/matrix + link: https://matrix.to/#/#softwarefactory-project:matrix.org + - icon: fontawesome/brands/docker + link: https://quay.io/organization/software-factory + - icon: fontawesome/brands/golang + link: https://pkg.go.dev/github.com/softwarefactory-project/sf-operator + - icon: fontawesome/brands/github + link: https://github.com/softwarefactory-project/sf-operator + +nav: + - Home: README.md + - Operator: + - operator/index.md + - Getting started: operator/getting_started.md + - Uninstall: operator/uninstall.md + - Deploy: + - deployment/index.md + - Getting started: deployment/getting_started.md + - Configuration repository: deployment/config_repository.md + - Services reference: + - Backing services: deployment/backing_services.md + # - Log server + - Nodepool: deployment/nodepool.md + - Zuul: deployment/zuul.md + - TLS: + - Setting up certificates: deployment/certificates.md + - Adding third-party certificates into the CA trust chain: deployment/corporate-certificates.md + - Monitoring: deployment/monitoring.md + - Logging: deployment/logging.md + - Deleting a deployment: deployment/delete.md + - User: + - user/index.md + - Services configuration: + - Nodepool: user/nodepool_config_repository.md + - Zuul tenants: user/zuul_config_repository.md + - Develop: + - developer/index.md + - Contributing: developer/CONTRIBUTING.md + - Getting started: developer/getting_started.md + - Developing on a MicroShift instance: developer/microshift.md + - Testing: developer/testing.md + - Releasing: developer/release.md + - Hacking images: developer/images.md + - Contributing: developer/CONTRIBUTING.md + - Howtos: + - developer/howtos/index.md + - Troubleshooting: developer/troubleshooting.md + - Reference: + - reference/index.md + - Decision Records (ADR): + - reference/adr/index.md + - reference/adr/0000-use-markdown-any-decision-records.md + - reference/adr/0001-operator-config.md + - reference/adr/0002-zuul-system-config.md + - reference/adr/0003-config-update.md + - reference/adr/0004-zuul-main.md + - reference/adr/0005-ops-tooling.md + - reference/adr/0006-monitoring.md + - reference/adr/0007-edge-cert.md + - reference/adr/0008-config-jobs.md + - reference/adr/0009-database-agnosticity.md + - reference/adr/0010-zuul-operator-usage.md + - reference/adr/0011-backup-and-restore.md + - reference/adr/0011-nodepool-builder.md + - reference/adr/0012-CLI-overhaul.md + - reference/adr/0013-more-CLI-features.md + # - Template: reference/adr/adr-template.md + - Custom Resource Definitions: deployment/crds.md + - API: + - reference/api/index.md + - CLI: + - reference/cli/index.md diff --git a/sfcli.config b/sfcli.yaml similarity index 100% rename from sfcli.config rename to sfcli.yaml