Expand single node onprem docs

Signed-off-by: davidmirror-ops <david [email protected]>

Author: davidmirror-ops

docs/on-premises/single-node/001-configure-single-node-k8s.md

@@ -3,16 +3,16 @@
 By following this tutorial, you will deploy a Kubernetes cluster on a single VM.   
 Feel free to skip this section if you already have a working Kubernetes environment.
 
-> Do you plan to add more nodes/physical machines to your K8s environment? Then head over to the multi-node guide and start from there. **This guide doesn't currently provide a migration path from single-node to multi-node deployments**.
-
 ## Prerequisites
 
 - A Linux or macOS machine
 - [`kubectl`](https://kubernetes.io/docs/tasks/tools/) to interact with the K8s cluster
-- [`multipass`](https://multipass.run/install) to manage VMs.
+- [`multipass`](https://multipass.run/install) if you plan to run K8s on VMs.
 
 ## Configuration process
-> If you plan to run Flyte directly on bare-metal servers, just follow the microk8s [installation instructions](https://microk8s.io/docs/getting-started) and skip to step 3
+> If you plan to run Flyte directly on Linux bare-metal servers, just follow the microk8s [installation instructions](https://microk8s.io/docs/getting-started) and skip to step 4:
+
+
 1. Create the VM where you'll run Kubernetes:
 ``` bash
 multipass launch --name k8smaster --memory 4G --disk 40G
@@ -51,7 +51,11 @@ sudo usermod -a -G microk8s ubuntu
 ``` bash
 cat /var/snap/microk8s/current/credentials/client.config
 ```
-7. On a new terminal tab, open your kubectl config file (typically located at `$HOME/.kube/config`) and the the config for your new K8s instance:
+7. Exit the shell session
+```bash
+exit
+```
+8. On a new terminal tab, open your kubectl config file (typically located at `$HOME/.kube/config`) and the the config for your new K8s instance:
 
 - a. Add a new entry to the `clusters` section including the `certificate-authority-data` and `server`
 - b. Replace the `server` IP with the IP for your machine/VM 
@@ -88,7 +92,7 @@ Example output:
 ```bash
 Switched to context "microk8s".
 ```
-7. Test your connection:
+9. Test your connection:
 ```bash
 kubectl get nodes
 ```

docs/on-premises/single-node/002-single-node-onprem-install.md

@@ -2,26 +2,26 @@
 
 This section assumes that you have a working Kubernetes environment.
 
-You'll be configuring the external platform dependencies of Flyte:
+The external platform dependencies of Flyte are:
 
-- An S3-compliant object storage used for task metadata and to retrieve data to be processed by workflows.
+- An S3-compatible object storage used for task metadata and to retrieve data to be processed by workflows.
 - A relational database.
 
 In this tutorial, we'll use Minio with a single bucket as the object storage provider and Postgres as the relational database. These two elements are configured to retain data even if the corresponding Pod is deleted.
 
-> NOTE: this guide is intended for single-node K8s installations and doesn't provide migration instructions to switch to multi-node afterwards. If you plan to use multiple servers to run Flyte, go to the multi-node section and start from there.
+> NOTE: if you plan to run Flyte on a K8s environment with multiple nodes, the instructions in these section should be generally useful regardless of number of K8s worker and controlplane nodes. Also, to provide shared storage for your environment make sure to check out the supported `minio` [topologies](https://min.io/docs/minio/linux/operations/installation.html) and [supported backend storage systems](https://blog.min.io/best-practices-minio-virtualized/). 
 
 1. Prepare your K8s cluster to provision Persistent Volumes:
 ```bash
 microk8s enable hostpath-storage
 ```
 > NOTE: for other K8s distributions, verify the provisioner available for local storage, typically associated with a StorageClass (`kubectl get storageclass`). If there isn't any, consider using [this implementation](https://github.com/rimusz/hostpath-provisioner) of the hostpath provisioner. To learn more about how Kubernetes handles data persistency, go to [the docs](https://kubernetes.io/docs/concepts/storage/persistent-volumes/).
 
-> PersistentVolumeClaims created by the hostpath storage provisioner are bound to the local node, so **it is impossible to move them to a different node**.
+> PersistentVolumeClaims created by the hostpath storage provisioner are bound to the local node, so **it is impossible to move them to a different node**. For multi-node K8s environments, use the StorageClass surfaced by your shared storage backend.
 
-2. Download the manifest that will provision the Flyte dependencies:
+2. Download the manifest that will deploy the Flyte dependencies:
 ``` bash
-curl -sl https://raw.githubusercontent.com/davidmirror-ops/flyte-the-hard-way/main/docs/on-premises/single-node/manifests/local-flyte-resources.yaml > local-flyte-resources.yaml
+curl -sl https://raw.githubusercontent.com/davidmirror-ops/flyte-the-hard-way/main/docs/on-premises/single-node/manifests/onprem-flyte-dependencies.yaml > onprem-flyte-dependencies.yaml
 ```
 3. Make sure to adjust sensitive values like `MINIO_ROOT_PASSWORD` and `POSTGRES_PASSWORD` before submitting the manifest:
 ``` bash
@@ -47,10 +47,25 @@ NAME                        READY   STATUS    RESTARTS   AGE
 postgres-6f6bb8bff7-9sjnj   1/1     Running   0          75s
 minio-7d795cd5d8-dlk54      1/1     Running   0          75s
 ```
-5. In order to avoid saving the DB password in plain text to the `values` file, we leverage a recent addition to the `flyte-binary` chart that allows to consume pre-created secrets:
+5.  Add the Flyte Helm repo:
+```bash
+helm repo add flyteorg https://flyteorg.github.io/flyte
+``` 
+At this point the dependencies required by Flyte are ready. You can now choose which form factor to deploy:
+
+- Single binary: all [Flyte components](https://docs.flyte.org/en/latest/concepts/architecture.html) (`flyteadmin`,`flytepropeller`, `flyteconsole`, etc) packaged into a single Pod. This is useful for environments with limited resources and a need for quick setup.
+
+- Core: all components as standalone Pods, and potentially different number of replicas. This is required for multi-K8s-cluster environments.
+
+You can only have one of these form factors on a single K8s cluster. 
+The following sections guide you through the setup process for each.
+
+## Install single binary
+
+1. In order to avoid saving the DB password in plain text to the `values` file, we leverage a feature of the `flyte-binary` chart that allows to consume pre-created secrets:
 
 - Create an external secret containing the DB password:
->Replace `<POSTGRES_PASSWORD>` with what you configured on step 3 
+
 ```yaml
 cat <<EOF >local-secret.yaml      
 apiVersion: v1
@@ -63,7 +78,7 @@ stringData:
   202-database-secrets.yaml: |
     database:
       postgres:
-        password: <POSTGRES_PASSWORD> 
+        password: "postgres" 
 EOF
 ```
 - Submit the manifest:
@@ -87,17 +102,14 @@ Data
 ====
 202-database-secrets.yaml:  48 bytes
 ```
-6.  Download the values file:
+2.  Download the values file:
 ```bash
-curl -sL https://raw.githubusercontent.com/davidmirror-ops/flyte-the-hard-way/main/docs/on-premises/single-node/manifests/local-values.yaml > local-values.yaml
+curl -sL https://raw.githubusercontent.com/davidmirror-ops/flyte-the-hard-way/main/docs/on-premises/single-node/manifests/onprem-flyte-binary/values.yaml > onprem-flyte-binary-values.yaml
 
-7. Add the Flyte Helm repo:
-```bash
-helm repo add flyteorg https://flyteorg.github.io/flyte
-``` 
-8. Install Flyte: 
+
+3. Install Flyte: 
 ```bash
-helm install flyte-binary flyteorg/flyte-binary  --values local-values.yaml -n flyte
+helm install flyte-binary flyteorg/flyte-binary  --values onprem-flyte-binary-values.yaml -n flyte
 ```
 Example output:
 
@@ -110,7 +122,7 @@ REVISION: 1
 TEST SUITE: None
 ```
 
-9. Verify the `flyte-binary` Pod is in `Running` state:
+4. Verify the `flyte-binary` Pod is in `Running` state:
 ```bash
 kubectl get pods -n flyte
 ```
@@ -121,8 +133,49 @@ postgres-6f6bb8bff7-9sjnj       1/1     Running   0          30m
 minio-7d795cd5d8-dlk54          1/1     Running   0          30m
 flyte-binary-58d779b9d8-z2hzs   1/1     Running   0          23s
 ```
-10. Configure your Flyte config file for local connections (typically located at `$HOME/.flyte/config.yaml`):
-> If you haven't done so, install `flytectl` so the config file is created. Check out the instructions [here](https://docs.flyte.org/en/latest/flytectl_overview.html#installation)
+Congratulations!     
+You have setup Flyte single binary. Now, learn [how to connect to your Flyte instance](#connecting-to-flyte)
+## Install Flyte core
+
+> The following configuration requests about 3 CPU cores and 3 GB of memory for the different Flyte components without accounting for workflow executions. 
+
+1. Download the values file
+```bash
+curl -sL https://raw.githubusercontent.com/davidmirror-ops/flyte-the-hard-way/main/docs/on-premises/single-node/manifests/onprem-flyte-core-values.yaml > onprem-flyte-core-values.yaml
+```
+2. Review the values file if you need to change anything in the `userSettings` section.
+3. Install the `flyte-core` Helm chart:
+```bash
+helm install flyte-core flyteorg/flyte-core --values onprem-flyte-core-values.yaml -n flyte 
+```
+Example output
+```bash
+NAME: flyte-core
+LAST DEPLOYED: Fri Mar  8 11:09:10 2024
+NAMESPACE: flyte
+STATUS: deployed
+REVISION: 1
+TEST SUITE: None
+```
+4. Wait for the Pods to come up:
+```bash
+kubectl get po -n flyte
+
+NAME                                 READY   STATUS    RESTARTS     AGE
+postgres-d56745848-7dkhl             1/1     Running   4 (3d ago)   16d
+minio-758b9b5d86-s2tnl               1/1     Running   3 (3d ago)   7d21h
+syncresources-7cdd9f468c-kzndm       1/1     Running   0            58s
+flyteconsole-856d9c594b-qmjv8        1/1     Running   0            58s
+datacatalog-bddddcc47-lnmhk          1/1     Running   0            58s
+flytepropeller-6dbb9f8cb5-w7wsn      1/1     Running   0            58s
+flyte-pod-webhook-867c44bdd4-thrth   1/1     Running   0            58s
+flyteadmin-66cb66764d-j7cx2          1/1     Running   0            58s
+flytescheduler-579b6cb648-jmmgm      1/1     Running   0            58s
+```
+## Connecting to Flyte
+
+1. Configure your Flyte config file for local connections (typically located at `$HOME/.flyte/config.yaml`):
+> If you haven't done so, install `flytectl` and run `flytectl config init` so the config file is created. Check out the instructions [here](https://docs.flyte.org/en/latest/flytectl_overview.html#installation)
 
 ```yaml
 admin:
@@ -134,7 +187,7 @@ logger:
   show-source: true
   level: 6
 ```
-11. Create a local DNS entry so the Flyte CLI connects to the `minio` service using its FQDN:
+2. Create a local DNS entry so the Flyte CLI connects to the `minio` service using its FQDN:
 
 - In an OSX environment:
 ```bash
@@ -149,9 +202,9 @@ sudo vi /etc/hosts
 ##
 127.0.0.1       minio.flyte.svc.cluster.local 
 ```
-12. In three different terminal windows, start three port-forwarding sessions:
-
+3. In three different terminal windows, start three port-forwarding sessions. As each Helm chart uses different Services and ports, the commands are different:
 
+### Single binary
 ```bash
 kubectl -n flyte port-forward service/minio 9000:9000
 ```
@@ -161,9 +214,19 @@ kubectl -n flyte port-forward service/flyte-binary-grpc 8089:8089
 ```bash
 kubectl -n flyte port-forward service/flyte-binary-http 8088:8088
 ```
+### Core
+```bash
+kubectl -n flyte port-forward service/minio 9000:9000
+```
+```bash
+kubectl -n flyte port-forward service/flyteadmin 8089:81
+```
+```bash
+kubectl -n flyte port-forward service/flyteconsole 8088:80
+```
+## Using Flyte
 
-
-13. Save the following "hello world" workflow definition:
+4. Save the following "hello world" workflow definition:
 
 ```bash
 cat <<<EOF >hello_world.py
@@ -179,7 +242,7 @@ if __name__ == "__main__":
     print(f"Running my_wf() {my_wf()}")
 EOF
 ```
-14. Execute the workflow on the Flyte cluster:
+5. Execute the workflow on the Flyte cluster:
 ```bash
 pyflyte run --remote hello_world.py my_wf
 ```
@@ -188,7 +251,7 @@ Example output:
 Go to http://localhost:8089/console/projects/flytesnacks/domains/development/executions/f0c602e28c5c84d46b22 to see execution in the console.
 ```
 > NOTE: different to what the CLI output indicates, use the `8088` port instead of 8089 to connect to the UI
-15. Go to the Flyte console and monitor the execution:
+6. Go to the Flyte console and monitor the execution:
 ![](../../images/local-flyte-ui.png)
 
 ---

docs/on-premises/single-node/003-ingress-tls.md

@@ -1,6 +1,6 @@
 # Add Ingress and Transport Layer Security (TLS)
 
-To avoid the need to open port-forward sessions and being able to connect to the Flyte instance using a single IP/FQDN, this guide will help you add Ingress networking to your deployment. Also, to create a secure communication tunnel between the client and the Flyte instance, you'll configure TLS.
+To avoid the need to open port-forward sessions to connect to the Flyte instance using a single IP/FQDN, this guide will help you add and [Ingress](https://kubernetes.io/docs/concepts/services-networking/ingress/) resource to your deployment. Also, to create a secure communication tunnel between the client and the Flyte instance, you'll configure TLS.
 
 ## Add Ingress networking
 
@@ -12,6 +12,7 @@ microks enable ingress
 >NOTE: for other distributions, check out the NGINX [installation instructions](https://docs.nginx.com/nginx-ingress-controller/installation/installing-nic/installation-with-helm/)
 
 >This guide uses NGINX as it supports the annotations that Flyte uses. 
+
 2. Verify the status of the NGINX Ingress controller pod:
 ```bash
 kubectl get pod -n ingress 
@@ -21,32 +22,64 @@ Example output:
 NAME                                      READY   STATUS    RESTARTS   AGE
 nginx-ingress-microk8s-controller-6tdpg   1/1     Running   0          50m
 ```
-3. Add the following block to your `local-values.yaml` file:
+
+
+3. Add the following block to values file, depending on the Helm chart you installed:
+
+## Single binary
 ```yaml
 ingress:
  create: true
  ingressClassName: nginx
  httpAnnotations:
-  nginx.ingress.kubernetes.io/app-root: /console
+   nginx.ingress.kubernetes.io/app-root: /console
  grpcAnnotations:
-  nginx.ingress.kubernetes.io/backend-protocol: GRPC
+   nginx.ingress.kubernetes.io/backend-protocol: GRPC
  host: flyteonprem.fthw.local #Replace this with the domain name you plan to use to connect to Flyte
 ```
+## Core
+```yaml
+common:
+  ingress:
+    create: true
+    ingressClassName: nginx
+    httpAnnotations:
+      nginx.ingress.kubernetes.io/app-root: /console
+    grpcAnnotations:
+      nginx.ingress.kubernetes.io/backend-protocol: GRPC
+    host: flyteonprem.fthw.local #Replace this with the domain name you plan to use to connect to Flyte.
+  ```
+
 4. Save your changes.
-5. Upgrade the Helm deployment:
+5. Upgrade the Helm release:
+
+## Single binary
 ```bash
-helm upgrade flyte-binary flyteorg/flyte-binary  --values local-values.yaml -n flyte
+helm upgrade flyte-binary flyteorg/flyte-binary  --values onprem-flyte-binary-values.yaml -n flyte
+```
+
+## Core
+ ```bash
+helm upgrade flyte-core flyteorg/flyte-core  --values onprem-flyte-core-values.yaml -n flyte
 ```
 6. Verify the status of your Ingress resource:
 ```bash
 kubectl get ingress -n flyte
 ```
 Example output:
+
+## Single binary
 ```bash
 NAME                CLASS   HOSTS                    ADDRESS     PORTS   AGE
 flyte-binary-http   nginx   flyteonprem.fthw.local   127.0.0.1   80      168m
 flyte-binary-grpc   nginx   flyteonprem.fthw.local   127.0.0.1   80      168m
 ```
+## Core
+```bash
+NAME                CLASS   HOSTS                    ADDRESS     PORTS   AGE
+flyte-core   nginx   flyteonprem.fthw.local   127.0.0.1   80      168m
+```
+
 7. Create a new A register for your `HOST` in your DNS server pointing to the IP address of your server. In the absence of a DNS server, edit your local file adding a new entry:
 
 - In an OSX environment:
@@ -86,29 +119,38 @@ openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout ${KEY_FILE} -out ${C
 ``` bash
 kubectl create secret tls ${CERT_NAME} --key ${KEY_FILE} --cert ${CERT_FILE} -n flyte
 ```
-4. Add a `tls` section to the ingress definition in you `local-values.yaml` file:
+4. Add a `tls` section to the ingress definition in you `values` file:
 ```yaml
 ingress:
   tls:
-   - hosts:
-       - "flyteonprem.fthw.local"#replace with your hostname
+    enabled: true
+    - hosts:
+      - "flyteonprem.fthw.local"#replace with your hostname
      secretName: flytetls
-  create: true
-  ingressClassName: nginx
-  httpAnnotations:
-   nginx.ingress.kubernetes.io/app-root: /console
-  grpcAnnotations:
-   nginx.ingress.kubernetes.io/backend-protocol: GRPC
-  host: flyteonprem.fthw.local
+  ...
 ```
 5. Upgrade your Helm release
+## Single binary
 ```bash
-helm upgrade flyte-binary flyteorg/flyte-binary --values local-values.yaml -n flyte
+helm upgrade flyte-binary flyteorg/flyte-binary  --values onprem-flyte-binary-values.yaml -n flyte
 ```
-6. Verify that your Ingress resource now includes TLS:
+
+## Core
+ ```bash
+helm upgrade flyte-core flyteorg/flyte-core  --values onprem-flyte-core-values.yaml -n flyte
+```
+6. Verify that your Ingress configuration now includes TLS:
+
+## Single binary
 ```bash
 kubectl  describe ingress flyte-binary-grpc  -n flyte                
 ```
+
+## Core
+```bash
+kubectl describe ingress flyte-core  -n flyte                
+```
+
 The output should include a line similar to:
 ```yaml
 ...