helm/infrastructure/subcharts/kong/FAQs.md

   1 # Frequently Asked Questions (FAQs)
   2
   3 Despite the title, this is more a list of common problems.
   4
   5 #### Kong cannot connect to a fresh Postgres install and fails to start
   6
   7 If Kong is reporting that it cannot connect to Postgres because of an invalid
   8 password on a fresh install, you likely have a leftover PersistentVolume from a
   9 previous install using the same name. You should delete your install, delete
  10 the associated PersistentVolumeClaim, and install again.
  11
  12 Postgres PVCs [are not deleted when the chart install is
  13 deleted](https://docs.bitnami.com/kubernetes/faq/troubleshooting/troubleshooting-helm-chart-issues/#persistence-volumes-pvs-retained-from-previous-releases),
  14 and will be reused by subsequent installs if still present. Since the `kong`
  15 user password is written to disk during database initialization only, that old
  16 user's password is expected, not the new user's.
  17
  18 PVC names use the pattern `data-<release name>-postgresql-<replica index>`. If
  19 you named your install `foo` and did not increase the Postgres replica count,
  20 you will have a single `data-foo-postgresql-0` PVC that needs to be deleted:
  21
  22 ```
  23 kubectl delete pvc data-foo-postgresql-0
  24 ```
  25
  26 If you use a workflow that frequently deletes and re-creates installs, you
  27 should make sure to delete PVCs when you delete the release:
  28
  29 ```
  30 helm delete foo; kubectl delete pvc data-foo-postgresql-0
  31 ```
  32
  33 #### Upgrading a release fails due to missing ServiceAccount
  34
  35 When upgrading a release, some configuration changes result in this error:
  36
  37 ```
  38 Error creating: pods "releasename-kong-pre-upgrade-migrations-" is forbidden: error looking up service account releasename-kong: serviceaccount "releasename-kong" not found
  39 ```
  40
  41 Enabling the ingress controller or PodSecurityPolicy requires that the Kong
  42 chart also create a ServiceAccount. When upgrading from a configuration that
  43 previously had neither of these features enabled, the pre-upgrade-migrations
  44 Job attempts to use this ServiceAccount before it is created. It is [not
  45 possible to easily handle this case automatically](https://github.com/Kong/charts/pull/31).
  46
  47 Users encountering this issue should temporarily modify their
  48 [pre-upgrade-migrations template](https://github.com/Kong/charts/blob/main/charts/kong/templates/migrations-pre-upgrade.yaml),
  49 adding the following at the bottom:
  50
  51 ```
  52 {{ if or .Values.podSecurityPolicy.enabled (and .Values.ingressController.enabled .Values.ingressController.serviceAccount.create) -}}
  53 ---
  54 apiVersion: v1
  55 kind: ServiceAccount
  56 metadata:
  57   name: {{ template "kong.serviceAccountName" . }}
  58   namespace: {{ template "kong.namespace" . }}
  59   annotations:
  60     "helm.sh/hook": pre-upgrade
  61     "helm.sh/hook-delete-policy": before-hook-creation,hook-succeeded
  62   labels:
  63     {{- include "kong.metaLabels" . | nindent 4 }}
  64 {{- end -}}
  65 ```
  66
  67 Upgrading with this in place will create a temporary service account before
  68 creating the actual service account. After this initial upgrade, users must
  69 revert to the original pre-upgrade migrations template, as leaving the
  70 temporary ServiceAccount template in place will [cause permissions issues on
  71 subsequent upgrades](https://github.com/Kong/charts/issues/30).
  72
  73 #### Running "helm upgrade" fails because of old init-migrations Job
  74
  75 When running `helm upgrade`, the upgrade fails and Helm reports an error
  76 similar to the following:
  77
  78 ```
  79 Error: UPGRADE FAILED: cannot patch "RELEASE-NAME-kong-init-migrations" with
  80 kind Job: Job.batch "RELEASE-NAME-kong-init-migrations" is invalid ... field
  81 is immutable
  82 ```
  83
  84 This occurs if a `RELEASE-NAME-kong-init-migrations` Job is left over from a
  85 previous `helm install` or `helm upgrade`. Deleting it with
  86 `kubectl delete job RELEASE-NAME-kong-init-migrations` will allow the upgrade
  87 to proceed. Chart versions greater than 1.5.0 delete the job automatically.
  88
  89 #### DB-backed instances do not start when deployed within a service mesh
  90
  91 Service meshes, such as Istio and Kuma, if deployed in a mode that injects
  92 a sidecar to Kong, don't make the mesh available to `InitContainer`s,
  93 because the sidecar starts _after_ all `InitContainer`s finish.
  94
  95 By default, this chart uses init containers to ensure that the database is
  96 online and has migrations applied before starting Kong. This provides for a
  97 smoother startup, but isn't compatible with service mesh sidecar requirements
  98 if Kong is to access the database through the mesh.
  99
 100 Setting `waitImage.enabled=false` in values.yaml disables these init containers
 101 and resolves this issue. However, during the initial install, your Kong
 102 Deployment will enter the CrashLoopBackOff state while waiting for migrations
 103 to complete. It will eventually exit this state and enter Running as long as
 104 there are no issues finishing migrations, usually within 2 minutes.
 105
 106 If your Deployment is stuck in CrashLoopBackoff for longer, check the init
 107 migrations Job logs to see if it is unable to connect to the database or unable
 108 to complete migrations for some other reason. Resolve any issues you find,
 109 delete the release, and attempt to install again.
 110
 111 #### Kong fails to start after `helm upgrade` when Postgres is used
 112
 113 As of Kong chart 2.8, this issue is no longer present. 2.8 updates the Postgres
 114 sub-chart to a version that checks for existing password Secrets and leaves
 115 them as-is rather than overwriting them.
 116
 117 You may be running into this issue: https://github.com/helm/charts/issues/12575.
 118 This issue is caused due to: https://github.com/helm/helm/issues/3053.
 119
 120 The problem that happens is that Postgres database has the old password but
 121 the new secret has a different password, which is used by Kong, and password
 122 based authentication fails.
 123
 124 The solution to the problem is to specify a password to the `postgresql` chart.
 125 This is to ensure that the password is not generated randomly but is set to
 126 the same one that is user-provided on each upgrade.
 127
 128 The Postgres chart provides [two options](https://github.com/bitnami/charts/tree/master/bitnami/postgresql#postgresql-common-parameters)
 129 for setting a password:
 130
 131 - `auth.password` sets a password directly in values.yaml, in cleartext. This
 132   is fine if you are using the instance for testing and have no security
 133   concerns.
 134 - `auth.existingSecret` specifies a Secret that contains [specific keys](https://github.com/bitnami/charts/blob/a6146a1ed392c8683c30b21e3fef905d86b0d2d6/bitnami/postgresql/values.yaml#L134-L143).
 135   This should be used if you need to properly secure the Postgres instance.
 136
 137 If you have already upgraded, the old password is lost. You will need to
 138 delete the Helm release and the Postgres PersistentVolumeClaim before
 139 re-installing with a non-random password.