Merge pull request #60 from konstructio/colony-docs-update

Colony docs update

.vale/config/vocabularies/base/accept.txt

@@ -45,6 +45,7 @@ kbot
 KMS
 konstruct
 kubectl
+kubens
 
 # L
 Linode
@@ -93,6 +94,7 @@ uncomment
 # V
 vale
 vcluster
+VM
 Vultr
 
 # W

docs/index.md

@@ -1,74 +1,20 @@
 ---
+title: Overview
+description: Learn more about Konstruct's bare metal data center product
 sidebar_position: 1
 ---
 
-# Colony
+# What is Colony?
 
-colony is a bare metal provisioner and data center infrastructure management system. It's a cloud native microservice ecosystem with components hosted in konstruct cloud and other components that will run on your data centers. You need colony if you want to easily manage bare metal OS provisioning and deprovisioning operations in your own data centers.
+Colony is a bare metal provisioner and data center infrastructure management system. It's a cloud native microservice ecosystem with some components hosted in Konstruct and other components that run in your data centers.
 
-## Get Started
+Colony provides you a way to easily manage bare metal OS provisioning and deprovisioning operations in your own data centers.
 
-To be able to run colony, you will need to be physically within your data center with a laptop.
+- Read [our blog on Colony.](https://blog.konstruct.io/virtual-data-center/)
+- Check out [the Product page](https://konstruct.io/colony) to learn more and request a demo.
 
-### Prerequisites
+![Colony UI](./img/colony/colonylanding.png)
 
-To be able to run colony in your data center, you will need to install the colony CLI, have Docker Desktop running on your laptop and retrieve your colony API key.
+## Getting Support
 
-#### colony CLI
-
-The easiest way to install the colony CLI is using [Homebrew](https://brew.sh). Run this command in your terminal of choice:
-
-```shell
-brew install colony
-```
-
-If you need to upgrade the colony CLI, run:
-
-```shell
-brew update
-brew upgrade colony
-```
-
-#### Docker Desktop
-
-To install Docker Desktop on your machine, please follow [their instructions](https://docs.docker.com/get-docker/).
-
-#### colony API key
-
-To create a colony API key,first [sign-up to the colony management portal](https://colony-ui.mgmt-20.kubefirst.com/auth/signup).
-
-![colony sign-up page](img/colony/signup.png)
-
-You have the choice to create an account using the following providers:
-
-- Civo
-- GitHub
-- GitLab
-- Google
-
-Once signed in, open the "API keys" page from the "ADMIN SETTINGS" section of the left sidebar.
-
-![Empty API Keys page](img/colony/api-keys-empty.png)
-
-Click on the "Generate API key": while your new key is being created, the button text will quickly change to "", and once it's done, you will see a new key added in your API keys page.
-
-![API Keys page showing one key](img/colony/api-keys-new.png)
-
-To copy your newly created API key, either use the Copy button, or manually show the API key value, select the text and copy it into your clipboard. This key will be useful to initialize colony.
-
-### Install colony
-
-TBD
-
-### Discover your data center machines (physical or virtual)
-
-![Discovered assets in colony](img/colony/assets-discovered.png)
-
-TBD
-
-## Next steps
-
-Once our machines are available in the colony interface assets page, you have two choices:
-
-1. Use one of [our template to install an operating system](templates/index.md) on one or multiple machines.
-2. [Create one or multiple clusters](/clusters/index.md) on those machines.
+Do you have questions _before_ you get started? Did you run into an issue that is keeping you from using Colony? We can help! [Join our Slack Community](https://konstructio.slack.com/) for support and get the answers you need!

docs/install/index.md

@@ -0,0 +1,17 @@
+---
+title: Getting Started
+description: Follow the steps to install Colony in a virtual Vagrant environment
+sidebar_position: 2
+---
+
+# Get Started
+
+If you're new to Colony we recommend checking out the [Overview](/docs/index.md) to learn more about Colony.
+
+Keep at eye out for our future releases for install instructions in your data center. If you want to learn more [join our Slack Community](https://konstructio.slack.com/)!
+
+## How do I try Colony?
+
+Right now the easiest way to get started with Colony is by [installing our virtual Vagrant environment](virtual-install) to see how quick and easy it is to use.
+
+After you complete the initial set up, you can use Colony to discover your assets and provision a cluster.

docs/install/vagrant.md

@@ -0,0 +1,27 @@
+---
+title: Vagrant VM
+description: Learn more about how the Vagrant VM works
+sidebar_position: 5
+---
+
+## How does the Vagrant VM work?
+
+After the virtual data center setup completes there will be a small virtual rack of servers, including an exit node, a spine leaf network, and 5 virtual machines (VM) that are waiting to be turned on and auto-enrolled with Colony.
+
+The first part of the install is a setup that puts you on a VM “laptop” to match the experience of using Colony in a data center.
+
+Your VM “laptop” is loaded with tools like:
+
+- Colony CLI
+- Docker
+- Helm
+- K3d
+- kubectl - We add an alias for this
+- kubens
+- Tinkerbell (Tinkerbell stack)
+
+If you're curious about all of the tools we install, check out the repository details [in the setup here.](https://github.com/konstructio/colony-vagrant/blob/5182ef647fab8cffa17147a73ea6270da05c66fe/laptop/setup.sh#L3-L103)
+
+## Vagrant VM diagram
+
+![Colony Vagrant Diagram](../img/colony/colonyvagrantdiagram.png)

docs/install/virtual-install.md

@@ -0,0 +1,72 @@
+---
+title: Installing Colony
+description: Follow the steps to install Colony in a virtual Vagrant environment
+sidebar_position: 3
+---
+
+# Installing Colony
+
+## Summary
+
+This installation guide walks through what you need to install Colony into a repeatable Vagrant virtual environment. The virtual data center `colony-vagrant` creates an environment that you can host on a single Civo compute instance to explore Colony
+
+_We’re working to expand support for this virtual data center to include AWS soon._
+
+## What you’ll need
+
+To be able to install and run this virtual environment you need:
+
+- Git (Run `brew install git`)
+- Make (Run `brew install make`)
+- A [Civo API key](https://www.civo.com/docs/account/api-keys)
+- A Colony API token (_details on creating this below_)
+
+:::tip
+The Civo instance that hosts this virtual environment costs just under $1 to run for 4 hours, which is plenty of time to create some new bare metal Kubernetes clusters and add a hello world.
+:::
+
+### Generate your Colony API Key
+
+Logging in to Colony for the first time creates your account and gives you access to create an API Key. Accounts can be created by logging in with: Civo, GitHub, GitLab, or Google.
+
+Complete the steps to generate a new Colony API Key
+
+1. Log in to [Colony](https://colony.konstruct.io/)
+2. Navigate to **API Keys** and select **Generate API Key**
+   ![Colony API Key](../img/colony/colony-apikey.png)
+
+3. Once created, **copy and save the key** to use in your Colony install.
+
+## Steps to install Colony
+
+Follow the steps below to launch a virtual Vagrant environment.
+
+1. Run the following command to clone the Vagrant repository for Colony.
+
+   ```git
+   git clone https://github.com/konstructio/colony-vagrant
+   ```
+
+2. Navigate to the directory for the repository and make your data center.
+
+   ```bash
+   cd colony-vagrant
+   make dc
+   ```
+
+3. In the terminal, **select a region**. (_We typically use `nyc1`_)
+4. Add your **Civo API Key**.
+5. Enter your default **SSH key** (or your own/explicit key).
+6. Enter **a name** for your data center instance.
+7. Add your **Colony API Key**.
+8. Select the default **Colony CLI**.
+9. Click to select **Create data center**.
+
+_The process to create your virtual data center typically takes about 10 minutes._
+
+After the virtual data center setup completes there will be a small virtual rack of servers, including an exit node, a spine leaf network, and 5 virtual machines (VM) waiting to be turned on and auto-enrolled with Colony.
+
+## What's next?
+
+- [Start using Colony to discover assets](virtual-install2)
+- Check out what's [included with the Vagrant VM](vagrant)

docs/install/virtual-install2.md

@@ -0,0 +1,72 @@
+---
+title: Use Colony 
+description: Use Colony in a virtual environment to learn more 
+sidebar_position: 4
+---
+# Use Colony in the VM
+
+## Summary
+
+After successfully installing the virtual Vagrant environment you're ready to start discovering assets with Colony and adding configurations. Follow the steps outlined below to discover your assets, and create a cluster.
+
+## Discovering Assets
+
+Now that everything is installed and your VM “laptop” is up and running you’re going to connect the data center to Colony.
+
+1. Run the following command to connect your data center to Colony
+
+   ```bash
+   colony init -–apiKey= $COLONY_API_KEY –apiURL=https//colony-api-virtual.konstruct.io
+   ```
+
+2. Next, exit to return the shell back to the data center.
+
+   ```bash
+   exit
+   ```
+
+3. Finally, from the data center context run this command to turn on one of the reserved servers every 30 seconds, and auto-enroll them with Colony, making them available for provisioning operations.
+
+   ```bash
+   bash ./virtual-datacenter/power-on.sh
+   ```
+
+   :::info
+   If you connect to Colony and (_in the UI_) nothing appears after a minute or two there’s definitely an issue with the setup. Get in touch with us and we’ll be happy to get you sorted out.
+   :::
+
+4. Now imagine you’re walking around in the data center to “turn on” the virtual machines.
+
+- This process is smaller in scale and slower than it would be in an actual data center because of the constraints of the testing environment and all of the functionality we’ve built in for the virtual environment but it works exactly the same.
+
+You should see something like this:
+
+![Colony new data center](../img/usage/newdatacenter.png)
+
+## Creating Clusters
+
+After your assets are all listed as “discovered” you can navigate to the **Clusters page** in the sidebar and we can show you how easy it is to use Colony to create a new cluster (*in this example we’ll use Talos as a demo)
+
+:::note
+In a real-world set up data centers have network segmentation rules governing the IP address ranges in use.
+:::
+
+1. Select **Create Cluster** and choose **Kubernetes** from the menu to open the initial configuration. _For this example we’re going to create a new cluster with Talos._
+2. Complete the cluster details as follows:
+   - Select a cluster type - Talos (_simplicity and security_)
+   - Cluster Name - talos-demo (_or something similar_
+   - Global Gateway IP - 10.0.10.1 (_static for the vagrant data center environment_)
+   - Additional SANS (_not required_)
+
+3. Select **Next** to continue to select a Control Plane (_you can choose one or multiples, these instructions are for one_)
+4. Select the top disk (the multi-disk setup is just to show support)
+   - Static IP for all the VMs --> 10.0.10.20/24
+5. Select **Next** to continue to the Worker Node.
+   - Static IP 10.0.10.21/24
+
+**While it’s provisioning you will see Colony starting up the worker and control plane nodes.**
+
+:::tip
+
+Check out the [Colony Admin page](../usage) for details on deprovisioning
+:::