adds about.md

redbrick · Jan 30, 2023 · 32ae431 · 32ae431
1 parent 458c2ab
commit 32ae431
Show file tree

Hide file tree

Showing 3 changed files with 92 additions and 54 deletions.
diff --git a/docs/aperture/about.md b/docs/aperture/about.md
@@ -0,0 +1,62 @@
+# Aperture
+
+Aperture is Redbrick's fleet of hardware that was installed in May 2022 by `distro`, `pints`, `skins`, `cawnj`, `ymacomp`
+and `arkues`. It consists of:
+
+- 3x Dell R6515
+
+    | CPU | RAM | Storage |
+    | ---- | ---- | ------- |
+    | AMD 7302P 3GHz, 16C/32T, 128M, 155W, 3200 | 2x 16GB RDIMM, 3200MT/s Dual Rank | 4x 2TB SATA HDDs (hardware RAID) |
+
+- 2x Ubiquiti USW Pro
+- 1x Ubiquiti UDM Pro
+
+## Servers
+
+The three servers are named `glados`, `wheatley` and `chell`.
+
+## Networks
+
+The firewall is called [`mordor`](firewall.md), and the two 24-port switches are called [`rivendell` and `isengard`](switches.md).
+
+## Networking
+
+The IP address range for the `aperture` subnet is 10.10.0.0/24, with 10.10.0.0/16 being used for user VMs.
+
+| Hostname | Internal Address | External Address | Purpose |
+| -------- | ---------- | -------- | ------- |
+| `mordor` | 10.10.0.1 | N/A | Firewall |
+| `rivendell` | 10.10.0.2 | N/A | Switch |
+| `isengard` | 10.10.0.3 | N/A | Switch |
+| `glados` | 10.10.0.4 | 136.206.16.4 | Server |
+| `wheatley` | 10.10.0.5 | 136.206.16.5 | Server |
+| `chell` | 10.10.0.6 | 136.206.16.6 | Server |
+
+!!! note
+    Blue cables are used for production network.
+
+## KVM
+
+`nexus` is the name of the KVM switch. It's internal IP address is 10.10.0.10.
+
+`glados` is connected on port 1, `wheatley` on port 2, and `chell` on port 3.
+
+!!! note
+    Yellow cables are used for KVM network.
+
+## IDRAC
+
+The new servers are all equipped with IDRACs. These still need to be configured.
+
+!!! node
+    Red cables are used for IDRAC network.
+
+## [Images (click me)](images.md)
+
+## Switching from the old network to the new
+
+We have two address ranges that come in on a single redundant link, so we're exchanging that redundant link for two
+separate links, each taking responsibility for an address range (136.26.15.0/24 and 136.206.16.0/24). So we're surrendering
+redundancy to gain uptime/connectivity during the switchover only. Once the new servers are production ready, we can
+recombine the link to regain the redundancy.
diff --git a/docs/aperture/ansible.md b/docs/aperture/ansible.md
@@ -32,6 +32,8 @@ chell
 ansible_user= <your username>
 ```
 
+> Contact @distro for a fully populated file.
+
 ### Test it out
 
 ```bash
@@ -83,3 +85,18 @@ Redbrick's ansible configuration is stored in the [ansible](https://github.com/r
 some more documentation there on each playbook.
 
 Ansible's documentation is available [here](https://docs.ansible.com/ansible/latest/index.html).
+
+## Common Errors
+
+### Hashicorp Apt Key
+
+Sometimes, when running a playbook, you'll get an error like this:
+
+```bash
+TASK [apt : apt update packages to their latest version and autoclean] ***************************************************************************************************
+fatal: [wheatley]: FAILED! => {"changed": false, "msg": "Failed to update apt cache: unknown reason"}
+fatal: [chell]: FAILED! => {"changed": false, "msg": "Failed to update apt cache: unknown reason"}
+fatal: [glados]: FAILED! => {"changed": false, "msg": "Failed to update apt cache: unknown reason"}
+```
+
+This is because the Hashicorp apt key has expired. To fix this, uncomment the `hashicorp-apt` task in the playbook.
diff --git a/docs/aperture/index.md b/docs/aperture/index.md
@@ -1,62 +1,21 @@
 # Aperture
 
-Aperture is Redbrick's fleet of hardware that was installed in May 2022 by `distro`, `pints`, `skins`, `cawnj`, `ymacomp`
-and `arkues`. It consists of:
+What is aperture? It's nothing to do with cameras. See [about](about.md) for more information on the hardware.
 
-- 3x Dell R6515
-
-    | CPU | RAM | Storage |
-    | ---- | ---- | ------- |
-    | AMD 7302P 3GHz, 16C/32T, 128M, 155W, 3200 | 2x 16GB RDIMM, 3200MT/s Dual Rank | 4x 2TB SATA HDDs (hardware RAID) |
+## New Admins
 
-- 2x Ubiquiti USW Pro
-- 1x Ubiquiti UDM Pro
+If you're a new admin, this is a cheat sheet for you. In order to get broadly up to speed and understand the content of
+these pages, I suggest you read the following:
 
-## Servers
+- [About](about.md)
+- [Nomad docs](https://www.nomadproject.io/docs/), specifically the [job specification](https://developer.hashicorp.com/nomad/docs/job-specification)
+and [managing nomad jobs](https://developer.hashicorp.com/nomad/tutorials/manage-jobs) pages.
+- [Consul docs]](https://www.consul.io/docs), specifically how it can be used with Nomad.
+- [Ansible docs](https://docs.ansible.com/ansible/latest/index.html), specifically the [playbook](https://docs.ansible.com/ansible/latest/user_guide/playbooks.html)
 
-The three servers are named `glados`, `wheatley` and `chell`.
+## FAQ
 
-## Networks
+So, you've hit a problem. Here's some quicklinks to some common problems:
 
-The firewall is called [`mordor`](firewall.md), and the two 24-port switches are called [`rivendell` and `isengard`](switches.md).
-
-## Networking
-
-The IP address range for the `aperture` subnet is 10.10.0.0/24, with 10.10.0.0/16 being used for user VMs.
-
-| Hostname | Internal Address | External Address | Purpose |
-| -------- | ---------- | -------- | ------- |
-| `mordor` | 10.10.0.1 | N/A | Firewall |
-| `rivendell` | 10.10.0.2 | N/A | Switch |
-| `isengard` | 10.10.0.3 | N/A | Switch |
-| `glados` | 10.10.0.4 | 136.206.16.4 | Server |
-| `wheatley` | 10.10.0.5 | 136.206.16.5 | Server |
-| `chell` | 10.10.0.6 | 136.206.16.6 | Server |
-
-!!! note
-    Blue cables are used for production network.
-
-## KVM
-
-`nexus` is the name of the KVM switch. It's internal IP address is 10.10.0.10.
-
-`glados` is connected on port 1, `wheatley` on port 2, and `chell` on port 3.
-
-!!! note
-    Yellow cables are used for KVM network.
-
-## IDRAC
-
-The new servers are all equipped with IDRACs. These still need to be configured.
-
-!!! node
-    Red cables are used for IDRAC network.
-
-## [Images (click me)](images.md)
-
-## Switching from the old network to the new
-
-We have two address ranges that come in on a single redundant link, so we're exchanging that redundant link for two
-separate links, each taking responsibility for an address range (136.26.15.0/24 and 136.206.16.0/24). So we're surrendering
-redundancy to gain uptime/connectivity during the switchover only. Once the new servers are production ready, we can
-recombine the link to regain the redundancy.
+- [I can't connect to Aperture](vpn.md)
+- [Ansible is running into an error](ansible.md#common-errors)