feat: add missing doc links and context

Signed-off-by: Kevin Carter <[email protected]>

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
-```

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)

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 -

docs/vault.md

@@ -3,30 +3,36 @@
 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.
 - **Sealed-secret:** If the Vault UI URL will use a domain certificate then, the Kubernetes secret should be deployed in the vault namespace. Make sure the secret manifest is encrypted using sealed-secret for secure storage in a Git repository.
 - **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 - <<EOF
 path "osh/*" {
    capabilities = ["read"]
@@ -104,7 +125,8 @@ EOF
 ```
 
 - Create a role which will restrict the access as per your requirement:
-```bash
+
+``` shell
 vault write auth/genestack/role/osh \
    bound_service_account_names=default \
    bound_service_account_namespaces=openstack \
@@ -114,26 +136,37 @@ vault write auth/genestack/role/osh \
 ```
 
 - Create secrets for keystone:
+
 Now, generate and store secrets for Keystone within the designated path.
-  - Keystone RabbitMQ Username:
-    ```bash
-    vault kv put -mount=osh/keystone keystone-rabbitmq-username username=keystone
-    ```
-  - Keystone RabbitMQ Password:
-    ```bash
-    vault kv put -mount=osh/keystone keystone-rabbitmq-password password=$(< /dev/urandom tr -dc _A-Za-z0-9 | head -c${1:-64};echo;)
-    ```
-  - Keystone Database Password:
-    ```bash
-    vault kv put -mount=osh/keystone keystone-db-password password=$(< /dev/urandom tr -dc _A-Za-z0-9 | head -c${1:-32};echo;)
-    ```
-  - Keystone Admin Password:
-    ```bash
-    vault kv put -mount=osh/keystone keystone-admin  password=$(< /dev/urandom tr -dc _A-Za-z0-9 | head -c${1:-32};echo;)
-    ```
-  - Keystone Credential Key:
-    ```bash
-    vault kv put -mount=osh/keystone keystone-credential-keys  password=$(< /dev/urandom tr -dc _A-Za-z0-9 | head -c${1:-32};echo;)
-    ```
+
+- Keystone RabbitMQ Username:
+
+``` shell
+vault kv put -mount=osh/keystone keystone-rabbitmq-username username=keystone
+```
+
+- Keystone RabbitMQ Password:
+
+``` shell
+vault kv put -mount=osh/keystone keystone-rabbitmq-password password=$(< /dev/urandom tr -dc _A-Za-z0-9 | head -c${1:-64};echo;)
+```
+
+- Keystone Database Password:
+
+``` shell
+vault kv put -mount=osh/keystone keystone-db-password password=$(< /dev/urandom tr -dc _A-Za-z0-9 | head -c${1:-32};echo;)
+```
+
+- Keystone Admin Password:
+``` shell
+vault kv put -mount=osh/keystone keystone-admin  password=$(< /dev/urandom tr -dc _A-Za-z0-9 | head -c${1:-32};echo;)
+```
+
+- Keystone Credential Key:
+``` shell
+vault kv put -mount=osh/keystone keystone-credential-keys  password=$(< /dev/urandom tr -dc _A-Za-z0-9 | head -c${1:-32};echo;)
+```
+
 ---
+
 Once the secrets are created in Vault, we can use `vault-secrets-operator` to populate the Kubernetes secret resources in Kubernetes cluster.

mkdocs.yml

@@ -57,3 +57,4 @@ edit_uri: "edit/main/docs"
 nav:
   - Documentation: 'index.md'
   - Components: components.md
+  - Quickstart: quickstart.md