ENDOC-421 Enhance the nginx instructions with common options #425
Conversation
| --- | ||
| sidebarDepth: 2 | ||
| --- | ||
| # Manage NGINX |
There was a problem hiding this comment.
I think we need an overview section to introduce the page. Our starting point assumes someone has already installed the NGINX controller and this page is for verifying and refining that configuration.
| kind: ConfigMap | ||
| ``` | ||
|
|
||
| Refer to the NGINX sections in each of the cloud install guides (EKS, AKS, GKE) for more information: |
There was a problem hiding this comment.
This section should be added to the intro of the new page. It's basically a prerequisite for everything else on the new page.
There was a problem hiding this comment.
@nshaw i can't find any references to nginx in tips and tricks ??
There was a problem hiding this comment.
@Lyd1aCla1r3 , I think because you already deleted it? I'll propose something for the new page.
| kind: ConfigMap | ||
| ``` | ||
|
|
||
| Production environments require additional common annotations: |
| ## Verify the NGINX Ingress Install | ||
| We recommend setting up a test application to verify that the ingress is working. | ||
|
|
||
| 1. Create a simple application from the `Cloud Shell`: |
There was a problem hiding this comment.
Cloud Shell is only for GKE. Let's just remove "from the Cloud Shell" in this sentence.
|
|
||
| 1. Create a simple application from the `Cloud Shell`: | ||
| ``` | ||
| kubectl create deployment hello-server --image=us-docker.pkg.dev/google-samples/containers/gke/hello-app:1.0 |
There was a problem hiding this comment.
This is specific to GKE but I don't have a better idea currently without doing some testing. :(
There was a problem hiding this comment.
@nshaw i kept the language but added a note, in bold, to clarify that step 1. applies to gke only and to start at step 2. if you're using another service. is that direction correct?
There was a problem hiding this comment.
@Lyd1aCla1r3 Sorry, I wasn't clear. The step is required for any server - you have to deploy a sample service to test the controlller. Let's remove the Note from above and just drop the "from the Cloud Shell" comment on Step 1. I may be wrong but think someone who is at this level can figure out a way to do this for their own env.
| ``` | ||
| It may take several minutes to populate the `Address`. | ||
|
|
||
| 6. Verify access to the web application using the `EXTERNAL-IP/hello` address of the previous `nginx-ingress-controller`. You should see the following: |
There was a problem hiding this comment.
Remove "previous". There should only be a single nginx-ingress-controller.
| ``` | ||
| Note that you will need the EXTERNAL-IP address of your ingress controller to configure the application. | ||
|
|
||
| 7. Set `ENTANDO_INGRESS_CLASS` to `nginx`. Entando exposes this environment variable to establish the ingress controller used for the deployment. |
There was a problem hiding this comment.
This is a bit confusing and I think out-of-date.
"Verify that you configured the ingress class in the Operator ConfigMap: entando.ingress.class: "nginx" so Entando knows which ingress controller should be used."
| kubectl delete deploy/hello-server service/hello-server ing/ingress-resource | ||
| ``` | ||
|
|
||
| ## Customize the Ingress Configuration |
There was a problem hiding this comment.
Customize the NGINX Configuration
| nginx.ingress.kubernetes.io/proxy-read-timeout: "600" # to increase the timeout when uploading large files | ||
| ``` | ||
|
|
||
| ## Setup `cert-manager` |
There was a problem hiding this comment.
Add the cert-manager for TLS Support
|
|
||
| There are situations where the default NGINX ingress configuration doesn't work well for Entando and must be customized. Refer to the [Development Tips and Tricks](../../docs/reference/local-tips-and-tricks.md#customizing-nginx) page for more information. | ||
| ::: tip | ||
| We recommend verifying NGINX is working correctly. This is confirmed with a `404 Not Found` error page when accessing the EXTERNAL-IP in your browser. Alternatively, you can [set up a simple test application](../devops/manage-nginx.md#verify-the-nginx-ingress-install) using your local `kubectl`. You can also [customize the NGINX ingress](../devops/manage-nginx.md#customize-the-ingress-configuration) to optimize the configuration for Entando. |
There was a problem hiding this comment.
'We recommend verifying NGINX is working correctly.' >> sounds awkward
There was a problem hiding this comment.
@jyunmitch rephrased in all instances
| There are situations where the default NGINX ingress configuration doesn't work well for Entando and must be customized. Refer to the [Development Tips and Tricks](../../docs/reference/local-tips-and-tricks.md#customizing-nginx) page for more information. | ||
| ::: tip | ||
| We recommend verifying NGINX is working correctly. This is confirmed with a `404 Not Found` error page when accessing the EXTERNAL-IP in your browser. Alternatively, you can [set up a simple test application](../devops/manage-nginx.md#verify-the-nginx-ingress-install) using your local `kubectl`. You can also [customize the NGINX ingress](../devops/manage-nginx.md#customize-the-ingress-configuration) to optimize the configuration for Entando. | ||
| ::: | ||
| ### Install the Entando Custom Resource Definitions (CRDs) | ||
| Once per cluster you need to deploy the `Entando Custom Resources`. | ||
| 1. Download the Custom Resource Definitions (CRDs) and deploy the cluster scoped resources |
There was a problem hiding this comment.
Use just CRDs or Custom Resource Definitions because the acronym is already defined above.
There was a problem hiding this comment.
@jyunmitch was researching acronym usage... this is actually an initialism lol will add to style guide agenda...
|
|
||
| There are situations where the default NGINX ingress configuration doesn't work well for Entando and must be customized. Refer to the [Development Tips and Tricks](../../docs/reference/local-tips-and-tricks.md#customizing-nginx) page for more information. | ||
| ::: tip | ||
| We recommend verifying NGINX is working correctly. This is confirmed with a `404 Not Found` error page when accessing the EXTERNAL-IP in your browser. Alternatively, you can [set up a simple test application](../devops/manage-nginx.md#verify-the-nginx-ingress-install) using your local `kubectl`. You can also [customize the NGINX ingress](../devops/manage-nginx.md#customize-the-ingress-configuration) to optimize the configuration for Entando. |
There was a problem hiding this comment.
'We recommend verifying NGINX is working correctly.' >> same as above, sounds awkward. maybe add 'that'. >> 'verifying that NGINX is working..."
|
|
||
| ::: tip | ||
| We recommend verifying NGINX is working correctly. This is confirmed with a `404 Not Found` error page when accessing the EXTERNAL-IP in your browser. Alternatively, you can [set up a simple test application](../devops/manage-nginx.md#verify-the-nginx-ingress-install) using either Azure Cloud Shell or your local `kubectl`. You can also [customize the NGINX ingress](../devops/manage-nginx.md#customize-the-ingress-configuration) to optimize the configuration for Entando. | ||
| ::: | ||
| ### Install the Entando Custom Resource Definitions (CRDs) | ||
| 1. Download the Custom Resource Definitions (CRDs) and, once per cluster, deploy the cluster scoped resources |
There was a problem hiding this comment.
use CRDs or Custom Resource Definitions in this sentence since the acronym is already defined above.
| There are situations where the default NGINX ingress configuration doesn't work well for Entando and must be customized. Refer to the [Development Tips and Tricks](../../docs/reference/local-tips-and-tricks.md#customizing-nginx) page for more information. | ||
| ::: tip | ||
| We recommend verifying NGINX is working correctly. This is confirmed with a `404 Not Found` error page when accessing the EXTERNAL-IP in your browser. Alternatively, you can [set up a simple test application](../devops/manage-nginx.md#verify-the-nginx-ingress-install) using your local `kubectl`. You can also [customize the NGINX ingress](../devops/manage-nginx.md#customize-the-ingress-configuration) to optimize the configuration for Entando. | ||
| ::: | ||
| ### Install the Entando Custom Resource Definitions (CRDs) | ||
| Once per cluster you need to deploy the `Entando Custom Resources`. | ||
| 1. Download the Custom Resource Definitions (CRDs) and deploy the cluster scoped resources |
There was a problem hiding this comment.
same as before, use CRDs or full name
| @@ -83,27 +83,6 @@ The base domain configured via the ENTANDO_DEFAULT_ROUTING_SUFFIX (e.g. in your | |||
|
|
|||
| ### `The IP address changed after the initial install` | |||
| - Restarting a Windows computer can cause this (see [Windows Hyper-V IP Changes](#hyper-v-ip-changes) below), and the workaround noted above (e.g. update your /etc/hosts file) also applies. Simply update the IP address in the first column to use the current IP of your virtual machine. | |||
There was a problem hiding this comment.
which work around? Maybe add what heading this bit is referring to
There was a problem hiding this comment.
it's the workaround directly above... i think a link wasn't inserted because the page wouldn't scroll ??
There was a problem hiding this comment.
I was looking for '/etc/hosts' in the headers. Not a big deal
| @@ -83,27 +83,6 @@ The base domain configured via the ENTANDO_DEFAULT_ROUTING_SUFFIX (e.g. in your | |||
|
|
|||
| ### `The IP address changed after the initial install` | |||
| - Restarting a Windows computer can cause this (see [Windows Hyper-V IP Changes](#hyper-v-ip-changes) below), and the workaround noted above (e.g. update your /etc/hosts file) also applies. Simply update the IP address in the first column to use the current IP of your virtual machine. | |||
There was a problem hiding this comment.
I was looking for '/etc/hosts' in the headers. Not a big deal
| @@ -3,8 +3,9 @@ sidebarDepth: 2 | |||
| --- | |||
| # Manage NGINX | |||
|
|
|||
| This page assumes you are running Entando on [Amazon Elastic Kubernetes Service](../getting-started/eks-install.md), [Azure Kubernetes Service](../getting-started/azure-install.md) or [Google Kubernetes Engine](../getting-started/gke-install.md) and have already replaced the default ingress controller with NGINX. The following sections explain how to verify and refine your NGINX configuration. | |||
There was a problem hiding this comment.
Since this is an intro paragraph, it would start better with "... explain how to verify and refine your NGINX configuration." Then move onto assumptions?
There was a problem hiding this comment.
Yeah, I agree. I said prereq in my last comment and it's a little more general than that. Maybe this:
There are environments where it's useful to use NGINX rather than the default ingress controller. This page shows how to verify and refine your NGINX configuration.
See the following install guides if needed:
- Amazon Elastic Kubernetes Service (EKS)
- Azure Kubernetes Service (AKS)
- Google Kubernetes Engine (GKE)
Note: the links weren't quite right in the previous version.
| @@ -3,8 +3,9 @@ sidebarDepth: 2 | |||
| --- | |||
| # Manage NGINX | |||
|
|
|||
| This page assumes you are running Entando on [Amazon Elastic Kubernetes Service](../getting-started/eks-install.md), [Azure Kubernetes Service](../getting-started/azure-install.md) or [Google Kubernetes Engine](../getting-started/gke-install.md) and have already replaced the default ingress controller with NGINX. The following sections explain how to verify and refine your NGINX configuration. | |||
| ## Verify the NGINX Ingress Install | |||
There was a problem hiding this comment.
Are you verifying the ingress or verifying the install?
There was a problem hiding this comment.
@jyunmitch i borrowed this title directly from one of the cloud service install guides... you're verifying the install of the ingress. @nshaw?
There was a problem hiding this comment.
An ingress is a Kubernetes thing. The NGINX Ingress Controller is what gets installed and it takes over ingress handling. So I think Verify the NGINX Ingress Install is fine.
| kind: ConfigMap | ||
| ``` | ||
|
|
||
| Refer to the NGINX sections in each of the cloud install guides (EKS, AKS, GKE) for more information: |
There was a problem hiding this comment.
@Lyd1aCla1r3 , I think because you already deleted it? I'll propose something for the new page.
| @@ -3,8 +3,9 @@ sidebarDepth: 2 | |||
| --- | |||
| # Manage NGINX | |||
|
|
|||
| This page assumes you are running Entando on [Amazon Elastic Kubernetes Service](../getting-started/eks-install.md), [Azure Kubernetes Service](../getting-started/azure-install.md) or [Google Kubernetes Engine](../getting-started/gke-install.md) and have already replaced the default ingress controller with NGINX. The following sections explain how to verify and refine your NGINX configuration. | |||
There was a problem hiding this comment.
Yeah, I agree. I said prereq in my last comment and it's a little more general than that. Maybe this:
There are environments where it's useful to use NGINX rather than the default ingress controller. This page shows how to verify and refine your NGINX configuration.
See the following install guides if needed:
- Amazon Elastic Kubernetes Service (EKS)
- Azure Kubernetes Service (AKS)
- Google Kubernetes Engine (GKE)
Note: the links weren't quite right in the previous version.
|
|
||
| 1. Create a simple application from the `Cloud Shell`: | ||
| ``` | ||
| kubectl create deployment hello-server --image=us-docker.pkg.dev/google-samples/containers/gke/hello-app:1.0 |
There was a problem hiding this comment.
@Lyd1aCla1r3 Sorry, I wasn't clear. The step is required for any server - you have to deploy a sample service to test the controlller. Let's remove the Note from above and just drop the "from the Cloud Shell" comment on Step 1. I may be wrong but think someone who is at this level can figure out a way to do this for their own env.
No description provided.