diff --git a/README.md b/README.md index dc1105d4..23ef1af8 100644 --- a/README.md +++ b/README.md @@ -8,13 +8,13 @@

- + - + - + @@ -27,7 +27,6 @@

- # WireGuard® Automation from Homelab to Enterprise - [x] Peer-to-Peer Mesh Networks - [x] Site-to-Site Gateways diff --git a/config/config.go b/config/config.go index 22471614..367bbb83 100644 --- a/config/config.go +++ b/config/config.go @@ -61,6 +61,7 @@ type ServerConfig struct { CheckinInterval string `yaml:checkininterval` DefaultNodeLimit int32 `yaml:"defaultnodelimit"` Verbosity int32 `yaml:"verbosity"` + ServerCheckinInterval int64 `yaml:"servercheckininterval"` } diff --git a/database/postgres.go b/database/postgres.go index 74b30e1a..efe3932d 100644 --- a/database/postgres.go +++ b/database/postgres.go @@ -26,7 +26,7 @@ var PG_FUNCTIONS = map[string]interface{}{ func getPGConnString() string { pgconf := servercfg.GetSQLConf() pgConn := fmt.Sprintf("host=%s port=%d user=%s "+ - "password=%s dbname=%s sslmode=%s", + "password=%s dbname=%s sslmode=%s connect_timeout=5", pgconf.Host, pgconf.Port, pgconf.Username, pgconf.Password, pgconf.DB, pgconf.SSLMode) return pgConn } diff --git a/docs/_build/doctrees/architecture.doctree b/docs/_build/doctrees/architecture.doctree index b5c897ae..b1cd1400 100644 Binary files a/docs/_build/doctrees/architecture.doctree and b/docs/_build/doctrees/architecture.doctree differ diff --git a/docs/_build/doctrees/environment.pickle b/docs/_build/doctrees/environment.pickle index d8ba343d..4df0dba5 100644 Binary files a/docs/_build/doctrees/environment.pickle and b/docs/_build/doctrees/environment.pickle differ diff --git a/docs/_build/doctrees/server-installation.doctree b/docs/_build/doctrees/server-installation.doctree index bfd68624..5ebe8e9d 100644 Binary files a/docs/_build/doctrees/server-installation.doctree and b/docs/_build/doctrees/server-installation.doctree differ diff --git a/docs/_build/html/.buildinfo b/docs/_build/html/.buildinfo index 7d1c1c1a..32ab5bd0 100644 --- a/docs/_build/html/.buildinfo +++ b/docs/_build/html/.buildinfo @@ -1,4 +1,4 @@ # Sphinx build info version 1 # This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done. -config: c5f7c337a81aafa96c2a1d23d89efa34 +config: a1af1119123a96439517d8d95e387598 tags: 645f666f9bcd5a90fca523b33c5a78b7 diff --git a/docs/_build/html/_sources/architecture.rst.txt b/docs/_build/html/_sources/architecture.rst.txt index 92c5b485..1a1720f8 100644 --- a/docs/_build/html/_sources/architecture.rst.txt +++ b/docs/_build/html/_sources/architecture.rst.txt @@ -77,13 +77,13 @@ Netmaker Server The Netmaker server is, at its core, a golang binary. Source code can be found `on GitHub `_. The binary, by itself can be compiled for most systems. If you need to run the Netmaker server on a particular system, it likely can be made to work. In typical deployments, it is run as a Docker container. It can also be run as a systemd service as outlined in the non-docker install guide. -The Netmaker server acts as an API to the front end, and as a GRPC server to the machines in the network. GRPC is much faster and more efficient than standard API calls, which increases the speed of transactions. For this reason, the Netmaker server exposes two ports: The default for the API is 8081, and the default for GRPC is 50051. Either the API or the GRPC server can be disabled on any given Netmaker instance can be disabled, allowing you to deploy two different servers for managing the API (which is largely for the admin's use) and GRPC (which is largely for the nodes' use). +The Netmaker server acts as an API to the front end, and as a GRPC server to the machines in the network. GRPC is much faster and more efficient than standard API calls, which increases the speed of transactions. For this reason, the Netmaker server exposes two ports: The default for the API is 8081, and the default for GRPC is 50051. Either the API or the GRPC server can be disabled on any given Netmaker instance, allowing you to deploy two different servers for managing the API (which is largely for the admin's use) and GRPC (which is largely for the nodes' use). Most server settings are configurable via a config file, or by environment variables (which take precedence). If the server finds neither of these, it sets sensible defaults, including things like the server's reachable IP, ports, and which "modes" to run in. These modes include client mode and dns mode. Either of these can be disabled but are enabled by default. Client mode allows you to treat the Netmaker host machine (operating system) as a network Node, installing the netclient and controlling the host network. DNS mode has the server write config settings for CoreDNS, a separate component and nameserver, which picks up the config settings to manage node DNS. -The Netmaker server interacts with either sqlit (default) or rqlite, a distributed version of sqlite, as its database. This DB holds information about nodes, networks, users, and other important data. This data is configuration data. For the most part, Netmaker serves configuration data to Nodes, telling them how they should configure themselves. The Netclient is the agent that actually does that configuration. +The Netmaker server interacts with either sqlite (default), postgres, or rqlite, a distributed version of sqlite, as its database. This DB holds information about nodes, networks, users, and other important data. This data is configuration data. For the most part, Netmaker serves configuration data to Nodes, telling them how they should configure themselves. The Netclient is the agent that actually does that configuration. Netclient @@ -104,10 +104,10 @@ If running in daemon mode, on a periodic basis (systemd timer), the netclient pe The check in process is what allows Netmaker to create dynamic mesh networks. As nodes are added to, removed from, and modified on the network, other nodes are notified, and make appropriate changes. -sqlite and rqlite ---------------------- +Datavase (sqlite, rqlite, postgres) +------------------------------------- -As of v0.8, Netmaker uses sqlite by default as a database. It can also use rqlite, a distributed (RAFT consensus) databaseand. Netmaker interacts with this database to store and retrieve information about nodes, networks, and users. +As of v0.8, Netmaker uses sqlite by default as a database. It can also use PostgreSQL, or rqlite, a distributed (RAFT consensus) databaseand. Netmaker interacts with this database to store and retrieve information about nodes, networks, and users. Additional database support (besides sqlite and rqlite) is very easy to implement for special use cases. Netmaker uses simple key value lookups to run the networks, and the database was designed to be extensible, so support for key-value stores and other SQL-based databases can be achieved by changing a single file. diff --git a/docs/_build/html/_sources/server-installation.rst.txt b/docs/_build/html/_sources/server-installation.rst.txt index 539a0657..ae3bbde8 100644 --- a/docs/_build/html/_sources/server-installation.rst.txt +++ b/docs/_build/html/_sources/server-installation.rst.txt @@ -9,7 +9,7 @@ System Compatibility Netmaker will require elevated privileges to perform network operations. Netmaker has similar limitations to :doc:`netclient <./client-installation>` (client networking agent). -Typically, Netmaker is run inside of containers (Docker). To run a non-docker installation, you must run the Netmaker binary, CoreDNS binary, rqlite, and a web server directly on the host. Each of these components have their own individual requirements. +Typically, Netmaker is run inside of containers (Docker). To run a non-docker installation, you must run the Netmaker binary, CoreDNS binary, database, and a web server directly on the host. Each of these components have their own individual requirements. The quick install guide is recommended for first-time installs. @@ -101,13 +101,38 @@ DNS_MODE: DATABASE: **Default:** "sqlite" - **Description:** Specify db type to connect with. Currently, options include "sqlite" and "rqlite". + **Description:** Specify db type to connect with. Currently, options include "sqlite", "rqlite", and "postgres". -SQL_CONN: +SQL_CONN: **Default:** "http://" **Description:** Specify the necessary string to connect with your local or remote sql database. +SQL_HOST: + **Default:** "localhost" + + **Description:** Host where postgres is running. + +SQL_PORT: + **Default:** "5432" + + **Description:** port postgres is running. + +SQL_DB: + **Default:** "netmaker" + + **Description:** DB to use in postgres. + +SQL_USER: + **Default:** "postgres" + + **Description:** User for posgres. + +SQL_PASS: + **Default:** "nopass" + + **Description:** Password for postgres. + CLIENT_MODE: **Default:** "on" @@ -344,18 +369,130 @@ The following file configures Netmaker as a subdomain. This config is an adaptio .. _HAInstall: -Highly Available Installation -=============================== + + +Highly Available Installation (Kubernetes) +================================================== + +Netmaker comes with a Helm chart to deploy with High Availability on Kubernetes. + +Requirements +--------------- + +To run HA Netmaker on Kubernetes, your cluster must have the following: +- RWO and RWX Storage Classes (RWX is only required if running Netmaker with DNS Management enabled). +- An Ingress Controller and valid TLS certificates +- This chart can currently generate ingress for Nginx or Traefik Ingress with LetsEncrypt + Cert Manager +- If LetsEncrypt and CertManager are not deployed, you must manually configure certificates for your ingress + +Furthermore, the chart will by default install and use a postgresql cluster as its datastore. + +Recommended Settings: +---------------------- +A minimal HA install of Netmaker can be run with the following command: +`helm install netmaker --generate-name --set baseDomain=nm.example.com` +This install has some notable exceptions: +- Ingress **must** be manually configured post-install (need to create valid Ingress with TLS) +- Server will use "userspace" WireGuard, which is slower than kernel WG +- DNS will be disabled + +Example Installations: +------------------------ +An annotated install command: + +.. code-block:: + + helm install ./netmaker --generate-name \ # generate a random id for the deploy + --set baseDomain=nm.example.com \ # the base wildcard domain to use for the netmaker api/dashboard/grpc ingress + --set replicas=3 \ # number of server replicas to deploy (3 by default) + --set ingress.enabled=true \ # deploy ingress automatically (requires nginx or traefik and cert-manager + letsencrypt) + --set ingress.className=nginx \ # ingress class to use + --set ingress.tls.issuerName=letsencrypt-prod \ # LetsEncrypt certificate issuer to use + --set dns.enabled=true \ # deploy and enable private DNS management with CoreDNS + --set dns.clusterIP=10.245.75.75 --set dns.RWX.storageClassName=nfs \ # required fields for DNS + --set postgresql-ha.postgresql.replicaCount=2 \ # number of DB replicas to deploy (default 2) + + +The below command will install netmaker with two server replicas, a coredns server, and ingress with routes of api.nm.example.com, grpc.nm.example.com, and dashboard.nm.example.com. CoreDNS will be reachable at 10.245.75.75, and will use NFS to share a volume with Netmaker (to configure dns entries). + +.. code-block:: + + helm install ./netmaker --generate-name --set baseDomain=nm.example.com \ + --set replicas=2 --set ingress.enabled=true --set dns.enabled=true \ + --set dns.clusterIP=10.245.75.75 --set dns.RWX.storageClassName=nfs \ + --set ingress.className=nginx + +The below command will install netmaker with three server replicas (the default), **no coredns**, and ingress with routes of api.netmaker.example.com, grpc.netmaker.example.com, and dashboard.netmaker.example.com. There will be one UI replica instead of two, and one database instance instead of two. Traefik will look for a ClusterIssuer named "le-prod-2" to get valid certificates for the ingress. + +.. code-block:: + + helm3 --kubeconfig /root/k3s.yaml install ./netmaker --generate-name \ + --set baseDomain=netmaker.example.com --set postgresql-ha.postgresql.replicaCount=1 \ + --set ui.replicas=1 --set ingress.enabled=true \ + --set ingress.tls.issuerName=le-prod-2 --set ingress.className=traefik + +Below, we discuss the considerations for Ingress, Kernel WireGuard, and DNS. + +Ingress +---------- +To run HA Netmaker, you must have ingress installed and enabled on your cluster with valid TLS certificates (not self-signed). If you are running Nginx as your Ingress Controller and LetsEncrypt for TLS certificate management, you can run the helm install with the following settings: + +- `--set ingress.enabled=true` +- `--set ingress.annotations.cert-manager.io/cluster-issuer=` + +If you are not using Nginx or Traefik and LetsEncrypt, we recommend leaving ingress.enabled=false (default), and then manually creating the ingress objects post-install. You will need three ingress objects with TLS: + +- `dashboard.` +- `api.` +- `grpc.` + +If deploying manually, the gRPC ingress object requires special considerations. Look up the proper way to route grpc with your ingress controller. For instance, on Traefik, an IngressRouteTCP object is required. + +There are some example ingress objects in the kube/example folder. + +Kernel WireGuard +------------------ +If you have control of the Kubernetes worker node servers, we recommend **first** installing WireGuard on the hosts, and then installing HA Netmaker in Kernel mode. By default, Netmaker will install with userspace WireGuard (wireguard-go) for maximum compatibility, and to avoid needing permissions at the host level. If you have installed WireGuard on your hosts, you should install Netmaker's helm chart with the following option: + +- `--set wireguard.kernel=true` + +DNS +---------- +By Default, the helm chart will deploy without DNS enabled. To enable DNS, specify with: + +- `--set dns.enabled=true` + +This will require specifying a RWX storage class, e.g.: + +- `--set dns.RWX.storageClassName=nfs` + +This will also require specifying a service address for DNS. Choose a valid ipv4 address from the service IP CIDR for your cluster, e.g.: + +- `--set dns.clusterIP=10.245.69.69` + +**This address will only be reachable from hosts that have access to the cluster service CIDR.** It is only designed for use cases related to k8s. If you want a more general-use Netmaker server on Kubernetes for use cases outside of k8s, you will need to do one of the following: +- bind the CoreDNS service to port 53 on one of your worker nodes and set the COREDNS_ADDRESS equal to the public IP of the worker node +- Create a private Network with Netmaker and set the COREDNS_ADDRESS equal to the private address of the host running CoreDNS. For this, CoreDNS will need a node selector and will ideally run on the same host as one of the Netmaker server instances. + +Values +--------- + +To view all options for the chart, please visit the README in the code repo `here `_ . + +Highly Available Installation (VMs/Bare Metal) +================================================== For an enterprise Netmaker installation, you will need a server that is highly available, to ensure redundant WireGuard routing when any server goes down. To do this, you will need: 1. A load balancer 2. 3+ Netmaker server instances -3. rqlite as the backing database +3. rqlite or PostgreSQL as the backing database These documents outline general HA installation guidelines. Netmaker is highly customizable to meet a wide range of enterprise environments. If you would like support with an enterprise-grade Netmaker installation, you can `schedule a consultation here `_ . -The main consideration here is how to configure rqlite. Most other settings and procedures match the standardized way of making applications HA: Load balancing to multiple instances, and sharing a DB. In our case, the DB (rqlite) is distributed, making HA data more easily achievable. +The main consideration for this document is how to configure rqlite. Most other settings and procedures match the standardized way of making applications HA: Load balancing to multiple instances, and sharing a DB. In our case, the DB (rqlite) is distributed, making HA data more easily achievable. + +If using PostgreSQL, follow their documentation for `installing in HA mode `_ and skip step #2. 1. Load Balancer Setup ------------------------ @@ -398,7 +535,19 @@ Once rqlite instances have been configured, the Netmaker servers can be deployed 3. Netmaker Setup ------------------ -Netmaker will be started on each node with default settings, except with DATABASE=rqlite and SQL_CONN set appropriately to reach the local rqlite instance. Rqlite will maintain consistency with each Netmaker backend. +Netmaker will be started on each node with default settings, except with DATABASE=rqlite (or DATABASE=postgress) and SQL_CONN set appropriately to reach the local rqlite instance. Rqlite will maintain consistency with each Netmaker backend. + +If deploying HA with PostgreSQL, you will connect with the following settings: + +.. code-block:: + + SQL_HOST = + SQL_PORT = + SQL_DB = + SQL_USER = + SQL_PASS = + DATABASE = postgres + 4. Other Considerations ------------------------ @@ -408,5 +557,3 @@ This is enough to get a functioning HA installation of Netmaker. However, you ma - - diff --git a/docs/_build/html/_static/documentation_options.js b/docs/_build/html/_static/documentation_options.js index 5198796d..492f0699 100644 --- a/docs/_build/html/_static/documentation_options.js +++ b/docs/_build/html/_static/documentation_options.js @@ -1,6 +1,6 @@ var DOCUMENTATION_OPTIONS = { URL_ROOT: document.getElementById("documentation_options").getAttribute('data-url_root'), - VERSION: '0.8.2', + VERSION: '0.8.3', LANGUAGE: 'None', COLLAPSE_INDEX: false, BUILDER: 'html', diff --git a/docs/_build/html/about.html b/docs/_build/html/about.html index a0ad3084..f9d61e41 100644 --- a/docs/_build/html/about.html +++ b/docs/_build/html/about.html @@ -46,7 +46,7 @@ - About — Netmaker 0.8.2 documentation + About — Netmaker 0.8.3 documentation @@ -81,7 +81,7 @@