From 611d85d7c4eb9d68f4f7b8d74fcd1312027496f1 Mon Sep 17 00:00:00 2001 From: Kevin Carter Date: Mon, 26 Feb 2024 13:04:08 -0600 Subject: [PATCH] feat: add missing doc links and context Signed-off-by: Kevin Carter --- README.md | 16 ++----- docs/index.md | 52 +++++++++++++++++------ docs/prometheus.md | 4 +- docs/vault.md | 103 ++++++++++++++++++++++++++++++--------------- mkdocs.yml | 1 + 5 files changed, 115 insertions(+), 61 deletions(-) diff --git a/README.md b/README.md index 93cc369f..c3f6109b 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,11 @@ Genestack — where Kubernetes and OpenStack tango in the cloud. Imagine a waltz what you need. ## Documentation + +Read the deployment and operations documentation + [Genestack Documentation](https://rackerlabs.github.io/genestack/) + ## Included/Required Components * Kubernetes: @@ -81,15 +85,3 @@ 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/docs/index.md b/docs/index.md index 437c7b03..a87ea7ed 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,20 +1,48 @@ -#### 1.Getting Started +# Welcome to the Genestack Documentation + +Genestack — where Kubernetes and OpenStack tango in the cloud. Imagine a waltz between systems that deploy +what you need. Operators play the score, managing the complexity with a flick of their digital batons. They +unify the chaos, making scaling and management a piece of cake. Think of it like a conductor effortlessly +guiding a cacophony into a symphony. + +## Environment Architecture + +Genestack is making use of some homegrown solutions, community operators, and OpenStack-Helm. Everything +in Genestack comes together to form cloud in a new and exciting way; all built with opensource solutions +to manage cloud infrastructure in the way you need it. + +They say a picture is worth 1000 words, so here's a picture. + +![Genestack Architecture Diagram](assets/images/diagram-genestack.png) + +--- + +Building our cloud future has never been this simple. + +### 0.Getting Started * [Getting Started](getting-started.md) -#### 2.Kubernetes + * [Building Virtual Environments for Testing](build-test-envs.md) + +### 1.Kubernetes * [Building Your Kubernetes Environment](build-k8s.md) * [Retrieve kube config](kube-config.md) -#### 3.Storage + +### 2.Storage * [Create Persistent Storage](Create-Persistent-Storage.md) -#### 4.Openstack Infrastructure - * [Deploy Openstack on k8s](Deploy-Openstack.md) -####Build Images + +### 3.Infrastructure + * [Deploy Required Infrastructure](deploy-required-infrastructure.md) + * [Deploy Prometheus](prometheus.md) + * [Deploy Vault](vault.md) + +### 4.Openstack Infrastructure + * Deploy Openstack on k8s](Deploy-Openstack.md) + +#### Post Deployment + * [Post Deploy Operations](post-deploy-ops.md) * [Building Local Images](build-local-images.md) -####Build Test Environments - * [Building Virtual Environments for Testing](build-test-envs.md) -####Networking * [OVN Database Backup](ovn-db-backup.md) -####Post Deployment - * [Post Deploy Operations](post-deploy-ops.md) -####Upgrades + +#### Upgrades * [Running Genestack Upgrade](genestack-upgrade.md) * [Running Kubernetes Upgrade](k8s-upgrade.md) diff --git a/docs/prometheus.md b/docs/prometheus.md index 84303cff..de5973bf 100644 --- a/docs/prometheus.md +++ b/docs/prometheus.md @@ -1,11 +1,11 @@ -##Prometheus +# Prometheus We are using Prometheus for monitoring and metrics collection backend. To read more about Prometheus see: https://prometheus.io #### Install kube-prometheus helm chart -``` +``` shell cd /opt/genestack/kustomize/prometheus kubectl kustomize --enable-helm . | kubectl create -f - diff --git a/docs/vault.md b/docs/vault.md index 3840b0c3..d65a0671 100644 --- a/docs/vault.md +++ b/docs/vault.md @@ -3,6 +3,7 @@ HashiCorp Vault is a versatile tool designed for secret management and data protection. It allows you to securely store and control access to various sensitive data, such as tokens, passwords, certificates, and API keys. In this guide, we will use HashiCorp Vault to store Kubernetes Secrets for the Genestack installation. ## Prerequisites + Before starting the installation, ensure the following prerequisites are met: - **Storage:** Kubernetes Cluster should have available storage to create a PVC for data storage, especially when using integrated storage backend and storing audit logs. - **Ingress Controller:** An Ingress Controller should be available as Vault's UI will be exposed using Ingress. @@ -10,23 +11,28 @@ Before starting the installation, ensure the following prerequisites are met: - **Cert-Manager:** The installation will use end-to-end TLS generated using cert-manager. Hence, cert-manager should be available. ## Installation -```bash + +``` shell cd kustomize/vault/base ``` + Modify the `values.yaml` file with your desired configurations. Refer to the sample configuration in this directory, already updated for installation. -```bash +``` shell vi values.yaml ``` - Perform the installation: -```bash + +``` shell kustomize build . --enable-helm | kubectl apply -f - ``` ## Configure Vault + After installing Vault, the Vault pods will initially be in a not-ready state. Initialization and unsealing are required. -``` + +``` shell NAME READY STATUS RESTARTS AGE vault-0 0/1 Running 0 55s vault-1 0/1 Running 0 55s @@ -35,38 +41,48 @@ vault-agent-injector-7f9f668fd5-wk7tm 1/1 Running 0 55s ``` ### Initialize Vault -```bash + +``` shell kubectl exec vault-0 -n vault -- vault operator init -key-shares=5 -key-threshold=3 -format=json > cluster-keys.json ``` + This command provides unseal keys and a root token in cluster-keys.json. Keep this information secure. ### Join Vault Pods to Form a Cluster -```bash + +``` shell kubectl exec -it vault-1 -n vault -- sh vault operator raft join -leader-ca-cert=@/vault/userconfig/vault-server-tls/ca.crt https://vault-0.vault-internal:8200 ``` -```bash + +``` shell kubectl exec -it vault-2 -n vault -- sh vault operator raft join -leader-ca-cert=@/vault/userconfig/vault-server-tls/ca.crt https://vault-0.vault-internal:8200 ``` ### Unseal Vault + On each Vault pod (vault-0, vault-1, vault-2), use any of the 3 unseal keys obtained during initialization: -```bash +``` shell kubectl exec -it vault-1 -n vault -- sh vault operator unseal ``` + Repeat the unseal command as needed with different unseal keys. ### Authenticate to Vault + Use the root token obtained during initialization to authenticate: -```bash + +``` shell kubectl exec -it vault-0 -- vault login ``` ## Validation + Login to vault-0 and list the raft peers: -``` + +``` shell kubectl exec vault-0 -n vault -it -- sh / $ vault operator raft list-peers Node Address State Voter @@ -75,27 +91,32 @@ vault-0 vault-0.vault-internal:8201 leader true vault-1 vault-1.vault-internal:8201 follower true vault-2 vault-2.vault-internal:8201 follower true ``` + --- ## Example to create secrets in Vault for Keystone: - Enable Kubernetes auth method: -```bash + +``` shell kubectl exec --stdin=true --tty=true vault-0 -n vault -- vault auth enable -path genestack kubernetes ``` - Define Kubernetes connection: -```bash + +``` shell kubectl exec --stdin=true --tty=true vault-0 -n vault -- vault write auth/genestack/config kubernetes_host="https://$KUBERNETES_PORT_443_TCP_ADDR:443" ``` - Define secret path for keystone: -```bash + +``` shell kubectl exec --stdin=true --tty=true vault-0 -n vault -- vault secrets enable -path=osh/keystone kv-v2 ``` - Create a policy to access `osh/*` path: -```bash + +``` shell vault policy write osh - <