diff --git a/.github/workflows/mkdocs.yaml b/.github/workflows/mkdocs.yaml new file mode 100644 index 00000000..1e423941 --- /dev/null +++ b/.github/workflows/mkdocs.yaml @@ -0,0 +1,59 @@ +name: pages build and deployment + +on: + push: + branches: + - main + paths: + - "docs/**" + - ".github/workflows/mkdocs.yml" + pull_request: + paths: + - "docs/**" + - ".github/workflows/mkdocs.yml" + workflow_dispatch: + +# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued. +# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete. +concurrency: + group: "pages" + cancel-in-progress: false + +jobs: + build: + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-python@v5 + with: + python-version: 3.x + - run: pip install -r doc-requirements.txt + - run: mkdocs build + - uses: actions/upload-pages-artifact@v2 + with: + path: site/ + + deploy: + # depend on the docs being built + needs: build + + # ensure we only run on commits to the main branch + if: github.ref == 'refs/heads/main' + + runs-on: ubuntu-latest + + # Grant GITHUB_TOKEN the permissions required to make a Pages deployment + permissions: + pages: write # to deploy to Pages + id-token: write # to verify the deployment originates from an appropriate source + + # Deploy to the github-pages environment + environment: + name: "github-pages" + url: ${{ steps.deployment.outputs.page_url }} + + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v2 diff --git a/.gitignore b/.gitignore index 07aa5c34..eeb46464 100644 --- a/.gitignore +++ b/.gitignore @@ -121,3 +121,6 @@ kubernetes_sigs-kubespray*tar.gz ansible_collections kustomize/**/all.yaml + +# mkdocs +site/ diff --git a/README.md b/README.md index 7e16757e..93cc369f 100644 --- a/README.md +++ b/README.md @@ -6,27 +6,7 @@ Genestack — where Kubernetes and OpenStack tango in the cloud. Imagine a waltz what you need. ## Documentation -* Getting Started - * [Getting Started](docs/getting-started.md) -* Kubernetes - * [Building Your Kubernetes Environment](docs/build-k8s.md) - * [Retrieve kube config](docs/kube-config.md) -* Storage - * [Create Persistent Storage](docs/create-persistent-storage.md) -* Openstack Infrastructure - * [Deploy Openstack on k8s](docs/deploy-openstack.md) -* Build Images - * [Building Local Images](docs/build-local-images.md) -* Build Test Environments - * [Building Virtual Environments for Testing](docs/build-test-envs.md) -* Networking - * [OVN Database Backup](docs/ovn-db-backup.md) -* Post Deployment - * [Post Deploy Operations](docs/post-deploy-ops.md) -* Upgrades - * [Running Genestack Upgrade](docs/genestack-upgrade.md) - * [Running Kubernetes Upgrade](docs/k8s-upgrade.md) - +[Genestack Documentation](https://rackerlabs.github.io/genestack/) ## Included/Required Components * Kubernetes: @@ -101,3 +81,15 @@ architecture of the Genestack ecosystem. They say a picture is worth 1000 words, so here's a picture. ![Genestack Architecture Diagram](assets/images/diagram-genestack.png) + +## Get Deploying + +Read the [docs](https://github.com/rackerlabs/genestack/wiki), start building your clouds with Genestack now. + +### Get the Docs + +You can clone a copy of all of our documentation locally by running the following command. + +``` shell +git clone https://github.com/rackerlabs/genestack/wiki +``` diff --git a/doc-requirements.txt b/doc-requirements.txt new file mode 100644 index 00000000..9a8a4ca4 --- /dev/null +++ b/doc-requirements.txt @@ -0,0 +1,2 @@ +mkdocs +mkdocs-material diff --git a/docs/Create-Persistent-Storage.md b/docs/Create-Persistent-Storage.md index fbc8f4fa..dd1d21dd 100644 --- a/docs/Create-Persistent-Storage.md +++ b/docs/Create-Persistent-Storage.md @@ -188,7 +188,7 @@ The following steps are one way to set it up, however, consult the [documentatio ### Create the target volume group on your hosts -TopoLVM requires access to a volume group on the physical host to work, which means we need to set up a volume group on our hosts. By default, TopoLVM will use the controllers as storage hosts. The genestack Kustomize solution sets the general storage volume group to `vg-general`. This value can be changed within Kustomize found at `kustomize/topolvm/general/kustomization.yaml`. +TopoLVM requires access to a volume group on the physical host to work, which means we need to set up a volume group on our hosts. By default, TopoLVM will use the controllers as storage hosts. The genestack Kustomize solution sets the general storage volume group to `vg-general`. This value can be changed within Kustomize found at `kustomize/topolvm/general/kustomization.yaml`. > Simple example showing how to create the needed volume group. @@ -205,4 +205,3 @@ Once the volume group is on your storage nodes, the node is ready for use. ``` shell kubectl kustomize --enable-helm /opt/genestack/kustomize/topolvm/general | kubectl apply -f - ``` - diff --git a/docs/Deploy-Openstack.md b/docs/Deploy-Openstack.md index 799a0ec0..dfeebbf8 100644 --- a/docs/Deploy-Openstack.md +++ b/docs/Deploy-Openstack.md @@ -700,4 +700,3 @@ kubectl --namespace openstack \ ``` shell kubectl --namespace openstack apply -k /opt/genestack/kustomize/skyline/base ``` - diff --git a/docs/deploy-required-infrastructure.md b/docs/deploy-required-infrastructure.md index 94391f9c..4d6a4a8f 100644 --- a/docs/deploy-required-infrastructure.md +++ b/docs/deploy-required-infrastructure.md @@ -310,4 +310,3 @@ kubectl --namespace openstack get horizontalpodautoscaler.autoscaling memcached ``` Once everything is Ready and online. Continue with the installation. - diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 00000000..5d4f9400 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,21 @@ +## Genestack Documentation +* Getting Started + * [Getting Started](docs/getting-started.md) +* Kubernetes + * [Building Your Kubernetes Environment](docs/build-k8s.md) + * [Retrieve kube config](docs/kube-config.md) +* Storage + * [Create Persistent Storage](docs/create-persistent-storage.md) +* Openstack Infrastructure + * [Deploy Openstack on k8s](docs/deploy-openstack.md) +* Build Images + * [Building Local Images](docs/build-local-images.md) +* Build Test Environments + * [Building Virtual Environments for Testing](docs/build-test-envs.md) +* Networking + * [OVN Database Backup](docs/ovn-db-backup.md) +* Post Deployment + * [Post Deploy Operations](docs/post-deploy-ops.md) +* Upgrades + * [Running Genestack Upgrade](docs/genestack-upgrade.md) + * [Running Kubernetes Upgrade](docs/k8s-upgrade.md) diff --git a/docs/kube-config.md b/docs/kube-config.md index 7801ced3..d6cdecd0 100644 --- a/docs/kube-config.md +++ b/docs/kube-config.md @@ -30,4 +30,3 @@ Edit the kube config to point at the first controller. ``` shell sed -i 's@server.*@server: https://X.X.X.X:6443@g' "${HOME}/.kube/config" ``` - diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 00000000..38e0d707 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,60 @@ +--- +site_name: Genestack +site_description: >- + Genestack — where Kubernetes and OpenStack tango in the cloud. Imagine a waltz between systems that deploy what you need. + +theme: + name: material + + palette: + - media: "(prefers-color-scheme: light)" + scheme: default + toggle: + icon: material/brightness-7 + name: Switch to dark mode + - media: "(prefers-color-scheme: dark)" + scheme: slate + toggle: + icon: material/brightness-4 + name: Switch to light mode + + features: + - announce.dismiss + - content.action.edit + - content.code.annotate + - content.code.copy + # - content.tabs.link + - content.tooltips + # - header.autohide + # - navigation.expand + - navigation.footer + - navigation.indexes + - navigation.instant + # - navigation.prune + - navigation.sections + - navigation.tabs + - navigation.tabs.sticky + - navigation.top + - navigation.tracking + - search.highlight + - search.share + - search.suggest + - toc.follow + +plugins: + - search + +markdown_extensions: + - admonition + - attr_list + - def_list + +repo_name: rackerlabs/genestack +repo_url: https://github.com/rackerlabs/genestack +dev_addr: "127.0.0.1:8001" +edit_uri: "edit/main/docs" + +nav: + - Home: index.md + - Quick-Start: quickstart.md + - Components: components.md