Installation FAQ

This document provides answers to common questions and solutions for issues encountered during the installation of API7 Gateway.

Q1: Why is the Control Plane unable to connect to the PostgreSQL database?

A: Ensure the following:

• The database host is reachable from the CP environment.
• The database user has sufficient permissions to create tables.
• Port 5432 is open on the database server.
• Check CP logs for specific error messages, for example: kubectl logs -n <namespace> deploy/<dashboard-deployment-name> --tail=100.

Q2: How do I resolve port conflict errors during installation?

A: If ports such as 7443, 7943, or 9080 are already in use, you can:

• Kubernetes: Change the service port in values.yaml.
• Docker Compose: Update the host-to-container port mapping (e.g., "8443:7443").
• Bare Metal: Update the configuration file to listen on a different port.

Q3: Why is the Data Plane status showing as "Offline" in the Dashboard?

A: This usually indicates a communication issue between the DP and CP.

• Check if the DP can reach the CP address on port 7943.
• Verify that the mTLS certificates are correctly configured and have not expired.
• Ensure the data plane points to the correct CP / DP Manager address (etcd.host on Kubernetes, or the equivalent setting in your Docker Compose or bare-metal configuration).

Q4: I am getting "Permission Denied" when running Helm commands. What should I do?

A: Ensure your Kubernetes context is correctly set and you have administrative privileges for the namespace.

• Run kubectl config current-context to verify your context.
• Use RBAC to grant the necessary permissions to your user account.

Q5: How can I fix image pull errors (ImagePullBackOff)?

A: This error occurs when the Kubernetes node cannot download the container image.

• Check if you have internet access or access to your private registry.
• Verify the image repository and tag in your values.yaml.
• For private registries, ensure the imagePullSecrets are correctly configured.

Q6: My license is invalid. Where can I get a new one?

A: Licenses can be obtained via:

• Trial: Request a trial license.
• Production: Contact your API7 account manager.
• Verification: Check if the license key is correctly copied into your configuration without extra spaces or line breaks.

Q7: Why are CP/DP pods restarting frequently (CrashLoopBackOff)?

A: This is often due to resource limits or misconfiguration.

• Run kubectl describe pod <pod_name> to see the restart reason.
• Check logs for error messages: kubectl logs -n <namespace> <pod_name> --previous.
• Verify that your hardware meets the System Requirements.

Q8: How do I configure mTLS between CP and DP?

A: mTLS between the Control Plane and Data Plane is enabled by default for secure communication.

For details on how certificate issuance, rotation, and verification work, see Mutual TLS between CP and DP.

Q9: Can I deploy API7 without a LoadBalancer in Kubernetes?

A: Yes, you can use NodePort or ClusterIP services.

• NodePort: Access services via <NodeIP>:<NodePort>.
• ClusterIP: Keep the service internal and expose it through an Ingress controller, reverse proxy, or external load balancer.

Q10: How do I check the version of my API7 installation?

A:

• Helm: Run helm list -n <namespace> to see the installed chart and app versions.
• Dashboard: In the Dashboard, open the user menu and select About to see the running version.
• Helm Values: Run helm get values <release-name> -n <namespace> to inspect the values used for a specific installation.
• Images: Run kubectl -n <namespace> get pods -o jsonpath='{.items[*].spec.containers[*].image}' | tr ' ' '\n' | sort -u to list the exact image tags running in the cluster.