If there is a problem with Keystone, it will not take long for you to notice this. If you attempt to run the stack-list command when Keystone is not working, you will see an error similar to the following one:

Note that, in the error message, the connection URL is for the Keystone service. This is a clear sign that something is wrong with the Keystone endpoint or process. In this situation, you want to make sure that Keystone is up and running correctly. If you need to troubleshoot Keystone, refer to Chapter 2, Troubleshooting OpenStack Identity.

One issue that can be difficult to troubleshoot is incorrect credentials. When you attempt to run heat commands with incorrect credentials, you will see an error similar to the following one:

The server unavailable error may lead you to believe that the heat-api or heat-engine service is unavailable. If you run the command with the --debug argument, you will find more information that is useful when troubleshooting:

heat --debug stack-list

The output of the preceding command will look like what is shown in the following screenshot. When using the --debug switch with the heat command-line tool, debug information will be printed to the console along with the output of the command. This debug information can provide more clues to assist in your troubleshooting. As demonstrated here, you will be able to see information from the API calls made by the heat command-line tool:

As we troubleshoot the preceding error, we can use the techniques discussed earlier in this chapter to make sure that the heat-api and heat-engine services are working as expected. In addition to this, because we know that Heat relies upon many of the other OpenStack services, we should confirm the successful operation of Keystone, Glance, Nova, Neutron, and any other services we may be leveraging in our Heat templates. After you have confirmed the services, you should double-check your Heat configuration.

The 503 Service Unavailable error usually points to the fact that the heat service user you are using is not configured correctly. To confirm the service user for Heat, take a look at the Heat configuration file, typically located at /etc/heat/heat.conf. In that file, under the [keystone_authtoken] stanza, there will be a username and password, as shown in the following screenshot:

Confirm that the username and password set in this configuration file are the same username and password that were set in Keystone. You can confirm this by attempting a Keystone auth token call with that username and password.

The preceding curl command demonstrates how we can use the Keystone API to authenticate the Heat user. In the preceding command, the username is on line 12 and is set to heat. The password for the heat user is set on line 16. It is set to heatpassword in the example.

If the username and password are correct, this call will return successfully with an HTTP 201 response and provide an authtoken in the X-Subject-Token header.

If the password is incorrect, the output from this curl call will be similar to the following output:

This 401 Unauthorized error is a great clue, indicating that there is a problem with the username and password you are using. To resolve this issue, you either need to change the username and password in the /etc/heat/heat.conf under the [keystone_authtoken] stanza or you can update the password in Keystone to match what you have configured in the Heat configuration file. To update the password for the heat user, you can use a command similar to the one given here:

openstack user set --password <newpassword> heat

This command will update the password for the heat user, but it does not return any output upon successful completion. You can confirm that the password has been successfully updated by running the curl command that we discussed in the previous section.