srx/fab-city-software-kit
1
0
Fork 0
mirror of https://gitlab.fabcity.hamburg/software/fab-city-software-kit.git synced 2024-09-19 20:08:52 +02:00
Code Packages Projects Releases Activity

renamed project and updated documentation

Browse source
This commit is contained in:
Sebastian Wendel 2023-03-29 17:33:53 +02:00
parent c5eda3d891
commit 7115fe8a42
No known key found for this signature in database
GPG key ID: 14ED8B1EC3371ECE
3 changed files with 171 additions and 24 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

112
KUBERNETES.md Normal file
View file

@ -0,0 +1,112 @@
# Kubernetes introduction
[Kubernetes (K8s)](https://kubernetes.io/), is an open-source system for automating deployment, scaling, and management of containerized applications. You can run a FabCityOS Core instance inside your Kubernetes cluster, either if you want to expose it to the outside world or just let some other applications use it inside your cluster and take advantage of the instant and powerful search engine.
First of all, you will need a Kubernetes cluster up and running. If you are not familiar with how Kuberentes works or need some help with this step, please check the [Kubernetes documentation](https://kubernetes.io/docs/home/).
## About K3s
[K3s](https://k3s.io/) is a lightweight, certified Kubernetes distribution designed for resource-constrained environments such as edge devices, IoT, and ARM processors. It is a fully compliant Kubernetes distribution that provides a simplified installation process, reduced memory footprint, and optimized networking performance. K3s is easy to set up, operate and maintain, making it ideal for developers who want to deploy and manage Kubernetes clusters on small-scale infrastructure. It is open source and free to use, and it supports all Kubernetes features such as storage, networking, and load balancing. Overall, K3s provides a simplified, lightweight, and reliable Kubernetes solution for running containerized applications in resource-constrained environments.
## Kubernetes cluster sizing
[Kubernetes cluster sizing](https://learnk8s.io/kubernetes-node-size) is the process of determining the appropriate resources and capacity required for a Kubernetes cluster to run your workloads efficiently and effectively. Sizing a Kubernetes cluster involves evaluating a variety of factors, including the size and complexity of your workloads, the amount of traffic they generate, and the available resources in your infrastructure.
When sizing a Kubernetes cluster, it's important to consider factors such as CPU, memory, and storage requirements for your workloads. You'll need to determine the number and type of nodes required to run your workloads and ensure that your nodes have sufficient resources to meet your application's demands.
Another important consideration when sizing a Kubernetes cluster is the availability and resiliency requirements of your workloads. You'll need to determine the number of replicas required to ensure that your application can continue to function in the event of node failures or other issues.
Ultimately, the goal of Kubernetes cluster sizing is to ensure that your cluster can meet the performance and availability requirements of your applications while optimizing resource utilization and minimizing costs. [Properly sizing](https://kubernetes.io/docs/setup/best-practices/cluster-large/) your Kubernetes cluster can help you achieve these goals, and ensure that your applications are running smoothly and efficiently.
## Kubernetes setup on Debian
A guide through the process of installing and configuring k3s on Debian, including adding additional agents.
### Install Dependencies
Before we can install k3s, we need to make sure that our system has the necessary dependencies. Run the following command to update the package list and install dependencies:
```sh
sudo apt-get update && sudo apt-get install -y curl iptables
```
### Install k3s
The easiest way to install k3s is to use the installation script provided by Rancher. Run the following command to download and run the script:
```sh
curl -sfL <https://get.k3s.io> | sh -
```
This will install k3s on your system. You can verify that k3s is running by running the following command:
```sh
sudo systemctl status k3s
```
### Configure k3s
By default, k3s is configured to run as a single-node cluster. If you want to configure it to run as a multi-node cluster, you need to edit the configuration file. The configuration file is located at `/etc/rancher/k3s/config.yaml`.
You can edit this file to specify the configuration options for k3s. Some of the options you might want to change include the cluster token, the node IP address, and the server URL.
Once you have made your changes, save the file and restart the k3s service by running the following command:
```sh
sudo systemctl restart k3s
```
### Add Additional Agents
To add additional agents to your k3s cluster, you need to run the k3s agent on each node. You can do this by running the following command on each node:
```sh
curl -sfL <https://get.k3s.io> | K3S_URL=<https://<server-ip>:6443> K3S_TOKEN=<cluster-token> sh -
```
Replace <server-ip> with the IP address of the k3s server, and <cluster-token> with the token generated during the installation of k3s.
Once the agent is running on each node, you can verify that the nodes are added to the cluster by running the following command on the k3s server:
```sh
sudo kubectl get nodes
```
This should show a list of all the nodes in your k3s cluster.
That's it! You have successfully installed and configured k3s on Debian, including adding additional agents.
## About Kustomize
Kubernetes [Kustomize](https://kubectl.docs.kubernetes.io/references/kustomize/) is a tool that allows you to customize and manage Kubernetes resources through overlays, patches, and base configurations. It is a native configuration management tool for Kubernetes that helps you manage your application's configuration files in a more organized and efficient way.
With Kustomize, you can create multiple versions of your Kubernetes resources for different environments, such as development, testing, and production, without duplicating your configuration files. Kustomize allows you to keep your base configuration separate from environment-specific configuration, making it easier to manage changes and updates to your application.
To work with Kustomize, you'll need to create a base configuration that defines the common configuration for your application, and then use overlays and patches to customize the configuration for each environment. Kustomize uses a simple directory structure and a set of YAML files to manage your Kubernetes resources.
Overall, Kustomize is a powerful tool that simplifies the management of your Kubernetes resources, making it easier to manage your applications in a dynamic, multi-environment environment.
## Security advice
Here are some advice on evaluating the quality, security and selection of Kubernetes third party Helm charts:
### Quality
- **Check the Chart Documentation**: A well-documented Helm chart will contain detailed instructions for deploying the application along with various configuration options available to the user.
- **Community Support**: Check the community support for the chart by checking the number of stars, forks, and issues in the project's GitHub repository. It's also worth checking if the chart is listed in the Helm Hub and if it has been certified by the CNCF.
- **Versioning**: Check if the chart follows semantic versioning, which ensures that changes in the chart are backward compatible.
- **Release Frequency**: Check the release frequency of the chart. A chart that is frequently updated and maintained is a good indication that the developers are actively working on it.
### Security
- **Check the Dependencies**: Helm charts are made up of dependencies. Ensure that the chart's dependencies are secure and have no known vulnerabilities.
- **Container Images**: Check if the chart's container images are built from trusted sources and are updated regularly to address security vulnerabilities.
- **Secrets**: Ensure that the chart does not store secrets in plain text in the Kubernetes manifests. Instead, secrets should be encrypted and stored in a secret store like Vault or Keycloak.
- **Compliance**: Ensure that the chart follows best practices for compliance with security standards like CIS Kubernetes Benchmark or NIST SP 800-190.
### Selection
- **Customization**: Check if the chart can be easily customized to meet your requirements. Ensure that it provides configuration options for various components and services.
- **Popularity**: Check the popularity of the chart by checking the number of downloads, stars, and forks on the project's GitHub repository. A popular chart is more likely to have community support and will be easier to find help and documentation.
- **Compatibility**: Ensure that the chart is compatible with your Kubernetes cluster and other software components in your environment.
- **Support**: Check if the chart is supported by the vendor or developer. Ensure that there is a support plan or community support available for the chart.

81
README.md
View file

@ -2,43 +2,53 @@
<img src="https://raw.githubusercontent.com/dyne/interfacer-docs/main/docs/_media/general/interfacer-logo.png" alt="Interfacer" />
</p>
<h1 align="center">Interfacer SWKit for Kubernetes ⚓️</h1>
<h1 align="center">Fab City Software Kit for Kubernetes ⚓️</h1>
<h4 align="center">
<a href="https://interfacerproject.github.io/interfacer-docs">Documentation</a> |
<a href="https://www.interfacerproject.eu/">Website</a> |
<a href="https://www.interfacerproject.eu/#news">Blog</a>
</h4>
<p align="center">
<a href="https://gitlab.fabcity.hamburg/software/interfacer-swkit/LICENSE"><img src="https://img.shields.io/badge/license-AGPL-informational" alt="License"></a>
<a href="https://gitlab.fabcity.hamburg/software/interfacer-swkit/-/pipelines"><img src="https://gitlab.fabcity.hamburg/software/interfacer-swkit/badges/main/pipeline.svg" alt="Pipeline"></a>
<a href="https://matrix.to/#/#fcos:fabcity.hamburg"><img src="https://img.shields.io/badge/Matrix-FCOS-blue.svg?logo=element" alt="Matrix"></a>
<a href="https://gitlab.fabcity.hamburg/software/fab-city-os-core-chart/LICENSE"><img src="https://img.shields.io/badge/license-AGPL-informational" alt="License"></a>
<a href="https://matrix.to/#/#fcos:fabcity.hamburg"><img src="https://img.shields.io/badge/Matrix-FabCityOS-blue.svg?logo=element" alt="Matrix"></a>
</p>
This Repo is designed to be a lightweight way to configure the Interfacer SWKit applications. Interfacer SWKit is a bundle of Applications to enabling a data-based circular economy via global collaboration and local production.
Welcome to the Fab City Software Kit! This Repo is designed to be a lightweight way to configure the Fab City Software Kit applications. Fab City Software Kit is a bundle of Applications to enabling a data-based circular economy via global collaboration and local production.
## About the **INTERFACER** Project
The goal of the INTERFACER project is to build the open-source digital infrastructure for Fab Cities.
Our vision is to promote a green, resilient, and digitally-based mode of production and consumption that enables the greatest possible sovereignty, empowerment and participation of citizens all over the world.
We want to help Fab Cities to produce everything they consume by 2054 on the basis of collaboratively developed and globally shared data in the commons.
To know more [DOWNLOAD THE WHITEPAPER](https://www.interfacerproject.eu/assets/news/whitepaper/IF-WhitePaper_DigitalInfrastructureForFabCities.pdf).
## Table of Contents <!-- omit in toc -->
- [📖 Documentation](#-documentation)
- [About the **INTERFACER** Project](#about-the-interfacer-project)
- [🚀 Getting Started](#-getting-started)
- [Kubernetes introduction](#kubernetes-introduction)
- [Repository structure](#repository-structure)
- [⚙️ Dependencies](#️-dependencies)
- [Install kubectl](#install-kubectl)
- [Install helm](#install-helm)
- [⚙️ Development Workflow and Contributing](#️-development-workflow-and-contributing)
## 📖 Documentation
- [kubectl](https://kubernetes.io/docs/reference/generated/kubectl/kubectl-commands)
- [kustomize](https://kubectl.docs.kubernetes.io/guides/)
- [helm](https://helm.sh/docs/)
- [cert-manager](https://cert-manager.io/docs/)
- [ingress-nginx](https://kubernetes.github.io/ingress-nginx/)
- [💾 Install Fab City Software Kit](#-install-fab-city-software-kit)
- [📖 Documentation](#-documentation)
- [Tools](#tools)
- [Helm Charts](#helm-charts)
- [👤 Contributing](#-contributing)
- [🌐 Links](#-links)
- [💼 License](#-license)
## 🚀 Getting Started
Kubernetes (K8s), is an open-source system for automating deployment, scaling, and management of containerized applications. You can run a FabCityOS Core instance inside your Kubernetes cluster, either if you want to expose it to the outside world or just let some other applications use it inside your cluster and take advantage of the instant and powerful search engine.
### Kubernetes introduction
First of all, you will need a Kubernetes cluster up and running. If you are not familiar with how Kuberentes works or need some help with this step, please check the [Kubernetes documentation](https://kubernetes.io/docs/home/).
Please refer to our [introductory guide](./KUBERNETES.md) for a brief overview of Kubernetes setup, cluster sizing, command-line tools, and security considerations.
### Repository structure
@ -63,6 +73,8 @@ First of all, you will need a Kubernetes cluster up and running. If you are not
└── flake.nix # nix flake for local runtime dependency
```
## ⚙️ Dependencies
### Install kubectl
`kubectl` is the most commonly used CLI to manage a Kubernetes cluster. The installation instructions are [available here](https://kubernetes.io/docs/tasks/tools/install-kubectl/).
@ -71,16 +83,39 @@ First of all, you will need a Kubernetes cluster up and running. If you are not
`helm` is a Command Line Interface which will automate chart management and installation on your Kubernetes cluster. To install Helm, follow the [Helm installation instructions](https://helm.sh/docs/intro/install/).
#### Deploy the SWKit <!-- omit in toc -->
### 💾 Install Fab City Software Kit
```sh
git clone https://gitlab.fabcity.hamburg/software/interfacer-swkit.git
cd interfacer-swkit
git clone https://gitlab.fabcity.hamburg/software/fab-city-software-kit/
cd fab-city-software-kit
kubectl kustomize --enable-helm overlays/dev | kubectl apply -f -
```
## ⚙️ Development Workflow and Contributing
## 📖 Documentation
Any new contribution is more than welcome in this project!
### Tools
If you want to know more about the development workflow or want to contribute, please visit our [contributing guidelines](/CONTRIBUTING.md) for detailed instructions!
- [kubectl](https://kubernetes.io/docs/reference/generated/kubectl/kubectl-commands)
- [kustomize](https://kubectl.docs.kubernetes.io/guides/)
- [helm](https://helm.sh/docs/)
### Helm Charts
- [Cert Manager](https://cert-manager.io/docs/)
- [Ingress Nginx](https://kubernetes.github.io/ingress-nginx/)
- [Fab City OS Core](https://gitlab.fabcity.hamburg/software/fab-city-os-core-chart)
- [Gitea](https://gitea.com/gitea/helm-chart/)
- [Matrix Synapse](https://github.com/ananace/matrix-synapse)
## 👤 Contributing
Any new contribution is more than welcome in this project! If you want to know more about the development workflow or want to contribute, please visit our [contributing guidelines](/CONTRIBUTING.md) for detailed instructions!
## 🌐 Links
- <https://interfacerproject.eu/>
- <https://fabcity.hamburg/>
## 💼 License
[AGPL-3.0](./LICENSE). © 2023 Fab City Hamburg e. V.

2
apps/kustomization.yaml
View file

@ -1,6 +1,6 @@
---
resources:
- interfacer-webpresence
- interfacer-core
- interfacer-webpresence
- gitea
- synapse