From 4a5ad45091c0f90ea47a488edc25640786c164bc Mon Sep 17 00:00:00 2001 From: Sergey Shurlakov Date: Tue, 12 Oct 2021 17:24:51 +0600 Subject: [PATCH] Fix installation requirements (#131) * Add missing requirements and small fixes in text * add more detailed explanations * Minor fixes in Octopod_deployment_guide.md * Minor fix in README.md Co-authored-by: Sergey Shurlakov Co-authored-by: Aleksei Sizov --- charts/octopod/README.md | 23 +++++++++++------ docs/en/Octopod_deployment_guide.md | 40 ++++++++++++++++++++++++----- 2 files changed, 49 insertions(+), 14 deletions(-) diff --git a/charts/octopod/README.md b/charts/octopod/README.md index b7e78bd..c06f5ed 100644 --- a/charts/octopod/README.md +++ b/charts/octopod/README.md @@ -6,20 +6,27 @@ ```console $ helm repo add typeable https://typeable.github.io/octopod/ $ helm repo update -$ kubectl create ns octopod-deployment +$ kubectl create namespace octopod-deployment $ helm install octopod typeable/octopod --set octopod.baseDomain="your-domain.com" ``` ## Introduction -This chart bootstraps an Octopod deployment in a [Kubernetes](http://kubernetes.io) cluster using the [Helm](https://helm.sh) package manager. +This chart bootstraps Octopod deployment in a [Kubernetes](http://kubernetes.io) cluster using the [Helm](https://helm.sh) package manager. ## Prerequisites -- Kubernetes 1.12+ -- Helm 3.1.0 -- PV support (for postgresql persistense) -- nginx-ingress controller +### Mandatory + +- Kubernetes version >= 1.12.0 <= 1.22.0 +- PVC support (for PostgreSQL persistence) +- [NGINX Ingress](https://kubernetes.github.io/ingress-nginx/) contoller version <= 0.49.3 installed. NGINX Ingress controller v1.x.x is not currently supported + +### Optional + +- Cert Manager ([cert-manager](https://cert-manager.io/docs/installation/)) installed, if you want to get SSL certificates from Let's Encrypt automatically. +- Cluster issuer ([ACME Issuer](https://cert-manager.io/docs/configuration/acme/#creating-a-basic-acme-issuer)) created. By default we assume that it would be named `letsencrypt`. You can change it by setting `ingress.tls.clusterIssuer` parameter. + ## Installing the Chart This chart will not create or delete any namespaces for you. @@ -53,10 +60,10 @@ To uninstall/delete the `my-release` deployment: $ helm -n octopod delete my-release ``` -The command removes all the Kubernetes components but PVC's associated with the postgres chart and deletes the release. +The command removes all the Kubernetes components except PVCs associated with the postgres chart, and deletes the release. ## Note about generated values -Some values (such as passwords) in this chart (and its dependencies) are generated automatically, but due to [a limitation in helm](https://github.com/helm/charts/issues/5167) the values are changing on every upgrade. To prevent this you must fix these values by providing them via `--set` flags or in the [values file](https://helm.sh/docs/chart_template_guide/values_files/). +Some values (such as passwords) in this chart (and its dependencies) are generated automatically, but due to [the limitation in Helm](https://github.com/helm/charts/issues/5167) the values are changing on every upgrade. To prevent this you must set these values explicitly by providing them via `--set` flags or in the [values file](https://helm.sh/docs/chart_template_guide/values_files/). These values are: - `postgresql.postgresqlPassword` ― main db password diff --git a/docs/en/Octopod_deployment_guide.md b/docs/en/Octopod_deployment_guide.md index fd0337a..fc9687f 100644 --- a/docs/en/Octopod_deployment_guide.md +++ b/docs/en/Octopod_deployment_guide.md @@ -7,12 +7,40 @@ There are several options to install Octopod depending on your needs. You can install Octopod in any Kubernetes cluster using our [Helm chart](../../charts/octopod). -Your cluster must satisfy following requirements: -- PVC support -- Ingress contoller ([ingress-nginx](https://kubernetes.github.io/ingress-nginx/)) installed -- Kubernetes version >= 1.19.0 +Your cluster must satisfy the following requirements: + +#### Mandatory requirements + +- Kubernetes version >= 1.12.0 <= 1.22.0 +- PVC support (for PostgreSQL persistence) +- [NGINX Ingress](https://kubernetes.github.io/ingress-nginx/) contoller version <= 0.49.3 installed. NGINX Ingress controller v1.x.x is not currently supported + +#### Optional requirements + +- Cert Manager ([cert-manager](https://cert-manager.io/docs/installation/)) installed, if you want to get SSL certificates from Let's Encrypt automatically. + +After ensuring that your cluster satisfies the requirements you can follow [the Helm installation instruction](../../charts/octopod/README.md) provided with our Helm chart. + +### Running Ocopod in production considerations. + +You must consider several things before running Octopod in production and onboarding your team. + +##### DNS records + +Octopod will create a lot of on-demand environments and they must be reachable for your team. Usually it implies creating a lot of DNS records, pointing to Octopod managed environments. This process must be automated. + +We highly recommend you to use [ExternalDNS](https://github.com/kubernetes-sigs/external-dns) as a very versatile solution for DNS records automation. +In certain cases, however, it isn't possible to use ExternalDNS. In this case you can use a wildcard DNS record, pointing to the service endpoint of your ingress controller. We do not recommend using wildcard DNS records. Even though they are much easier to implement, they could lead to hard-to-trace errors and they are also implementation-dependent. + +##### Certificates + +If you want to request SSL certificates dynamically from Let's Encrypt you must be aware of their [limits](https://letsencrypt.org/docs/rate-limits/). Because of these limits we recommend you to use a wildcard certificate for all Octopod deployments. The wildcard certificate has its limitations, like being valid only for one subdomain. This implies a need for planning your deployments DNS naming. + +##### Resources + +This is the most obvious one of the three, but you need to plan your cluster capacity based on your team needs. Setting [resource limits](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/) for your workloads is one of the best practices of using Kubernetes, and you probably have done this already. +Also consider using autoscaling since it really helps to reduce costs in highly dynamic environments. -After ensuring that your cluster satisfies the requirements you can follow [the Helm installation instruction](../../charts/octopod/README.md) provided with our helm chart. ### If you want to try it locally @@ -36,7 +64,7 @@ Script will expose octopod ui at `octopod.lvh.me`. ## What next? -Now you may want to check how to [install helm charts](Helm-based_deployment_guide.md) with Octopod. +Now you may want to check how to [install Helm charts](Helm-based_deployment_guide.md) with Octopod.