diff --git a/.order b/.order index 77d8b7f..41c0361 100644 --- a/.order +++ b/.order @@ -2,11 +2,15 @@ README welcome getting-started agile-working +traceability-concept documentation-guidelines +stages versioning branching-code-review-process -network +requirements-gathering-interview service-catalogue +network +vms-and-lxcs know-how/git-commands know-how/sap-tricks faq diff --git a/README.md b/README.md index 2eaa68e..d24c9c8 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,19 @@ This space is for the engineering team to share knowledge, resources, and best practices. +## Conventions + +### Naming conventions + +As we are heavily using Microsoft Azure and Azure DevOps, we are following the naming conventions provided by Microsoft: + +- [Abbreviation recommendations for Azure resources](https://learn.microsoft.com/en-us/azure/cloud-adoption-framework/ready/azure-best-practices/resource-abbreviations) + +Furthermore, we are using the [AzureNamingTool](https://github.com/mspnp/AzureNamingTool): + +- [AzureNamingTool Deployment Instructions](https://xwr.visualstudio.com/jambor.pro/_git/app-azure-naming) +- [AzureNamingTool Development Instance](https://app-azurenamingtool-dev-bnhfgbdgafeqh2gf.switzerlandnorth-01.azurewebsites.net) + ## Sructure of the repository We are trying to keep the repositories small and structured. The following overview shows the general structure and the most important repositories. diff --git a/agile-working.md b/agile-working.md index 1045b8c..38e2818 100644 --- a/agile-working.md +++ b/agile-working.md @@ -32,6 +32,7 @@ We based our setup on the CMMI process template. The following work items and st - Each team member works on tasks, selected independently from the "Ready" area. - Tasks in the "Done" column of each state should first undergo a peer review within the team. - Only tasks in the "Closed" column are considered fully completed. +- It is best practice to not have more than 2 work items in progress at the same time. Tools: Azure Boards diff --git a/know-how/git-commands.md b/know-how/git-commands.md index 8d5136a..13080ef 100644 --- a/know-how/git-commands.md +++ b/know-how/git-commands.md @@ -1,5 +1,7 @@ # Git Commands +You can also review [Oh Shit, Git!?!](https://ohshitgit.com/), for some good solutions to comon git problems. + ## Random Ideas [Kart: DVC for geospatial and tabular data. Git for GIS](https://kartproject.org/), [Discussion](https://news.ycombinator.com/item?id=38073512#git), [Go to Post from 2023-10-30T20:40:06](https://social.lansky.name/@hn50/111325898767760054) diff --git a/network.md b/network.md index 4fb9bae..34e3ecb 100644 --- a/network.md +++ b/network.md @@ -1,12 +1,26 @@ # Network +List of vnets (latest version see Unifi console): + +| Name | VLAN ID | Router | Subnet | +| --- | --- | --- | --- | +| Default | 1 | prd-unifi-1 | 192.168.1.0/24 | +| Management | 2 | prd-unifi-1 | 192.168.2.0/24 | +| Clients | 3 | prd-unifi-1 | 192.168.3.0/24 | +| Server | 4 | prd-unifi-1 | 192.168.4.0/24 | +| IoT | 5 | prd-unifi-1 | 192.168.5.0/24 | +| Guests | 6 | prd-unifi-1 | 192.168.6.0/24 | +| Volt - Development | 7 | prd-unifi-1 | 192.168.7.0/24 | +| Var - Testing | 8 | prd-unifi-1 | 192.168.8.0/24 | +| Watt - Production | 9 | prd-unifi-1 | 192.168.9.0/24 | + Tasks: - Define Networks - OK Ranges definieren - OK Verteilen, was wohin kommt - - VLAN IDs statisch besser als dynamisch - - DNS definieren (fix vs. dynamisch) + - OK VLAN IDs statisch besser als dynamisch + - OK DNS definieren (fix vs. dynamisch) - Gateway Settings - Auto Update - Block outgoing DNS diff --git a/resources/diagrams/network.drawio b/resources/diagrams/network.drawio index 49a88b1..b225ae2 100644 --- a/resources/diagrams/network.drawio +++ b/resources/diagrams/network.drawio @@ -1,136 +1,234 @@ - + - + - - + + - - - - + + + + + + + + + + + + + + + - + - + - - + + - - + + - - + + - - + + - - + + - - + + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + - + - - + + - - + + - - + + - - + + - - + + - - + + - - - - - + + - + - + - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/resources/diagrams/network.png b/resources/diagrams/network.png index fca6a12..25aa98e 100644 Binary files a/resources/diagrams/network.png and b/resources/diagrams/network.png differ diff --git a/stages.md b/stages.md new file mode 100644 index 0000000..2a8f508 --- /dev/null +++ b/stages.md @@ -0,0 +1,11 @@ +# Stages + +**Ampere (Traffic Router):** The conductor ensuring that the flow of development, testing, and deployment processes is directed to the correct stage efficiently and effectively. + +1. Volt (Development): This is the initial stage where new features and fixes are developed and tested. It's the foundation for your application, similar to how the volt is a fundamental unit of electrical potential. + +2. Var (Staging): In this stage, code is rigorously tested in an environment that mimics the production setting. Var, the unit for reactive power, resonates with this stage's role in ensuring that the system will react effectively under various conditions. + +3. Watt (Production): The final stage where the application is live and accessible to end-users. Named after the unit of power, this stage is where the system's full capabilities are utilized. + +This naming scheme maintains a consistent theme while capturing the essence of each stage. diff --git a/vms-and-lxcs.md b/vms-and-lxcs.md new file mode 100644 index 0000000..7292d5b --- /dev/null +++ b/vms-and-lxcs.md @@ -0,0 +1,67 @@ +# Basic Know-How about VMs and LXC containers + +## Microsft Azure compatible Linux Distributions + +We love Debian, but it's not well supported by Microsoft Azure. Thus we are going mainstream and use Ubuntu. + +## User Management + +- Limit root login to console only as an emergency fallback. You can login via the hypervisor console then. +- Create a `ansible` super user with sudo rights; allow SSH access by keys only. This is used for maintenance and configuration. +- Create a normal user `debian` with restricted privileges; also allow SSH by keys only. This one can be used for normal system tasks. +- Disallow password-based SSH logins for all users besides root. +- Periodically review SSH logs for unauthorized access attempts. + +## IaC vs. CaC + +Infratsructure as Code (IaC) is how we deploy virtual bare-metal. We are using Terraform for that. + +Configuration as Code (CaC) is how we configure the VMs and LXC containers and install software. We are using Ansible for that. + +We are defining the boundary between IaC and CaC as follows: + +- IaC is responsible for the VMs and LXC containers, the network, and the storage. +- IaC ends as soon as the VMs and LXC containers are up and running. +- SSH keys are installed by IaC. +- CaC is responsible for the software installed on the VMs and LXC containers. +- CaC uses the SSH keys installed by IaC to connect to the VMs and LXC containers. + +## IaC Terraform Proxmox Provider + +The [Proxmox Terraform Provider](https://github.com/Telmate/terraform-provider-proxmox) is not mature enough now. Thus we use [Proxmox VE Helper-Scripts](https://community-scripts.github.io/ProxmoxVE/scripts). + +The following text in this chapter are notes and references in case the provider gets more mature and we switch in the future. + +Our hypervisor is Proxmox, which is based on Debian. We are using the [Proxmox cloud-init](https://pve.proxmox.com/wiki/Cloud-Init_Support) template for Ubuntu. + +We are using a small server images to keep the attack surface small. The cloud-init template is a server Ubuntu image with cloud-init installed. Get the URL from the Ubuntu website and download it to the Proxmox servers local storage for ISO images. Ubuntu website link: [https://cloud-images.ubuntu.com/releases/](https://cloud-images.ubuntu.com/releases/). We are going for the file ending in `*server-cloudimg-amd64.img`. + +We are also using Ubuntu for the LXC containers. We are using the latest Ubuntu standard LXC template you can download via the Proxmox web interface for that. + +## SSH keys + +SSH keys are managed via the approach described in the [infra-terraform-sshkeyvault](https://xwr.visualstudio.com/jambor.pro/_git/infra-terraform-sshkeyvault) repository. As of now we create them one by one with the provided scripts. + +## Create an LXC container + +- Make use of the [Azure Naming Tool](https://app-azurenamingtool-dev-bnhfgbdgafeqh2gf.switzerlandnorth-01.azurewebsites.net/) to get a suitable name for the LXC container. We use the same schema as for virtual machines. E.g. `vm-mal-dev-opr-1` +- Create a new ssh key according to the [infra-terraform-sshkeyvault](https://xwr.visualstudio.com/jambor.pro/_git/infra-terraform-sshkeyvault) repository. Use a name from the naming tool, e.g. `kvs-mal-dev-opr-1` + +- Search for a pre-defined template or the latest Ubuntu template: [Proxmox VE Helper-Scripts](https://community-scripts.github.io/ProxmoxVE/scripts) +- Review the script and check that you understand it and no malicious code is in it. (ha ha, we all do that, right?) +- Execute the script on the Proxmox servers shell via the web interface. SSH is not advised for that. + +- If you cannot choose Ubuntu as distribution, you should choose to create an empty Ubunto LXC and install the desired service on top of that. +- Create a LXC within the Proxmox web interface and use the latest Ubuntu LTS template. +- **Important networking note** using IPv6 dhcp causes the network to stop working as the lease seems not to be updated. Keep IPv6 as static, IPv4 can be dhcp. +- Ensure to set the right vnet ID according to [networking instructions](network.md). +- ssh into the LXC container making use of the ssh key. +- Install waht ever you need to install. Preferably use Ansible for that. + +## Create a VM + +- ... + +## Add new resource to Ansible repository + +We are maintaining VMs and LXCs with Ansible. Add the newly created VM or LXC to the Ansible inventory [infra-ansible-serverconfiguration](https://xwr.visualstudio.com/jambor.pro/_git/infra-ansible-serverconfiguration).