This page will give a set of common failing scenarios and how to solve them

Installation errors

Depending on the installer you are using, the format of an installation error could change.

The next feedback provides a <MESSAGE> using Helm

Error: execution error at (api-portal/templates/api-portal-deployment.yaml:<row>:<col>): <MESSAGE>

The next feedback provides a <MESSAGE> using Tanzu

Please consider using 'tanzu package installed update' to update the installed package with correct settings
| 'PackageInstall' resource install status: ReconcileFailed

Error: resource reconciliation failed: ytt: Error:
- assert.fail: fail: <MESSAGE>
    in <toplevel>
      api-portal-deployment.yaml:68 |             #@ assert.fail(<MESSAGE>)
. Reconcile failed: Error (see .status.usefulErrorMessage for details)
Error: exit status 1

The next sections describe a set of common errors.

Missing configuration for API keys

When API keys are enabled using the flag apiKey.enabled=true, the installation will stop immediately and it could show different messages indicating which it is missing. Depending on the tool you are using, the same message will be prompted with different formats

Check the API Keys configuration requirements for more details.

Missing configuration for Single Sing-On (SSO)

Since version 1.1.0

When Single Sign-On (SSO) is enabled, sso.enabled=true, the next error will indicate that you have to provide sso.secretName:

The configuration 'sso.enabled=true' active by default requires non empty value for 'sso.secretName'

The installation will not check if the secret specified in the value sso.secretName exists in the cluster. In that situation, the package installation could be stuck the time specified by --poll-timeout (15 minutes by default) until failing. The logs can be checked for further diagnosis.

Check how to configure SSO for more details.

Geode StatefulSet failing to get healthy

In some clusters with slow startup times, the Geode servers and locators might fail to get to a healthy state within the timeout limit. If you encounter this issue, you can use the following strategies.

  1. Scale down the number of server and locator pods to 1 each using the values.yaml or other methods. Re-run the installation and once the pods are healthy, you can scale up the number of pods to your desired amount.

  2. Edit the locator and server pods to modify the livenessProbe and readinessProbe to increase the timeoutSeconds field to 30 or higher:

    kubectl edit statefulset.apps/geode-locator-api-portal
    kubectl edit statefulset.apps/geode-server-api-portal
    

Tanzu install after failing

When a Package or Package Repository installation fails, the resource will stay for diagnosis purposes. It allows you to find why it failed or re-attempt the process.

Any install command will raise the previous error even if the operator corrected the configuration. To avoid this situation, please, delete the Package or Package Repository and try again using the new configuration.

Example of an after-failing scenario

  1. An operator configures the values file, and it forgets the sso.secretName
cat <<EOF | cat > api-portal-values.yaml
---
apiPortalServer:
namespace: api-portal
sso:
  enabled: true
EOF
  1. An error is raised during the installation
tanzu package install api-portal --namespace tap-install -p api-portal.tanzu.vmware.com -v 1.1.0-alpha.1-111-g81062e5 -f api-portal-values.yaml --wait=true
Error: resource reconciliation failed: ytt: Error:
- assert.fail: fail: The configuration 'sso.enabled=true' active by default requires non empty value for 'sso.secretName'
    in <toplevel>
      api-portal-deployment.yaml:68 |             #@ assert.fail("The configuration 'sso.enabled=true' active by default requires non empty value for 'sso.secretName'")
. Reconcile failed: Error (see .status.usefulErrorMessage for details)
Error: exit status 1

✖  exit status 1
  1. The operator uses the feedback to fix the installation issue ("The configuration 'sso.enabled=true' active by default requires non empty value for 'sso.secretName'") and it tries to install the package again
tanzu package install api-portal --namespace tap-install -p api-portal.tanzu.vmware.com -v 1.1.0-alpha.1-111-g81062e5 -f api-portal-values.yaml --wait=true
Error: resource reconciliation failed: ytt: Error:
- assert.fail: fail: The configuration 'sso.enabled=true' active by default requires non empty value for 'sso.secretName'
    in <toplevel>
      api-portal-deployment.yaml:68 |             #@ assert.fail("The configuration 'sso.enabled=true' active by default requires non empty value for 'sso.secretName'")
. Reconcile failed: Error (see .status.usefulErrorMessage for details)
Error: exit status 1

✖  exit status 1
  1. The operator needs to delete the package first
tanzu package installed delete api-portal -n tap-install -y
  1. The next attempt works fine with the new configuration

Unable to save API keys

If you have API key management enabled, but are unable to save api keys, you might have incorrectly configured the kubernetes vault integration. You can validate this is the issue by looking at the api-portal-server logs using the command below:

k logs deploy/api-portal-server -n api-portal

Look for an error message that contains the text service account name not authorized or invalid role name.

To fix the integration you will first want to find the service account used by the api-portal deployment. One method of determining this is to do a describe on the deployment, like below:

kubectl describe deployment api-portal-server -n api-portal

If the service account is default consider setting it explicitly. You can achieve this by modifying the values used during installation. Below you will find the relevant values to set:

serviceAccount:
  create: true                      # You may set it to false if you'd like to create the service account manually
  name: api-portal-service-account 

Once you have the service account name, go through Step 3 of configure vault instance and use it anywhere it asks for the service account.

check-circle-line exclamation-circle-line close-line
Scroll to top icon