docs/self-host: add k8s requirements & other fixes

PostHog · Oct 13, 2021 · 2fdfe23 · 2fdfe23
1 parent 4693c2e
commit 2fdfe23
Show file tree

Hide file tree

Showing 15 changed files with 119 additions and 113 deletions.
diff --git a/contents/docs/self-host/deploy/aws.mdx b/contents/docs/self-host/deploy/aws.mdx
@@ -7,12 +7,17 @@ tags:
     - aws
 ---
 
+import ClusterRequirementsSnippet from './snippets/cluster-requirements'
 import InstallingSnippet from './snippets/installing'
 import UpgradingSnippet from './snippets/upgrading'
 import UninstallingSnippet from './snippets/uninstalling'
 import TryUnsecureSnippet from './snippets/tryunsecure'
 
-First, we need to set up a Kubernetes Cluster, see [Setup EKS - eksctl](https://docs.aws.amazon.com/eks/latest/userguide/getting-started-eksctl.html). Follow the "Managed nodes - Linux" guide. The default nodes (2x m5.large) work well for running PostHog.
+First, we need to set up a Kubernetes cluster (see the official AWS [documentation](https://docs.aws.amazon.com/eks/latest/userguide/getting-started-eksctl.html) for more info).
+
+<ClusterRequirementsSnippet />
+
+## Chart configuration
 
 Here's the minimal required `values.yaml` that we'll be using later. You can find an overview of the parameters that can be configured during installation under [chart configuration](/docs/self-host/deploy/configuration).
 ```yaml

diff --git a/contents/docs/self-host/deploy/azure.mdx b/contents/docs/self-host/deploy/azure.mdx
@@ -3,14 +3,21 @@ title: Deploying to Azure
 sidebarTitle: Azure
 sidebar: Docs
 showTitle: true
+tags:
+    - azure
 ---
 
+import ClusterRequirementsSnippet from './snippets/cluster-requirements'
 import InstallingSnippet from './snippets/installing'
 import UpgradingSnippet from './snippets/upgrading'
 import UninstallingSnippet from './snippets/uninstalling'
 import TryUnsecureSnippet from './snippets/tryunsecure'
 
-First, we need to set up a Kubernetes Cluster, see [Creation with Azure portal](https://docs.microsoft.com/en-us/azure/aks/kubernetes-walkthrough-portal#create-an-aks-cluster). Make sure your cluster has enough resources to run PostHog (total minimum 4 vcpu & 8GiB RAM).
+First, we need to set up a Kubernetes cluster (see the official Azure [documentation](https://docs.microsoft.com/en-us/azure/aks/kubernetes-walkthrough-portal#create-an-aks-cluster) for more info).
+
+<ClusterRequirementsSnippet />
+
+## Chart configuration
 
 Here's the minimal required `values.yaml` that we'll be using later. You can find an overview of the parameters that can be configured during installation under [chart configuration](/docs/self-host/deploy/configuration).
 ```yaml
@@ -30,7 +37,7 @@ kafka:
 
 <InstallingSnippet />
 
-    
+
 ### Lookup external IP
 
 ```console

diff --git a/contents/docs/self-host/deploy/digital-ocean.mdx b/contents/docs/self-host/deploy/digital-ocean.mdx
@@ -3,89 +3,55 @@ title: Deploying to Digital Ocean
 sidebarTitle: Digital Ocean
 sidebar: Docs
 showTitle: true
+tags:
+    - do
+    - digitalocean
 ---
 
-import DOIPAddressSnippet from './snippets/do-ip-address'
+import GetUrlSnippet from './snippets/get-url'
+import GetIPAddressSnippet from './snippets/get-ip-address'
+import PostInstallSnippet from './snippets/post-install'
+import ClusterRequirementsSnippet from './snippets/cluster-requirements'
 import InstallingSnippet from './snippets/installing'
 import UpgradingSnippet from './snippets/upgrading'
 import UninstallingSnippet from './snippets/uninstalling'
 import TryUnsecureSnippet from './snippets/tryunsecure'
 
-## Why Digital Ocean
+[Digital Ocean](https://digitalocean.com) is one of the most well-established Cloud Providers. Compared to AWS, where the amount of options and configuration can be overwhelming, Digital Ocean is generally simpler to use and faster to get running.
 
-[Digital Ocean](https://digitalocean.com) is one of the most well-established Cloud Providers. Compared to AWS, where the amount of options and configuration can be overwhelming, Digital Ocean is generally simpler to use and faster to get running. 
-<br />
+The first thing you'll need is a get a Digital Ocean account. You can click on the badge below to get US$100 in credit over 60 days (i.e. run PostHog for free for ~2 months).
+
+You can then either follow the [1-click install](#1-click-install) or the [manual install](#manual-install).
 
-The first thing you'll need is a get a Digital Ocean account. You can click on the badge below to get $100 in credit over 60 days (i.e. run PostHog for free for 2 months).
 <br />
 
 <center>
   <a href="https://www.digitalocean.com/?refcode=6a26a2c395b0&utm_campaign=Referral_Invite&utm_medium=Referral_Program&utm_source=badge" title="DigitalOcean Referral">
     <img alt="DigitalOcean Referral Badge" src="https://web-platforms.sfo2.cdn.digitaloceanspaces.com/WWW/Badge%201.svg" />
   </a>
 </center>
-<br />
 
-You can then either follow the [1-click install](#1-click-install) or the [manual install](#manual-install).
+<br />
 
 ## 1-click install
+There is a [1-click install](https://marketplace.digitalocean.com/apps/posthog-1) option to deploy PostHog via the [DigitalOcean Marketplace](https://marketplace.digitalocean.com/).
+The DigitalOcean UI will ask you if you want to install PostHog on an already provisioned Kubernetes cluster or if you want to create a new one.
 
-### Marketplace UI
-There is a [1-click option to deploy PostHog](https://marketplace.digitalocean.com/apps/posthog-1) on DigitalOcean Marketplace UI.
-
-If you don't already have a cluster setup you should follow the getting started guide to setup kubeconfig. The minimal suggested cluster capacity is using **two of the smallest production nodes**.
-
-You will also need to secure your PostHog deployment.
-
-### CLI
-
-Alternatively use [doctl](https://github.com/digitalocean/doctl) which also sets up kubeconfig for you.
-
-```console
-doctl kubernetes cluster create posthog-cluster --count=2 --size="s-2vcpu-4gb" --region=sfo3 --1-clicks=posthog
-```
-
-### Configuring kubectl access
-
-To monitor, debug, and maintain your PostHog instance, you should connect to your cluster using `kubectl`.
-
-To do so, you should follow [these instructions](https://docs.digitalocean.com/products/kubernetes/how-to/connect-to-cluster/).
-
-The simplest way to do this is with the following command:
-
-```shell
-doctl kubernetes cluster kubeconfig save your_posthog_cluster_name
-```
-
-### Accessing PostHog
-
-After deploying PostHog to your Kubernetes cluster you can get the IP to connect to one of two ways:
-
-<DOIPAddressSnippet />
-
-Congrats, you now have a working PostHog instance!
-
-You can now [integrate your development applications](/docs/integrate) with your PostHog deployment for testing purposes.
-
-> Note: You will only be able to test web apps on HTTP such as those running on `localhost`.
-
-But there's one more important step before using PostHog in production: securing your instance. See the next section for details.
+Once the setup is completed, remember to [configure your `kubectl` access](https://docs.digitalocean.com/products/kubernetes/how-to/connect-to-cluster/) and [secure your 1-click installation](#securing-your-1-click-install).
 
 ### Securing your 1-click install
 
-It's [not yet possible to provide parameters to DigitalOcean](https://github.com/digitalocean/marketplace-kubernetes/issues/230), so we need a post-install step to enable TLS.
-
-> In order to do this you will need [kubectl](https://kubernetes.io/docs/tasks/tools/) and [helm](https://helm.sh/) installed.
+It's unfortunately [not yet possible to provide parameters to DigitalOcean](https://github.com/digitalocean/marketplace-kubernetes/issues/230), so we need a post-install step to enable TLS.
 
-#### 1. Lookup external IP
+> In order to do this you will need [kubectl](https://kubernetes.io/docs/tasks/tools/) and [Helm](https://helm.sh/) installed.
 
-As above, you can get the IP to connect to one of two ways:
+#### 1. Lookup the IP address of the installation
 
-<DOIPAddressSnippet />
+<GetIPAddressSnippet />
 
 #### 2. Set up DNS
 
-Create an `A` record from your desired hostname to the external IP.
+Create an `A` record from your desired hostname to the external IP we got above.
 
 #### 3. Update PostHog
 
@@ -101,21 +67,27 @@ certManager:
   enabled: true
 ```
 
-Run the upgrade (note that if you used the UI for install, you'll need to follow the getting started guide to setup kubeconfig, if you skipped it earlier use the "Remind me how to do this" link on the Kubernetes cluster tab)
+and then run:
 
-```
+```console
 helm repo add posthog https://posthog.github.io/charts-clickhouse/
 helm repo update
 helm upgrade -f values.yaml --timeout 20m --namespace posthog posthog posthog/posthog
 ```
 
+### Accessing PostHog
+
+<GetUrlSnippet />
+
+<PostInstallSnippet />
+
 ## Manual install
 
-Alternatively, to install the chart manually using [Helm >= v3](https://helm.sh/) follow these steps:
+First, we need to set up a Kubernetes cluster (see the official DigitalOcean [documentation](https://docs.digitalocean.com/products/kubernetes/quickstart/) for more info).
 
-### 1. Set up K8s cluster
-  
-First, we need to set up a Kubernetes Cluster. See [Kubernetes quickstart](https://docs.digitalocean.com/products/kubernetes/quickstart/). Note that the minimum total resource requirements to run PostHog are 4vcpu and 4G of memory. 
+<ClusterRequirementsSnippet />
+
+#### 1. Chart configuration
 
 Here's the minimal required `values.yaml` that we'll be using later. You can find an overview of the parameters that can be configured during installation under [configuration](/docs/self-host/deploy/configuration).
 ```yaml
@@ -131,23 +103,29 @@ kafka:
     size: 20Gi
 ```
 
-### 2. Install the chart
+#### 2. Install the chart
 
 <InstallingSnippet />
 
-### 3. Lookup external IP
+#### 3. Lookup the IP address of our installation
+
+<GetIPAddressSnippet />
 
-<DOIPAddressSnippet />
+#### 4. Set up DNS
 
-### 4. Set up DNS
+Create an `A` record from your desired hostname to the external IP we got above.
 
-Create an `A` record from your desired hostname to the external IP.
+### Accessing PostHog
+
+<GetUrlSnippet />
+
+<PostInstallSnippet />
 
 ## Troubleshooting
+
 ### I cannot connect to my PostHog instance after creation
 <TryUnsecureSnippet />
 
-
 ## Upgrading the chart
 <UpgradingSnippet />
 

diff --git a/contents/docs/self-host/deploy/gcp.mdx b/contents/docs/self-host/deploy/gcp.mdx
@@ -4,14 +4,19 @@ sidebarTitle: Google Cloud Platform
 sidebar: Docs
 showTitle: true
 tags:
-  - gcp
+    - gcp
 ---
 
+import ClusterRequirementsSnippet from './snippets/cluster-requirements'
 import InstallingSnippet from './snippets/installing'
 import UpgradingSnippet from './snippets/upgrading'
 import UninstallingSnippet from './snippets/uninstalling'
 
-First, we need to set up a Kubernetes Cluster. See [Google Cloud Kubernetes Engine (GKE)](https://cloud.google.com/kubernetes-engine/).
+First, we need to set up a Kubernetes cluster (see the official GCP [documentation](https://cloud.google.com/kubernetes-engine/) for more info).
+
+<ClusterRequirementsSnippet />
+
+## Chart configuration
 
 Here's the minimal required `values.yaml` that we'll be using later. You can find an overview of the parameters that can be configured during installation under [configuration](/docs/self-host/deploy/configuration).
 ```yaml

diff --git a/contents/docs/self-host/deploy/other.mdx b/contents/docs/self-host/deploy/other.mdx
@@ -5,17 +5,15 @@ sidebar: Docs
 showTitle: true
 ---
 
+import ClusterRequirementsSnippet from './snippets/cluster-requirements'
 import InstallingSnippet from './snippets/installing'
 import UpgradingSnippet from './snippets/upgrading'
 import UninstallingSnippet from './snippets/uninstalling'
 import TryUnsecureSnippet from './snippets/tryunsecure'
 
-For all other platforms, we suggest setting up Kubernetes first and using the helm chart directly to deploy a PostHog instance with Nginx ingress controller.
-
-## Prerequisites
-- [Kubernetes](http://kubernetes.io) 1.19+
-- [Helm](https://helm.sh) >= v3
+For all the other platforms, setup your Kubernetes cluster (see the documentation of your platform for more info).
 
+<ClusterRequirementsSnippet />
 
 ## Installing the chart
 

diff --git a/contents/docs/self-host/deploy/snippets/cluster-requirements.mdx b/contents/docs/self-host/deploy/snippets/cluster-requirements.mdx
@@ -0,0 +1,12 @@
+#### Cluster requirements
+* Kubernetes version >= 1.19
+* Ensure your cluster has enough resources to run PostHog (we suggest a total minimum of 4 vcpu & 8GB of memory).
+* Ensure the `AllowVolumeExpansion` parameter is set to `True` in the storage class definition (this setting enables PVC resize)
+    <details>
+
+    ```console
+    $ kubectl get storageclass -o json | jq '.items[].allowVolumeExpansion'
+    true
+    ```
+
+    </details>
diff --git a/contents/docs/self-host/deploy/snippets/do-ip-address.mdx b/contents/docs/self-host/deploy/snippets/do-ip-address.mdx
diff --git a/contents/docs/self-host/deploy/snippets/get-ip-address.mdx b/contents/docs/self-host/deploy/snippets/get-ip-address.mdx
@@ -0,0 +1,6 @@
+```shell
+export INGRESS_IP=$(kubectl get --namespace posthog ingress posthog -o jsonpath="{.status.loadBalancer.ingress[0].ip}") && \
+echo "\n-----\n" && \
+echo "Your PostHog IP address is: $INGRESS_IP" && \
+echo "\n-----\n"
+```
diff --git a/contents/docs/self-host/deploy/snippets/get-url.mdx b/contents/docs/self-host/deploy/snippets/get-url.mdx
@@ -0,0 +1,6 @@
+```shell
+export INGRESS_IP=$(kubectl get --namespace posthog ingress posthog -o jsonpath="{.status.loadBalancer.ingress[0].ip}") && \
+echo "\n-----\n" && \
+echo "Your PostHog installation is available at: http://$INGRESS_IP" && \
+echo "\n-----\n"
+```
diff --git a/contents/docs/self-host/deploy/snippets/installing.mdx b/contents/docs/self-host/deploy/snippets/installing.mdx
@@ -1,9 +1,7 @@
-To install the chart with the release name `posthog` in `posthog` namespace, run the following:
+To install the chart using [Helm >= v3](https://helm.sh/) with the release name `posthog` in `posthog` namespace, run the following:
 
 ```console
 helm repo add posthog https://posthog.github.io/charts-clickhouse/
 helm repo update
 helm install -f values.yaml --timeout 20m --create-namespace --namespace posthog posthog posthog/posthog
 ```
-
-
diff --git a/contents/docs/self-host/deploy/snippets/post-install.mdx b/contents/docs/self-host/deploy/snippets/post-install.mdx
@@ -0,0 +1,2 @@
+Congrats, you now have a working PostHog instance! You can now [integrate your development applications](/docs/integrate) with your PostHog deployment for testing purposes.
+> Note: You will only be able to test web apps on HTTP such as those running on `localhost`.
diff --git a/contents/docs/self-host/deploy/snippets/tryunsecure.mdx b/contents/docs/self-host/deploy/snippets/tryunsecure.mdx
@@ -1,4 +1,6 @@
-As a troubleshooting tool, you can allow HTTP access by setting these values in your `values.yaml`, but we recommend always accessing PostHog via https.
+import GetURLSnippet from './get-url'
+
+As a troubleshooting tool, you can allow HTTP access by setting these values in your `values.yaml`, but we recommend always accessing PostHog via HTTPs.
 ```yaml
 ingress:
   nginx:
@@ -9,9 +11,6 @@ web:
   secureCookies: false
 ```
 
-After upgrading you can run the following to get the IP to access PostHog:
-```console
-export INGRESS_IP=$(kubectl get --namespace posthog ingress posthog -o jsonpath="{.status.loadBalancer.ingress[0].ip}")
-echo "Visit http://$INGRESS_IP to use PostHog\!"
-```
+After upgrading you can run the following command to get the URL to access PostHog:
 
+<GetURLSnippet />
diff --git a/contents/docs/self-host/index.md b/contents/docs/self-host/index.md
@@ -12,13 +12,13 @@ Getting a shiny, running production environment of PostHog is probably one the f
 
 Lucky for you, our platform is incredibly easy to use and affordable to host with any provider. Below, we have several step-by-step guides outlining how to set up hosting on a variety of different services.
 
-### **Deployment options**
+### Deployment options
 
-- [DigitalOcean](/docs/self-host/deploy/digital-ocean)
-- [Google Cloud Platform](/docs/self-host/deploy/gcp)
 - [AWS](/docs/self-host/deploy/aws)
 - [Azure](/docs/self-host/deploy/azure)
-- [Using Helm Charts](/docs/self-host/deploy/other)
+- [DigitalOcean](/docs/self-host/deploy/digital-ocean)
+- [Google Cloud Platform](/docs/self-host/deploy/gcp)
+- [Other platforms](/docs/self-host/deploy/other)
 
 ## Configure
 

diff --git a/contents/images/do-ip-location.png b/contents/images/do-ip-location.png