From a293eccc21e19fc1226e12466262f1cc460974f4 Mon Sep 17 00:00:00 2001 From: Lydia Date: Mon, 29 Nov 2021 13:37:27 -0800 Subject: [PATCH 01/10] ENDOC-385 Revisit existing content --- .../docs/reference/local-tips-and-tricks.md | 92 +++++++++---------- 1 file changed, 45 insertions(+), 47 deletions(-) diff --git a/vuepress/docs/v6.3.2/docs/reference/local-tips-and-tricks.md b/vuepress/docs/v6.3.2/docs/reference/local-tips-and-tricks.md index 19808cbebb..3df3a1e2ae 100644 --- a/vuepress/docs/v6.3.2/docs/reference/local-tips-and-tricks.md +++ b/vuepress/docs/v6.3.2/docs/reference/local-tips-and-tricks.md @@ -3,74 +3,73 @@ sidebarDepth: 2 redirectFrom: /next/tutorials/devops/local-tips-and-tricks.html --- # Development Tips and Tricks -We've collected a list of tips and tricks for optimizing your local quickstart or [Getting Started](../../docs/getting-started/) development environment. We invite you to ask questions, collaborate with the community, and share your own favorite +We've collected a list of tips and tricks to optimize your local quickstart or [Getting Started](../../docs/getting-started/) development environment. We invite you to ask questions, collaborate with the community, and share your own favorite practices over on the [Entando forum](https://forum.entando.org). ## Quickstart Management -Here are a few common questions about the quickstart environment which uses Multipass to launch an Ubuntu VM, install K3s Kubernetes into it, and then deploy Entando. +Here are a few common questions about the quickstart environment, which uses Multipass to launch an Ubuntu VM, install K3s Kubernetes, and then deploy Entando. ### General -1. **How can I remove a quickstart environment?**. If you want to completely remove the VM created by Multipass then you can use `multipass delete ` (where the default VM-NAME for a quickstart is `entando`) and then `multipass purge` to recover the resources. If you just want to shutdown Entando but keep the VM you can use `multipass shell ` to shell into the VM and then remove the namespace via `sudo kubectl delete namespace entando`. +1. **How can I remove a quickstart environment?**. If you want to completely remove the VM created by Multipass, you can use `multipass delete ` (where the default VM-NAME for a quickstart is `entando`) and then `multipass purge` to recover the resources. If you just want to shutdown Entando but keep the VM, you can use `multipass shell ` to shell into the VM and then remove the namespace via `sudo kubectl delete namespace entando`. ### Multipass -1. **How can I shell into a Multipass VM?** `multipass shell `. If you don't provide a VM-NAME, multipass will use the default name `primary` and even launch it for you if it doesn't exist. -1. **What do I need to do after restarting my laptop?** By default Multipass is installed as a service and will restart automatically. If Multipass isn't running, you'll need to first start the service, and then you can start your VM via `multipass start `. Kubernetes will start automatically along with any installed pods, including Entando. It can take a few minutes for all of the pods to start completely but you can use `sudo kubectl -n entando get pods --watch` to observe the progress. -1. **How can I idle or pause my Entando instance?** You can use either `multipass stop ` or `multipass suspend `, if you'd rather preserve the VM state. You can then use `multipass start ` to start the VM. +1. **How can I shell into a Multipass VM?** `multipass shell `. If you don't provide a VM-NAME, Multipass will use the default name `primary`, and even launch it for you if it doesn't exist. +1. **What do I need to do after restarting my laptop?** By default, Multipass is installed as a service and will restart automatically. If Multipass isn't running, you'll need to first initialize this service; then you can start your VM via `multipass start `. Kubernetes will launch automatically along with any installed pods, including Entando. It can take a few minutes for all of the pods to fully initialize, but you can use `sudo kubectl -n entando get pods --watch` to observe the progress. +1. **How can I pause or idle my Entando instance?** You can pause with `multipass stop `, or idle with `multipass suspend ` to preserve the VM state. You can then use `multipass start ` to start the VM. 1. **What else can Multipass do?** You can run `multipass help` or refer to the [Multipass docs](https://multipass.run/docs) for more information on Multipass. ### Entando in Kubernetes -1. **How can I install a new copy of Entando into an existing VM?** The quickstart deploys Kubernetes resources into a dedicated namespace, `entando` by default. You can simply delete the namespace, `sudo kubectl delete namespace entando`, if you want to delete all of its resources. You can then re-create the namespace and re-install by applying the Helm template for your environment. Alternatively, you can use `ent quickstart --vm-reuse=true` but you'll need to set other `ent quickstart` options so check the `ent` help. +1. **How can I install a new copy of Entando into an existing VM?** By default, the quickstart installation deploys Kubernetes resources into a dedicated namespace called `entando`. If you want to remove all of the resources in `entando` you can simply delete the namespace with `sudo kubectl delete namespace entando`. You can then re-create the namespace and re-install the resources by applying the Helm template for your environment. Alternatively, you can achieve this with `ent quickstart --vm-reuse=true`, but you'll need to set other `ent quickstart` options, so check the `ent` help. 1. **How can I shell into a running pod or view its logs?** You can use the standard Kubernetes commands, e.g. `sudo kubectl exec -it -c ` -1. **What do I if Entando doesn't start completely?** The most common cause for this is a networking problem. See the [Network issues](#network-issues) section below for details. If all else fails reach out to the Entando team on Slack or in the Forums. +1. **What do I do if Entando doesn't fully initialize?** The most common cause of this is a networking problem. See the [Network issues](#network-issues) section below for details. If all else fails, reach out to the Entando team on Slack or in the Forums. ## Shared Servers -We've recommended using Multipass as a way to quickly spin up an Ubuntu VM to host a local Kubernetes cluster for test purposes. There are many times when a local environment is useful but most teams utilize a shared Kubernetes cluster managed by an operations team and installed either on premise or with a cloud provider for full integration testing, CI/CD, DevOps, etc. +We recommend using Multipass to quickly spin up an Ubuntu VM to host a local Kubernetes cluster for test purposes. A local environment is often useful, but most teams utilize a shared Kubernetes cluster. This shared cluster is managed by an operations team, and installed either on premise or with a cloud provider for full integration testing, CI/CD, DevOps, etc. ## Network Issues -A local Entando 6.3 quickstart installation (e.g. what you'll get if you follow the [Getting Started](../../docs/getting-started/) guide) may use a set of local domain names to enable accessing Entando services. Your IP address will vary but may look something like this: +A local Entando 6.3 quickstart installation (e.g. what you'll get if you follow the [Getting Started](../../docs/getting-started/) guide) may use a set of local domain names to enable access to Entando services. Your IP address will vary, but may look something like this: ``` quickstart-entando.192.168.99.1.nip.io quickstart-kc-entando.192.168.99.1.nip.io quickstart-eci-entando.192.168.99.1.nip.io ``` -The base domain configured via the ENTANDO_DEFAULT_ROUTING_SUFFIX (e.g. in your entando.yaml) is based on a fixed IP address and that address is configured during the initial installation. That setting is used to generate ingress routes to map incoming URLs to individual services. In production environments there's generally a dedicated network layer to manage IPs/routing (both on premise and cloud) but those options are often not readily available in a local setup. Here are a couple common issues that can prevent Entando from starting in a local environment: +The base domain configured via the ENTANDO_DEFAULT_ROUTING_SUFFIX (e.g. in your entando.yaml) borrows a fixed IP address that is created during the initial installation. This domain is used to generate ingress routes to map incoming URLs to individual services. In production environments there's generally a dedicated network layer to manage IPs/routing (both on premise and in the cloud), but this is not readily available in most local setups. Below are a couple of common issues that can prevent Entando from initializing in a local environment: ### `.nip.io isn't allowed` - - This could be because of firewall settings or corporate security policies. The simplest workaround is to manually edit your /etc/hosts file and map the necessary domains to the IP of your local virtual machine. + - This could be due to firewall settings or corporate security policies. The simplest workaround is to manually edit your /etc/hosts file and map the necessary domains to the IP of your local virtual machine. ``` 192.168.99.1 quickstart-kc-entando.192.168.99.1.nip.io 192.168.99.1 quickstart-eci-entando.192.168.99.1.nip.io 192.168.99.1 quickstart-entando.192.168.99.1.nip.io ``` - If you add microservices to your installation, you may need to add additional mappings for the new ingresses. -- See [this section below](#option-2-manually-update-your-hosts-file) for detailed steps on Windows. +- See [this section below](#option-2-manually-update-your-hosts-file) for detailed steps to perform this on Windows. ### `The IP address changed after the initial install` -- The workaround noted above (e.g. update your /etc/hosts file) can also be used here. Simply update the IP address in the first column to use the current IP of your virtual machine. -- On Windows this can happen simply because your laptop restarted. See [Windows Hyper-V IP Changes](#hyper-v-ip-changes) below. +- 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. ## Windows Development ### Multipass loses control of VMs **Q: What do I do if Multipass cannot access my VMs?** -**A:** The most common symptoms include an `IP=UNKNOWN` entry when issuing a `multipass list` and any attempts to stop or shell into the VM will fail. +**A:** The most common symptoms include an `IP=UNKNOWN` entry when issuing a `multipass list`, and when attempts to stop or shell into the VM consistently fail. -Internet Connection Sharing (ICS) is a Windows service that provides Internet connectivity to virtual machines and its `hosts.ics` file can occasionally get corrupted. Restarting the host laptop or desktop should remedy this but a quicker and simpler fix is to shutdown any VMs using the hypervisor (Hyper-V or VirtualBox), remove the `hosts.ics` file from `Windows/System32/drivers/etc` using elevated privileges, and then restart the VM(s). You can examine the `hosts.ics` file first to check if it is well-formed or if it contains spurious numbers or letters rather than clean IP to VM-NAME mappings. +Internet Connection Sharing (ICS) is a Windows service that provides Internet connectivity to virtual machines, and its `hosts.ics` file can occasionally get corrupted. Restarting the host laptop or desktop should remedy this, but a quicker and simpler fix is to shutdown any VMs using the hypervisor (Hyper-V or VirtualBox), remove the `hosts.ics` file from `Windows/System32/drivers/etc` using elevated privileges, and then restart the VM(s). You can examine the `hosts.ics` file first to check if it is well-formed, with clean IP to VM-NAME mappings insteaad of spurious numbers or letters. ### Hyper-V IP Changes **Q: My Entando installation stops working when I restart Windows. How can I fix this?** -**A:** The basic issue is that Windows Hyper-V makes it difficult to set a static IP for a VM. (See this [forum post](https://techcommunity.microsoft.com/t5/windows-insider-program/hyper-v-default-switch-ip-address-range-change-ver-1809-build/m-p/261431) for details.) As discussed [above](#network-issues), Entando's ingress routes rely on an fixed IP address and will break if the IP address changes after initial installation. Here are a few options to solve this issue, short of modifying your router or network switch settings: +**A:** The basic issue is that Windows Hyper-V makes it difficult to set a static IP for a VM (see this [forum post](https://techcommunity.microsoft.com/t5/windows-insider-program/hyper-v-default-switch-ip-address-range-change-ver-1809-build/m-p/261431) for details). As discussed [above](#network-issues), Entando's ingress routes rely on a fixed IP address and will break if the IP address changes after initial installation. Here are a few options to solve this issue, short of modifying your router or network switch settings: #### Option 1: Single host routing -The simplest way to deal with the peculiarities of Hyper-V IP assignments is to avoid it by using the Windows-specific mshome.net addresses. This allows you to access a VM by using an address like `.mshome.net`. If you set up your enviroment using the [Automatic Install](../getting-started/#automatic-install) instructions, then the ent CLI will select the single host option for you and the address will be `entando.mshome.net`. You can accomplish the same thing yourself using the `ent quickstart` script but see its `--help` for the current set of options. +The simplest way to deal with the peculiarities of Hyper-V IP assignment is to avoid it, instead using Windows-specific mshome.net addresses. This allows you to access a VM with an address like `.mshome.net`. If you set up your enviroment using the [Automatic Install](../getting-started/#automatic-install) instructions, then the ent CLI will select the single host option and the address will be `entando.mshome.net`. You can accomplish the same thing yourself using the `ent quickstart` script, but see its `--help` for the current set of options. #### Option 2: Manually update your hosts file The next simplest option to re-enable external access to your cluster is to update your hosts file after each Windows restart. -You need two pieces of information for this workaround and you'll need administrator access to do this. +You need two pieces of information for this workaround, and you'll also need administrator access. -1. Determine the original IP used for your VM. This is included in the `ENTANDO_DEFAULT_ROUTING_SUFFIX` or you can see it included in the ingress names. Run ` kubectl -n entando get ingress` and you should see something like this: +1. Determine the original IP used for your VM. This is included in the `ENTANDO_DEFAULT_ROUTING_SUFFIX`, or you can find it included in the ingress names. Run ` kubectl -n entando get ingress` to see something like this: ```` NAME CLASS HOSTS quickstart-kc-ingress quickstart-kc-entando.192.168.235.100.nip.io @@ -78,14 +77,14 @@ quickstart-eci-ingress quickstart-eci-entando.192.168.235.100.ni quickstart-ingress quickstart-entando.192.168.235.100.nip.io ```` -2. Determine the current IP using `hostname -I` in the VM or by running `multipass list` from Windows: +2. Determine the current IP using `hostname -I` in the VM, or by running `multipass list` from Windows: ``` $ multipass list Name State IPv4 Image primary Running 172.31.118.12 Ubuntu 18.04 LTS ``` -3. As a Windows administrator, edit your hosts file `(C:\Windows\System32\drivers\etc\hosts)` to map any needed URLs from the old IP to the new IP. This will bypass .nip.io lookups. +3. As a Windows administrator, edit your hosts file `(C:\Windows\System32\drivers\etc\hosts)` to map any required URLs from the old IP to the new IP. This will bypass .nip.io lookups. ``` 172.31.118.12 quickstart-kc-entando.192.168.235.100.nip.io @@ -93,16 +92,16 @@ primary Running 172.31.118.12 Ubuntu 18.04 LTS 172.31.118.12 quickstart-entando.192.168.235.100.nip.io ``` -4. You should now be able to access your Entando URLs via the new IP. If your Entando installation stalled during startup, it should continue starting up as soon as the external address is functional again. +4. You should now be able to access your Entando URLs via the new IP. If your Entando installation stalled during startup, it should continue initializing as soon as the external address is functional again. #### Option 3: Add a Windows route -This option is a little more involved the first time but it means repairing your network settings can be done very easily later. In this case you'll pick a static IP, configure a Windows route to map it to the Hyper-V interface, and claim the IP in the Ubuntu VM via a netplan entry. +This option is initially a little more involved, but future repairs to your network settings can then be made very easily. You'll need to choose a static IP, configure a Windows route to map it to the Hyper-V interface, and claim the IP in the Ubuntu VM via a netplan entry. - You'll need to run all of these steps before installing Entando the first time but then just steps #1 and #2 after subsequent Windows restarts. + When implementing this option for the first time, all steps must be executed before installing Entando. Subsequent Windows restarts require steps #1 and #2, only. -1. Determine an IP that is unused on your local network. You can use ping or other tools for this but in the following steps we assume that your selected IP is 192.168.99.1. +1. Determine an IP that is unused on your local network (e.g. via ping). The following steps assume that IP 192.168.99.1 is selected. -2. Determine the interface address to Hyper-V, e.g. 32 below. Use cmd `route print` and look for the Interface entry for Hyper-V: +2. Determine the interface address to Hyper-V (e.g. 32 below). Use cmd `route print` and find the Interface entry for Hyper-V: ``` Interface List 32...00 15 5d 86 45 20 ......Hyper-V Virtual Ethernet Adapter @@ -113,13 +112,13 @@ Interface List route -p add [YOUR-IP] mask 255.255.255.255 0.0.0.0 IF [HYPER-V-INTERFACE] route -p add 192.168.99.1 mask 255.255.255.255 0.0.0.0 IF 32 ``` -4. Verify the route was added by using `route print 192.168.99.1`. This command is useful after restart to check if the route needs to be created again. +4. Verify the route was added via `route print 192.168.99.1`. This command is useful after restart to check if the route needs to be created again. -5. Next, configure your VM to claim the same address. Shell into the VM using `winpty multipass shell [YOUR-VM-NAME]`. +5. Configure your VM to claim the same address. Shell into the VM using `winpty multipass shell [YOUR-VM-NAME]`. 6. Change to the root user to make the following steps simpler: `sudo -i` -7. Determine your network adapter via `ip link`, e.g. eth0. You just need the name. It's often second in the list after the loopback adapter. +7. Determine your network adapter name via `ip link`, e.g. eth0. It's often second in the list after the loopback adapter. ``` bash ubuntu@primary:~$ ip link 1: lo: mtu 65536 qdisc noqueue state UNKNOWN mode DEFAULT group default qlen 1000 @@ -128,9 +127,9 @@ ubuntu@primary:~$ ip link link/ether 00:15:5d:00:1a:0c brd ff:ff:ff:ff:ff:ff ``` -8. `cd /etc/netplan` +8. Navigate to your netplan directory: `cd /etc/netplan` -9. Create a netplan entry starting with 0 so it's loaded first: `vi 0-entando.yaml` +9. Create a netplan entry starting with 0 (so it's indexed and loaded first): `vi 0-entando.yaml` ``` yaml network: @@ -155,19 +154,19 @@ network: - 192.168.99.1/24 ``` -10. Apply the changes via `netplan apply` +10. Apply the changes with `netplan apply` -11. Verify connectivity via `ping 192.168.99.1` from the VM. You should get a response rather than a timeout. +11. From the VM, verify connectivity via `ping 192.168.99.1`. You should receive a response and not a timeout. -12. (Optional) Run a python server to verify you can access the VM from the host at `http://192.168.99.1:8000.` It may take a minute or so before the server is ready. +12. (Optional) Run a Python server to verify you can access the VM from the host at `http://192.168.99.1:8000.` It may take a minute or so before the server is ready. ``` python3 -m http.server 8000 ``` -13. You should now be able to install Entando using the static IP. If your Entando installation stalled during startup and was previously configured using the static IP, it should continue starting up as soon as the external address is functional again. +13. You should now be able to install Entando using the static IP. If your Entando installation stalled during startup, and was previously configured with a static IP, it should continue initializing as soon as the external address is functional again. #### Option 4: Reinstall Entando -We're including this option because it works and requires no additional configuration. If you plan to regularly work with Entando we recommend developing against a centralized and shared Kubernetes instance rather than running a full stack locally. If you need a cluster locally we recommend using option 1 or 2. +We're including this option because it works and requires no additional configuration. If you plan to regularly work with Entando we recommend developing against a centralized and shared Kubernetes instance rather than running a full stack locally. If you require a local cluster we recommend using option 1 or 2. ### JHipster **Q: How can I run JHipster on Windows?** @@ -175,17 +174,16 @@ We're including this option because it works and requires no additional configur **A:** JHipster requires a TTY interface for its menus to function correctly. Here are a few options to satisfy that requirement on Windows: * Run `jhipster` under cmd or Powershell * Using Git Bash, run `winpty jhipster.cmd` -* Use Ubuntu bash via WSL (1 or 2) or within the Multipass VM +* Use Ubuntu bash via WSL (1 or 2), or within the Multipass VM ### Multipass with VirtualBox -Multipass supports the use of VirtualBox on Windows as an alternative to using Hyper-V, say if you're using Windows Home. See the Multipass documentation on how to configure it to work with VirtualBox. +Multipass supports the use of VirtualBox on Windows as an alternative to Hyper-V. Refer to the Multipass documentation for VirtualBox configuration instructions. -In order to get Entando working correctly with this setup you will need to add a port forwarding rule so you can access Entando from your host system. -* Create your VM within Multipass. - -* Go to the Oracle VM VirtualBox Manager and edit the `Network` settings for the VM. +For Entando to work correctly with VirtualBox you will need to add a port forwarding rule to access Entando from your host system. +* Create your VM within Multipass +* Go to the Oracle VM VirtualBox Manager to edit the `Network` settings for the VM * Go to the `Advanced` options and click `Port Forwarding Rules` -* Add a new rule. +* Add a new rule * `Name`: your choice * `Protocol`: TCP * `Host IP`: leave this blank @@ -193,5 +191,5 @@ In order to get Entando working correctly with this setup you will need to add a * `Guest IP`: leave this blank * `Guest Port`: 80 * Click OK -* At this point any requests to port 80 on your localhost should be forwarded to the VM. -* You can now identify the IP of your host and use that to configure the `ENTANDO_DEFAULT_ROUTING_SUFFIX` in your yaml file, e.g. `192.168.64.25.nip.io`. You should not use the non-routable address (e.g. 10.0.2.15) identified from within the guest VM itself, but rather use the IP of the host. +* Any requests to port 80 on your localhost should be forwarded to the VM. +* Use the IP of your host to configure the `ENTANDO_DEFAULT_ROUTING_SUFFIX` in your YAML file, e.g. `192.168.64.25.nip.io`. You must use the host ID and not the non-routable address identified from within the guest VM, e.g. 10.0.2.15. From aa490f777af7e6e6782b8d625dac75aa7e157ca9 Mon Sep 17 00:00:00 2001 From: Lydia Date: Mon, 29 Nov 2021 13:46:53 -0800 Subject: [PATCH 02/10] ENDOC-385 Consistend with Q and A --- vuepress/docs/v6.3.2/docs/reference/local-tips-and-tricks.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/vuepress/docs/v6.3.2/docs/reference/local-tips-and-tricks.md b/vuepress/docs/v6.3.2/docs/reference/local-tips-and-tricks.md index 3df3a1e2ae..41e7a9a658 100644 --- a/vuepress/docs/v6.3.2/docs/reference/local-tips-and-tricks.md +++ b/vuepress/docs/v6.3.2/docs/reference/local-tips-and-tricks.md @@ -177,7 +177,9 @@ We're including this option because it works and requires no additional configur * Use Ubuntu bash via WSL (1 or 2), or within the Multipass VM ### Multipass with VirtualBox -Multipass supports the use of VirtualBox on Windows as an alternative to Hyper-V. Refer to the Multipass documentation for VirtualBox configuration instructions. +**Q: How do I run Multipass with VirtualBox?** + +**A:** Multipass supports the use of VirtualBox on Windows as an alternative to Hyper-V. Refer to the Multipass documentation for VirtualBox configuration instructions. For Entando to work correctly with VirtualBox you will need to add a port forwarding rule to access Entando from your host system. * Create your VM within Multipass From 000958e40b3ab2ba9eceefeaa9ecf99e82343646 Mon Sep 17 00:00:00 2001 From: Lydia Date: Mon, 29 Nov 2021 13:55:17 -0800 Subject: [PATCH 03/10] ENDOC-385 Q and A format --- .../docs/reference/local-tips-and-tricks.md | 37 +++++++++++++++---- 1 file changed, 29 insertions(+), 8 deletions(-) diff --git a/vuepress/docs/v6.3.2/docs/reference/local-tips-and-tricks.md b/vuepress/docs/v6.3.2/docs/reference/local-tips-and-tricks.md index 41e7a9a658..9622503c92 100644 --- a/vuepress/docs/v6.3.2/docs/reference/local-tips-and-tricks.md +++ b/vuepress/docs/v6.3.2/docs/reference/local-tips-and-tricks.md @@ -10,18 +10,39 @@ practices over on the [Entando forum](https://forum.entando.org). Here are a few common questions about the quickstart environment, which uses Multipass to launch an Ubuntu VM, install K3s Kubernetes, and then deploy Entando. ### General -1. **How can I remove a quickstart environment?**. If you want to completely remove the VM created by Multipass, you can use `multipass delete ` (where the default VM-NAME for a quickstart is `entando`) and then `multipass purge` to recover the resources. If you just want to shutdown Entando but keep the VM, you can use `multipass shell ` to shell into the VM and then remove the namespace via `sudo kubectl delete namespace entando`. +**Q: How can I remove a quickstart environment?** + +**A:** If you want to completely remove the VM created by Multipass, you can use `multipass delete ` (where the default VM-NAME for a quickstart is `entando`) and then `multipass purge` to recover the resources. If you just want to shutdown Entando but keep the VM, you can use `multipass shell ` to shell into the VM and then remove the namespace via `sudo kubectl delete namespace entando`. ### Multipass -1. **How can I shell into a Multipass VM?** `multipass shell `. If you don't provide a VM-NAME, Multipass will use the default name `primary`, and even launch it for you if it doesn't exist. -1. **What do I need to do after restarting my laptop?** By default, Multipass is installed as a service and will restart automatically. If Multipass isn't running, you'll need to first initialize this service; then you can start your VM via `multipass start `. Kubernetes will launch automatically along with any installed pods, including Entando. It can take a few minutes for all of the pods to fully initialize, but you can use `sudo kubectl -n entando get pods --watch` to observe the progress. -1. **How can I pause or idle my Entando instance?** You can pause with `multipass stop `, or idle with `multipass suspend ` to preserve the VM state. You can then use `multipass start ` to start the VM. -1. **What else can Multipass do?** You can run `multipass help` or refer to the [Multipass docs](https://multipass.run/docs) for more information on Multipass. +**Q: How can I shell into a Multipass VM?** + +**A:** `multipass shell `. If you don't provide a VM-NAME, Multipass will use the default name `primary`, and even launch it for you if it doesn't exist. + +**Q: What do I need to do after restarting my laptop?** + +**A:** By default, Multipass is installed as a service and will restart automatically. If Multipass isn't running, you'll need to first initialize this service; then you can start your VM via `multipass start `. Kubernetes will launch automatically along with any installed pods, including Entando. It can take a few minutes for all of the pods to fully initialize, but you can use `sudo kubectl -n entando get pods --watch` to observe the progress. + +**Q: How can I pause or idle my Entando instance?** + +**A:** You can pause with `multipass stop `, or idle with `multipass suspend ` to preserve the VM state. You can then use `multipass start ` to start the VM. + +**Q: What else can Multipass do?** + +**A:** You can run `multipass help` or refer to the [Multipass docs](https://multipass.run/docs) for more information on Multipass. ### Entando in Kubernetes -1. **How can I install a new copy of Entando into an existing VM?** By default, the quickstart installation deploys Kubernetes resources into a dedicated namespace called `entando`. If you want to remove all of the resources in `entando` you can simply delete the namespace with `sudo kubectl delete namespace entando`. You can then re-create the namespace and re-install the resources by applying the Helm template for your environment. Alternatively, you can achieve this with `ent quickstart --vm-reuse=true`, but you'll need to set other `ent quickstart` options, so check the `ent` help. -1. **How can I shell into a running pod or view its logs?** You can use the standard Kubernetes commands, e.g. `sudo kubectl exec -it -c ` -1. **What do I do if Entando doesn't fully initialize?** The most common cause of this is a networking problem. See the [Network issues](#network-issues) section below for details. If all else fails, reach out to the Entando team on Slack or in the Forums. +**Q: How can I install a new copy of Entando into an existing VM?** + +**A:** By default, the quickstart installation deploys Kubernetes resources into a dedicated namespace called `entando`. If you want to remove all of the resources in `entando` you can simply delete the namespace with `sudo kubectl delete namespace entando`. You can then re-create the namespace and re-install the resources by applying the Helm template for your environment. Alternatively, you can achieve this with `ent quickstart --vm-reuse=true`, but you'll need to set other `ent quickstart` options, so check the `ent` help. + +**Q: How can I shell into a running pod or view its logs?** + +**A:** You can use the standard Kubernetes commands, e.g. `sudo kubectl exec -it -c ` + +**Q: What do I do if Entando doesn't fully initialize?** + +**A:** The most common cause of this is a networking problem. See the [Network issues](#network-issues) section below for details. If all else fails, reach out to the Entando team on Slack or in the Forums. ## Shared Servers We recommend using Multipass to quickly spin up an Ubuntu VM to host a local Kubernetes cluster for test purposes. A local environment is often useful, but most teams utilize a shared Kubernetes cluster. This shared cluster is managed by an operations team, and installed either on premise or with a cloud provider for full integration testing, CI/CD, DevOps, etc. From 9f0007af74b82faa0787e410e9542a9f0286e92b Mon Sep 17 00:00:00 2001 From: Lydia Date: Mon, 29 Nov 2021 15:31:46 -0800 Subject: [PATCH 04/10] ENDOC-385 Adding NGINX --- .../docs/reference/local-tips-and-tricks.md | 25 +++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/vuepress/docs/v6.3.2/docs/reference/local-tips-and-tricks.md b/vuepress/docs/v6.3.2/docs/reference/local-tips-and-tricks.md index 9622503c92..4a8ff1fe74 100644 --- a/vuepress/docs/v6.3.2/docs/reference/local-tips-and-tricks.md +++ b/vuepress/docs/v6.3.2/docs/reference/local-tips-and-tricks.md @@ -69,6 +69,31 @@ 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. +## Customizing NGINX + +In some situations the default NGINX ingress configuration doesn't work well for Entando. For instance, JWT tokens can be too large, proxy-buffer-size can be too small, etc. A 502 Bad Gateway error can indicate this config needs to be modified. + +To configure the NGINX controller globally (for the entire cluster) we just need to edit the default NGINX's configmap, which is ingress-nginx-controller in the ingress-nginx namespace. Add the following inside the data parameter: + +``` +apiVersion: v1 +data: + allow-snippet-annotations: "true" + proxy-buffer-size: 24k +kind: ConfigMap +``` + +Refer to the NGINX troubleshooting sections from each of the cloud install guides (EKS, AKS, GKE, TKG) for more information: + +* [Amazon Elastic Kubernetes Service (EKS)](../../tutorials/devops/installation/elastic-kubernetes-service/eks-install.html#appendix-a-troubleshooting) +* [Azure Kubernetes Service (AKS)](../../tutorials/devops/installation/azure-kubernetes-service/azure-install.html#deploy-nginx-ingress-controller) +* [Google Kubernetes Engine (GKE)](../../tutorials/devops/installation/google-cloud-platform/gke-install.html#cluster-setup) +* [Tanzu Kubernetes Grid (TKG)](../../tutorials/devops/installation/tanzu/tanzu-install.html#deploy-the-nginx-ingress-controller) + + + + + ## Windows Development ### Multipass loses control of VMs **Q: What do I do if Multipass cannot access my VMs?** From 1f43a18018cbdc24de18e995e104c16c5a7b01fd Mon Sep 17 00:00:00 2001 From: Lydia Date: Mon, 29 Nov 2021 15:36:27 -0800 Subject: [PATCH 05/10] ENDOC-385 Remove TKG --- vuepress/docs/v6.3.2/docs/reference/local-tips-and-tricks.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/vuepress/docs/v6.3.2/docs/reference/local-tips-and-tricks.md b/vuepress/docs/v6.3.2/docs/reference/local-tips-and-tricks.md index 4a8ff1fe74..9e025254c6 100644 --- a/vuepress/docs/v6.3.2/docs/reference/local-tips-and-tricks.md +++ b/vuepress/docs/v6.3.2/docs/reference/local-tips-and-tricks.md @@ -83,12 +83,11 @@ data: kind: ConfigMap ``` -Refer to the NGINX troubleshooting sections from each of the cloud install guides (EKS, AKS, GKE, TKG) for more information: +Refer to the NGINX troubleshooting sections from each of the cloud install guides (EKS, AKS, GKE) for more information: * [Amazon Elastic Kubernetes Service (EKS)](../../tutorials/devops/installation/elastic-kubernetes-service/eks-install.html#appendix-a-troubleshooting) * [Azure Kubernetes Service (AKS)](../../tutorials/devops/installation/azure-kubernetes-service/azure-install.html#deploy-nginx-ingress-controller) * [Google Kubernetes Engine (GKE)](../../tutorials/devops/installation/google-cloud-platform/gke-install.html#cluster-setup) -* [Tanzu Kubernetes Grid (TKG)](../../tutorials/devops/installation/tanzu/tanzu-install.html#deploy-the-nginx-ingress-controller) From b9218057cc8d5d7ba9cf99c20d54c5980836babe Mon Sep 17 00:00:00 2001 From: Lydia Date: Mon, 29 Nov 2021 15:50:47 -0800 Subject: [PATCH 06/10] ENDOC-385 Install timeout addressed --- .../docs/reference/local-tips-and-tricks.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/vuepress/docs/v6.3.2/docs/reference/local-tips-and-tricks.md b/vuepress/docs/v6.3.2/docs/reference/local-tips-and-tricks.md index 9e025254c6..f4aba44164 100644 --- a/vuepress/docs/v6.3.2/docs/reference/local-tips-and-tricks.md +++ b/vuepress/docs/v6.3.2/docs/reference/local-tips-and-tricks.md @@ -13,7 +13,23 @@ Here are a few common questions about the quickstart environment, which uses Mul **Q: How can I remove a quickstart environment?** **A:** If you want to completely remove the VM created by Multipass, you can use `multipass delete ` (where the default VM-NAME for a quickstart is `entando`) and then `multipass purge` to recover the resources. If you just want to shutdown Entando but keep the VM, you can use `multipass shell ` to shell into the VM and then remove the namespace via `sudo kubectl delete namespace entando`. + +**Q: What if the installation fails due to timeout?** + +**A:** A Docker Hub policy limiting download bandwidth may cause the quickstart installation to fail with timeout errors. The workaround is a two step process: + +1. Delete the `entando` namespace +``` +ent k delete namespace entando +``` + +2. Run the following +``` +ent quickstart "entando" "quickstart" --simple --debug=1 --yes --with-vm --release=v6.3.2 +``` +The namespace will be recreated, preserving the images already pulled, so it's unlikely the installation time will exceed the timeout threshold again. + ### Multipass **Q: How can I shell into a Multipass VM?** From 7859c39036d2ad35710b501bc433657926564293 Mon Sep 17 00:00:00 2001 From: Lydia Date: Tue, 30 Nov 2021 08:58:57 -0800 Subject: [PATCH 07/10] ENDOC-385 All changes -configmap --- .../docs/v6.3.2/docs/reference/local-tips-and-tricks.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/vuepress/docs/v6.3.2/docs/reference/local-tips-and-tricks.md b/vuepress/docs/v6.3.2/docs/reference/local-tips-and-tricks.md index f4aba44164..148526eca0 100644 --- a/vuepress/docs/v6.3.2/docs/reference/local-tips-and-tricks.md +++ b/vuepress/docs/v6.3.2/docs/reference/local-tips-and-tricks.md @@ -50,11 +50,11 @@ The namespace will be recreated, preserving the images already pulled, so it's u ### Entando in Kubernetes **Q: How can I install a new copy of Entando into an existing VM?** -**A:** By default, the quickstart installation deploys Kubernetes resources into a dedicated namespace called `entando`. If you want to remove all of the resources in `entando` you can simply delete the namespace with `sudo kubectl delete namespace entando`. You can then re-create the namespace and re-install the resources by applying the Helm template for your environment. Alternatively, you can achieve this with `ent quickstart --vm-reuse=true`, but you'll need to set other `ent quickstart` options, so check the `ent` help. +**A:** By default, the quickstart installation deploys Kubernetes resources into a dedicated namespace called `entando`. If you want to remove all of the resources in `entando`, you can simply delete the namespace with `sudo kubectl delete namespace entando`. You can then re-create the namespace and re-install the resources by applying the Helm template for your environment. Alternatively, you can achieve this with `ent quickstart --vm-reuse=true`, but you'll need to set other `ent quickstart` options, so check the `ent` help. **Q: How can I shell into a running pod or view its logs?** -**A:** You can use the standard Kubernetes commands, e.g. `sudo kubectl exec -it -c ` +**A:** You can use the standard Kubernetes commands, e.g. `sudo kubectl exec -it -c `. **Q: What do I do if Entando doesn't fully initialize?** @@ -87,9 +87,9 @@ The base domain configured via the ENTANDO_DEFAULT_ROUTING_SUFFIX (e.g. in your ## Customizing NGINX -In some situations the default NGINX ingress configuration doesn't work well for Entando. For instance, JWT tokens can be too large, proxy-buffer-size can be too small, etc. A 502 Bad Gateway error can indicate this config needs to be modified. +In some situations the default NGINX ingress configuration doesn't work well for Entando. For instance, JWT tokens can be too large, proxy-buffer-size can be too small, etc. A 502 Bad Gateway error can indicate that this config needs to be modified. -To configure the NGINX controller globally (for the entire cluster) we just need to edit the default NGINX's configmap, which is ingress-nginx-controller in the ingress-nginx namespace. Add the following inside the data parameter: +To configure the NGINX controller globally (for the entire cluster), we need to edit the default NGINX's configmap, which is ingress-nginx-controller in the ingress-nginx namespace. Add the following inside the data parameter: ``` apiVersion: v1 From 3123065ee2009fcc1f8dbbeac8c6599b85e17e4a Mon Sep 17 00:00:00 2001 From: Lydia Date: Tue, 30 Nov 2021 11:11:43 -0800 Subject: [PATCH 08/10] ENDOC-385 Final changes before apply to Next --- .../v6.3.2/docs/reference/local-tips-and-tricks.md | 10 +++------- .../open-shift/openshift-install-by-operator-hub.md | 4 ++-- .../installation/open-shift/openshift-install.md | 2 +- 3 files changed, 6 insertions(+), 10 deletions(-) diff --git a/vuepress/docs/v6.3.2/docs/reference/local-tips-and-tricks.md b/vuepress/docs/v6.3.2/docs/reference/local-tips-and-tricks.md index 148526eca0..da1e00bafa 100644 --- a/vuepress/docs/v6.3.2/docs/reference/local-tips-and-tricks.md +++ b/vuepress/docs/v6.3.2/docs/reference/local-tips-and-tricks.md @@ -89,7 +89,7 @@ The base domain configured via the ENTANDO_DEFAULT_ROUTING_SUFFIX (e.g. in your In some situations the default NGINX ingress configuration doesn't work well for Entando. For instance, JWT tokens can be too large, proxy-buffer-size can be too small, etc. A 502 Bad Gateway error can indicate that this config needs to be modified. -To configure the NGINX controller globally (for the entire cluster), we need to edit the default NGINX's configmap, which is ingress-nginx-controller in the ingress-nginx namespace. Add the following inside the data parameter: +To configure the NGINX controller globally (for the entire cluster), we need to edit the default NGINX's ConfigMap, which is ingress-nginx-controller in the ingress-nginx namespace. Add the following inside the data parameter: ``` apiVersion: v1 @@ -99,16 +99,12 @@ data: kind: ConfigMap ``` -Refer to the NGINX troubleshooting sections from each of the cloud install guides (EKS, AKS, GKE) for more information: +Refer to the NGINX sections in each of the cloud install guides (EKS, AKS, GKE) for more information: * [Amazon Elastic Kubernetes Service (EKS)](../../tutorials/devops/installation/elastic-kubernetes-service/eks-install.html#appendix-a-troubleshooting) * [Azure Kubernetes Service (AKS)](../../tutorials/devops/installation/azure-kubernetes-service/azure-install.html#deploy-nginx-ingress-controller) * [Google Kubernetes Engine (GKE)](../../tutorials/devops/installation/google-cloud-platform/gke-install.html#cluster-setup) - - - - ## Windows Development ### Multipass loses control of VMs **Q: What do I do if Multipass cannot access my VMs?** @@ -117,7 +113,7 @@ Refer to the NGINX troubleshooting sections from each of the cloud install guide Internet Connection Sharing (ICS) is a Windows service that provides Internet connectivity to virtual machines, and its `hosts.ics` file can occasionally get corrupted. Restarting the host laptop or desktop should remedy this, but a quicker and simpler fix is to shutdown any VMs using the hypervisor (Hyper-V or VirtualBox), remove the `hosts.ics` file from `Windows/System32/drivers/etc` using elevated privileges, and then restart the VM(s). You can examine the `hosts.ics` file first to check if it is well-formed, with clean IP to VM-NAME mappings insteaad of spurious numbers or letters. -### Hyper-V IP Changes +### Hyper-V IP changes **Q: My Entando installation stops working when I restart Windows. How can I fix this?** **A:** The basic issue is that Windows Hyper-V makes it difficult to set a static IP for a VM (see this [forum post](https://techcommunity.microsoft.com/t5/windows-insider-program/hyper-v-default-switch-ip-address-range-change-ver-1809-build/m-p/261431) for details). As discussed [above](#network-issues), Entando's ingress routes rely on a fixed IP address and will break if the IP address changes after initial installation. Here are a few options to solve this issue, short of modifying your router or network switch settings: diff --git a/vuepress/docs/v6.3.2/tutorials/devops/installation/open-shift/openshift-install-by-operator-hub.md b/vuepress/docs/v6.3.2/tutorials/devops/installation/open-shift/openshift-install-by-operator-hub.md index e752e9fa87..0d00312771 100644 --- a/vuepress/docs/v6.3.2/tutorials/devops/installation/open-shift/openshift-install-by-operator-hub.md +++ b/vuepress/docs/v6.3.2/tutorials/devops/installation/open-shift/openshift-install-by-operator-hub.md @@ -8,9 +8,9 @@ The following tutorial shows how to install an Entando application using the Red We have two sets of scenarios listed below: * Scenario 1.1-1.5 for cluster admins who can create projects and operators -* Scenario 2.1 for a user with access to administer a project. +* Scenario 2.1 for users with access to administer projects -Scenario 1.1 is similar to the Entando quickstart style of deployment which can be applied in many environments, including on local developer laptops. The subsequent scenarios (1.2-1.5) build on that initial setup but can be performed independently if desired. Unless otherwise noted, you have the freedom to keep or modify the default options when installing the `Entando Operator` and other resources in the tutorials. +Scenario 1.1 is similar to the Entando quickstart style of deployment and can be applied in many environments, including on local developer laptops. The subsequent scenarios (1.2-1.5) build on this initial configuration and can be performed independently. Unless otherwise noted, you have the freedom to retain or modify the default settings when installing the `Entando Operator` and other resources. ## Prerequisites - A 4.6 (or higher) OpenShift installation diff --git a/vuepress/docs/v6.3.2/tutorials/devops/installation/open-shift/openshift-install.md b/vuepress/docs/v6.3.2/tutorials/devops/installation/open-shift/openshift-install.md index 8224320d6d..a889fde16f 100644 --- a/vuepress/docs/v6.3.2/tutorials/devops/installation/open-shift/openshift-install.md +++ b/vuepress/docs/v6.3.2/tutorials/devops/installation/open-shift/openshift-install.md @@ -5,7 +5,7 @@ sidebarDepth: 2 # Installation on OpenShift ## Overview -This tutorial shows how to manually install Entando into OpenShift 3.11 or 4.x. __If you're working with OpenShift 4.6+ it is highly recommended that you install via the Red Hat-certified Entando Operator which should be available in your OperatorHub__ thanks to the Red Hat Marketplace. See [this tutorial](./openshift-install-by-operator-hub.md) for instructions specific to the `Entando Operator.` +This tutorial shows how to manually install Entando into OpenShift 4.x. __If you're working with OpenShift 4.6+ it is highly recommended that you install via the Red Hat-certified Entando Operator, which should be available in your OperatorHub__ thanks to the Red Hat Marketplace. See [this tutorial](./openshift-install-by-operator-hub.md) for instructions specific to the `Entando Operator.` ## Prerequisites From 69ca5400c4bf162e4de89a77a8d2404f51c288fa Mon Sep 17 00:00:00 2001 From: Lydia Date: Tue, 30 Nov 2021 15:00:24 -0800 Subject: [PATCH 09/10] ENDOC-385 Applied changes to Next --- .../docs/reference/local-tips-and-tricks.md | 155 ++++++++++++------ 1 file changed, 106 insertions(+), 49 deletions(-) diff --git a/vuepress/docs/next/docs/reference/local-tips-and-tricks.md b/vuepress/docs/next/docs/reference/local-tips-and-tricks.md index 19808cbebb..5c47dbb01e 100644 --- a/vuepress/docs/next/docs/reference/local-tips-and-tricks.md +++ b/vuepress/docs/next/docs/reference/local-tips-and-tricks.md @@ -3,74 +3,130 @@ sidebarDepth: 2 redirectFrom: /next/tutorials/devops/local-tips-and-tricks.html --- # Development Tips and Tricks -We've collected a list of tips and tricks for optimizing your local quickstart or [Getting Started](../../docs/getting-started/) development environment. We invite you to ask questions, collaborate with the community, and share your own favorite +We've collected a list of tips and tricks to optimize your local quickstart or [Getting Started](../../docs/getting-started/) development environment. We invite you to ask questions, collaborate with the community, and share your own favorite practices over on the [Entando forum](https://forum.entando.org). ## Quickstart Management -Here are a few common questions about the quickstart environment which uses Multipass to launch an Ubuntu VM, install K3s Kubernetes into it, and then deploy Entando. +Here are a few common questions about the quickstart environment, which uses Multipass to launch an Ubuntu VM, install K3s Kubernetes, and then deploy Entando. ### General -1. **How can I remove a quickstart environment?**. If you want to completely remove the VM created by Multipass then you can use `multipass delete ` (where the default VM-NAME for a quickstart is `entando`) and then `multipass purge` to recover the resources. If you just want to shutdown Entando but keep the VM you can use `multipass shell ` to shell into the VM and then remove the namespace via `sudo kubectl delete namespace entando`. +**Q: How can I remove a quickstart environment?** + +**A:** If you want to completely remove the VM created by Multipass, you can use `multipass delete ` (where the default VM-NAME for a quickstart is `entando`) and then `multipass purge` to recover the resources. If you just want to shutdown Entando but keep the VM, you can use `multipass shell ` to shell into the VM and then remove the namespace via `sudo kubectl delete namespace entando`. + +**Q: What if the installation fails due to timeout?** + +**A:** A Docker Hub policy limiting download bandwidth may cause the quickstart installation to fail with timeout errors. The workaround is a two step process: + +1. Delete the `entando` namespace +``` +ent k delete namespace entando +``` + +2. Run the following +``` +ent quickstart "entando" "quickstart" --simple --debug=1 --yes --with-vm --release=v6.3.2 +``` +The namespace will be recreated, preserving the images already pulled, so it's unlikely the installation time will exceed the timeout threshold again. + ### Multipass -1. **How can I shell into a Multipass VM?** `multipass shell `. If you don't provide a VM-NAME, multipass will use the default name `primary` and even launch it for you if it doesn't exist. -1. **What do I need to do after restarting my laptop?** By default Multipass is installed as a service and will restart automatically. If Multipass isn't running, you'll need to first start the service, and then you can start your VM via `multipass start `. Kubernetes will start automatically along with any installed pods, including Entando. It can take a few minutes for all of the pods to start completely but you can use `sudo kubectl -n entando get pods --watch` to observe the progress. -1. **How can I idle or pause my Entando instance?** You can use either `multipass stop ` or `multipass suspend `, if you'd rather preserve the VM state. You can then use `multipass start ` to start the VM. -1. **What else can Multipass do?** You can run `multipass help` or refer to the [Multipass docs](https://multipass.run/docs) for more information on Multipass. +**Q: How can I shell into a Multipass VM?** + +**A:** `multipass shell `. If you don't provide a VM-NAME, Multipass will use the default name `primary`, and even launch it for you if it doesn't exist. + +**Q: What do I need to do after restarting my laptop?** + +**A:** By default, Multipass is installed as a service and will restart automatically. If Multipass isn't running, you'll need to first initialize this service; then you can start your VM via `multipass start `. Kubernetes will launch automatically along with any installed pods, including Entando. It can take a few minutes for all of the pods to fully initialize, but you can use `sudo kubectl -n entando get pods --watch` to observe the progress. + +**Q: How can I pause or idle my Entando instance?** + +**A:** You can pause with `multipass stop `, or idle with `multipass suspend ` to preserve the VM state. You can then use `multipass start ` to start the VM. + +**Q: What else can Multipass do?** + +**A:** You can run `multipass help` or refer to the [Multipass docs](https://multipass.run/docs) for more information on Multipass. ### Entando in Kubernetes -1. **How can I install a new copy of Entando into an existing VM?** The quickstart deploys Kubernetes resources into a dedicated namespace, `entando` by default. You can simply delete the namespace, `sudo kubectl delete namespace entando`, if you want to delete all of its resources. You can then re-create the namespace and re-install by applying the Helm template for your environment. Alternatively, you can use `ent quickstart --vm-reuse=true` but you'll need to set other `ent quickstart` options so check the `ent` help. -1. **How can I shell into a running pod or view its logs?** You can use the standard Kubernetes commands, e.g. `sudo kubectl exec -it -c ` -1. **What do I if Entando doesn't start completely?** The most common cause for this is a networking problem. See the [Network issues](#network-issues) section below for details. If all else fails reach out to the Entando team on Slack or in the Forums. +**Q: How can I install a new copy of Entando into an existing VM?** + +**A:** By default, the quickstart installation deploys Kubernetes resources into a dedicated namespace called `entando`. If you want to remove all of the resources in `entando`, you can simply delete the namespace with `sudo kubectl delete namespace entando`. You can then re-create the namespace and re-install the resources by applying the Helm template for your environment. Alternatively, you can achieve this with `ent quickstart --vm-reuse=true`, but you'll need to set other `ent quickstart` options, so check the `ent` help. + +**Q: How can I shell into a running pod or view its logs?** + +**A:** You can use the standard Kubernetes commands, e.g. `sudo kubectl exec -it -c `. + +**Q: What do I do if Entando doesn't fully initialize?** + +**A:** The most common cause of this is a networking problem. See the [Network issues](#network-issues) section below for details. If all else fails, reach out to the Entando team on Slack or in the Forums. ## Shared Servers -We've recommended using Multipass as a way to quickly spin up an Ubuntu VM to host a local Kubernetes cluster for test purposes. There are many times when a local environment is useful but most teams utilize a shared Kubernetes cluster managed by an operations team and installed either on premise or with a cloud provider for full integration testing, CI/CD, DevOps, etc. +We recommend using Multipass to quickly spin up an Ubuntu VM to host a local Kubernetes cluster for test purposes. A local environment is often useful, but most teams utilize a shared Kubernetes cluster. This shared cluster is managed by an operations team, and installed either on premise or with a cloud provider for full integration testing, CI/CD, DevOps, etc. ## Network Issues -A local Entando 6.3 quickstart installation (e.g. what you'll get if you follow the [Getting Started](../../docs/getting-started/) guide) may use a set of local domain names to enable accessing Entando services. Your IP address will vary but may look something like this: +A local Entando 7 quickstart installation (e.g. what you'll get if you follow the [Getting Started](../../docs/getting-started/) guide) may use a set of local domain names to enable access to Entando services. Your IP address will vary, but may look something like this: ``` quickstart-entando.192.168.99.1.nip.io quickstart-kc-entando.192.168.99.1.nip.io quickstart-eci-entando.192.168.99.1.nip.io ``` -The base domain configured via the ENTANDO_DEFAULT_ROUTING_SUFFIX (e.g. in your entando.yaml) is based on a fixed IP address and that address is configured during the initial installation. That setting is used to generate ingress routes to map incoming URLs to individual services. In production environments there's generally a dedicated network layer to manage IPs/routing (both on premise and cloud) but those options are often not readily available in a local setup. Here are a couple common issues that can prevent Entando from starting in a local environment: +The base domain configured via the ENTANDO_DEFAULT_ROUTING_SUFFIX (e.g. in your entando.yaml) borrows a fixed IP address that is created during the initial installation. This domain is used to generate ingress routes to map incoming URLs to individual services. In production environments there's generally a dedicated network layer to manage IPs/routing (both on premise and in the cloud), but this is not readily available in most local setups. Below are a couple of common issues that can prevent Entando from initializing in a local environment: ### `.nip.io isn't allowed` - - This could be because of firewall settings or corporate security policies. The simplest workaround is to manually edit your /etc/hosts file and map the necessary domains to the IP of your local virtual machine. + - This could be due to firewall settings or corporate security policies. The simplest workaround is to manually edit your /etc/hosts file and map the necessary domains to the IP of your local virtual machine. ``` 192.168.99.1 quickstart-kc-entando.192.168.99.1.nip.io 192.168.99.1 quickstart-eci-entando.192.168.99.1.nip.io 192.168.99.1 quickstart-entando.192.168.99.1.nip.io ``` - If you add microservices to your installation, you may need to add additional mappings for the new ingresses. -- See [this section below](#option-2-manually-update-your-hosts-file) for detailed steps on Windows. +- See [this section below](#option-2-manually-update-your-hosts-file) for detailed steps to perform this on Windows. ### `The IP address changed after the initial install` -- The workaround noted above (e.g. update your /etc/hosts file) can also be used here. Simply update the IP address in the first column to use the current IP of your virtual machine. -- On Windows this can happen simply because your laptop restarted. See [Windows Hyper-V IP Changes](#hyper-v-ip-changes) below. +- 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. + +## Customizing NGINX + +In some situations the default NGINX ingress configuration doesn't work well for Entando. For instance, JWT tokens can be too large, proxy-buffer-size can be too small, etc. A 502 Bad Gateway error can indicate that this config needs to be modified. + +To configure the NGINX controller globally (for the entire cluster), we need to edit the default NGINX's ConfigMap, which is ingress-nginx-controller in the ingress-nginx namespace. Add the following inside the data parameter: + +``` +apiVersion: v1 +data: + allow-snippet-annotations: "true" + proxy-buffer-size: 24k +kind: ConfigMap +``` + +Refer to the NGINX sections in each of the cloud install guides (EKS, AKS, GKE) for more information: + +* [Amazon Elastic Kubernetes Service (EKS)](../../tutorials/devops/installation/elastic-kubernetes-service/eks-install.html#appendix-a-troubleshooting) +* [Azure Kubernetes Service (AKS)](../../tutorials/devops/installation/azure-kubernetes-service/azure-install.html#deploy-nginx-ingress-controller) +* [Google Kubernetes Engine (GKE)](../../tutorials/devops/installation/google-cloud-platform/gke-install.html#cluster-setup) ## Windows Development ### Multipass loses control of VMs **Q: What do I do if Multipass cannot access my VMs?** -**A:** The most common symptoms include an `IP=UNKNOWN` entry when issuing a `multipass list` and any attempts to stop or shell into the VM will fail. +**A:** The most common symptoms include an `IP=UNKNOWN` entry when issuing a `multipass list`, and when attempts to stop or shell into the VM consistently fail. -Internet Connection Sharing (ICS) is a Windows service that provides Internet connectivity to virtual machines and its `hosts.ics` file can occasionally get corrupted. Restarting the host laptop or desktop should remedy this but a quicker and simpler fix is to shutdown any VMs using the hypervisor (Hyper-V or VirtualBox), remove the `hosts.ics` file from `Windows/System32/drivers/etc` using elevated privileges, and then restart the VM(s). You can examine the `hosts.ics` file first to check if it is well-formed or if it contains spurious numbers or letters rather than clean IP to VM-NAME mappings. +Internet Connection Sharing (ICS) is a Windows service that provides Internet connectivity to virtual machines, and its `hosts.ics` file can occasionally get corrupted. Restarting the host laptop or desktop should remedy this, but a quicker and simpler fix is to shutdown any VMs using the hypervisor (Hyper-V or VirtualBox), remove the `hosts.ics` file from `Windows/System32/drivers/etc` using elevated privileges, and then restart the VM(s). You can examine the `hosts.ics` file first to check if it is well-formed, with clean IP to VM-NAME mappings insteaad of spurious numbers or letters. -### Hyper-V IP Changes +### Hyper-V IP changes **Q: My Entando installation stops working when I restart Windows. How can I fix this?** -**A:** The basic issue is that Windows Hyper-V makes it difficult to set a static IP for a VM. (See this [forum post](https://techcommunity.microsoft.com/t5/windows-insider-program/hyper-v-default-switch-ip-address-range-change-ver-1809-build/m-p/261431) for details.) As discussed [above](#network-issues), Entando's ingress routes rely on an fixed IP address and will break if the IP address changes after initial installation. Here are a few options to solve this issue, short of modifying your router or network switch settings: +**A:** The basic issue is that Windows Hyper-V makes it difficult to set a static IP for a VM (see this [forum post](https://techcommunity.microsoft.com/t5/windows-insider-program/hyper-v-default-switch-ip-address-range-change-ver-1809-build/m-p/261431) for details). As discussed [above](#network-issues), Entando's ingress routes rely on a fixed IP address and will break if the IP address changes after initial installation. Here are a few options to solve this issue, short of modifying your router or network switch settings: #### Option 1: Single host routing -The simplest way to deal with the peculiarities of Hyper-V IP assignments is to avoid it by using the Windows-specific mshome.net addresses. This allows you to access a VM by using an address like `.mshome.net`. If you set up your enviroment using the [Automatic Install](../getting-started/#automatic-install) instructions, then the ent CLI will select the single host option for you and the address will be `entando.mshome.net`. You can accomplish the same thing yourself using the `ent quickstart` script but see its `--help` for the current set of options. +The simplest way to deal with the peculiarities of Hyper-V IP assignment is to avoid it, instead using Windows-specific mshome.net addresses. This allows you to access a VM with an address like `.mshome.net`. If you set up your enviroment using the [Automatic Install](../getting-started/#automatic-install) instructions, then the ent CLI will select the single host option and the address will be `entando.mshome.net`. You can accomplish the same thing yourself using the `ent quickstart` script, but see its `--help` for the current set of options. #### Option 2: Manually update your hosts file The next simplest option to re-enable external access to your cluster is to update your hosts file after each Windows restart. -You need two pieces of information for this workaround and you'll need administrator access to do this. +You need two pieces of information for this workaround, and you'll also need administrator access. -1. Determine the original IP used for your VM. This is included in the `ENTANDO_DEFAULT_ROUTING_SUFFIX` or you can see it included in the ingress names. Run ` kubectl -n entando get ingress` and you should see something like this: +1. Determine the original IP used for your VM. This is included in the `ENTANDO_DEFAULT_ROUTING_SUFFIX`, or you can find it included in the ingress names. Run ` kubectl -n entando get ingress` to see something like this: ```` NAME CLASS HOSTS quickstart-kc-ingress quickstart-kc-entando.192.168.235.100.nip.io @@ -78,14 +134,14 @@ quickstart-eci-ingress quickstart-eci-entando.192.168.235.100.ni quickstart-ingress quickstart-entando.192.168.235.100.nip.io ```` -2. Determine the current IP using `hostname -I` in the VM or by running `multipass list` from Windows: +2. Determine the current IP using `hostname -I` in the VM, or by running `multipass list` from Windows: ``` $ multipass list Name State IPv4 Image primary Running 172.31.118.12 Ubuntu 18.04 LTS ``` -3. As a Windows administrator, edit your hosts file `(C:\Windows\System32\drivers\etc\hosts)` to map any needed URLs from the old IP to the new IP. This will bypass .nip.io lookups. +3. As a Windows administrator, edit your hosts file `(C:\Windows\System32\drivers\etc\hosts)` to map any required URLs from the old IP to the new IP. This will bypass .nip.io lookups. ``` 172.31.118.12 quickstart-kc-entando.192.168.235.100.nip.io @@ -93,16 +149,16 @@ primary Running 172.31.118.12 Ubuntu 18.04 LTS 172.31.118.12 quickstart-entando.192.168.235.100.nip.io ``` -4. You should now be able to access your Entando URLs via the new IP. If your Entando installation stalled during startup, it should continue starting up as soon as the external address is functional again. +4. You should now be able to access your Entando URLs via the new IP. If your Entando installation stalled during startup, it should continue initializing as soon as the external address is functional again. #### Option 3: Add a Windows route -This option is a little more involved the first time but it means repairing your network settings can be done very easily later. In this case you'll pick a static IP, configure a Windows route to map it to the Hyper-V interface, and claim the IP in the Ubuntu VM via a netplan entry. +This option is initially a little more involved, but future repairs to your network settings can then be made very easily. You'll need to choose a static IP, configure a Windows route to map it to the Hyper-V interface, and claim the IP in the Ubuntu VM via a netplan entry. - You'll need to run all of these steps before installing Entando the first time but then just steps #1 and #2 after subsequent Windows restarts. + When implementing this option for the first time, all steps must be executed before installing Entando. Subsequent Windows restarts require steps #1 and #2, only. -1. Determine an IP that is unused on your local network. You can use ping or other tools for this but in the following steps we assume that your selected IP is 192.168.99.1. +1. Determine an IP that is unused on your local network (e.g. via ping). The following steps assume that IP 192.168.99.1 is selected. -2. Determine the interface address to Hyper-V, e.g. 32 below. Use cmd `route print` and look for the Interface entry for Hyper-V: +2. Determine the interface address to Hyper-V (e.g. 32 below). Use cmd `route print` and find the Interface entry for Hyper-V: ``` Interface List 32...00 15 5d 86 45 20 ......Hyper-V Virtual Ethernet Adapter @@ -113,13 +169,13 @@ Interface List route -p add [YOUR-IP] mask 255.255.255.255 0.0.0.0 IF [HYPER-V-INTERFACE] route -p add 192.168.99.1 mask 255.255.255.255 0.0.0.0 IF 32 ``` -4. Verify the route was added by using `route print 192.168.99.1`. This command is useful after restart to check if the route needs to be created again. +4. Verify the route was added via `route print 192.168.99.1`. This command is useful after restart to check if the route needs to be created again. -5. Next, configure your VM to claim the same address. Shell into the VM using `winpty multipass shell [YOUR-VM-NAME]`. +5. Configure your VM to claim the same address. Shell into the VM using `winpty multipass shell [YOUR-VM-NAME]`. 6. Change to the root user to make the following steps simpler: `sudo -i` -7. Determine your network adapter via `ip link`, e.g. eth0. You just need the name. It's often second in the list after the loopback adapter. +7. Determine your network adapter name via `ip link`, e.g. eth0. It's often second in the list after the loopback adapter. ``` bash ubuntu@primary:~$ ip link 1: lo: mtu 65536 qdisc noqueue state UNKNOWN mode DEFAULT group default qlen 1000 @@ -128,9 +184,9 @@ ubuntu@primary:~$ ip link link/ether 00:15:5d:00:1a:0c brd ff:ff:ff:ff:ff:ff ``` -8. `cd /etc/netplan` +8. Navigate to your netplan directory: `cd /etc/netplan` -9. Create a netplan entry starting with 0 so it's loaded first: `vi 0-entando.yaml` +9. Create a netplan entry starting with 0 (so it's indexed and loaded first): `vi 0-entando.yaml` ``` yaml network: @@ -155,19 +211,19 @@ network: - 192.168.99.1/24 ``` -10. Apply the changes via `netplan apply` +10. Apply the changes with `netplan apply` -11. Verify connectivity via `ping 192.168.99.1` from the VM. You should get a response rather than a timeout. +11. From the VM, verify connectivity via `ping 192.168.99.1`. You should receive a response and not a timeout. -12. (Optional) Run a python server to verify you can access the VM from the host at `http://192.168.99.1:8000.` It may take a minute or so before the server is ready. +12. (Optional) Run a Python server to verify you can access the VM from the host at `http://192.168.99.1:8000.` It may take a minute or so before the server is ready. ``` python3 -m http.server 8000 ``` -13. You should now be able to install Entando using the static IP. If your Entando installation stalled during startup and was previously configured using the static IP, it should continue starting up as soon as the external address is functional again. +13. You should now be able to install Entando using the static IP. If your Entando installation stalled during startup, and was previously configured with a static IP, it should continue initializing as soon as the external address is functional again. #### Option 4: Reinstall Entando -We're including this option because it works and requires no additional configuration. If you plan to regularly work with Entando we recommend developing against a centralized and shared Kubernetes instance rather than running a full stack locally. If you need a cluster locally we recommend using option 1 or 2. +We're including this option because it works and requires no additional configuration. If you plan to regularly work with Entando we recommend developing against a centralized and shared Kubernetes instance rather than running a full stack locally. If you require a local cluster we recommend using option 1 or 2. ### JHipster **Q: How can I run JHipster on Windows?** @@ -175,17 +231,18 @@ We're including this option because it works and requires no additional configur **A:** JHipster requires a TTY interface for its menus to function correctly. Here are a few options to satisfy that requirement on Windows: * Run `jhipster` under cmd or Powershell * Using Git Bash, run `winpty jhipster.cmd` -* Use Ubuntu bash via WSL (1 or 2) or within the Multipass VM +* Use Ubuntu bash via WSL (1 or 2), or within the Multipass VM ### Multipass with VirtualBox -Multipass supports the use of VirtualBox on Windows as an alternative to using Hyper-V, say if you're using Windows Home. See the Multipass documentation on how to configure it to work with VirtualBox. +**Q: How do I run Multipass with VirtualBox?** -In order to get Entando working correctly with this setup you will need to add a port forwarding rule so you can access Entando from your host system. -* Create your VM within Multipass. +**A:** Multipass supports the use of VirtualBox on Windows as an alternative to Hyper-V. Refer to the Multipass documentation for VirtualBox configuration instructions. -* Go to the Oracle VM VirtualBox Manager and edit the `Network` settings for the VM. +For Entando to work correctly with VirtualBox you will need to add a port forwarding rule to access Entando from your host system. +* Create your VM within Multipass +* Go to the Oracle VM VirtualBox Manager to edit the `Network` settings for the VM * Go to the `Advanced` options and click `Port Forwarding Rules` -* Add a new rule. +* Add a new rule * `Name`: your choice * `Protocol`: TCP * `Host IP`: leave this blank @@ -193,5 +250,5 @@ In order to get Entando working correctly with this setup you will need to add a * `Guest IP`: leave this blank * `Guest Port`: 80 * Click OK -* At this point any requests to port 80 on your localhost should be forwarded to the VM. -* You can now identify the IP of your host and use that to configure the `ENTANDO_DEFAULT_ROUTING_SUFFIX` in your yaml file, e.g. `192.168.64.25.nip.io`. You should not use the non-routable address (e.g. 10.0.2.15) identified from within the guest VM itself, but rather use the IP of the host. +* Any requests to port 80 on your localhost should be forwarded to the VM. +* Use the IP of your host to configure the `ENTANDO_DEFAULT_ROUTING_SUFFIX` in your YAML file, e.g. `192.168.64.25.nip.io`. You must use the host ID and not the non-routable address identified from within the guest VM, e.g. 10.0.2.15. From e1aa63b9f2fcfd72eb472f9e8c8a776362edad3c Mon Sep 17 00:00:00 2001 From: Lydia Date: Tue, 30 Nov 2021 15:02:44 -0800 Subject: [PATCH 10/10] ENDOC-385 Resolve conflict --- vuepress/docs/next/docs/reference/local-tips-and-tricks.md | 2 +- vuepress/docs/v6.3.2/docs/reference/local-tips-and-tricks.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/vuepress/docs/next/docs/reference/local-tips-and-tricks.md b/vuepress/docs/next/docs/reference/local-tips-and-tricks.md index 5c47dbb01e..cabddf2c48 100644 --- a/vuepress/docs/next/docs/reference/local-tips-and-tricks.md +++ b/vuepress/docs/next/docs/reference/local-tips-and-tricks.md @@ -7,7 +7,7 @@ We've collected a list of tips and tricks to optimize your local quickstart or [ practices over on the [Entando forum](https://forum.entando.org). ## Quickstart Management -Here are a few common questions about the quickstart environment, which uses Multipass to launch an Ubuntu VM, install K3s Kubernetes, and then deploy Entando. +Here are a few common questions about the quickstart environment. The quickstart environment uses Multipass to launch an Ubuntu VM, where K3s Kubernetes is then installed and from which Entando is deployed. ### General **Q: How can I remove a quickstart environment?** diff --git a/vuepress/docs/v6.3.2/docs/reference/local-tips-and-tricks.md b/vuepress/docs/v6.3.2/docs/reference/local-tips-and-tricks.md index da1e00bafa..1272392cc7 100644 --- a/vuepress/docs/v6.3.2/docs/reference/local-tips-and-tricks.md +++ b/vuepress/docs/v6.3.2/docs/reference/local-tips-and-tricks.md @@ -7,7 +7,7 @@ We've collected a list of tips and tricks to optimize your local quickstart or [ practices over on the [Entando forum](https://forum.entando.org). ## Quickstart Management -Here are a few common questions about the quickstart environment, which uses Multipass to launch an Ubuntu VM, install K3s Kubernetes, and then deploy Entando. +Here are a few common questions about the quickstart environment. The quickstart environment uses Multipass to launch an Ubuntu VM, where K3s Kubernetes is then installed and from which Entando is deployed. ### General **Q: How can I remove a quickstart environment?**